TweetFollow Us on Twitter

PictPack
Volume Number:9
Issue Number:5
Column Tag:4th Dimension

Related Info: Picture Utilities

PictPack - A Package of 4D Externals

Managing picture variables in 4D Externals

By Kent Miller, Arlington, Texas

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

About the author

Kent Miller is the author of 4D Balloon Help and 4D Chooser, both published by Business Network of Oklahoma City. His Email addresses are KPMiller@aol.com or KPMILLER on America Online.

In this article, I will develop a small 4D package that reads PICT files into picture variables, writes picture variables to PICT files, and returns information about 4D picture variables. I will also attempt to illustrate three things:

• How to read and write a PICT file

• How to free up extra memory for your 4D external

• Using a 4D EntryPoint to put a PicHandle into a picture variable

PicHandles and PICT files contain the exact same information except a PICT file has 512 bytes of information at the beginning (to hold information such as the name of the creating program and copyright information). So, if you want to read a PICT, you simply skip the first 512 bytes of the file and then read the rest into a PicHandle. To write one, you just write 512 bytes of something and then write a PicHandle.

The ReadPict Procedure

The ReadPict external takes two parameters, the name of the picture variable to put the picture in and an integer that returns an error. The procedure prompts the user to select a file. When a file is chosen, it reads the picture if it can free up enough memory.

After a 4D database is used for a while, memory gets pretty full and you will probably need to free up some space before reading the picture. I was under the impression that a call to NewHandle made every effort to free up a block of memory, but it seems like I can get a bigger handle more reliably (at least in a 4D external) by calling CompactMem with the amount of memory I want before making the NewHandle call.

A picture field in 4D is made up of two things, a PicHandle and a 6-byte PicEnd record that 4D uses to determine where and how to draw the picture. The PicEnd record is defined like this:

{1}

 PicEnd = record
 origin : Point;
 transferMode : integer;
 end;

The PicEnd record goes (strangely enough) at the end of the picture. Since we had the foresight when we allocated memory to allocate enough for the PicHandle plus the PicEnd, we can just use BlockMove and some fancy pointer arithmetic to put the record at the end of the PicHandle.

{2}

with myPicEnd do
 begin
 origin.h := 0;
 origin.v := 0;
 transfer := srcCopy;
 end;
BlockMove(@myPicEnd, Ptr(ord(thePic^) + 
 GetHandleSize(thePic) - 6), 6);

We use a 4D EntryPoint routine to put the picture back into 4D. 4D has some really convoluted variant record structures it uses to pass information to and from externals. We need two of these structures to put the picture into 4D-the VarRec contains the information we want to send to 4D and the ParmBlock is used whenever you need to make a 4D EntryPoint call.

We fill the VarRec like this:

{3}

       myVarRec.varKind := PICT;
       myVarRec.picSize := GetHandleSize(thePic);
       myVarRec.PP := PicHandle(thePic);

and we fill the ParmBlock like this:

{4}

       Blk4D.Name := PtrList^[1].S^;
       Blk4D.HH := @myVarRec;
       Blk4D.ClearOldVariable := true;

and call the EntryPoint:

{5}

       Call4D(EX_PUT_VARIABLE, Blk4D);

There are 2 reasons I call 4D to put the information into the variable instead of just directly passing a picture variable. In a database that is compiled with 4D Compiler, 4D doesn’t pre-initalize variables it passes you. So, there really isn’t anyway to tell if a variable is valid or not unless you leave the responsibility of initialization to the 4D developer. This isn’t a big deal if it is an integer or longint, but if you think it is a valid PicHandle and try to dispose it, bad things can happen. If you don’t dispose it, you take the chance of the memory becoming lost in the heap. The second reason is assuming the handle is valid, I never can decide what to do with the handle 4D passes. Should I dispose it? What if 4D has another copy of it somewhere? This method eliminates that confusion and I recommend that anytime you need to pass a picture (or text) variable back to 4D you use the EntryPoint routines.

The only other thing of note in this procedure is that once you give 4D the PicHandle, don’t dispose it. After you make the EntryPoint call, 4D becomes responsible for managing the PicHandle. Sample 4D code to call ReadPict is shown in Figure 1.

Figure 1 - Sample 4D Code calling ReadPict

The SavePict Procedure

There are three parameters to the SavePict procedure, the picture variable to save, the creator type for the file, and a place to return an error. I can pass a picture variable this time since I am just going to use it, not replace it. First, I call GetHandleSize to see if the PicHandle from 4D looks valid. If it does, the procedure uses StandardPutFile to get a path for the file. Next, it opens the file and writes 512 bytes of zeros. Then it determines how many bytes of the PicHandle to write by calling GetHandleSize and subtracting 6 bytes for the PicEnd record. Finally, it writes those bytes to the file.

{6}

       count := GetHandleSize(Handle(pic)) - 6;
       err := FSWrite(newFileRefNum, count, Ptr(pic^));

Sample 4D code to call the SavePict procedure is given in Figure 2.

Figure 2 - Sample 4D Code calling SavePict

The ReturnPictInfo Procedure

I have also written a small procedure to get information about pictures for the sake of completeness. I use the System 7 call GetPictInfo to return information about picture fields. Any information could be returned from the package, but I just picked what I think would be the most useful to the user. The parameters to this procedure are the picture variable, 3 integers for the length, width, and depth (number of bits-per-pixel) of the picture, and 2 longints for the size in bytes and number of colors in the picture. Figure 3 shows 4D code to call this procedure.

Figure 3 - Sample 4D Code calling ReturnPictInfo

Loose Ends

All the record definitions and constants I use in the package that aren’t standard Macintosh structures are defined in the Access0 library that is included in the 4D External Kit.

These procedures are lumped into a package, but I suppose that they could’ve just as easily be broken up into separate externals. Being in a package just makes it easier to move them in and out of a database. They can also be grouped together into a popup menu in the 4D design environment using ‘FON#’ and ‘THM#‘ resources. If you have 4D 3.0, you can create these resources with the new 4D External Mover that comes with it. Otherwise those resource templates are included in the 4D External Kit.

This package, like every 4D package, will require 2 resources to be recognized by 4D. The ‘4BNX’ resource groups your package with other resources needed by your package. In our case, the only resource we need besides the ‘4DPX’ (the package itself) is the ‘STR#’ resource that lists the procedures in our package with their parameters. You can create these resources in ResEdit using the templates that come with the 4D External Kit. The ‘4BNX’ and ‘STR#’ resources are included with the source listing in Rez format.

I have used the System 7 file system calls and used the System 7 Picture Utilities Package, so making the package run in System 6 is left as an exercise for the reader.

Think Pascal Project

Figure 4 - The Think Pascal project window

{7}
Source Code
unit PictPack;

interface

 uses
  SANE, Access0, Palettes, PictUtil;

 procedure main (ProcNum: Longint; 
 PtrList: PackageVariablesPtr; var Data: handle; 
 var FuncPtr: PackRetParam);

