PMGuide - Presentation Parameters

A presentation parameter is a piece of data that can be attached to a window to influence the way it is painted. An application can use system-defined presentation parameters to change the colors used by the various PM controls. It can also use a presentation parameter to change the font used for text. If you want to create your own presentation parameters, you must use indexes above PP_USER.

About Presentation Parameters

An application can attach any presentation parameter to a window. However, the window's implementation determines whether or not the presentation parameter will have an effect on the window. For example, if a window does not contain any text, the window will ignore the setting of a font presentation parameter. In general, a well-behaved window should support the more commonly used presentation parameters, such as those for setting the foreground and background colors and the text font. OS/2 uses presentation parameters to let users change window fonts and colors by dragging colors and fonts from Workplace Shell palettes and dropping them in the window. If a window does not support the correct presentation parameters, it can appear unresponsive to the user's actions.

By default, presentation parameter values are inherited from the window's owner. Suppose you create a dialog window that has radio buttons. You don't have to set the same background color in both the dialog window and the radio buttons because the radio button will inherit its background color from the dialog window. Any time the dialog's background color is changed, the radio button's color changes automatically.

WinSetPresParam is used to attach a presentation parameter to a window. Although any presentation parameter index can be used, windows typically support only a small subset of the possible values. For example, the Presentation Manager controls support the PP_FONTNAMESIZE presentation parameter and several of the color and color index presentation parameters. Setting a supported presentation parameter to a window will cause the window to repaint itself, making use of the new value.

Setting a color presentation parameter to a window does not automatically change a color. It is up to the window's implementation to query the presentation parameter's value, and then use it when updating the window.

Querying and Setting Presentation Parameters

To implement support for a presentation parameter in a window, you need to find out what its value is and when that value has been changed. To query a presentation parameter's value use WinQueryPresParam, passing in the index of the presentation parameter and a buffer large enough for the value to be returned in. For presentation parameters that have string values, the buffer should be large enough to include the null termination character.

The flag QPF_NOINHERIT can be specified if the presentation parameter should not be inherited from the window's owner. Otherwise the system looks up the window's owner chain until it finds an occurrence of the same presentation parameter index.

When a presentation parameter is set or changed, the window receives a WM_PRESPARAMCHANGED message. If only one value is changed, that presentation parameter's index is passed with the message. If more than one value is changed, zero is passed. In the latter case, the window must query all its presentation parameters to find out which ones have changed. In response to the WM_PRESPARAMCHANGED message, the receiving window should repaint itself according to the new values received. It is not possible to reject a presentation parameter change; the new value has already been set by the time the notification message has been received.

WinRemovePresParam is available for removing a presentation parameter from a window.

/*******************************************************************/
/* Set the background color of the window                          */
/*******************************************************************/

lColor = RGB_RED;                         /* RGB color value       */

WinSetPresParam(hwndMain,                 /* window handle         */
                PP_BACKGROUNDCOLOR,       /* background pres param */
                sizeof(lColor),           /* length of pres param  */
                &lColor);                 /* pres param value      */

/* ... in window procedure for hwndMain ... */

case WM_PRESPARAMCHANGED:
/****************************************************************/
/* Message received when a presparam has been changed.          */
/* Invalidate the window to repaint with new color.             */
/****************************************************************/
   WinInvalidateRect(hwndMain, NULL, FALSE);
   break;

case WM_PAINT:
/****************************************************************/
/* Repaint the window                                           */
/****************************************************************/
   hps = WinBeginPaint(hwndMain, NULLHANDLE, NULL);

/****************************************************************/
/* Put presentation space into RGB mode                         */
/****************************************************************/
   GpiCreateLogColorTable(hps, 0, LCOLF_RGB, 0, 0, NULL);

/****************************************************************/
/* Query presentation parameter value for background color      */
/****************************************************************/
   WinQueryPresParam(hwndMain,            /* Window handle         */
                     PP_BACKGROUNDCOLOR,  /* Background presparam  */
                     0,
                     NULL,
                     sizeof(lColor),      /* Length of data buffer */
                     &lColor,             /* Data buffer returned  */
                     0);

