RESINFO() Function - Get Resource File Information
Syntax
RESINFO(res_handle,resource${,ERR=lineref})
Description
For BBj-specific information, see RESINFO() Function - BBj.
The RESINFO() function returns a formatted string containing information about the contents of a resource file.
|
Parameter |
Description |
|
res_handle |
Resource handle returned by RESOPEN(). |
|
resource$ |
String returned by RESFIRST(). |
|
ERR=lineref |
Branch to be taken if an error occurs during execution. |
If the resource$ value does
not refer to a valid resource within the file, RESINFO() generates an
!ERROR=11. If the returned substring
is too large for the workspace, RESINFO() generates an !ERROR=31.
If the resource contains a reference to a child window that does not exist
or that references itself, RESINFO() generates an !ERROR=93
and sets TCB(10) to the ID of the control involved.
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.
For 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: RESINFO() 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 the Resource Properties Index. |
|
context |
11,2 |
Window context ID (always -1). |
|
id |
13,2 |
Window ID, as defined when it was created. |
|
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. |
|
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 window, ignore any returned value. |
|
childlist |
25,2 |
Starting point of 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. |
Issue DEC($00$+ fieldname$ ) to print a decimal form of the id, xy, w, and h fields.
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, listed in the Resource Properties Index. |
|
context |
11,2 |
Window context (always -1). |
|
id |
13,2 |
Resource id if standalone child window substring. Control id in the context of the parent window if part of a top-level window substring. |
|
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. |
|
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 have 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. |
Issue DEC($00$+ fieldname$ ) to print a decimal form of the id, x, y, w, and h fields.
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, listed in the Resource Properties Index. |
|
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. |
|
Not used. |
17,2 |
Not used. |
|
siblingmenu |
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, which are listed in the Resource Properties Index. |
|
id |
7,2 |
Menu item ID. |
|
accelkey |
9,2 |
Menu item accelerator key. |
|
submenu |
11,2 |
Submenu through 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, the value is set to 0. |
|
siblingmenu |
13,2 |
Sibling menu through 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, the value is set to 0. |
|
name |
15, n |
Null-terminated string that contains the menu name, as defined either by ResBuilder or the SENDMSG() function. 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, 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 and accelkey
fields, issue DEC($00$+fieldname$).
NOTE: The "id" field
(7,2) returns $0000$ for separator items.
Example
rem build a list of top level forms in a resource file
(.BRC) by name and id
resource_handle=resopen("my_resource_file.brc")
template$="id:u(2),class:u(1),type:u(1)"
dim resource$:template$
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 resource_data$:temp_data$
resource$=RESFIRST(resource_handle,err=er_no_resources)
done=0
repeat
rem is it a top level form?
If resource.class = 0 and resource.type = 1 then
: resource_data$=RESINFO(resource_handle,resource$);
: resource_list$=resource_list$+resource_data.name$;
: resource_list$=resource_list$+$00$+str(resource.id)+$0A$
resource$=RESNEXT(resource_handle,resource$,err=er_loop_error)
continue
er_loop_error:
if err=2 then
: done=1,loop_good = 1
: else
: done=1,loop_good = 0
until done
er_no_resources:
stop