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
$524.94
Apple Inc.
+5.93
MSFT
$40.01
Microsoft Corpora
-0.39
GOOG
$536.10
Google Inc.
-20.44

MacTech Search:
Community Search:

Software Updates via MacUpdate

Mac DVDRipper Pro 4.1.7 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
PDFpenPro 6.2 - Advanced PDF toolkit for...
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Create... Read more
PDFpen 6.2 - Edit and annotate PDFs with...
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
Monolingual 1.5.9 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. It requires a 64-bit capable Intel-based Mac and at least... Read more
Maya 2015 - Professional 3D modeling and...
Maya is an award-winning software and powerful, integrated 3D modeling, animation, visual effects, and rendering solution. Because Maya is based on an open architecture, all your work can be scripted... Read more
Starcraft II: Wings of Liberty 1.1.1.180...
Download the patch by launching the Starcraft II game and downloading it through the Battle.net connection within the app. Starcraft II: Wings of Liberty is a strategy game played in real-time. You... Read more
Sibelius 7.5.0 - Music notation solution...
Sibelius is the world's best-selling music notation software for Mac. It is as intuitive to use as a pen, yet so powerful that it does most things in less than the blink of an eye. The demo includes... Read more
Typinator 5.9 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
MYStuff Pro 2.0.16 - Create inventories...
MYStuff Pro is the most flexible way to create detail-rich inventories for your home or small business. Add items to MYStuff by dragging and dropping existing information, uploading new images, or... Read more
TurboTax 2013.r17.002 - Manage your 2013...
TurboTax guides you through your tax return step by step, does all the calculations, and checks your return for errors and overlooked deductions. It lets you file your return electronically to get... Read more

Latest Forum Discussions

See All

Living Planet - Tiny Planet Videos and P...
Living Planet - Tiny Planet Videos and Photos 1.0 Device: iOS Universal Category: Photography Price: $.99, Version: 1.0 (iTunes) Description: 50% OFF LAUNCH SPECIAL! BUY NOW BEFORE THE PRICE GOES UP... | Read more »
Livescribe 3 Smartpen Review
Made by: Livescribe Price: $149.99 for Livescribe 3 Hardware/iOS Integration Rating: 4.5 out of 5 stars Usability Rating: 4 out of 5 stars Reuse Value Rating: 4.75 out of 5 stars Build Quality Rating: 4.5 out of 5 stars Overall Rating: 4.44 out of... | Read more »
Unpossible Review
Unpossible Review By Carter Dotson on April 17th, 2014 Our Rating: :: RALPH WIGGUM APPROVESUniversal App - Designed for iPhone and iPad Unpossible is much better than its English!   | Read more »
Hitman GO Review
Hitman GO Review By Carter Dotson on April 17th, 2014 Our Rating: :: GO HITMAN, GO!Universal App - Designed for iPhone and iPad Hitman GO is not the obvious way to do a mobile version of the Hitman series, but it’s an incredibly... | Read more »
Monster High Ghouls and Jewels is a Frea...
Monster High Ghouls and Jewels is a Freaky Fashion-Forward Match-3 Puzzler Posted by Rob Rich on April 17th, 2014 [ permalink ] | Read more »
Dinosaur Train A to Z Review
Dinosaur Train A to Z Review By Amy Solomon on April 17th, 2014 Our Rating: :: DINO DETAILSUniversal App - Designed for iPhone and iPad Dinosaur Train A to Z is an educational app about dinosaurs that includes In-App Purchases... | Read more »
Easter Comes to Junk Jack X – Bringing N...
Easter Comes to Junk Jack X – Bringing New Crafts, Chemistry, and More Posted by Rob Rich on April 17th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Call of Cookie Review
Call of Cookie Review By Jordan Minor on April 17th, 2014 Our Rating: :: COOKIE CRUMBLESUniversal App - Designed for iPhone and iPad Call of Cookie proves that plants aren’t the only fighting foods out there.   | Read more »
Corel Launches Video Editing App Pinnacl...
Corel Launches Video Editing App Pinnacle Studio for iPhone, Updates iPad Version for iOS 7 Posted by Tre Lawrence on April 17th, 2014 [ | Read more »
Bad Vamp Review
Bad Vamp Review By Jennifer Allen on April 17th, 2014 Our Rating: :: BASIC VAMPIRIC ADVENTURESUniversal App - Designed for iPhone and iPad Run or destroy the vampires in this simple, single-screen game that lacks real bite.   | Read more »

Price Scanner via MacPrices.net

Apple restocks refurbished Mac minis starting...
The Apple Store has restocked Apple Certified Refurbished Mac minis for up to $150 off the cost of new models. Apple’s one-year warranty is included with each mini, and shipping is free: - 2.5GHz Mac... Read more
Hyundai Brings Apple CarPlay To The 2015 Sona...
Hyundai Motor America has announced it will bring Apple CarPlay functionality to the 2015 Sonata. CarPlay is pitched as a smarter, safer and easier way to use iPhone in the car and gives iPhone users... Read more
Updated iPads Coming Sooner Than We Had Thoug...
MacRumors, cites KGI securities analyst Ming Chi Kuo, well-respected as an Apple product prognisticator, saying that Apple will introduce an upgraded iPad Air and iPad mini in 2014/Q3, meaning the... Read more
Toshiba Unveils New High And Low End Laptop M...
Toshiba has announced new laptop models covering both the high-end and low-end of the notebook computer spectrum. Toshiba 4K Ultra HD Laptop Toshiba’s new Satellite P55t features one of the world’s... Read more
Save up to $270 with Apple refurbished 13-inc...
The Apple Store has Apple Certified Refurbished October 2013 13″ Retina MacBook Pros available starting at $1099, with models up to $270 off MSRP. Apple’s one-year warranty is standard, and shipping... Read more
Apple now offering refurbished iPad mini with...
The Apple Store has Certified Refurbished 2nd generation iPad minis with Retina Displays now available starting at $339. Apple’s one-year warranty is included with each model, and shipping is free.... Read more
Microsoft Blinks – Drops Microsoft Office 365...
Microsoft has dropped the annual subscription fee for Microsoft Office 365 Personal – which is needed in order to create and edit documents in Microsoft Office for iPad. However, Apple’s iOS and OS X... Read more
New AVG Vault Apps for iOS and Android Help K...
AVG Technologies N.V. an online security company for 177 million active users, has announced the launch of its latest mobile application, AVG Vault. The free app introduces an innovative user... Read more
Free Local Carrot iPhone App Helps Find Fresh...
I love fresh vegetables. I’m not a vegan, although I was for several years in the 1980s, but fresh vegetables and other whole foods are still my dietary mainstays as a matter of taste rather than... Read more
CarSO Pro – Car Service and Finance Manager/O...
Lviv, Ukraine-based BM-Studios’ CarSO Pro is a tool to manage operations concerning your car. Never forget to change the oil or prolong the insurance for your car. Remember when you’ve done the car... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**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
*Apple* Retail - Manager - Holyoke - Apple I...
Job Summary Keeping an Apple Store thriving requires a diverse set of leadership skills, and as a Manager, you’re a master of them all. In the store’s fast-paced, Read more
*Apple* Retail - Manager - Apple (United Sta...
Job SummaryKeeping an Apple Store thriving requires a diverse set of leadership skills, and as a Manager, you're a master of them all. In the store's fast-paced, dynamic Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**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
*Apple* Retail - Market Leader - Cincinnati...
…challenges of developing individuals, building teams, and affecting growth across Apple Stores. You demonstrate successful leadership ability - focusing on excellence Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.