List Box Controls 

List Box Type

 

The style of the List Box is determined by selecting a List Box Type:

 

Standard

Used to review and access a single column of data.

 

Formatted

Used to define multiple columns, line breaks and other formatting.

 

List View

Produces vertically wrapping columns (with optional bitmaps) where only the first element of each record is displayed.

 

Report View

Displays multiple data elements in a tabular list with the use of headings and other attributes.

 

Tree View

Provides a tree-like structure view with optional bitmaps.

Depending on the type selected, the contents of the List Box Properties dialogue changes to represent the options available for that particular style of List Box.

A system popup menu consisting of extraction, search and print options can also be added to any Grid or List Box (except Tree Views). See List Box and Grid System Popup Menu.

Standard

For the List Box Type, select Standard. The Standard List Box allows users to review and access a single column of data.

Example:

When creating or editing a Standard List Box control, the List Box Properties dialogue (pictured below using the Folder Style version of the NOMADS designer) is displayed:

Dynamic Control Properties

PxPlus 2018 introduces the capability to create dynamic control properties for List Box controls when combined with Data Classes. Dynamic data classes are created by selecting the Dynamic check box in Data Class Definitions maintenance. At run time, dynamic control properties are evaluated and automatically populated with values based on what is defined in the data class.

When a data class is entered for the List Box control, information from the data class is loaded into the List Box properties. If the data class is dynamic, the dynamic control properties are automatically set to Dynamic initially and assigned a %NOMADS'class' variable that corresponds to a data class field (i.e. %NOMADS'class'length).

List Box control properties designated as dynamic can be manually switched to dynamic or non-dynamic. A List Box control can have a combination of dynamic and non-dynamic control properties only when a data class is entered.

See Dynamic Control Properties for information and examples.

Note:
Dynamic control properties are supported in NOMADS and iNomads environments.

List Box Properties

This dialogue is divided into the following tabbed panels for viewing and/or changing List Box properties: Display, Font/Color, Attributes, Values, Logic, User Aid and Query.

Name

Unique name of the List Box control (NOMADS provides a default). Naming conventions for variables apply. Click the Browse Library button to copy parameters from an existing object (via the Library Browse dialogue).

Note:
When a new control name is entered, it will be checked against the Reserved Words list to determine if it is restricted for use as a NOMADS control name. If it is found, a warning message will display.

(User Reserved Words Maintenance was added in PxPlus 2020.)

Class

Enter a Data Class to load the information from the data class definition into the control's properties.

If using Property Sheets, click the Data Class button and enter a data class in the Data Class Options dialogue.

(The Data Class Options dialogue was added in PxPlus 2018.)

To enter a data class, use any of the following methods:

  • Click the Query button (binoculars) to select from a list of predefined data classes (if any) for the current control type.
  • Type the name of an existing data class. Only data classes for the current control type are allowed.
  • Create a data class on the fly. Enter a new Class name and respond Yes to the displayed message, which launches Data Class Definitions.

If the data class is changed, a message will display prior to overwriting any information. This works similar to using the Reapply Data Class button.

If the data class assigned to the control is deleted in Data Class Definitions, the text ** Class not on File ** will display (will be a message box if using Property Sheets).

(Dynamic data classes and properties were added in PxPlus 2018.)

(Data Class Maintenance)

Click this button to launch Data Class Definitions for creating or editing a data class.

If using Property Sheets, click the Data Class button, then click the Data Class Maintenance button in the Data Class Options dialogue.

(The Data Class Options dialogue was added in PxPlus 2018.)
(The Data Class Maintenance button was added in PxPlus 2018.)

(Reapply Data Class)

(Available when a data Class is entered)

Click this button to update control properties with current information from the selected data class. A message displays before any control properties are overwritten.

If using Property Sheets, click the Data Class button and select the Reapply Class check box in the Data Class Options dialogue.

(The Data Class Options dialogue was added in PxPlus 2018.)

Important Note:
Care should be taken when using the Reapply Data Class button or changing the data Class entered for the control, as this will overwrite any existing values.

If the Dynamic (from Data Class) check box was manually changed on the User Aid and/or Query tabs, clicking the Reapply Data Class button will reselect this check box if the data class entered for the control is dynamic or deselect it if not dynamic.

(The Reapply Data Class button was added in PxPlus 2018.)

Dynamic Class

(Display Only)

