TweetFollow Us on Twitter

Icon Stuffing
Volume Number:7
Issue Number:7
Column Tag:HyperChat

Related Info: Quickdraw Resource Manager

Icon Stuffing XCMD

By Steven Fuchs, Stony Brook, NY

iConjured Up

Last year at a meeting of LIMUG, the Long Island Mac Users Group I was introduced to a very useful utility stack called iConjurer by Tom Wimbish, which as the name would suggest is a tool for creating icons. What iConjuror provides is an environment from which the powerful painting tools contained in HyperCard can be used to create icon sized pictures as well as a convenient method of storing them. iConjuror’s shortcoming was that it provided no direct way to convert the pictures HyperCard created into ICON resources. The workaround for this was to copy the image of the icon onto the clipboard and then launch ResEdit, open the requested stack and paste the picture into ResEdits ICON editor, which would convert the first 32 pixels in each of the first 32 rows into an icon. Although once committed to muscular memory this process could be accomplished quickly, it was decidedly un-Mac like, in other words there had to be a better way. I decided that what was needed was an XCMD which could take the image of an icon and create an ICON resource, either in the current stack or in any desired stack. Hence the impetus behind the creation of the IconStuffer XCMD.

Working Overview

When a picture doesn’t tell a story

The first order of business was to make the data of the selected picture available to the XCMD. While some sleuthing into HyperCards inner workings probably could produce a direct method of obtaining the contents of the selection rectangle this is undesirable for some very good reasons. In general it is by far the more difficult task, and in any programming, Mac programming especially and XCMD programing even more so you should always look to avoid trouble. Secondly a method of this sort would almost certainly not work with a different version of HyperCard and may not even work between different machines. Therefore I chose to take the easier path and obtain this information from the clipboard, after forcing the user to copy the image of the icon. However easier does not mean easy, and accessing the clipboard for the icons image is no exception. The clipboard stores its images in the form of a ‘PICT’ resource, Inside Macintosh tells us that the format for a ‘PICT’ resource consists of the QuickDraw calls necessary to recreate the image. The ‘ICON’ resource is simply a series of 1024 bits, the ones and zeros of which represent the black and white pixels of the icons 32x32 rectangle. While much time could have been spent decoding the ins and outs of ‘PICT’ resources and learning how to convert these to icons, a much easier mechanism exists. All that is involved is pulling a bit of a fast one on the operating system and QuickDraw.

Now You See It

All QuickDraw drawing takes place into a data structure known as a GrafPort. When you create a window unbeknownst to you, you are creating a GrafPort. While the Mac OS allows for the creation of GrafPorts on their own it is rarely used, and I will not do that. What I do need to recreate is an important record of the GrafPort called portBits. The portBits record is a bitmap which is the destination of all drawing by the GrafPort.

This bitmap contains the ones and zeros which make up the black and white pixels of the GrafPort in question. It is this data which can easily be converted into an ‘ICON’ resource. The important record in the bitmap is the BufferAddr record, which is a pointer to the location at which the bits that make up the image begin. The QuickDraw sleight of hand I used was to create my own bitmap and fool the GrafPort into drawing into it. The data is now in a form suitable to my purposes and is ready to be made into an icon.

Step by Step

Take a picture, please

Before proceeding some error checking must be done, I know, boring,boring, boring. What must be, must be however and the first form of this takes place in the function FillIconPointer. Using the toolbox function GetScrap we will determine whether or not there is a ‘PICT’ resource on the clipboard at all. This is done by passing a handle of arbitrary size, and telling it I would like the available ‘PICT’ resource only. The function returns the size of the resource as well as resizing the handle and copying the ‘PICT’ resource into it.

