HCGS Article 3

[gareth@vcn.bc.ca (Gareth Jones)]

Here is another article on HyperCard GS by yours truly.

++++++++++++

Getting the Whole Picture with the "Picture" XCMD
     
     Gareth Jones
     
     10 November 1995
     
      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.
     Syntax
     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.