|
Document revision: 2024-05-27
Refers to JDLG version: 2.0.18
Contents
ListBox class
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:
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.
ListBoxHeader class
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:
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.
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","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$
|
|