V:4.1.4/Karajan:Forms Library
Contents |
Concepts
Files: forms.k, forms.xml
The forms library can be used to build and gather information from GUI forms. The current implementation uses the Java Swing library.
Component ID
Each component whose state is user-modifiable (such as button, textField, etc.) must have an ID, which can be used to retrieve the state of the component when using the form element.
Component Layout
The layout of components is done using hbox and vbox.
Component Alignment
Components support alignment using the *halign and *valign arguments. *Halign and *valign have values between 0.0 and 1.0, with 0.0 representing left/top alignment, and 1.0 representing right/bottom alignment. By default, both *halign and *valign are set to 0.5 (centered).
Form Elements
form:form
form:form(id, title, waiton)
This element represents the main form element. It creates a window based on the specification received in ..., and displays it. It will then wait for a control with the id that matches the waiton value, and terminates returning a map pairing control ids and their values. The layout of the controls in the window is performed by recursive nesting of vertical and horizontal containers (vbox and hbox respectively).
form:hbox
form:hbox(*homogeneous, ...)
Represents a horizontal container. All controls specified by ... are laid out one after another horizontally. By default, all controls are assigned an area of equal height, but the width varies according to the natural dimensions of the control (the total width is proportionally divided between the components according to their size). The *homogenous argument can be used to force all cells to have an equal width. The various possibilities are illustrated in Figure 1, Figure 2, and Figure 3.
Figure 1: A non-homogenous hbox
Figure 2: A scaled non-homogenous hbox
Figure 3: A homogenous hbox
form:vbox
form:vbox(*homogenous, ...)
A vbox is similar to a hbox but with the sub-components laid vertically.
form:label
form:label(text, *halign, *align)
Represents a text label. The text content is described by the text argument.
See also: Component Alignment
form:button
form:button(id, caption, *halign, *valign)
Represents a push-button. The text used for the label is specified with the caption argument. The ID is specified with the id argument.
See also: Component Alignment
form:checkBox
form:checkBox(id, *caption, *checked, *halign , *valign)
Constructs a check-box, whose initial state can be set using the *checked argument. By default, the check-box is not checked. The label of the checkbox is specified using the caption argument.
See also: Component Alignment
form:radioBox
form:radioBox(id, caption, ...)
Allows the construction of a radio-button group. The group will have a titled border with the text defined by the caption argument. RadioBox expects radio button definitions on the default channel (...).
form:radioButton
form:radioButton(id, caption, *selected, *halign, *valign)
Defines a radio button, with the text set by the caption argument. By default, the first button in a radioBox is selected, unless the *selected argument is used on a different radio button.
See also: Component Alignment
form:textField
form:textField(id, *columns, *halign, *valign)
Describes a text field, used for text input. A text field has only one line of text. The number of columns of the text field is indicated using the *columns argument.
See also: Component Alignment
form:passwordField
form:passwordField(id, *columns, *halign, *valign)
A passwordField is similar to a textField, with the difference that the characters entered are visually represented by asterisks (*).
See also: textField
form:comboBox
form:comboBox(id, *halign, *valign, ...)
Constructs a combo-box, which can be used to select from multiple items in a drop-down list. The items are specified as ..., using comboItem.
See also: Component Alignment
form:comboItem
form:comboItem(*text, *selected)
Specifies a comboBox item. The text of the item is indicated by the text argument. By default, the first item in a comboBox is selected, unless the *selected argument is used on a different item.
form:HSeparator
form:HSeparator()
Constructs a horizontal separator component.
form:VSeparator
form:VSeparator()
Constructs a vertical separator component.
form:filler
form:filler(*width, *height)
Defines a filler component. A filler component serves no functional purpose, but can be used to influence the layout of a form by providing a visually invisible component of the specified *width and *height (in pixels).
form:messageDialog
form:messageDialog(message, title)
Used to display a popup window displaying the specified message and having the specified title. The element completes when the popup message is closed by the user, either by using the window controls or the OK button.