Indicates whether the selected data Class is Dynamic. See Dynamic Control Properties.

If using Property Sheets, click the Data Class button to display the Dynamic Class check box in the Data Class Options dialogue.

(The Data Class Options dialogue was added in PxPlus 2018.)
(The Dynamic Class check box was added in PxPlus 2018.)

Preview

Displays how the visible properties of the control will appear at run time.

Display ( * indicates a Dynamic property)

List Box Type

Select the style of List Box:

Standard

(Default) Used to review and access a single column of data.

Formatted

Used to define multiple columns, line breaks and other formatting.

List View

Produces vertically wrapping columns (with optional bitmaps) where only the first element of each record is displayed.

Report View

Displays multiple data elements in a tabular list with the use of headings and other attributes.

Tree View

Provides a tree-like structure view with optional bitmaps.

If the List Values drop box (on Display tab) is set to Dynamic, List Box Type will be locked.

(Dynamic data classes and properties were added in PxPlus 2018.)

*List Values

List of values that NOMADS uses to preload the List Box. Can be Fixed value, string Expression or Dynamic. (Dynamic is available only when a data Class is entered.)

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

If the List Values drop box is set to Dynamic, the following properties will be locked: List Box Type, Format, Default Setting and Translation.

(Dynamic data classes and properties were added in PxPlus 2018.)

Position

Column

Starting column for the top left corner of the control - numeric expression. Format mask is ##0.00. Valid entries are 0 to 620.

Line

Starting line for the top left corner of the control - numeric expression. Format mask is ##0.00. Valid entries are 0 to 255.

(Support for increased Column and Line maximums was added in PxPlus 2021.)

Size

Width

Width of the control in number of columns - numeric expression. Format mask is ##0.00. Valid entries are 0 to 620.

Height

Height of the control in number of lines - numeric expression. Format mask is ##0.00. Valid entries are 0 to 255.

Note:
If a data class is entered and the List Box Width/Height values in the data class are subsequently changed, the size of the List Box will not change when the Reapply Data Class button is selected.

(This functionality was added in PxPlus 2018.)

(Support for increased Width and Height maximums was added in PxPlus 2021.)

Attributes

Optional attributes for Tab Stop, Variable Input, Initially Disabled and Initially Hidden. See Attributes.

*Input Length

(Applicable when List Box Type is Standard and Variable Input check box is selected)

Maximum input characters. Can be Fixed, numeric Expression or Dynamic. (Dynamic is available only when a data Class is entered.)

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

(Dynamic data classes and properties were added in PxPlus 2018.)

Font/Color ( * indicates a Dynamic property)

Font Specification

Font
Size

Click the drop-down arrow for a list of selections.

Color

For each of the following Color options, click the Query button to access Color Selections. Valid formats for color selections include predefined system colors (e.g. Light Red), Custom (RGB codes), HTML Hex Color Codes, User Defined colors (e.g. Color17) and string Expressions.

The "Demo" list box to the right provides a preview of your color selections.

Foreground
Background

Click the Query button for color selections.

Highlight 1

(Not Applicable for List View and Tree View) Background color - alternating lines. Click the Query button for color selections.

Highlight 2

(Not Applicable for List View and Tree View) Background color - alternating three lines. Click the Query button for color selections.

Line Color

(Report View and Tree View Only) Color of the lines drawn between rows and columns on a report view List Box or between entries on a tree view List Box. Click the Query button for color selections.

(The Line Color property, the Color Selections Query button and Color Selections dialog were added in PxPlus 2020.)

Attributes

Optional attributes. See Attributes below.

*Visual Class

Assign a visual class to the control. Can be Fixed, Expression or Dynamic. (Dynamic is available only when a data Class is entered.)

Click the Visual Class Maintenance button to launch the Visual Classes Maintenance utility for creating or editing visual classes.

To assign visual classes to controls at the library level, see Visual Class Assignment.

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

Note:
Visual class names that begin with an "*" (asterisk) are pre-defined visual classes used by PVX Plus and may be subject to change without notice.

(Dynamic data classes and properties were added in PxPlus 2018.)
(The Visual Class Maintenance button was added in PxPlus 2019.)

*iNomads Class

Assign an iNomads class to the control. Can be Fixed, Expression or Dynamic. (Dynamic is available only when a Class is entered.)

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