If there was a ‘PICT’ resource in the scrap I need to allocate the memory necessary for the icon. Since I know an ‘ICON’ measures 32x32 I am spared the step of figuring out the size of the necessary bitmap. The space of the bitmap is allocated using the NewPointer function. Since NewPointer accepts its size parameter in bytes and not bits, and there are 8 bits in a byte, the size of the pointer should be 32x32/8 or 128. I allocate this into the pointer BufferAddress and in a fit of safety consciousness, check to be sure the allocation succeeded. Assuming that it did, I then assign the remaining records of the structure OffMap. Record 1 of a bitmap, baseAddr is a pointer to the address at which the bitmap image starts. Record 2 of a bitmap is rowBytes, or the number of bytes wide the image is to be. Since an ICON is a fixed size I know that this value will always be 32/8 or 4. In some other circumstance I would compute rowBytes by dividing the width of the bit image by 8. Also an important note is that the Mac operating system requires that all addresses be even, so to avoid a deadly crash the value for rowBytes must always be even. Finally we set bounds, which is the rectangle which encloses our bitmap or 32 x 4.

Now that we are fully prepared to fool QuickDraw only a few more precautions remain. First and foremost is to remember the bitmap currently stored in portBits so as to return things to their original state upon completion, very important for the XCMD programmer. I obtain the existing portBits by calling GetPort and storing the value of portBits into the variable OldMap. Then I use the toolbox call SetPortBits to reassign any subsequent drawing in that GrafPort to my bitmap. I then call ClipRect to insure that the entire image is drawn and EraseRect in order to clear any existing bits from the BitMap. Then a simple call to DrawPicture will allow QuickDraw to fill in the proper pixels of my bitmap for me. Finally a call to SetPortBits again will restore the GrafPorts portBits, dispose of the handle to the PICT resource, and return as the result of FillIconPointer the address at which the bitmap image of the icon begins.

How a bitmap becomes an ICON

The path to creating an ICON resource now becomes very simple since I now have the data in the form I want it. Most of this remaining work takes place in the function CreateNewIcon . First I create a handle of size 128, the fixed size of an icon. A handle is necessary since the toolbox call AddResource demands a handle aand must be used to attach a resorce to the resource file. I then invoke the toolbox call BlockMove to copy the data from the bitmaps pointer to the handle. With the handle now prepared call AddResource which attaches the handle to the resource fork and WriteResource which makes it final by saving the resource to disk. Finally release the memory used by the icon. Congratulations! You have just made an icon.

Selective Stuffing

IconStuffer can act in one of two modes, simple and difficult. Simple mode is activated when IconStuffer is called with no parameters. It simply jams its new ICON resource into the current resource file, which in my case is the iConjuror stack. This is the default response and requires no additional action to bring about. The complex mode is induced when IconStuffer receives a parameter from HyperCard. IconStuffer expects this parameter to be the full pathname of a file. If a parameter is passed then the function SetResFile is called which accepts a file name and attempts to open a resource file with that name. If there is no file with that name one is created. SetResFile returns the new resource manager reference number. Finally the function CreateNewIcon is called which actually creates the ICON resource and places it in that file, the file is then closed and control returns to HyperCard.

Figure 1: Project File

The Final Steps

Compiling a code resource

For those readers new to the process of compiling a code resource I will provide a short description of this process which is also adequately explained in pages 156-158 of the THINK Users guide. The only items to insure that you use the DRVR runtime lib instead of the default runtime lib, and that the files HyperXCMD and HyperXCMD interface files are included in the project, as shown in Figure 1. The select “Set Project Type” from the project menu, and choose the Code Resource icon. Name the resource IconStuffer, give it any arbitrary number (1120 is used in my example), and set the type to “XCMD”. Now select build Code Resource from the menu and step back. If all goes well you have just created your first, (or yet another) XCMD for HyperCard.

The MenuField concept

My method of calling IconStuffer is through a device known as a MenuField (not my name), the script of which is in Figure 2 . A MenuField is a locked field which responds to mouseups within it depending upon the line clicked in. The first responsibility of a MenuField is to utilize the newfield message. The newfield message is passed to a field upon its being pasted . By trapping this and inserting text into itself the IconStuffer field insures that it will always contain the correct menu choices. Figure 2 contains the script for IconStuffer Field, the newfield handler will add the text “This Stack” into line 1, “Any Stack•” into line 2, and “Choose Stack” into line 3.

