GRIDPLUS2 - Reading And Setting The Value of GRIDPLUS Widgets
Home Reference Manpage Examples Download License Contact

Reading And Setting The Value of GRIDPLUS Widgets

The values of the GRIDPLUS widgets are stored in a global array with a null name.

For Example:

global {}

Note: See the appropriate command/mode reference page for reading the values of specific widgets.

The recommended method to set all GRIDPLUS widget values is to use the either gpset or gpmap commands.

There is also a command to unset GRIDPLUS widget values (gpunset).

It is intended that GRIDPLUS widget values would normally be unset using the GRIDPLUS clear command/mode.

Using The gpset Command

The gpset command can be used to set one or more GRDIDPLUS widget values. It can also be used to set the value of non-GRIDPLUS widgets if they have an associated variable which is an element in the array with a null name.

There are three possible syntax options:-

gpset item value

...To set the value of a single widget - Or...

gpset {item value ... ...}

...To set the values of several widgets.

Note: The GRIDPLUS tablelist, text and tree widgets can only be set using the first of the above syntax options.

gpset -| item value

The "-|" option specifies that the value should be "dedented". For lines beginning with spaces, the shortest leading space string is removed from each line. This can aid source code readability. See this Example.

gpset option item value

...To set the value of a calendar -or- tablelist column names/titles.

Note: This syntax is used when the -selectonly, -names or -titles option is to be specified.


Calendar

For GRIDPLUS calendar widgets (by default) the array element has the same name as the widget frame: Thus the value of ".mycal" is referenced as "$(.mycal)".

For Example:

gpset .mycal 08/25/2009
Note: The date must be in the format as defined by -dateformat. An incorrect format will result in an error when posting a dropdown calendar.

To clear the date selection on the calendar display without changing the value...

gpset -selectonly .mycal {}


Checkbutton

For GRIDPLUS Checkbutton widgets the array element has the same name as the widget: Thus the value of ".savings" in a Checkbutton Grid called ".account" is referenced as "$(.account,savings)".

The value will be either "0" (zero) when "deselected" or "1" when "selected".

For Example:

gpset .account,savings 1


Dateselector

For GRIDPLUS Dateselector widgets the array element has the same name as the widget: Thus the value of ".date1" in ".mygrid" is referenced as "$(.mygrid,date1)".

The recommended method to set GRIDPLUS dateselector values is to use the gpset command.

For Example:

gpset .mygrid,date1 07/12/2009

Note: The date must be in the format as defined by -dateformat. An incorrect format will result in an error when posting a dropdown calendar.


Dropdown

For GRIDPLUS Dropdown widgets the array element has the same name as the widget: Thus the value of ".dropdown1" in ".mygrid" is referenced as "$(.mygrid,dropdown1)".

The gpset command can also be used to set the dropdown list.

For Example:

To set the value of the dropdown use gpset with one parameter...

gpset {.mygrid,dropdown1 "Option two"}

To set the dropdown list use gpset with two parameters...

gpset .mygrid,dropdown1 {"Option one" "Option two" "Option three"}


Entry

For GRIDPLUS Entry widgets the array element has the same name as the widget: Thus the value of ".name" in ".person" is referenced as "$(.person,name)".

For Example:

gpset .person,name "Mary Smith"


Radiobutton

For GRIDPLUS Radiobutton widgets in the default group the array element has the same name as the radiobutton Grid: Thus the value of the ".gender" radiobutton group is referenced as "$(.gender)".

For radiobutton widgets that are part of a specified group the array element name is based on a combination of the name of the radiobutton Grid and the name of the group: Thus the value of a ".person" grid radiobutton in a group called "gender" is referenced as "$(.person,gender)".

The value will be that specified for the currently selected radiobutton. If no button is selected the value will be null.

The recommended method to set GRIDPLUS radiobutton values is to use the gpset command.

For Example:

gpset .gender female

...or...

gpset .person,gender male


Spinbox

For GRIDPLUS Spinbox widgets the array element has the same name as the widget: Thus the value of ".number_required" in ".order" is referenced as "$(.order,number_required)".

For Example:

gpset .order,number_required 4


Tablelist

For GRIDPLUS Tablelist widgets the array element has the same name as the widget frame: Thus the value of ".accounts" is referenced as "$(.accounts)".

Note: For the GRIDPLUS tablelist only the value of the selected row is stored in the array. If no row is selected there is no entry in the array.

The value of the tablelist is a list. Each element in the list corresponds to a row in the tablelist. Each row element is itself a list, where each element in the list corresponds to a column in the row.