/****************************************************************/
/* Fill window with background color retrieved from presparam   */
/****************************************************************/
   WinQueryWindowRect(hwndMain, &rectMain);
   WinFillRect(hps, &rectMain, lColor);

/* ... rest of painting code ... */

   WinEndPaint(hps);
   break;

Creating a Window with a Presentation Parameter

It is possible to pass in presentation parameters when creating a window, using WinCreateWindow. The last parameter pPresParams is a pointer to a PRESPARAMS structure containing an array of PARAM structures, which in turn contain the presentation parameter indexes and values. The size field in PRESPARAMS should be set to the size of the array being passed.

/*******************************************************************/
/* Set a presentation parameter when creating a window             */
/*******************************************************************/

PPRESPARAMS ppresMain;

lColor = RGB_RED;

/*******************************************************************/
/* Allocate space for PRESPARAMS structure and one presparam       */
/*******************************************************************/

ppresMain = (PPRESPARAMS)malloc(sizeof(ULONG) * 4);

/*******************************************************************/
/* Set up PRESPARAMS structure with a background color             */
/*******************************************************************/

ppresMain->cb = sizeof(ULONG) * 3;
ppresMain->aparam[0].id = PP_BACKGROUNDCOLOR;
ppresMain->aparam[0].cb = sizeof(lColor);

memcpy(&ppresMain->aparam[0].ab, &lColor, sizeof(lColor));

/*******************************************************************/
/* Create the window and pass in the background color presparam    */
/*******************************************************************/

hwndMain = WinCreateWindow(hwndFrame,
                           "MainWindow",
                           0,
                           0,
                           0, 0, 0, 0,
                           0,
                           HWND_TOP,
                           FID_CLIENT,
                           NULL,
                           ppresMain);    /* Pass presparam data   */

Specifying PRESPARAMS in a Dialog Template

If you are creating a dialog window, you can specify presentation parameters inside the dialog template. For any window in a dialog template (including the dialog window itself) you may add one or more PRESPARAMS statements to the template following the definition of the control.

Note: For the dialog window, place the PRESPARAMS statement immediately after the DIALOG statement in the template.

DLGTEMPLATE DLG_MYDIALOG
BEGIN
    DIALOG  "Add Expression", DLG_MYDIALOG, 30, 25, 205, 55,
            WS_VISIBLE, FCF_SYSMENU | FCF_TITLEBAR
    /* Set font to be used in dialog */
    PRESPARAMS  PP_FONTNAMESIZE, "10.Helv"
    BEGIN
        LTEXT       "Enter new expression:", -1, 5, 40, 195, 8
        /* Set above static control to yellow text on red background */
        PRESPARAMS  PP_BACKGROUNDCOLOR, RGB_RED
        PRESPARAMS  PP_FOREGROUNDCOLORINDEX, CLR_YELLOW
        ENTRYFIELD  "", -1, 7, 27, 191, 8, ES_MARGIN
        PUSHBUTTON  "OK", DID_OK, 5, 5, 45, 14
    END
END

Querying Color Presentation Parameter Pairs

Many of the color presentation parameters come in pairs. For example, the background color of a window can be set using either PP_BACKGROUNDCOLOR, which takes an RGB color value (for example, RGB_RED), or PP_BACKGROUNDCOLORINDEX, which takes a color index (for example, CLR_RED). The newer presentation parameters do not have a color index equivalent, so it is recommended that you use RGB values wherever possible. RGB presentation parameters will also work with SYSCLR_ index values and negative CLR_ indexes (for example, CLR_BLACK).

WinQueryPresParam can be used to query a pair of color presentation parameters at once. The first parameter takes precedence over the second, and should normally be the RGB presentation parameter. The color index should be the second. If you are querying a color index presentation parameter and you want the color value to be returned as an RGB value, you can specify either QPF_ID1COLORINDEX or QPF_ID2COLORINDEX to convert a color index value to an RGB value.

