Resources

More About Resources, I Would Know

• The resources (musicians)
• The application (the conductor)
• The resource file (the seating arrangement)

Table 12.1 shows the types of resources, defined by OS/2, that we look at this chapter
 

All resources are defined using resource identifiers, numeric constants that, together with the type of the resource being referenced, uniquely identify each resource in an application. A resource is said to be loaded when an application needs to use it for the first time; this loading of the resource results in a handle that the application uses when it calls a Presentation Manager function.

Resource Files

DLGINCLUDE  resid filename

Gotcha! Because the original purpose of the dialog file is as described, each DLGINCLUDE statement must have a unique resource identifier. It is not necessary, however, to limit each dialog file to having a single dialog box definition.

Using the Resource Compiler

To compile a resource file, MYAPP.RC, to a .RES file without attaching MYAPP.RES to MYAPPS.EXE, compressing resources, and using "." as a directory to search, the following code would be entered:

RC -R  -X1  -I.  MYAPP.RC

Pointers and Icons

POINTER resid filename

HPOINTER APIENTRY WinLoadPointer(HWND hwndDesktop,
                                 HMODULE hmod,
                                 ULONG idres);

Once a pointer or icon is loaded, it can be drawn in a window with WinDrawPointer  function.

BOOL     APIENTRY WinDrawPointer(HPS hpsWnd,
                                 LONG lX,
                                 LONG lY,
                                 HPOINTER hpPointer,
                                 ULONG ulFlags);

This function returns a flag indicating success or failure.
The WinDrawPointer function is useful for drawing an icon in a window, but it cannot be used to set the mouse pointer to anything. To accomplish this, we instead need the WinSetPointer function.

BOOL     APIENTRY WinSetPointer(HWND hwndDesktop,
                                HPOINTER hptrNew);

Gotcha! Just because the mouse is set to a specified pointer doesn't mean that something else cannot set it to something else. In fact. WinDefWindowProc will set the pointer to the arrow pointer within its processing for the WM_MOUSEMOVE message. Typically, the application would intercept the WM_MOUSEMOVE message and call WinSetPointer at that point to change the mouse pointer and not call WinDefWindowProc.

In addition to any user-drawn pointers or icons, Presentation Manager defines a number of "system pointers": the arrow pointer, the waiting pointer, and some icons that have been discussed come from here. These pointers and icons can be accessed or reloaded using the WinQuerySysPointer function.

HPOINTER APIENTRY WinQuerySysPointer(HWND hwndDesktop,
                                     LONG lptr,
                                     BOOL bLoad);

bLoad specifies whether the handle to the pointer that the system loaded during its initialization should be returned or whether the pointer should be loaded again and a new handle returned. To make modifications to the pointer for use within your application, bLoad should be specified TRUE. This function returns a handle to the specified pointer or to a copy of the specified pointer, depending on the value of bLoad.

Pointers and icons that were loaded explicitly by an application are destroyed using the WinDestroyPointer function.

BOOL     APIENTRY WinDestroyPointer(HPOINTER hpPointer);

Bitmaps

The manner in which a bitmap is specified within a resource file is like that of the pointer and icon.

BITMAP resid filename

HBITMAP  APIENTRY GpiLoadBitmap(HPS hpsWnd,
                                HMODULE hmDll,
                                ULONG idBitmap,
                                LONG lWidth,
                                LONG lHeight);

BOOL  APIENTRY WinDrawBitmap(HPS hpsWnd,
                             HBITMAP hbmBitmap,
                             PRECTL prclSrc,
                             PPOINTL pptlDst,
                             LONG clrFore,
                             LONG clrBack,
                             ULONG ulFlags);

This function returns a flag indicating its success or failure.

We've used the word "monochrome" twice, so it is helpful to be able to determine what the parameters are that were used to create the bitmap. This is done with the GpiQueryBitmapInfoHeader function

BOOL    APIENTRY GpiQueryBitmapInfoHeader(HBITMAP hbmBitmap,
                                          PBITMAPINFOHEADER2 pbmpData);

