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:

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



______________________________________________________________________________________

Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.