ID Number: Q66504
3.00
WINDOWS
Summary:
This article documents the file format used by version 3.0 of the
Windows Program Manager to store the icons in each "group" window.
Note that the format of files with the .GRP extension will change in
future releases of Windows, including Windows versions 3.1 and later.
Therefore, this information is valid only for versions earlier than
3.1.
More Information:
General Layout
--------------
The Program Manager group consists of a header and a variable-size
data space.
Program Group Header
--------------------
The header identifies the group and specifies some global information.
The structure is as follows:
struct tagGROUPHEADER {
char identifier[4];
WORD wCheckSum;
WORD cbGroup;
WORD nCmdShow;
RECT rcNormal;
POINT ptMin;
WORD pName;
WORD wLogPixelsX;
WORD wLogPixelsY;
WORD wBitsPerPixel;
WORD wPlanes;
WORD cItems;
WORD rgiItems[cItems];
};
The identifier field contains the string "PMCC". If this string is not
present in the first 4 bytes of a file, that file will not be a valid
group file. The wCheckSum field is used as an additional check on the
validity of the file: the sum of the words in the file must be 0. When
writing a group file, set wCheckSum accordingly.
The cbGroup field contains the size of the group file. When reading a
group file, if the file is larger than cbGroup, the extra information
should be ignored. When writing a file, set cbGroup to the size of the
file.
The nCmdShow field contains a ShowWindow() index that specifies
whether the group will be minimized (SW_SHOWMINIMIZE), normal
(SW_SHOWNORMAL), or maximized (SW_SHOWMAXIMIZE).
The rcNormal rectangle specifies the window rectangle when the window
is in the normal position (not minimized or maximized). Coordinates
are relative to the Program Manager's MDI client window. The point
ptMin specifies the position at which the group file icon will be
placed when the group is minimized. The pName field is the offset in
the file of the zero-terminated title for the group. This title
appears in the group's caption.
The wLogPixelsX, wLogPixelsY, wBitsPerPixel, and wPlanes fields
contain the corresponding values returned from GetDeviceCaps() for a
screen (or window) DC at the time the icons in this group file were
extracted. If the values do not match the current display when a group
is loaded, the Program Manager will extract the appropriate icons from
the .EXE files.
The cItems field contains the size of the rgiItems field. Each entry
in rgiItems, if non-zero, points to an item structure. Note that
cItems is not necessarily the number of items in the group because
there may be NULL entries in rgiItems. The first item in rgiItems will
be the initially active item when the group is loaded.
Item Data
---------
Item data may appear anywhere after the group header up to the limit
of cbGroup. The offsets in rgiItems point to the following structure:
struct tagITEMINFO {
POINT pt;
WORD iIcon;
WORD cbHeader;
WORD cbANDPlane;
WORD cbXORPlane;
WORD pHeader;
WORD pANDPlane;
WORD pXORPlane;
WORD pName;
WORD pCommand;
WORD pIconPath;
};
The pt field specifies the location of the item's icon within the
group window. The fields cbHeader, cbANDPlane, and cbXORPlane specify
the sizes of each of the three icon components. These three components
are stored at the offsets specified by pHeader, pANDPlane, and
pXORPlane. The name of the item, the command line that it executes,
and the path to the file containing its icon are specified by pName,
pCommand, and pIconPath, respectively. Each of these fields contains
the offset from the beginning of the file to a zero-terminated string.
The iIcon field selects the icon within the icon source file if there
is more than one. It is zero for the first icon in the file. This
index has nothing to do with the identifier of the icon resource; it
is based upon the order that icons appear in the .EXE file.
When adding an icon to a group, append its data to the end of the
item-information section and add the appropriate pointers. When an
item is deleted, information stored below it is moved up to shrink the
size of the group file.
Maintaining Compatibility
-------------------------
An application that reads and writes group files must maintain
compatibility with existing and future versions of the Program Manager
by carefully adhering to a few rules.
The first rule is to use the Program Manager DDE (dynamic data
exchange) interface whenever possible. This interface allows an
application to add groups and items without dealing with the group
file format. Remember to treat direct access to the group files as a
measure of last resort. These files were not originally designed to be
accessed by programs other than the Program Manager.
If the identifier string in the header is not correct, the application
should not load the file; it is not a group file. If the checksum is
not correct, assume that the file is damaged. If the file is smaller
than the header size or the value of cbGroup, the file is damaged. If
the file is larger than cbGroup, checksum the additional data if the
application performs the checksum; otherwise, ignore the additional
data.
Never write a group file that is larger than cbGroup bytes long.
Do not leave "unused" space between structures in the icon data area.
This space will not be recovered and will be wasted. This includes
space at the end of the file (but less than cbGroup).
Do not attempt to add structures and data for private use because the
Program Manager will not maintain the association between private data
and the item if the user edits or deletes the item. The data will be
lost and will waste space in the group file.
If the screen metric fields do not match the metrics of the current
display driver, do not use any of the icon data. If the application
updates the screen metrics, make sure all icons in the group are in
the appropriate format. Icons added to the group must match the format
specified by the screen metrics fields.
Do not update a group manually while the Program Manager is running.
To modify a group while the Program Manager is running, use the DDE
commands documented elsewhere. Updating groups while the Program
Manager is running can cause the Program Manager to crash.
Additional reference words: progman 3.00