Functions for Reading and Updating the Screen
(fngb__template$, fngb__get_screen$, fngb__put_screen$)
These functions enable you to work with controls using the names assigned in ResBuilder (as opposed to the numeric control IDs), which provides a simplified way to manipulate graphical controls.
|
Function |
Description |
|
Returns a string template that describes the controls on a specified window. |
|
|
Copies the value of each of the controls from the screen (window) to the template record. |
|
|
Copies the value of the selected control(s) from the screen (window) to the template record. |
|
|
Updates each of the controls on the screen (window) based on the values from the template record. |
|
|
Updates the selected control(s) on the screen (window) based on the values from the template record. |
These functions provide all of the functionality you'll need for most situations, but in some cases, you'll need to use more precise mnemonics, as well as the CTRL() and SENDMSG() functions. For example, these functions read or write complete lists from or to list button and list box controls. To determine the currently selected item in a list box or list button, use the CTRL() function; to change the currently selected item or items, use one of the 'LISTSEL', 'LISTMSEL', or 'LISTUNSEL' mnemonics.
The following table shows how each control type maps to the template data structure:
|
Control Type |
Template Format |
Value Description |
Get Value: Screen -> String |
Put Value: String -> Screen |
|
Push Button (11) |
C(1*=0) |
N/A |
N/A |
N/A |
|
Radio Button (12) |
N(1*=0) |
0=unchecked 1=checked |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'CHECK' |
|
Check Box (13) |
N(1*=0) |
0=unchecked 1=checked |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'CHECK' or 'UNCHECK' |
|
Horizontal Scrollbar (14) |
N(4*=0) |
scrollbar position based on the 'scrollrange' |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'SCROLLPOS'(gb__ctl_id,int) |
|
Vertical Scrollbar (15) |
N(4*=0) |
scrollbar position based on the 'scrollrange' |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'SCROLLPOS'(gb__ctl_id,int) |
|
Edit (16) |
C(64*=0) |
Text value of the control. |
ctrl(gb__sysgui, gb__ctl_id,1) |
'TITLE' |
|
Static Text (17) |
C(64*=0) |
Text value of the control. |
ctrl(gb__sysgui, gb__ctl_id,1) |
'TITLE' |
|
List Box (18) |
C(255*=0) |
Complete list, with items delimited by line feeds, followed by list selections, delimited by $ff$. See below for more information. |
ctrl(gb__sysgui, gb__ctl_id,7) |
'LISTSUSPEND' 'LISTCLR' 'LISTADD' 'LISTRESUME' |
|
List Button (19) |
C(255*=0) |
Complete list, with items delimited by line feeds, followed by list selections, delimited by $ff$. See below for more information. |
ctrl(gb__sysgui, gb__ctl_id,7) |
'LISTSUSPEND' 'LISTCLR' 'LISTADD' 'LISTRESUME' |
|
List Edit (20) |
C(64*=0) |
Text value of the edit portion of the control. |
ctrl(gb__sysgui, gb__ctl_id,1) |
'TITLE' |
|
Group Box (21) |
C(1*=0) |
N/A |
N/A |
N/A |
|
Custom Edit (22) |
C(64*=0) |
Text value of the control. |
ctrl(gb__sysgui, gb__ctl_id,7) |
'TITLE' |
|
Menu Item (100) |
N(1*=0) |
0=unchecked 1=checked |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'CHECK' or 'UNCHECK' |
|
Checkable Menu Item (101) |
N(1*=0) |
0=unchecked 1=checked |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'CHECK' or 'UNCHECK' |
|
Status Bar (102) |
C(64*=0) |
Text value of the control. |
ctrl(gb__sysgui, gb__ctl_id,1) |
'TITLE' |
|
Tool Button (103) |
N(1*=0) |
0=unchecked 1=checked |
dec(ctrl(gb__sysgui, gb__ctl_id,2)) |
'CHECK' or 'UNCHECK' |
|
INPUTE (104) |
C(64*=0) |
Text value of the control. |
ctrl(gb__sysgui, gb__ctl_id,1) |
'TITLE' |
|
INPUTN (105) |
C(16*=0) |
Text value of the control (use NUM() to convert to numeric). |
ctrl(gb__sysgui, gb__ctl_id,1) |
'TITLE' |
|
Tab (106) |
N(4*=0) |
Currently selected tab index. |
dec(sendmsg (gb__sysgui, gb__ctl_id,29,0,$$)) |
sendmsg(gb__sysgui, gb__ctl_id,34,0,$$) |
|
Grid (107) |
C(1*=0) |
N/A |
N/A |
N/A |
|
Line (108) |
C(1*=0) |
N/A |
N/A |
N/A |
|
Image (109) |
C(1*=0) |
N/A |
N/A |
N/A |
Values can be passed to list boxes and list buttons in a string that contains the complete list of items, delimited by line feeds. The following would load the items "One", "Two", and "Three" in a list control:
win.list_btn$="One"+$0a$+"Two"+$0a$+"Three"+$0a$
In the GUIBuilder version that is shipped in Visual PRO/5 Rev. 2.20 and above, it is also possible to specify which item or items should be highlighted by appending string numerics to the list, delimited by $ff$ characters. Passing the following string with fngb__put_screen would cause the first and third items to be highlighted (note that item numbering is zero-based).
win.list_btn$="One"+$0a$+"Two"+$0a$+"Three"+$0a$+"0"+$ff$+"2"
Likewise, after using fngb__get_screen to query a list control, the highlighted item or items will be indicated with a list of string numerics delimited by $ff$ characters.
The highlighting functionality is dependent on $ff$ characters not being used in the list text. If this character does occur in the list, unpredictable results will occur.
Get String Template Given Window ID
Syntax
fngb__template$(gb__win_id$)
Description
This function returns a string template given a window ID. The string template contains a field for each control on the specified form or window, with the data types and meanings listed in the table above. The following example is based on the "Hello" program described in "Getting Started":
>dim Hello$:fngb__template$(gb__win_id$)
>print fattr(Hello$,"")
STATUS
PUSH_ME
MESSAGE
>print fattr(Hello$)
STATUS:C(64*=0):ID=1 TYPE=102 X=0 Y=178 W=320 H=22:,
PUSH_ME:C(1*=0):ID=1001 TYPE=11 X=110 Y=50 W=90 H=25:,
MESSAGE:C(64*=0):ID=1002 TYPE=17 X=50 Y=110 W=200 H=25:
Field names are assigned based on the names from ResBuilder. If the name in ResBuilder is blank, the template field name will be "ID" + str(ctl_id). When defining the template, if GUIBuilder finds a field name that duplicates one already in the template, it adds "_"+str(ctl_id) to the end of the second field name to make it unique. If the field name in ResBuilder contains any characters that are illegal in Visual PRO/5 identifiers (e.g. spaces), they will be converted to underscores. For example, a ResBuilder field name of "Over Credit Limit?" would appear in the template as "OVER_CREDIT_LIMIT". The characters " " and "?" are converted to underscores, and leading and trailing underscores are removed.
|
Field |
Description |
|
ID |
Control ID assigned in ResBuilder. |
|
TYPE |
Numeric field type as defined in the above table. |
|
X, Y, W, and H |
Location of control on the screen (X=horizontal pixel location, Y=vertical pixel location, W=width in pixels, and H=height in pixels). |
Copy Control value from Screen to Template Record
Syntax
fngb__get_screen$(gb__win_id$,screen$)
Description
This function retrieves data from the screen/window into a string variable you dimensioned using the fngb__template$() function. Here's an example from the "Hello" program:
>Hello$=fngb__get_screen$(gb__win_id$,Hello$)
>print Hello.Status$
>print Hello.Push_Me$
>print Hello.Message$
Hello from GUIBuilder!
Copy Selected Control value(s) from Screen to Template Record
Syntax
fngb__get_fields$(gb__win_id$,screen$, "fieldname{,fieldname..}")
Description
This function retrieves data from specified fields on the screen/window into a string variable you dimensioned using the fngb__template$() function. Here's an example from the "Hello" program:
>Hello$=fngb__get_fields$(gb__win_id$,Hello$,"Status")
Update Screen Control Values from Template Record
Syntax
fngb__put_screen$(gb__win_id$,screen$)
Description
This function takes data from the string variable you dimensioned using the fngb__template$() function and updates it to the screen/window. Here's an example from the "Hello" program:
>Hello.Status$="This is a status message"
>Hello.Message$="Hello, GUIBuilder"
>Hello$=fngb__put_screen$(gb__win_id$,Hello$)
Update Selected Screen Control Value(s) from Template Record
Syntax
fngb__put_fields$(gb__win_id$,screen$,"fieldname{,fieldname..}")
Description
This function takes selected data from the string variable you dimensioned using the fngb__template$() function and updates it to the screen/window. Here's an example from the "Hello" program:
>Hello$=fngb__put_fields$(gb__win_id$,Hello$,"Message")