implementation

 procedure readPict (var thePic: Handle; 
 var theerr: integer);
 FORWARD;

 procedure savePict (var pic: PicHandle; 
 var creator: str255; var err: integer);
 FORWARD;

 procedure ReturnPictInfo (var thePictHandle: PicHandle; 
 var length, width, depth: integer; 
 var colors, size: longint);
 FORWARD;

 procedure main (ProcNum: Longint; 
 PtrList: PackageVariablesPtr; var Data: handle; 
 var FuncPtr: PackRetParam);

  var
   thePic: Handle;
   Blk4D: ParmBlock;
   staticResNum: integer;
   theerr: OSErr;
   myVarRec: VarRec;

 begin
  case ProcNum of
   -1: 
    begin { Init - I’m not allocating any memory}
    end;

   -2: 
    begin { deInit }
    end;

   1: {read a Pict}
    begin
     PtrList^[2].I^ := noErr;
     thePic := nil;
     ReadPict(thePic, PtrList^[2].I^);
     if PtrList^[2].I^ = noErr then  
      begin
       myVarRec.varKind := PICT;
       myVarRec.picSize := GetHandleSize(thePic);
       myVarRec.PP := PicHandle(thePic);
       Blk4D.Name := PtrList^[1].S^;
       Blk4D.HH := @myVarRec;
       Blk4D.ClearOldVariable := true;
       Call4D(EX_PUT_VARIABLE, Blk4D);
       PtrList^[2].I^ := Blk4D.error;
      end;
    end;

   2: {save a Pict}
    begin
     if GetHandleSize(handle(PtrList^[1].P^)) <= 0 then
      PtrList^[4].I^ := -1
     else
      SavePict(PtrList^[1].P^, PtrList^[2].S^, 
 PtrList^[3].I^);
    end;

   3: 
    ReturnPictInfo(PtrList^[1].P^, PtrList^[2].I^, 
 PtrList^[3].I^, PtrList^[4].I^, PtrList^[5].L^, 
 PtrList^[6].L^);
  end;  {case ProcNum}
 end;

 procedure readPict (var thePic: Handle; 
 var theErr: integer);

  var
   reply: StandardFileReply;
   theTypeList: SFTypeList;
   thePicFile: integer;
   bytes, t: longint;
   myPicEnd: PicEnd;
   err: integer;

 begin
  theTypeList[0] := ‘PICT’;
  StandardGetFile(nil, 1, theTypeList, reply);
  if not (reply.sfGood) then
   theErr := -1
  else
   begin
    theErr := FSPOpenDF(reply.sfFile, fsCurPerm, 
 thePicFile);
    if theErr = noErr then
     begin
      theErr := GetEOF(thePicFile, bytes);
      bytes := bytes - 512;
      {need to leave 6 bytes for 4D’s PicEnd}
      t := compactMem(bytes + 6);
      thePic := NewHandle(bytes + 6);
      if thePic = nil then
       theErr := memError
      else
       begin
        Hlock(thePic);
        theErr := SetFPos(thePicFile, 1, 512);
        theErr := FSRead(thePicFile, bytes, thePic^);
        with myPicEnd do  {put on the 4D picEnd record}
         begin
          origin.h := 0;
          origin.v := 0;
            transfer := srcCopy;
         end;
        BlockMove(@myPicEnd, Ptr(ord(thePic^) + 
 GetHandleSize(thePic) - 6), 6);
        HUnLock(thePic);
       end;
      err := FSClose(thePicFile);
     end;
   end;
 end;

 procedure savePict (var pic: PicHandle; 
 var creator: str255; var err: integer);

  var
   theErr: OSErr;
   p: PTR;
   newFileRefNum: integer;
   picSize: longint;
   c: OSType;
   count: longint;
   reply: StandardFileReply;
 
begin
  if pic <> nil then
   begin
    StandardPutFile(‘Save a PICT file ’, 
 ‘PICT from 4D’, reply);
    if (reply.sfGood) then
     begin
      {If the file already exists, replace it}
      theErr := FSpDelete(reply.sfFile); 
      if length(creator) = 4 then
       begin
        BlockMove(@creator[1], @c, 4);
        err := FSpCreate(reply.sfFile, c, 
 ‘PICT’, reply.sfScript);
       end
      else
       err := FSpCreate(reply.sfFile, ‘SPNT’, 
 ‘PICT’, reply.sfScript);
      if err = noErr then
       begin
        err := FSpOpenDF(reply.sfFile, 
 fsRdWrPerm, newFileRefNum);
        if err = noErr then
         begin
          p := NewPtrClear(512);
          if p = nil then
           err := MemError
          else
           begin
            count := 512;
            err := FSWrite(newFileRefNum, count, p);
            if err = noErr then
             begin
              {Take off 6 bytes for the picEnd}
              count := GetHandleSize(Handle(pic)) - 6; 
              err := FSWrite(newFileRefNum, count, 
 ptr(ord(pic^)));
             end;
            DisposPtr(p);
           end;
          err := FSClose(newFileRefNum);
         end;
       end; {NoErr on FSpCreate}
     end;
   end;
 end;

 procedure ReturnPictInfo (var thePictHandle: PicHandle; 
 var length, width, depth: integer; 
 var colors, size: longint);

  var
   thePictInfo: PictInfo;
   saveHandleState: integer;
   theErr: OSErr;

 begin
  saveHandleState := HGetState(Handle(thePictHandle));     
  {save the original state}

  {GetPictInfo can move memory}
  HLock(Handle(thePictHandle));  
  theErr := GetPictInfo(thePictHandle, thePictInfo, 
 returnColorTable, 1, systemMethod, 0);

  if theErr = noErr then
   begin
    if thePictInfo.theColorTable <> nil then
     DisposHandle(Handle(thePictInfo.theColorTable));
    width := thePictInfo.sourceRect.right - 
 thePictInfo.sourceRect.left;
    length := thePictInfo.sourceRect.bottom - 
 thePictInfo.sourceRect.top;
    depth := thePictInfo.depth;
    colors := thePictInfo.uniqueColors;
    size := GetHandleSize(handle(thePictHandle));
  end;
  HSetState(Handle(thePictHandle), saveHandleState);
 end;

