company logo

List box styles

ODABA supports several types of list controls. All list controls are based on a tree model, which supports several regions with sub-regions in a list. Each region in a list may contain a number of columns.

List types supported are:

  • List - simple list with one column
  • Table - list with several columns
  • Tree - structured list with several columns
  • Combo box - single line edit field combined with a drop list or tree
  • Radio button group - radio button list
  • Day calendar - calendar presentation of any number of days
  • Month calendar - calendar presentation for days of a month

Except within a tree, all regions of a list will be displayed when opening the list. For each region, a region header might be defined. Regions and columns defining a list are called list schema. Items displayed in the list are called list items. Each list item contains a data item for each column defined for the region.

List elements and list items might be decorated or associated with several layout properties, which determine the appearance of data items.

Notes:

The combo box is actually not a list control, but id contains a drop list, which might be a tree or a list and behaves as such.

List schema

For a list control, columns and regions might be defined. A simple list just defines the data source (collection) and usually displays the instance keys according to the selected order in the list.

More complex list schemata might be defined by adding columns and regions to the list definition. Regions may contain sub regions, which might contain sub regions again etc. The ODABA GUI framework also supports recursive regions (in order to display the children of the children of the children etc.).

List columns

List columns are defined as a list of data sources (fields) added to the columns collection of a field control. Depending to the data type of the data source, data will be displayed left (text) or right (numbers) adjusted in the table cell. Boolean values will be displayed as check boxes.

Column size

For a table or tree, column size may differ for header columns and table columns. Header column size is, usually, defined in text (label) definition for header columns. The table column size is defined in field (column) properties.

When height or width is defined as 0, appropriate values defined in the associated control (when being assigned) will be used instead. Defining -1 (automatic sizing) for header or data columns, available space is used. The portion of space to be assigned to such columns may be controlled by defined grow rate for column. Only, the grow rate corresponding to header orientation is used (e.g. horizontal grow rate for horizontal headers and vertical grow rate for vertical headers). Defining grow rate -1 for a column causes assigning cell size to content. Grow rate 0 is always the same as grow rate 1.

Since column width for for trees or tables with horizontal header must be the same as table column width, column width is synchronized with column header width. Similar, for vertical column headers column height and header height are synchronized.

Moreover, for horizontal column headers the maximum header column height is used as table heder height. For vertical column headers the maximum header column width is used as header width.

Column number

Defining columns for multiple trees or region tables or lists requires, that number of column is the same for each region in the list control. In order to fill up number of columns for regions with less columns than the maximum, one may fill up regions with dummy columns that define an user-defined data reference type but no data source, no data type and all data source options off.


Column schema

Columns may contain fields, which provide a number of sub-columns. E.g. one may define hierarchical columns like:

  • Name (name)
  • First name (first_name)
  • Address (location(0))
  • Place (city)
  • Street (street)
  • No (number)
  • Birth (birth_date)

This becomes particular useful when displaying data from related instances (as for location), since in this case, the location instance is read ones, only instead of three times. In the table, list or tree, columns are not displayed hierarchically, but as:

  • Name
  • First name
  • Place (city)
  • Street (street)
  • No (number)
  • Birth (birth_date)

Complex columns (like Address) will not become visible in the list header. Complex columns may also be used for providing a column schema, which may apply on several tables, lists or trees.

Hierarchical column header

In order to define hierarchical column headers, the list, tree or table must be marked as multi-line (header) in the associated control style definition. In case of multi-line headers, the defined column hierarchy

  • Name (name)
  • First name (first_name)
  • Address (location(0))
  • Place (city)
  • Street (street)
  • No (number)
  • Birth (birth_date)

would be displayed with Name, First name, Address and Birth in the first header row and Place, Street and No in the second headline row below Address. Table columns are defined by all columns that have no sub columns,

Header direction

In order to support longer title for small columns, one may define text rotation for header columns. In case of text rotation, the column header text is rotated by -90° (all other values for rotation are invalid in the current version). Rotated column headers are written from bottom to top. When rotating column headers, width and height are rotated, too, e.g. text width and height should always be defined regardless on header rotation.

For defining rotated columns the column field definition must be associated with a column control (referring to a column style that defined a -90° rotation).

Column headline and decoration

Column head lines bay be displayed on control (list, tree or table) and/or region level. In order to display column headers, a tithe has to be defined for column text definitions and the show label option has to be switched on. A control or region headline will be displayed, when at least one of the columns has activated the show label option.