typedef struct _BITMAPINFOHEADER2        /* bmp2  */
{
   ULONG  cbFix;            /* Length of structure                    */
   ULONG  cx;               /* Bit-map width in pels                  */
   ULONG  cy;               /* Bit-map height in pels                 */
   USHORT cPlanes;          /* Number of bit planes                   */
   USHORT cBitCount;        /* Number of bits per pel within a plane  */
   ULONG  ulCompression;    /* Compression scheme used to store the bitmap */
   ULONG  cbImage;          /* Length of bit-map storage data in bytes*/
   ULONG  cxResolution;     /* x resolution of target device          */
   ULONG  cyResolution;     /* y resolution of target device          */
   ULONG  cclrUsed;         /* Number of color indices used           */
   ULONG  cclrImportant;    /* Number of important color indices      */
   USHORT usUnits;          /* Units of measure                       */
   USHORT usReserved;       /* Reserved                               */
   USHORT usRecording;      /* Recording algorithm                    */
   USHORT usRendering;      /* Halftoning algorithm                   */
   ULONG  cSize1;           /* Size value 1                           */
   ULONG  cSize2;           /* Size value 2                           */
   ULONG  ulColorEncoding;  /* Color encoding                         */
   ULONG  ulIdentifier;     /* Reserved for application use           */
} BITMAPINFOHEADER2;
typedef BITMAPINFOHEADER2 *PBITMAPINFOHEADER2;

The GpiQueryBitmapInfoHeader  function returns a flag indicating success or failure of the function..
In  OS/2 versions l.x. this structure was called BITMAPINFOHEADER and contained only the first five fields. In the current structure, PM developers have enabled programmers to have much more control over the creation of a bitmap (or, in this situation, much mow information about a bitmap). However, they also realized that programmers probably still will use only the first five fields. So,  the Gpi requires only that programmers initialize all fields up to the last one they are interested in and that they specify the number of bytes initialized in the cbFix field; and if the parameters of an existing bitmap are being queried, only cbFix needs to be initialized to specify how many bytes need to be returned. Thus, if cbFix  has the value 16. only the first five fields (sizeof(cbFix) + sizeof(cx) + sizeof(cy) + sizeof(cPlanes) + sizeof(cBitCount) = 16) would be provided, but any value that makes sense, up to the size of the structure, can be specified. Before GpiQueryBitmapInfoHeader is called, cbFix should be initialized to specify bow much information should be returned.
 
 

Gotcha! Initializing cbFix to the proper value is a must when calling the GpiQueryBitmapInfoHeader function, or unpredictable information will be returned.

cx and cy specify the width and height of the bitmap. cPlanes specifies the number of color planes used by the bitmap; while OS/2 supports multiplane bitmaps, the APIs to draw bitmaps support only single-plane bitmaps. cBitCount specifies the number of bits it takes to represent one pel in the bitmap and can have a value 1, 2, 4, 8, or 24; if the value is 1, it is a monochrome bitmap, since it can base only 2¹ colors. ulCompression specifies the compression scheme used to compress the bitmap in memory and can be one of the values listed in Table 12.7.
 

Table 12.7 Values for  ulCompression

Constant	Description
BCA_UNCOMP	Uncompressed
BCA_HUFFMAN1D	Huffman encoding scheme
BCA_RLE4	Run-length encoding for 4 bit-per-pel (BPP) bitmaps
BCA_RLE8	Run-length encoding for 8 BPP bitmaps
BCA_RLE24	Run-length encoding for 24 BPP bitmaps

cbImage specifies how much memory is needed to store the bitmap data. cxResolution and cyResolution specify  the resolution of the device for which the bitmap was intended to be displayed upon. This does not  prohibit the bitmap from being displayed on another display type; it merely indicates the display type for which the bitmap was drawn. cclrUsed, cclrImportant, ulRecording, ulRendering, cSizel, cSize2,  and ulColorEncoding all  specify additional data as described in structure's comments and are beyond the scope of this text.

Bitmaps are destroyed using the GpiDeleteBitmap function.

BOOL     APIENTRY GpiDeleteBitmap(HBITMAP hbmBitmap);

String tables.

Unlike all other resources, string tables do not have a resource identifier explicitly assigned to them by the programmer. Instead, the resource compiler breaks up the string table into groups of 16 strings and automatically assigns an identifier to each 16- string group. A string table has the following form in a resource file.

STRINGTABLE
{  resid1,   "string1"
    rasid2,   "string2"'
    rasid3,   "string3"'
}

