LayoutManager specification

Units

Numbers may be given with these units (default is pt, if no unit is given). All units apart from px take into account the display resolution, e.g. 72 DPI.

• px - Pixel
• pt - Points
• mm - Millimeter
• cm - Centimeter
• em - Font-Width
• ex - Font-Size
• ln - Line-Height
• in - inch
• pc - pica (1 pc = 12 pt)

Color definitions

Up to now colors can only be specified as RGB color. The RGB value must be given as a hexadecimal number prefixed with # (like in html): #rrbbgg, where rr specifies red, bb blue and gg green value. Its also possible to define the color with an integer value (without preceding #): ((red * 256) + blue) * 256 + green. But one should prefer the html-like syntax.

Example

Red=100, Blue=150, Green=25: #649619 or 6592025

Style definition

Styles may be applied inline or using a style definition or using both. In the later case, inline styles override the inherited style from the style definition.

Font and text properties

Note that the attributes loosely follow the CSS property names.

• font-family - font name
• font-size - font size
• font-style - normal | italic, defaults to normal
• font-weight - normal | bold, defaults to normal
• text-align - left | center | right | justify, defaults to left

Example

Margin, Border and Padding

Each widget can be surrounded by (from the inner to the outer): padding, border and margin. The size/width of margin, border and padding can be specified individually for each side.

The margin is transparent, i.e. is painted in the background color of the parent container. However the padding area has the same background color as the widget. The color of the border can be specified.

• margin - Size of the margin on each side (default 0).
• margin-top, margin-left, margin-bottom, margin-right - Alternative: Specifies margin size for each side individually.
• border-width - Size of the border (default 0).
• border-width-top, border-width-left, border-width-bottom, border-width-right - Alternative: Specifies border size for each side individually.
• border-color - Color of the border (default black).
• padding - Size of the padding on each side (default 0).
• padding-top, padding-left, padding-bottom, padding-right - Alternative: Specifies border size for each side individually.

Example

Colors

• color - RGB value of content foreground color, e.g. text color of a label (default black).
• background - RGB value of padding and content background color (default white).
• border-color - RGB value of border color (default black).

Example

Widget Sizes

Each widget has default sizes. E.g. the width of a label is setup large enough to display all text. The layout manager typically uses this preferred size and assures that is lies between minimum and maximum size. The defaults of each component may be overridden by specifying these style properties:

• width, height - Preferred size (default depends on widget and content).
• minwidth, minheight - Minimum size (default 0).
• maxwidth, maxheight - Maximum size (default unlimited).

Example

Label Styles

For widgets with specified label attribute all style attributes are applied on the widget (e.g. editfield) and not on the label. To change the style of the label special attributes must be set. With the attribute label-style a predefined style definition can be used for the label. To specify or overwrite individual style attributes every style attribute must be prefixed with “label-”. For example: label-border-width=“2” sets a 2 pixel thick border around the label. Or label-width=“100” makes the label 100 pixel wide. The old attribute labelwidth is still supported, but should be replaced
by label-width.

Examples

Here a predefined style label-style2 is applied on the editfield’s label:

The same result can be achieved be specifying each style attribute separately:

Default Styles

Global Default Style

It’s possible to specify default styles for widgets. The global default style, which applies for all widgets, can be set
via a style definition with empty name "". In the following example the global default style defines a yellow background color for all widgets and containers.

Containers are handled different. Only the background color of the global default style is taken into account and applied to the top-level container (child containers are transparent). All other style properties are ignored. This means for example if a border is set in the default style, that border is drawn around all widgets but not around containers. Imagine one wants to provide default paddings for all components. In that case it would be undesirably, if the padding was applied to all containers too.

In the following example the default padding of 10 pixels and the red borders are used for the labels but not for the sourrounding containers.

On the other hand if one want’s to change style properties for specific containers, this can be done on the container directly. Either by specifying a style or by setting single style attributes.

Widget Default Styles

Its also possible to define individual default styles for different types of widgets. Just speciyify attribute default-for in the style definition. The value of the attribute must be the name of the widget for which the style should be applied.

Examples:

