PMGuide - Message Processing: Difference between revisions

Latest revision as of 04:48, 28 April 2025

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference
How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

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.

Combination-Box Control Window Processing

This system-provided window procedure processes the actions on a prompted entry field (combination-box) control (WC_COMBOBOX).

Purpose

A combination-box 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.

When the combination-box control has the focus, the text in the entry field is given selected emphasis and, if the list box control has a matching entry, it is scrolled to show that match at the top of the list.

A combination-box, while sometimes only showing the entryfield, also owns the area occupied by the invisible list box. Another window can and will be clipped to it if they have clipping flags set.

Combination Box Control Styles

These combination-box control styles are available:

CBS_SIMPLE: Both the entry field control and the list box control are visible. When the selection changes in the list box control, the text of the selected item in the list box control is placed in the entry field. Also, the text in the entry field is completed by extending the text of the entry field with the closest match from the list box.
CBS_DROPDOWN: Inherits all the properties of a combination-box control with a style of CBS_SIMPLE and, in addition, the list box control is hidden until the user requests that it should be displayed.
CBS_DROPDOWNLIST: In which the entry field control is replaced by a static control, that displays the current selection from the list box control. The user must explicitly cause the display of the list box control in order to make alternative selections in the list box.

Default Colors

The following system colors are used when the system draws combination-box controls:

SYSCLR_WINDOWFRAME
SYSCLR_ENTRYFIELD
SYSCLR_WINDOW
SYSCLR_BUTTONMIDDLE
SYSCLR_BUTTONDARK
SYSCLR_BUTTONLIGHT
SYSCLR_OUTPUTTEXT
SYSCLR_WINDOWTEXT
SYSCLR_HIGHLITEFOREGROUND
SYSCLR_HIGHLITEBACKGROUND
SYSCLR_FIELDBACKRGOUND
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_FOREGROUNDCOLOR
PP_DISABLEDFOREGROUNDCOLOR
PP_HIGHLIGHTFOREGROUNDCOLOR
PP_FONTNAMESIZE
PP_BORDERCOLOR.

Combo Box Control Notification Messages

The combo box control uses most of the same window messages as the entry field control and the list box control to notify its owner of significant events.

WM_CONTROL (in Combination Boxes)

Combo Box Control Window Messages

The combo box control uses most of the same messages as the entry field control and the list box control. In particular, the following messages are supported to achieve the functions of a combo box. These messages are explained in detail in the entry field control window messages and the list box control window messages sections.

WM_SETWINDOWPARAMS (in Entry Fields): To set the text of the entry field.
WM_QUERYWINDOWPARAMS (in Entry Fields): To obtain the text of the entry field.
LM_QUERYITEMCOUNT: To obtain the count of items in the list box control.
LM_INSERTITEM: To insert an item into the list box control.
LM_SETTOPINDEX: To scroll the list box control so that the specified item is at the top.
LM_QUERYTOPINDEX: To obtain the index of the item at the top of the list box control.
LM_DELETEITEM: To delete an item from the list box control. If necessary, this also changes the content of the entry field to the item at the top of the list box control.
LM_SELECTITEM: To select a specified item in the list box control. Also, this changes the content of the entry field to the item at the top of the list box control and, if the list box control is not visible, causes the list box control to 'dropdown' below the entry field control.
LM_QUERYSELECTION: To obtain the current selection in the list box control.
LM_SETITEMTEXT: To change the text of an item in the list box control. If necessary, this also changes the content of the entry field control.
LM_QUERYITEMTEXT: To obtain the text of an item in the list box control.
LM_QUERYITEMTEXTLENGTH: To obtain the length of the text of an item in the list box control.
LM_SEARCHSTRING: To obtain the index of an item in the list box control containing a specified string.
LM_DELETEALL: To delete all the items in the list box control.
WM_ENABLE: To enable the combo box control to respond to input.
EM_QUERYFIRSTCHAR: To obtain the character displayed at the left edge of the entry field control.
EM_SETFIRSTCHAR: To scroll the entry field control so that the specified character is displayed at the left edge of the entry field control.
EM_QUERYCHANGED: To obtain the changes to the entry field control.
EM_QUERYSEL: To obtain the current selection of the entry field control.
EM_SETSEL: To set the current selection of the entry field control.
EM_SETTEXTLIMIT: To set the maximum number of characters to be contained in the entry field control.
EM_CUT: To place the contents of the selection of the entry field control into the clipboard and then delete those contents from the entry field control.
EM_PASTE: To place the contents of the clipboard into the entry field control.
EM_COPY: To place the contents of the selection of the entry field control into the clipboard.
EM_CLEAR: To clear the current selection of the entry field control.

Container Control Window Processing

This system-provided window procedure processes the actions on a container control (WC_CONTAINER).

Purpose

A container control is a visual component whose specific purpose is to hold objects. These objects, or container items, can be anything that either your application or a user might store in a container. Examples are executable programs, word processing files, graphics images, and database records.

Container item data is stored in RECORDCORE or MINIRECORDCORE data structures. Both the application and the container have access to the data stored in these records.

Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, then MINIRECORDCORE should be used instead of RECORDCORE and PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data structures and messages.

The maximum number of records is limited by the amount of memory in the user's computer. The container control does not limit the number of records that a container can have.

The following list shows which types of data can be displayed for each container view. Refer to the description of the container control in the OS/2 Programming Guide for more information about the types of views.

View Types

Data

Icon view

Icons or bit maps with text strings beneath

Grid view

Icons or bit maps arranged in grid squares

Name view

Icons or bit maps with text strings to the right

Text view

Text strings

Tree view

Icons or bit maps, and text strings

Details view

Icons or bit maps, text strings, numbers, times, and dates.

Direct editing of container item text is supported in all views, including blank text fields.

The container control is designed according to the Common User Access (CUA) guidelines. For example, the CUA direct manipulation protocol is fully supported, enabling a user to visually drag an object in a container window and drop it on another object or container window. In addition, the container control supports CUA-defined selection types and techniques for selecting container items, as well as selection mechanisms, such as pointing devices and the keyboard, and multiple forms of emphasis. For a complete description of CUA containers, refer to the SAA CUA Guide to User Interface Design and to the SAA CUA Advanced Interface Design Reference.

The container control automatically provides or enables either horizontal or vertical scroll bars, or both, whenever all or part of one or more container items are not visible in a container window's client area.

Container Control Window Words

The container control reserves 4 bytes in its window words for application use. This memory can be accessed using the WinSetWindowULong and WinQueryWindowULong functions at offset QWL_USER.

Container Control Styles and Selection Types

Containers are WC_CONTAINER class windows that have the following CCS_container styles and selection types. Container control styles and selection types are specified when the container control is created.

Container Control Styles

The following list defines container style bits that your application can use. These style bits must be set by your application.

CCS_AUTOPOSITION

Automatic positioning, which causes container items displayed in the icon view to be arranged when any of the following occur:

The window size changes
Container items are inserted, removed, sorted, invalidated, or filtered
The font or font size changes
The window title text changes.

In all of these cases, container items are arranged the same as when the CM_ARRANGE message is sent. The CCS_AUTOPOSITION style bit is valid only when it is used with the icon view (CV_ICON).

CCS_MINIRECORDCORE: A record style bit that causes the container to interpret all container records as being smaller than they would otherwise be. If a CM_ALLOCRECORD message is received, all records are interpreted and allocated according to the information in the MINIRECORDCORE data structure instead of the RECORDCORE data structure, which is used if this style bit is not specified.

CCS_READONLY: A read-only style bit for an entire container, which prevents a user from editing any of the text in a container window. If you do not set this style bit, a user can edit any of the text in a container window unless you set the following read-only attributes in the appropriate data structures:

CA_TITLEREADONLY: Sets the container title to read-only. This is an attribute of the CNRINFO data structure's flWindowAttr field.

CRA_RECORDREADONLY: Sets text fields in records to read-only. This is an attribute of the RECORDCORE and MINIRECORDCORE data structures' flRecordAttr field.; Note: If the CCS_MINIRECORDCORE style bit is specified when a container is created, the MINIRECORDCORE should be used instead of RECORDCORE and PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data structures and messages.

CFA_FIREADONLY: Sets column data to read-only. This is an attribute of the FIELDINFO data structure's flData field.

CFA_FITITLEREADONLY: Sets column headings to read-only. This is an attribute of the FIELDINFO data structure's flTitle field.

CCS_VERIFYPOINTERS: A pointer verification style bit, which verifies that the application pointers are members of the container's linked list before they are used. If it is not set, the container does not verify the pointers.

Notes: The CCS_VERIFYPOINTERS style bit does not verify the validity of a pointer. It only verifies whether a pointer is a member of a container's linked list.

After your code has been developed and tested, you may want to remove the CCS_VERIFYPOINTERS style bit in order to improve the container's performance. Otherwise, the container will attempt to verify all pointers, which will slow its response to actions that users perform.

Container Control Selection Types

If a selection type is not specified, single selection is the default. For the tree view, single selection is the only type supported. Refer to the description of the selection types in the SAA CUA Advanced Interface Design Reference for more information.

CCS_SINGLESEL: Single selection, which allows a user to select only one container item at a time. Each time a user selects a container item, the selection of any other container item is cancelled.

CCS_EXTENDSEL: Extended selection, which allows a user to select one or more container items. A user can select one item, a range of items, or multiple ranges of items.

