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.

 
AAPL
$102.94
Apple Inc.
+0.44
MSFT
$45.02
Microsoft Corpora
-0.41
GOOG
$573.81
Google Inc.
+2.21

MacTech Search:
Community Search:

Software Updates via MacUpdate

Mac DVDRipper Pro 5.0 - Copy, backup, an...
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
pwSafe 3.1 - Secure password management...
pwSafe provides simple and secure password management across devices and computers. pwSafe uses iCloud to keep your password databases backed-up and synced between Macs and iOS devices. It is... Read more
StatsBar 1.8 - Monitor system processes...
StatsBar gives you a comprehensive and detailed analysis of the following areas of your Mac: CPU usage Memory usage Disk usage Network and bandwidth usage Battery power and health (MacBooks only)... Read more
Path Finder 6.5.5 - Powerful, award-winn...
Path Finder is a file browser that combines the familiar Finder interface with the powerful utilities and innovative features. Just a small selection of the Path Finder 6 feature set: Dual pane... Read more
QuarkXPress 10.2.1 - Desktop publishing...
With QuarkXPress, you can communicate in all the ways you need to -- and always look professional -- in print and digital media, all in a single tool. Features include: Easy to Use -- QuarkXPress is... Read more
Skype 6.19.0.450 - Voice-over-internet p...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
VueScan 9.4.41 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Cloud 3.0.0 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
LibreOffice 4.3.1.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
SlingPlayer Plugin 3.3.20.505 - Browser...
SlingPlayer is the screen interface software that works hand-in-hand with the hardware inside the Slingbox to make your TV viewing experience just like that at home. It features an array of... Read more

Latest Forum Discussions

See All

The Manhattan Project Review
The Manhattan Project Review By Andrew Fisher on September 2nd, 2014 Our Rating: :: ROCKET SCIENCEUniversal App - Designed for iPhone and iPad The Manhattan Project offers a great Euro-style gameplay experience, but it is totally... | Read more »
Rhonna Designs Magic (Photography)
Rhonna Designs Magic 1.0 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0 (iTunes) Description: Want to sprinkle *magic* on your photos? With RD Magic, you can add colors, filters, light leaks, bokeh, edges,... | Read more »
This Week at 148Apps: August 25-29, 2014
Shiny Happy App Reviews   | Read more »
Qube Kingdom – Tips, Tricks, Strategies,...
Qube Kingdom is a tower defense game from DeNA. You rally your troops – magicians, archers, knights, barbarians, and others – and fight against an evil menace looking to dominate your kingdom of tiny squares. Planning a war isn’t easy, so here are a... | Read more »
Qube Kingdom Review
Qube Kingdom Review By Nadia Oxford on August 29th, 2014 Our Rating: :: KIND OF A SQUARE KINGDOMUniversal App - Designed for iPhone and iPad Qube Kingdom has cute visuals, but it’s a pretty basic tower defense game at heart.   | Read more »
Fire in the Hole Review
Fire in the Hole Review By Rob Thomas on August 29th, 2014 Our Rating: :: WALK THE PLANKUniversal App - Designed for iPhone and iPad Seafoam’s Fire in the Hole looks like a bright, 8-bit throwback, but there’s not enough booty to... | Read more »
Alien Creeps TD is Now Available Worldwi...
Alien Creeps TD is Now Available Worldwide Posted by Ellis Spice on August 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Dodo Master Review
Dodo Master Review By Jordan Minor on August 29th, 2014 Our Rating: :: NEST EGGiPad Only App - Designed for the iPad Dodo Master is tough but fair, and that’s what makes it a joy to play.   | Read more »
Motorsport Manager Review
Motorsport Manager Review By Lee Hamlet on August 29th, 2014 Our Rating: :: MARVELOUS MANAGEMENTUniversal App - Designed for iPhone and iPad Despite its depth and sense of tactical freedom, Motorsport Manager is one of the most... | Read more »
Motorsport Manager – Beginner Tips, Tric...
The world of Motorsport management can be an unforgiving and merciless one, so to help with some of the stress that comes with running a successful race team, here are a few hints and tips to leave your opponents in the dust. | Read more »

Price Scanner via MacPrices.net

Apple refurbished iPads available for up to $...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
Are We Now In The Post-Post-PC Era?
A longtime and thoroughgoing laptop aficionado, I was more than a little dismayed by Steve Jobs’s declaration back in 2010 when he sprang the iPad on an unsuspecting world. that we’d entered a “post-... Read more
PC Outlook Improves, But 2014 Shipments Still...
According to the International Data Corporation (IDC) Worldwide Quarterly PC Tracker, worldwide PC shipments are expected to fall by -3.7 percent in 2014. To hat’s actually an improvement from the... Read more
IDC Lowers Tablet Sales Projections for 2014...
Following a second consecutive quarter of softer than expected demand, International Data Corporation (IDC) has lowered its worldwide tablet plus 2-in-1 forecast for 2014 to 233.1 million units. The... Read more
Apple now offering refurbished 21-inch 1.4GHz...
The Apple Store is now offering Apple Certified Refurbished 21″ 1.4GHz iMacs for $929 including free shipping plus Apple’s standard one-year warranty. Their price is $170 off the cost of new models,... Read more
Save $50 on the 2.5GHz Mac mini, on sale for...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $300 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $300 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free. These are the best prices on... Read more
The Rise of Phablets
Carlisle & Gallagher Consulting Group, a businesses and technology consulting firm focused solely on the financial services industry, has released an infographic depicting the convergence of... Read more
Bad Driver Database App Allows Good Drivers t...
Bad Driver Database 1.4 by Facile Group is a new iOS and Android app that lets users instantly input and see how many times a careless, reckless or just plain stupid driver has been added to the... Read more
Eddy – Cloud Music Player for iPhone/iPad Fre...
Ukraine based CapableBits announces the release of Eddy, its tiny, but smart and powerful cloud music player for iPhone and iPad that allows users to stream or download music directly from cloud... 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
*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
*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
*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
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.