Default style for all labels: Helvetica 12pt bold

Default style for all text fields (widgettype “editfield”): Helvetica 12pt, text color black

Layout Management

Container Layout

XMLEditor uses just one layout manger - a nested BoxLayout. In each box components can be arranged either horizontally (with and without line breaks) or vertically. The layout manager tries to give each component it’s preferred size. Optionally weights can be specified for each component to tell the layout manager, which components like to be wider or higher than their preferred sizes.

The general syntax for a container is:

The following values are allowed for the attribute align:

• right

  Components are arranged horizontally from left to right.
  The components are aligned to each other according to their align-y
  attribute (default is “top”). If possible, the container will be made large
  enough to fit in all of it’s components. No line breaks occure.
  This is the default container alignment.

• down

  Components are arranged vertically from top to bottom.
  The components are aligned to each other according to their align-x
  attribute (default is “left”). If possible, the container will be made large
  enough to fit in all of it’s components.

• right-down

  A kind of flow-layout with line breaks.
  Components are arranged horizontally from left to right.
  If the container width is not large enough to store all sub components on
  one line, a line break occures and the rest of the components is
  positioned on the next line and so on.

  Nevertheless the layout manager tries to make the container as wide
  to place all components on one line, if possible. That means to see a line
  break one has to provide a limit on the container size. Either manually
  by specifying a maximum width or implicitly by making the window size smaller.

  The components themself are always top-aligned to each other.
  That means specifying an align-y attribute has no effect.

• fillright

  deprecated Same as “right-down”.

Examples

In the following example all three possible container alignments are combined. The top-level container A has a “down” alignment, the container B a “right” alignment and container C aligns its components “right-down”.

Widget Alignment

Each widget has alignments for horizontal and vertical directions. The alignment defines how a component is positioned in a container, if there’s available space left, which is not used by the component itself.

The alignment of a component can be specified with the following attributes:

• align-x - Horizontal alignment of components to each other
  in containers with vertical (= down) alignment.

Possible values: left | center | right | 0.0 … 1.0, where 0 is left (default left).
* align-y - Vertical alignment of components to each other
in containers with horizontal (= right) alignment.

Possible values: top | center | bottom | 0.0 … 1.0, where 0 is top (default top).

Example for vertical alignment

The following container lays out its components horizontally. The component with the maximum height (widget E) defines the container’s height. All other components are smaller, so there’s available space in vertical direction. Those components are placed according to their align-y attribute.

Example for horizontal alignment

The following container lays out its components vertically. The component with the maximum width (widget E) defines the container’s width. All other components are smaller, so there’s available space in horizontal direction. Those components are placed according to their align-x attribute.

Example for aligned Containers

Of course x- and y-alignments can also be specified for containers, which are normal components too. In this example three containers have different vertically alignments inside a parent container with horizontal alignment.

Widget Weights (Dynamic sizes)

To adjust a component’s size dynamically to use the available space (e.g. window size), weights can be specified. E.g. a weight > 0 on a component says that this component likes to get additional space (if available). If a weight is not specified or weight is 0, that widget will never become additional space. It will be as large as it’s preferred size specifies, but not larger. Weights can be specified for both horizontal and vertical space individually.

Each weight is an arbitrary positive number and specifies the weight among all components at this level (i.e. all widgets in this container). If - after satisfying the preferred size requirements - available space is left, it is ditributed among the components according to their fraction of the total weight (= sum of all weights).

The following attributes can be set to define a component’s weights:

• weight-x - Horizontal weight, i.e. component likes to be as wide as possible.
• weight-y - Vertical weight, i.e. component likes to be as tall as possible.

Example for horizontal weights

Here the right component gets 2 / (1 + 2) = 2/3 of the available horizontal space and the left component gets the remaining 1/3. I.e. the right widget is always twice as wide as the left one.

Example for vertical weights

In this example three components are positioned vertically in a container with fixed height of 250 pixels. The first component (the label) does not specify a vertical weight, hence it is not larger than it’s preferred height. The remaining vertical space is distributed equally to the two textareas, since they define identical y-weights > 0.

Example for weight calculation

