WININFO() Function - Get SYSGUI Window Information String
Syntax
WININFO(sysgui,contextid{,ERR=lineref}{,END=lineref})
Description
The WININFO() function returns a string that contains information about the contents of a SYSGUI window.
|
Parameter |
Description |
|
sysgui |
Valid SYSGUI channel. |
|
contextid |
Context ID of the SYSGUI window. |
|
ERR=lineref |
Branch to be taken if an error occurs during execution. |
If the contextid value does
not refer to a valid window in the channel, WININFO() generates an !ERROR=11.
If contextid refers to a window
that is not a top-level window, WININFO() generates an !ERROR=17. If the
returned substring is too large for the workspace, WININFO() generates
an !ERROR=31.
The returned string consists of a series of substrings containing information
about the top-level window and additional substrings for each contained
child window and control. The first child window or control substring
is offset two bytes from the end of the top-level window information substring.
As an example, if the top-level window contains a child window and a number
of controls, the first substring would contain the top-level window information,
the second substring would contain the child window information, and the
remaining substrings would contain information about the controls in the
top-level and child windows.
Note: WININFO() function does not guarantee that it will return data in any particular order.
Top Level Window Substring Format
The following template and table define the format of the top-level window substring:
class:u(1),type:u(1),emask:u(4),flags:u(4),context:i(2),id:u(2),x:u(2),
y:u(2),w:u(2),h:u(2),menuoffset:u(2),childlist:u(2),name:c(1*=0),title:c(1*=0)
|
Field |
Offset/Length |
Description |
|
class,type |
1,2 |
Window type, as defined by CTRL(sysgui,controlid,4). |
|
emask |
3,4 |
Window event mask. |
|
flags |
7,4 |
Window creation flags. Listed in Appendix B, Resource Property Descriptions. |
|
context |
11,2 |
Window context ID. |
|
id |
13,2 |
Context ID the window was created in. |
|
x |
15,2 |
X position, in pixels, of the upper-left corner of the window. |
|
y |
17,2 |
Y position, in pixels, of the upper-left corner of the window. |
|
w |
19,2 |
Width, in pixels, of the window. |
|
h |
21,2 |
Height, in pixels, of the window plus the height of the status bar, if it exists and is visible. |
|
menuoffset |
23,2 |
Starting point of the menu substring within the window information string. If the window's flags do not indicate the presence of a menu, ignore any returned value. |
|
childlist |
25,2 |
Starting point of a child window or control substrings within the window information string. (For child windows that contain controls or child windows.) |
|
name |
27, n |
Null-terminated string containing the name, as defined either by ResBuilder or the SENDMSG() function. If no name is associated, a name is generated using the ID. For example, if a window has an ID of 10, the generated name would be WIN10. |
|
title |
27+ n +1, m |
Null-terminated string that contains the window title. |
To print a decimal form of the id, x, y, w, and h fields, issue DEC($00$+ fieldname$).
Child Window Substring Format
The following template and table define the format of the child window substring:
class:u(1),type:u(1),emask:u(4),flags:u(4),context:i(2),id:u(2),x:u(2),y:u(2),w:u(2),
h:u(2),childlist:u(2),siblinglist:u(2),name:c(1*=0),title:c(1*=0)
|
Field |
Offset/Length |
Description |
|
class,type |
1,2 |
Child window type as defined by CTRL(sysgui,controlid,4). |
|
emask |
3,4 |
Window event mask. |
|
flags |
7,4 |
Child window creation flags, which are listed in Appendix B, Resource Property Descriptions. |
|
context |
11,2 |
Window context ID. |
|
id |
13,2 |
Window ID or the context ID in which the window was created (if there is no ID associated with the window). |
|
x |
15,2 |
X position, in pixels, of the upper-left corner of the window. |
|
y |
17,2 |
Y position, in pixels, of the upper-left corner of the window. |
|
w |
19,2 |
Width, in pixels, of the child window. |
|
h |
21,2 |
Height, in pixels, of the child window plus the height of the status bar, if it exists and is visible. |
|
childlist |
23,2 |
Starting point of child window or control substrings within the window information string. (For child windows that contain controls or child windows.) |
|
siblinglist |
25,2 |
Starting point of the sibling information within the window information string. (For child windows that contain siblings.) |
|
name |
27, n |
Null-terminated string that contains the child window name as defined by ResBuilder or the SENDMSG() function. If there is no name associated with the child window, a name is generated using the ID. For example, if a child window has an ID of 10, the generated name would be CWIN10. |
|
title |
27+ n +1, m |
Null-terminated string that contains the window title. |
To print a decimal form of the id, x, y, w, and h fields, issue DEC($00$+ fieldname$).
Control Substring Format
The following template and table define the format of the control substring:
class:u(1),type:u(1),flags:u(4),id:u(2),x:u(2),y:u(2),w:u(2),h:u(2),reserved:u(2),
siblinglist:u(2),name:c(1*=0),title:c(1*=0)
|
Field |
Offset/Length |
Description |
|
class,type |
1,2 |
Control type as defined by CTRL(sysgui,controlid,4). |
|
flags |
3,4 |
Control creation flags, which are listed in Appendix B, Resource Property Descriptions. |
|
id |
7,2 |
Control ID. |
|
x |
9,2 |
X position, in pixels, of the upper-left corner of the control, within the parent window. |
|
y |
11,2 |
Y position, in pixels, of the upper-left corner of the control, within the parent window. |
|
w |
13,2 |
Width, in pixels, of the control. |
|
h |
15,2 |
Height, in pixels, of the control. |
|
reserved |
17,2 |
Reserved for possible expansion in a later release. |
|
siblinglist |
19,2 |
Starting point of the sibling information within the window information string.(For controls that contain siblings, such as other child windows or controls, within the top-level or child window.) |
|
name |
21, n |
Null-terminated string that contains the control name as defined by ResBuilder or the SENDMSG() function. If there is no name associated with the control, a name is generated using the ID and window name. For example, if a window has an ID of 10 and the control has an ID value of 13, the generated name would be WIN10CTL13. |
|
title |
21+ n +1, m |
Null-terminated string that contains the control title. |
To print a decimal form of the id, x, y, w, and h fields, issue DEC($00$+ fieldname$ ).
Menu Substring Format
The following template and table define the format of the menu substring:
class:u(1),type:u(1),flags:u(4),id:u(2),accelkey:u(2),submenu:u(2),siblingmenu:u(2),
name:c(1*=0),title:c(1*=0)
|
Field |
Offset/Length |
Description |
|
class,type |
1,2 |
Menu type as defined by CTRL(sysgui,controlid,4). |
|
flags |
3,4 |
All relevant flags for the menu item. Menu item flags are listed in Appendix B, Resource Property Descriptions. |
|
id |
7,2 |
Menu item ID. |
|
reserved |
9,2 |
Reserved for future use. |
|
submenu |
11,2 |
Submenu by way of a two-byte offset from the beginning of the string to any submenu associated with this menu ID. If no submenus are accessed through this menu ID, it is set to 0. |
|
siblingmenu |
13,2 |
Sibling menu by way of a two-byte offset from the beginning of the string to any submenu associated with this menu ID. If no sibling menu items are accessed through this menu ID, it is set to 0. |
|
name |
15, n |
Null-terminated string that contains the menu name, as defined either by ResBuilder. If no name is associated, a name is generated based on the ID and the menu. For example, if a menu has an ID of 10, then the generated name would be MENU10. |
|
title |
15+ n +1, m |
Null-terminated string that contains the menu item title. |
All fields are repeated for each menu item. To print a decimal form of the id field, issue DEC($00$+ fieldname$).
Example
rem the following code loops through the top level windows
currently
rem open on the sysgui
temp_data$="class:u(1),type:u(1),emask:u(4),flags:u(4),"
temp_data$=temp_data$+"con_id:u(2),id:u(2),x:u(2),y:u(2),"
temp_data$=temp_data$+"w:u(2),h:u(2),menuoff:u(2),child:u(2),"
temp_data$=temp_data$+"name:c(10*=0),title:c(10*=0)"
dim window_data$:temp_data$
window_list$=""
done=0
context=WINFIRST(sysgui_chan,err=no_windows)
repeat
window_data$=WININFO(sysgui_chan,context)
rem "extract the name and build the list
window_list$=window_list$ + window_data.name$ + $00$
window_list$=window_list$ + str(context) + $0A$
context=WINNEXT(sysgui_chan,context,err=loop_error)
continue
loop_error:
if err=2 then
: done=1,loop_good=1
: else
: done=1,loop_good = 0;
: error_message$="An error " + str(err)
: error_message$=error_message$+" occurred on WINNEXT()."
Until done
no_windows:
stop