House o' HyperCard
Scripts of the Month
HyperCard 2.0 introduced the
palette command, allowing you to display a floating palette with buttons and a background picture. The Palette Maker card in Power Tools lets you lay out and create your own palettes, and many scripters immediately glommed onto palettes as a powerful control and navigation tool, particularly for multi-stack applications or utilities meant to be used across stacks.
The Palette Maker card, however, is just the beginning for those acquainted with the power of (echo sound effect)...the PLTE resource! You can change the window's appearance, use a color background picture instead of black and white, include long scripts in your palette buttons instead of being limited to a single line, and change various settings of the completed palette.
This page is a compendium of what I know about the palette command. It is necessarily incomplete, and includes some undocumented hacks; all have been checked but some may not work in your situation, so test before you decide to have a stack depend on them.
palette command is actually an XCMD built into the HyperCard application. It has two parameters:
palette "My Palette", "100,100" causes your palette to appear with its top left corner 100 pixels from the left edge and 100 pixels from the top edge of the card window.
palette command sends an
openPalette message when a palette opens, a
closePalette message when it's closed (by HyperTalk or the close box). Both messages carry two parameters: the palette's name and its window ID.
You can use this information to track the opening and closing of palettes. For example, suppose your stack has a menu item to show or hide your navigation palette. You can adjust the name of the menu item depending on whether the palette is visible or not:
on closePalette theName, theID if theName is "My Navigator" then set the name of menuItem "Hide Navigation Controls" ¬ of menu "Options" to "Show Navigation Controls" else pass closePalette end closePalette on openPalette theName, theID if theName is "My Navigator" then set the name of menuItem "Show Navigation Controls" ¬ of menu "Options" to "Hide Navigation Controls" else pass openPalette end openPalette
Palette windows have a number of properties you can get and set. Like all HyperCard windows, palette windows have size and location properties:
Each window also has a name and ID; you can have two windows with the same name, but never the same ID, so you can use the descriptor "window ID ID-number" to uniquely identify a palette window. (You get the ID from the
openPalette message HyperCard sends when the palette is created.)
There are three properties that are unique to palette windows:
hilitedButtonis the number of the button that is currently highlighted. If no button is highlighted, this property is 0 (zero). If the palette only allows transitory highlights (while the button is actually being pressed), the highlightedButton is always -1. You can use this property to set the highlighting in a navigation palette as follows:
on openCard if there is a window "My Palette" then set the hilitedButton of window "My Palette" ¬ to the number of this card end openCardThis example assumes you've set up the palette so each button corresponds to the card with the same number. For more complex situations, or where a navigation button leads to a section containing more than one card, you may want to write a custom function to relate cards to palette buttons.
commandsis the list of commands sent by each button in the palette. Commands are separated by returns. You can get this property, but not set it.
buttonCountof a palette is the number of buttons that palette has. You can get this property, but not set it.
HyperCard stores the information for a palette in a resource of type PLTE in the stack containing the palette. You can download a ResEdit template (1K) for the PLTE resource.
To use the template, open the document with ResEdit (632K) or another resource editor. In it, you'll find a resource of type TMPL (a template). Paste this resource into either ResEdit, or the ResEdit Preferences file inside your Preferences folder in the System Folder. (ResEdit is a little snarky about allowing modification of its preferences file while it's running, so you may have to make a copy, paste into that, then replace the original with the copy after quitting ResEdit.)
From now on, you can open a PLTE resource within ResEdit and see a reasonable display of the palette contents, instead of the hash of raw hex numbers that ResEdit displays when you open a resource of a type it doesn't understand. This means you can see and modify various attributes of palettes, even after they're created.
Each PLTE resource has several palette attributes, followed by the attributes of each button in the palette. The palette attributes are the version, WDEF, type, hilite mode, PICT ID, and offsets.
This is the palette version. It should always be 0 (zero); the
palette XCMD cannot understand other versions.
This is the window definition code used for the palette resource. Window definition codes are based on a WDEF resource which provides the code needed to draw the window. (This can be a little confusing, since the term WDEF is used for both the palette attribute and the WDEF resource. You get a WDEF number by multiplying the WDEF's resource ID by 16, then adding an optional attribute code.)
The resource ID of HyperCard's windoid WDEF is 128; the WDEF number is therefore 128 * 16 = 2048, plus a variation code between 0 and 15, and so the possible values you can type into the "WDEF" box are 2048 to 2063.
The bits of the variation code are:
Bits 0, 2, and 3 don't seem to be useful; if bit 3 is turned on, the zoom box appears but does nothing. The grow box never appears regardless of the setting of bit 2. (This is apparently because the PLTE XCMD does not implement any behavior for these bits. The list above describes the standard Mac behavior for the variation code bits, but since PLTE ignores them, they're not used for their standard purpose, nor for anything else. Thanks to Jens Ayton for this information.)
In practice, two settings make sense for this attribute: 2052 (for an untitled palette) and 2054 (for a palette with a title).
Theoretically, you could write your own WDEF resource and use it instead. You can also use other WDEFs built into HyperCard or the system (although these often produce user-interface results that are not appropriate for palettes). Some settings you can use for the WDEF attribute are:
Produces a dialog-box window with extra white space between the picture and the window borders. When the window is open, it locks out switching to other applications. (The attribute is based on the WDEF 0 resource in the System file.)
Produces a plain box. (The attribute is based on the WDEF 0 resource in the System file.)
Produces a box with a drop shadow. (The attribute is based on the WDEF 0 resource in the System file.)
Produces a window with a close box and normal title bar. (The attribute is based on the WDEF 0 resource in the System file.)
Produces a window with a close box, black title bar, and rounded corners. This window type is usually used for desk accessories. (The attribute uses the WDEF 1 resource, which is in either ROM or the System file, depending.)
Produces a palette window with a title bar in 9-point Geneva, where a setting of 2054 uses 12-point Chicago. (The attribute uses the WDEF 124 resource, which is in the System file in later system versions.)
Produces a palette window with the title bar running down the left edge instead of along the top. (Also uses WDEF 124.)
Produces a movable modal window with a title bar and no close box. This window style has a white border between the palette's background picture and the window edges. (The attribute uses the WDEF 129 resource, which is in the HyperCard application.)
Transitory highlighting is best for action buttons. Persistent highlighting, on the other hand, is best for buttons that show a status or mode. For example, in a palette whose buttons go to different sections of the stack, persistent highlighting lets the palette display which section the user is in, as well as navigate from section to section.
This is the way highlighting is shown. There are two possible values:
Frame highlighting is more subtle, but it may be hard to see, especially if your palette already has framed buttons.
This is the ID of the PICT resource where the palette's background picture is stored. If a PICT with this ID can't be found, the
palette command tries to find a PICT resource with the same ID, then the same name, as the PLTE resource.
The Palette Maker in the Power Tools stack only creates black and white palette backgrounds. However, you can replace the PICT resource thus created with a color version. Open the PICT resource, copy it, paste it into a color paint program, and add color. Make sure not to change the size while coloring your PICT resource. When you're done, copy the picture and paste it into the PICT resource.
The actual size of the palette is determined by the PICT size, not the PLTE size; it's possible to have palette buttons "offscreen" if they're outside the PICT's dimensions. On use for this capability is to place data in the scripts of the extra buttons, using the
commands property to get the data from these scripts. Another is to use the same PLTE to control different versions of a palette - for example, contracted and expanded palettes - by placing the PICT resources in different stacks and using the
start using and
stop using commands at strategic moments. (Thanks to James Parkin for this tip.)
Different palettes can use the same PICT resource at the same time.
These offsets are the vertical and horizontal distance from the top left corner of the QuickDraw gWorld used to draw the palette. That gWorld is set to the rectangle of the Palette Maker card used to create the palette, so the V Offset and H Offset is the location of the top left corner of the "Border Unit" button in the Palette Maker. (Thanks to Harvey Dutoff for noticing this.)
(I'm still confused about exactly what these offsets mean. Clues are welcomed.)
The button attributes follow the palette attributes in the PLTE resource window. For each button in the palette, these attributes include the button's position (Button Rect) and the HyperTalk executed when the user clicks the button (Button Msg).
You can change the position of a button if you want to change the underlying picture to match. Remember that palette buttons are invisible - the user's only cue about where the buttons are comes from the picture - so don't change button positions without changing the picture.
The Palette Maker card in the Power Tools stack, which most people use to create palettes, only lets you include one line of HyperTalk in each button. However, it turns out that the Button Msg field accepts more than one line of HyperTalk - up to 255 characters. After you create a palette in Palette Maker, you can use ResEdit to open the PLTE resource and type in multiple lines, including if/then and repeat constructs, and these lines will be executed when you click the button. You won't be able to use long or very complex handlers, but 255 characters is enough for quite a bit of mischief.
The Chiclette XCMD, written by Jean-Marc Astesana, offers features over and above the built-in PLTE XCMD in HyperCard:
Chiclette is free for noncommercial use.