TreeGrid v6.0

Types Enum, Radio and Select

TreeGrid documentation index

 

The Enum and Radio types specify a list of values and let user to choose on or more from them.

These cells are not editable by <input>, so a user cannot enter another value that the ones in list.

To have a combo with input use Defaults list with Text type.

 

Enum type

 

A user selects the item(s) from combo box (similar to <SELECT> tag).

It is possible to let a user to select more items by setting Range attribute.

If you want to mix selection from list and direct value editing, use rather Defaults list instead of Enum type.

The left Enum icon can be hidden by setting attribute Icon=””. To place it to the right set IconAlign=’Right’

 

Radio type

 

All items are displayed with radio button or checkbox and a user checks one or more of them.

It is possible to let a user to select more items by setting Range attribute.

 

Select type

 

Cell type Select is special type to show not editable combo with list of predefined values.

Its functionality is similar to Enum type, but it does not have its complexity.

The difference to Enum type is just in its look.

It is just shortcut for Type=”HtmlButton=”Defaults”.

The predefined list is defined by Defaults attribute.

It does not have any Enum attribute listed below, here is stated just for its similarity to Enum.

 

Value in Enum and Radio cell

 

The Enum cell value can be set as

a) index to Enum array, from 0. For example Enum=’|One|Two|Three”, Value=’2’ as Three

b) value from Enum array. For example Enum=’ |One|Two|Three”, Value=’Three’

c) value from EnumKeys array. For example Enum=’ |One|Two|Three” EnumKeys=’|A|B|C’ Value=’C’ as Three

To distinguish ambiguity cases between a) and b) when Enum array contains numbers, set IndexEnum (by default is preferred b))

After change of the value, the value is set by the same way as it was preset (index/Enum name/EnumKeys name).

To distinguish ambiguity cases between a) and b) when changing empty / null Enums, set IndexEnum (by default is preferred b)).

The Enum value is uploaded to server as it is set in data.

When set Range, the value contains list of selected items, separated by semicolon. The items can be also index/Enum name/EnumKeys name.

 

Filter

 

If the Enum or Radio type cell is used in Filter row, it automatically hides the filter operator menu.

For Enum it adds one empty item as the first item to the list to clear the filter.

For Radio it adds one item “off” as the last item.

You can change this behavior by FilterOff attribute.

To filter by more Enum values set Range attribute of the Filter cell.

 

Basic definition

 

<C> <cell>        string    Type             [“Text”]              Type=”Enum” or “Radio”                                                                                .

To define Enum type, set column or cell attribute Type to “Enum”, for Radio type set Type to “Radio”.

 

<C> <cell>        string[*] Enum                                                                                                                                                             .

A list of values to select from. It is first character separated array (the first character in the string is separator). For example “,one,two,three” or “|1,1|2,3”.

This value will be shown in the cell.

This list will be also shown in expanded combo if EditEnum and EnumMenu are not set.

 

API event          string    OnGetEnum     (TGrid grid, TRow row, string col, string enum)                                        chg 6.0 .

Called to get Enum attribute dynamically. Returns enum or new enum list.

 

<C> <cell>        string[*] EnumKeys                                                                                                                                              .

A list of keys for Enum type.

If set, the Enum type cell contain this key instead of Enum name or index.

The EnumKeys must have the same order and count as Enum array.

 

API event          string    OnGetEnumKeys    (TGrid grid, TRow row, string col, string enumkeys)                                 .

Called to get EnumKeys attribute dynamically. Returns enumkeys or new enum keys list.

 

<Filter cell>      string    FilterOff [‘’]                                                                                                                                   upd 6.0 .

You can set FilterOff to existing value or index to use this item to clear filter.

Or you can set it to not existing value to show the FilterOff value as the “clear filter” item caption.

If the Enum/Radio uses number indexes, the index is automatically shifted to let the list to be the same as in the other cells!

 

<Filter cell>      bool       FilterEnumKeys        [0]                                                                                                      new 7.0 .

If set to 0 it filters by Enum string.

If set to 1 it filters by Enum value, by key or index.

 

<Cfg>                bool       IndexEnum       [0]                                                                                                                                 .

If the number cell values will be taken as index to Enum (from 0) or as value from Enum. 0 – value, 1 – index.

Only for ambiguity cases – when Enum contains a number or when changed from empty or null value.

In all other cases it is chosen according to the actual value.

It is ignored when set EnumKeys.

 

<C> <cell>        bool       CanEmpty          [0]                                                                                                      new 6.0;upd 7.0.

If the enum index can be empty, only for enums set by index.

If set to 1, the cell value differs between 0 and “”. It is by default set to filter.

Since 7.0 it also controls behavior of the Clear attribute, for 0 Clear sets the first value from Enum, for 1 it sets empty string.

 

<C> <cell>        string    EmptyValue      [“”]                                                                                                                   new 6.0 .

The string displayed when the enum text is empty. Useful especially for Range cells.

It is shown only for display, not in popup menu.

It is not escaped, it can contain HTML code.

 

Related lists

The Enum and Radio type lists can be related, one cell will have different lists for different values in another cell. Like Continent -> Country -> State -> Region -> City.

 