The iNomads class contains class attribute references used when defining the control in the HTML code generated in iNomads. An iNomads class reference must start with an alpha character (A-Z or a-z), followed by any combination of A-Z, a-z, 0-9, underscore or dash. Multiple references may be entered, separated by a space.

For a list of pre-defined iNomads classes, see iNomads Classes.

(Dynamic data classes and properties were added in PxPlus 2018.)

Attributes ( * indicates a Dynamic property)

Attributes

Tab Stop

Adds the control to the tab order list. Allows use of the Tab key for moving to the control.

Auto Tab Skip

Control is skipped when tabbing forward but is still accessible via Shift - Tab or the mouse.

Borderless

The control is drawn with no border or frame.

Disable On Empty

The system automatically disables the List Box when it contains no entries. When populated, the List Box is re-enabled. Overridden when the 'Enabled property is turned off. (Default is Off.)

Initially Disabled

Control region is grayed out and is not accessible to the user for input. The control is accessible programmatically.

Initially Hidden

Control is not displayed but is accessible programmatically.

Enable Scrolling

Allows the control to scroll in a resizable/scrollable dialogue box. See Panel Resizing.

Signal On Exit

A signal is generated when focus leaves the control whether the selection or value has changed or not. NOMADS will execute the On Change logic.

Automatic (Signal All Changes)

A signal is returned on any changes in the control.

Strip Trailing Spaces

Strips trailing spaces when reading/writing data for control.

Ignore Change Flag

Select this check box when you do not want the NOMADS CHANGE_FLG variable to be updated when the control value is changed.

(The Ignore Change Flag property was added in PxPlus 2017.)

Standard Listbox Attributes

Allow Variable Input

Enables the user to select any element from the list or enter any other value. See Variable List Box.

Multiple Selections

Users can select more than one entry from the List Box.

No Height Adjustment

The List Box will not be forced to show only complete lines. The last line will be truncated horizontally (i.e. displaying a partial line to ensure that the height of the List Box matches the size defined). See Resizing Input Controls.

Load Options

Smart Load
(formerly Auto Load)

Select this button to set up a Smart control that will self-load based on a query definition. See Smart Controls.

Background Loading

Load logic to execute while there is no user input. Select Background Loading and then click the Logic button to add/edit logic. See Background Loading.

Load on Demand

Logic to execute when a load on demand signal occurs. The signal will occur when the user scrolls the List Box items into view. Select Load on Demand and then click the Logic button to add/edit logic. See Load on Demand.

Note:
Smart controls are not compatible with Load on Demand or Background Loading logic.

(Support for enhanced Smart Load capability was added in PxPlus 2018.)

Other

Alt-Key

Hot key for the control. Click the drop-down arrow for a list of selections.

*User Tag Field

For controls, data/tag field that can be used to pass information on such things as formatting, error messages or validation rules. Can be Fixed, Expression or Dynamic. (Dynamic is available only when a data Class is entered.) Field contents are placed in a variable using the control name with a .TAG$ extension. If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

Object Persistence

Sets Object Persistence. Click the drop-down arrow for a list of selections:

Default

Set via global variable

Always

On, overriding global activation

Never

Off, overriding global activation

(Dynamic data classes and properties were added in PxPlus 2018.)

Values ( * indicates a Dynamic property)

*Default Setting

Initial value to be highlighted when the List Box is drawn (Fixed value or string Expression).

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked. See Dynamic Control Properties.

If the List Values drop box (on Display tab) is set to Dynamic, the Default Setting property will be set to Dynamic and locked.

(Dynamic data classes and properties were added in PxPlus 2018.)

*Translation

Click the Translate check box to set up a table of values representing List Box selections. Definition consists of a Table Value Length (length of each of the items in the table) and the Translation value (Fixed or string Expression).

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked. See Dynamic Control Properties. If the dynamic data class was defined with Load From File functionality, the Table Value Length will be set to 0 and locked.

If the List Values drop box (on Display tab) is set to Dynamic, the Translation properties and values will be locked.

(Dynamic data classes and properties were added in PxPlus 2018.)
(The setting of Table Value Length to 0 when entering a dynamic data class with Load From File functionality was added in PxPlus 2021.)

Logic

Default Program

Displays the name of the Default Program used in the Panel Header definition.

(The Default Program was added for display in PxPlus 2019.)

Post Create

Logic to be processed after the control is drawn. Click the drop-down arrow for a list of selections. See Events Logic.

