LISTVIEW

PLBCMP GUI Only

The LISTVIEW instruction defines an object that displays items using one of four different views. You can arrange items into columns with or without headings, icons or accompanying text. To define a LISTVIEW, use one of the following statement formats:

(1)	[label]	LISTVIEW	[%]
(2)	[label]	LISTVIEW	(arraysize)
(3)	[label]	LISTVIEW	^
(4)	[label]	LISTVIEW	^,{target}
(5)	[label]	LISTVIEW	^(arraysize)
(6)	[label]	LISTVIEW	^(arraysize),({target}),...,({target})

Where:

label

Optional. A Data Label.

Optional. Denotes the item as being GLOBAL.

arraysize

Required. An integer decimal constant, CONST variable, or EQUATEd value indicating the number of array items.

Optional. Denotes the item as being a POINTER.

target

Required. The name of a previously defined data item of the same type.

Flags Affected: NONE

Note the following:

The LISTVIEW displays a collection of items.
Each item in the list has a label.
Each item in the list can optionally have both a large and small icon or bitmap associated with it.
Each item can also have a four byte user-defined value associated with it.
Associated with each item can be any number of sub-items or columns butall items must have the same number of sub-items.
A sub-item contains a text string that appears next to the item in report view.
A LISTVIEW object can be displayed in one of four different views as specified by the VIEWSTYLE property:

a list using the item's large (or standard) icons that fills horizontally and wraps when the line is filled.

a vertical list using the small icons that fills horizontally and wraps when the line is filled.

a list that fills vertically and then wraps to start a new column

a report this is only filled vertically and does not wrap.

Multi-dimension arrays are supported up to a maximum of fourteen dimensions.
The ^ denotes Pointer Variable.
Although a LISTVIEW may be defined as Global, it is DESTROYed during a CHAIN instruction.
The LISTVIEW object supports a double click event ($DBLCLICK).
The click or double-click events are generated with the left or right mouse buttons. The event modifier variable as specified in EVENTREGISTER or EVENTINFO contains the left or right mouse indicator.
When a click or double click event occurs, the event result variable contains the current row item number that has the item focus. A click or double click event does not occur unless a row item number is being selected or has already been selected. If the click or double click is performed on row data other than the left most column data, the result always returns the item number that currently has the focus.
The PL/B Web Server LISTVIEW object supports an UPDATED event ($UPDATED). This event can only be generated after an end-user keyed action has modified a cell while the SetEditColumn method is being used.
When using LISTVIEW methods that use the Column names for XML output, the Column names must conform to XML Basic requirements. See the XML Basics description for more details. This is the basic description where LISTVIEW Columns are output as XML tag names:

" Tag names are case-sensitive and must start with letters, or an underscore. The rest of the tag name can contain letters, digits, hyphens, underscores, and periods."

When the LISTVIEW Column names contain invalid characters for XML tag names, the $LV_XMLWR_OUTPUTASATTR option should be used where appropriate for the LISTVIEW methods being used.

The LISTVIEW object allows specification of the foreground color, background color, and font attributes for individual cells using five methods.

The InsertAttrColumn method adds a hidden column to the LISTVIEW that contains attribute data strings. The SetItemText method may then set a specialized formatted attribute string for a row item in the attribute data column. The attribute data string is formatted to provide default settings followed by individual column attribute settings that are used for a specific LISTVIEW row.

The {default} and {column} strings are composed of three (3) subfields that provide index numbers separated by a comma. The {default} and each {column} subfield group must be separated by a semicolon. The format of the attribute data strings must be given as follows:

"{default};{column1};{column2};....;{columnx}"

Where:

default

Optional. The {default} field gives default foreground color, background color, and font indexes for this row. The {default} field is composed of three subfield indexes that reference attribute tables that have been setup for a LISTVIEW object.

column1 - columnx

Optional. The {column1} field is optional and if specified gives the specific color and font attribute indexes for column one for this row. This same field definition format applies for all columns that exist in the LISTVIEW object.

The string format for the {default} and {column} fields are defined as follows:

"{fgNDX},{bgNDX},{fontNdx}"

Where:

fgNDX

This subfield is a decimal number that is an index to retrieve a foreground color from the color table that has been created for the LISTVIEW object. The {fgNDX} decimal number value can be from one (1) to twenty (20).

bgNDX

This subfield is a decimal number that is an index to retrieve a background color from the color table that has been created for the LISTVIEW object. The {fgNDX} decimal number value can be from one to twenty.

fontNDX

This subfield is a decimal number that is an index into the font table that has been created for the LISTVIEW object. The {fontNDX} decimal number value can be from one to twenty.

Example Attribute Strings:

"1,1,1;2,3,4"

In this example, the default attribute field has specified an index value of one for the foreground color, the background color, and the font. This attribute also specifies that the first column of the LISTVIEW object uses an index value of two (2) for the foreground color, an index value of three (3) for the background color, and an index value of four (4) for the font. All subsequent columns are to use the default.

",2;1,3;;4"

In this example, the default attribute field has only specified an index value of two for the background color. In this case, the default foreground color and font are determined from the default attribute data settings that have been setup for the LISTVIEW object. For the first column of the LISTVIEW, the index value one retrieves the foreground color while the index value three retrieves the font. The second column of the LISTVIEW uses only default values. The third column of the LISTVIEW uses the index value of four to retrieve the foreground color. Again, all other attributes are specified by the default settings.

The general program logic flow to make use of the LISTVIEW color and font features to control individual cell attributes is:

Create a LISTVIEW object.
Use the InsertAttrColor, InsertAttrRGB, and InsertAttrFont methods to initialize the color and/or the font index tables for the LISTVIEW object.
Use the InsertAttrDefault method to set the default attribute settings.
Use the InsertAttrColumn method to put an attribute column into the LISTVIEW object.
Use the SetItemText method to define the attribute data strings for each row of the LISTVIEW desired. If an item in the attribute column does not have an attribute string, the default settings are used.