.
Eloquence JDLG contact contact


JDLG object and attribute reference:
ListBox and ListBoxHeader classes

 
.
  Document revision: 2024-05-27
Refers to JDLG version: 2.0.18


Contents


A ListBox provides a selection of multiple lines where each line optionally consists of multiple columns. A single current line is maintained by the cy attribute that is affected by the activeitem and activeline attributes. The current line is visually highlighted and also used to specify the current insertion and deletion position (delln, ins and line attributes).

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, which may be programmatically enabled or disabled:

  • The user may use the column context menu (by clicking the context menu 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, fourth ... sort column.

Note: When sorting a ListBox which contains HTML content, the affected column(s) are sorted based on the plain content, not the HTML content, i.e., any HTML tags and attributes are internally removed from the content before sorting takes place.

activecolumn : integer, get
A mouse click which submits a rule or starts a drag & drop operation sets activecolumn to the physical index of the clicked column (starting with 0).

Note: activecolumn is -1 if a rule submission is not caused by a mouse click or a drag & drop operation originating from this ListBox, or if the ListBox does not contain ListBoxHeader objects.

activeitem : integer, get/set
Current active line (starting with 1, 0 = no active line).
Notes:
  • Setting activeitem always affects cy.
  • This is also the line where a drag originated.
activeline : integer, get/set
Current active line (starting with 1, 0 = no active line).
Notes:
  • Setting activeline to a nonzero value affects cy.
  • This is also the line where a drag originated.
add : string, set
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, get/set
Alternative background color in hexadecimal #RRGGBB notation, used for even lines in the list (please refer to the documentation of the common bgcolor attribute for examples).

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 below.

border : integer, get/set
Provided for ASCII DLG backward compatibility.

The ListBox border visibility and thickness 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.

The default value is 1.

class : string, get
Returns "ListBox".
clear : integer or string, set
Deletes all lines in the list. The argument is ignored.
colcontextmenu : integer, get/set
Nonzero (default): The column context menu to show or hide selected columns is enabled.

Zero: The column context menu is disabled.

column[] : string, get
Returns the path of the ListBoxHeader object associated with the specified column (starting with 1).

Note: ERROR 660 is issued if the specified column does not exist.

columnorder : string, get/set
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 v character to make a column visible
  • 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)

The default value is: 0 1 ... n-1

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).

See also the examples below.

Note: Using the v character requires JDLG version 1.7.0 or newer.

colmargin : integer, get/set
Specifies the default left/right margin for the column cell content.

For details, please refer to the ListBoxHeader.margin documentation below.

Notes:

  • The ListBoxHeader.margin attribute may be used to specify the margin for a specific column.

  • The margin does not apply to the column title.

  • Requires JDLG version 1.7.2 or newer.
columns : integer, get
Returns the current number of columns.
content : string, get/set
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 : integer, get
No function (provided for ASCII DLG backward compatibility).
cy : integer, get/set
Current line (starting with 0).
Note: This is also the line where a drag originated.
delim : string, get/set
Column values are separated by this delimiter.
By default, the TAB character (ASCII 9) is used.
delln : integer, set
Deletes the specified number of lines, starting with the current line (cy).
fgcolor2 : string, get/set
Alternative foreground color in hexadecimal #RRGGBB notation, used for even lines in the list (please refer to the documentation of the common bgcolor attribute for examples).

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 above.

gridcolor : string, get/set
Color of grid lines in hexadecimal #RRGGBB notation, effective if hlines and/or vlines is set (please refer to the documentation of the common bgcolor attribute for examples).
hlines : integer, get/set
Zero (default): Horizontal grid lines are not displayed.
Nonzero: Horizontal grid lines are displayed.
See also vlines below.
hsb : integer, get/set
No function (provided for ASCII DLG backward compatibility).
The horizontal scroll bar is displayed if required.
See also vsb below.
ins : string, set
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 : integer, get
Returns the current content size (total number of characters).
line[] or line : string, get/set
Used to get or set the line with the specified index (starting with 1). If used without an index or with a zero index, the current line (cy) is affected.