Click the Program Logic button beside the Perform or Call action to launch the default program editor, which is typically the *IT - Integrated Toolkit. To make Ed+ the default program editor, change the setting for the %NOMADS'Program_Editor property to Ed+.

(The ability to set Ed+ as the default program editor was added in PxPlus 2023.)

When Receiving Focus

Logic to execute when the control receives focus. Click the drop-down arrow for a list of selections. See Events Logic.

Click the Program Logic button beside the Perform or Call action to launch the default program editor, which is typically the *IT - Integrated Toolkit. To make Ed+ the default program editor, change the setting for the %NOMADS'Program_Editor property to Ed+.

(The ability to set Ed+ as the default program editor was added in PxPlus 2023.)

When Entry is Selected from List Box

Logic to be executed when focus leaves the control or the state of the control has changed. Click the drop-down arrow for a list of selections. See Events Logic.

Click the Program Logic button beside the Perform or Call action to launch the default program editor, which is typically the *IT - Integrated Toolkit. To make Ed+ the default program editor, change the setting for the %NOMADS'Program_Editor property to Ed+.

(The ability to set Ed+ as the default program editor was added in PxPlus 2023.)

User Aid ( * indicates a Dynamic property)

Dynamic (from Data Class)

(Available when a data Class is entered)

If selected, identifies which Help Reference properties are dynamic. If a dynamic data class is entered, this check box is automatically selected. If the data class is not dynamic, this check box can be manually selected.

Note:
If the Dynamic (from Data Class) check box was manually changed on the User Aid and/or Query tabs, clicking the Reapply Data Class button will reselect this check box if the data class entered for the control is dynamic or deselect it if not dynamic.

(Dynamic data classes and properties were added in PxPlus 2018.)

*Help Reference

Help text to be invoked at run time by pressing Shift - F1 while focus is on a control.

Type

Select from External or Internal help types:

External

(Default) Standard Windows help system consisting of a help File Name (.html, .hlp, .doc, etc.) and an optional Keyword or Reference number (Fixed value or string Expression).

Internal

Application supplied message text (Fixed value, string Expression or Message Library Reference).

File Name

Name of the help file.

Keyword

Indicates that the text in the adjacent field is the index entry for the topic in the indicated help file.

Reference

Indicates that the adjacent field contains the reference number for a specific topic in the context sensitive help.

Popup

Select this check box to display the help topic as a popup rather than as an independent window.

Test

Tests the current help settings.

If the Dynamic (from Data Class) check box is selected, the Help Reference properties will be dynamic and locked. See Dynamic Control Properties.

(Dynamic data classes and properties were added in PxPlus 2018.)

*Floating Tip

Mouse pointer message for the control. Can be a Fixed value, string Expression, Message Library Reference or Dynamic. (Dynamic is available only when a data Class is entered.)

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

You can customize the floating tip by adding a tip title, descriptive tip text and a hyperlink. These features enhance the visual display and functionality of the tip by providing users with much needed information at their fingertips. You can define either a Standard tip or an HTML tip that provides a simplified HTML Editor for customizing the tip text. To do this, click the button to the right of the Floating Tip multi-line input to invoke the Define Info Tip dialogue. See Defining an Info Tip.

Note:
The Floating Tip drop box and multi-line input cannot be changed once an HTML tip has been defined.

NOMADS Wiki Help

The floating tip text can be used when displaying the Wiki Help. Info tips, however, are not supported and will be ignored.

(Support for customizing Floating Tips was added in PxPlus 2016.)
(Dynamic data classes and properties were added in PxPlus 2018.)
(Support for the use of Floating Tip text in the Wiki Help was added in PxPlus 2023.)

*Message Bar

Text to be displayed in the panel's status bar when focus is on the control. Can be a Fixed value, string Expression, Message Library Reference or Dynamic). (Dynamic is available only when a data Class is entered.)

If a dynamic data class is entered, this property will be automatically set to Dynamic and assigned a %NOMADS'class' variable, which is locked.

Note:
Expressions that come from a data class must be global variables.

If the data class is not dynamic, this property can be manually set to Dynamic. See Dynamic Control Properties.

(Dynamic data classes and properties were added in PxPlus 2018.)

Query ( * indicates a Dynamic property)

Dynamic (from Data Class)

(Available when a data Class is entered)

