1 LISP LIBRARY PACKAGES MANUAL 1 LISP LIBRARY PACKAGES MANUAL FREE MENU 1 USER INTERFACE 1 FREE MENU 6 Free Menus are powerful and flexible menus that are useful for applications that need menus with different types of items, including command items, state items, and editable items. It is easy both to create and to manipulate Free Menus. 2 Free Menu Items 1 A Free Menu is a window with items in it. Free Menu items can be thought of as objects, each item having its own particular properties. Each object is a FREEMENUITEM data type, which has information about the item, such as its label, its type, and the function to call when it is selected. The following Free Menu item types are available, and other types are easily implemented. The properties mentioned below, such as SELECTEDFN or ID, are described further in the section Free Menu Item Properties MOMENTARY items are like command buttons. When the button is selected, its associated function is called. TOGGLE items are simple two-state buttons. When depressed the button is highlighted, and it stays that way until pressed again. The states of a toggle button are T and NIL, initially NIL. 3STATE items rotate through NEUTRAL, T, and NIL states each time they are pressed. The NIL state is indicated by a diagonal line through the button, while T is highlighted, and NEUTRAL is normal. The default initial state is NEUTRAL. NWAY items provide a way to group any number of items together, in any format within the Free Menu. Only one item from each group can be selected at a time, and that item is highlighted to indicate so. NWAY groups are formed by creating a number of NWAY items with the same ID field. Pressing an item in the group with the left mouse button causes that item to become the selected item of the group. Pressing an item with the middle button causes the group to be deselected, leaving the state NIL. The main item is the first one declared in that group, and its SELECTEDFN is called whenever any item in the group is selected, unless that item has its own particular SELECTEDFN. The default initial state is NIL. NCHOOSE items are similar to NWAY items, but the new state is selected from a pop-up menu when the item is pressed. There is no implicit way to turn an NCHOOSE item OFF.'' The possible values of the item are specified in a list of atoms, strings, or bit maps, as the value of the ITEMS property. The font of the ITEMS can be specified by the ITEMFONT property. The title of the pop-up menu will be the same as the item's LABEL, or can be specified by the ITEMTITLE property. EDIT items are textual items that can be edited. When the item is pressed, an edit caret appears at that cursor position within the item, allowing inserting and deleting characters at that point. While editing, the left mouse button causes the caret to be moved to a new position. The right mouse button deletes from the caret to the cursor. Editing is stopped when another item is selected, or when the carriage return key or control-X is typed. Each EDIT item should have an ID specified, to be used when reading the state of the Free Menu, since the string being edited cannot distinguish one EDIT item from another. If a MAXWIDTH property is given, it specifies the maximum string width of the item after which input will be ignored. If the EDITSTOPFLG property is T, then the item's maximum width will be MAXWIDTH, or else the width of the item up to the right edge of the window. Thus reshaping the window can change the maximum size of an EDIT item. If the item has no MAXWIDTH or EDITSTOPFLG property, the item has no maximum size, and input is never restricted. Typing off the edge of the window will cause the window to scroll appropriately. EDITSTART items are useful for filling in templates and the like. Each EDITSTART item has one or more EDIT items associated with it. When the item is pressed, editing is turned on for each EDIT item, sequentially. The window will be scrolled if necessary to ensure that an EDIT item is visible in the window when editing starts on that item. The items to edit are specified as a list of the ID's of the desired items, as the value of the ITEMS property. If an ID is specified for an item that doesn't exist, it will be ignored. Note that the items to edit are looked for when the EDITSTART item is selected, not when the Free Menu is created. TITLE items serve two purposes. First, they simply provide a way of putting dummy text in a Free Menu, which does nothing when selected. Secondly, title items can be used as the base for new item types. The application can create new item types by specifying DOWNFN, HELDFN, MOVEDFN, and SELECTEDFN for a title item, making it behave as desired. 2 Making a Free Menu 1 There are two ways to make a Free Menu. Both involve writing a Free Menu description, which is then turned into the menu itself. Each Free Menu resides within a window and making a Free Menu returns the window that the menu lives in. That window can then be opened or attached, as desired. If the location of the window cannot be determined when the description is written, the window can be moved to the desired position before it is opened. When a Free Menu window is opened, it is automatically redisplayed with the current Free Menu contents. Explicit Formatting 1 A complete Free Menu description is a list containing a description of each item in the menu and an optional set of window properties to control the window's appearance. Each item description is a list of properties and values, in property list format. The window properties are specified in a list whose first element is the atom WINDOWPROPS, followed by property names and values. To make a Free Menu from an explicit description, use the function FM.MAKEMENU. Here is an example Free Menu description: ((TYPE TITLE LABEL Command: LEFT 0 BOTTOM 30 FONT (MODERN 10 BOLD)) (LABEL Load LEFT 60 BOTTOM 30 SELECTEDFN DOLOAD) (LABEL Delete LEFT 100 BOTTOM 30 SELECTEDFN DODELETE) (TYPE TITLE LABEL Device: FONT (MODERN 10 BOLD) LEFT 0 BOTTOM 15) (TYPE NWAY ID DEVICE LABEL PUP LEFT 60 BOTTOM 15 SELECTEDFN CHANGEDEVICE) (TYPE NWAY ID DEVICE LABEL NS LEFT 90 BOTTOM 15) (TYPE NWAY ID DEVICE LABEL FLOPPY LEFT 110 BOTTOM 15) (TYPE NWAY ID DEVICE LABEL DSK LEFT 160 BOTTOM 15) (TYPE EDITSTART LABEL Filename: LEFT 0 BOTTOM 0 FONT (MODERN 10 BOLD) ITEMS (FILENAME)) (TYPE EDIT ID FILENAME LABEL "" LEFT 60 BOTTOM 0) (WINDOWPROPS TITLE "Example Free Menu" LEFT 100 BOTTOM 200)) which will produce the following Free Menu: ;?gIy:mz%Ŷmm0VmmVi7Em8e0@ x0@ D 0@pDp!LJz@`D""mm@ D#mm@ D"mm@`D""Hmn|pxp!x 8 ǀD  D HD  D@Hg6DQ D@FmٶxP@ DAo@2  DHـ@2  DHLJ@q>86Ƕ6s?`Ƕc6`6o66{66{o6`` Automatic Formatting 1 It can be very difficult to figure out where of each item should appear in the window when you are writing the description, so Free Menus may also be described by rows. This type of description consists of a list of Free Menu window properties and row descriptions. A row description is simply a list of item descriptions, in the order that they should appear, left to right. These item descriptions do not have LEFT and BOTTOM properties. The function FM.FORMATMENU formats a row description and returns a Free Menu window. For example, the same Free Menu could be described: (((TYPE TITLE LABEL Command: FONT (MODERN 10 BOLD)) (LABEL Load SELECTEDFN DOLOAD) (LABEL Delete SELECTEDFN DODELETE)) ((TYPE TITLE LABEL Device: FONT (MODERN 10 BOLD)) (TYPE NWAY ID DEVICE LABEL PUP SELECTEDFN CHANGEDEVICE) (TYPE NWAY ID DEVICE LABEL NS (TYPE NWAY ID DEVICE LABEL FLOPPY) (TYPE NWAY ID DEVICE LABEL DSK)) ((TYPE EDITSTART LABEL Filename: FONT (MODERN 10 BOLD) ITEMS (FILENAME)) (TYPE EDIT ID FILENAME LABEL "")) (WINDOWPROPS TITLE "Example Free Menu" LEFT 100 BOTTOM 200)) and the Free Menu would look like: 9?gIy:mz%Ŷmm0VmmVi7Em8e 0x 0D  08hDp!LJ z"D"" mm"<D# mm"DD" mm"DD""H mn@q@Èǀ"D2D @$@$I "D2D @"$J g6"D*0<@"# mٶ"x* @ o"@&D @$I ـ"@&D @$HLJ@"8 |qÈ 6 Ƕ  6s?` Ƕc6` 6o6 6{6 6{o6` ` Free Menu Window Properties 1 The following Free Menu window properties may be specified: TITLE: The title of the Free Menu will appear as a window title. Default is NIL (no title). BORDER: The number of bits to appear in the border of the Free Menu window. Default is the value of WBorder. LEFT: The initial left position of the Free Menu window on the screen. Default is zero. BOTTOM: The initial bottom position of the Free Menu window on the screen. Default is zero. Free Menu Item Descriptions 1 None of the property values in an item description are evaluated. When constructing Free Menu descriptions that incorporate evaluated expressions, for example labels that are bit maps, it is helpful to use the backquote construct. For example, if the value of the variable MYBITMAP is a bit map, then `(LABEL ,MYBITMAP LEFT 10 BOTTOM 15 TYPE TOGGLE) would create an item description incorporating the value of MYBITMAP as its label. Free Menu Item Properties 1 These are the basic properties of each item. LABEL: An atom, string, or bit map. Bit maps are always copied, so that the original won't be changed. This property must be specified for every item. ID: May be used to specify a unique identifier for this item, but is not necessary. See FM.ITEMFROMID, below. This field is used for grouping NWAY and EDITSTART items. LEFT and BOTTOM: The location in window coordinates of the lower-left corner of this item. These properties may be left out if Automatic Formatting is used. TYPE: The type of the item. Choose from one of the Free Menu Item type keywords MOMENTARY, TOGGLE, 3STATE, NWAY, NCHOOSE, EDITSTART, OR TITLE. The default is MOMENTARY. FONT: The font that the item will appear in. The default is the value of DEFAULTFONT. Fonts are specified by a list of FAMILY, SIZE, and FACE. For example, FONT (HELVETICA 10 STANDARD) or FONT (CLASSIC 8 MIR). MESSAGE: A message that will be printed in the prompt window if a mouse button is held down over this item for MENUHELDWAIT milliseconds. The default is a message appropriate to the type of the item. STATE: The initial state of TOGGLE, 3STATE, or NCHOOSE items. The state of an NWAY group may be initialized after the Free Menu is created, using the function FM.CHANGESTATE. The following properties provide a way for application functions to be called under certain mouse events. These functions are called with the ITEM, the WINDOW, and the BUTTONS depressed as arguments. These application functions do not interfere with any Free Menu system functions that take care of handling the different item types. In each case, though, the application function is called after the system function. The default for all of these functions is NIL. SELECTEDFN: The name of the function to be called when this item is selected. DOWNFN: The name of the function to be called when a mouse button goes down over this item, or when the mouse moves over the item with buttons depressed. HELDFN: The name of a function to be called repeatedly while the mouse is held down over this item. MOVEDFN: The name of the function to be called when the mouse moves off this item with buttons still depressed. The following properties are only applicable to certain types of items: ITEMS: Used to specify the choices for an NCHOOSE item, and the list of the ID's of the items to edit for an EDITSTART item. ITEMFONT: Specifies the font of the choices for an NCHOOSE item. ITEMTITLE: Specifies the title of the pop-up menu for an NCHOOSE item. MAXWIDTH: The maximum allowable string width of an EDIT item. EDITSTOPFLG: A flag for EDIT items, that when set to T causes input to be ignored after the string reaches the right edge of the window. All other properties given in an item descriptor will be treated as user properties, and will be saved on the USERDATA list of the item. 2 Using Free Menus 1 When a Free Menu is created, the items in the menu are stored in a list, in the order that they are described, as the value of the window's FM.ITEMS property. Following are functions for creating, accessing, and manipulating Free Menus: (FM.MAKEMENU DESCRIPTION) [Function] Creates a Free Menu window from a complete description, returning the window. This function will return quickly unless new display fonts have to be created. See the example above under Explicit Formatting. (FM.FORMATMENU DESCRIPTION) [Function] This function is very similar to FM.MAKEMENU, except that the item layout formatting is done automatically, so the user doesn't have to specify a left and bottom location for each item. This is a useful way to generate Free Menus programmatically, where the items to be put in the menu may vary. FM.FORMATMENU takes a description similar to a complete Free Menu description, except that it is broken down into rows, where each row is a list of item descriptions, and each item description doesn't contain LEFT or BOTTOM fields. The items will be formatted from top to bottom, left to right, in the order they appear in the description. See the example above under Automatic formatting. (FM.REDISPLAYMENU WINDOW) [Function] Redisplays the entire Free Menu in its window, if the window is open. (FM.REDISPLAYITEM ITEM WINDOW) [Function] Redisplays a particular Free Menu item in its window, if the window is open. (FM.FIXSHAPE WINDOW ALWAYSFLG) [Function] Reshapes the window to its full extent, leaving the lower-left corner unmoved. Unless ALWAYSFLG is T, the window will only be increased in size as a result of fixing the shape. (FM.EDITP WINDOW) [Function] If an item is in the process of being edited in the Free Menu WINDOW, that item is returned. Otherwise, NIL is returned. (FM.READSTATE WINDOW) [Function] This function examines all the items in the Free Menu. For items that have a state, (TOGGLE, 3STATE, NWAY, NCHOOSE, EDIT), the item's ID (or LABEL if there is no ID) and its current state are collected into a list in property list format, accessible with LISTGET. For EDIT items, the current state is the string being edited. Note that labels and ID's are case dependent. For the example Free Menu above, this function might return: (DEVICE DSK FILENAME "dandy") (FM.ITEMPROP ITEM PROP {VALUE}) [Macro] Similar to WINDOWPROP, this macro provides an easy access to the fields of a Free Menu Item. VALUE is optional, and if given will be used as the new value for that PROP, and the old value will be returned. When a call to FM.ITEMPROP is compiled, if the PROP is known, e.g., quoted, the macro figures out what field to access, and the appropriate expression is compiled. This is much more efficient than selecting the item property at run time. However, if the PROP is not known at compile time, the function FM.ITEMPROP, which goes through the necessary selection, is compiled. The following fields are readable and settable with FM.ITEMPROP: LABEL [FreeMenuItem Property] A string, atom, or bit map that the item looks like on the screen. ID [FreeMenuItem Property] A unique identifying field for each item, or group of items. STATE [FreeMenuItem Property] The current state of the item, as described under Item Types. FONT [FreeMenuItem Property] A FONTDESCRIPTOR. The font that the label appears in. This field is not meaningful for bit map labels. BITMAP [FreeMenuItem Property] The actual bit map that is displayed on the screen. REGION [FreeMenuItem Property] The region in the coordinates of the Free Menu window that the item is displayed in. This region is also used as the mouse-sensitive region for this item. MESSAGE [FreeMenuItem Property] A message that is printed in the prompt window if a mouse button is held down over this item for MENUHELDWAIT milliseconds. ITEMPTR [FreeMenuItem Property] A field that is used by NWAY and EDITSTART items to point to other items in the same Free Menu, for grouping purposes. SYSDOWNFN, SYSMOVEDFN, SYSSELECTEDFN [FreeMenuItem Properties] These fields hold the names of the functions that the Free Menu system uses for keeping track of state items, and for bookkeeping when items are selected, etc. The application should use the corresponding fields below. DOWNFN, HELDFN, MOVEDFN, SELECTEDFN [FreeMenuItem Properties] These fields hold the names of the application's functions that are called when mouse events occur on this item. The application may also keep information on properties not described above, in which case the property/value pair will be put on the USERDATA list of the item. The following properties may only be read, not set. An attempt to change the value of these properties will cause an error (at compile time if the property is known): TYPE [Read Only FreeMenuItem Property] A key word that describes the type of the item. One of MOMENTARY, TOGGLE, 3STATE, NWAY, NCHOOSE, EDIT, EDITSTART, and TITLE. USERDATA [Read Only FreeMenuItem Property] A list of other information about the item, in property list format. Use FM.ITEMPROP with a property name other than one of those above in order to read and set properties on this list. (FM.CHANGESTATE ITEM WINDOW NEWSTATE) [Function] Changes the state of ITEM programmatically, and returns the old state. This function is only applicable to TOGGLE, 3STATE, NWAY, NCHOOSE, and EDIT items. For TOGGLE items NEWSTATE is disregarded, and the current state is simply toggled. For 3STATE items, NEWSTATE may be one of NEUTRAL, T, or NIL. For NWAY items, NEWSTATE is treated as a flag; if NIL, the state of the group becomes ITEM; if T, the group is deselected, leaving the state NIL. For NCHOOSE items, NEWSTATE may be any of the subitems allowed for that item. For EDIT items, the label of the item is changed to NEWSTATE, as long as the Free Menu isn't busy editing an item. (FM.CHANGELABEL ITEM WINDOW NEWLABEL) [Function] This function allows an item's label to be changed after the Free Menu has been created. It works for any type of item. If the window is open, the item will be redisplayed with its new appearance. Changing the label of an EDIT item while being edited will produce confused results, but will work fine while the item is dormant. NEWLABEL can be an atom, a string, or a bit map (except for EDIT items). (FM.ITEMFROMID WINDOW ID) [Function] Gets a handle on an item from its ID property. This function searches for an item whose ID field matches, or secondly whose LABEL field matches. (FM.WHICHITEM WINDOW POSorX Y) [Function] Gets a handle on an item from its known location within the window. If WINDOW is NIL, (WHICHW) is used, and if POSorX is NIL, the current cursor location is used. (FM.EDITITEM ITEM WINDOW) [Function] Starts editing at the beginning of ITEM, as long as the WINDOW is open. Any item can be edited, but non-EDIT items are not set up to accommodate a change in size of ITEM. This function will most likely be useful for starting editing of an EDIT item that is currently the null string. (FM.SHADEITEM ITEM WINDOW SHADE) [Function] Paints SHADE on top of ITEM. Only the screen is changed, so redisplaying the window will return the item to its original shade. SHADE can also be a bit map, in which case it is XORed with the item's bit map onto the screen. This allows items to be shaded with a mask. This function has no effect if the window is closed. (FM.SHADEITEMBM ITEM SHADE) [Function] This is a permanent version of FM.SHADEITEM. SHADE is painted (or XORed if it is a bit map) onto ITEM's bit map. Shading of an EDIT or NCHOOSE item's bit map will produce weird results, as any new characters (or values) will appear without the new shading. (LIST ((PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC ) STARTINGPAGE# 94) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD LEFT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC )) (54 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGV) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE VERSOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 618) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD LEFT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (559 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD LEFT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (54 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGV) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE VERSOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL)))))/T(<<(**... ) T.)T()2T)T( /T/TB PAGEHEADING VERSOHEADB PAGEHEADING RECTOHEADA PAGEHEADINGFOOTINGVA PAGEHEADINGFOOTINGR(TERMINAL MODERNMODERNTERMINALMODERN MODERN MODERN MODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN   HRULE.GETFNMODERN  HRULE.GETFNMODERN   HRULE.GETFNMODERN   HRULE.GETFNMODERN   HRULE.GETFNMODERN  l       ]  HRULE.GETFNMODERN   HRULE.GETFNMODERN +   HRULE.GETFNMODERN  D27CL274Y3> , BMOBJ.GETFN3   HRULE.GETFNMODERN  E4!&3: %#J$> #d BMOBJ.GETFN3   HRULE.GETFNMODERN  < ^ o Z ^   HRULE.GETFNMODERN  2 2 S  HRULE.GETFNMODERN  -        F O  h q H ~ B H ?    HRULE.GETFNMODERN   HRULE.GETFNMODERN      F M   W R  >6 )  _AV#C=>i4 | y(%q'~+  4= 7 LA  !57 H!.  " Zt  g  .-Vz