H O M E

Jonathan Cooper Manager of Information, Art Gallery of New South Wales, Sydney, AUSTRALIA

Getting the Picture

Originally published in Mac-inations (Club Mac, Sydney, Australia) 1992

Recently I read a message on the Club Mac Bulletin Board requesting information about colour in HyperCard. The person who wrote the message knew that HyperCard is essentially a black and white programme but wondered whether it was still possible to display colour. I replied that, yes, it was possible, thanks to an external command called "picture" that comes with HyperCard 2.0 and offered to send a description of its use and syntax. It was then that I discovered that the three books I have on HyperTalk 2 [The Complete HyperCard 2.0 Handbook by Danny Goodman (Bantam, 1990), HyperTalk 2.0: The Book by Dan Winkler and Scot Kamins (Bantam, 1990) and The Complete Book of HyperTalk® 2 by Dan Shafer (Addison-Wesley, 1991)] disagreed with each other. (I guess they were all relying on different pre-release versions of HyperCard.) Unfortunately, the "HyperTalk Reference" stack doesn't even mention the "picture" XCMD, so there was nothing to do but experiment. So, what appears below is based on a combination of Danny Goodman (who seems to be the most correct) and my own observations. If you discover that things seem to happen a little differently on your setup, please let me know.

Syntax
"Picture" can be called in any of the following forms:

picture

picture "<name>"

picture "<name>",<type>

picture "<name>",<type>,<windowStyle>

picture "<name>",<type>,<windowStyle>,<visible>

picture "<name>",<type>,<windowStyle>,<visible>,bitDepth

where:

<name> is the name of the picture (full path can be used if it is a picture file) (This becomes the name of the window),

<type> can be file, resource or clipboard,

<windowStyle> can be dialog, shadow, rect, plain, zoom, windoid or roundRect,

<visible> can be true or false (1)

<bitDepth> can be 1, 2, 4, 8, 16 or 32 (depending on the monitor) (2).

Three examples:

1. picture "HD 40:Pictures :Dog",file,shadow,true,16

... displays a picture from a file called "Dog" (in the folder "Pictures ", on the volume "HD 40") in a shadow-style window and a bit-depth of 16. The picture window is now called simply "Dog"

2. picture "Dog",resource,plain

...displays a picture from a PICT resource called "Dog" in a plain-style window. The window will be called "Dog" (surprise surprise!).

3. picture

... produces a standard open file dialog box to prompt you to find a MacPaint or PICT file to display. When one is found, it is displayed in a document window. The name of the window will be the file's name (minus the volume and folder names).

After the Picture XCMD creates a new window, it sends the following message to the current card:

(In HyperCard 2.0)

openPicture <windowName>

(In HyperCard 2.1)

openPicture <windowName>,<windowID>

To close a window, simply use the command:

close window <windowName>

Properties

Pictures have the following properties (that you can get and set):

rect, top, bottom, left, right, topLeft, bottomRight, height, width, loc, globalRect, globalLoc, scroll, visible, zoom, scale, dithering

The first seven ( rect to bottomRight) are the same as for other objects, in card window co-ordinates (3).

Height and width should be self-explanitory

Loc for some reason behaves differently for pictures than it does for other objects. It seems to give the same value as topRight (in card window co-ordinates).

GlobalRect and globalLoc are the same as rect and loc respectively except that they are expressed in global (i.e. screen) co-ordinates.

Scroll is the point of the picture, expressed in pixel co-ordinates local to the picture that appears at the top left corner of the window. The default is "0,0".

Visible can be true or false.

Zoom can be " in " or " out", like clicking the zoom box (zoom windowStyle only).

Scale is an integer from -5 to 5 that represents the scaling of the picture as a power of 2. Thus for example, 0 is normal size, 3 is eight times (=23) normal size and -1 is half (=2-1) normal size.

Dithering can be true or false. (The default is false.) Dithering mixes existing colours to give the illusion of a third colour not normally available on a particular screen (e.g. for displaying 16-bit pictures on an 8-bit monitor) (4).

Getting feedback

When the user clicks on a picture, the XCMD sends the message

mouseDownInPicture <windowName>,"<position>"

... followed by ...

mouseUpInPicture <windowName>,"<position>"

... to the current card, where <position> is the two-item position of the click -- local to the picture, horizontal followed by vertical.

This means you can control what happens according to which picture is clicked and where it is clicked. So to clarify, if you were to click on a picture window called "Dogcow" 30 pixels from its left edge and 50 pixels from its top edge (not including its title bar) you would trigger the message...

mouseDownInPicture "Dogcow","30,50"

followed by...

mouseUpInPicture "Dogcow","30,50"

Two examples:

1.

on mouseUpInPicture windowName
  close window windowName
end mouseUpInPicture

... will close any picture window when it is clicked upon.

2.

on mouseUpInPicture windowName,where
  put item 1 of where into h
  put item 2 of where into v
  put left of window windowName into L
  put right of window windowName into R
  put top of window windowName into T
  put bottom of window windowName into B
  put average(L,R)-L into centreH
  put average(T,B)-T into centreV
  if h>centreH-20 and h<centreH+20 and v>centreV-20 and v<centreV+20
  then answer "Bull's eye!"
  else answer "Missed."
end mouseUpInPicture

... will tell you whether you have clicked within the centre 40 x 40 region of the picture (="Bull's eye") or not.

One final note:

Pictures displayed with the "Picture" XCMD are in external windows. Therefore, unless you script it otherwise, when the user changes cards or moves the card around the screen, the picture will stay put. In fact with all window styles other than rect and shadow, if the user clicks on the card anywhere outside the picture, the picture will disappear behind the card window. (You can get it back by typing command-L for "Next window".) If you want coloured pictures that are integrated into your cards (and you can't wait for HyperCard 2.5 - or whatever) you should have a look at the freeware stack Colorizing HyperCard, but be warned, if you thought the "picture" XCMD was too complex, you might be in for a bit of a shock. Still, if the end result is important enough, the effort is worth it!

____

1. False (i.e. invisible) is used for loading large pictures into RAM, perhaps on opening the stack or card, so that the user doesn't have to wait for it to appear when they click a button and also for changing properties without distracting the user.

2. If available RAM is low, bitdepth can also be set to 0, which means that the picture is drawn directly onto the card rather than being loaded into "offscreen buffers". This however makes scrolling and zooming of the picture slower because data must be retrieved from a file each time.

3. You can use one of the following values instead of an actual rect or loc value:
card - centres the picture on the same screen as the card window
biggest - centres the picture on the largest screen
deepest - centres the picture on the screen with the greatest depth of colour
main - centres the picture on the screen where the menu bar is located

4. At least that's the theory. On my system (HC 2.1 on an LCII with 16-bit colour) I couldn't see any difference between dithering or not dithering. If anyone can get results from using this property, please let me know.

5. <position> is one parameter; if it is quoted literally (as opposed to in a variable) it must be surrounded by quotes.