If selected, identifies which Query Type and its associated properties are dynamic. If a dynamic data class is entered, this check box is automatically selected. If the data class is not dynamic, this check box can be manually selected.

Note:
If the Dynamic (from Data Class) check box was manually changed on the User Aid and/or Query tabs, clicking the Reapply Data Class button will reselect this check box if the data class entered for the control is dynamic or deselect it if not dynamic.

(Dynamic data classes and properties were added in PxPlus 2018.)

*Query Type

Type of query to associate to the control: Panel, Query Program, Non-Query Logic. Valid formats include a NOMADS query object or query list, a custom query panel, or user-supplied query program. Depending on the Query Type selected, different information is entered. For an explanation of each type and the information to enter, see Query Type.

For information on assigning a query to a control, see Assigning a Query.

If setting up the List Box as a Smart control (see Smart Load attribute), you can define a query for the Smart control. See Defining Smart Controls.

If the Dynamic (from Data Class) check box is selected, the Query Type and its associated properties will be dynamic and locked. See Dynamic Control Properties.

(Dynamic data classes and properties were added in PxPlus 2018.)

 

Security

Security restrictions. See Restricting Access for information on Object Security Definition.

Groups

Assign the control to a group. See Group Assignment.

Popup Menu

Associate a popup menu that will appear when you right-click the mouse over the selected control.

To define a popup menu, see Popup Menu.

To add a system popup menu to any List Box (except tree view), see List Box and Grid System Popup Menu.

Notes

Add notes/comments for the control. Maximum 1024 characters. These notes also display in the Wiki Help documentation for the panel. See NOMADS Wiki Help.

(The Notes button was added in PxPlus 2023.)

Formatted

For the List Box Type, select Formatted. The Formatted List Box includes the ability to define multiple columns, line breaks and other formatting.

Example:

Colors can also be displayed if color mnemonics are embedded in the List Box data. Most of the properties for a Formatted List Box are identical to those required for defining a Standard List Box, except for the Allow Variable Input attribute.

On the Attributes panel, a Format button is also available:

Attributes ( * indicates a Dynamic property)

Formatted Listbox Attributes

*Format

Button that launches the Formatted List Box Definition dialogue to define List Box columns, including options for Width, Alignment, Special Options and Column Separator.

If the List Values drop box (on Display tab) is set to Dynamic, the Format button will be locked.

(Dynamic data classes and properties were added in PxPlus 2018.)

Formatted List Box Definition

The Formatted List Box Definition dialogue displays the following options and buttons:

Width

Width of the column, either a Fixed value or an Expression. To modify the Width value, click the dotted button to invoke a separate dialogue.

Alignment

Select one of the text alignment options from the drop-down list: Left, Right, Center, Numeric, Blanks (justify using blanks).

Special Options

Click the drop-down arrow for a list of selections:

None

No special options

New Line

Starts a new line in that field

Skip Field

Hides the column

Column Separator

Click the drop-down arrow to select a Hex or ASCII string value as the default column separator character.

Insert Above
Insert Below

Adds a blank row above or below the currently selected row for creating a new column.

Delete Row

Removes the currently selected row (i.e. removes the column from the List Box).

Move Up
Move Down

Changes the order of the existing columns in the List Box.

List View

For the List Box Type, select List View. The List View List Box produces vertically wrapping columns (with optional bitmaps) where only the first element of each record is displayed.

Example:

Most of the properties for a List View List Box are identical to those required for defining a Standard List Box, except for the Allow Variable Input and No Height Adjustment attributes.

On the Attributes panel, Partial Match and Full Line Highlight attributes, as well as a Format button, are available, as described below:

Attributes ( * indicates a Dynamic property)

ListView Attributes

Partial Match

Partial matches in the List Box data are highlighted. If selected, the text string used in a LIST_BOX WRITE will be considered a partial match for highlighting List Box data; e.g. if you write "ABC", then the first item that starts with "ABC" is highlighted. (If the Multiple Selections attribute is also set, all items starting with "ABC" would be selected.)

Multiple Selections

Users can select more than one entry from the List Box.

*Format

Button that launches the List View Format Definition dialogue used to define various format options (i.e. title, width, alignment, sorting, etc.) for the columns in a List View List Box. If the List Values drop box (on Display tab) is set to Dynamic, the Format button will be locked.

(Dynamic data classes and properties were added in PxPlus 2018.)