CCS_MULTIPLESEL: Multiple selection, which allows a user to select zero or more container items.

Container Control Data

See the following for information on the container control data structures:

Container Control Notification Messages

These messages are initiated by the container control window to notify its owner of significant events.

WM_CONTROL (in Container Controls)
WM_CONTROLPOINTER (in Container Controls)
WM_DRAWITEM (in Container Controls)

Container Control Notification Codes

The following WM_CONTROL (in Container Controls) notification codes are sent by the container control to its owner.

Container Control Window Messages

This section describes the container control window procedure actions on receiving the following messages.

Default Dialog Processing

This section describes how messages are processed by the default dialog procedure. The default dialog procedure can be called using WinDefDlgProc. A user dialog procedure should make this call for all messages that it does not want to process.

For WM_* messages other than those specified in this section the Default Dialog Procedure takes the same action and sets result to the same value as in Frame Control Window Processing. In the instance of messages that would be sent to FID_CLIENT, they are passed to the default window procedure.

For any other messages the default window procedure takes no action, other than to set reply to NULL.

Default Dialog Messages

This section describes the default dialog procedure actions on receiving the following messages.

WM_CHAR (Default Dialogs)
WM_CLOSE (Default Dialogs)
WM_COMMAND (Default Dialogs)
WM_INITDLG (Default Dialogs)
WM_MATCHMNEMONIC (Default Dialogs)
WM_QUERYDLGCODE

Default File Dialog Processing

This section describes how messages are processed by the default dialog procedure of the file dialog. This standard dialog can be used to provide a common, consistent file selection function.

The file dialog's default procedure can be called using the WinDefFileDlgProc function. A user-provided subclassing dialog procedure should make this call for all messages that it does not process when using the file dialog.

The default dialog procedure of the file dialog sends the messages listed in this section to itself to perform the requested action. This design allows a user-provided dialog procedure to customize the file dialog to its own needs.

File Dialog Messages

This section describes the file dialog procedure actions on receiving the following messages.

Default Font Dialog Processing

This section describes how messages are processed by the default dialog procedure of the font dialog. This standard dialog can be used to provide a common, consistent font selection function.

The font dialog's default procedure can be called using the WinDefFontDlgProc function. A user-provided subclassing dialog procedure should make this call for all messages that it does not process when using the font dialog.

The default dialog procedure of the font dialog sends the messages listed in this section to itself to perform the requested action. This design allows a user-provided dialog procedure to customize the font dialog to its own needs.

Font Dialog Messages

This section describes the font dialog procedure actions on receiving the following messages.

Direct Manipulation (Drag) Message Processing

This section describes the processing that occurs during a direct manipulation operation when the application sends or receives a direct manipulation (DM_*) message.

Direct Manipulation Messages

This section describes messages that an application may send or receive during a direct manipulation operation.

Dynamic Data Exchange Messages

This section describes the message part of the DDE protocol, which is a set of guidelines that allows two applications to share data freely between one another; not necessarily driven directly by user input.

Note: DDE operates between two specific applications, each of which must be aware of the other, and active.

WinDdeInitiate, WinDdePostMsg, and WinDdeRespond are the functions associated with these messages.

Dynamic Data Exchange Messages

This section describes the dynamic data exchange protocol actions on the following messages.

Entry Field Control Window Processing

This system-provided window procedure processes the actions on an entry field control (WC_ENTRYFIELD).

Purpose

An entry field control is a rectangular window that displays a single line of text that the operator can edit. When it has the focus, the cursor marks the current insertion or replacement point.

When working with entry fields, the WM_CONTROL message is of major concern. An entry-field control communicates with its owner by sending WM_CONTROL messages. It contains a notification code in MP1 and a handle to the current entry field in MP2. The return value for WM_CONTROL is 0. Notification codes are denoted by an EN prefix.

For entry field control data see, ENTRYFDATA.

Entry Field Control Styles

These entry field control styles are available:

ES_LEFT: The text in the control is left-justified. This is the default style if neither ES_RIGHT nor ES_CENTER is specified.
ES_RIGHT: The text in the control is right-justified.
ES_CENTER: The text in the control is centered.
ES_AUTOSIZE: The text will be sized to make sure the contents fit.
ES_AUTOSCROLL: If the user tries to move off the end of a line, the control automatically scrolls one-third the width of the window in the appropriate direction.
ES_MARGIN: This style can be used to cause a border to be drawn around the control, with a margin around the editable text. The margin is half a character-width wide and half a character-height high.; When an entry field control with this style is positioned, it adjusts the position so that the text is placed at the position specified. This position differs from the original position by the width of the border and the margin.
ES_READONLY: This style causes a single line entry field to be created in read only state.; When an entry field is in read only state, characters do not get inserted into the text. However the insertion interface is still functional.; The entry field read only state can be altered by use of the EM_SETREADONLY message.
ES_UNREADABLE: This style causes the text to be displayed as an asterisk for each character. It can be used for passwords.
ES_COMMAND: This style identifies the entry field as a command entry field. This information is used by the Help Manager to provide command help if the end user requests help for this field.; Not more than one entry field on each dialog should be given this style.
ES_AUTOTAB: This style indicates that when the field is filled by adding a character to the end of the entry field text, the effect of a tab key will be generated. Inserting or replacing a character in the middle of the text, however, does not result in an autotab.; This style is recommended for use with fixed-length, non-scrollable fields that are filled completely. The maximum length of the entry field text is held in the control data, see ENTRYFDATA.

These entry field controls are intended for countries that use a double-byte character encoding scheme:

ES_SBCS: The text is purely single-byte.; If the number of characters entered exceeds EM_SETTEXTLIMIT, or a DBCS character is entered, the alarm sounds and the last character entered is ignored.
ES_DBCS: The text is purely double byte.; If the number of bytes in the entry field exceeds EM_SETTEXTLIMIT, or an SBCS character is entered, the alarm sounds and the last character entered is ignored.
ES_ANY: The text is a mixture of SBCS and DBCS characters.; If the number of bytes in the input field exceeds EM_SETTEXTLIMIT, the alarm sounds and the last character entered is ignored.; ES_ANY is the default.

Note: If the queue code page is an ASCII code page and the data in the entry field is to be converted to an EBCDIC code page, there is a possibility that shift-in and shift-out characters introduced by the conversion process can cause the converted data to overrun the target field. Coding ES_MIXED protects the target field from overrun in this situation.

ES_MIXED: The text is a mixture of SBCS and DBCS characters which may subsequently be converted from an ASCII DBCS code page to an EBCDIC DBCS code page with a consequent possible increase in the length of the data.

If

DBCSchars*2 + SBCSchars + N > EM_SETTEXTLIMIT

where N starts at 0 and is incremented whenever the string goes from SBCS to DBCS or DBCS to SBCS, the alarm sounds and the last character entered is ignored.

Note: For every conversion from SBCS to DBCS there must be a corresponding return to SBCS (N must be an even number).

Default Colors

The following system colors are used when the system draws button controls:

SYSCLR_ENTRYFIELD
SYSCLR_BUTTONDARK
SYSCLR_BUTTONLIGHT
SYSCLR_OUTPUTTEXT
SYSCLR_WINDOWTEXT
SYSCLR_HIGHLITEFOREGROUND
SYSCLR_HIGHLITEBACKGROUND

Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:

PP_FOREGROUNDCOLOR
PP_DISABLEDFOREGROUNDCOLOR
PP_HIGHLIGHTFOREGROUNDCOLOR
PP_FONTNAMESIZE

Entry Field Control Notification Messages

This message is initiated by the entry field control window to notify its owner of significant events.

WM_CONTROL (in Entry Fields)

Entry Field Control Window Messages

This section describes the entry field control window procedure actions on receiving these messages:

Frame Control Window Processing

This system-provided window procedure processes the actions on a frame window (WC_FRAME). The frame control window procedure sends all messages not processed to FID_CLIENT and sets reply to 0.

For a description of the frame creation flags and the frame control styles, see Frame Creation Flags and Frame Control Styles.
For frame control data, see FRAMECDATA.

Purpose

The window that contains all of the parts listed below is called the frame window. Each of the parts that make up a window, such as the title bar and menu, are separate child windows of the frame window. All of these child windows, except the client window (FID_CLIENT), are called frame controls.

FID_CLIENT is not a frame control, it is an instance of a window class implemented by the application.

The frame window and all of the frame controls are implemented with system-provided preregistered window classes.

The frame window holds together all of the frame controls and FID_CLIENT that make up an application window. The frame window is responsible for arranging the frame controls and the FID_CLIENT as the frame window is sized and moved. It is also responsible for routing specific messages to its frame controls and the FID_CLIENT.

Each of the frame controls and FID_CLIENT are known to the frame window by a system-provided window-identifier value as listed below:

FID_CLIENT: Client window
FID_HORZSCROLL: Horizontal scroll bar
FID_MENU: Application menu
FID_MINMAX: Minimize/Maximize box
FID_SYSMENU: System menu
FID_TITLEBAR: Title bar
FID_VERTSCROLL: Vertical scroll bar.

For correct operation, only one window per frame must be defined with each of the above FID_* values.

Frame Creation Flags

These frame creation flags are available:

FCF_TITLEBAR: Title bar.
FCF_SYSMENU: System menu.
FCF_MENU: Application menu.
FCF_MINMAX: Minimize and Maximize buttons.
FCF_MINBUTTON: Minimize button.
FCF_MAXBUTTON: Maximize button.
FCF_VERTSCROLL: Vertical scroll bar.
FCF_HORZSCROLL: Horizontal scroll bar.
FCF_SIZEBORDER: Sizing border.
FCF_BORDER: Window is drawn with a thin border.
FCF_DLGBORDER: Window is drawn with a standard dialog border.
FCF_ACCELTABLE: Causes an accelerator table to be loaded, for this frame window, from the resource file identified on the WinCreateStdWindow function.
FCF_ICON: Window is created with an icon associated with it that is used to represent the window when it is minimized.

If present, the parameter of the WinCreateStdWindow function must be the identity of an icon. This icon is loaded and associated with the window. When the window is minimized, the icon is shown if the screen is capable of showing it. When the window is destroyed, the icon is also destroyed.

FCF_SHELLPOSITION: The window is created with a size and position determined by the shell, rather than explicitly by the application.
FCF_SYSMODAL: The frame window is System Modal.
FCF_NOBYTEALIGN: When this flag is not set, the frame window is adjusted so that window operations, such as moving, can be performed in an optimized manner. For example, some displays can move a window more quickly if the movement is by a multiple of eight pels.

If this flag is set, such optimizations are not performed and size and position values are honored.

FCF_TASKLIST: When this flag is set, the program title is added to the front of the frame window text, the resulting string is used as the window title and is also entered on the task list.

In this context, the program title is the text string used by the Desktop Manager to identify the program, or the text string specified as a parameter in the START command. If neither string has been defined, the filename and extension of the .EXE file are used as the program title.

Note that a WinSetWindowText will not change the entry in the switch list, a WinChangeSwitchEntry must be done to affect this.

FCF_NOMOVEWITHOWNER: The window should not be moved when its owner is moved. FCF_STANDARD; Same as (FCF_TITLEBAR | FCF_SYSMENU | FCF_MINBUTTON | FCF_MAXBUTTON | FCF_SIZEBORDER | FCF_ICON | FCF_MENU | FCF_ACCELTABLE | FCF_SHELLPOSITION | FCF_TASKLIST).

This value is assumed if any Frame Window is created with no Control Data.

FCF_SCREENALIGN: See FS_SCREENALIGN.
FCF_MOUSEALIGN: See FS_MOUSEALIGN.
FCF_AUTOICON: Performance optimization. When repainting iconized frames, the system will redraw the icon and will not send a WM_PAINT message to the application.
FCF_HIDEBUTTON: Hide button.
FCF_HIDEMAX: Hide and maximize buttons.

Frame Control Styles

These frame control styles are available. Frame styles may only be used when the frame is created from a dialog template.

FS_SCREENALIGN: The coordinates specifying the location of the dialog box are relative to the top left corner of the screen, rather than being relative to the owner window's origin.
FS_MOUSEALIGN: The coordinates specifying the location of the dialog box are relative to the position of the pointing device pointer at the time the window was created. The operating system tries to keep the dialog box on the screen, if possible.
FS_SIZEBORDER: See FCF_SIZEBORDER.
FS_BORDER: See FCF_BORDER.
FS_DLGBORDER: See FCF_DLGBORDER.
FS_SYSMODAL: See FCF_SYSMODAL.
FS_NOBYTEALIGN: See FCF_NOBYTEALIGN.
FS_TASKLIST: See FCF_TASKLIST.
FS_NOMOVEWITHOWNER: See FCF_NOMOVEWITHOWNER.
FS_AUTOICON: See FCF_AUTOICON.

Default Colors

The following system colors are used when the system draws frame controls:

SYSCLR_DIALOGBACKGROUND
SYSCLR_ACTIVETITLE
SYSCLR_INACTIVETITLE
SYSCLR_APPWORKSPACE
SYSCLR_ACTIVEBORDER
SYSCLR_WINDOW
SYSCLR_SHADOW
SYSCLR_WINDOWFRAME
SYSCLR_FIRST

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_SHADOW
PP_FOREGROUNDCOLOR
PP_BORDERCOLOR
PP_DISABLEDBACKGROUNDCOLOR

Frame Control Notification Messages

These messages are initiated by the frame control window to notify the FID_CLIENT window.

WM_MINMAXFRAME (in Frame Controls)

Frame Control Window Messages

This section describes the frame control window procedure actions on receiving the following messages.

WM_ACTIVATE (in Frame Controls)
WM_ADJUSTFRAMEPOS
WM_BUTTON1DBLCLK (in Frame Controls)
WM_BUTTON2DBLCLK (in Frame Controls)
WM_BUTTON1DOWN (in Frame Controls)
WM_BUTTON2DOWN (in Frame Controls)
WM_BUTTON1UP (in Frame Controls)
WM_BUTTON2UP (in Frame Controls)
WM_CALCFRAMERECT (in Frame Controls)
WM_CHAR (in Frame Controls)
WM_CLOSE (in Frame Controls)
WM_COMMAND
WM_DRAWITEM (in Frame Controls)
WM_ERASEBACKGROUND
WM_FLASHWINDOW
WM_FOCUSCHANGE (in Frame Controls)
WM_FORMATFRAME (in Frame Controls)
WM_INITMENU (in Frame Controls)
WM_MEASUREITEM (in Frame Controls)
WM_MENUSELECT (in Frame Controls)
WM_NEXTMENU (in Frame Controls)
WM_OWNERPOSCHANGE
WM_PAINT (in Frame Controls)
WM_QUERYBORDERSIZE
WM_QUERYCONVERTPOS (in Frame Controls)
WM_QUERYFOCUSCHAIN
WM_QUERYFRAMECTLCOUNT
WM_QUERYFRAMEINFO
WM_QUERYICON
WM_QUERYWINDOWPARAMS (in Frame Controls)
WM_SETBORDERSIZE
WM_SETICON
WM_SETWINDOWPARAMS (in Frame Controls)
WM_SIZE (in Frame Controls)
WM_SYSCOMMAND
WM_TRACKFRAME (in Frame Controls)
WM_TRANSLATEACCEL (in Frame Controls)
WM_TRANSLATEMNEMONIC (in Frame Controls)
WM_UPDATEFRAME (in Frame Controls)

Help Manager Message Processing

This section describes the processing of messages sent by the Help Manager or applications in response to requests for help by the user.

Help Manager messages

The following messages are sent by the Help Manager to the application, or by the application to the Help Manager.

Language Support Dialog Processing

This system-provided window procedure processes messages for a dialog that has been created or loaded specifying a 'NULL' dialog procedure.

For any other messages the Language Support Dialog Procedure issues and returns the result of the WinDefDlgProc function.

Language Support Dialog Messages

This section describes the actions taken by the Language Support Dialog Procedure when the following messages are received.

WM_ACTIVATE (Language Support Dialog)
WM_CONTROL (Language Support Dialog)
WM_PAINT (Language Support Dialog)
WM_PPAINT (Language Support Dialog)
WM_SETFOCUS (Language Support Dialog)
WM_SIZE (Language Support Dialog)
WM_SYSCOLORCHANGE (Language Support Dialog)

Language Support Window Processing

This system-provided window procedure processes messages for a window that has been created with a window class specifying a "NULL" window procedure.

This section describes the WM_* messages and the language support window procedure action.

For any other messages the Language Support Window Procedure performs the same actions as the Default Window Procedure.

Language Support Window Messages

This section describes the actions taken by the Language Support Window Procedure when the following messages are received.

WM_ACTIVATE (Language Support Window)
WM_CONTROL (Language Support Window)
WM_PAINT (Langauge Support Window)
WM_PPAINT (Language Support Window)
WM_SETFOCUS (Language Support Window)
WM_SIZE (Language Support Window)
WM_SYSCOLORCHANGE (Language Support Window)

List Box Control Window Processing

This system-provided window procedure processes the actions on a list box control (WC_LISTBOX).

Purpose

A list box control is a window containing a list of items. Each item in a list box contains a text string (0 or more characters) and a handle. The text string is displayed in the list box window. The handle can be used by the application to refer to other data associated with each item.

List Box Control Styles

These list box control styles are available:

LS_HORZSCROLL

The list box control enables the operator to scroll the list box horizontally.

LS_MULTIPLESEL: The list box control enables the operator to select more than one item at any one time. Lists that do not have this style allow only a single selection at any one time. If this style is specified, LS_EXTENDEDSEL should also be specified.
LS_EXTENDEDSEL: If this style is specified, the extended selection user interface is enabled.
LS_OWNERDRAW: The list box control has one or more items that can be drawn by the owner. Typically, these items are represented by bit maps rather than by text strings.
LS_NOADJUSTPOS: If this style is included, the list box control is drawn at the size specified. This can cause parts of an item to be shown.

Default Colors

The following system colors are used when the system draws list-box controls:

SYSCLR_FIELDBACKRGOUND
SYSCLR_BUTTONDARK
SYSCLR_WINDOW
SYSCLR_WINDOWTEXT
SYSCLR_ENTRYFIELD
SYSCLR_HILITEFOREGROUND
SYSCLR_HILITEBACKGROUND
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_DISABLEDFOREGROUNDCOLOR
PP_FOREGROUNDCOLOR
PP_HILITEFOREGROUNDCOLOR
PP_BORDERCOLOR

List Box Control Notification Messages