The total preferred width of the two components is 150px. If the enclosing component, e.g. window, has 600px, 450px are left as
additional space. The first item in this example gets an additional width of 1 / (1 + 0.5) * 450px = 300px, makes it 400px wide. The second item gets an additional width of 0.5 / (1 + 0.5) * 450px = 150px, which makes it 200px wide.

Example for weight-y in horizontal aligned container

Apparently it makes no sense to specify a y-weight in containers with horizontal alignment, since components are positioned from left to right. But look at the following picture. No y-weights are specified for the two textareas. Hence they are not larger than their preferred height of 100 pixels, allthough the container has a fixed height of 150 pixels.

In the next case vertical weights have been set for both components. This tells the layout manager that both components like to get as much additional vertical space as possible. Since the container alignment is horizontal, both components get the total height of the container, allthough they have specified different y-weights. In this example the portion of the y-weight of the total weight is not of interrest. It’s ok to specify any y-weight greater 0.

Auto width or height - DEPRECATED

To make a widget as wide or as tall as possible you can say width=“auto” or height=“auto”. However this is deprecated now. Specify a horizontal or vertical width for the component instead. It’s also a good idea to specify a width/height or minumum width/height anyway, since this will be used by the layout manager to calculate the (minimum or preferred) size of the component, if no window size is known in advance.

Old deprecated way:

New way:

Widgets with Labels

For convenience it is possible for all types of widgets (except bare containers) to set a label attribute.

For example a textarea with a label:

This will result in an implicit right-aligned container, which contains both the label and the (text) widget. The label is always positioned left of the widget. The following image shows the result (the container is normally invisible, but marked here with a red border for clarity):

Both components are per default top-aligned. However the alignment of the widget can be changed via attribute align-y, the alignment of the label by attribute label-align-y.

The above layout definition is a shortcut for specifying each of text widget, label and container separately. I.e. it is the same as the following layout definition:

Its also possible to place the label above the widget instead of left of it. Just set an align attribute with value “down” (default is “right”). This leads to an invisible down-aligned container (marked red in the following image).

Both components are per default left-aligned. But again the alignment of both the widget and the label can be changed via attributes align-x and label-align-x respectively.

As mentioned already in section “Label Styles”, all style attributes are applied on the widget itself, i.e. not on the label and not on the surrounding container. Style attributes, which are prefixed with “label-” affect the label. However it is not possible to define style attributes (e.g. margin or border) for the container.

For example: The following widget definition defines a border, which is drawn only around the textfield and not around both the label and the textfield.

Restrictions, Special Cases and Deprecations

A)

DEPRECATED Will be changed into a single label widget without container. Child widgets are not (any longer) allowed! It leads to the same as the following widget definitions, which should be used preferred:

or NEW

B)

Illegal, since labels no longer allowed for containers!

Replace with:

C)

Illegal, since labels not allowed for container-widgets!

D)

Allowed only for “group” widgets. Illegal for all other widget types, since child widgets are now only allowed for containers and container-widgets (like groups), not for “base” widgets.

Widget definition

Widget Alignment

Widgets are placed within containers according to their alignment (align attribute).

• align - right | down | right-down (fillright), layout sub components, defaults to right

Example 1:

Layout is

• container with right-alignment (default) having these sub items:
  • static text as label
  • editable field with content asset@name of data source “$other”

Example 2:

Layout is

• container with down-alignment
  • static text as label
  • editable field with content asset@name of data source “$other”
  • container with right-alignment
    • static text as label
    • editable field with content asset@name of data source “$other”

Special Widget Attributes

• enabled = true | false
• enableddef = key-path
• readonly = true | false
• readonlydef = key-path

Referencing data

The source attribute specifies the path to the value:

The “$data.” prefix denotes the data source, which is application specific. By convention, $data denotes the “main” to work with. “$data” may be omitted.

Nesting and looping in data

Use select=“true” to select local data root. The second item denotes party.record@name:

Creates items for all record elements of party:

Lookup definitions

Inline options definition

Reference to data

Note that the value and label attributes default to “@value” and “@label”, which allows the above inline definition without these attributes.