Other

Full Line Highlight

Full line highlight style allows the user to click any column to highlight the row; otherwise, the user can only click in the first column to highlight the row. Select from the drop-down list to set: Default, On, Off. Default indicates use of the PxPlus setting of the '+V' or '-V' mnemonic.

Report View

For the List Box Type, select Report View. The Report View List Box displays multiple data elements in a tabular list (as with a Formatted List Box) but with the use of headings and other attributes.

Example:

Note:
To create a more elaborate version of this control (spreadsheet-style input format, etc.), see Grid Control.

When defining a Report View List Box, the following attributes are available:

Attributes ( * indicates a Dynamic property)

ReportView Attributes

Partial Match

Partial matches in the List Box data are highlighted. If selected, the text string used in a LIST_BOX WRITE will be considered a partial match for highlighting List Box data; e.g. if you write "ABC", then the first item that starts with "ABC" is highlighted. (If the Multiple Selections attribute is also set, all items starting with "ABC" would be selected.)

Multiple Selections

Users can select more than one entry from the List Box.

Disable Sorting

Clicking on the column heading does not cause List Box elements to be sorted. The column headings will not have the 3D button look but will appear flat. Column resizing is still allowed.

Suppress Buttons

If this attribute is selected, the heading line is suppressed. The area that is occupied normally by the header is used for list output.

Column Size Lock

When selected, the Report View column headers cannot be resized by dragging. Default is Off.

Auto Column Size

When selected, columns will automatically be proportionally resized when the List Box is resized. Default is Off.

Header Lock

Locks the column headers so that the user is unable to click on them or drag them. Default is Off.

Lines Per Row

Number of lines high per row. Valid values are >= 1. Allows for word wrap. Default is 1.0.

Center Text Vertically

Select this check box to center text vertically in the List Box row only when Lines Per Row is > 1. Text that exceeds the column width is truncated and an ellipsis (…) is displayed. When not selected (Default), text is aligned to the top of the List Box row, and text that exceeds the column width is word wrapped.

Example:

  

Lock Top Rows

Number of rows at the top of the List Box to exclude from sorting. Enter a value or use the spinner controls to increase/decrease the value.

Lock Bottom Rows

Number of rows at the bottom of the List Box to exclude from sorting. Enter a value or use the spinner controls to increase/decrease the value.

Header Height

Controls the height of the header in report view lists in pixels. Setting this property to -1 restores the height to its default size. Setting this property to 0 results in no header. Default is -1.

Grid Lines

Controls the display of grid lines between the rows and columns. Options are None (Default), Full grid, Vertical, Horizontal.

Sort Options

Controls how column data is sorted. Click the drop-down arrow for a list of selections:

Default

Null values at end

None (Raw binary sort)

Ignore case/Nulls last

Ignore case

Ignore accents/Nulls last

Ignore accents

Ignore case & accents/Nulls last

Ignore case and accents

 

The Default setting will use the system StdSortOrder setting. See the 'OPTION' mnemonic and the 'SortOrder$ property.

*Format

Button that launches the Report View Format Definition dialogue used to define various format options (i.e. title, width, alignment, sorting, etc.) for the columns in a Report View List Box. If the List Values drop box (on Display tab) is set to Dynamic, the Format button will be locked.

(Dynamic data classes and properties were added in PxPlus 2018.)
(The Center Text Vertically and Lock Top Rows options were added in PxPlus 2019.)
(The Header Height option was added in PxPlus 2020.)

Other

Full Line Highlight

Full line highlight style allows the user to click any column to highlight the row; otherwise, the user can only click in the first column to highlight the row. Select from the drop-down list to set: Default, On, Off. Default indicates use of the PxPlus setting of the '+V' or '-V' mnemonic.

List/Report View Format Definition

The List/Report View Format Definition dialogue is launched by selecting the Format button on the Attributes panel when defining List View and Report View List Box types. This dialogue consists of the following:

Title

Title appearing above each column. Click the dotted button to invoke a separate dialogue with the following drop-down selections:

Fixed

For inputting a fixed value

Expression

For inputting an expression

Message Lib Ref

For referencing a user-defined message

Width

Width of the column, either a Fixed value or an Expression. To modify the Width value, click the dotted button to invoke a separate dialogue.

Alignment

Select a text alignment option from the drop-down list: Left, Right, Center. No numeric alignment is available, since this is a standard Windows control.