These messages are initiated by the list box control window to notify its owner of significant events.

WM_CONTROL (in List Boxes)
WM_DRAWITEM (in List Boxes)
WM_MEASUREITEM (in List Boxes)

List Box Control Window Messages

This section describes the list box control window procedure actions on receiving the following messages.

Menu Control Window Processing

This system-provided window procedure processes the actions on a menu control (WC_MENU).

Purpose

A menu control is a child or pull-down window that contains a list of selection items. These items can be represented by text strings, separators, bit maps or menu buttons. Menu templates can be loaded as resources and the menu can be created automatically when the parent window is created. The application can build the menu dynamically by sending MM_INSERTITEM messages. An application can change a menu by sending messages to it.

Menus enable the operator to select one of the items in the list, using the pointing device or the keyboard. When a selection is made, the menu parent is notified by posting a WM_COMMAND, WM_SYSCOMMAND, or WM_HELP message and a unique identifier representing the operator's selection.

Menus automatically resize themselves when items are added and removed. Menus are automatically destroyed when their owner is destroyed.

Typically, an application has an action bar menu and several submenus. The action bar is normally visible, and is a child window in the parent window frame. The submenus are normally hidden and become visible when selections are made on the action bar.

Menu Control Styles

These menu control styles are available:

MS_ACTIONBAR: The items in the list are displayed side-by-side. This style is used to implement a top level menu. Menus that do not have this style are displayed in one or more columns and are submenus associated with an action bar.

All menu controls have styles CS_SYNCPAINT and CS_PARENTCLIP.

MS_CONDITIONALCASCADE

This style is used to specify that the items in this list are a conditional cascade menu. Conditional cascade menus act like normal cascade menus with the exception that the cascade does not automatically open when the user selects it. To open the conditional cascade menu, the mini-pushbutton on the menu item must be selected. If the menu is selected without opening the cascade, the default item in the cascade is selected. The default action on the cascade is identified by a check mark. MS_TITLEBUTTON

Used to identify menus that can be used as buttons in the title bar. Can only be used with MS_ACTIONBAR.

This style causes the menu to be drawn using the CUA colors specified for the title bar rather than the action bar.

MS_VERTICALFLIP

Normally, pull-down menus (the default, without the MS_VERTICALFLIP style) are displayed below their associated action bar item. If there is not room on the screen to display the entire pull-down in this manner, and if there is room to display the pull-down above the action bar, it is displayed above the action bar. Pull-down menus with the MS_VERTICALFLIP style are flipped vertically. That is, they are displayed above the menu if possible, otherwise below it. The vertical flip style must be set explicitly by the application when the window is minimized, and must be reset when it is restored.

If an application action bar contains this style, the style is applied to all pull-down menus belonging to the action bar (the style does not directly affect the display of the action bar). This provides a convenient means for the application to flip the appearance of all pull-down menus.

Menu Item Styles

These menu item styles are available:

MIS_SUBMENU: The item is a submenu. When the user selects this type of item, a submenu is displayed from which the user must make further selection. Items that are not submenu items are command items.
MIS_SEPARATOR: The display object is a horizontal dividing line. This type of item can only be used in pull-down menus. This type of item cannot be enabled, checked, disabled, highlighted, or selected by the user. The functional object is NULL when this style is specified.
MIS_BITMAP: The display object is a bit map.
MIS_TEXT: The display object is a text string.
MIS_BUTTONSEPARATOR: The item is a menu button. Any menu can have zero, one, or two items of this type. These are the last items in a menu and are automatically displayed after a separator bar. The user cannot move the cursor to these items, but can select them with the pointing device or with the appropriate key.
MIS_BREAK: The item begins a new row or column.
MIS_BREAKSEPARATOR: Same as MIS_BREAK, except that it draws a separator between rows or columns of a pull-down menu. This style can only be used within a submenu.
MIS_SYSCOMMAND[[: If this item is selected, the menu notifies the owner by posting a WM_SYSCOMMAND message rather than a WM_COMMAND message.
MIS_OWNERDRAW: Items with this style are drawn by the owner. WM_DRAWITEM and WM_MEASUREITEM notification messages are sent to the owner to draw the item or determine its size.
MIS_HELP: If the item is selected, the menu notifies the owner by posting a WM_HELP message rather than a WM_COMMAND message.
MIS_STATIC: This type of item exists for information purposes only. It cannot be selected with the pointing device or keyboard.

Menu Item Attributes

Applications can get and set the state of these attributes by sending MM_QUERYITEMATTR and MM_SETITEMATTR messages.

These menu item attributes are available:

MIA_HILITED: The state of this attribute is TRUE, if and only if, the item is selected.
MIA_CHECKED: If this attribute is TRUE, a check mark appears next to the item (submenu only).
MIA_DISABLED: This attribute is TRUE if the item is disabled and cannot be selected. The item is drawn in a disabled state.
MIA_FRAMED: If this attribute is TRUE, a frame is drawn around the item (top-level menu only).
MIA_NODISMISS: If the item is selected, the submenu remains down. A menu with this attribute is not hidden until the application or user explicitly does so, for example by selecting either another menu on the action bar or by pressing the escape key.

Default Colors

The following system colors are used when the system draws menu controls:

SYSCLR_WINDOWFRAME
SYSCLR_BUTTONDARK
SYSCLR_BUTTONLIGHT
SYSCLR_SHADOW
SYSCLR_TITLEBOTTOM
SYSCLR_DIALOGBACKGROUND

Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:

PP_FOREGROUNDCOLOR
PP_HILITEFOREGROUNDCOLOR
PP_BORDERCOLOR
PP_DISABLEDFOREGROUNDCOLOR

Menu Control Notification Messages

These messages are initiated by the menu control window procedure to notify its owner of significant events.

WM_COMMAND (in Menu Controls)
WM_DRAWITEM (in Menu Controls)
WM_HELP (in Menu Controls)
WM_INITMENU (in Menu Controls)
WM_MEASUREITEM (in Menu Controls)
WM_MENUEND (in Menu Controls)
WM_MENUSELECT (in Menu Controls)
WM_NEXTMENU (in Menu Controls)

Menu Control Window Messages

This section describes the menu control window procedure actions on receiving the following messages.

Multi-Line Entry Field Control Window Processing

This system-provided window procedure processes the actions on a multi-line entry field control (WC_MLE).

Purpose

A multi-line entry field control is 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.

The text is displayed within a rectangular window. Scroll bars appear if requested.

On all four sides of the text within the window there exists a thin margin area. This margin remains drawn in the window's background color, and characters are never drawn into this margin. Mouse events that occur in the margin are processed differently from mouse events that occur in the text area. The margin should be large enough to be easily clicked on, but not so large as to take up a large quantity of screen space. It is suggested, but not required, that the left and right margins be half the average character width of the system font, and that the top and bottom margins be half the maximum baseline extent of the system font.

Text is defined as a stream of characters, with hard line-break characters in the text. Between any two bytes in the text stream, and at either end of the document, there is an insertion point. Note that in a DBCS environment, it is possible to have an insertion point in the middle of a DBCS character. If such an insertion point is specified in a function, the function will either round the insertion point in a sensible way, or the function will fail with an error code indicating the problem.

The text always contains a selection region, defined by an anchor point and a cursor point. The anchor and cursor points are insertion points. If the MLE window has the focus, the text between these two points is drawn highlighted and the cursor point is indicated by a flashing text cursor. The selection region can be affected by some import/export operations.

The cursor point and the anchor point define the range of the selection. These two points are often the same, in which case no text is selected and only a text cursor (but no highlighting) is displayed. A user can use SHIFT+cursor movement combinations to extend the selection, which leaves the anchor point alone, and moves the cursor point to a new position in the document.

The MLE has three modes:

INSERT/OVERTYPE: This mode determines whether keystrokes are inserted into the text, or whether they overtype existing text. Unlike the other two modes, this mode is maintained by the system. The MLE must merely be aware of the system mode.
READ-ONLY: The keyboard user interface disallows any operations that would change the content of the text, although applications using the MLE can still change the text contents. The application can query this mode, in order that it can disallow application-specific operations.

WORD-WRAP: When this mode is in effect, soft line-breaks are inserted into the text at word boundaries so that the user need not scroll the display horizontally to see all the text. When this mode is off, text is allowed to trail off the right-hand edge of the window.

Notes

The MLE is intended for text under 4Kb in size. Performance will be fast for text up to 32KB in size. Text greater than this will be supported but performance may not be acceptable.

In this section 'CR' denotes carriage-return, and 'LF' denotes line-feed.

Multi-Line Entry Field Control Data

See MLECTLDATA for multi-line entry field control data.

Multi-Line Entry Field Control Styles

These multi-line entry field control styles are available:

MLS_BORDER: Draws a border around the MLE field.
MLS_DISABLEUNDO: Directs the MLE control not to allow undo actions.
MLS_HSCROLL: Adds a horizontal scroll bar to the MLE field. The MLE control enables this scroll bar whenever any line exceeds the width of the MLE field.
MLS_IGNORETAB: Directs the MLE control to ignore the Tab key. It passes the appropriate WM_CHAR to its owner window.
MLS_LIMITVSCROLL: Displays the last MLE line at the bottom of the screen page. When this style is not used, the MLE control shows an empty space between the last MLE line and the bottom of the screen page.
MLS_READONLY: Prevents the MLE field from accepting text from the user. This style is useful for displaying lengthy static text in a client or dialog window.
MLS_VSCROLL: Adds a vertical scroll bar to the MLE field. The MLE control enables this scroll bar whenever the number of lines exceeds the height of the MLE field.
MLS_WORDWRAP: Automatically breaks lines that are longer than the width of the MLE field.

Multi-Line Entry Field Control Notification Messages

This message is initiated by the multi-line entry field window procedure to notify its owner of significant events.

WM_CONTROL (in Multiline Entry Fields)

Multi-Line Entry Field Window Messages

This section describes the multi-line entry field control window procedure actions on receiving the following messages.

MLM_CHARFROMLINE
MLM_CLEAR
MLM_COPY
MLM_CUT
MLM_DELETE
MLM_DISABLEREFRESH
MLM_ENABLEREFRESH
MLM_EXPORT
MLM_FORMAT
MLM_IMPORT
MLM_INSERT
MLM_LINEFROMCHAR
MLM_PASTE
MLM_QUERYBACKCOLOR
MLM_QUERYCHANGED
MLM_QUERYFIRSTCHAR
MLM_QUERYFONT
MLM_QUERYFORMATLINELENGTH
MLM_QUERYFORMATRECT
MLM_QUERYFORMATTEXTLENGTH
MLM_QUERYIMPORTEXPORT
MLM_QUERYLINECOUNT
MLM_QUERYLINELENGTH
MLM_QUERYREADONLY
MLM_QUERYSEL
MLM_QUERYSELTEXT
MLM_QUERYTABSTOP
MLM_QUERYTEXTCOLOR
MLM_QUERYTEXTLENGTH
MLM_QUERYTEXTLIMIT
MLM_QUERYUNDO
MLM_QUERYWRAP
MLM_RESETUNDO
MLM_SEARCH
MLM_SETBACKCOLOR
MLM_SETCHANGED
MLM_SETFIRSTCHAR
MLM_SETFONT
MLM_SETFORMATRECT
MLM_SETIMPORTEXPORT
MLM_SETREADONLY
MLM_SETSEL
MLM_SETTABSTOP
MLM_SETTEXTCOLOR
MLM_SETTEXTLIMIT
MLM_SETWRAP
MLM_UNDO
WM_BUTTON1DBLCLK (in Multiline Entry Fields)
WM_BUTTON1DOWN (in Multiline Entry Fields)
WM_BUTTON1UP (in Multiline Entry Fields)
WM_CHAR (in Multiline Entry Fields)
WM_ENABLE (in Multiline Entry Fields)
WM_MOUSEMOVE (in Mulitline Entry Fields)
WM_QUERYWINDOWPARAMS (in Multiline Entry Fields)
WM_SETWINDOWPARAMS (in Multiline Entry Fields)

Notebook Control Window Processing

This system-provided window procedure processes the actions on a notebook control (WC_NOTEBOOK).

Purpose

A notebook control (WC_NOTEBOOK window class) is 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. It simulates a real-world notebook while improving it by overcoming its natural limitations. A user can select and display pages by using either a pointing device, such as a mouse, or the keyboard.

The notebook is designed to be customizable to meet varying application requirements, while providing an easy-to-use user interface component that can be used to develop products that conform to the Common User Access* (CUA*) user interface guidelines. The application can specify different colors, sizes, and orientations for its notebooks, and whether the notebook should be the old or new style, but the underlying function of the control remains the same.

Old Notebook Control Styles

Old notebook control window styles can be set with a notebook is created. The following styles can be set when creating a notebook control window. If no styles are specified, defaults, which are identified in the following descriptions, are used.

Specify one of the following to determine whether the control is a a solid bound or spiral bound notebook:

BKS_SOLIDBIND: Paints a solid binding on the notebook. This is the default.
BKS_SPIRALBIND: Paints a spiral binding on the notebook.

Specify one of the following to determine where the back pages are positioned:

BKS_BACKPAGESBR: Paints back pages on the notebook's bottom and right sides. This is the default.
BKS_BACKPAGESBL: Paints back pages on the notebook's bottom and left sides.
BKS_BACKPAGESTR: Paints back pages on the notebook's top and right sides.
BKS_BACKPAGESTL: Paints back pages on the notebook's top and left sides.

Specify one of the following to determine the side of the notebook on which the major tabs are positioned. Valid combinations with back pages styles are noted in each definition.

BKS_MAJORTABRIGHT: Places major tabs on the notebook's right edge. Only valid in combination with BKS_BACKPAGESBR or BKS_BACKPAGESTR. This is the default when either of these back pages styles is used.
BKS_MAJORTABLEFT: Places major tabs on the notebook's left edge. Only valid in combination with BKS_BACKPAGESBL or BKS_BACKPAGESTL. This is the default when BKS_BACKPAGESTL is used.
BKS_MAJORTABTOP: Places major tabs on the notebook's top edge. Only valid in combination with BKS_BACKPAGESTR or BKS_BACKPAGESTL.
BKS_MAJORTABBOTTOM: Places major tabs on the notebook's bottom edge. Only valid in combination with BKS_BACKPAGESBR or BKS_BACKPAGESBL. This is the default when BKS_BACKPAGESBL is used.

Specify one of the following to set the shape of the notebook tabs:

BKS_SQUARETABS: Draws tabs with square edges. This is the default.
BKS_ROUNDEDTABS: Draws tabs with rounded edges.
BKS_POLYGONTABS: Draws tabs with polygon edges.

Specify one of the following to position the status line text:

BKS_STATUSTEXTLEFT: Left-justifies status line text. This is the default.
BKS_STATUSTEXTRIGHT: Right-justifies status line text.
BKS_STATUSTEXTCENTER: Centers status line text.

Specify one of the following to position the tab text:

BKS_TABTEXTCENTER: Centers tab text. This is the default.
BKS_TABTEXTLEFT: Left-justifies tab text.
BKS_TABTEXTRIGHT: Right-justifies tab text.

The following styles are not valid with an old notebook:

BKS_TABBEDDIALOG

Indicates a new style notebook.

BKS_BUTTONAREA

Creates a common button area in a new style notebook. This style uses the same area as BKS_POLYGONTABS, and will cause unexpected results if used in an old notebook.

New Notebook Control Styles

New notebook control window styles can be set when a notebook is created. A new notebook is indicated by the BKS_TABBEDDIALOG style being specified. The following styles can be set when creating a notebook control window. If no styles are specified, defaults, which are identified in the following descriptions, are used.

Specify the following to determine the position of the major tabs on the new notebook and the ordering of the tabs in the notebook.

BKS_MAJORTABTOP: Places major tabs on the notebook's top edge. This is the default for a new notebook.
BKS_BACKPAGESTR: Tabs are ordered left to right (default)
BKS_BACKPAGESTL: Tabs are ordered right to left.
BKS_MAJORTABBOTTOM: Places major tabs on the notebook's bottom edge.
BKS_BACKPAGESBR: Tabs are ordered left to right (default)
BKS_BACKPAGESBL: Tabs are ordered right to left.

Specify a common button area:

BKS_BUTTONAREA: Creates a common button area in a new style notebook.

The following styles are ignored for a new notebook:

BKS_SOLIDBIND: Paints a solid binding on the notebook. This is the default.
BKS_SPIRALBIND: Paints a spiral binding on the notebook.
BKS_MAJORTABRIGHT: Places major tabs on the notebook's right edge. This is the default when either of these back pages styles is used.
BKS_MAJORTABLEFT: Places major tabs on the notebook's left edge.
BKS_SQUARETABS: Draws tabs with square edges.
BKS_ROUNDEDTABS: Draws tabs with rounded edges.
BKS_POLYGONTABS: Draws tabs with polygon edges.
BKS_TABTEXTCENTER: Centers tab text.
BKS_TABTEXTLEFT: Left-justifies tab text.
BKS_TABTEXTRIGHT: Right-justifies tab text.
BKS_STATUSTEXTLEFT: Left-justifies status line text.
BKS_STATUSTEXTRIGHT: Right-justifies status line text.
BKS_STATUSTEXTCENTER: Centers status line text.

Notebook Control Data

See the following for descriptions of the notebook control data structures:

Notebook Control Notification Messages

These messages are initiated by the notebook control window to notify its owner of significant events.

WM_CONTROL (in Notebook Controls)
WM_CONTROLPOINTER (in Notebook Controls)
WM_DRAWITEM (in Notebook Controls)

Notebook Control Window Messages

This section describes the notebook control window procedure actions on receiving the following messages.

BKM_CALCPAGERECT
BKM_DELETEPAGE
BKM_INSERTPAGE
BKM_INVALIDATETABS
BKM_QUERYPAGECOUNT
BKM_QUERYPAGEDATA
BKM_QUERYPAGEID
BKM_QUERYPAGEINFO
BKM_QUERYPAGESTYLE
BKM_QUERYPAGEWINDOWHWND
BKM_QUERYSTATUSLINETEXT
BKM_QUERYTABBITMAP
BKM_QUERYTABTEXT
BKM_SETDIMENSIONS
BKM_SETNOTEBOOKBUTTONS
BKM_SETNOTEBOOKCOLORS
BKM_SETPAGEDATA
BKM_SETPAGEINFO
BKM_SETPAGEWINDOWHWND
BKM_SETSTATUSLINETEXT
BKM_SETTABBITMAP
BKM_SETTABCOLOR
BKM_SETTABTEXT
BKM_TURNTOPAGE
WM_CHAR (in Notebook Controls)
WM_PRESPARAMCHANGED (in Notebook Controls)
WM_SIZE (in Notebook Controls)

Scroll Bar Control Window Processing

This system-provided window procedure processes the actions on a scroll bar control (WC_SCROLLBAR).

Purpose

Scroll bars are controls used to indicate that additional information can be displayed in a window, logically to the left or right for horizontal scroll bars, logically above or below for vertical scroll bars. The user interface for scroll bars allows for scrolling one unit or one page at a time, or alternatively picking up the scroll bar slider and moving it to a position in the scroll bar that indicates a logical position in the data.

Scroll Bar Control Data

See SBCDATA for information on scroll bar control data.

Scroll Bar Control Styles

These scroll bar control styles are available:

SBS_HORZ: Create a horizontal scroll bar.
SBS_VERT: Create a vertical scroll bar.
SBS_THUMBSIZE: Indicates the presence of the cVisible and cTotal parameters in the SBCDATA data structure.
SBS_AUTOTRACK: The slider scrolls as more information is being displayed on the screen.
SBS_AUTOSIZE: The scroll bar slider changes size to reflect the amount of data contained in the window.

Default Colors

The following system colors are used when the system draws scroll-bar controls:

SYSCLR_SCROLLBAR
SYSCLR_WINDOWFRAME
SYSCLR_FIELDBACKGROUND
SYSCLR_WINDOW
SYSCLR_BUTTONMIDDLE.

Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:

PP_FOREGROUNDCOLOR
PP_BORDERCOLOR
PP_HILITEFOREGROUNDCOLOR.

Scroll Bar System Values

Applications can use the following system values to create and add control scroll bars:

SV_CXVSCROLL: Width of the vertical scroll-bar.
SV_CYHSCROLL: Height of the horizontal scroll-bar.
SV_CYVSCROLLARROW: Height of the vertical scroll-bar arrow bit maps.
SV_CXHSCROLLARROW: Height of the vertical scroll-bar arrow bit maps.
SV_FIRSTSCROLLRATE: The delay (in milliseconds) before autoscrolling starts, when using a scroll bar.
SV_SCROLLRATE: The delay (in milliseconds) between scroll operations, when using a scroll bar.
SYSCLR_SCROLLBAR: Color for drawing scroll-bar backgrounds.
TID_SCROLL: Timer ID for a reserved scrolling time. This is used for sending notification messages when a scroll-arrow or scroll-bar background is selected.

Scroll Bar Control Notification Messages

These messages are initiated by the scroll bar control window procedure to notify its owner of significant events.

WM_HSCROLL (in Horizontal Scroll Bars)
WM_VSCROLL (in Vertical Scroll Bars)

Scroll Bar Control Window Messages

This section describes the scroll bar control window procedure actions on receiving the following messages.

Slider Control Window Processing

This system-provided window procedure processes the actions on a slider control (WC_SLIDER).

Purpose

A slider control (WC_SLIDER window class) is a visual component whose specific purpose is to allow a user to set, display, or modify a value by moving a slider arm along a slider shaft. Sliders are typically used to allow a user to easily set values that have familiar increments, such as feet, inches, degrees, decibels, and so forth.

However, they can also be used for other purposes when immediate feedback is necessary, such as to blend colors or to show the percentage of a task that has completed. For example, an application might allow a user to mix and match color shades by moving a slider arm, or a read-only slider could be provided that shows how much of a task has completed by filling in the slider shaft as the task progresses. These are just a few examples to show you the many ways in which sliders can be used.

The appearance of and user interaction for a slider is similar to the appearance of and user interaction for a scroll bar. However, these two controls are not interchangeable because each has a distinct purpose. The scroll bar is used to scroll into view information that is outside a window's client area, while the slider is used to set, display, or modify that information, whether it is in the client area or not in the client area.

The slider is designed to be customizable to meet varying application requirements, while providing an easy-to-use user interface component that can be used to develop products that conform to the Common User Access (CUA) user interface guidelines. The application can specify different scales, sizes, and orientations for its sliders, but the underlying function of the control remains the same. For a complete description of CUA sliders, refer to the SAA CUA Guide to User Interface Design and the SAA CUA Advanced Interface Design Reference.

Slider Control Styles

Slider control window styles are set when a slider window is created. The following styles can be set when creating a slider control window. If no styles are specified, defaults, which are identified in the following descriptions, are used.

Specify either of the following to determine the slider's orientation:

SLS_HORIZONTAL: The slider is positioned horizontally. The slider arm can move left and right on the slider shaft. A scale can be placed on top of the slider shaft, below the slider shaft, or in both places. This is the default orientation of the slider.
SLS_VERTICAL: The slider is positioned vertically. The slider arm can move up and down the slider shaft. A scale can be placed on the left side of the slider shaft, on the right side of the slider shaft, or in both places.

Specify one of the following to position the slider within the slider window:

SLS_CENTER: The slider is centered in the slider window. This is the default positioning of the slider.
SLS_BOTTOM: The slider is positioned at the bottom of the slider window. This is valid for horizontal sliders only.
SLS_TOP: The slider is positioned at the top of the slider window. This is valid for horizontal sliders only.
SLS_LEFT: The slider is positioned at the left edge of the slider window. This is valid for vertical sliders only.
SLS_RIGHT: The slider is positioned at the right edge of the slider window. This is valid for vertical sliders only.

Specify one of the following to determine the location of the scale on the slider shaft:

SLS_PRIMARYSCALE1: The slider uses the increment and spacing specified for scale 1 as the incremental value for positioning the slider arm. Scale 1 is displayed above the slider shaft of a horizontal slider and to the right of the slider shaft of a vertical slider. This is the default for a slider.

SLS_PRIMARYSCALE2: The slider uses the increment and spacing specified for scale 2 as the incremental value for positioning the slider arm. Scale 2 is displayed below the slider shaft of a horizontal slider and to the left of the slider shaft of a vertical slider.

Specify one of the following to determine the slider arm's home position:

SLS_HOMELEFT

The slider uses the left edge of the slider as the base value for incrementing. This is the default for horizontal sliders and is valid for horizontal sliders only.

SLS_HOMERIGHT

The slider uses the right edge of the slider as the base value for incrementing. This is valid for horizontal sliders only.

SLS_HOMEBOTTOM: The slider uses the bottom of the slider as the base value for incrementing. This is the default for vertical sliders and is valid for vertical sliders only.
SLS_HOMETOP: The slider uses the top of the slider as the base value for incrementing. This is valid for vertical sliders only.

Specify one of the following to determine the location of the slider buttons. If you do not specify one of these styles, or if conflicting styles are specified, slider buttons are not included in the slider control.

SLS_BUTTONSLEFT: The slider includes incremental slider buttons with the control and places them to the left of the slider shaft. These slider buttons move the slider arm by one position, either left or right, in the direction that is selected. This is valid for horizontal sliders only.
SLS_BUTTONSRIGHT: The slider includes incremental slider buttons with the control and places them to the right of the slider shaft. These slider buttons move the slider arm by one position, either left or right, in the direction that is selected. This is valid for horizontal sliders only.
SLS_BUTTONSBOTTOM: The slider includes incremental slider buttons with the control and places them at the bottom of the slider shaft. These slider buttons move the slider arm by one position, either up or down, in the direction that is selected. This is valid for vertical sliders only.
SLS_BUTTONSTOP: The slider includes incremental slider buttons with the control and places them at the top of the slider shaft. These slider buttons move the slider arm by one position, either up or down, in the direction that is selected. This is valid for vertical sliders only.

Other styles that you can specify:

SLS_SNAPTOINCREMENT: The slider arm, when moved to a position between two specified values on the slider scale, such as between two tick marks, is positioned on the nearest value and is redrawn at that position. If this style is not specified, the slider arm remains at the position to which it is moved.
SLS_READONLY: The slider is created as a read-only slider. This means that the user cannot interact with the slider. It is used merely as a mechanism to present a quantity to the user, such as the percentage of completion of an ongoing task. Visual differences for a read-only slider include a narrow slider arm, no slider buttons and no detents.
SLS_RIBBONSTRIP: As the slider arm moves, the slider fills the slider shaft between the home position and the slider arm with a color value that is different from the slider shaft color, similar to the mercury in a thermometer.
SLS_OWNERDRAW: The application is notified whenever the slider shaft, the ribbon strip, the slider arm, and the slider background are to be drawn.

Slider Control Data

See SLDCDATA.

Slider Control Notification Messages

These messages are initiated by the slider control window to notify its owner of significant events.

WM_CONTROL (in Slider Controls)
WM_CONTROLPOINTER (in Slider Controls)
WM_DRAWITEM (in Slider Controls)

Slider Control Window Messages

This section describes the slider control window procedure actions on receiving the following messages.

SLM_ADDDETENT
SLM_QUERYDETENTPOS
SLM_QUERYSCALETEXT
SLM_QUERYSLIDERINFO
SLM_QUERYTICKPOS
SLM_QUERYTICKSIZE
SLM_REMOVEDETENT
SLM_SETSCALETEXT
SLM_SETSLIDERINFO
SLM_SETTICKSIZE
WM_CHAR (in Slider Controls)
WM_PRESPARAMCHANGED (in Slider Controls)
WM_QUERYWINDOWPARAMS (in Slider Controls)
WM_SETWINDOWPARAMS (in Slider Controls)

Spin Button Control Window Processing

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

Purpose

A spin button control (WC_SPINBUTTON window class) is a visual component whose specific purpose is to give users quick access to a finite set of data. The spin button allows users to select from a scrollable ring of choices. Since users can see only one item at a time, the spin button control should be used only with data that is intuitively related, such as a list of months of the year, or an alphabetic list of cities or states.

A spin button consists of at least one spin field that is a single-line entry field (SLE), and up and down arrows that are stacked on top of one another. These arrows are positioned at the right of the SLE.

You can create multifield spin buttons for those applications in which users must select more than one value. For example, in setting a date the spin button control can provide individual fields for setting the month, day, and year. The first spin field in the spin button could contain a list of months, the second spin field could contain a list of numbers and the third spin field could contain a list of years.

Spin Button Control Styles

Create a spin button using the style bits listed below. These styles can be joined together by using logical ORs (|).

Specify one of the following to determine whether a spin field will be a master or a servant. If neither is specified, SPBS_SERVANT is the default.

SPBS_MASTER: The spin button component consists of at least one single line entry field (SLE), or spin field, and two arrows, the Up Arrow and the Down Arrow. When a spin button contains more than one spin field, the master component contains the spin arrows. If the component contains only one spin field, it should be a master.
SPBS_SERVANT: You can create a multifield spin button by spinning servants from the master.

Specify one of the following to determine the type of characters allowed in the spin field:

SPBS_ALLCHARACTERS: Any character can be typed in the spin field. This is the default.
SPBS_NUMERICONLY: Only the digits 0-9 and the minus sign (-) can be typed in the spin field.
SPBS_READONLY: Nothing can be typed in the spin field.

Specify one of the following to determine how the text is to be presented in the spin field:

SPBS_JUSTLEFT: Left-justify the text. This is the default.
SPBS_JUSTRIGHT: Right-justify the text.
SPBS_JUSTCENTER: Center the text.

Specify the following when you do not want a border around the spin button:

SPBS_NOBORDER: Suppresses drawing a border.

Specify the following to increase the spin speed:

SPBS_FASTSPIN: Enables the spin button to increase the spin speed with time. The speed doubles every two seconds. Note: The spin button skips information when this option is specified. Do not use SPBS_FASTSPIN if the application requires that this field be checked each time a spin up or spin down occurs. Do not specify this option on a master component that has servants spun from it.

Specify the following to pad numeric fields with 0s. This is useful when the spin field contains values that represent time or money.

SPBS_PADWITHZEROS: The output number is padded at the front between the first non-zero digit and the field width, or 11 characters, whichever is the lesser. The negative sign, if there is one, is retained. The maximum number of characters required to display a LONG number is 11.

Spin Button Control Data

See SPBCDATA

Spin Button Control Notification Message

This message is initiated by the spin button control window to notify its owner of significant events.

WM_CONTROL (in Spin Button Controls)

Spin Button Control Window Messages

This section describes the spin button control window procedure actions on receiving the following messages.

Static Control Window Processing

This system-provided window procedure processes the actions on a static control (WC_STATIC).

Purpose

Static controls are simple text fields, bit maps, icons, and boxes that can be used to label or box other controls. Static controls do not accept user input, nor do they send notification messages to their owner.

Static Control Data

None.

Static Control Styles

These static control styles are available:

SS_TEXT: Creates a box with formatted text. The text is formatted before it is displayed according to the setting of these text drawing-style flags:

DT_LEFT: Left-justified text
DT_CENTER: Centered text
DT_RIGHT: Right-justified text; ORed with one of:
DT_TOP: Text is aligned to top of window
DT_VCENTER: Text is aligned vertically in center of window
DT_BOTTOM: Text is aligned to bottom of window; The following text drawing style can also be ORed, but only if DT_TOP and DT_LEFT are also specified:
DT_WORDBREAK: Text is multi-line with word-wrapping at ends of lines.
Note: : For "static" text that can be selected, a Button Control with a style of BS_NOBORDER can be used.

SS_GROUPBOX: A group box static control is a box that has an identifying text string in its upper left corner. Group boxes are used to collect a group of radio buttons or other controls into a single unit.

SS_ICON: Draws an icon. The text of the static control is a string that is used to derive the resource ID from which the icon is loaded. The format of the string is:

The first byte is 0xFF, the second byte is the low byte of the resource ID, and the third byte is the high byte of the resource ID.
The first character is "#"; subsequent characters make up the decimal text representation of the resource ID. This format can be used for specifying a system icon in a resource file. The decimal string is the value of the appropriate SPTR_* constant

If the string is empty or does not follow the format above, no resource is loaded.

The resource is assumed to reside in the resource file of the current process.

This control is resized to the size of the icon.

SS_SYSICON: This style is the same as SS_ICON except that the icon ID is specified as one of the system pointer ID values (SPTR_* values) rather than a resource ID. This style provides a convenient way to include system icons in application dialog boxes.

SS_BITMAP: Draws a bit map. The text of the static control names the bit-map resource, as for SS_ICON.
SS_FGNDRECT: Creates a rectangle filled with the color of the foreground.
SS_BKGNDRECT: Creates a rectangle filled with the color of the background.
SS_FGNDFRAME: Creates a box with frame color equal to the foreground color.
SS_BKGNDFRAME: Creates a box with frame color equal to the background color.
SS_HALFTONERECT: Creates a rectangle filled with halftone shading.
SS_HALFTONEFRAME: Creates a box with halftone shading frame.
SS_AUTOSIZE: The static control will be sized to make sure the contents fit.

Default Colors

The following system colors are used when the system draws static controls:

SYSCLR_WINDOWFRAME
SYSCLR_WINDOWSTATICTEXT
SYSCLR_WINDOW
SYSCLR_BACKGROUND.

Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:

PP_BORDERCOLOR
PP_FOREGROUNDCOLOR.

Static Control Notification Messages

No notification messages are initiated by the static control window procedure.

Static Control Window Messages

This section describes the static control window procedure actions on receiving the following messages.

SM_QUERYHANDLE
SM_SETHANDLE
WM_MATCHMNEMONIC (in Static Controls)
WM_QUERYCONVERTPOS (in Static Controls)
WM_QUERYWINDOWPARAMS (in Static Controls)
WM_SETWINDOWPARAMS (in Static Controls)

Title Bar Control Window Processing

This system-provided window procedure processes the actions on a title bar control (WC_TITLEBAR).

Purpose

The title bar control is the frame control that is used to display the application window title. It is also used to display the active or inactive status of the frame window.

The title bar control also implements the user interface for moving the frame window.

The standard identifier for a title bar control in a frame window is FID_TITLEBAR.

Title Bar Control Styles

There is only one title bar style, the default.

The following system colors are used when the system draws button controls:

SYSCLR_ACTIVETITLETEXTBGND
SYSCLR_ACTIVETITLE
SYSCLR_ACTIVETITLETEXT
SYSCLR_ACTIVETITLETEXTBGND
SYSCLR_INACTIVETITLE
SYSCLR_INACTIVETITLETEXT
SYSCLR_INACTIVETITLETEXTBGND
SYSCLR_TITLEBOTTOM
SYSCLR_(IN)ACTIVETITLETEXTBGND
SYSCLR_(IN)ACTIVETITLE

Some of these defaults can be replaced by using the following presentation parameters in the application resource script file or source code:

PP_FONTNAMESIZE
PP_ACTIVECOLOR
PP_INACTIVECOLOR
PP_ACTIVETEXT*COLOR
PP_INACTIVETEXT*COLOR
PP_ACTIVETEXTFGNDCOLOR
PP_INACTIVETEXTFGNDCOLOR
PP_BORDERCOLOR.

Title Bar Control Notification Messages

These messages are initiated by the title bar control to notify its owner of significant events.

WM_SYSCOMMAND (in Title Bar Controls)
WM_TRACKFRAME (in Title Bar Controls

Title Bar Control Window Messages

This section describes the title bar control window procedure actions on receiving the following messages.

TBM_QUERYHILITE
TBM_SETHILITE
WM_QUERYCONVERTPOS (in Title Bar Controls)
WM_QUERYWINDOWPARAMS (in Title Bars)
WM_SETWINDOWPARAMS (in Title Bar Controls)

Value Set Control Window Processing

This system-provided window procedure processes the actions on a value set control (WC_VALUESET).

Purpose

Like radio buttons, a value set control (WC_VALUESET window class) is a visual component whose specific purpose is to allow a user to select one choice from a group of mutually exclusive choices. However, unlike radio buttons, 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.

Even though text is supported, a value set's primary purpose is to display choices as graphical images. By using graphical images in a value set, you can preserve space on the display screen. You can also allow the user to see exactly what is being selected instead of having to rely on descriptions of the choices. This allows a user to make a selection faster than if the user had to read a description of each choice. For example, if you want to allow a user to choose from a variety of patterns, you can present those patterns as value set choices instead of having to provide a list of radio buttons with description of each pattern.

If long strings of data are to be displayed as choices, radio buttons should be used. However, for small sets of numeric or textual data information, either a value set or radio buttons can be used.

The value set is designed to be customizable to meet varying application requirements, while providing an easy-to-use user interface component that can be used to develop products that conform to the Common User Access (CUA) user interface guidelines. The application can specify different types of items, sizes, and orientations for its value sets, but the underlying function of the control remains the same. For a complete description of CUA value sets, refer to the SAA CUA Guide to User Interface Design and the SAA CUA Advanced Interface Design Reference.

Value Set Control Styles

Value set control window styles are set when a value set window is created.

Set one of the following styles when creating a value set control window. You can override these styles by specifying VIA_BITMAP, VIA_ICON, VIA_TEXT, VIA_RGB, or VIA_COLORINDEX attributes for individual value set items.

VS_BITMAP: The attribute for each value set item is set to the VIA_BITMAP value set item attribute, which means the value set treats each item as a bit map unless otherwise specified. This is the default. The following picture provides an example of a value set with bit maps.

VS_ICON: The attribute for each value set item is set to the VIA_ICON value set item attribute, which means the value set treats each item as an icon unless otherwise specified. The following picture provides an example of a value set with icons.

VS_TEXT: The attribute for each value set item is set to the VIA_TEXT value set item attribute, which means the value set treats each item as a text string unless otherwise specified. The following picture provides an example of a value set with text strings.

VS_RGB: The attribute for each value set item is set to the VIA_RGB value set item attribute, which means the value set treats each item as a RGB color value unless otherwise specified. This style is most often used when you need to create new colors. The picture following the definition of VS_COLORINDEX provides an example of a value set with colors.
VS_COLORINDEX: The attribute for each value set item is set to the VIA_COLORINDEX value set item attribute, which means the value set treats each item as an index into the logical color table unless otherwise specified. This style is most often used when the colors currently available are adequate. The following picture provides an example of a value set with colors.

Specify one or more of the following optional window styles, if desired, by using an OR operator (|) to combine them with the style specified from the preceding list:

VS_BORDER: The value set draws a thin border around itself to delineate the control. The following picture provides an example of a value set with a border.

VS_ITEMBORDER: The value set draws a thin border around each item to delineate it from other items.

Note: The VS_ITEMBORDER style is useful for items that are hard to see, such as faint colors or patterns. The following picture provides an example of a value set with item borders.

VS_RIGHTTOLEFT: The value set interprets column orientation as right-to-left, instead of the default left-to-right arrangement. This means columns are numbered from right-to-left with the rightmost column being 1 and counting up as you move left. Home is the rightmost column and end is the leftmost column.

There is no visible difference between a value set ordered left-to-right and a value set ordered right-to-left. Therefore, if your application uses multiple value sets, the ordering of the items should be consistent in each value set to avoid confusing the user.

Note: The VS_RIGHTTOLEFT style is used on creation of the control. Changing this style after creation causes unexpected results.

VS_SCALEBITMAPS: The value set automatically scales bit maps to the size of the cell. If this style is not used, each bit map is centered in its cell. Also, if the cell is smaller than the bit map, the bit map is clipped to the size of the cell.
VS_OWNERDRAW: The application is notified whenever the background of the value set window is to be painted.

Value Set Control Data

For information on value set control data, see the following:

Value Set Control Notification Messages

These messages are initiated by the value set control window to notify its owner of significant events.

WM_CONTROL (in Value Set Controls)
WM_CONTROLPOINTER (in Value Set Controls)
WM_DRAWITEM (in Value Set Controls)

Value Set Control Window Messages

This section describes the value set control window procedure actions on receiving the following messages.

VM_QUERYITEM
VM_QUERYITEMATTR
VM_QUERYMETRICS
VM_QUERYSELECTEDITEM
VM_SELECTITEM
VM_SETITEM
VM_SETITEMATTR
VM_SETMETRICS
WM_CHAR (in Value Set Controls)
WM_PRESPARAMCHANGED (in Value Set Controls)
WM_QUERYWINDOWPARAMS (in Value Set Controls)
WM_SETWINDOWPARAMS (in Value Set Controls)
WM_SIZE (in Value Set Controls)

Default Window Procedure Message Processing

This system-provided window procedure processes the actions that control the operation of windows.

Purpose

General window messages are used for standard processing. These messages can be requested from the system or sent to the system for information, or for actions such as create window, validate window, track mouse movement, and select and deselect actions.

Reserved Messages

These message ranges are reserved:

WM_USER: All messages below this value are reserved for system use. Private messages must have an identifier with a value of WM_USER or higher.

Note: The operating system uses certain message values higher than WM_USER. These message values should not be used by an application. A partial listing of these messages is in the following figure:

From PMSTDDLG.H:

       #define FDM_FILTER       WM_USER+40
       #define FDM_VALIDATE     WM_USER+41
       #define FDM_ERROR        WM_USER+42

       #define FNTM_FACENAMECHANGED   WM_USER+50
       #define FNTM_POINTSIZECHANGED  WM_USER+51
       #define FNTM_STYLECHANGED      WM_USER+52
       #define FNTM_COLORCHANGED      WM_USER+53
       #define FNTM_UPDATEPREVIEW     WM_USER+54
       #define FNTM_FILTERLIST        WM_USER+55

You should scan your header files to see if other messages have been defined with values higher than WM_USER.

General Window Styles: The window is the mechanism by which the application communicates with the operator. Each window can have a window style that controls the appearance and behavior of the window. There are also class styles that apply to all the windows of a particular class (class being FRAME, BUTTON, and so on).

See Window Class Styles and Window Styles for more information.

Window Class Styles

These window class styles are available:

CS_SIZEREDRAW: Determines whether a window will be redrawn when sized. This style is to be used for a window whose contents are sensitive to the size of the window. For example, the data in some windows can be scaled up or down to fit the size of the Client Area. In other windows, the data remains the same size whatever the size of the window; it is merely clipped if the window is made smaller. The CS_SIZEREDRAW style is to be used in the first instance but not in the second. For more information, see WM_CALCVALIDRECTS.
CS_SYNCPAINT: Window is synchronously repainted. This style causes WS_SYNCPAINT to be set for all windows of this class.
CS_MOVENOTIFY: This class style should be used by a child window if it wants to be notified with a WM_MOVE message when its parent is moved. For more detail, see the WM_MOVE message description.
CS_CLIPCHILDREN: Causes a window of style WS_CLIPCHILDREN to be created, regardless of whether this style bit is specified on the create window function.
CS_CLIPSIBLINGS: Causes a window of style WS_CLIPSIBLINGS to be created, regardless of whether this style bit is specified on the create window function.
CS_PARENTCLIP: Causes a window of style WS_PARENTCLIP to be created, regardless of whether this style bit is specified on the create window function.
CS_SAVEBITS: Causes a window of style WS_SAVEBITS to be created, regardless of whether this style bit is specified on the create window function.
CS_PUBLIC: Causes a public window class to be registered. It is an error if this parameter is specified on any process other than the shell process.
CS_HITTEST: If set, causes a WM_HITTEST message to be sent to the window, before sending any pointing device message.; If not set, no WM_HITTEST message is sent, and it is assumed that the window returns HT_NORMAL if the window is not disabled, and HT_ERROR if the window is disabled.; Top-level frame windows do not have CS_HITTEST set.
CS_FRAME: If set, all windows of this class are expected to behave as frame windows.

Window Styles

These window styles are available:

WS_SYNCPAINT: Window is synchronously repainted.

This style is set for windows that have Class Style CS_SYNCPAINT. Applications can then turn this style on and off to vary the window processing.

System-Provided Window Styles:

WS_ANIMATE: This specifies that window animation will be turned on. Windows animation is a visual effect that occurs when the window is opened or closed; the window seems to zoom out when it is opened, and zoom in when it is closed.

This visual effect also depends on the Animation setting in the System-Settings notebook. If Animation is enabled and this window style is set, window animation occurs when the window is opened or closed. When Animation is disabled in the System-Settings notebook, this style has no effect and no window animation occurs.

WS_CLIPCHILDREN: This specifies that the area occupied by the children of a window is to be excluded when drawing in that window. Normally, it is included.
WS_CLIPSIBLINGS: This specifies that the area occupied by the siblings of a window is to be excluded when drawing in that window. Normally, it is included.
WS_DISABLED: This specifies that the window is disabled. The default is enabled.
WS_MAXIMIZED: This specifies that the frame window is to be created maximized.

When a window is moved or sized in the normal way at least one border should remain on the screen. When a window is maximized and the maximum size is as large as the screen all borders should be positioned just outside the screen.

WS_MINIMIZED: This specifies that the frame window is to be created minimized.
WS_PARENTCLIP: This controls how a window is clipped when a drawing action takes place into the window.

Generally, a WS_PARENTCLIP window is not to draw outside its window rectangle.

WS_SAVEBITS: This specifies that the screen image of the area under a window of this style be saved when the window is made visible.
WS_VISIBLE: This specifies that the window is visible. The default is invisible.

Note: A window can still be visible, in this sense, even if it cannot be seen because it is covered by other windows.

Styles for Windows in Dialogs

WS_GROUP: This identifies the dialog items that make up a group.; This style is to be specified on the first window of any group. Subsequent windows of the group must not have this style. The windows of the group must be adjacent siblings. This can be done by listing the windows consecutively in Dialog Template or by inserting each new window in the group behind the previous one (WinCreateWindow).
WS_TABSTOP: This identifies a dialog item as one to which the operator can TAB.

General Window Messages

This section describes the window procedure actions upon receiving the following messages.