Innermost Secrets
of HyperCard Palettes

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.

The `palette` command

The palette command is actually an XCMD built into the HyperCard application. It has two parameters:

name
The name of the PLTE resource holding this palette. If the name contains spaces, it must be enclosed in quotes. This name becomes the name of the palette window, and you can use it wherever you use a window reference - in open, close, hide, and show commands, and in setting the window coordinates.
topLeft
The top left coordinate of the location (relative to the top left corner of the current card) where you want the palette to appear. This parameter is optional; if you leave it out, the palette appears at 10,20.

The command 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.

The 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 window properties

Palette windows have a number of properties you can get and set. Like all HyperCard windows, palette windows have size and location properties: location, rect, top, left, bottom, right, topLeft, bottomRight.

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:

hilitedButton
The hilitedButton is 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 openCard
```
This 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.
commands
The commands is 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.
buttonCount
The buttonCount of a palette is the number of buttons that palette has. You can get this property, but not set it.

The PLTE resource template

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.)

[screenshot of PLTE resource in 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.

The parts of the PLTE resource

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.

Version

This is the palette version. It should always be 0 (zero); the palette XCMD cannot understand other versions.

WDEF

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:

Bit 0: disables title-bar dimming (but turning this bit off only seems to affect the palette when a modal dialog comes up, and only until the next time you click the palette)
Bit 1: title bar with the palette's name
Bit 2: grow box
Bit 3: zoom box

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:

1:
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.)

2:
Produces a plain box. (The attribute is based on the WDEF 0 resource in the System file.)

3:
Produces a box with a drop shadow. (The attribute is based on the WDEF 0 resource in the System file.)

4:
Produces a window with a close box and normal title bar. (The attribute is based on the WDEF 0 resource in the System file.)

16:
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.)

1984:
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.)

1993:
Produces a palette window with the title bar running down the left edge instead of along the top. (Also uses WDEF 124.)

2064:
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.)

Type

This attribute controls whether buttons retain their highlighting, or highlight only while being clicked.

-1: transitory highlighting, which goes away when the user releases the mouse button.
0: persistent highlighting, which remains even after the user has clicked.
all other numbers: persistent highlighting, with the numbered button already highlighted when the palette first opens.

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.

Hilite Mode

This is the way highlighting is shown. There are two possible values:

0 means buttons are reverse-highlighted: black reverses to white, white reverses to black, and colors (if the palette uses a color PICT resource) are reversed to their opposites in the system palette.
1 means buttons are framed with a reversed-color outline when highlighted; only the outline of the button is reversed, instead of the entire button area.

Frame highlighting is more subtle, but it may be hard to see, especially if your palette already has framed buttons.

PICT ID

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.

V Offset and H Offset

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.)

Button Attributes

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.

Beyond the Palette Command

The Chiclette XCMD, written by Jean-Marc Astesana, offers features over and above the built-in PLTE XCMD in HyperCard:

Buttons send mouseDown, mouseStillDown, and mouseUp messages
You can select a cursor resource to be used when the mouse is within the palette
The appearance of buttons (text font, size, and style; icon; disabled state; button style) can be manipulated "on the fly" by changing their properties.

Chiclette is free for noncommercial use.

Jeanne A. E. DeVoto jaed@jaedworks.com

Innermost Secrets of HyperCard Palettes

The palette command