Home Contents Previous Next

1.41 class dialog_item

Class dialog_item describes the communication between a dialogue window (class dialog). and an item in such a window. Besides the normal communication between graphicals and windows, this entails:

1.41.1 Class variables

dialog_item.label_suffix: name = :
Suffix added to the label of this dialog item if not already present. The only sensible values are’:’or” . See also char_array<-ensure_suffix, char_array<-label_name and dialog_item->initialise.

1.41.2 Instance variables

dialog_item <- above: graphical*
Dialog-item immediately above me.

Defaults: @nil (no item is above me)

See also
dialog->layout
graphical <- active: bool
Determines whether the item is sensitive for user-events. If @off, the item's image is greyed-out by anding it with a grey pattern.

Defaults: @on (active).

dialog_item <-> alignment: {column,left,center,right}
Determines how the dialog is fitted in the two-dimensional space of the dialog window by dialog->layout. The values are:
column
Align the item below the upper-neighbour
left
Place the item immediately right of its left-neighbour. (left means flush-left).
center
Place centered items adjacent and centered in the available horizontal space.
right
Flush the item to the right of the available horizontal space.

For example, button objects in OpenWindow dialog windows should be centered. Setting button.alignment to center will properly align buttons for OpenWindow look-and-feel.

dialog_item <-> auto_label_align: bool
Align the width of the label automatically with the labels of the items in the same column.

Defaults: @on (align labels in the same row).

See also
- dialog_item-label_width
- dialog->layout
dialog_item <-> auto_value_align: bool
Automatically align the width of the values. Currently applicable to menu's only, where it refers to the width of the entries in the menu.

Defaults: @on (do align values)

See also
- menu-value_width
- class menu
- dialog->layout
dialog_item <- below: graphical*
Dialog item immediately below me.
See also
dialog->layout
dialog_item <- label: char_array|image*
Label of the item. For most items, the label is displayed in the label_font and indicates the function of the item.

Defaults: The provided name (first initialisation argument) is capitalised to provide the initial label.

See also
menu->initialise
dialog_item <- label_format: {left,center,right}
Determines how labels of dialog objects aligned in a vertical column are aligned by dialog->layout. dialog->layout first determines the widest label, after which it requests all dialog items to make their label equally wide. This parameter determines how a small label is aligned in a wider box.

See also dialog_item.label_suffix.

dialog_item-label_width: [int]
The width of the area in which the label is displayed. Used to implement automatic alignment of labels of items displayed in a vertical row. See also dialog->layout.
See also
- dialog_item-auto_label_align
- dialog->layout
dialog_item <- left: graphical*
Item immediately to the left.
See also
dialog->layout
dialog_item <- look: {open_look,motif,win,gtk}
General look-and-feel switch. The interpretation is left to the subclasses. See also scroll_bar<->look.

XPCE is shipped with Defaults both to generate OpenLook style (Unix/X11) or Windows-95 style (Win32).

dialog_item <-> message: [code]*
Message executed when the item is executed. The conditions on which the execution takes place as well as the arguments forwarded are determined by the specific type of item.
See also
- menu->initialise
- dialog_item-execute_event
dialog_item <-> popup: popup*
Popup menu associated with the item.
See also
class popup
dialog_item -> reference: [point]
Reference point for alignment in two-dimensional grid. When to items are aligned horizontally or vertically, dialog->layout aligns the graphical<-x or graphical<-y component of their reference points.

The get-method returns the value of the variable when filled and fails otherwise. This method is redefined by most dialog-item subclasses (button<-reference, text_item<-reference, etc.).

Invoking dialog_item->reference: @default will make the item return its class-defined default. Invoking this method with an instance of class point will explicitly set the reference-point.

dialog_item <- right: graphical*
Item immediately to the right.
dialog_item <- status: {inactive,active,preview,execute}
The status variable describes the current status with regard to processing user-events. The values are:
inactive
Default initial value
active
In focus of events; the item may indicate so.
preview
Indicates releasing the button now will start execution
execute
Indicates the dialog_item<->message is currently executing

Defaults: inactive

See also
- dialog_item-execute_event
- dialog_item-cancel_event
- dialog_item-release_event_focus
- dialog_item-preview_event
- dialog_item-obtain_event_focus

1.41.3 Send methods

dialog_item ->cancel:
Cancel current gesture. Equivalent to dialog_item->status: inactive.
dialog_item ->default: any
Virtual method. Defined by subclasses that may be modified. It assigns the initial value as well as the value to which the item is graphical->restore’d.
dialog_item ->device: device*
If the device is changed all dialog_item<-above, etc. relations are destroyed first.
dialog_item ->event: event
Show dialog_item<-popup when defined.

First invoke graphical->event. If this fails and dialog_item<-popup is not @nil, open this popup menu. This method is redefined by most subclasses.

dialog_item ->initialise: name=name
Create a dialog_item from its name. Class dialog_item is just a super-class of the real dialog items and it is of very little use to create a instance of this super-class. dialog_item<-label is filled with char_array<-label_name and the label is guaranteed to end with pce.DialogItem.label_suffix.
dialog_item ->modified: bool
When @on, this method invokes dialog_item->modified_item: @receiver, @on on its graphical<-device (normally dialog->modified_item). When @off is method just succeeds.

This method is redefined by subclasses of dialog_item that allow the user to modify the selection.

See also graphical->restore, dialog_item<-default and dialog->modified_item.

dialog_item ->open:
Convenience method: if the dialog_item is not yet placed in a dialog window, place it in a default dialog window and open this window on the display, so 
?- send(text_item(name), open).

Suffices to create a default text_item object in a window on the display.

dialog_item ->reset:
Reset the dialog_item<-status to inactive. This will reset dialog items if the execution is aborted from the activated code.
dialog_item ->show: bool
Inherits description from: dialog_item<-show
See also
graphical-displayed
dialog_item ->value_width: [int]
Inherits description from: dialog_item<-value_width

1.41.4 Get methods

dialog_item <-default: -> any
The dialog_item<-default of a dialog_item defines the value to which the dialog_item<-selection will be reset by graphical->restore. The dialog_item<->default mechanism is defined for all sub-classes of class dialog_item that may be modified by the user.
dialog_item <-modified: -> bool
Virtual method. Subclasses that define items which may be modified by the user (class text_item, class menu) redefine this method to return @on after the user has modified the item. See also graphical->apply and dialog->modified_item.
dialog_item <-show: -> bool
Equivalent to graphical<->displayed. Retained for backward compatibility.
dialog_item <-value_width: -> int
Methods used to align the values of dialog_items placed above each other. Implemented for class menu to align the field width when multiple menu's are in a vertical column,