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)”
 }
};

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Things 3.1.1 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
GraphicConverter 10.4.3 - $39.95
GraphicConverter is an all-purpose image-editing program that can import 200 different graphic-based formats, edit the image, and export it to any of 80 available file formats. The high-end editing... Read more
Google Chrome 60.0.3112.78 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
PDFpenPro 9.1 - 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. Create fillable forms and tables of content... Read more
PDFpen 9.1 - $74.95
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
DiskCatalogMaker 7.1.3 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Amadeus Pro 2.4 - Multitrack sound recor...
Amadeus Pro lets you use your Mac for any audio-related task, such as live audio recording, digitizing tapes and records, converting between a variety of sound formats, etc. Thanks to its outstanding... Read more
Little Snitch 4.0.1 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Sparkle Pro 2.2.1 - $79.99
Sparkle Pro will change your mind if you thought building websites wasn't for you. Sparkle is the intuitive site builder that lets you create sites for your online portfolio, team or band pages, or... Read more
iWatermark Pro 2.0.0fc4 - Easily add wat...
iWatermark Pro is the essential watermarking app for professional, business, and personal use. Easily secure and protect your photos with text, a graphic, a signature, or a QR watermark. Once added... Read more

Latest Forum Discussions

See All

Mix and match magical brews in Miracle M...
Miracle Merchant, the charming fantasy card game by Tiny Touch Tales, is arriving next week. The development team, which also brought you Card Crawl and Card Thief, announced the game's launch with a pleasant little trailer that showcases the game'... | Read more »
Last Day on Earth: Zombie Survival guide...
Last Day on Earth: Zombie Survival is the latest big hit in the survival game craze. The gist of the game is pretty cut and dry -- try your best to survive in a world overrun by flesh-eating zombies. But Last Day on Earth justifies the hype... | Read more »
Eden: Renaissance (Games)
Eden: Renaissance 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Eden: Renaissance is a thrilling turn-based puzzle adventure set in a luxurious world, offering a deep and moving... | Read more »
Glyph Quest Chronicles guide - how to ma...
Glyph Quest returns with a new free-to-play game, Glyph Quest Chronicles. Chronicles offers up more of the light-hearted, good humored fantasy fun that previous games featured, but with a few more refined tricks up its sleeve. It's a clever mix of... | Read more »
Catch yourself a Lugia and Articuno in P...
Pokémon Go Fest may have been a bit of a disaster, with Niantic offering fans full refunds and $100 worth of in-game curency to apologize for the failed event, but that hasn't ruined trainers' chances of catching new legendary Pokémon. Lugia nad... | Read more »
The best deals on the App Store this wee...
There are quite a few truly superb games on sale on the App Store this week. If you haven't played some of these, many of which are true classics, now's the time to jump on the bandwagon. Here are the deals you need to know about. [Read more] | Read more »
Realpolitiks Mobile (Games)
Realpolitiks Mobile 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: PLEASE NOTE: The game might not work properly on discontinued 1GB of RAM devices (iPhone 5s, iPhone 6, iPhone 6 Plus, iPad... | Read more »
Layton’s Mystery Journey (Games)
Layton’s Mystery Journey 1.0.0 Device: iOS Universal Category: Games Price: $15.99, Version: 1.0.0 (iTunes) Description: THE MUCH-LOVED LAYTON SERIES IS BACK WITH A 10TH ANNIVERSARY INSTALLMENT! Developed by LEVEL-5, LAYTON’S... | Read more »
Full Throttle Remastered (Games)
Full Throttle Remastered 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Originally released by LucasArts in 1995, Full Throttle is a classic graphic adventure game from industry legend Tim... | Read more »
Stunning shooter Morphite gets a new tra...
Morphite is officially landing on iOS in September. The game looks like the space shooter we've been needing on mobile, and we're going to see if it fits the bill quite shortly. The game's a collaborative effort between Blowfish Studios, We're Five... | Read more »

Price Scanner via MacPrices.net

Photographer Explains Choosing Dell Laptop Ov...
Last week photographer and video blogger Manny Ortiz posted a video explaining the five most important reasons he settled on a Dell XPS 15 laptop instead of a MacBook Pro for his latest portable... Read more
Sale! 10-inch iPad Pros for $50 off MSRP, no...
B&H Photo has 64GB and 256GB 10.5″ iPad Pros in stock today and on sale for $50 off MSRP. Each iPad includes free shipping, and B&H charges sales tax in NY & NJ only: – 10.5″ 64GB iPad... Read more
WaterField Designs Upgrades TSA-friendly Zip...
San Francisco based designer and manufacturer Waterfield Designs has unveiled an upgraded and refined Zip Brief. Ideal for the minimalist professional, the ultra-slim Zip laptop bag actually holds a... Read more
USB 3.0 Promoter Group Announces USB 3.2 Upda...
The USB 3.0 Promoter Group has announced the pending release of the USB 3.2 specification, an incremental update that defines multi-lane operation for new USB 3.2 hosts and devices. USB Developer... Read more
Save on MacBook Pros with Apple Refurbished 2...
Apple recently dropped prices on Certified Refurbished 2016 15″ and 13″ MacBook Pros with models now as much as $590 off original MSRP. An Apple one-year warranty is included with each model, and... Read more
13-inch 2.3GHz/256GB MacBook Pros on sale for...
B&H Photo has 13″ 2.3GHz/256GB MacBook Pros in stock today and on sale for $100 off MSRP including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/256GB Space Gray MacBook Pro (... Read more
Clearance 2016 13-inch MacBook Airs, Apple re...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $809. An Apple one-year warranty is included with each MacBook, and shipping is free: – 13″ 1.6GHz/8GB/128GB MacBook Air: $... Read more
PHOOZY World’s First Thermal Capsules to Summ...
Summer days spent soaking up the sun can be tough on smartphones, causing higher battery consumption and overheating. To solve this problem, eXclaim IP, LLC has introduced the PHOOZY Thermal Capsule... Read more
2018 Honda Ridgeline with Android Auto and Ap...
The 2018 Honda Ridgeline is arriving in dealerships nationwide with a Manufacturer’s Suggested Retail Price (MSRP1) starting at $29,630. The 2017 Honda Ridgeline was named North American Truck of the... Read more
comScore Ranks Top 15 U.S. Smartphone Apps fo...
comScore, Inc. recently released data from comScore Mobile Metrix, reporting the top smartphone apps in the U.S. by audience reach for June 2017. * “Apple Music,” as it appears in comScore’s monthly... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Poole -...
Job Summary The people here at Apple don't just create products - they create the kind of wonder that's revolutionised entire industries. It's the diversity of those Read more
SW Engineer *Apple* TV - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
Frameworks Engineering Manager, *Apple* Wat...
Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
Product Manager - *Apple* Pay on the *Appl...
Job Summary Apple is looking for a talented product manager to drive the expansion of Apple Pay on the Apple Online Store. This position includes a unique Read more
*Apple* Retail - Multiple Positions - Apple...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.