The real work is done in the mouseup handler which upon receiving a click determines the line clicked in a takes the proper action. Clicking in line 1 calls the simple mode of IconStuffer, adding the icon to the current stack. Clicking in line 3 pulls a bit of a trick on HyperCard. Sending HyperCard the message go to “the target stack” will cause HyperCard prompt the user for a stack with the prompt “Help find the target stack”.

This flawed logic however will break if the user has a stack named “the target stack”. By choosing a phrase the would not often be used for a stack name this HyperCard trick can be used with success. As a precaution before using this get the long name of the current stack, and afterwards check to be certain that they are not identical. If they are identical you should assume that the user clicked on the cancel button , not selecting a stack. In this case the Mac like thing to do is to abort the operation of the script in as graceful a method as possible.

If the stack names are different then return to the starting point bringing the long name of the target stack with you. This will be in the form of “stack “StartUp:HyperCard:Utilities:IconBox”” for a stack named IconBox. simply remove the word stack, and the opening and closing quotes, this information is ready for passing to IconStuffer. This is what occurs when a user clicks on line 3 of the MenuField or optionclicks on line 2. The different is that an optionclick in line 2 of the MenuField stores the long name of the target stack in line 10 of the field and the short name of the stack in line 2. Subsequent clicks in line 2 of the field will utilize line 10 to paste the icon into that specified file.

--1

on newfield
  Put "This Stack"&return&"Any Stack"&return&"Choose Stack" into me
end newfield

on mouseup
  Put trunc((item 2 of the clickloc-item 2 of the rect of me)¬
  /textheight of me)+1 into LineHit
  if LineHit is 1 then IconStuffer
  else if (the optionkey is down and LineHit is 2) or LineHit is 3 ¬
  or (line 10 of me is empty and LineHit is 2) then
    push card
    Lock Screen
    go to stack "the target stack"
    put the long name of this stack into LName
    delete word 1 of LName
    delete char 1 of LName
    delete last char of LName
    put the short name of this stack into SName
    pop card
    unlock screen
    IconStuffer(LName)
    if LineHit is 2 then
      Put SName into line 2 of me
      Put LName into line 10 of me
    end if
  else  IconStuffer(line 10 of me)
end mouseup

Figure 2: HyperTalk Script

In Closing

My sources close to the Heartbeat of Apple have informed me that HyperCard 2.0 would soon be out , and that it contains an icon editor that not only makes iConjuror obsolete, but makes the writing of IconStuffer a waste of time. As of the writing of this article HyperCard 2.0 had not come out and I have not seen its icon editor. Needless to say that if I had heeded the naysayers and not written IconStuffer I would not be using it today, and much the poorer for it. Let that be a lesson to you. Even with impending obsolescence from the belated HyperCard 2.0 (or 2.01, 2.02, 2.03 etc. ) IconStuffer remains a good guide for creating icons from common QuickDraw calls, and for creating offscreen bitmaps. Good Luck and use in Good Health. Hope you enjoy.

unit IconStufferUnit;
interface
 uses
  HyperXCmd;

 procedure MAIN (ParamPtr: XCmdPtr);
implementation

{FillIconPointer accepts no parameters and returns a }
{pointer to the icons bits. The operation is successful }
{if the clipboard contains a PICT resource and the }
{ memory necessary for the ICON can be obtained}
 function FillIconPointer: Ptr;
  var
   HldHandle: handle;
   IconRect: Rect;
   OldPort: GrafPtr;
   err, TheOffset: longint;
   OffMap, OldBits: BitMap;
   BufferAddress: ptr;
 begin
  BufferAddress := nil;
  HldHandle := NewHandle(2);
  err := GetScrap(HldHandle, 'PICT', TheOffset);
  if err > 0 then
   begin
{**The clipboard contained a PICT  **}
    SetRect(IconRect, 0, 0, 32, 32);
    OffsetRect(IconRect, 40, 40);
    BufferAddress := NewPtr(32 * 4);
    if BufferAddress <> nil then
 {**    Memory for the ICON present**}
     begin
 {**    Create offsreen bitmap**}
      OffMap.baseAddr := BufferAddress;
      OffMap.rowBytes := 4;
      OffMap.bounds := IconRect;
      GetPort(OldPort);
{**Store previous bitmap  **}
      OldBits := OldPort^.portbits;
{**Draw into our bitmap   **}
      SetPortBits(OffMap);
      ClipRect(IconRect);
      EraseRect(IconRect);
      DrawPicture(PicHandle(HldHandle), IconRect);
{**Restore previous bitmap**}
      SetPortBits(OldBits);
      ClipRect(OldPort^.portRect);
     end;
   end;
{**Dispose of our copy of the scrap**}
  DisposHandle(HldHandle);
{**Return data bits**}
  FillIconPointer := BufferAddress;
 end;