Columns are separated by the delimiter specified by the delim attribute.

Note: On DLG SET, a new line is appended if the specified line does not exist. On DLG GET, if used with an index, ERROR 660 is issued if the specified line does not exist. If used without an index or with a zero index, DLG GET returns an empty string if the specified line does not exist.

modelorder[] : integer, get
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.

Note: If the line does not exist, the specified view index is returned.

See also vieworder below.

movable : integer, get/set
Nonzero (default): The columns may be rearranged by dragging the column titles into a new position.

Zero: The column titles may not be dragged into a new position.

multiline : integer, get/set
No function (provided for ASCII DLG backward compatibility).
newline : integer, get/set
Zero (default): Lines are separated by LF (ASCII 10).
Nonzero: Lines are separated by CR/LF (ASCII 13, 10).
resetorder : integer, set
Arranges all columns in physical order, retaining the current line sorting. If a nonzero argument is specified, in addition all hidden columns are made visible.
rowdata[] or rowdata : integer or string, get/set
User-defined data stored for the line with the specified index (starting with 1). If used without an index or with a zero index, the current line (cy) is affected.

DLG SET defines the data type (integer or string).

Note: ERROR 660 is issued if the specified line does not exist.

rowheight : integer, get/set
Specifies the minimum row height.

The default rowheight value is zero, which causes the row height to be 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 : integer, get/set
If nonzero, the rule value is returned to the program, along with the path of the ListBox object (see also ruleoverride below), when an action is triggered. The kind of action that causes a rule submission is specified by the singleclick attribute (see below).

When a rule is submitted, the cy, activeitem and activeline attributes are set. If the rule submission is caused by a mouse click, the activecolumn attribute is set in addition.

The default rule value is zero.

See also the documentation of the common rule attribute.

rulekey : integer, get
If a rule submission is caused by keyboard input, this is the related key code.

Key codes:
10 ENTER
32 SPACE

Key codes other than ENTER or SPACE are cursor navigation keys, a rule submission happens only if the singleclick attribute value is 2 or 3:
33 PAGE UP
34 PAGE DOWN
35 END
36 HOME
38 UP
40 DOWN
224 Numpad UP (see note below)
225 Numpad DOWN (see note below)

The rulekey value is zero if a rule submission is not caused by keyboard input.

Notes:

  • Requires JDLG version 2.0.14 or newer.

  • Since JDLG version 2.0.16 the returned Numpad UP/DOWN key codes are the same as the UP/DOWN key codes:
    38 Numpad UP
    40 Numpad DOWN
ruleoverride : integer, get/set
If nonzero, the rule of a previously focused EditText or ComboBox object is overridden (the ListBox rule value combined with the EditText or ComboBox path is returned).

The default ruleoverride value is zero.

For details, please refer to the RuleOverride documentation.

singleclick : integer, get/set
Specifies which action should activate a rule submission:
0 (default)  rule submission on mouse button double click, ENTER and SPACE keys
1  rule submission on mouse button single click, ENTER and SPACE keys
2  rule submission on mouse button double click, ENTER and SPACE keys, UP/DOWN cursor keys
3  rule submission on mouse button single click, ENTER and SPACE keys, UP/DOWN cursor keys
Note: Since JDLG version 2.0.16 the mouse button single click behavior is configured by the eloquence.config.delay.singleclick property.
sizable : integer, get/set
Nonzero (default): The user may change the column width.
Zero: The column width is fixed.

Note: The ListBoxHeader.resizable attribute allows to specify this for an individual column. If ListBox.sizable is zero, ListBoxHeader.resizable has no effect.

sortrule : integer, get/set
Alias for the vcrule attribute, provided for backward compatibility. (Note: Requires JDLG version 1.7.2 or newer.)
sortsequence : string, get/set
Used to get or 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.

The default value is: * ... *

See also the examples below.

status : string, get/set
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, get/set
No function (provided for ASCII DLG backward compatibility).
toolhelp[] : string, get/set
Used to get or set toolhelp text for the line with the specified index (starting with 1). If used with a zero index, the current line (cy) is affected.