If a window does not have a presentation parameter set for a particular color, the window must select a default color to use. For example, if there is no value set for PP_FOREGROUNDCOLOR or PP_FOREGROUNDCOLORINDEX, the window has to choose a default foreground color when it paints. The usual practice is to select a corresponding system color (for example, SYSCLR_WINDOWTEXT) and use that to paint the foreground of the window.

The decision of which system color to use is an important one, as system colors can be changed by the user with a Scheme Palette. Your choice should always be appropriate to the functionality of the window. If the user does change a system color, your window will receive a WM_SYSCOLORCHANGED message to notify you that your default colors might have been changed.

If there is no appropriate system color available, you will need to select a hard-coded color value as the default instead.

/****************************************************************/
/* Query presentation parameter value for background color      */
/****************************************************************/

if (WinQueryPresParam(
        hwndMain,                /* Window handle               */
        PP_BACKGROUNDCOLOR,      /* Background presparam (RGB)  */
        PP_BACKGROUNDCOLORINDEX, /* Background presparam (Index)*/
        NULL,
        sizeof(lColor),          /* Length of data buffer       */
        &lColor,                 /* Data buffer returned        */
        QPF_ID2COLORINDEX) == 0) /* Convert 2nd presparam to RGB*/
{
   /*************************************************************/
   /* No presparam found - query default background color       */
   /*************************************************************/

   lColor = WinQuerySysColors(
        HWND_DESKTOP,            /* Desktop window handle       */
        SYSCLR_BACKGROUND,       /* System default background   */
        0);                      /* Reserved                    */
}

GpiSetBackColor(hps, lColor);

Setting a Font Presentation Parameter

There is one font presentation parameter, PP_FONTNAMESIZE, which is used to select the default font for a window. If this presentation parameter is attached to a window, the specified font is automatically selected as the default and is the one used when text-drawing PM functions are called (for example, WinDrawText and GpiCharStringAt).

The format of the font name string is as follows:

<point size>.<face name>[.<modifer>[.<modifier> ...]

where:

• <point size> is the point size of the font
• <face name> is the face name of the font
• <modifier> is one of the following:

 * Bold
 * Italic
 * Underscore
 * Outline
 * Strikeout

Examples are "12.New Times Roman" and "10.Helvetica.Bold.Italic".

Note: Modifiers can be used to create a font with a combination of the listed attributes. Do not use modifiers if a true font of that type is already available. For example, use "10.Helvetica Bold" instead of "10.Helvetica.Bold".

/*******************************************************************/
/* Set the text font for the window                                */
/*******************************************************************/

szFont = "10.Helvetica Bold Italic";

WinSetPresParam(hwndMain,                 /* window handle         */
                PP_FONTNAMESIZE,          /* background pres param */
                strlen(szFont) + 1,       /* length of pres param  */
                szFont);                  /* pres param value      */

Colors Used by PM Controls

PM controls make extensive use of presentation parameters for determining the fonts and colors to paint with. All the controls that display text strings use the font set by the PP_FONTNAMESIZE presentation parameter. The colors used in the controls can be set using presentation parameters. Each control responds to a subset of the color presentation parameters, depending on the type of painting it is required to do. Some of the color presentation parameters are specific to a single control; others are used by many or all of the controls.

When there are no presentation parameters set, a control selects the default colors to use. If nothing else is available, the control will use the default system colors (obtained by calling WinQuerySysColor). When no system color is available, it will use a hard-coded RGB color.

In summary, the colors a control window uses depends on what has been set by the application and the user. The order of precedence (from first to last) for a PM control's choice of colors is as follows:

• Presentation parameters
• Application-specific control colors
• Global control colors
• Default colors (system colors, where available)

For a list of the default colors used by a system PM control, select its name from the following list:

• Static Bitmap
• Static Text
• Group Box
• Push Button
• Check Box
• Radio Button
• Entry Field
• List Box
• Combo Box
• Title Bar
• Menu
• Frame
• Scroll Bar
• Spin Button
• Slider
• Circular Slider
• MLE
• Value Set
• Notebook
• Container