{GetNextEmptyID does just that while insuring that the  }
{ID's under 128 which are reserved are not used!**}
 function GetNextEmptyID: integer;
  var
   Answer: integer;
 begin
  Answer := 0;
  repeat
   Answer := UniqueID('ICON');
  until Answer > 128;
  GetNextEmptyID := Answer;
 end;

{**SetResFile accepts a string as a parameter and  }
{returns the resource manager reference number **}
 function SetResFile (TheName: str255): integer;
  var
   TheAns: integer;
 begin
  TheAns := OpenResFile(TheName);
  if TheAns = -1 then
   begin
    CreateResFile(TheName);
    TheAns := OpenResFile(TheName);
   end;
  SetResFile := TheAns;
 end;

{**CreateNewIcon accepts the data and the ID to }
{ be used and creates the ICON resource.Returning true  }
{if the operation was a success**}
 function CreateNewIcon (TheImage: Ptr; TheID: integer): Boolean;
  var
   TheHandle: handle;
 begin
  CreateNewIcon := false;
{**Allocate space for the ICON**}
  TheHandle := NewHandle(128);
  if TheHandle <> nil then
   begin
    HLock(TheHandle);
{**Copy bits from the pointer to the handle  **}
    BlockMove(TheImage, TheHandle^, 128);
    HUnLock(TheHandle);
{**Convert handle to a resource    **}
    AddResource(TheHandle, 'ICON', TheID, '');
    if ResError = noErr then
     begin
{**Test for success! **}
      CreateNewIcon := true;
{**Force a disk update    **}
      WriteResource(TheHandle);
     end;
   end;
 end;

{**MAIN brings the routines together **}
 procedure MAIN (ParamPtr: XCmdPtr);
  var
   TheData: Ptr;
   TheHandle: handle;
   TheID, OldRes, NewRes: integer;
   TheItem: str255;
 begin
  TheData := FillIconPointer;
  if TheData <> nil then
{**Could data for ICON be obtained **}
   begin
    OldRes := CurResFile;
    NewRes := 0;
    if ParamPtr^.paramCount > 0 then
     begin
{**Should a different file be used **}
      ZeroToPas(ParamPtr, ParamPtr^.params[1]^, TheItem);
      NewRes := SetResFile(TheItem);
{**If so use it  **}
      UseResFile(NewRes);
     end;
    if NewRes <> -1 then
     begin
{**If there was no file error **}
      TheID := GetNextEmptyID;
{**Do the work!  **}
      if not CreateNewIcon(TheData, TheID) then
       SendHCMessage(ParamPtr, 'Answer "Icon could not be created"');
{**Restore resource chain **}
      UseResFile(OldRes);
      if NewRes > 0 then
{**If a file was opened then close it**}
       CloseResFile(NewRes);
      DisposPtr(TheData);
     end
    else
     SendHCMessage(ParamPtr, 'Answer "File was not found"');
   end
  else
   SendHCMessage(ParamPtr, 'Answer "PICT could not be obtained"');
 end;
end.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

How to get coins faster in Rodeo Stamped...
There comes a time in a cowboy or cowgirl's life when all the riding and lassoing skills in the world aren't enough. You're going to need some cold, hard cash to keep your sky zoo expanding in Rodeo Stampede. [Read more] | Read more »
Artik Games releases Splashy Cats for An...
Splashy Cats had us hooked from the title alone, and when we found out the game was literally just zig-zagging one of our favourite pop-culture references, guised as a playable cat character, down a river – our appetites were whetted to say the... | Read more »
Battle Cars (Games)
Battle Cars 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Welcome to the world of Battle Cars. Battle Cars is a classic arcade top-down racing game with fast mini cars and funny weapons to... | Read more »
How to get started with live.ly
One could be forgiven for thinking that there are already plenty of streaming video apps out there. It's just that the App Store charts would insist that you're mistaken. [Read more] | Read more »
Rodeo Stampede: Guide to all Savannah an...
A "gotta catch 'em all" joke seems appropriate here, even though we're talking animals in Rodeo Stampede and not pocket monsters. By now you've probably had plenty of rides, tamed some animals and built yourself a pretty nice zoo | Read more »
Is there cross-platform play in slither....
So you've sunken plenty of hours into crawling around in slither.io on your iPhone or iPad. You've got your stories of tragedy and triumph, the times you coiled four snakes at one time balanced out by the others when you had a length of more than... | Read more »
Rodeo Stampede guide to running a better...
In Rodeo Stampede, honing your skills so you can jump from animal to animal and outrun the herd as long as possible is only half the fun. Once you've tamed a few animals, you can bring them home with you. [Read more] | Read more »
VoxSyn (Music)
VoxSyn 1.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0 (iTunes) Description: VoxSyn turns your voice into the most flexible vocal sound generator ever. Instantly following even subtle modulations of pitch and... | Read more »
Catch Battleplans on Google Play from Ju...
Real-time strategy title Battleplans is due for release on Google Play on June 30th, following its release for iOS systems last month. With its simple interface and pretty graphics, the crowd-pleaser brings a formerly overlooked genre out for the... | Read more »
iDoyle: The interactive Adventures of Sh...
iDoyle: The interactive Adventures of Sherlock Holmes - A Scandal in Bohemia 1.0 Device: iOS Universal Category: Books Price: $1.99, Version: 1.0 (iTunes) Description: Special Release Price $1.99 (Normally $3.99) | Read more »

Price Scanner via MacPrices.net

MacBook Airs on sale for up to $50-$100 off M...
B&H Photo has 13″ and 11″ MacBook Airs on sale for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.6GHz/128GB MacBook Air: $849 $50 off list price - 11″ 1.... Read more
Brexit Vote Result Forecast To Slash UK 2016...
Uncertainty and economic volatility can be expected to increase over the next nine months, as the Brexit and concerns over the future of the EU hit IT investment, say Canalys market analysts, with... Read more
13-inch 256GB MacBook Air on sale for $1149,...
Amazon has the 2016 13″ 1.6GHz/256GB MacBook Air (model MMGG2LL/A) on sale for $1149.99 including free shipping. Their price is also $50 off MSRP. Read more
Haven App Launches New Age Of Wirless 911 Eme...
Haven from RapidSOS represents a transformation in access to emergency services from a phone call solely dependent on voice to a robust data connection for voice, text, medical/demographic data.... Read more
Cu Parachute 1.1 Retirement Success PLanning...
Tucson, Arizona based Indie developer Bradley McCarthy has announce the release of Cu (Copper) Parachute 1.1 for iPhone, iPad, and iPod touch devices — a tool with which users can continuously... Read more
Research and Markets Releases iPhone 6s Plus...
A new analysis report from Dublin-based Research and Markets observes that with the iPhone 6s Plus, Apple introduced a new rear camera module. The new device has similar structure and technology than... Read more
Apple refurbished Retina MacBook Pros availab...
Apple has Certified Refurbished 2015 13″ and 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
12-inch 32GB and 128GB WiFi iPad Pros on sale...
B&H Photo has 12″ 32GB & 128GB WiFi iPad Pros on sale for up to $80 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 32GB WiFi iPad Pro: $749 $50... Read more

Jobs Board

*Apple* Retail - Multiple Positions, Willow...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* iPhone 6s and New Products Tester Ne...
…we therefore look forward to put out products to quality test for durability. Apple leads the digital music revolution with its iPods and iTunes online store, Read more
*Apple* Retail - Multiple Positions, Towson...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.