end.
Other Resources DeRez-ed

resource ‘4BNX’ (128) {
 { /* array 4BNXArray: 1 elements */
 /* [1] */
 ‘STR#’,/*Type */
 128,   /*Local ID*/
 128    /*Global ID*/
 }
};

resource ‘STR#’ (128) {
 { /* array StringArray: 3 elements */
 /* [1] */
 “ReadPict(&S;&I)”,
 /* [2] */
 “SavePict(&P;&S;&I)”,
 /* [3] */
 “ReturnPictInfo(&P;&I;&I;&I;&L;&L)”
 }
};

 
AAPL
$101.20
Apple Inc.
+0.62
MSFT
$45.20
Microsoft Corpora
-0.02
GOOG
$583.54
Google Inc.
+0.17

MacTech Search:
Community Search:

Software Updates via MacUpdate

calibre 2.0.0 - Complete e-library manag...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more
Apple iMovie 10.0.5 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more
Apple Keynote 6.2.2 - Apple's prese...
Apple Keynote makes it simple to create and deliver beautiful presentations. Powerful tools and dazzling effects bring your ideas to life. You can work seamlessly between Mac and iOS devices. And... Read more
Apple Numbers 3.2.2 - Apple's sprea...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
OpenOffice 4.1.1 - Free and open-source...
OpenOffice.org is both an Open Source product and a project. The product is a multi-platform office productivity suite. It includes the key desktop applications, such as a word processor,... Read more
Pages 5.2.2 - Apple's word processo...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices. And... Read more
Quicken 2015 2.0.1 - Complete personal f...
The new Quicken 2015 helps you manage all your personal finances in one place, so you can see where you're spending and where you can save. Quicken automatically categorizes your financial... Read more
CleanMyMac 2.2.7 - Delete files that was...
CleanMyMac makes space for the things you love. Sporting a range of ingenious new features, CleanMyMac 2 lets you safely and intelligently scan and clean your entire system, delete large, unused... Read more
MacFamilyTree 7.2.4 - Create and explore...
MacFamilyTree gives genealogy a facelift: it's modern, interactive, incredibly fast, and easy to use. We're convinced that generations of chroniclers would have loved to trade in their genealogy... Read more
Videobox 4.1.1 - Download Flash video th...
Videobox allows you to quickly and easily download Flash video from most all of the popular video sites on the internet. Videobox will convert the video into a native Quicktime format so it's ready... Read more

Latest Forum Discussions

See All