Usage with popups:

May be specified inline as well:

Usage as lookup:

Initializing data

defaultvalue, inititem.item, override

Filtering / matching

If present, items are only displayed, if any of the filter entries match:

Filters may be specified by reference as well. Defaults to “filters.filter” - that is inline.

Widgets

Checkbox - checkbox

Additional attributes:

• caption - checkbox text
• captionbold - true|false bold checkbox text; DEPRECATED
• checkedvalue - value to set when checked, defaults to “true”
• uncheckedvalue - value to set when unchecked, defaults to “false”

Examples:

Radiobutton - radiobutton

Additional attributes:

• checkedvalue - value to set when checked (a radiobutton does not set any value when unchecked)

Examples:

Color Picker - colorpicker

The RGB color value is stored as integer using:

Example:

Delete Button - deletebutton

Additional attributes:

• confirmmessage - display confirmation dialog with this message

Note how source is treated: if empty, perform delete on node, if non empty perform clear (set to null) of attribute.

Examples:

Drag item - dragitem

Additional attributes:

• dragitem@name: name of root element to create
• dragitem.item<>@path: path to put value
• dragitem.item<>@source: path or value (sourcetype = “value”)
• dragitem.item<>@sourcetype: refpath, refpathtop, refpathglobal, defpath,
  defpathtop, defpathglobal, value, defaults to refpath

or

• dragitem.item<>@special:
• refpath: absolute refpath (including indexes “<>”)
• selectstart: current text selection start of associated text field
• selectlength: current text selection end of associated text field
• selectedtext: current text selection of associated text field

Note: selectstart and selectLength take the selection of the text field that has the current focus (focus ring) and verifies that its absolute refpath matches the one of the draggable item. If no item has the focus, the value of the dragitem item (item@refpath) is used.

Sample:

The resulting drag item text would look like (assuming @date having the value “10.2.2003”):

Date - editdate

Additional attributes:

• mode - “search” for search dialog

Example:

Static text - statictext

Examples:

Label - label

Examples:

Text field - editfield

editable text field

Example:

Text box - edittext

Multiline editable text field width scroll bar

Additional attributes

• mode - xml: display xml starting at @source (points to xml element node),
  diff-words: display word-by-word difference between @source and @source2, otherwise just display text

Example:

Group box - group

Grouping container, i.e. a container with title and frame around sub items.

Additional attributes:

• caption - group title
• captionbold - true|false bold title; DEPRECATED
• align - right|down the container alignment

Example:

Button - button

Additional attributes

• caption - button text
• confirmmessage - display confirmation dialog with this message
• method - method to invoke

Example:

Insert button - insertbutton

Standard insert button control for XMLEditor. Compare with loop, maxoccurs and insertbefore attributes of XMLEditor.

Additional attributes (shared with item that has loop attribute set):

• newcaption - optional button text, or if not set uses "new " + caption

Listbox - listbox

Example:

Picture - picture

@width = "auto" will use picture size, otherwise picture will be scaled to given width and height

Additional attributes

• scale - current scaling, defaults to 1 (100%). If 0, scaling is not allowed.

Popup menues - popupmenu, popupmenu2, popupmenu3

• popupmenu uses “real” popup menu controls
• popupmenu2 uses bevel buttons with menus (typically better performance)
• popupmenu3 uses text fields with drop down lists (allow for tabbing and up/down key)

Additional attributes

• @optionssource defaults to “options.option”
• @optionssourcetype defaults to “defpath”
• @optionsvaluesource defaults to “@value”
• @optionslabelsource defaults to “@label”

Examples:

@optionssourcetype=“suboption” signs that this popup belongs to hierarchical popup group (previous item must be of same type, that is popupmenu, popupmenu2 or popupmenu3)

Cascading popup - popupmenutree

Example:

Separator - separator

Separator line.

Window Splitter - splitter

Additional attributes

• @split - horizontal|vertical split orientation
• @divider-pos - divider position

Include- includeitem

Additional attributes

• key - key of dialog definition to be included

Example:

Select case - selectcase

Switch on value (continue with items below case). If no items below, will through next case with items.

Example: