PMGuide - Message Processing

Messages are processed by window and dialog procedures.

Every window has a window procedure. Windows can also be combined into standard windows or dialog boxes. These are special cases of groups of windows that also have their own procedures. A window or dialog procedure must be capable of processing any message. This can be achieved by delegating some message types to the default window, or dialog, procedures by use of the WinDefWindowProc and WinDefDlgProc functions respectively.

Control windows are a special type of child windows. They take the form of objects such as buttons, scroll bars, list boxes, and text entry fields. These child windows process mouse and keyboard input and notify its owner of significant input events. Procedures for these child window controls are inside the Presentation Manager and are often called system-provided window procedures.

All messages have the same form as QMSG. structure.

Message Types

There are two types of window procedure message processing:

• Default window and dialog procedure message processing
• Control window message processing.

These types are described in Default Window and Dialog Procedure Message Processing and Control Window Message Processing. The messages are described in the message groups found on the Contents.

Default Window and Dialog Procedure Message Processing

These window procedures provide default processing for application window procedures:

• Default window and dialog procedure
• Language support window and dialog procedures, which are used if the application specifies a null window procedure
• Default AVIO window procedure.

These messages are described in Default Window Procedure Message Processing. The system-provided window procedures take no action on messages that are not defined in this chapter, and return NULL.

Control Window Message Processing

Controls are predefined classes of child windows that any application can use for input and output. These control classes are predefined:

WC_BUTTON

       Consists of buttons and boxes that the operator can select by clicking the pointing device or using the keyboard. These messages are described in Button Control Window Processing. WC_CIRCULARSLIDER
       Consists of a visual component whose specific purpose is to allow a user to set, display, or modify a value by moving the slider arm around the circular slider dial. Messages are described in Circular Slider Control Window 

Messages.

WC_COMBOBOX

       Consists of an entry field control and a list box control merged into a single control. The list, which is usually limited in size, is displayed below the entry field and offset one dialog box unit to its right. These messages are described in Combination-Box Control Window Processing. 

WC_CONTAINER

       Consists of a visual component whose specific purpose is to hold objects such as executable programs, word processing files, graphics images, and database records. Messages are described in Container Control Window Processing. 

WC_ENTRYFIELD

       Consists of a single line of text that the operator can edit. These messages are described in Entry Field Control Window Processing. 

WC_FRAME

       Consists of a composite window. These messages are described in Frame Control Window Processing. 

WC_LISTBOX

       Presents a list of text items from which the operator can make selections. These messages are described in List Box Control Window Processing. 

WC_MENU

       Presents a list of items, which may be text displayed horizontally as action bars or vertically as pull-down menus. Menus are usually used to provide a command interface to applications. These messages are described in Menu Control Window Processing. 

WC_MLE

       Consists of a rectangular window that displays multiple lines of text that the operator can edit. When it has the focus, the cursor marks the current insertion or replacement point. These messages are described in Multi-Line Entry Field Control Window Processing. 

WC_NOTEBOOK

       Consists of a visual component whose specific purpose is to organize information on individual pages so that a user can find and display that information quickly and easily. Messages are described in Notebook Control Window Processing. 

WC_SCROLLBAR

       Consists of window scroll bars that allow the operator to make a request to scroll the contents of an associated window. These messages are described in Scroll Bar Control Window Processing. 

WC_SLIDER

       Consists of a visual component whose specific purpose is to allow a user to set, display, or modify a value by moving the slider arm along the slider shaft. Messages are described in Slider Control Window Processing. WC_SPINBUTTON
       Presents a scrollable ring of choices from which the operator can select. These messages are described in Spin Button Control Window Processing. 

WC_STATIC

       Consists of simple display items that do not respond to keyboard or pointing device events. These messages are described in Static Control Window Processing. 

WC_TITLEBAR

       Displays the window title or caption and allows the operator to move its owner. These messages are described in Title Bar Control Window Processing. 

WC_VALUESET

       Consists of a visual component whose specific purpose is to allow a user to select one choice from a group of mutually exclusive choices. A value set can use graphical images (bit maps or icons), as well as colors, text, and numbers, to represent the items that a user can select. Messages are described in Value Set Control Window Processing. 

Owner-Notification Messages

Controls are useful because they notify their owners when significant events take place. A control notifies its owner by sending a WM_CONTROL message or by posting a WM_COMMAND or WM_HELP message.

WM_CONTROL

WM_COMMAND

       Param2 contains information that indicates the source of the WM_COMMAND message:

           CMDSRC_PUSHBUTTON
               Posted by a pushbutton control CMDSRC_MENU
               Posted by a menu control CMDSRC_ACCELERATOR
               Posted by WinTranslateAccel CMDSRC_FONTDLG
               Posted by a font dialog. CMDSRC_OTHER
               Other source.

WM_HELP

Param1 contains information that indicates the source of the WM_HELP message:

CMDSRC_PUSHBUTTON
   Posted by a pushbutton control 

CMDSRC_MENU
   Posted by a menu control 

CMDSRC_ACCELERATOR
   Posted by WinTranslateAccel 

CMDSRC_OTHER
   Other source.

Notation Conventions

Each message description contains:

Name

       The message name; a 2-byte identity unique to a message.

       Some message identity values are reserved for the use of the operating system, some are available for use by an application. See Reserved Messages under Default Window Procedure Message Processing.

       For all messages, the first two or three characters of the name indicate the type of window that is related to the message; for example:

LM

           List box control 

SBM

           Scroll bar control. 

Cause

           The principal reason that caused the generation of the message. 

Parameters

           Input and output parameters pertinent to the message.

           There are always two parameters (param1 and param2) and one return value. Any or all of the parameters can be NULL. 

Remarks

           An explanation of the relationship between the parameters in the context of the message and an indication of the expected processing of the message. 

Default

           A definition of how the default window procedures (provided by the system) process the message. 

Note: A message is not equivalent to a call of the same name.

=Button Control Window Processing

This system-provided window procedure processes the actions on a button control (WC_BUTTON).

For information on button control data see BTNCDATA.

Purpose

A button control is a small rectangular child window representing a button that the operator can "switch" on or off. Button controls can be used alone or in groups, and can either be labeled or appear without text. Button controls typically change appearance when the operator clicks a pointing device on them or pressing the space bar when the button has the keyboard focus.

Buttons can be disabled to prevent them from responding when the operator clicks on them. Disabled buttons are displayed using a different emphasis technique (for example, color or half-toning).

Button Control Styles

These button control styles are available:

BS_AUTOCHECKBOX

       An automatic check box automatically toggles its state whenever the user clicks on it. 

BS_AUTORADIOBUTTON

       When clicked, an automatic radio button automatically checks itself and unchecks all other radio buttons in the same group. 

BS_AUTOSIZE

       Buttons with this style are sized automatically to make sure the contents fit.

       If BS_AUTOSIZE is selected when the button is created, and a -1 is specified for either the parameter of WinCreateWindow, (or when creating the button as a resource) then the button's optimal size is calculated to display the its contents. 

BS_AUTO3STATE

       An automatic three-state check box automatically toggles its state when the user clicks on it. 

BS_BITMAP

       Places a bit map instead of text on the push button control. This style works only with the BS_PUSHBUTTON. 

BS_CHECKBOX

       A check box is a small square with a character string to the right. If it is checked, a small black box appears inside the small square. When the box or string is clicked, by clicking on it with the pointing device or pressing the keyboard spacebar when it is active, 

BS_DEFAULT

       A BS_DEFAULT pushbutton is one with a thick border box. It has the same properties as a pushbutton. In addition, the user may press a BS_DEFAULT pushbutton by pressing the RETURN or ENTER key. The intention is the same for user-buttons, but the appearance of a BS_DEFAULT userbutton is application defined.

       This style can be ORed with the BS_PUSHBUTTON and BS_USERBUTTON styles: 

BS_HELP

       The button posts a WM_HELP message rather than a WM_COMMAND message.

       This style can be ORed with the BS_PUSHBUTTON style.

       If both BS_HELP and BS_SYSCOMMAND are set, BS_HELP takes precedence. 

BS_ICON

       Places an icon instead of text on the push button control. This style works only with the BS_PUSHBUTTON style. 

BS_MINIICON

       This enables miniicons (half the size of normal icons) to be placed on the push button control. 

BS_NOBORDER

       The pushbutton is displayed without a border drawn around it. There is no other change in the pushbutton's operation.

       This style can be ORed with the BS_PUSHBUTTON style. 

BS_NOCURSORSELECT

       The radio button does not select itself when given the focus as the result of an arrow key or tab key.

       This style can be ORed with the BS_AUTORADIOBUTTON style. 

BS_NOPOINTERFOCUS

       Buttons with this style do not set the focus to themselves when clicked with the pointing device. This enables the cursor to stay on a control for which information is required, rather than moving to the button. This style has no effect on keyboard interaction. The tab key can still be used as usual to move the focus to the button.

       This style can be ORed with any of the basic button styles. 

BS_NOTEBOOKBUTTON

       A notebook button is identical to a pushbutton except that when it is created as a child of a notebook page it becomes a button in the common button area of the notebook page. If the button is not in a notebook page it will be indistinguishable from a pushbutton. 

BS_PUSHBUTTON

A pushbutton is a box that contains a string. When a button is pushed, by clicking the pointing device on it or pressing the spacebar when it is active, the parent window is notified. BS_RADIOBUTTON

A radio button is similar to a check box, but is typically used in groups in which only one button at a time is checked. When a radio button is clicked or a cursor key is pressed to move within the group, it notifies its owner window. It is then up to the owner window to check the clicked radio button and uncheck all the rest, if necessary.

BS_SYSCOMMAND

The button posts a WM_SYSCOMMAND message rather than a WM_COMMAND message.

This style can be ORed with the BS_PUSHBUTTON style.

If both BS_HELP and BS_SYSCOMMAND are set, BS_HELP takes

BS_TEXT

This enables both text and a bitmap, icon, or miniicon to be placed on the push button control. This style works only with the BS_PUSHBUTTON style, and should be used in conjunction with BS_BITMAP, BS_ICON or BS_MINIICON.

BS_USERBUTTON

This is an application-definable button. The owner window of this style control receives the additional button style BN_PAINT.

BS_3STATE

A three-state check box is identical to a check box control except that its check box can be half-toned as well as the box being checked or unchecked.

When BS_ICON, BS_MINIICON or BS_BITMAP is selected, the image can be activated by specifying the image ID with the button text string. For instance, to load an icon (#define ICON_ID 300), and display it within a button, the button string is set to "#300."

When BS_ICON, BS_MINIICON or BS_BITMAP is selected along with BS_TEXT, the image can still be activated by specifying the following with a zero-terminated text string. format:

   "#<image-id>\t<text>"

where:

   <image-id>
       resource id of the icon, miniicon or bitmap \t
       tab character <text>
       zero-terminated button text string 

   For example, to load an icon (#define ICON_ID 300) and display it with the button text "My Button," the button string is set to "#300\tMy Button." Notice the "\t" is used to separate the text from the image-id. The image is displayed above the text within the button.