source files: xchc.[ch]
(SEND <xchc> :GET <:PROPERTY> [<default-value>]) (SEND <xchc> :SET <:PROPERTY> <value>) (SEND <xchc> :REMPROP <:PROPERTY>) (SEND <xchc> :PROPERTY-LIST-LENGTH) (SEND <xchc> :PROPERTY-LIST-NTH <fix:index> [<default-value>])
As usual, :GET/:SET are used to manipulate both values with special significance to the MENU instance, and propertylist values passively stored for the benefit of the user.
If :GET does not find the requested property, it returns <default-value> if one was provided, otherwise signals an error.
Numeric properties may in general be supplied as float or ints indifferently. If NIL is provided where a numeric property was expected, nothing is done. (This is a feature, not a bug.)
:REMPROP removes the given property from the propertylist, returning (:PROPERTY . <val>) if the property was successfully removed, else NIL.
:PROPERTY-LIST-LENGTH and :PROPERTY-LIST-NTH are provided to allow iteration through all properties on thing, the latter's <default-value> works just as on :GET.
:LABEL is a lisp string constituting a title for the menu.
:LABEL-FONT and :CHOICE-FONT are integers from 0 to 11 inclusive indentifying the hershey font in which to display the label and the choices (respectively) of the menu.
:CHOICE is the currently selected option on the menu (0 -> N-1).
:CHOICES is the complete set of choice strings/lists originally supplied. DO NOT MODIFY THIS LIST.
:CHOSEN-STRING is the currently selected option on the menu, as a string, or a list headed by a string. This is a read-only property for the benefit of hook functions.
:MAX-VISIBLE-CHOICES is the maximum number of choices to present to the user at a time -- further choices can be accessed by paging UP and DOWN through the list. Current default 40.
:VERTICAL-MARGIN is the spacing between the menu holes, expressed as a fraction of the total width of the widget.
:HORIZONTAL-MARGIN is the spacing between the menu holes and the sides of the widget, expressed as a fraction of the total width of the widget.
:CHOICE-HEIGHT of each choice on the menu, expressed as a fraction of the total width of the widget. If this is set to zero, the widget will lack a visible menu.
:UPDOWN-HEIGHT is the height of the bottoms of the slots containing the UP and DOWN labels (present when there are more choice strings than visible choice slots), expressed as a fraction of the total width of the widget.
:LABEL-HEIGHT is the height of the bottom of the slot containing the label and value, expressed as a fraction of the total width of the widget. If this is set to zero, the widget will lack visible label and value.
:FRUSTUM-DEPTH is the depth of the main frustum, expressed as a fraction of the total width of the widget.
:CHOICE-DEPTH is the depth of the slot containing the choices, expressed as a fraction of the total width of the widget.
:UPDOWN-DEPTH is the depth of the slot containing the UP and DOWN selections, expressed as a fraction of the total width of the widget.
:LABEL-DEPTH is the depth of the slot containing the label, expressed as a fraction of the total width of the widget.
Class-menu instances tend to silently ignore or modify values for the above quantities if they consider them silly.
:CHANGE-HOOK function(s) will be called whenever the currently selected choice on the menu changes for any reason. EXCEPTION: If the value of a menu is changed by a change-hook, the change-hook functions are *not* re-invoked. This is to prevent infinite recursions in the common case of a changehook wishing to adjust the menu value.
When change-hook functions are invoked, XG.3D.GUI-CURRENT-WIDGET is set to the current menu object: :GET may then be used to read the currently selected :CHOICE from it. This is the normal way of having a menu control something.
The remaining hooks are primarily for specialized needs -- if you want to highlight an object while it is being controlled, you may do so with appropriate click hooks, for example.
If a :DOWN-CLICK-HOOK, :DRAG-HOOK, or :UPCLICK-HOOK is provided, they will be invoked whenever the user downclicks (respectively, drags or upclicks) the menu proper (as opposed to the body, label or limit fields).