Xbasic

{PROPGRID}

Syntax

{PROPGRID= Width, Height PropGrid }

Arguments

Width

Numeric. An integer value for the maximum number of characters to display on one line. The actual number displayed may be less because of word wrap.

Height

Numeric. Optional. Default = 1. The number of rows to display. This may be a fractional number, such as 1.25.

PropGrid

Pointer. A pointer variable with one of the properties shown below.

Description

The {PROPGRID} command displays the type of control displayed below. The control provides a mechanism for displaying many prompts and accepting many inputs from the user.

images/XD_Property_Grid.gif

PropGrid Properties 

  • .Settings 

    Pointer

  • .Def 

    Character. A CR-LF delimited list of the categories and items in the property grid. Refer to Property Grid Formatting.

  • .Object 

    Pointer. Provides access to the Property Grid methods.

Property Grid Formatting 

A CR-LF delimited list defines the structure and contents of the property grid. Each entry is on its own line. Entries may:

  • define the beginning and name of a category

  • define the state of a category

  • define the name of an item within a category

  • define the variable that will contain the user's input

Define a category with the following 2 character sequence at the beginning of a new line "^^". The name of the category follows these 2 characters. For example: ^^CategoryName. The end of a category is defined by the beginning of a new category or the end of the .Def list. Define the open/closed state of a category by placing one of the following two statements immediately after the category definition.

state=opened state=closed

Define the name of an item with the following 2 character sequence at the beginning of a new line "++". The name of the item follows these 2 characters. For example: ++ItemName. Define the variable that will accept the user's input to an item by placing a statement in the following format immediately after the item definition: var= OutputVariable . ItemName. For example:

var=output.Item4

Example 

Create the variables for the Property Grid object.

dim pg as P
dim pg.settings as P
dim pg.def as C
dim pg.object as P
dim output as P
dim output.Item1 as C = ""
dim dlg_title as C

Create the variables to display and respond to the list boxes in this example.

dim itemList as C = comma_to_crlf("Item,Item2,Item3,Item4,Item5,Item6,Item7,Item8,Item9")
dim TargetItem as C = "Item"
dim categoryList as C = comma_to_crlf("Category,Category2,Category3")
dim TargetCategory as C = "Category"
dim dlg_title as C

Define the structure of the property grid.

pg.def = <<%str%
^^Category 
	state=opened 
	++Item 
		var=output.Item1 
	++Item2 
		var=output.Item2 
	++Item3 
		var=output.Item3
^^Category2 
	state=closed 
	++Item4 
		var=output.Item4 
	++Item5 
		var=output.Item5 
	++Item6 
		var=output.Item6 
^^Category3 
	state=closed 
	++Item7 
		var=output.Item7 
	++Item8 
		var=output.Item8 
	++Item9 
		var=output.Item9
%str%

Define the structure of the property grid.

dlg_title = "PropGrid Example"
ui_modeless_dlg_box(dlg_title,<<%dlg%
{can_exit=close}
{propgrid=100,20pg};
{region}
Set focus to: |.20TargetItem^=itemList;
Expand/Contract: |.20TargetCategory^=categoryList;
{endregion};
{lf};
<10&Close!close>;
%dlg%,<<%code%

Respond to events.

if a_dlg_button = "setfocus" then
    a_dlg_button = ""
    pg.object.SetFocus(TargetItem)
    'give focus to the Propgrid object
    ui_dlg_ctl_goto(dlg_title,"{propgrid")
        
else if a_dlg_button = "Toggle"
    a_dlg_button = ""
    dim currentExpandState as l
    currentExpandState = pg.object.IsExpanded(TargetCategory)
    pg.object.ExpandItem( TargetCategory, .not. currentExpandState)
else if a_dlg_button = "Close"
    a_dlg_button = ""
    ui_modeless_dlg_close(dlg_title)
end if
%code%)

Properties for a Property Grid Item 

Name
Description
var

Name of variable being bound to

type

Type of control (combo,smart)

data

Content for special controls (data for combo list if combo, expression for loading the popup).

help

Help displayed when the item has focus.

readonly

Expression that determines if user is prevented from editing the item.

inputbold

When Expression is true, bold the text.

inputerror

When Expression is true, change the text to red.

font

Expression returns font descriptor that selects the font to use.

Example Combo 

++Color 
	var=v.color 
	type=combo 
	[email protected] 
	help=pick a color

Example Popup (Smart) Field 

++Smartfield
   var=v.text 
   type=smart 
   data=v.text=MyGetFunction(v.text)

Input Bold and Readonly Example 

++Smartfield2
   var=temp inputbold=v.text<>""
   readonly=.t. 
   type=smart
   data=v.text=MyGetFunction(v.text)

Example of Input Error 

++Name
   var=Name
   inputerror=name="bad"

Example Font Change 

++Name
   var=name
   font=if(name="henry","Comic Sans MS,10","Arial,10")
   help=Type 'henry' and the font will change.

See Also