For ListBox lines not having a specific toolhelp text, the common toolhelp text is displayed if set.

If set to an empty string, a previously set toolhelp text is deleted for the line with the specified index.

See also the documentation of the common toolhelp attribute.

Note: Requires JDLG version 2.0.14 or newer.

topitem : integer, get/set
Current topmost line (starting with 0).
vactiveline : integer, get/set
Current active line in view order (using the current line sort sequence, starting with 1, 0 = no active line).

Note: Setting vactiveline 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, get
Returns the path of the ListBoxHeader object associated with the specified column in view order (using the current column order, starting with 1).

Note: ERROR 660 is issued if the specified column does not exist.

vcolumns : integer, get
Returns the number of columns currently visible.
vcontent : string, get
Used to get all lines in view order (using the current line sort sequence and column 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.

vcrule : integer, get/set
If nonzero, the vcrule value is returned to the program, along with the path of the ListBox object, when the user has modified a ListBox view property (column order and visibility, sort sequence).

The default vcrule value is zero.

See also the documentation of the common rule attribute.

Note: Requires JDLG version 2.0.6 or newer. Replaces the sortrule attribute which was introduced with JDLG version 1.7.2.

vheight : integer, get
Returns the current number of lines.
vieworder[] : integer, get
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.

Note: If the line does not exist, the specified physical index is returned.

See also modelorder above.

vline[] : string, get
Used to get the line with the specified index in view order (using the current line sort sequence and column order, starting with 1).

Invisible columns are skipped.

Columns are separated by the delimiter specified by the delim attribute.

Note: ERROR 660 is issued if the specified line does not exist.

vlines : integer, get/set
Zero (default): Vertical grid lines are not displayed.
Nonzero: Vertical grid lines are displayed.
See also hlines above.
vsb : integer, get/set
No function (provided for ASCII DLG backward compatibility).
The vertical scroll bar is displayed if required.
See also hsb above.
vwidth : integer, get
Returns the number of characters of the currently widest line.


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

Please refer to the ListBox introduction for further details.

Notes:

  • The ListBoxHeader.w attribute is used to specify the column width in font raster units or pixel units (see below).

  • The ListBoxHeader.h attribute has no function and is ignored.

align : string, get/set
Specifies how a column's content is horizontally aligned.

Possible values are:
 "left"
 "center"
 "right"

The default value is "left".

Note: This affects the column's content, not the title.

autowidth : integer, set
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 set to a nonzero value.

class : string, get
Returns "ListBoxHeader".
coltype : integer, get/set
Specifies the type of a column.

The following types are supported:
 0: alphanumeric
 1: numeric
 2: boolean (nonzero or zero)
 3: bar graph display
 4: undefined, currently not supported
 5: folded alphanumeric
 6: date

The default value is 0 (alphanumeric).

Types 0 and 1 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 1, otherwise sorting the column probably results in an unexpected sequence.

The format of numeric column values (coltype 1) may be specified with the format attribute (see note below).

If coltype is set to 2 a checkbox is displayed. The state of the checkbox depends on whether the value is nonzero or zero.

The purpose of type 3 is to display a column consisting of bar graphs. A bar graph column value consists of two values separated by 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.

With type 0, a non-folded sort sequence is used for alphanumeric data (such as abc...ABC...). Type 5 may be used to specify a folded sort sequence (aAbBcC...zZ...).

Type 6 may be used to display date values that are correctly sorted. A date value is expected to have a YYYYMMDD format, for example 20110124 for 24. January 2011. The output is then formatted as DD.MM.YYYY unless otherwise specified by the format attribute, for example 24.01.2011 (see note below).

Note: Using a format for coltypes 1 or 6 requires JDLG version 1.7.2 or newer.

format : string, get/set
Specifies the format for numeric or date columns.

If coltype is 1 (numeric) the column values are expected as integer or floating point number:
 1. optional leading minus sign
 2. optional pre-decimal digits
 3. optional decimal point (.)
 4. optional post-decimal digits
The format string is parsed for special characters which specify how the column values are formatted:
Character  Function
0 Digit
# Digit, zero shows as absent
. Decimal separator
, Grouping separator
; Separates positive and negative subpatterns
% Multiply by 100 and show as percentage
' Quote special characters, for example:
'#'# → #123
# o''clock → 12 o'clock
The decimal and grouping separators are formatted according to the current locale. For example, the English locale uses the point as decimal separator and the comma as grouping separator, the German locale uses the comma as decimal separator and the point as grouping separator. The grouping separator is used to prefix a constant number of digits between the grouping characters.
German locale examples:
Format  Positive  Negative
#0.00 1234,56-1234,56
,##0.00 1.234,56-1.234,56
,##0.00;(,##0.00) 1.234,56(1.234,56)

If coltype is 6 (date) the column values are expected to have a YYYYMMDD format, for example 20110124 for 24. January 2011. The format string is parsed for special characters which specify how the column values are formatted:
Character  Function  Examples
y Year 1996; 96
M Month in year July; Jul; 07
d Day in month 10
E Day in week Tuesday; Tue
F Day of week in month 2
D Day in year 189
w Week in year 27
W Week in month 2
The month and day names are formatted according to the current locale.
Examples:
Format  Display
dd.MM.yyyy 31.12.2015
MM/dd/yyyy 12/31/2015
yyyy-MMM-dd 2015-Dec-31 (English)
2015-Dez-31 (German)

Notes:

  • Depending on the Java version the supported formatting characters may vary. The characters documented above are supported in all Java versions. For details, please refer to the Oracle java.text.DecimalFormat and java.text.SimpleDateFormat documentation.

  • Requires JDLG version 1.7.2 or newer.
index : integer, get
Returns the physical column index (starting with 0).
line[] or line : string, get/set
Used to get or set the cell in a column with the specified line index (starting with 1). If used without an index or with a zero index, the current line (Listbox.cy) is affected.

Note: ERROR 660 is issued if the specified line does not exist.

margin : integer, get/set
Specifies a left/right margin for the column cell content.

Possible values are:
0 (default)  no margin
1  left/right margin, width is 50% of the Dialog raster width
>1  left/right margin, width is the specified Dialog raster width percentage, for example DLG SET "ListBox.colmargin",30 sets the margin width to 30% of the Dialog raster width

Notes:

  • The ListBox.colmargin attribute may be used to specify the default margin for all columns.

  • The margin does not apply to the column title.

  • Requires JDLG version 1.7.2 or newer.
resizable : integer, get/set
Nonzero (default): The user may change the column width.
Zero: The column width is fixed.

Note: If ListBox.sizable is zero, this has no effect.

textpos : string, get/set
Alias for the align attribute (provided for backward compatibility).
title : string, get/set
Column title.
userhide : integer, get/set
Nonzero (default): The column is included in the column context menu, allowing the user to show or hide the column.

Zero: The column is not listed in the column context menu, allowing for permanently visible or invisible columns.

Note: Requires JDLG version 2.0.14 or newer.

vindex : integer, get
Returns the column view index (using the current column order, starting with 0).
visible : integer, get/set
Nonzero (default): The column is visible.
Zero: The column is invisible (hidden).

Note: Corresponds to the column context menu and the columnorder attribute.

vline[] : string, get
Used to get the cell in a column with the specified line index in view order (using the current line sort sequence, starting with 1).

Note: ERROR 660 is issued if the specified line does not exist.

w : integer, get/set
Column width in font raster units or pixel units, depending on the value of the sizeraster attribute.

If font raster units are used, the value of the w attribute is multiplied by the font width of the "X" character plus a margin of two raster units.

The default column width is 8 raster units.

Note: Using pixel units requires JDLG version 1.7.0 or newer.


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","4|3|2|1|0"

! 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:

# 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 = 0
      .autowidth = 1
    }

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

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

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$


 
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision: 2024-05-27  
  Copyright © 1995-2024 Marxmeier Software AG