Palette Handler
 
The free Common Lisp software is provided strictly on an as-is basis. It is completely unsupported. NoteHeads neither assumes any responsibility for this free software, nor for any results of the use of this free software, be they direct or indirect. The free software remains, at all times, the intellectual property of NoteHeads
     Download the Utility in BinHex format
  Description
This utility implements Macintosh floating palettes with optional auto-sizing and re-sizing, triple-action function, optional palette menu(s), etc.The triple-action makes it possible to define many different types of tool behaviour, from simple tool selection to more involved toggle states. Palette items can be made to behave like radio buttons, checkboxes or normal buttons or any combination thereof.

Two types of palette items are defined: text items and SICN items. You can easily add more.
All palette items may be grouped into clusters and given radio button, toggled or momentary action. You can let the palette position its subviews automatically for you if you wish, but you can also specify each individual subview's position and size explicitly.
Documentation
The class PALETTE defines a windoid data type in which to put palette items. It takes all initargs that windoids take, with the following additions:

• :COLUMNS If non-NIL, the palette will be auto-sized to contain the indicated number of item columns. The sizes of the individual items/subviews will be taken into account when ordering them. When :COLUMNS is non-NIL, the positions of subviews are disregarded and may be omitted entirely. (SET-COLUMNS palette columns) may be used to resize a palette to a new number of columns. If NIL, the :VIEW-SIZE argument will be used to provide the size of the palette. Defaults to NIL.

• :OVERLAP Used when :COLUMNS is non-NIL. Indicates the number of pixels that items should overlap. Normally 0 for text items and 1 for framed items such as SICNs. Defaults to 0.

• :SHOW-ON-MENU If non-NIL, a string giving the name of a menu to which the name of the palette will be added (as given by :WINDOW-TITLE). The menu will be created if not already present on the menu bar. The menu item toggles the visibility of the palette. A tick mark indicates that a palette is visible. Palettes normally do not have a close box, but the :CLOSE-BOX-P argument may be used to provide one. When a palette is closed, it is removed from the menu. (The menu will not be removed when the last palette belonging to it is closed.) The menu may be any menu, but if it has to be created, two standard menu items are added: "Show all" and "Hide all". These two commands apply only to the palettes listed on the menu in question. Defaults to "Palettes".

The special variable *PALETTES* contains a list of all active palettes. It may be read, but should not be modified by the user.

The class PALETTE-ITEM defines the basic behaviour for palette items (though it is perfectly OK to put anything on a palette -- it need not be a PALETTE-ITEM). They are DIALOG-ITEMs and take all the usual initargs in addition to the following:

• :ACTION NIL or a symbol or function which is called when the item is clicked. (Note that the function is called when the mouse switch is pressed, not released, as with DIALOG-ITEM-ACTION-FUNCTION). This function is always called when the item is clicked, regardless of whether it is highlighted or not. The ACTION function is always called before the :ACTION-ON and :ACTION-OFF functions.

• :ACTION-ON NIL or a symbol or function which is called when the item becomes highlighted (selected). Clicking again on a highlighted item will not reinvoke the ACTION-ON function.

• :ACTION-OFF NIL or a symbol or function which is called when the item becomes unhighlighted (deselected). This may happen as a result of some other item becoming highlighted, or if the item is toggled.

• :HIGHLIGHTED T if the palette item is highlighted when the palette is created.

• :TOGGLE T if the palette item can be toggled on and off. If NIL, it is either momentary in action, or is only turned off by other items turning on.

• :MOMENTARY T if the menu item is briefly selected when clicked, then reverts back to its off state. (Momentary items do not use ACTION-ON or ACTION-OFF functions, only ACTION functions.)

• :CLUSTER Similar to radio buttons. When a palette item becomes highlighted due to a mouse click, ACTION-OFF functions are invoked for all highlighted palette items in the same cluster (unhighlighting them). All palettes, visible and invisible, are searched. This allows item clusters to be spread over several palettes. When all ACTION-OFF functions have been invoked, the ACTION of the clicked item is invoked, if any. Finally, the ACTION-ON function is invoked.

• :DIALOG-ITEM-TEXT the text to display for the palette item. It is drawn centered inside the view. Font, size and style may be specified in the usual manner.

The class PALETTE-SICN-ITEM is a specialization of PALETTE-ITEM. It displays a SICN (16x16 small b/w icon). The 16x16 SICNs are drawn in 22x22 boxes which can be framed. If they are, you will probably want to OVERLAP them by 1 to create a visually pleasing grid. PALETTE-SICN-ITEMS take the following additional initargs:

• :ID The SICN resource ID

• :INDEX The index of the individual SICN within the resource

• :FRAMED T if frame the SICN, NIL if no frame

Examples
There is an extended example in the source file "Palettes.lisp". The example requires a resource file, which is included with the archive. It is not needed for normal operation of the palette utility.
Acknowledgements
The SICN palette items uses some code from Luke Hohmann's SICN routines, with extensive modifications and added functionality.