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