CTRL() Function - Get GUI Control Data

Syntax

CTRL(chan{,control_id{,function{,context_id}}}{,ERR=lineref})

Description

For BBj-specific information, see the CTRL() Function - BBj.

The CTRL() function reports on the status of selected items on a GUI device and returns a string value.

Parameter Description
chan A SYSGUI channel number. If no other parameters are specified, CTRL() returns a 2-byte binary string that contains the value of the current SYSGUI context as selected by the 'CONTEXT' mnemonic. (The current context is also available with the FIN() function.)
control_id ID of the control. A value of 0 may be used to get information about a context's window or dialog rather than an individual control or child window.
function

A function, numbered 0-16, as indicated in the following list.

If not specified, it is the default is set according to the type of object in question. The following types behave as though function=2 (Get value) was requested: radio buttons, check boxes, list boxes, list buttons, scroll bars, menu items, and tool buttons. All others behave as though function=1 (Get text) was requested.

context_id Context ID. If omitted, the current context is used.
ERR=lineref Branch to be taken if an error occurs during execution.

CTRL() Function 0 – Get Bounding Rectangle

This CTRL() function returns

the bounding rectangle in current scaled units (refer to Coordinate Systems for additional information). It returns an 8-byte string (four 2-byte binary integers):

Byte Description
1,2 X Location
3,2 Y Location
5,2 Width
7,2 Height

For a window, the values returned are the client (inside) values. The outer rectangle values are returned for all other controls and child windows.

CTRL() Function 1 – Get Text

This CTRL() function returns resource text, according to the following:

Resource Item Returned
List box and list button controls Text of selected items, delimited by $0A$ (but no final $0A$).
Custom edit control Text of the current paragraph.
Tab control Index of the currently selected tab. The ASC() function can be used to return the index of the selected tab. (Tabs use zero-based indices.)
All other resources

Title of resource.

CTRL() Function 2 – Get Value

This CTRL() function returns a value, according to the following:

Resource Item Returned
Scroll bar control Position (2-byte binary integer)
List box and list button controls Indices of selected items as consecutive 2-byte binary integers (zero based).
Radio button and check box controls Status: checked ($01$) or unchecked ($00$).
Custom edit control Current paragraph number (zero based).
Tool button control Status: down ($01$) or up ($00$).
Window ID of the child window or control that has focus, or 0 if no object inside that window has focus.
INPUTN control

An 8-byte string representing a business math value using:

DIM B$:"BUS:B"B.BUS$=CTRL(sysgui,controlid,2)

Menu Items

Status: checked ($0001$) or unchecked ($0000$).

Example: CTRL(chan,-menu_item_tag,2)

CTRL() Function 3 – Get Count

This CTRL() function returns the following:

Resource Item Returned
List box and list button control Number of selected items (2-byte binary integer) followed by the total number of items in the list (2-byte binary integer).
Custom edit control Number of paragraphs (2-byte binary integer).

CTRL() Function 4 – Get Type

For BBj-specific information, see CTRL() Function.

This CTRL() function returns the object type as two binary bytes. The first byte is the class of the object, and the second byte is the type of the object, as follows:

Class of Object

First Byte Value Class of Object
0 Window
1 Generic control
2 Custom edit control
3 Menu item
4 Tool button control
5 Special purpose control

Type of Object

Second Byte Decimal Value Type of Object
1 Top level window
2 Child window with border
7 Child window without border
11 Push button control
12 Radio button control
13 Check box control
14 Horizontal scroll bar control
15 Vertical scroll bar control
16 Edit control
17 Static text control
18 List box control
19 List button control
20 List edit control
21 Group box control
22 Custom edit control
100 Menu item
101 Checkable menu item
102 Status bar control
103 Tool button control
104 INPUTE control
105 INPUTN control
106 Tab control
107 Grid control

CTRL() Function 5 – Get Custom Edit Paragraph by Number

This CTRL() function returns the text of any paragraph in a custom edit control and works only in the current context. The context_id parameter contains the number of the paragraph to retrieve.

CTRL() Function 6 – Get Menu

This CTRL() function retrieves the entire menu hierarchy in 'SETMENU' format from the window. The control_id parameter must equal 0. If the window has no menu, it returns an empty string.

CTRL() Function 7 – Get All Text

