Eloquence JDLG - ListBox and ListBoxHeader classes reference


	Home

	Search

	Product Information

	Support

	Knowledge Base

	Documentation

	Download

	Feedback


Eloquence JDLG
Documentation / Eloquence JDLG / Object and attribute reference / ListBox JDLG object and attribute reference: ListBox and ListBoxHeader classes

Document revision: 2023-02-22
Refers to JDLG version: 2.0.16

Contents

ListBox class
ListBoxHeader class
Examples

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

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.

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$


	Privacy \| Webmaster \| Terms of use \| Impressum	Revision: 2023-02-22
	Copyright © 1995-2021 Marxmeier Software AG

JDLG object and attribute reference: ListBox and ListBoxHeader classes

JDLG object and attribute reference:
ListBox and ListBoxHeader classes