A ListBox may contain one or more ListBoxHeader objects. Each ListBoxHeader within a ListBox defines a column with a title. A column has various properties:

• The user may use the column context menu (by clicking the right mouse button in the column header) to selectively show or hide a column.
• The user may change a column's width by dragging a column's border in the column header.
• The user may rearrange the columns by dragging a column's title into a new position.
• The user may click a column's title to sort the list by this column. Clicking again toggles between ascending/descending/no sorting. While clicking, the Ctrl key may be pressed to specify a second, third, forth ... sort column.

A program may control and selectively enable each of these properties.

Contents:

• ListBox attributes
• ListBoxHeader attributes
• Examples

ListBox attributes

Name	Type	Default	GET	SET	Description
activeitem	INT		X	X	Current active line (starting with 1, 0 = no active line) Note: Setting activeitem always affects cy.
activeline	INT		X	X	Current active line (starting with 1, 0 = no active line) Note: Setting activeline to a nonzero value affects cy.
add	STRING		-	X	Adds new lines to the end of the list Lines are separated by LF (ASCII 10) or CR/LF (ASCII 13, 10) as specified by the newline attribute, columns are separated by the delimiter specified by the delim attribute.
bgcolor2	STRING		X	X	Used to specify a separate background color assigned to even lines in the list Accepts a string argument in "#rrggbb" form, where rr, gg and bb are hexadecimal values for the red, green and blue color intensities, each ranging from 00 (minimum) to ff (maximum). If set, bgcolor is assigned to odd lines (1,3,5,...) and bgcolor2 is assigned to even lines (2,4,6,...). If not set, bgcolor is assigned to both odd and even lines. See also: fgcolor2
border	INT	1	X	X	Implemented for compatibility reasons The ListBox border visibility and thickness currently cannot be specified. A ListBox always has a border. In a single column ListBox without a column header, if border is positive and nonzero each line is visually indented by a leading space.
clear	INT		-	X	Deletes all lines in the list
column	STRING[]		X	-	Returns the fully qualified path to the specified column (starting with 1)
columnorder	STRING	1 2 ... n	X	X	Used to retrieve the current column view order or to rearrange the columns the same way they may be rearranged by dragging the column titles into a new position The columnorder string consists of an entry for each column. The entries are separated by the delimiter specified by the delim attribute. Each entry may consist of: - the numerical column position (column view order, starting with 0) - the * character to leave the position unchanged - the ! character to make a column invisible - the > character to move the column clockwise among a group of columns (the group consists of all columns that have the > entry) Note: The position of an entry in the columnorder string is equivalent to the physical position of the column. Also note: On DLG SET, the ListBox is synchronized (similar to DLG DRAW). Please refer to the examples below.
columns	INT		X	-	Current number of columns
content	STRING		X	X	Used to get or set all lines at once Lines are separated by LF (ASCII 10) or CR/LF (ASCII 13, 10) as specified by the newline attribute, columns are separated by the delimiter specified by the delim attribute.
cx	INT	0	X	-	Implemented for compatibility reasons, has no effect (returns 0)
cy	INT	0	X	X	Current line (starting with 0)
delim	STRING	TAB (ASCII 9)	X	X	Column values are separated by this delimiter
delln	INT		-	X	Deletes the specified number of lines from the current line (cy)
fgcolor2	STRING		X	X	Used to specify a separate foreground color assigned to even lines in the list Accepts a string argument in "#rrggbb" form, where rr, gg and bb are hexadecimal values for the red, green and blue color intensities, each ranging from 00 (minimum) to ff (maximum). If set, fgcolor is assigned to odd lines (1,3,5,...) and fgcolor2 is assigned to even lines (2,4,6,...). If not set, fgcolor is assigned to both odd and even lines. See also: bgcolor2
gridcolor	STRING	#000000 (black)	X	X	Color of grid lines in hexadecimal RGB notation (#RRGGBB), effective if hlines and/or vlines is set
hlines	INT	0	X	X	Visibility of horizontal grid lines
hsb	INT	0	X	-	Implemented for compatibility reasons, has no effect (returns 0) Horizontal scroll bar is displayed if required.
ins	STRING		-	X	Inserts new lines before the current line (cy) Lines are separated by LF (ASCII 10) or CR/LF (ASCII 13, 10) as specified by the newline attribute, columns are separated by the delimiter specified by the delim attribute.
length	INT		X	-	Current content size (total number of characters)
line	STRING[]		X	X	Used to get or set the specified line (starting with 1) If used without an index, the current line (cy) is affected. Columns are separated by the delimiter specified by the delim attribute.
modelorder	INT[]		X	-	Returns the physical line index of the specified view index (starting with 1) For example, if the current sort sequence causes the physical line #5 to be displayed at position 10 DLG GET modelorder[10] returns 5.
movable	INT	1	X	X	Specifies if the columns may be rearranged by dragging the column titles into a new position
multiline	INT	1	X	X	Implemented for compatibility reasons, has no effect
newline	INT	0	X	X	0: lines are separated by LF (ASCII 10) 1: lines are separated by CR/LF (ASCII 13, 10)
resetorder	INT		-	X	Arranges all columns in physical order and makes all hidden columns visible The current line sorting is retained.
rowheight	INT	0	X	X	Specifies the minimum row height By default, the row height is calculated from the font size. However, if HTML content is used the row height required to display the HTML content cannot be determined, therefore it must be explicitly specified. About using HTML content, please refer to the examples below.
rule	INT	0	X	X	If nonzero: rule value to be submitted when the selected line changes. Note: Rule activation depends on the singleclick attribute.
ruleoverride	INT	0	X	X	If set, the rule of a previously focused EditText or ComboBox object is overridden (the ListBox rule combined with the EditText or ComboBox path is returned).
singleclick	INT	0	X	X	Specifies which action should activate a rule submission 0: rule activation on mouse button double click 1: rule activation on mouse button single click 2: rule activation on mouse button double click and up/down cursor keys 3: rule activation on mouse button single click and up/down cursor keys
sizable	INT	1	X	X	If set, the user may change the column width. Note: The ListBoxHeader resizable attribute allows to specify this for an individual column. If ListBox sizable is set to 0, ListBoxHeader resizable has no effect.
sortsequence	STRING	* ... *	X	X	Used to get and set the current sort sequence The sortsequence string consists of an entry for each column. The entries are separated by the delimiter specified by the delim attribute. Each entry may consist of: - a sort specifier (see below) - the * character to set a column unsorted - the ! character to disable sorting for a column A sort specifier is a positive number that specifies the sort precedence for a specific column. By default a column is sorted in ascending order. The number may be prefixed with either A or D to specify ascending or descending order. Please refer to the examples below.
status	STRING		X	X	Used to conveniently get and set (i.e., save and restore) the state of a ListBox This includes the column order, the sort sequence and the width of each column. The status string consists of 3 lines separated by LF (ASCII 10) or CR/LF (ASCII 13, 10) as specified by the newline attribute: - line 1: column order (see columnorder above) - line 2: sort sequence (see sortsequence above) - line 3: width of each column separated by the delimiter specified by the delim attribute Note: On DLG SET, the ListBox is synchronized (similar to DLG DRAW).
title	STRING	empty	X	-	Implemented for compatibility reasons, has no effect
topitem	INT		X	X	Current topmost line (starting with 0)
vactiveline	INT		X	X	Current active line in view order (starting with 1, 0 = no active line) Note: Setting activeline to a nonzero value affects cy (which is set to the physical line index). Also note: On DLG SET, the ListBox is synchronized (similar to DLG DRAW).
vcolumn	STRING[]		X	-	Returns the fully qualified path to the specified column in view order (using the current column view order, starting with 1) Invisible columns do not count.
vcolumns	INT		X	-	Current number of visible columns
vcontent	INT		X	-	Used to get all lines in view order (using the current line and column sort order) Invisible columns are skipped. Lines are separated by LF (ASCII 10) or CR/LF (ASCII 13, 10) as specified by the newline attribute, columns are separated by the delimiter specified by the delim attribute.
vheight	INT		X	-	Current number of lines
vieworder	INT[]		X	-	Returns the view index of the specified physical line index (starting with 1) For example, DLG GET vieworder[5] returns 10 if the current sort sequence causes the physical line #5 to be displayed at position 10.
vline	STRING[]		X	-	Used to get the specified line in view order (using the current line sort sequence and column order, starting with 1) Columns are separated by the delimiter specified by the delim attribute.
vlines	INT	0	X	X	Visibility of vertical grid lines
vsb	INT	0	X	-	Implemented for compatibility reasons, has no effect (returns 0) Vertical scroll bar is displayed if required.
vwidth	INT		X	-	Current number of columns (number of characters of widest line)

