1.40 class dialog_group

A dialog_group object is a compound dialog item, a number of dialog_item objects displayed on a specialised device object.

Class dialog_group specialises class device to ensure proper handling of the layout of the controls displayed inside it as well as the placement of the group in the dialog. The class is also responsible for proper handling of keyboard input, including the dialog_group<-default_button.

A dialog_group is built exactly the same as a dialog object. Here is a small example:

...,
new(DG, dialog_group(location)),
send(DG, append, text_item(address)),
send(DG, append, text_item(city)),
send(DG, append, text_item(country)),
...

1.40.1 Instance variables

dialog_group <-> alignment: {column,left,center,right}

Alignment of the dialog group in the surrounding dialog window. See dialog_item<-alignment.

dialog_group <-> auto_align: bool

Automatically align in dialog (@on). See‘dialog_item dialog_group<-auto_align’.

dialog_group <- border: [size]

Space around the items. The value @default uses the same value for the border as for the dialog_group<-gap between items. See also dialog_group->kind.

dialog_group <- gap: size

Distance between the dialog_items displayed in the group. See device->layout_dialog for a description of the layout algorithm

dialog_group <- label: [name|image]*

Text displayed to lable the dialog group. If the label is the empty name object (” ), the label is not displayed. See also dialog_group->name and dialog_group<-label_font.

dialog_group <- label_font: font

Font used for displaying the dialog_group<-label.

dialog_group <- label_format: {top,center,bottom,hot_spot}

Alignment of the label with the line drawn around the group. Its value should normally be controlled by the class-variable to ensure consistent appearance of compound dialog groups.

dialog_group <- radius: 0..

Radius for the corners of the box surounding the group elements. Used to commit to the style.

dialog_group <- size: [size]

Size of the contents. @default implies the size is computed from the items displayed in the group.

1.40.2 Send methods

dialog_group ->append: item=graphical, relative_to_last=[{below,right,next_row}]

Mimics the behaviour of dialog->append.

dialog_group ->modified_item: item=graphical, modified=bool

Indicates item has changed state.

dialog_group ->restore:

dialog_group->restore all items to their dialog_group<-default.

dialog_group ->apply: always=[bool]

These methods are reimplementations of the corresponding methods on class dialog. See dialog->apply, dialog->modified_item and dialog->restore.

dialog_group ->event: event

Maps the obtain_keyboard_focus event to device->advance, and otherwise simply invokes device->event to dispatch the event over the items.

dialog_group ->geometry: x=[int], y=[int], width=[int], height=[int]

If either width or height is specified, a size object is computed and dialog_group->size is invoked. The group is moved.

dialog_group ->initialise: name=[name], kind=[{box,group}]

Create an empty dialog group from its name. The name is used to assign the graphical<-name slot and handed to dialog_group->name to compute the default dialog_group<-label from it. Using the standard configuration, the graphical<-name is capitalised to produce the dialog_group<-label.

The dialog_group->kind determines the appearance of the group.

See also class label_box.

dialog_group ->kind: kind=[{box,group}]

Set default appearance. The default dialog_group->kind is box. Its values:

box

Sets dialog_group<-border to @default, dialog_group<-label to the dialog_group<-label_name calculated from the graphical<-name and graphical<-pen to 1. This results in a (3d-) box with a label containing the items, which is normally used to visually group items for the user.

group

Sets dialog_group<-border to size(0,0), dialog_group<-label to” and graphical<-pen to 0. This mode is normally used to group dialog items for technical reasons. One such reason is the definition of a single dialog item for a special type that requires multiple sub-items as a subclass of class dialog_group. The other is to subdivide the items in a dialog window in multiple groups to define layouts that do not fit in the standard matrix layout provided by dialog windows.

dialog_group ->layout_dialog:

Invokes device->layout_dialog using the dialog_group<-gap and dialog_group<-size attributes.

dialog_group ->name: name

Assigns the graphical<-name and determines the displayed dialog_group<-label. The label is computed using the dialog_group<-label_name method.

dialog_group ->position: point

Determines the top-left corner of the group.

dialog_group ->reference: point

Overrules the definition of device->reference with the one of graphical->reference as changing the origin of a dialog group does not have any practical meaning.

dialog_group ->x: int

Set the X-coordinate of the left-side of the group.

dialog_group ->y: int

Set the Y-coordinate of the top-side of the group.

1.40.3 Get methods

dialog_group <-default_button: delegate=[bool] -> button

Current Button connected to RET. If delegate is @off, only buttons displayed on the group itself are considered. Otherwise the graphical<-device links are followed, searching for default buttons on containers.

dialog_group <-label_name: name -> name

Determine default-label from the name using the method‘name dialog_group<-label_name’. The latter by default capitalises the name, replacing underscores by spaces. It may be redefined to map labels to a different language.