This CTRL() function returns the following:

Resource Item Returned
Custom edit control The text of all paragraphs with ($0A$) after each paragraph, including the last paragraph. There is a 4K limit to the data returned. If the custom edit control has more than 4K of data, function 5, above, must be used for each paragraph in the control.
List box and list button controls Returns the text of all items with ($0A$) after each paragraph, including the last item.
All other resources Performs Get Text (Function 1).

CTRL() Function 8 – Get Status

This CTRL() function returns a 2-byte binary string. The first byte is $00$ if the object is currently visible or $01$ if it is invisible. The second byte is $00$ if the object is enabled, and nonzero if the object is disabled. (The second byte can be greater than $01$.)

CTRL() Function 9 – Get All Font Families

This CTRL() function returns the names of all available font families for the given object or window. The same list is returned for any SYSGUI object. Entries are terminated with linefeed characters ($0A$).

CTRL() Function 10 – Get Font Information

This CTRL() function returns information about the current font in any window, special purpose control, or custom edit control. It does not work with generic controls.

The format for this information is:

"width:u(1),height:u(1),leading:u(1),ascent:u(1),descent:u(1),size:u(2),style:u(2),
family:c(1*=)"

Size, style, and family are for the font actually in use, which may or may not be an exact match for the font requested with the 'FONT' mnemonic.

CTRL() Function 11 – Get Last Measurement

This CTRL() function returns the result of the last 'MEASURE' mnemonic as a 2-byte binary string. It may only be used on a window.

CTRL() Function 12 – Get Selection

This CTRL() function returns an 8-byte string for custom edit and edit controls that is comprised of four 2-byte binary quantities as follows:

Paragraph 1

Offset 1

Paragraph 2

Offset 2

Only with Custom Edit controls do the paragraph items return values other than zero. Paragraph 1 and Offset 1 indicate the start of the current text selection. Paragraph 2 and Offset 2 indicate the end. If the start and end are the same, there is no selection, and the position of the caret (insertion point) is reported. All positions are zero-based.

CTRL() Function 13 – Get Printer Information

This CTRL() function returns a 24-byte binary string for a window that consists of six 4-byte quantities, as follows (all units are in pixels):

Byte Value
1,4 Width of printable surface.
5,4 Height of printable surface.
9,4 Horizontal pixels per inch.
13,4 Vertical pixels per inch.
17,4 X offset of printable area from corner.
21,4 Y offset of printable area from corner.

CTRL() Function 14 – Get Printer Setup

This CTRL() function returns a window's binary string (length may vary) that reflects the state of the user's current printer setup selections, for example: portrait versus landscape, which printer, resolution. BASIS has no control over the format of the string and cannot document it. However, the string may be passed back with 'PRESTORE' to return the printer settings to a previous, known state.

CTRL() Function 15 – Retrieve Background Color

This CTRL() function returns the background color in $RRGGBB$ format for all controls, except tab, horizontal and vertical scroll bars, and horizontal and vertical lines.

CTRL() Function 16 – Retrieve Foreground Color

This CTRL() function returns the foreground color in $RRGGBB$ format for all controls, except tab, horizontal and vertical scroll bars, and horizontal and vertical lines.

Examples

Example 1

This example uses CTRL() function parameters 0, 1, and 2:

REM Open SYSGUI

OPEN (1)"X0"

REM Create a Window

PRINT (1)'WINDOW'(100,100,300,300,"Test Window",$$)

REM Put one checkbox in the window, with a title of "Pick me!"

PRINT (1)'CHECKBOX'(101,100,75,160,0,"Pick me!",$$)

DIM BOX$:"X:I(2),Y:I(2),W:U(2),H:U(2)"

REM Put location, width and height of checkbox in BOX$

LET BOX$=CTRL(1,101,0)

PRINT "X =",BOX.X,", ","Y =",BOX.Y,", ","WIDTH =",BOX.W,", ","HEIGHT =",BOX.H

REM Use "Get text" to determine title of checkbox

LET TITLEBOX$=CTRL(1,101,1)

PRINT "Title of checkbox: ",TITLEBOX$

REM Use "Get value" to see if the checkbox is checked or unchecked

IF CTRL(1,101,2)=$00$ THEN PRINT "Box is unchecked" ELSE PRINT "Box is checked"

>RUN