ListBoxHeader attributes

Name	Type	Default	GET	SET	Description
align	STRING	left	X	X	Specifies how a column is aligned Possible values are: - left - center - right Note: This affects the column's content, not the title.
autowidth	INT	0	-	X	If set to nonzero, the width of a column is set to its widest content during the next DLG DO or DLG DRAW Note: This affects the width of a column only once. If the width should be adjusted after new content has been added, autowidth must again be DLG SET to a nonzero value.
coltype	INT	0	X	X	Specifies the type of a column The following types are supported: 0: alphanumeric 1: numeric 2: boolean (nonzero or zero) 3: bar graph display Types 1 and 2 are provided to specify how the text of a column should be sorted. If the column contains numerical data the type should be set to 2, otherwise sorting the column probably results in an unexpected sequence. If coltype is set to 3 a checkbox is displayed. The state of the checkbox depends on whether the value is nonzero or zero. The purpose of type 4 is to display a column consisting of bar graphs. A bar graph column value consists of two values separated with a semicolon. The first value is the size and the second value is the maximum range of the bar. For example, 25;100 would display a 25% bar and 150;200 would display a 75% bar.
index	INT		X	-	Used to get the physical column index (starting with 0)
line	STRING[]		X	-	Used to get the specified cell in a column (starting with 1) If used without an index, the current line (cy) is used.
resizable	INT	1	X	X	If set, the user may change the column width Note: If the ListBox sizable attribute is set to 0, this has no effect.
textpos	STRING	left	X	X	This is an alias for the align attribute, implemented for compatibility reasons
title	STRING	empty	X	X	Current column title
vindex	INT		X	-	Used to get the column view index (using the current column order, starting with 0) Note: For an invisible column, -1 is returned.
vline	STRING[]		X	-	Used to get the specified cell in a column in view order (using the current sort sequence, starting with 1)