LONG    APIENTRY WinLoadString(HAB habAnchor,
                               HMODULE hmDll,
                               ULONG ulId,
                               LONG lSzBuffer,
                               PCSZ  pchBuffer);

That's all there is to it!

Accelerators

ACCELTABLE resid
{
  key, cmd_id, type  [, modifiers ]
  key, cmd_id, type  [, modifiers ]
  key, cmd_id, type  [, modifiers ]
}

Gotcha! If a character (instead of a virtual key) is specified (or an accelerator, it is case-sensitive, so two entries must he provided to cover both possibilities of the shift key stale (unless each case should have different meanings, of course).

ACCELTABLE RES_CLIENT
{  "^O", MI_OPEN
   "^o", MI_OPEN
}

HACCEL APIENTRY WinLoadAccelTable(HAB habAnchor,
                                  HMODULE hmDll
                                  ULONG idAccelTable);

BOOL   APIENTRY WinSetAccelTable(HAB habAnchor,
                                 HACCEL haAccel,
                                 HWND hwndFrame);

For each message queue, there are certain "standard" accelerators that are defined, such as Alt+F4 to close a frame window. These are called "queue accelerators," since they are in effect for the entire message queue and are independent of the active window. If hwndFrame in the call to WinSetAccelTable  is NULLHANDLE, the accelerator table replaces the queue accelerator table.
Accelerator tables are destroyed with the WinDestroyAccelTable function.

BOOL   APIENTRY WinDestroyAccelTable(HACCEL haAccel);

Dialog Boxes

• The DLGTEMPLATE statement
• The DIALOG statement
• One or more child window definitions

DLGTEMPLATE resid
{
  DIALOG "title text", resid, x, y, cx, cy, style, flags
  [CTLDATA controldata]
  [PRESPARAM presparam]
  {  CONTROL "text", id, x, y, cx, cy, class, style
      [CTLDATA controldata]
      [PRESPARAM presparam]
   }
}

Gotcha! The resid on the DLGTEMPLATE and DIALOG statements must match, or the dialog will fail to load. Why the same constant must be specified twice is beyond our understanding.

x,y, cx, and cy are the coordinates of the lower left corner and the size of the dialog or window, respectively. style is one or more style flags;  since a dialog is really nothing more than a subclassed frame window, it can use the FS_ constants in addition to the WS_ constants. The child windows (CONTROL statement) can use the WS_. constants as well as the constants specific to their window class. class can be a WC_ constant or an application-defined class-registered prior to the loading of the dialog with WinRegisterClass - in double quotes.

The control data (CTLDATA statement) is used to initialize the dialog or the child window, as will be shown in later chapters. The presentation parameters (PRESPARAM statement) define the appearance, such as the font used, the foreground and background colors, and so on. See Chapter 9 for more information on setting presentation parameters.
It should be noted that the coordinates and size of the dialog and the child windows are based on a different coordinate system; the units are dialog units, which are based on the average character width of the system font for the resolution of the display. The concept-went-awry is that dialog units are supposed to be "display independent," meaning that the dialog will occupy the same amount of physical space on different resolutions; however, most monitors (in 1995) do not report their pel densities properly, so this rarely works. WinMapDlgPoints  can be used to convert between dialog units and pels.

BOOL    APIENTRY WinMapDlgPoints(HWND hwndDlg,
                                 PPOINTL pptlPoints,
                                 ULONG ulNumPoints,
                                 BOOL bCalcWindowCoords);

Menus

MENU resid 
{    SUBMENU "Text", submenu_id  [,styles]  
    {   MENUITEM "Text", menuitem_id  [,attributes] 
        MENUITEM "Text", menuitem_id  [,attributes] 
     } 
}

Help Tables

Application-defined Data

APIRET APIENTRY  DosGetResource(HMODULE hmDll,
                                ULONG ulType,
                                ULONG ulId,
                                PPVOID ppvData);

APIRET APIENTRY  DosFreeResource(PVOID pvData);

ulId is the resource identifier to be loaded. ppvData is a pointer to a pointer that is initialized by OS/2 to point to the beginning of the resource data. This pointer is specified on the call to DosFreeResource to return the memory consumed to the system, since OS/2 allocates the memory for the programmer when DosGetResource is called.
In the resource file, application-defined data must reside in a separate file and is included via the RESOURCE keyword.

RESOURCE type resid filename