For Example:

gpset .accounts {
   {000001 {Fred Smith} 120.45}
   {000004 {Mary Jones} 5156.67}
   {000003 {Susan Freeman} -987.03}
   {000002 {David Miles} 10654.84}
}

To set the tablelist column names...

gpset -names .mytable {"Name One" "Name Two" "Name Three"}

To set the tablelist column titles...

gpset -titles .mytable {"Title One" "Title Two" "Title Three"}


Text

For GRIDPLUS Text widgets the array element has the same name as the widget frame: Thus the value of ".notes" is referenced as "$(.notes)".

For Example:

gpset .mytext "This is some text\nThis is another line"


Tree

For GRIDPLUS Tree widgets the array element has the same name as the widget frame: Thus the value of ".mytree" is referenced as "$(.mytree)".

Note: For the GRIDPLUS tree only the value of the selected node is stored in the array. If no node is selected there is no entry in the array.

The value of the tree is a list. Each element in the list corresponds to a node in the tree. Each row element is itself a list, which contains the full hierarchic name of the node together with any required node options (See Reading and Setting GRIDPLUS Tree Values).

For Example:

gpset .mytree {
   /File1
   {/Dir1 +}
   {/Dir1/Dir2 +}
   /Dir1/Dir2/File2
   /Dir1/Dir2/File3
   /Dir1/File4
   /Dir1/File5
   /File6
}


Setting Multiple Multiple Values With One Command

It is possible to the values of several widgets with one gpset command.

For Example:

gpset {
   .account,savings 1
   .person,name     "Mary Smith"
   .gender          female
}

Note: tablelist , text and tree widgets cannot use the "multiple set" facility of gpset.

Using The gpmap Command

The gpmap command can be used to set one or more GRDIDPLUS widget values by mapping a list of GRIDPLUS widget data names to either a corresponding list of values, a list of array elements for a specified array -or- a list of keys for a specified dict. It can also be used to set the value of non-GRIDPLUS widgets if they have an associated variable which is an element in the array with a null name.

Syntax:-

To map a list of items to a list values...

gpmap {item ...} {value ...}

The list of items must have the same number of elements as the list of values.

To map a list of items to the elements of an array...

gpmap {item ...} {element ...} array

When used in this mode the third parameter specifies that name of an array. The second parameter is a list of array element names to be mapped to the corresponding items.

To map a list of items to the key/values of a dict...

gpmap {item ...} {key ...} dict

When used in this mode the third parameter specifies that name of a dict. The second parameter is a list of dict key names to be mapped to the corresponding items.

For Example:

Mapping a list of values...

gpmap {
   .account,savings
   .person,name
   .gender
} {
   1
   "Mary Smith"
   female
}

This could be particularly useful when using the result of a database access command/procedure to populate all or part of a screen.

For Example:

Mapping of a Metakit result...

gpmap {
   .phone,firstname
   .phone,lastname
   .phone,phone
   .phone,department
} [mk::get db.data![lindex $(.phonelist) 0] firstname lastname phone department]

Mapping of a SQLite result...

gpmap {
   .phone,firstname
   .phone,lastname
   .phone,phone
   .phone,department
} [phonedb eval {select firstname,lastname,phone,department from phones where personid = 'A001'}]

Example:

Mapping an array...

Assuming the array has the following elements:-

person(firstname)  "john"
person(lastname)   "Smith"
person(phone)      "555 9876"
person(department) "Sales"

The person array can be mapped to GRIDPLUS widgets thus...

gpmap {
   .phone,firstname
   .phone,lastname
   .phone,phone
   .phone,department
} {
   firstname
   lastname
   phone
   department
} person

Example:

Mapping a dict...

Assuming the dict has been created as:-

set person [dict create firstname "Mary" lastname "Jones" phone "555 4567" department "Accounts"]

The person dict can be mapped to GRIDPLUS widgets thus...

gpmap {
   .phone,firstname
   .phone,lastname
   .phone,phone
   .phone,department
} {
   firstname
   lastname
   phone
   department
} person

Note: The GRIDPLUS tablelist , text and tree widgets cannot be set using this command.

Using The gpunset Command

The gpunset command can be used to unset one or more GRDIDPLUS widget values. It can also be used to unset the value of non-GRIDPLUS widgets if they have an associated variable which is an element in the array with a null name.

Syntax:-

gpunset item ...

Example:

gpunset .person,name .person,gender


Copyright © 2014 Adrian Davis.