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

Apple iTunes 12.2 - Play Apple Music...
Apple iTunes lets you organize and stream Apple Music, download and watch video and listen to Podcasts. It can automatically download new music, app, and book purchases across all your devices and... Read more
Apple Security Update 2015-005 - For OS...
Apple Security Update 2015-005 is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.... Read more
Apple HP Printer Drivers 3.1 - For OS X...
Apple HP Printer Drivers includes the latest HP printing and scanning software for OS X Lion or later. For information about supported printer models, see this page. Version 3.1: The latest printing... Read more
Epson Printer Drivers 3.1 - For OS X 10....
Epson Printer Drivers installs the latest software for your EPSON printer or scanner for OS X Yosemite, OS X Mavericks, OS X Mountain Lion, and OS X Lion. For more information about printing and... Read more
Xcode 6.4 - Integrated development envir...
Xcode provides everything developers need to create great applications for Mac, iPhone, and iPad. Xcode brings user interface design, coding, testing, and debugging into a united workflow. The Xcode... Read more
OS X Yosemite 10.10.4 - Apple's lat...
OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels entirely fresh, yet inherently familiar. The apps you use every day, enhanced with new features. And a... Read more
Dash 3.0.2 - Instant search and offline...
Dash is an API Documentation Browser and Code Snippet Manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
FontExplorer X Pro 5.0 - Font management...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Typinator 6.6 - 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
Arq 4.12.1 - Online backup to Google Dri...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more

Hands-On With Raceline CC
Set for release soon, Rebellion’s motorbike racing game, Raceline CC certainly looks stylish. But how does it play? I got my hands on a preview build to answer exactly that. | Read more »
Siegefall - Tips, Tricks, and Strategies...
So, you fancy establishing a base and ruling the world again. Siegefall is a convenient place to do that, but how about some great tips and tricks on how best to go about it? Here are a few ideas on how to get ahead as a beginner to this medieval... | Read more »
The WWE Comes to Racing Rivals - Because...
Racing Rivals is a racing game that's all about, well, rivalry. And who knows rivalry better than WWE superstars (shhhh, that was rhetorical)? [Read more] | Read more »
Hey, Who Put Apple Music in My SoundHoun...
One of the App Store's popular music discovery sources - SoundHound - has already been updated to include Apple's own music discovery source - Apple Music. That was fast! [Read more] | Read more »
Arcane Legends has a New Expansion Calle...
Arcane Legends has been going strong since it debuted at the tail end of 2012. So well, in fact, that it's already up to its sixth expansion. [Read more] | Read more »
Vector 2 is Officially a Thing and it...
Vector is a pretty cool parkour-driven runner that's gotten a pretty decent following since it first came out - although personally I think more people could stand to show it some love. Anyway, Nekki has announced that a sequel isofficially on its... | Read more »
Get Ready to Trucksform and Roll Out (an...
It looks like NuOxygen is bringing the truck-transforming racer Trucksform (get it?) to iOS in a couple of weeks. Although really it's more of an auto-driver than a racer. But still, transforming trucks! [Read more] | Read more »
This Week at 148Apps:June 22-26, 2015
June's Summer Journey Continues With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice,... | Read more »
LEGO® Minifigures Online (Games)
LEGO® Minifigures Online 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: | Read more »
World of Tanks Blitz celebrates its firs...
Today marks the first anniversary of the launch of World of Tanks Blitz, the mobile version of the PC tank battler, World of Tanks. World of Tanks Blitz launched on iOS and Android on June 26th last year and to celebrate, Wargaming is giving all... | Read more »

Price Scanner via MacPrices.net

Apple Releases OS X 10.10.4 With WIFi Fix, iO...
On Tuesday, Apple released final versions of OS X 10.10.4 and iOS 8.4, as well as updates for the Safari browser for OS X Yosemite, Mavericks, and Mountain Lion. The OS X 10.10.4 update focuses on... Read more
Dual-Band High-Gain Antennas for Home Wi-Fi N...
Linksys has announced what it claims are the first dual-band, omni-directional high-gain antennas for the consumer market. The new Linksys high-gain antennas available in a 2- and 4-pack (WRT004ANT... Read more
Apple refurbished 2014 15-inch Retina MacBook...
The Apple Store has Apple Certified Refurbished 2014 15″ 2.2GHz Retina MacBook Pros available for $1609, $390 off original MSRP. Apple’s one-year warranty is included, and shipping is free. They have... Read more
Clearance 2014 MacBook Airs available for up...
Adorama has 2014 MacBook Airs on sale for up to $301 off original MSRP including NY + NJ sales tax and free shipping: - 11″ 256GB MacBook Air: $798 $301 off original MSRP - 13″ 128GB MacBook Air: $... Read more
5K iMacs on sale for $100 off MSRP, free ship...
B&H Photo has the new 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2199, also $100... Read more
27-inch 3.2GHz iMac on sale for $1679, save $...
B&H Photo has the 27″ 3.2GHz iMac on sale for $1679.99 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Read more
12-inch 1.2GHz Gray MacBook on sale for $1487...
Amazon.com has the new 12″ 1.2GHz Gray MacBook in stock and on sale for $1487 including free shipping. Their price is $102 off MSRP, and it’s the lowest price available for this model. We expect... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
Amazon.com has the 15″ 2.2GHz Retina MacBook Pro on sale for $1819 including free shipping. Their price is $180 off MSRP, and it’s the lowest price available for this model. Read more
OtterBox Releases New Symmetry Series Metalli...
Otterbox’s new Symmetry Series of smartphone cases flaunts the best of both both street style and street smarts with their new metallic finishes and trusted OtterBox protection for iPhone 6 and... Read more
Eliminate Cable Chaos with New GE Branded Wra...
GE licensee Jasco Products has introduced a new line of GE branded Wrap-n-Charge USB wall chargers with built-in cable management. “We are always working to combine great technology with innovative... Read more

Jobs Board

*Apple* TV Live Streaming Frameworks Test En...
**Job Summary** Work and contribute towards the engineering of Apple 's state-of-the-art products involving video, audio, and graphics in Interactive Media Group (IMG) at Read more
Project Manager, WW *Apple* Fulfillment Ope...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
Senior Data Scientist, *Apple* Retail - Onl...
**Job Summary** Apple Retail - Online sells Apple products to customers around the world. In addition to selling Apple products with unique services such as iPad Read more
*Apple* Music Producer - Apple (United State...
**Job Summary** Apple Music seeks a Producer to help shepherd some of the most important content and editorial initiatives within the music app, with a particular focus Read more
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.