PMGuide - Message Processing
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
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.
Default Colors
The following system colors are used when the system draws button controls:
SYSCLR_BUTTONDEFAULT SYSCLR_BUTTONLIGHT SYSCLR_BUTTONMIDDLE SYSCLR_MENUTEXT SYSCLR_WINDOW SYSCLR_WINDOWFRAME.
Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:
PP_BACKGROUNDCOLOR PP_BORDERCOLOR PP_DISABLEDFOREGROUNDCOLOR PP_FOREGROUNDCOLOR PP_HILITEFOREGROUNDCOLOR.
Button Control Notification Messages
These messages are initiated by the button control window to notify its owner of significant events.
- WM_COMMAND (in Button Controls)
- WM_CONTROL (in Button Controls)
- WM_HELP (in Button Controls)
- WM_SYSCOMMAND
- Button Control Window Messages
- BM_AUTOSIZE
- BM_CLICK
- BM_QUERYCHECK
- BM_QUERYCHECKINDEX
- BM_QUERYHILITE
- BM_SETCHECK
- BM_SETDEFAULT
- BM_SETHILITE
- WM_ENABLE (in Button Controls)
- WM_MATCHMNEMONIC (in Button Controls)
- WM_QUERYCONVERTPOS (in Button Controls)
- WM_QUERYWINDOWPARAMS (in Button Controls)
- WM_SETWINDOWPARAMS (in Button Controls)
Circular Slider Control Window Messages
The system-provided window procedure processes the actions on a circular control (WC_CIRCULARSLIDER).
Purpose
The circular slider control supports values set in analog rather than digital form. This control is intended to emulate the actual controls of stereo and video components.
The circular slider can be used instead of a linear slider. While, at present, there are no particular guidelines as to when a circular slider should replace a linear slider, the circular slider consumes less space on the screen and, therefore, is practical to represent several controls in the same window. For example, for an audio attributes dialog that has volume, balance, bass, and treble controls, you might want to use a linear slider for the volume control (since it is used frequently); but to conserve space and give a more familiar appearance, the circular slider could be used for the balance, bass, and treble.
Circular Slider Control Styles
These circular slider control styles are available:
- CSS_CIRCULARVALUE
Draws a circular thumb, rather than a line, for the value indicator.
- CSS_MIDPOINT
Makes the mid-point tick mark larger.
- CSS_NOBUTTON
Does not display value buttons.
- CSS_NONUMBER
Does not display the value on the dial.
- CSS_NOTEXT
Does not display title text under the dial.
- CSS_POINTSELECT
Permits the values on the circular slider to change immediately when dragged.
Direct manipulation is performed by using a mouse to click on and drag the circular slider. There are two modes of direct manipulation for the circular slider.
The default direct manipulation mode is to scroll to the value indicated by the position of the mouse. This could be important if you used a circular slider for a volume control, for example. Increasing the volume from 0% to 100% too quickly could result in damage to both the user's ears and the equipment.
The other mode of direct manipulation permits the value on the circular slider to change immediately when dragged. This mode is enabled using the CSS_POINTSELECT style bit. When this style is used, the value of the dial can be changed by tracking the value with the mouse, which changes values quickly.
- CSS_PROPORTIONALTICKS
Allow the length of the tick marks to be calculated as a percentage of the radius.
- CSS_360
Permits the scroll range to extend 360 degrees.
CSS_360 forces the CSS_NONUMBER style on. This is necessary to keep the value indicator from corrupting the number value.
Circular Slider Control Data
See CSBITMAPDATA.
Default Colors
The following system colors are used when the system draws circular slider controls:
SYSCLR_BACKGROUNDCOLOR SYSCLR_FOREGROUNDCOLOR
Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:
PP_BACKGROUNDCOLOR PP_BORDERCOLOR
Circular Slider Control Notification Messages
These messages are initiated by the circular slider control window to notify its owner of significant events.
- WM_CONTROL (in Circular Slider Controls)
- WM_CONTROLPOINTER (in Circular Slider Controls)
Circular Slider Control Window Messages
This section describes the Circular Slider Control Window Procedure actions on receiving the following messages.
- CSM_QUERYINCREMENT
- CSM_QUERYRADIUS
- CSM_QUERYRANGE
- CSM_QUERYVALUE
- CSM_SETBITMAPDATA
- CSM_SETINCREMENT
- CSM_SETRANGE
- CSM_SETVALUE
- WM_CHAR (in Circular Slider Controls)
- WM_PRESPARAMCHANGED (in Circular Slider Controls)
- WM_QUERYWINDOWPARAMS (in Circular Slider Controls)
- WM_SETWINDOWPARAMS (in Circular Slider Controls)
Clipboard Message Processing
The clipboard is used by the end-user to transfer data between Presentation Manager* (PM*) applications using the following operations:
- Cut
- Remove from a window, leaving a gap in the source, and save for later use.
- Copy
- Copy from a window, leaving the source intact, and save for later use.
- Paste
Paste the cut or copied data into the window of an application (the target).
Clipboard Messages
This section contains the messages used by the Clipboard.
- WM_DESTROYCLIPBOARD
- WM_DRAWCLIPBOARD
- WM_HSCROLLCLIPBOARD
- WM_PAINTCLIPBOARD
- WM_RENDERALLFMTS
- WM_RENDERFMT
- WM_SIZECLIPBOARD
- WM_VSCROLLCLIPBOARD
.....