Examples

Define a single column ListBox without a column header. Its rule is activated with a single mouse button click:

ListBox example1
{
   .x = 1
   .y = 11
   .w = 60
   .h = 20
   .rule = 3
   .singleclick = 1
}

Define a ListBox with three columns:

ListBox example2
{
   .x = 1
   .y = 11
   .w = 60
   .h = 20
   .rule = 3

   ListBoxHeader col1
   {
      .title = "Pos"
      .w = 10
   }

   ListBoxHeader col2
   {
      .title = "Item"
      .w = 10
   }

   ListBoxHeader col3
   {
      .title = "Description"
      .w = 45
   }
}

Usage of the columnorder attribute:

! Set the column delimiter to the pipe character
  DLG SET "My_dialog.My_listbox.delim","|"

! Rearrange 5 columns in reverse order
  DLG SET "My_dialog.My_listbox.columnorder","5|4|3|2|1"

! Hide the first and last column, leave the other columns unchanged
  DLG SET "My_dialog.My_listbox.columnorder","!|*|*|*|!"

! Exchange the last 2 columns, leave the other columns unchanged
  DLG SET "My_dialog.My_listbox.columnorder","*|*|*|>|>"

Usage of the sortsequence attribute:

! Set the column delimiter to the pipe character
  DLG SET "My_dialog.My_listbox.delim","|"

! Sort the last column in ascending order
  DLG SET "My_dialog.My_listbox.sortsequence","*|*|*|*|A1"

! Primary sort sequence is column 1 in ascending order
! Secondary sort sequence is column 2 in descending order
  DLG SET "My_dialog.My_listbox.sortsequence","A1|D2|*|*|*"

! Sort the last column in descending order
! Disable sorting for columns 1, 2 and 4
  DLG SET "My_dialog.My_listbox.sortsequence","!|!|*|!|D1"

Deriving ListBox and ListBoxHeader objects from a model dialog:

# ListBoxHeader objects must always be contained in a ListBox object.
# This also applies to a model definition, such as:

Dialog Model
{
  ListBox Lb
  {
    .delim = "|"
    .gridcolor = "#c000c0"
    .hlines = 1
    .vlines = 1
  }

  ListBox LbH
  {
    ListBoxHeader Text
    {
      .align = "left"
      .coltype = 1
      .autowidth = 1
    }

    ListBoxHeader Num
    {
      .align = "right"
      .coltype = 2
      .autowidth = 1
    }
  }
}

# The example below illustrates how both the ListBox as well as the
# contained ListBoxHeader objects are derived from a model dialog:

Dialog My_dialog
{
  ...

  Model.Lb My_listbox
  {
    .x = 1
    .y = 4
    .w = 60
    .h = 30
    .rule = 42

    Model.LbH.Text Custno
    {
      .title = "Customer Number"
    }

    Model.LbH.Text Name
    {
      .title = "Name"
    }

    Model.LbH.Num Turnover
    {
      .title = "Turnover"
    }
  }
}

Using HTML content in a ListBox:

! Content of first column is centered
  DLG SET "My_dialog.My_listbox.col1.align","center"

! Set the column delimiter to the pipe character
  DLG SET "My_dialog.My_listbox.delim","|"

! Set the row height to 32 pixels
  DLG SET "My_dialog.My_listbox.rowheight",32

! Add a line containing an image in the first column
! and a colored text in the second column.
! The image height is assumed to be 32 pixels.

  Row$="<html><img src='http://my_server/my_image.gif'></html>"
  Row$=Row$&"|<html><font color='red'>Some Text In Red</font></html>"
  DLG SET "My_dialog.My_listbox.add",Row$