Trolls vs Vikings Update Adds Over One H...
Trolls vs Vikings Update Adds Over One Hundred Levels, Reduces Item Cost, and More Posted by Ellis Spice on August 22nd, 2014 [ permalink ] | Read more »
SNK Celebrates the 20th Anniversary of T...
SNK Celebrates the 20th Anniversary of The King of Fighters With a Big Sale Posted by Ellis Spice on August 22nd, 2014 [ permalink ] | Read more »
It Came From Canada: Star Wars: Commande...
With a brand new Star Wars trilogy on the horizon, prepare yourselves for Disney and George Lucas’s space fantasy throwback to be more omnipresent than ever before. So it should come as no surprise that new adventures in that galaxy far, far away... | Read more »
Swing Copters Review
Swing Copters Review By Jordan Minor on August 22nd, 2014 Our Rating: :: DIE TRYINGUniversal App - Designed for iPhone and iPad The creator of Flappy Bird is back with a vengeance.   | Read more »
The Outcast Review
The Outcast Review By Nadia Oxford on August 22nd, 2014 Our Rating: :: HANDS OFF. WAY OFF.Universal App - Designed for iPhone and iPad It’s easy to see what The Outcast is trying for, but its execution needs a lot of work.   | Read more »
Brain+ Review
Brain+ Review By Nadia Oxford on August 22nd, 2014 Our Rating: :: DIM BULBUniversal App - Designed for iPhone and iPad Brain+ is just another entry in an over-saturated brain-training marketplace – and not a particularly fun entry... | Read more »
The Witcher Battle Arena – New Gameplay...
The Witcher Battle Arena – New Gameplay Trailer Revealed Posted by Jessica Fisher on August 22nd, 2014 [ permalink ] Based in the Witcher universe, | Read more »
Max Gentlemen Review
Max Gentlemen Review By Jennifer Allen on August 22nd, 2014 Our Rating: :: OUTSTAYING ITS WELCOMEiPhone App - Designed for the iPhone, compatible with the iPad Max Gentlemen seems pretty quirky initially but that appeal wears thin... | Read more »
Club Penguin Gets Frozen All Over in Lat...
Club Penguin Gets Frozen All Over in Latest Takeover Event Posted by Ellis Spice on August 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Doctor Who: Legacy Review
Doctor Who: Legacy Review By Jennifer Allen on August 22nd, 2014 Our Rating: :: RUN OF THE MILLUniversal App - Designed for iPhone and iPad Doctor Who: Legacy is an ok match-3 puzzle game, but it lacks some much needed personality... | Read more »

Price Scanner via MacPrices.net

Leftover 15-inch 2.0GHz Retina MacBook Pros a...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Pro.Calendar – New Productivity App for iPad...
Austin, Texas based mobile business and productivity app developer LightArrow, Inc. has announced Pro.Calendar, a powerful and intuitive calendar app with eight versatile calendar options including... Read more
SanDisk Ultra II SSD — Supercharge Your Syste...
SanDisk Corporation has announced the new SanDisk Ultra II SSD with enhanced SSD Dashboard. The new drive is designed to deliver a cost-effective and easy upgrade solution for PC owners looking to... Read more
Samsung and Barnes & Noble Introduce New...
Samsung Electronics America and NOOK Media, a subsidiary of Barnes & Noble, Inc. have announced the introduction of the new Samsung Galaxy Tab 4 NOOK, a 7-inch tablet combining Samsung’s leading... Read more
21-inch iMacs on sale for up to $150 off MSRP
B&H Photo has 21″ iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only. B&H will also include a free copy of Parallels Desktop software: - 21″ 2.7GHz iMac: $... Read more
27-inch 3.2GHz iMac on sale for $1698, save $...
Abt has the 27″ 3.2GHz iMac on sale for $1698 including free shipping. Their price is $101 off MSRP. Read more
Mac Backup Guru 2.0 Drive Backup/Cloneing Uti...
Mac Backup Guru developer MacDaddy has released Mac Backup Guru 2.0, offering new and enhanced advanced features, such as bootable backups, synchronised volumes and folders, and a Snapshot mode that... Read more
Operate GE’s New Free-Standing KItchen Range...
Think you accidentally left the oven on? Switch it off while on the go. The new free-standing Profile™ Series gas and electric ranges are GE’s second cooking appliances, following their wall oven, to... Read more
Parallels Announces Parallels Desktop 10 for...
The no. 1-selling software for running Windows applications on a Mac becomes an even easier choice for millions of consumers and IT professionals worldwide with the launch of the most powerful... Read more
Apple now offering certified refurbished 2014...
 The Apple Store is now offering Apple Certified Refurbished 2014 MacBook Airs for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As more and more people discover Apple , they visit our stores seeking ways to incorporate our products into their lives. It's your job, as a Store Read more
Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Solutions Consultant (ASC)- Retail S...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.