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.
Two independent properties define a menu. menu->kind
defines how the items are presented: as a drop-down combo box showing
the selection (cycle), as a list of items with a radio
button or check box (marked), or as a segmented control (choice).
menu->multiple_selection
defines whether the user may select one or more items. menu->kind
resets menu->multiple_selection
to @off, so
set the kind first. toggle is a shorthand for a marked
menu with multiple selection:
?- new(M, menu(options, toggle)). ?- new(M, menu(options, marked)), send(M, multiple_selection, @on).
Menus are drawn in the colours of the theme; see the class variables
accent_colour, indicator_border, indicator_background,
indicator_size, segment_background, segment_border
and
segment_pressed.
marked and choice menus accept the keyboard
focus. The arrow keys move the selection of a single selection menu. In
a multiple selection menu they move menu<-focus_item,
which Space or Return toggles. At the first or last item, Left and Right
move the focus to the previous or next dialog item.
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. In both layouts the label is left of the first item, so a
dialog aligns it with the labels of the items above and below. 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 and 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.
->feedback
sets menu->kind,
keeping menu->multiple_selection:
->kind
->kind
->kind
->focus_item.<->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.
toggle for a marked
menu with menu<-multiple_selection @on.
<->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.
marked
menu and for the padding of the segments of a choice menu.<->selected.
A marked menu shows radio buttons if @off
and check boxes if @on.
A cycle menu always has a single selection.
If @on, Alt-click or double-click on an item selects only this item. Doing so again on this item while it is the only one selected restores the selection from before. The message of the menu is called as for a click on the item.
|{marked}*marked menu that have
MenuItem<->selected: @off.
When marked (default), this is a radio button or check box
drawn in the theme colours. When @nil,
nothing is painted before the item.
|{marked}*marked menu that have
MenuItem<->selected: @on.
When marked (default), this is a radio button or check box
drawn in the theme colours; in a popup it is a check mark. When @nil,
nothing is painted before the item.
->feedback)
->feedback,
but the latter only inverts the item.
<->popup.
Otherwise it is the width of the pullright marker 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.
->multiple_selection
to
@off. The
available options are:
->multiple_selection
is @on (see menu<-on_image
and
menu<-off_image).
->multiple_selection
to @on.
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.