menu-item

The class of menu-item objects. A menu-item is created by calling make-instance, specifying the menu-item class or some subclass of it.

Here is a list of the properties of a menu-item; each can be specified at creation time by passing the corresponding keyword initarg to make-instance:

• name: a symbol naming this menu-item, which could be used later with find-named-object to find the menu-item from its name.
• title: a string to display on the menu for this item. Place a tilde (~) in the string before a particular character to use that character as a menu access key, which will appear underlined in the menu. Alternately, the title may be a pixmap object (or pixmap handle) in order to display an image rather than a string in the menu.
• value: an arbitrary value to be processed when this menu-item is chosen. When the menu-item is chosen, this value is passed to handle-menu-selection. Unless an application overrides the default handle-menu-selection method (typically not necessary), the default method simply passes the value to the on-click function of the menu that this menu-item is on. The default on-click function, default-menu-on-click, simply returns the value. This default on-click function is often suitable for a pop-up-menu, causing this menu-item value to be returned from the call to pop-up-menu. For a pull-down-menu, the menu should always be given some other on-click function that performs the command indicated by this menu-item value (because the application will not be able to capture the value returned by default-menu-on-click and therefore the default function effectively does nothing).
• event-synonym: a symbol or list of symbols denoting the keyboard shortcut for this menu-item. When this menu-item is on a menu-bar, the user can invoke the menu-item by typing the event-synonym in the window that the menu-bar is on. See event-synonym for examples.
• help-string: an arbitrary string to explain what this menu-item does. Built-in menu-item-highlighted methods will show this string in the status-bar of the window that owns the menu when the user highlights this menu-item. (For a pop-up menu, this window is the one that was passed as the stream argument to the function pop-up-menu, if any.)
• cluster: an arbitrary symbol to place this menu-item in a group with other contiguous items on the same menu that specify the same cluster value. The item will display a dot when selected, and selecting one item in the cluster deselects the others.
• allow-during-modality: if true, then the event-synonym of the menu-item may still be used to invoke the item when there is a modal dialog present. The default is nil.
• available: if nil, then the menu-item will be grayed out and unavailable to the user. The default is true.
• selected: if true, then the menu-item will display a check mark, or a dot if it is in a cluster. The default is nil.
• checkable: on GTK, this must be true in order to use the selected property to display check marks. On Windows it has no effect.
• unchecked-pixmap: either a pixmap to be displayed on the left side of the menu-item when the item is not checked, or nil to display no pixmap. The default is nil. Used only on the Windows platform.
• checked-pixmap: either a pixmap to be displayed on the left side of the menu-item when the item is checked, or nil to display a default check mark pixmap. The default is nil. Used only on the Windows platform.

Here is a typical menu-item creation form:

(make-instance 'menu-item
  :name :help
  :title "~Help"
  :value 'show-help
  :help-string "Shows help on the selected thing."
  :event-synonym 'vk-f1)

A menu-item may be added to a menu when the menu is created by calling open-menu, or added later by calling add-to-menu.

See About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

See also the menu chapter in the IDE User Guide.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.