The INQUIRE verb allows you to retrieve information from a control, or retrieve the dimensions of a window.
General Format
Format 1
INQUIRE { control-item } [ ( {index-1} ... ) ]
{ CONTROL }
Remaining phrases are optional, can appear in any order.
AT screen-loc [CELL ]
[CELLS ]
[PIXEL ]
[PIXELS]
AT LINE NUMBER line-num [CELL ]
[CELLS ]
[PIXEL ]
[PIXELS]
AT {COLUMN } NUMBER col-num [CELL ]
{COL } [CELLS ]
{POSITION} [PIXEL ]
{POS } [PIXELS]
AT CLINE NUMBER cline-num [CELL ]
[CELLS]
AT CCOL NUMBER ccol-num [CELL ]
[CELLS]
TITLE {IN} title
{= }
VALUE {IN} [ MULTIPLE ] value [ LENGTH {IN} length-1 ]
{= } [ TABLE ] {= }
STYLE {IN} style-flags
{= }
HELP-ID {IN} help-id
{= }
{ { property-name } [ ( {param}... ) ] {IN} property-value } ...
{ PROPERTY property-name } {= }
{ object-expression }
[ LENGTH {IN} length-1 ] }
{= }
SYSTEM HANDLE {IN} system-handle
{= }
POP-UP MENU {IN} {menu-1}
{= }
LINE NUMBER {IN} line-num [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
{COLUMN } NUMBER {IN} col-num [CELL ]
{COL } {= } [CELLS ]
{POSITION} [PIXEL ]
{POS } [PIXELS]
SIZE {IN} width [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
LINES {IN} height [CELL ]
{= } [CELLS ]
[PIXEL ]
[PIXELS]
ID {IN} id
{= }
CLASS {IN} class-code
{= }
ENABLED {IN} enabled-state
{= }
VISIBLE {IN} visible-state
{= }
Format 2
INQUIRE { window-handle }
{ WINDOW [generic-handle] }
Remaining phrases are optional, can appear in any order.
LINE NUMBER {IN} line-no
{= }
{COLUMN } NUMBER {IN} col-num
{COL } {= }
{POSITION}
{POS }
TITLE {IN} title
{= }
SCREEN LINE NUMBER {IN} screen-line
{= }
SCREEN {COLUMN } NUMBER {IN} screen-col
{COL } {= }
{POSITION}
{POS }
SIZE {IN} width
{= }
LINES {IN} height
{= }
SYSTEM HANDLE {IN} system-handle
{= }
VISIBLE {IN} visible-state
{= }
POP-UP MENU {IN} menu-1
{= }
Syntax Rules
1. Control-item is a USAGE HANDLE data item that identifies the control to be inquired. If it is a typed handle, then it must be associated with a control. Control-item can also be an elementary Screen Section item that describes a control.
2. Index-1 is a numeric expression. The parentheses surrounding index-1 are required.
3. The AT, LINE, COLUMN, CLINE, and CCOL phrases must appear in conjunction with the CONTROL phrase.
4. Screen-loc is an integer data item or literal that contains exactly 4, 6, or 8 digits.
5. Line-num, col-num, cline-num, and ccol-num are numeric data items or literals. Note that they may contain non-integer values, except when pixels are specified.
6. Title is an alphanumeric data item.
7. Value may be any data item.
8. Style-flags is a numeric data item capable of holding 10 or more digits.
9. Help-id is a numeric data item.
10. Property-name is the name of a property specific to the type of control being inquired. If control-item refers to a generic handle, or if the CONTROL option is specified, then property-name cannot be used. Use the PROPERTY phrase instead.
11. Property-type is a numeric literal or data item.
12. Property-value is a data item. Its data type should be appropriate for the specified property.
13. Param is a literal, data-item, or numeric expression used when inquiring the property value of an ActiveX control or OLE object..
14. Object-expression has the following format:
{ {^} property-1 [ ( param-1 ... ) ]
[ :: property-2 [ ( param-2 ... ) ] ]... }
a) ^ can only be used in conjunction with Format 5 USE verb.
b) Property-1 is the name of a property of the ActiveX control or object. property-1 must not be a write-only property.
c) Property-2 is the name of a property of the ActiveX object which is the value of property-1. Property-2 must not be a write-only property.
d) Param-1 and param-2 are literals, data items, or numeric expressions.
15. Length-1 is a numeric data item. The LENGTH phrase may be specified only if the value or property-value immediately preceding it is an alphanumeric data item.
16. Window-handle is a USAGE HANDLE OF WINDOW or PIC X(10) data item.
17. Generic-handle is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
18. Line-no, col-no, screen-line, screen-col, width and height are numeric data items. Line-no and col-no should be signed and have at least two digits after the decimal point to get the best results. Screen-line and screen-col should be signed to get the best result.
19. System-handle and visible-state are numeric data items.
20. Menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
21. Id, class-code and enabled-state are numeric data items.
22. In Format 1, the LINE IN phrase and the COLUMN IN phrase may be used only if the control-item option is specified.
General Rules
Format 1 (INQUIRE CONTROL)
1. The INQUIRE CONTROL statement retrieves some or all of a control's current properties, and stores them as data items. Control-item identifies the control to inquire. If the CONTROL phrase is used instead, the runtime inquires the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime system maintains a list of controls in each window. When you are attempting to inquire from a control at a specific location, the runtime searches this list, inquiring the first control it finds that exactly matches the given location. The list is maintained in the order in which the controls are created.
2. If control-item does not refer to a valid control, or if the runtime cannot locate a control at the specified screen location, the INQUIRE statement has no effect.
3. If index-1 is specified, then certain properties in the control being inquired are modified to match the value of index-1. This modification occurs before any inquiry occurs. The exact set of properties modified depends on the control's type. Three controls have properties that are modified in this way:
| Control Type
| Properties Affected
|
| List Box
| QUERY-INDEX
|
| Grid
| Y, X
|
| Tree View
| ITEM |
INQUIRE grid-1(2, 3)
Would have the effect of setting the grid property "Y" to "2" and "X" to "3".
Supplying more index values than the control supports has no additional effect. You may omit trailing indexes; this leaves the corresponding properties unchanged.
This feature can be used to simplify inquiry on specific elements of controls that hold multiple values. For example, you can retrieve the contents of row 2, column 3 in a grid with the statement:
INQUIRE grid-1(2, 3), CELL-DATA IN data-1
This is exactly equivalent to the more cumbersome:
MODIFY grid-1, Y = 2, X = 3 INQUIRE grid-1, CELL-DATA IN data-1
4. When the runtime is storing data items, the rules for the MOVE statement are applied. The source for the title is alphanumeric. The type of control determines the source format of the value. The source format for a property is either numeric or alphanumeric depending on the specific property.
5. When used with an ActiveX control or OLE object, INQUIRE gets the value of a property or gets the style flags.
6. When the PROPERTY phrase is used to set an ActiveX control or OLE object, the runtime automatically converts parameters to the appropriate styles.
7. When the LENGTH option is specified, length-1 gives you the exact number of characters that were placed by the control in value or property-value. This option is useful in determining how long the logical data is in value or property-value, or if there are trailing spaces. If, for example, you inquired the SELECTION-TEXT property in an entry-field and specified the LENGTH option, you could tell if the user's selection contains trailing spaces. If you do not use the LENGTH option, your program will not distinguish between the trailing spaces in the selection and the trailing spaces added by the runtime.
8. The SYSTEM HANDLE phrase retrieves the host graphical system's handle that corresponds to the control and stores this value in system-handle. This value is the way the host graphical system identifies the control. You usually need it if you want to affect the control from some other language such as C. There is no use for the host system's handle if you are using only ACUCOBOL-GT; the handle is useful only when you need to have another language interact with an ACUCOBOL-GT screen.
9. Each host system defines its own technique for identifying graphical components. Under Windows, the Windows API uses the "HWND" type. For 32-bit Windows, this is a 32-bit unsigned value. You can use UNSIGNED-INT as an appropriate USAGE type for system-handle to cover these two cases portably.
10. If the control does not have a corresponding host handle, then system-handle is set to zero. This indicates that either the host system does not have an underlying graphical system, or that the particular control does not use the host's notion of a control in its implementation.
11. The POP-UP MENU option returns the handle of the pop-up menu associated with the control in menu-1. If the control has no pop-up menu, menu-1 is set to NULL.
12. The LINE IN and COLUMN IN phrases return the location of the control in line-num and col-num respectively. The SIZE IN and LINES IN phrase return the dimensions of the control in width and height respectively. These values have the same meaning and units that they have in a DISPLAY or MODIFY statement.
13. The ID IN phrase returns the control's ID if it has one. If it does not (or the control does not exist), id is set to zero.
14. The CLASS IN phrase returns the type of the control (label, entry field, etc). This is coded as a unique number for each class. The appropriate values can be found in the COPY library "controls.def".
15. The ENABLED IN phrase sets enabled-state to "1" if the control is enabled and "0" if the control is disabled.
16. The VISIBLE IN phrase sets visible-state to "1" if the control is visible and "0" if it is invisible.
Format 2 (INQUIRE WINDOW)
1. The INQUIRE WINDOW statement returns one or more attributes of the window identified by window-handle or generic-handle. If the WINDOW phrase is used and generic-handle is omitted, information is retrieved from the current window.
2. The LINE NUMBER and COLUMN NUMBER phrases return the position of the window relative to the interior of its parent. For the initial window, this will always be line "1", column "1". Note that the position returned can be negative, or larger than the parent window, indicating that the window's upper left corner is outside of its parent's interior.
3. The TITLE phrase returns the title of the current window.
4. The SCREEN LINE and SCREEN COLUMN phrases return the position of the window on the screen. This is an absolute position, not relative to any other window. The position is expressed in the screen's base units, with "1, 1" being the upper left corner of the screen. Screen base units are machine dependent. Under character systems, the base unit is a character cell, for graphical systems, the base unit is a pixel. A negative value indicates that the window's home location (the upper left corner) is off the screen.
5. The SIZE and LINES phrases return the window's width and height, respectively.
6. The SYSTEM HANDLE phrase retrieves the host graphical system's handle that corresponds to the window and stores this value in system-handle. This value is the way the host graphical system identifies the window. You usually need it if you want to affect the window from some other language such as C. There is no use for the host system's handle if you are using only ACUCOBOL-GT; the handle is useful only when you need to have another language interact with an ACUCOBOL-GT screen.
7. Each host system defines its own technique for identifying graphical components. Under Windows, the Windows API uses the "HWND" type. For 32-bit Windows, this is a 32-bit unsigned value. You can use UNSIGNED-INT as an appropriate USAGE type for system-handle to cover these two cases portably.
8. If the window does not have a corresponding host handle, then system-handle is set to zero. This indicates that either the host system does not have an underlying graphical system, or that the particular window does not use the host's notion of a control in its implementation.
9. The VISIBLE option returns in visible-state whether the window is visible or invisible. Visible-state is set to "1" if the window is visible, or "0" if it is invisible.