Bitmap

Indicates that a bitmap is to be displayed to the left of the data.

Hotlink

Displays the column as a hotlink. Columns with a hotlink are displayed in the color defined by the 'OPTION'("StdLvueHotlinkClr",color$) setting and are underlined while hovering over the column.

See the 'OPTION' mnemonic and the HotLinkColor$ property.

(The Hotlink property was added in PxPlus 2018.)

UpperCase Sort

Sorts the column based on the PxPlus lower/uppercase character translation tables.

(The UpperCase Sort property was added in PxPlus 2018.)

Column Sort

Click the drop-down arrow for a list of selections for numeric sorting: None, Date, Format numerics, Unformat numerics.

If Column Sort is set to Date, click the Date Formats drop box to select the date format where D = day, M = month, Y = year; e.g. MD, DMY, MDY.

Date Format

Click the drop-down list to select a date format, where D = day, M = month, Y = year.

Column Separator

Click the drop-down list to select a Hex or ASCII string value as the default column separator character.

Insert Above
Insert Below

Adds a blank row above or below the currently selected row for creating a new column.

Delete

Removes the currently selected row (i.e. removes the column from the List Box).

Up
Down

Changes the order of the existing columns in the List Box.

Tree View

For the List Box Type, select Tree View. The Tree View provides a tree-like structure view with optional bitmaps. See State Indicators. This format is the same as used by Windows Explorer.

Example:

Each entry in a Tree View consists of a series of strings or values separated by a delimiter, similar to a directory structure. Duplicates at each level are grouped together:

Given …

Yields …

Accounting/Maintenance/Customers
Accounting/Maintenance/Salesman
Accounting/Orders/Entry
Accounting/Orders/Printing
Production/Maintenance/Schedule
Production/Maintenance/Equipment

When defining a Tree View List Box type, the following attributes are available:

Attributes ( * indicates a Dynamic property)

TreeView Attributes

Data Has Bitmaps

As each entry in the tree view is added/written, then the beginning of the data is tested for the existence of a bitmap pathname enclosed within curly brackets. If a bitmap is present, then it overrides the standard bitmaps.

Direct Edit

Enables automatic editing so that the user can double click on an item to change its value. See Direct Editing.

Disable Sorting

The contents of the tree view will not be sorted automatically.

Suppress Buttons

By default, a tree view shows small buttons to the left of the entries with subordinate levels: either a '+' to indicate the existence of subordinates that have not been shown, or a '-' to indicate that the subordinates are being shown. Clicking the button toggles the display. If this attribute is selected, these buttons are suppressed.

Show Lines

Sets the tree view to draw connecting lines between the various entries.

*Format

Button that launches the Tree View Format Definition dialogue, which is used to set the Column Separator (delimiter character) and define default images to be displayed in the tree. You can define up to six default bitmaps or icons in tree views. If the List Values drop box (on Display tab) is set to Dynamic, the Format button will be locked.

*States

Button that launches the State Indicators dialogue, which is used to set up images that will appear in front of a List Box entry that can be used to indicate whether the item has been selected or not. See Defining State Indicators. If the List Values drop box (on Display tab) is set to Dynamic, the States button will be locked.

(Dynamic data classes and properties were added in PxPlus 2018.)
(Tree View States were added to Dynamic Data Classes in PxPlus 2019.)

Tree View Format Definition

The Tree View Format Definition dialogue is used to describe the default bitmaps and the column separator. PxPlus automatically selects the bitmap based on the existence of subordinates and current focus. You can click the bitmap query button to the right of each field to launch the Bitmaps dialogue and browse for existing internal and external bitmaps.

State Indicators

State indicators are basically images that will appear in front of a Tree View entry that can be used to indicate whether the item has been selected or not. These images are set up in NOMADS via the State Indicators dialogue. See Defining State Indicators.

A maximum of 15 images can be assigned to the List Box; NOMADS stores these images in the PxPlus control object property 'StateBitmaps$. All images must be of the same size/format and may specify transparency options. The image can be external or internal. Internal bitmaps contain an ! (exclamation point) preceding the bitmap name.

Toggling Between States

To toggle between different images or states, the 'ItemState property needs to be set in your application. The numeric value in 'ItemState determines what image will appear next to the row text. This property is 1-based, a value of 0 indicates no state indicator.

Example:

If a Tree View control is defined with three images, the first image will appear if the item state is one, the second image will appear if the item state is two and the third image will appear if the item state is three.

Auto Toggling of States

'AutoState is a numeric property used to control auto toggling of states. This can be set up in NOMADS via the State Indicators dialogue. See Defining State Indicators. If this is set to a non-zero value, state indicators will automatically be toggled without generating a CTL event with EOM = "S". This code is returned in the NOMADS variable _EOM$ in the On Change logic.

The number of states that the system will toggle through will be determined by the value set in this property, or if the property is set to 1, the number of bitmaps assigned to the Tree View. In addition, when the user toggles a state indicator while holding the Shift key down, all entries between the current entry and the last entry will be toggled to the new state of the current entry -- in effect allowing for group select/deselect.

Cascading States

'CascadeState is a numeric property used to control cascading of states. This property allows states to be cascaded from parent to children and vice-versa. This can be set up in NOMADS via the State Indicators dialogue. See Defining State Indicators.

If 'CascadeState is set to non-zero, the system will automatically cascade parent states to their children and correspondingly make parent states representative of all of their children. Setting a parent's state, either under program control or using the 'AutoState property in the Tree View definition, will result in all subordinate children to be set to the same state. When a child's state is set, its parent state will be set according to the state of all of the child's siblings - that is, if all children are in a consistent state, the parent will be set to the same state. If a parent has children of various states (some on, some off), the parent's state will be set to the value set in the 'CascadeState property.

Example:

You could have three state indicators - Off (state 1), On (state 2) and Partial (state 3). 'AutoState needs to be set to 2 and 'CascadeState to 3 to have children that automatically toggle off/on and parents that will be On (if all children are on), Off (if all children are off), and Partial (state 3 - children that are not in a consistent state).

When cascading, only items with states will be affected. In addition, items without states will not affect their parent's states nor will changing the parent of an item without a state affect the children of that item.

Defining State Indicators

The following steps outline how to set up state indicators for a Tree View control:

Step

Description

Step 1: Open State Indicators Dialogue

With a Tree View control selected in your panel, access the List Box Properties dialogue. Select the Attributes tab and then click the States button to launch the State Indicators dialogue.

Step 2: Assign State Images

In the State Indicators dialogue, enter the name of a bitmap in the State Images box. You can also click the bitmap library button to display the Bitmaps dialogue and browse for existing internal and external bitmaps. For internal bitmaps, an ! (exclamation point) must prefix the bitmap name (!Stop). A maximum of 15 images can be assigned in the State Images box.

To change the order of the images, drag and drop a numbered cell in the leftmost column to its new destination.

Step 3: Set 'AutoState and 'CascadeState

Set the values for the 'AutoState and 'CascadeState properties by selecting a value from the drop-down list.

Note:
These values cannot be greater than the assigned images. For example, if three images are assigned, then the 'AutoState values can be 0, 1, 2 or 3.

Tree View Expand Signals

The 'NotifyExpand property can be used (set by your application) to detect Tree View expand/collapse requests.

If this property is set to non-zero, a standard CTL event with an EOM code of '+' (expand) or '-' (collapse) will be generated whenever a tree view node is expanded or collapsed. This code is returned in the NOMADS variable _EOM$ in the On Change logic. The application can also read the 'Expanded property to determine the new state of the node. If this property is set to the default 0 (zero), no notification of the tree view expanding or collapsing is sent to the application.

'Expanded values include:

1

 

Expand level

0

 

Collapse level

+

 

Expand level and all subordinates

-2

 

Collapse level and all subordinates

Notifications are only sent when the expand/collapse is done by the user, not by the application accessing the 'Expanded property.

Direct Editing

'Edit is a numeric property to allow automatic editing of Tree View items. This property can contain three possible values:

0

 

Item cannot be edited (Default)

1

 

Item can be edited

-1

 

Force item into edit mode (Must be set directly in application)

For the Tree View control, select the Direct Edit check box on the Attributes panel to turn direct editing On or Off (0/1).

If the Direct Edit check box is selected, then a double click on an item will put the item into edit mode. When the value changes, a CTL event will be generated with an EOM code of "C", indicating that the item has changed. (No event occurs should the user cancel out of the edit mode.) This code is returned in the NOMADS variable _EOM$ in the On Change logic.

See Also

LIST_BOX Properties
LIST_BOX Directive