<C> <cell>        string [] Related                                                                                                                                          upd 6.0 .

The comma separated list of columns this Enum list is related to. The Enum list relies on values in these columns.

It defines dependent lists like Country -> State/County -> City.

The enumeration lists (Enum, EnumKeys, EditEnum and EnumMenu attributes) for the cell are chosen according to value(s) in Related columns from EnumA_B_C... attributes, where A,B,C are column values from cells in columns in Related list, in that order.

Use with Refresh or Clear attribute. When the attribute for the values does not exist, the original attribute without prefix is used.

The postfixes are the exact values in the cells, if you use EnumKeys use the values from EnumKeys, if you use names from Enum, use these names and if you indexes to Enum, use the indexes.

Example (B is related to A, C is related to B and also to A)

<C Name=’A’ Type=’Enum’ Clear=’B,C’ Enum=’|One|Two’/>

<C Name=’B’ Type=’Enum’ Related=’A’ Clear=’C’ Enum0=’|a|b|c’ Enum1=’|1|2’/>

<C Name=’C’ Type=’Enum’ Related=’A,B’ Enum0_0=’...’ Enum0_1=’...’ Enum0_2=’...’ Enum1_0=’...’ Enum1_1=’...’/>

 

<C> <cell>        string [] Clear                                                                                                                                   new 6.0;upd 7.0.

Which cells to clear after value of the cell changes. Usually used with Related attribute.

The comma separated list of column names. The cells in the same row and in these columns will be cleared – their value set to “”.

Since 7.0 it is affected by CanEmpty attribute, for 0 Clear sets the first value from Enum, for 1 it sets empty string.

 

<C> <cell>        string [] Refresh                                                                                                                                         upd 6.0 .           

Which cells to refresh after value of the cell changes. Usually used with Related attribute.

The comma separated list of column names. The cells in the same row and in these columns will be refreshed.

Has sense only for index enums, for string enums use rather Clear.

 

Enum specific

 

<C> <cell>        string[*] EditEnum                                                                                                                                                .

A list of values for Enum type to display them in expanded combo when editing.

If it is missing it is used Enum array instead.

Useful to show different item names in cell and in expanded combo list.

 

API event          string    OnGetEditEnum       (TGrid grid, TRow row, string col, string editenum)                     new 6.0 .

Called to get EditEnum attribute dynamically. Returns editenum or new edit enum list.

 

<C> <cell>        string    EnumMenu                                                                                                                             new 6.0 .

Full definition of the list displayed on expanding combo to select Enum value(s).

It supports extended capabilities like submenus and collapsible sections.

It is more extended alternative to EditEnum.

The menu format is standard TreeGrid menu.

 

API event          string    OnGetEnumMenu (TGrid grid, TRow row, string col, string enummenu)                  new 6.0 .

Called to get EnumMenu attribute dynamically. Returns enummenu or new enum menu list.

 

<C> <cell>        string    IntFormat                                                                                                                                                .

A format when the Enum value is set to number that is out of range or does not exist in Enum / EnumKeys.

Useful for number types to show a name for first few values and the rest as normal formatted integer.

Example: Enum=’|never|once|twice’ IntFormat=’###0 times’

It should be used for read only cells. Works also for floating point numbers.

 

Radio specific

 

<C> <cell>        bool       Wrap           [0]                                                                                                                                new 6.0 .

How the items will be wrapped inside the cell.

0 to show all items at one line, 1 to split items to more lines if needed, 2 to show every item at one line

 

<C> <cell>        int          RadioIcon          [0]                                                                                                                   new 6.0 .

Icon displayed for buttons

0 – displays radio button images for normal cell or checkbox images for Range cell.

1 – displays radio button images

2 – displays checkbox images

3 – displays <input type=’radio’> for normal cell or <input type=’checkbox’> for Range cell. It is slower than displaying images.

4 – displays <input type=’radio’>. It is slower than displaying images.

5 – displays <input type=’checkbox’>. It is slower than displaying images.

 

<C> <cell>        bool       RadioRight       [0]                                                                                                                   new 6.0 .

If set to 1, displays the icon on the right instead of left

 

<C> <cell>        bool       RadioUncheck           [0]                                                                                                      new 6.0 .

If the checked radio button can be unchecked to have all buttons empty – only for normal non Range cell.

 

<Actions>                      ChangeRadioRight            Attached to event OnCtrlRight                                                       .

Selects item in radio, the right one next to the actually selected, cannot be used for Range cells.

 

<Actions>                      ChangeRadioRightCycle          Attached to event OnEnter                                   new 7.0 .

Selects item in radio, the right one next to the actually selected, cannot be used for Range cells.

For the last item checked checks the first item.

 

<Actions>                      ChangeRadioLeft   Attached to events OnCtrlLeft                                                                      .

Selects item in radio, the left one next to the actually selected, cannot be used for Range cells.

 

<Actions>                      ChangeRadioLeftCycle              Not attached to any event                                     new 7.0 .

Selects item in radio, the left one next to the actually selected, cannot be used for Range cells.

For the first item checked checks the last item.

 

<Actions>                      ChangeRadio              Attached to event OnClickEditRadio                                             new 6.0 .

Selects item in radio, the one under mouse cursor