PMGuide - Control Windows

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

A control window is a window that an application uses in conjunction with another window to carry out simple input and output tasks. This chapter describes how to create and use control windows in PM applications.

About Control Windows

Control windows are used most often as part of a frame or dialog window, but they also can be used in a client window. An application can create control windows in a frame window by using frame-control flags in the WinCreateStdWindow function, or it can create control windows individually by calling the WinCreateWindow function.

Including control windows in a dialog window requires the use of a dialog template, which is a data structure that describes a dialog window and its control windows. The system uses the data in the dialog template to create the dialog window and control windows. An application can create a dialog template at run time, or it can use the system resource compiler to create a dialog-template resource.

The operating system provides many types of predefined control windows. An application can create a control of a particular type by specifying the appropriate control-window class name, either in the WinCreateWindow function or in a dialog template. The following is a list of the predefined control-window classes:

Class name	Description
WC_BUTTON	Consists of buttons and boxes the user can select by clicking the pointing device or using the keyboard.
WC_COMBOBOX	Creates a combination-box control, which combines a list-box control and an entry-field control. It allows the user to enter data by typing in the entry field or choosing from a list in the list box.
WC_CONTAINER	Creates a control for the user to group objects in a logical manner. A container can display those objects in various formats or views. The container control supports drag and drop so the user can place information in a container by simply dragging and dropping.
WC_ENTRYFIELD	Consists of a single line of text that the user can edit.
WC_FRAME	A composite window class that can contain child windows of many of the other window classes.
WC_LISTBOX	Presents a list of text items from which the user can make selections.
WC_MENU	Presents a list of items that can be displayed horizontally as action bars, or vertically as pull-down menus. Menus usually are used to provide a command interface to applications.
WC_NOTEBOOK	Creates a control for the user that is displayed as a number of pages. The top page is visible, and the others are hidden, with their presence being indicated by a visible edge on each of the back pages.
WC_SCROLLBAR	Consists of window scroll bars that let the user request to scroll the contents of an associated window.
WC_SLIDER	Creates a control that is usable for producing approximate (analog) values or properties. Scroll bars were used for this function in the past, but the slider provides a more flexible method of achieving the same result, with less programming effort.
WC_SPINBUTTON	Creates a control that presents itself to the user as a scrollable ring of choices, giving the user quick access to the data. The user is presented only one item at a time, so the spin button should be used with data that is intuitively related.
WC_STATIC	Simple display items that do not respond to keyboard or pointing device events.
WC_TITLEBAR	Displays the window title or caption and lets the user move the window's owner.
WC_VALUESET	Creates a control similar in function to the radio buttons but provides additional flexibility to display graphical, textual, and numeric formats. The values set with this control are mutually exclusive.

A control window is always owned by another window, usually a frame or dialog window. This relationship is important because a control window sends WM_CONTROL messages to its owner whenever an input event occurs in the control window. Each WM_CONTROL message includes the identifier of the control window in which the event occurred and a notification code that specifies the nature of the event. An application specifies a control window's ID either in the WinCreateWindow function or in a dialog template. Each ID must be unique.

Control windows are like other predefined window classes in that they respond to standard window-management messages and functions, such as WinSetWindowText and WinShowWindow.

All control-window classes have a set of specific messages they send and receive. The summary at the end of this chapter lists the messages that all control windows have in common.

The system paints most control windows synchronously-that is, it redraws a control window as soon as any part of that window becomes invalid.

Using Control Windows

An application can use control windows in a dialog window, standard frame window, or client window. The following sections describe how to use control windows in an application.

Using Control Windows in a Dialog Window

To use a control window in a dialog window, an application specifies the control in a dialog template in the application's resource-definition file. A dialog template typically includes several control windows. When the application loads the dialog-template resource and displays the dialog window, the system automatically displays the control windows as part of the dialog window.

An application can send messages, through the dialog-window procedure, to a control window to change its state. The control window sends notification messages to the dialog-window procedure. The content of a notification message depends on the type of control window.

Using Control Windows in a Non-Dialog Window

To use a control window in a non-dialog window, an application must call the WinCreateWindow function, using the appropriate window class name. An application usually specifies one of its client windows as the owner of the control window. Therefore, the client-window procedure receives notification messages from the control window. In cases where a control is owned by the frame window (such as a menu control), the notification messages to the frame window are passed to the client window.

Creating a Custom Control Window

The operating system provides the following three ways to create custom control windows:

• Use ownerdraw list boxes and menus or buttons.
• Subclass an existing control-window class.
• Register and implement a window class from scratch.

List boxes and menus can have an ownerdraw style, and buttons can have a user-button style, which cause the system to send a message to the owner of the ownerdraw control whenever the control must be drawn. (If the owner is a frame window, it sends these messages on to its client windows for handling by the client window procedure.) This feature lets an application alter the appearance of a control window. For menus and list boxes, the owner window draws the items within the control, and the system draws the outline of the control. For buttons, the user-button style affects the drawing of the entire control. Subclassing an existing control window is an easy way to create a custom control. The subclass procedure can alter selected behavior of the control window by processing only those messages that affect the selected behaviors. All other messages pass to the original control-window procedure.

The techniques for defining a custom control-window class are the same as those used for creating a client-window class. When you create a custom control-window class, be sure the window procedure can send and receive the messages listed in the two tables following this section.

If an application creates a private control-window class, the name of the private class could be used in the dialog template, just like a predefined window-class constant. For example, if an application defines and registers a window class called "MyControlClass", it could create a dialog window that contains that type of control window by using the following resource definition:

    DLGTEMPLATE IDD_CUSTOM_TEST
    BEGIN
    DIALOG "", IDD_CUSTOM_TEST, 1, 1, 126, 130, FS_DLGBORDER, 0
    BEGIN
        CONTROL "This is Text", IDD_TITLE,
              37, 107, 56, 12,
              WC_STATIC,
              SS_TEXT | DT_CENTER | DT_TOP | DT_WORDBREAK
              | WS_VISIBLE
        CONTROL "Custom Control", IDD_CUSTOM,
              33, 68, 64, 13,
              "MyControlClass",
              WS_VISIBLE
        CONTROL "Okay", DID_OK,
              57, 10, 24, 14,
              WC_BUTTON,
              BS_PUSHBUTTON | BS_DEFAULT | WS_TABSTOP | WS_VISIBLE
        END
    END