PROPERTYGRID Control

The PROPERTYGRID control is a custom grid control that is specifically designed for editing and displaying properties and attribute ("property items") of an object. The name and value of each property item to be edited is shown grouped by category, along with editing options determined by the property item type.

The control itself is split into two areas:

1. A grid that displays the property items. Each item displays the name of the property along with the current value (the width of the name and value columns can be adjusted by the user at runtime. Editing options are determined by the property type. The categories can be collapsed or expanded to show and hide a set of associated properties.
2. A description panel at the bottom of the control that contains brief notes about the currently selected property (this panel is optional and can be hidden). The height of this panel can be adjusted at runtime by the user.

Property Items

The Property Grid control exposes a list of property items for editing. Each property item is specified by a dynamic array of up to 9 attributes (normally @vm-delimited) with the following structure:

<0,1> Category

<0,2> Name

<0,3> Type

<0,4> Value

<0,5> Options

<0,6> Description

<0,7> Disabled Flag

<0,8> Item style

<0,9> Iconv

<0,10> ErrorText

<0,11> Default Value

<0,12> Option Values

<0,13> Display Name

<0,14> Miscellaneous Value

Each attribute is described below:

Category

This attribute is required. It is used to group items together for display.

Name

This attribute is required. It is used to identify the property and must be unique for the grid.

Type

This attribute is required. It describes how the property value is both presented and edited. It is a numeric value and can be one of the following types:

Value

Contains the value of the property item. This is usually a simple string except in the case of the following types:

Options

Contains options specific to the type being edited.

Description

Contains the text to display in the Property Grid Descriptions panel when the property item is selected.

Disabled Flag

When set to TRUE$ the property item is considered to be disabled - it is draw using gray text and cannot be edited - no combo button to options button is displayed.

Item Style

This attribute is a small set of style bits that control the inline editing when used with the following types:

PS_PGIT_EDIT$

PS_PGIT_EDITCOMBO$

PS_PGIT_EDITBUTTON$

The style bits are:

When displaying the following types the Item Style specifies if the item is a ColorKey value rather than a normal Color value:

PS_PGIT_COLOR$

PS_PGIT_COLORBUTTON$

PS_PGIT_COLORCOMBO$

PS_PGIT_COLORDLG$

The style bits are:

Iconv

This attribute is used to validate the property value when it is changed. It should be a standard Basic+ Iconv format as per the standard VALID property. When set the system PROPCHANGED promoted event handler uses it to check the new value.

ErrorText

This attribute is used to contain text that is displayed when the property fails validation in the system PROPCHANGED promoted event handler.

Default Value

This attribute contains a default value that is used if the property value is null after a user has edited it.

Option Values

If the item type is a dropdown-list (PS_PGIT_COMBO$) then this attribute can contain an @svm-delimited list of “internal values” that correspond to the list passed in the Options attribute. When this list is set the property value may be updated using one of these internal values rather than an external one. Likewise when the property value is queried the corresponding internal value is returned instead.

For example, consider a property item that has three options: “Apple”, “Orange” and “Lemon”, each with an internal values (codes) of “A1”, “O1” and “L1” respectively. If the Option Values attribute is not used the resulting program might look like this:

 
$insert ps_PropertyGrid_Equates

   

   propItems = ""

   

   fruitNames = "Apple" : @svm : "Orange" : @svm : "Lemon"

   fruitCodes = "A1"    : @svm : "O1"     : @svm : "L1"

   

   propItem                            = "Test Properties"

   propItem<0,PSPG_POS_NAME$>          = "Fruit"

   propItem<0,PSPG_POS_TYPE$>          = PS_PGIT_COMBO$

   propItem<0,PSPG_POS_VALUE$>         = fruitNames<0,0,1>

   propItem<0,PSPG_POS_OPTIONS$>       = fruitNames

   propItem<0,PSPG_POS_DESCRIPTION$>   = "Testing a simple dropdown item"

   propItem<0,PSPG_POS_DISABLED$>      = FALSE$

   

   propItems<-1> = propItem;   // ... add more items ..

   

   // Add the items to the grid

   Call Set_Property( @Window : ".PGD_TEST", "LIST", propItems )

   

   // ... sometime later retrieve the selected code ...

   fruitName = Get_Property( @Window : ".PGD_TEST", "VALUE, "Fruit" )

   fruitCode = ""

   

   locate fruitName in fruitNames using @svm setting pos then

      fruitCode = fruitCodes<0,0,pos>

   end
 

If the Option Values attribute is used then accessing the item Value is much easier, as can be seen in this example:

 
$insert ps_PropertyGrid_Equates

   

   propItems = ""

   

   fruitNames = "Apple" : @svm : "Orange" : @svm : "Lemon"

   fruitCodes = "A1"    : @svm : "O1"     : @svm : "L1"

   

   propItem                            = "Test Properties"

   propItem<0,PSPG_POS_NAME$>          = "Fruit"

   propItem<0,PSPG_POS_TYPE$>          = PS_PGIT_COMBO$

   propItem<0,PSPG_POS_VALUE$>         = fruitCodes<0,0,1>  ; // Set the code

   propItem<0,PSPG_POS_OPTIONS$>       = fruitNames

   propItem<0,PSPG_POS_DESCRIPTION$>   = "Testing a simple dropdown item"

   propItem<0,PSPG_POS_DISABLED$>      = FALSE$

   propItem<0,PSPG_POS_OPTIONVALUES$>  = fruitCodes         ; // Set the codes

   

   propItems<-1> = propItem;   // ... add more items ..

   

   // Add the items to the grid

   Call Set_Property( @Window : ".PGD_TEST", "LIST", propItems )

   

   // ... sometime later retrieve the selected code ...

   fruitCode = Get_Property( @Window : ".PGD_TEST", "VALUE", "Fruit" )
 

Display Name

Contains alternative text to display for the property item, overriding the Name attribute.

Miscellaneous Value

Contains miscellaneous data that the developer wishes to store with an item.

Developer Notes

- Equated constants for the Property Grid control can be found in the PS_PROPERTYGRID_EQUATES insert record. - Because property item categories can be collapsed and expanded the Property Grid has the concept of a "visible" list of items, and a "fully-expanded" list of items, much like the standard OI Hierarchical Listbox (aka TREELIST) control. Therefore it should be noted which view the PROPERTYGRID properties and methods work against when using them. - Bearing in mind the above it should be noted that some Property Grid properties (like LIST and ENABLED) can be referenced with an index argument when used with Get/Set_Property. The preferred way of using such an indexed property is via the item name, not its position, as the name is always constant regardless of whether the item is visible or not. - Categories are never included when using a property or method that works with the item list.

For example, in "fully expanded" list below the "CheckText" item has a SELPOS and SELPOSX value of 8, not 10, as the categories are not included. Likewise, in the "visible" list on the right the Data category has been collapsed. In this case the SELPOS value is now 2, but the SELPOSEX value is still 8.

"Fully expanded" list "Visible" list