In order to provide more column decorations as icons or colored text or text background, one may associate the column with a column control by assigning a class and a field control . The field control may refer to a font defining the headline font and/or an image decorating the column head line. Headline settings may also be altered by the application in the doBeforeDataSet() handler.


Column order definition

Column definitions also contain order specifications. When lists, trees or tables allow ordering columns by clicking on head line, columns are, usually, ordered by column values (content). In order to achieve descending order when sorting by column, descending option in the column's data source has to be set. Associating a column with a specific database order is possible by defining an index (key name) which refers to a valid index for the collection displayed in the list.

This works fine for lists and tables, but becomes a bit more complicate for trees with regions of different data types. When defining column orders for trees, those have to be defined for columns of each region separately.


List regions

Usually, a list, tree or table (shortly called lists here) consists of a top region, which is defined as the data source marked as collection. In order to define multiple region collections, the list's data source must not be marked as collection. Instead a region list contains collection data sources for different regions, which are defined either relatively to (in scope of) the list's data source or with an absolute path.

As data source path for a region one may refer to a simple property (extent or property in the parent data source), or to a complex property path (e.g. Person().children().cars() for getting a list of all children's cars). When using collection paths, the collection operator () at the end of the path is important. Finally, one may also refer to an OSI function returning a collection and which is defined in the scope of the parent data source.

In order to define hierarchical lists, regions may contain sub regions at any nesting level. Sub regions typically refer to properties in the parent region as data source, but may also refer to property paths or OSI functions. In a tree, sub regions may be expanded or collapsed explicitly. For lists and tables, sub regions are always visible.

for defining sub regions, the field definition for the region must get a field control defining the field(s) for the sub region. In order to define recursive sub regions (e.g. Person.children...children, i.e. children at any nesting level, the region field definition sub region field control may refer to sub region field control. Recursive region definitions may be used in trees but should be handles with care in lists and tables.

List layout definitions

List layouts includes several layout elements, which might be defined and changed separately:

  • text font
  • text color
  • background color
  • icon
  • label (region label or column headlines)
  • tool tips
  • detailed help information.

Usually, the layout defined for the control applies to all items in the list. When, however, regions and columns have been defined for the list, more sophisticated layout definitions might be provided. Finally, layout for each data item (cell) in a list might be changed from within the application.

Practically, layout information might be set for each

  • data item (run time)
  • column (list schema)
  • region header (list schema)
  • control (list schema)

Layout elements usually are inherited from upper levels. The list layout is not inherited as a whole, but in terms of elements, i.e. one may define a font for the list control and change the background color for a column still referring to the font defined for the control.

In order to define a layout for the region label or column header, layout elements might be defined for the region control. Defining region layout information requires a region control besides the region field. This information only applies on region label or column header.

In order to define a different layout for data items displayed for a region, layout elements can be assigned to each column control in the region (in this case, a column control needs to be defined besides the column field). The column layout also applies to the column heading, when column labels have been defined. In contrast to data items, the column heading also inherits layout information from the region, i.e. the region headline is displayed with the defined region layout completed by the column layout.

Data items usually display data according to the layout defined for the column. The region layout does not affect the data item layout. The data item layout might be, however, modified by the application (e.g. in an event handler when filling the list), which may define specific layout elements for each data item. Layout elements not explicitly defined for a data item are still taken from the column definition or from the control layout.

Defining region and column headers

Column headers are usually created from top region column definitions (text definitions). Text definitions get a separate size definition. For horizontal headers, the column width is synchronized with the column width defined in field or field control as follows:

  • When text width is 0, the width defined for field or control is used
  • When text width is -1 (use available space) and column width is greater than 0, column width is used
  • When text and column width are defined and both are greater than 0, the maximum is used.

For vertical headers, similar rules are used for synchronizing column header and column height.

Defining a region header can be achieved by defining a title in the region field text data tab or in the associated region field control. In any case, Show label has to be switched on. The region label is displayed for the first column, only. Other columns do not get a text label.

When a region label has been defined, the region label is shown in the list without being expanded. In order to display the sub items in the region, the region has to be expanded by the user.

In order to define column labels, columns have to be defined for the region. For each column a column label (header) might be defined by setting a title text in the text definitions tab and switching on the Show label option. In contrast to region lables, column labels are displayed, only, when the region contains data. When using column labels, the region is always expanded and cannot be collapsed.

Labeled items

In order to define a list with labeled items, i.e. a list, where each item gets a label in the first column, a column header has to be defined for each region and the region must define a single item.

Labeled items are typically used for displaying properties in transposed tables. This is an alternative way of designing property tables, which also could be achieved by defining a transposed table for a single instance.