PMGuide - Title-Bar Controls

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 title bar is one of several control windows that comprise a standard frame window, giving the frame window its distinctive look and performance capabilities. This chapter describes how to create and use title-bar control windows in PM applications.

About Title Bars

The title bar in a standard frame window performs the following four functions:

• Displays the title of the window across the top of the frame window
• Changes its highlighted appearance to show whether the frame window is active (Ordinarily, the topmost window on the screen is the active window.)
• Responds to the actions of the user—for example, dragging the frame window to a new location on the screen.
• Flashes (as a result of the WinFlashWindow function) to get the attention of the user.

Once the frame controls are in place in the frame window, an application typically ignores them, because the system handles frame controls. In some cases, however, an application can take control of the title bar by sending messages to the title-bar control window.

Default Title-Bar Behavior

A title-bar control window sends messages to its owner (the frame window) when the control receives user input. Following are the messages that the title-bar control processes. Each message is described in terms of how the title-bar control responds to that message.

Message	Description
TBM_QUERYHILITE	Returns the highlighted state of the title bar.
TBM_SETHILITE	Sets the highlighted state of the title bar, repainting the title bar if the state is changing.
WM_BUTTON1DBLCLK	Restores the title bar if the owner window is minimized or maximized. If the window is neither minimized nor maximized, this message maximizes the window.
WM_BUTTON1DOWN	Sends the WM_TRACKFRAME message to the owner window to start the tracking operation for the frame window.
WM_CREATE	Sets the text for the title bar. Returns FALSE if the text is already set.
WM_DESTROY	Frees the window text for the title bar.
WM_HITTEST	Always returns HT_NORMAL, so that the title bar does not beep when it is disabled. (It is disabled when the frame window is maximized.)
WM_PAINT	Draws the title bar.
WM_QUERYDLGCODE	Returns the predefined constant DLGC_STATIC. The user cannot use the Tab key to move to the title bar in a dialog window.
WM_QUERYWINDOWPARAMS	Returns the requested window parameters.
WM_SETWINDOWPARAMS	Sets the specified window parameters.
WM_WINDOWPOSCHANGED	Returns FALSE. Processes this message to prevent the WinDefWindowProc function from sending the size and show messages.

Using Title-Bar Controls

This section explains how to:

• Include a title bar in a frame window
• Alter the dragging action of a title bar

Including a Title Bar in a Frame Window

An application can include a title bar in a standard frame window by specifying the FCF_TITLEBAR flag in the WinCreateStdWindow function.

The following code fragment shows how to create a standard frame window with a title bar, minimize and maximize (window-sizing) buttons, size border, system menu, and an application menu:

#define ID_MENU_RESOURCE 101

HWND hwndFrame,hwndClient;
UCHAR szClassName[255];

ULONG flControlStyle = FCF_TITLEBAR | FCF_MINMAX | FCF_SIZEBORDER |
                       FCF_SYSMENU  | FCF_MENU;

hwndFrame = WinCreateStdWindow(HWND_DESKTOP, WS_VISIBLE | FS_ACCELTABLE,
                               &flControlStyle, szClassName, "",
                               0, (HMODULE) NULL, ID_MENU_RESOURCE,
                               &hwndClient);

To get the window handle of a title-bar control, an application calls WinWindowFromID, specifying the frame-window handle and a constant identifying the title-bar control, as shown in the following code fragment:

hwndTitleBar = WinWindowFromID(hwndFrame, FID_TITLEBAR);

To set the text of a title bar, an application can use the WinSetWindowText function. The frame window passes the new text to the title-bar control in a WM_SETWINDOWPARAMS message.

Altering Dragging Action

When the user clicks the title bar, the title-bar control sends a WM_TRACKFRAME message to its owner (the frame window). When the frame window receives the WM_TRACKFRAME message, the frame sends a WM_QUERYTRACKINFO message to itself to fill in a TRACKINFO structure that defines the tracking parameters and boundaries. To modify the default behavior, an application must subclass the frame window, intercept the WM_QUERYTRACKINFO message, and modify the TRACKINFO structure. If the application returns TRUE for the WM_QUERYTRACKINFO message, the tracking operation proceeds according to the information in the TRACKINFO structure. If the application returns FALSE, no tracking occurs.