X = 100, Y = 75, WIDTH = 160, HEIGHT = 24

Title of checkbox: Pick me!

Box is unchecked

Example 2

This example uses CTRL() Function 9:

REM Open SYSGUI

OPEN (1)"X0"

REM Create a Window

PRINT (1)'WINDOW'(100,100,300,300,"Test Window",$$)

LET FONTFAM$=CTRL(1,0,9)

PRINT FONTFAM$

>RUN

Algerian

Wide Latin

Arial Narrow

fixed

Example 3

This example uses CTRL() function 10:

REM Open SYSGUI

OPEN (1)"X0"

REM Create a Window

PRINT (1)'WINDOW'(100,100,300,300,"Test Window",$$)

DIM CUR_FONT$:"width:u(1),height:u(1),

leading:u(1),ascent:u(1),descent:u(1),

size:u(2),style:u(2),family:c(1*=)"

LET CUR_FONT$=CTRL(1,0,10)

PRINT "Current Font Family ",CUR_FONT.FAMILY$

Example 4

This example uses CTRL() function 12:

0010 OPEN (1)"X0"
0020 DIM EVENT$:TMPL(1)
0030 SCREEN_SETUP:
0040 LET ROW1=4,ROW2=30
0050 LET EDIT_HIGH=24
0060 LET BX=10,BY=10,BXINC=80,BYINC=35
0070 LET WINW=730,WINH=446
0080 PRINT (1)'WINDOW'(30,90,WINW,WINH,"Test Window",$0082$,$03400400$)
0090 LET B_EXIT=105,BX=400,BW=75,BH=EDIT_HIGH
0100 PRINT (1)'BUTTON'(B_EXIT,BX,BY,BW,BH,"Exit",$0000$)
0110 LET B_SELECT=107,BX=8,BY=ROW2,BW=321,BH=EDIT_HIGH
0120 PRINT (1)'EDIT'(B_SELECT,BX,BY,BW,BH,"",$0008$)
0130 LET B_SHOW=109,BY=BY+BYINC
0140 PRINT (1)'EDIT'(B_SHOW,BX,BY,BW,BH,"",$0008$)
0150 DOIT:
0160 LET EXIT_CODE=0
0170 WHILE EXIT_CODE=0
0180 READ RECORD(1,SIZ=LEN(EVENT$))EVENT$
0190 LET E$=EVENT$(3,1)
0200 LET ID=DEC(EVENT$(4,2))
0210 LET FLAG$=EVENT$(6,1)
0220 IF E$="X" THEN LET EXIT_CODE=1
0230 IF E$="B" THEN IF ID=B_EXIT THEN LET EXIT_CODE=1
0240 LET X$=CTRL(1,B_SELECT,12)
0250 LET F%=DEC(X$(3,2))
0260 LET B%=DEC(X$(7,2))
0270 IF F%<>B% THEN LET T$=CTRL(1,B_SELECT); LET
0270:T$=T$(F%+1,B%-F%+1); PRINT (1)'TITLE'(B_SHOW,T$)
0280 WEND
0290 STOP

Example 5

This example uses CTRL() function 13:

0010 OPEN (1)"X0"
0020 DIM EVENT$:TMPL(1)
0030 SCREEN_SETUP:
0040 LET ROW1=4,ROW2=30
0050 LET EDIT_HIGH=24
0060 LET BX=10,BY=10,BXINC=80,BYINC=35
0070 LET WINW=730,WINH=446
0080 PRINT (1)'WINDOW'(30,90,WINW,WINH,"Test Window",$0082$,$03400400$)
0090 LET B_EXIT=105,BX=400,BW=75,BH=EDIT_HIGH
0100 PRINT (1)'BUTTON'(B_EXIT,BX,BY,BW,BH,"Exit",$0000$)
0110 LET T$=CTRL(1,0,13)
0120 PRINT "Width ",DEC(T$(1,4))
0130 PRINT "Height ",DEC(T$(5,4))
0140 PRINT "Horiz Pixels ",DEC(T$(9,4))
0150 PRINT "Vert Pixels ",DEC(T$(13,4))
0160 PRINT "X Offset ",DEC(T$(17,4))
0170 PRINT "Y Offset ",DEC(T$(21,4))
0180 END

See Also

Functions - Alphabetical Listing