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 controls	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:

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

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:

0010 REM Open SYSGUI
0020 OPEN (1)"X0"
0030 REM Create a Window
0040 PRINT (1)'WINDOW'(100,100,300,300,"Test Window",$$)
0050 REM Put one checkbox in the window, with a title of "Pick me!"
0060 PRINT (1)'CHECKBOX'(101,100,75,160,0,"Pick me!",$$)
0070 DIM BOX$:"X:I(2),Y:I(2),W:U(2),H:U(2)"
0080 REM Put location, width and height of checkbox in BOX$
0090 LET BOX$=CTRL(1,101,0)
0100 PRINT "X =",BOX.X,", ","Y =",BOX.Y,", ","WIDTH =",BOX.W,", ","HEIGHT =",BOX.H
0110 REM Use "Get text" to determine title of checkbox
0120 LET TITLEBOX$=CTRL(1,101,1)
0130 PRINT "Title of checkbox: ",TITLEBOX$
0140 REM Use "Get value" to see if the checkbox is checked or unchecked
0150 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:

0010 REM Open SYSGUI
0020 OPEN (1)"X0"
0030 REM Create a Window
0040 PRINT (1)'WINDOW'(100,100,300,300,"Test Window",$$)
0050 LET FONTFAM$=CTRL(1,0,9)
0060 PRINT FONTFAM$
>RUN
Algerian
Wide Latin
Arial Narrow
fixed

Example 3

This example uses CTRL() function 10:

0010 REM Open SYSGUI
0020 OPEN (1)"X0"
0030 REM Create a Window
0040 PRINT (1)'WINDOW'(100,100,300,300,"Test Window",$$)
0050 DIM CUR_FONT$:"width:u(1),height:u(1),
0050:leading:u(1),ascent:u(1),descent:u(1),
0050:size:u(2),style:u(2),family:c(1*=)"
0060 LET CUR_FONT$=CTRL(1,0,10)
0070 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: