Getting the Whole Picture with the "Picture" XCMD

by Gareth Jones

One of the most intriguing tools in the "Scripter's Tools" stack that is part of HyperCard IIGS is the "Picture" external command (XCMD). When installed in a stack, the XCMD provides a command that will display a GS paint document, the top left part of a MacPaint document (320 by 200 pixels), or a graphic held as a resource or in the Clipboard. The style of window can also be specified by the user.

The Picture XCMD has many uses, from a simple picture viewer to the engine of a stack that loads pictures to modify them, to displaying fancy "About..." and "Help" dialogue boxes stored as resources in the stack by the program Genesys. It is also a useful addition to your Home stack, as you can then view graphics by simply typing "Picture" into the message box.


Picture commands have the following syntax:

picture [sourceName [, type [, windowStyle [, visible [, rect]]]]]

If you call picture with no parameters, HyperCard displays the directory dialog box and asks you to locate a paint file to display. If you cancel the dialog box, picture sets the result to "cancel".

If you decide to use parameters, the "Type" parameter should be one of the following words: "file", "resource", or "clipboard." The default is "file".

"WindowStyle" should be "dialog", "document", "rect", "shadow", or "windoid". The default is "document", which creates a movable window with horizontal and vertical scrollbars.

"Visible" is an expression that evaluates to "true" or "false". It determines whether the picture XCMD initially creates a visible or invisible window. The default value is "true".

"Rect" is an expression that specifies the location of the window on the screen. The following are examples of legal commands:

picture picture "My.Hard.Drive:PicName"
picture "PicName",file
picture "PicName",resource
picture "Picture Window's Name",clipboard
picture "PicName",file,shadow, true,"50,60,280,120"

The "SourceName" parameter of this XCMD is defined as a string that evaluates to:

  1. the name of an Apple Preferred format picture file or MacPaint compatible file (for source type "file"),
  2. the name or number of a PICT resource (for source type "resource"), or
  3. any name at all (for source type "clipboard").

In theory, the source name also becomes the name of the picture window, so that if you display a picture file with the pathname ":MyHardDrive:Paintings:NumberOne", the window displaying the picture would also be ":MyHardDrive:Paintings:NumberOne".

A Bug

Unfortunately, there is a serious bug in this XCMD that corrupts the last part of the window name if the name is 32 characters long or longer. You can verify this by putting the following script into a button and then clicking the button:

on mouseUp
  global filename
  answer file "Select a picture:" of type 192
  put it into filename
  picture filename
  put filename -- this shows the complete pathname in msg box
  wait five seconds
  close window filename -- this won't work, under either System 6.0.1 or 5.0.4
end mouseUp

The window does not close when it should, and the reason is that the final characters of the window's name have been mangled into garbage, represented on screen as inverse question marks.

A Fix

Obviously, a way has to be found to close the window under control of a script, or the picture window, windoid, or dialogue will clutter the screen until you quit the stack. Since addressing it by name is useless, use the following script to do the job.

on mouseUp
  REPEAT with i = 1 to the number of windows
   put first character of the name of window i into winName
   if winName is ":" then
     put the id of window i into IDnumber
     do "close window id" && IDnumber
     exit repeat
   end if
  end repeat
end mouseUp

The script depends on the fact that the picture window is almost certainly the only one whose name begins with a colon. It finds the window whose name begins that way and asks for its "ID number." Finally, it orders that the window with that ID number be closed.

It is unfortunate that Apple never fixed the bug I've described. However, you can work around it - completely avoid it, in fact - with a few lines of script.

Thanks to Lorne Walton for verifying the bug.

Gareth Jones is the former Editor of Apples B.C. News and a Contributing Editor of Hyper Quarterly, a new magazine-on-disk devoted to HyperCard IIGS stacks.

HyperCard IIGS Article Index | HyperCard FAQ | Hyper Quarterly Home