PMGuide - Static Controls

A static control is a simple text field, bit map, or icon that an application can use to label, enclose, or separate other control windows. This chapter describes how to create and use static controls in PM applications.

About Static Controls

Unlike the other types of control windows, a static control does not accept user input or send notification messages to its owner. The primary advantage of a static control is that it provides a label or graphic that requires little attention from an application. At most, an application might change the text or position of a static control.

Keyboard Focus

A static control never accepts the keyboard focus. When a static control receives a WM_SETFOCUS message, or when a user clicks the static control, the system advances the focus to the next sibling window that is not a static control. If the control has no siblings, the system gives the focus to the owner of the static control.

Static Control Handle

Every static control is associated with a 32-bit data field. A static control with the SS_BITMAP or SS_ICON style uses this field to store the handle of the bit map or icon that it displays. An application can obtain that handle by sending the SM_QUERYHANDLE message to the control. An application can replace the bit map or icon by sending the SM_SETHANDLE message to the control, specifying a valid icon or bit map handle. Changing the handle causes the system to redraw the control.

For a non-icon or non-bit map static control, the data field is available for application-defined data and has no effect on the appearance of the control.

An application can retrieve the data field of a static control window by calling WinWindowFromID, using the handle of the owner and the window identifier of the static control. The static control window identifier is specified in either the dialog-window template or WinCreateWindow.

Static Control Styles

A static control has style bits that determine whether the control displays text, draws a simple box containing text, displays an icon or a bit map, or shows a framed or unframed colored box. Applications can specify a combination of the following styles for a static control:

Style Name	Description
SS_BITMAP	Draws a bit map. The bit map resource must be provided in the resource-definition file. To include the bit map in a dialog window, the resource identifier must be specified in the text parameter of the CONTROL statement in the resource definition file. To include the bit map in a non-dialog window, the ASCII representation of the identifier must be specified in the pszName parameter of WinCreateWindow, that is, the first byte of the pszName parameter must be the cross-hatch character (#), and the remaining text must be the ASCII representation of the identifier, for example, #125.
SS_BKGNDFRAME	Creates a box whose frame has the background color.
SS_BKGNDRECT	Creates a rectangle filled with the background color.
SS_FGNDFRAME	Creates a box whose frame has the foreground color.
SS_FGNDRECT	Creates a rectangle filled with the foreground color.
SS_GROUPBOX	Creates a box whose upper-right corner contains control text. This style is useful for enclosing groups of radio buttons or check boxes in a box.
SS_HALFTONEFRAME	Creates a box whose frame has halftone shading.
SS_HALFTONERECT	Creates a box filled with halftone shading.
SS_ICON	Draws an icon. The resource identifier for the icon resource is determined the same way as the SS_BITMAP style. The icon resource must be in the resource-definition file.
SS_SYSICON	Draws a system-pointer icon. The resource identifier for the system-pointer resource is determined the same way as the SS_BITMAP style. To display this system pointer, the system calls WinQuerySysPointer with the specified identifier.
SS_TEXT	Creates a box with formatted text. An application can combine various formatting options with this style to produce formatted text in the boundaries of the control. The formatting flags are the same as those used for WinDrawText.

Default Static Control Performance

The messages specifically handled by the predefined static control class (WC_STATIC) are as follows:

Message Name	Description
SM_QUERYHANDLE	Returns the handle associated with the static control window.
SM_SETHANDLE	Sets the handle associated with the static control and invalidates the control window, forcing it to be redrawn.
WM_ADJUSTWINDOWPOS	Adjusts the SWP data structure so that the new window size matches the bit map, icon, or system-pointer dimensions associated with the static control.
WM_CREATE	Sets the text for a static-text control. Loads the bit map or icon resource for the bit map or icon static control. Returns TRUE if the resource cannot be loaded.
WM_DESTROY	Frees the text for a static-text control. Destroys the bit map or icon for a bit map or icon static control. The icon for a system-pointer static control is not destroyed because it belongs to the system.
WM_ENABLE	Invalidates the entire static control window, forcing it to be redrawn.
WM_HITTEST	Returns the value HT_TRANSPARENT for the following static-control styles: SS_BKGNDFRAME, SS_BKGNDRECT, SS_FGNDFRAME, SS_FGNDRECT, SS_GROUPBOX, SS_HALFTONEFRAME, SS_HALFTONERECT. For other styles, this message returns the result of WinDefWindowProc.
WM_MATCHMNEMONIC	Returns TRUE if the mnemonic passed in the mp1 parameter matches the mnemonic in the control-window text.
WM_MOUSEMOVE	Sets the mouse pointer to the arrow pointer and returns TRUE.
WM_PAINT	Draws the static control based on its style attributes.
WM_QUERYDLGCODE	Returns the predefined constant DLGC_STATIC.
WM_QUERYWINDOWPARAMS	Returns the requested window parameters.
WM_SETFOCUS	Sets the focus to the next sibling window that can accept the focus; or if no such sibling exists, sets the focus to the parent window.
WM_SETWINDOWPARAMS	Allows the text to be set (static-text controls only).

Using Static Controls

This section explains how to perform the following tasks:

• Include a static control in a dialog window
• Include a static control in a client window

Including a Static Control in a Dialog Window

To include a static control in a dialog window, you must define the control in a dialog-window template in a resource-definition file. The following resource-definition file creates a dialog window that contains a static-text control and three static-icon controls:

DLGTEMPLATE IDD_TOOLDLG LOADONCALL MOVEABLE DISCARDABLE
  BEGIN
    DIALOG "",
           IDD_TOOLDLG,
           114, 53, 161, 127,
           FS_NOBYTEALIGN |
           FS_DLGBORDER   |
           WS_VISIBLE     |
           WS_SAVEBITS

    BEGIN
      CTEXT "Select a tool",
            IDS_TEXT,
            49, 110, 56, 8,
            SS_TEXT   |
            DT_CENTER |
            DT_TOP    |
            WS_GROUP  |
            WS_VISIBLE

      AUTORADIOBUTTON "Paintbrush",
                      IDB_BRUSH,
                      63, 87, 61, 10,
                      WS_TABSTOP |
                      WS_GROUP   |
                      WS_VISIBLE

      AUTORADIOBUTTON "Scissors",
                      IDB_SCISSORS,
                      63, 64, 60, 10,
                      WS_TABSTOP |
                      WS_VISIBLE

      AUTORADIOBUTTON "Eraser",
                      IDB_ERASER,
                      65, 39, 43, 10,
                      WS_TABSTOP |
                      WS_VISIBLE

      ICON IDI_BRUSH,
           IDI_BRUSHICON,
           33, 84, 22, 16,
           WS_GROUP |
           WS_VISIBLE

      ICON IDI_SCISSORS,
           IDI_SCISSORSICON,
           33, 60, 22, 16,
           WS_GROUP |
           WS_VISIBLE

      ICON IDI_ERASER,
           IDI_ERASERICON,
           33, 36, 22, 16,
           WS_GROUP |
           WS_VISIBLE

      PUSHBUTTON "OK",
                 DID_OK,
                 10, 12, 38, 13,
                 WS_TABSTOP |
                 WS_GROUP   |
                 WS_VISIBLE

      PUSHBUTTON "Cancel",
                 DID_CANCEL,
                 59, 12, 38, 13,
                 BS_DEFAULT |
                 WS_TABSTOP |
                 WS_GROUP   |
                 WS_VISIBLE

      PUSHBUTTON "Help",
                 IDB_HELP,
                 111, 13, 38, 13,
                 BS_HELP    |
                 WS_TABSTOP |
                 WS_GROUP   |
                 WS_VISIBLE
    END
  END

ICON IDI_BRUSH    brush.ico
ICON IDI_SCISSORS scissr.ico
ICON IDI_ERASER   eraser.ico

Including a Static Control in a Client Window

An application can include a static control in a non-dialog window by calling WinCreateWindow with the window class WC_STATIC. The flStyle parameter to WinCreateWindow defines the appearance of the control.

The following code fragment creates a static text control whose size and position are based on the size of the client window and the metrics for the current font:

#define ID_TITLE 5
#define INCL_GPILCIDS

HWND hwnd,hwndStatic,hwndClient;
HPS hps;
RECTL rcl;
FONTMETRICS fm;
ULONG ulTitleLen;
CHAR szTitle[] = "Static Text Controls";

/* Obtain the size of the client window */
WinQueryWindowRect(hwnd, &rcl);

/* Obtain a presentation space handle and */
/* the metrics for the current font       */
hps = WinBeginPaint (hwnd, (HPS) NULL, (PRECTL) NULL);
GpiQueryFontMetrics(hps, sizeof(FONTMETRICS), &fm);

/* Obtain the size of the static control text string */
ulTitleLen = (ULONG) strlen(szTitle);

/* Create the static control. Base the size and  */
/* position on the size of the client window and */
/* the metrics of the current font.              */

hwndStatic = WinCreateWindow(
               hwndClient,                    /* Parent window          */
               WC_STATIC,                     /* Window class           */
               szTitle,                       /* Window text            */
               WS_VISIBLE |                   /* Make it visible        */
               SS_TEXT    |                   /* Static-text control    */
               DT_VCENTER |                   /* Center text vert.      */
               DT_CENTER,                     /* Center text horiz.     */
               ((rcl.xRight / 2) -            /* x position             */
               (ulTitleLen / 2) * fm.lEmInc),
               rcl.yTop - fm.lEmHeight * 2,   /* y position             */
               fm.lEmInc * ulTitleLen,        /* Width                  */
               fm.lEmHeight * 2,              /* Height                 */
               hwndClient,                    /* Owner window           */
               HWND_TOP,                      /* Top of z-order         */
               ID_TITLE,                      /* Window identifier      */
               NULL,                          /* Control data           */
               NULL);                         /* Presentation parameters*/

WinEndPaint(hps);

If your application creates a static control with the SS_ICON or SS_BITMAP style, make sure that the resource identifier specified in the pszName parameter corresponds to an icon or a bit map resource in the resource-definition file. If there is no resource, the application cannot create the static control.