PMGuide - Frame Windows
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
Frame Windows
A frame window is the basic window used by most Presentation Manager applications to enable the user to perform manipulation functions. This chapter explains how to create and use frame windows in PM applications.
About Frame Windows
An application nearly always starts with a frame window to create a composite window (for example, a main window) that consists of the frame window, several frame-control windows, and a client window. The frame controls conform to the Common User Access (CUA) user interface guidelines. The frame window coordinates the actions of the frame controls and client window, enabling the composite window to act as a single unit. Frame windows have the preregistered public window class WC_FRAME. The frame-window class, like the preregistered control classes, defines the appearance and behavior of the frame window.
Main Window
The main window of an application, typically, is composed of a frame window and a client window. The frame window usually includes control windows such as a title bar, system menu, menu bar (action bar or menu in user terminology), and scroll bars. A frame window provides the standard services the user expects from a window—for example, moving, sizing, minimizing, and maximizing. The frame window receives input from the control windows (called frame controls) and sends messages to both the frame controls and the client window.
Frame Controls
When creating a frame window, an application also can create one or more frame controls as child windows of the frame window. Most frame windows contain at least a system menu and title bar. Other optional controls might include a menu bar and scroll bar as shown above. An application can create a frame window with specified frame controls by calling WinCreateStdWindow with the appropriate frame-control flags. The frame window owns the child frame-control windows, which can send notification messages that tell the frame window what the user is doing with the frame controls. For example, using a mouse, a user can move a window by clicking the title bar and dragging the window to a new position. The title-bar control responds to the click by sending a message to the frame window, notifying it of the user's request to move the window. Then the frame window tracks the mouse motion and moves the frame window and all of its child windows to the new position. PM, rather than the application, handles the processing of the frame controls, thus providing the user a consistent interface for manipulating and interacting with windowed applications on the screen. Frame controls are described in individual chapters. For more information about control windows, see Control Windows.
Client Window
Every main window has a client window, which is the window in which the application displays output and receives mouse and keyboard input from the user. What an application displays in the client window, how it displays it, and how it interprets input to the window are controlled by the client's application-defined window procedure. An application creates the client window when it creates the frame window. The client window, which is specific to the application, is nearly always created using a private window class (a class registered by the application). Like a frame control, the client window is a child window and is owned by the frame window. This means, for example, that the client window is moved when the frame window moves, is clipped to the frame-window size, and is destroyed when the frame window is destroyed. The relationship between the frame window and the client window allows the frame window to pass messages between other frame controls and the client window. For example, a client window can send a message to the frame window requesting that the frame window change the window title. The frame window, in turn, sends a message to the title-bar control, telling it to change the title of the window.
Additional Frame-Window Items
In addition to its frame controls, a frame window also can contain a sizing border and the minimize and maximize buttons (also known as minimize and maximize icons). These items are not frame controls, because the frame window draws and maintains them. (Frame controls are windows that draw and maintain themselves.) The sizing border encloses the frame window and lets the user change the size of the window using a mouse. The minimize button, at the right end of the title bar, lets the user reduce the frame window to an icon. The maximize button, to the right of the minimize button, lets the user enlarge the window so that it fills the screen. An application can add these items to a frame window by using the FCF_SIZEBORDER, FCF_MAXBUTTON, and FCF_MINBUTTON (or FCF_MINMAX) styles. (The FCF_MINMAX style adds both a maximize button and a minimize button.)
Frame-Control Identifiers
A frame window uses a set of standard constants to identify the frame controls and the client window. The frame-control identifiers all begin with the prefix FID_ and can be used in functions such as WinWindowFromID to uniquely identify a given control or the client window. The frame controls also use these identifiers in notification messages sent to the frame window. The following table describes the frame-control identifiers:
| Identifier | Description |
|---|---|
| FID_CLIENT | Identifies a client window. |
| FID_HORZSCROLL | Identifies a horizontal scroll bar. |
| FID_MENU | Identifies a menu. |
| FID_MINMAX | Identifies the minimize and maximize (window-sizing) buttons. |
| FID_SYSMENU | Identifies a system menu. |
| FID_TITLEBAR | Identifies a title bar. |
| FID_VERTSCROLL | Identifies a vertical scroll bar. |
Frame-Window Creation
An application typically creates a frame window by using WinCreateStdWindow, which creates a frame window, a client window, and the specified frame controls. The application also can call WinCreateWindow with the WC_FRAME window class, which creates the frame window and controls but not the client window. To create the client, the application can call WinCreateWindow, specifying the original frame window as the parent and owner.
An application also can use a frame window to create a dialog window. For a dialog window, the frame window contains control windows but no client window. The application creates the dialog window by using WinLoadDlg or WinCreateDlg. These functions require an appropriate dialog template from the application's resource-definition file. The dialog template specifies the styles and dimensions for the frame window and for the control windows that compose the dialog window.
Frame Window Controls and Styles
An application uses frame-control flags in WinCreateStdWindow to specify which frame controls to give to the frame window. Frame-control flags are constants that have the FCF_ prefix.
The frame-window class (WC_FRAME}), like other public window classes, provides many class-specific window styles that applications can use to adapt the appearance and behavior of a frame window. To specify the frame-window styles, an application can use either frame-control flags or the frame-window style constants, which have the FS_ prefix. Each style constant has a corresponding frame-control flag. Both produce exactly the same styles in a frame window. Typically, if an application is creating a frame window that uses frame controls, the application uses frame-control flags to specify the frame-window styles-if not, the application uses frame-style constants. An application can combine the frame-style constants with the standard window styles when creating a frame window.
When an application calls WinCreateStdWindow without setting any frame-control flags, the function creates a standard window that is invisible and behind all its sibling windows, has a width and height of 0, and is positioned at the lower-left corner of its parent window. After the call to WinCreateStdWindow returns, the application can use WinSetWindowPos to change the window's size, coordinates, z-order position, and visibility.
If an application calls WinCreateStdWindow with the FCF_SHELLPOSITION frame-control flag, the function creates the window so that it is in front of its sibling windows and has a standard size and coordinates determined by the system.
Frame-Window Resources
If an application specifies FCF_ACCELTABLE, FCF_ICON, FCF_MENU, FCF_STANDARD, FS_ACCELTABLE, FS_ICON, or FS_STANDARD when creating a frame window, the application must provide the resources to support the specified style. Failure to do so causes the window creation to fail. Depending on the style, a frame window might attempt to load one or more resources from the application's executable files.
The following table shows the frame-control flags and frame-window styles that require resources:
┌────────────────────┬────────────────────┬────────────────────┐ │Flag │Style │Description │ ├────────────────────┼────────────────────┼────────────────────┤ │FCF_ACCELTABLE │FS_ACCELTABLE │Requires an │ │ │ │accelerator-table │ │ │ │resource. The frame │ │ │ │window uses the │ │ │ │accelerator table to│ │ │ │translate WM_CHAR │ │ │ │messages to │ │ │ │WM_COMMAND, WM_HELP,│ │ │ │or WM_SYSCOMMAND │ │ │ │messages. │ ├────────────────────┼────────────────────┼────────────────────┤ │FCF_ICON │FS_ICON │Requires an icon │ │ │ │resource. The frame │ │ │ │window draws the │ │ │ │icon when the user │ │ │ │minimizes the │ │ │ │window. │ ├────────────────────┼────────────────────┼────────────────────┤ │FCF_MENU │FS_MENU │Requires a │ │ │ │menu-template │ │ │ │resource. A frame │ │ │ │window uses the menu│ │ │ │template to create a│ │ │ │menu containing the │ │ │ │commands and menus │ │ │ │specified by the │ │ │ │resource. │ ├────────────────────┼────────────────────┼────────────────────┤ │FCF_STANDARD │FS_STANDARD │Requires a │ │ │ │menu-template │ │ │ │resource │ │ │ │(FCF_STANDARD only),│ │ │ │an accelerator-table│ │ │ │resource, and an │ │ │ │icon resource. │ └────────────────────┴────────────────────┴────────────────────┘
You can use the resource compiler to add icon, menu, and accelerator-table resources to the application's executable file. Each resource must have a resource identifier that matches the resource identifier specified in the FRAMECDATA structure passed to WinCreateWindow or in the idResources parameter of WinCreateStdWindow.
- Note
- For detailed information about icon, menu, and accelerator-table resources, see Mouse Pointers and Icons, Menus, and Keyboard Accelerators, respectively.
The following sample code illustrates how to use WinCreateStdWindow to load and set up certain resources for a frame window. Normally the first step is to set up a header file defining the the IDs of the applicable resources:
#define ID_RESOURCE 301
#define IDM_OPTIONS 350
#define IDM_SHIFT 351
#define IDM_EXIT 352
Then, make a resource (.RC) file, defining each resource:
#include <os2.h>
/* Icon */
POINTER ID_RESOURCE sampres.ico
/* Accelerator table */
ACCELTABLE ID_RESOURCE
BEGIN
VK_F10, IDM_SHIFT, VIRTUALKEY
VK_F3 , IDM_EXIT, VIRTUALKEY
END
/* Menu */
MENU ID_RESOURCE
BEGIN
SUBMENU "~Options", IDM_OPTIONS
BEGIN
MENUITEM "~Shift Colors\tF10", IDM_SHIFT
MENUITEM "~Exit\tF3", IDM_EXIT
END
END
When using WinCreateStdWindow with more than one resource, each resource can have the same ID, as in the above example (ID_RESOURCE or 1), but only if each resource is of a different type. Resources of the same type must have unique IDs. Use FCF flags to indicate what resources to load:
ULONG flFrameFlags=
FCF_TITLEBAR | /* Title bar */
FCF_SIZEBORDER | /* Size border */
FCF_MINMAX | /* Min & Max buttons */
FCF_SYSMENU | /* System menu */
FCF_SHELLPOSITION | /* System size & position */
FCF_TASKLIST | /* Add name to task list */
FCF_ICON | /* Add icon */
FCF_ACCELTABLE | /* Add accelerator table */
FCF_MENU; /* Add menu */
Use 0 (or NULL) in the seventh parameter of WinCreateStdWindow to indicate that the resource is stored in the application file, as follows:
hwndFrame = WinCreateStdWindow(
HWND_DESKTOP, /* Parent is desktop window */
WS_VISIBLE, /* Make frame window visible */
&flFrameFlags, /* Frame controls */
"ResSamClient", /* Window class for client */
NULL, /* No window title */
WS_VISIBLE, /* Make client window visible */
(HMODULE) 0, /* Resources in application module */
ID_RESOURCE, /* Resource identifier */
NULL); /* Pointer to client window handle */
Following is the full listing of the sample program:
#define INCL_PM
#include <os2.h>
MRESULT EXPENTRY ClientWndProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2);
int main(int argc, char *argv, char *envp)
{
HWND hwndFrame;
HWND hwndClient;
HMQ hmq;
QMSG qmsg;
HAB hab;
ULONG flFrameFlags=
FCF_TITLEBAR | /* Title bar */
FCF_SIZEBORDER | /* Size Border */
FCF_MINMAX | /* Min & Max Buttons */
FCF_SYSMENU | /* System Menu */
FCF_SHELLPOSITION | /* System size & position */
FCF_TASKLIST | /* Add name to task list */
FCF_ICON | /* Add icon */
FCF_ACCELTABLE | /* Add accelerator table */
FCF_MENU; /* Add menu */
hab = WinInitialize(0);
hmq = WinCreateMsgQueue(hab, 0);
WinRegisterClass(
hab, /* Anchor block handle */
"ResSamClient", /* Name of class being registered */
(PFNWP)ClientWndProc, /* Window procedure for class */
CS_SIZEREDRAW | /* Class style */
CS_HITTEST, /* Class style */
0); /* Extra bytes to reserve */
hwndFrame = WinCreateStdWindow(
HWND_DESKTOP, /* Parent is desktop window */
WS_VISIBLE, /* Make frame window visible */
&flFrameFlags, /* Frame controls */
"ResSamClient", /* Window class for client */
NULL, /* No window title */
WS_VISIBLE, /* Make client window visible */
(HMODULE) 0, /* Resources in application module */
ID_RESOURCE, /* Resource identifier */
NULL); /* Pointer to client window handle */
while (WinGetMsg(hab, &qmsg, 0, 0, 0))
WinDispatchMsg(hab, &qmsg);
WinDestroyWindow(hwndFrame);
WinDestroyMsgQueue(hmq);
WinTerminate(hab);
return 0;
}
MRESULT EXPENTRY ClientWndProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2);
{
RECTL rcl;
HPS hps;
static LONG lColor=CLR_RED;
switch (msg)
{
case WM_PAINT:
hps=WinBeginPaint(hwnd,(HPS) NULL, &rcl); /* Get hps */
WinFillRect(hps,&rcl,lColor); /* Fill the window */
WinEndPaint(hps); /* Free hps */
return 0;
case WM_COMMAND:
switch (SHORT1FROMMP(mp1))
{
case IDM_SHIFT: /* Shift selected */
if (lColor==CLR_RED) /* Change the color */
lColor=CLR_BLUE;
else lColor=CLR_RED;
WinInvalidateRect(hwnd,(PRECTL)NULL,0UL); /* Paint Window */
return 0;
case IDM_EXIT: /* Exit selected */
WinPostMsg(hwnd,WM_CLOSE,MPVOID,MPVOID); /* Exit program */
return 0;
}
}
return WinDefWindowProc (hwnd, msg, mp1, mp2);
}