A Menu is a dialog item that allows the user the select one or more values from a list. In its functionality it is similar to a list_browser object. However, a list_browser is meant to select from a dynamically generated list that may be large, while a menu is meant to select from a small number of alternatives that is generally static.
Class menu defines a
large number of options that determine both the layout of the items, the
feedback provided for the selected item, and whether or not one or more
items may be selected at the same time. For convenience, there is a
method called menu->kind
that allows you to select some common configurations with a single
message.
toggled menu_item has dialog_item<->message
not equal to @default,
this message is executed with:
@receiver The menu @arg1 The menu_item @arg2 New value of menu_item <-selected@arg3 Equivalent to @event
If the message of the menu_item is @default, the message associated with the menu is executed. The arguments are:
@receiver The menu @arg1 menu_item <-value@arg2 New value of menu_item <-selected@arg3 Equivalent to @event
toggled menu_item has dialog_item<->message
not equal to @default,
this message is executed with:
@receiver The menu @arg1 menu_item <-value@arg2 Equivalent to @event
If the message of the menu_item is @default, the message associated with the menu is executed. The arguments are:
@receiver The menu @arg1 The menu <-selection@arg2 Equivalent to @event
A menu consists of a label and a list of items. The label is placed
in a box described by the area menu<-label_area.
The items are placed in a two-dimensional array, each in its own box.
These item boxes all have the same size (menu<-item_size).
The top-left-corner of the first item is at menu<-item_offset.
If menu<->layout
equals horizontal, the items are placed left-to-right. If menu<->layout
equals vertical, the items are placed top-to-bottom. The items are
spread over menu<-columns
columns. The following illustrates the placement of a menu with
horizontal layout, 2 columns and 5 items:
label item-1 item-2 item-3
item-4 item-5
Various parameters influence the final layout. menu<->gap
defines the horizontal and vertical space between the items. graphical<->pen
defines the thickness of the lines for the boxes drawn around the items.
menu<->border
defines the white space between the item and the box around it.
<-pen
is not zero. When graphical<-pen
equals 0, border is only an additional gap.
Defaults: The default is 1
|chain|function*<-selection
is restored by menu->restore. If the menu
has menu<-multiple_selection: @off
this is a single value, otherwise it is a chain of values.
The default value may also be a function
object. In this case
menu->restore evaluates this function and
uses the result to set the
menu<-selection.
<->multiple_selection
equals @off.
In this mode, only the selected item is displayed. Used to implement menu<->kind.
item(s). The thickness of
the line equals the pen of the menu plus 1.
item(s). Used to implement‘Menu menu->kind:
choice’. Note that inverting images gives strange results on
colour displays.
<-off_image
left of not-selected items and menu<-on_image
left of selected items. Used to implement menu->kindmarked or toggle`.
<->border
is between the item and its surrounding box, while menu<->gap
defines the distance between the surrounding boxes of adjacent items.
Menu?x + Menu?item_offset?x + X*(Menu?item_size?w + Menu?gap?w).
and similar for the y-coordinate.
<-kind
provides the argument of the latest menu->kind
invocation. Note that the menu may look very different due to subsequent
style-parameters changed.
<->show_label
equals @on.
<-show_label
equals @on.<-columns
is greater than 1 and layout is horizontal, the items are
placed in horizontal rows. If layout is vertical, the items
are placed in vertical columns.
<-on_image
and menu<-off_image
equal @nil and
the maximum width plus menu<-border
if one or both of the markers are defined.<->selected.
|{marked}*<->selected: @off.
When @nil, no
image is painted before the item.
|{marked}*<->selected: @on.
When @nil, no
image is painted before the item.
->feedback)
->feedback,
but the latter only inverts the item.
<-popup_image
equals @nil or
there is no item in the menu that has a dialog_item<->popup.
Otherwise it is the width of menu<-popup_image
plus
menu<-border.<-label_font
in the box determined by menu<-label_area.
Otherwise the label is invisible.<->font.
The latter is often used for font-selectors to display each item in the
font that will be selected.
object. Object
is either a menu_item or the value of a menu_item. Example:
?- new(M, menu(fill, marked)),
send_list(M, append,
[ @nil,
@grey12_image,
@grey25_image
]),
send(M, active_item, @grey12_image, @off).
send(Menu, active_all_items, @off).
Available for backward compatibility.
send(Menu, active_all_items, @on).
Available for backward compatibility.
For popup objects,
if the argument is the name gap, the last added item is
sent menu_item->end_group.
This inserts a group-separation line in the menu.
See also menu->members, menu->insert_before
and send_list/3.
<-modified
yields @on or always
equals @on and menu<-selection
succeeds, dialog_item<-message
is forwarded with the following arguments:
@receiver the menu @arg1 menu <-selection.
See also dialog->apply.
-border->selection.
->compute
recalculates various variables to speed-up redraw. These are menu<-label_area, menu<-item_offset, menu<-item_size, menu<-left_offset
and
menu<-right_offset.<->value
as the argument from the menu. Note that it is generally bad style to
change the contents of menu's. Normally items that should not be
activated in some context are made inactive.->event.
On failure it passes the event of @_button_gesture if graphical<-active
equals @on.
The real work is done by menu->execute.
<->selected
attribute of the item on which the event occurred.->label, menu->kind
and dialog_item->message.
See class menu for
details.
Defaults: The default dialog_item->label
is the classname of the menu (menu). The default
menu->kind
is determined by the resource menu.kind.
The default message is @default.
|menu_itembefore is a name, menu<-member
is used to translate it into a menu_item. If before is not
in the menu, the new item is menu->append’ed
to the menu.
See also menu->append
and menu->prepend.
<->active
equals @off.
<->active
equals @on.
->kind
method allows for the selection of some commonly occurring combinations
of menu parameters with a single method. The available options are:
<-on_image
and
menu<-off_image)
to indicate the selected item.
<-kind
cycle menus.
Bugs: Used to set the notion of menu<->current
in older versions. In its current definition it is not very useful. Use menu<-member
to test membership.
->clear
the menu and then use menu->append
to add each member of the chain to the menu. This implies chain may
contain both menu_item
objects and plain names.
See also menu_item<-convert
and send_list/3.
<-modified<-active
after the currently selected menu_item. When the currently selected item
is the last or there is no currently selected item, the first active
item is selected.
Used internally when menu<-show_selection_only
equals @on (menu<->kind:
cycle).
->active
on the indicated menu-item, making the indicated menu-item insensitive.
->off,
but activates the menu_item.
->append
and menu->insert_before.
<-selected
of item. Equivalent to sending the message directly to the menu_item
object, but type-conversion will convert a menu_item<-value
to the corresponding menu_item.|chain*If the argument is @nil,
this is equivalent to menu->clear_selection,
<-value.
Backward compatibility.
Bugs: Does not check menu<-multiple_selection,
resulting in an inconsistent menu when multiple object are selected in a
menu with menu<-multiple_selection:
@off.
<-status
of a menu is not used.<-menu
of all member items to @nil,
clears menu->members
and invokes menu->unlink
on the super-class.
<->condition not equal
to @nil, it
invokes the
menu_item<->condition
attribute, providing the following context information:
@receiver The menu_item @arg1 The argument (i .e. the context)
If the message evaluates successfully, the menu_item is activated, otherwise it is deactivated.
<-members
chain of menu_item
objects.event is an event that occurred on the menu, return
the menu_item on which are it occurred. May be used to redefine
event-handling of menu's.
Diagnostics: Fails silently when the event did not occur on a menu_item's area.
<->value
equal to the provided value and return this.
Diagnostics: Fails silently on failure.
Bugs: For backward compatibility, if there is no item with menu_item<-value
that matches the specification, it will return the first item for which
the conversion of the argument and menu_item<-value
to a name yield the same name.
->selection, menu->modified: @off
or menu->default.
See also menu->apply.
If menu->modified
is set to @on
the graphical<-device
will be informed using
dialog->modified_item.
See dialog_item->modified.
|chain*<-multiple_selection
equals @off,
returns menu_item<-value
of the selected menu_item. Otherwise it returns a new chain with the
menu<-value for each of the selected items
(the chain may be empty).
Diagnostics: Fails if menu<-multiple_selection
equals @off
and no items are selected. This should only happen it there are no items
in the menu.