overview.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
About Frame Windows (1.2)
Using Section  Function Group  Message Group    Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
                            About Frame Windows
 
This topic describes creating and using frame windows in Presentation
Manager applications. You should also be familiar with the following
topics:
 
    Windows
    Control windows
    Messages and message queues
    MS OS/2 Resource Compiler
 
A frame window is the basic window used by most Presentation Manager
applications. A frame window provides a base for the application's main
window, dialog windows, and message boxes. Although applications rarely use
frame windows alone, applications nearly always start with a frame window to
create a composite window that consists of the frame window, several frame
controls, and a client window. The frame window coordinates the actions of
the other windows, allowing the composite window to act as if it were a
single unit.
 
A frame window is a window of 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. The appearance and
behavior of a frame window are designed to match the standard user-interface
guidelines for MS OS/2 Presentation Manager applications, including
applications that use the multiple-document interface. This means that
applications that use frame windows have a quick and efficient way to create
the "standard" windows recommended by the user-interface guidelines.
 
Although frame windows are an important part of dialog windows, dialog
windows are not described in this topic. For a complete description of
dialog windows, see the topic, Dialog Windows.
 
Main Window
 
An application's main window is typically made up of a frame window with
control windows such as a title bar, System menu, menu bar, and scroll bar.
The main window also typically includes a client window.
 
The frame window is sometimes under other windows. Although it is not
visible, it provides the standard services the user expects from the
window──for example, moving, sizing, minimizing, and maximizing. The frame
window receives input from the control windows (called frame controls). It
sends messages to the frame controls and to the client window to tell what
action is needed next.
 
Frame Controls
 
When an application creates a frame window, it can specify that one or more
control windows be created as child windows of the frame window. A frame
window can have a title-bar, System-menu, menu, and scroll-bar controls.
Each is a unique window created from a preregistered control-window class.
 
These frame controls provide a particular aspect of the user interface for a
"standard" application window. A title bar appears at the top of the window
and displays the application and/or window title. A System menu appears at
the left end of the title bar. It contains the commands used to move, size,
and close the window. A menu appears below the title bar and contains the
commands the user can choose to carry out work with the application. The
scroll bars appear at the right edge and bottom of the frame window. These
let the user scroll the contents of the client window.
 
Although all frame controls are optional, most, if not all, application main
windows use the title-bar and System-menu controls. These provide the
minimum functionality for a window that meets the user-interface
guidelines.
 
Each frame control is a child window of the frame window. Each frame control
is owned by the frame window. That is, the frame window is the owner as well
as the parent window for each frame control. Because the main role of a
frame window is to coordinate the activities of other windows, ownership of
the frame controls is very important. Ownership gives the frame controls a
way to send notification messages to the frame window. Notification messages
tell the frame window what the user does with the frame control.
 
For example, a user can move a window by clicking the title bar and then
dragging the window to a new position using a mouse. The title bar responds
to the click by sending a message to the frame window notifying it of the
user's request to move the window. The frame window can then track the mouse
motion and move the frame window and all its child windows to the new
position.
 
An application can add frame controls to a frame window by using the
FCF_TITLEBAR, FCF_SYSMENU, FCF_MENU, FCF_VERTSCROLL, and FCF_HORZSCROLL
styles. For a general discussion of control windows, see the topic,
Control windows.
 
Client Window
 
Every main window has a client window. The client window is the part of the
main window where the application displays output and receives mouse and
keyboard input. What an application displays in the client window, how it
displays it, and how it interprets input to the window is controlled
entirely by the application.
 
An application creates the client window when it creates the frame window.
The client window is specific to the application; it is nearly always
created by using a private window class (a class registered by the
application). Like frame controls, the client window is a child window and
an owned window of the frame window. This means, for example, that the
client window moves when the frame window moves, that the client window is
clipped to the frame-window size, and that the client window 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 from other frame controls to the client window
and vice versa. For example, a scroll-bar control notifies the frame window
when the user requests scrolling; the frame window then sends a message to
the client window. The client window requests that the frame window change
the window title; the frame window sends a message to the title-bar
control.
 
Sizing Border and Minimize and Maximize Buttons
 
Although the sizing border and minimize and maximize buttons are not frame
controls, they act very much like controls for the frame window. However,
they are different than frame controls because the frame window draws and
maintains these items; frame controls draw and maintain themselves.
 
The sizing border, enclosing the frame window, lets the user change the size
of the window by using a mouse. The minimize button, at the right end of the
title bar, lets the user shrink the frame window to an icon. The maximize
button, next to 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 the
FCF_MINMAX) styles. (The FCF_MINMAX style adds both a maximize 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 they send to the frame
window. The following are the frame-control identifiers:
 
♦  FID_CLIENT
♦  FID_HORZSCROLL
♦  FID_MENU
♦  FID_MINMAX
♦  FID_SYSMENU
♦  FID_TITLEBAR
♦  FID_VERTSCROLL
 
Frame-Window Creation
 
An application can create a frame window by using the WinCreateWindow
function and specifying the WC_FRAME window class. This creates the frame
window but does not add the frame controls and client window that accompany
most frame windows in applications. To add these additional windows, the
application can continue to call the WinCreateWindow function, specifying
the original frame window as the parent and owner window for each frame
control and for the client window. Or the application can call the
WinCreateStdWindow function which automatically carries out the individual
calls to WinCreateWindow.
 
Frame windows are also used to create dialog windows. In this case, the
frame window contains control windows but no client window. An application
can create a dialog window by using the WinLoadDlg or WinCreateDlg function.
These functions require an appropriate dialog template from the
application's resources on disk or from memory. The dialog template
specifies the styles and dimensions for the frame window and the control
windows that make up the dialog window.
 
Frame-Control Flags
 
An application can specify both the frame-window style and the frame
controls for a frame window by using the frame-control flags with the
WinCreateStdWindow function. The following are the frame-control flags:
 
Flag                 Description
────────────────────────────────────────────────────────────────────────────
FCF_TITLEBAR         Creates a title bar.
 
FCF_SYSMENU          Creates a System menu.
 
FCF_MENU             Creates a menu. This flag loads a menu from the
                     application's resources on disk.
 
FCF_MINBUTTON        Creates a minimize button.
 
FCF_MAXBUTTON        Creates a maximize button.
 
FCF_MINMAX           Creates both a minimize and a maximize button.
 
FCF_VERTSCROLL       Creates a vertical scroll bar.
 
FCF_HORZSCROLL       Creates a horizontal scroll bar.
 
FCF_SIZEBORDER       Creates a sizing border. A sizing border lets the user
                     adjust the size of the window.
 
FCF_BORDER           Creates a border. Use this flag for windows that must
                     not change size.
 
FCF_DLGBORDER        Creates a dialog border. Use this flag for dialog
                     windows.
 
FCF_SHELLPOSITION    Directs the frame window to request an initial size and
                     position from Start Programs.
 
FCF_TASKLIST         Adds the window title to the switch list of Task
                     Manager. If the process creating a frame window already
                     has an entry in the switch list, the window title is
                     appended to the previous entry.
 
FCF_NOBYTEALIGN      Enables the frame window to be moved to any position on
                     the screen. If this flag is not given, a frame window
                     always adjusts its position so that the x-coordinate of
                     its left edge is a multiple of 8. Using this flag
                     affects how quickly the system can draw the frame
                     window.
 
FCF_NOMOVEWITHOWNER  Enables the frame window to maintain its position even
                     if its owner window moves. This applies only to frame
                     windows that are not child windows of the owner. If
                     this flag is not given, the frame window moves when the
                     owner window moves.
 
FCF_ICON             Loads an icon from the application's resources on disk.
                     The icon is used whenever the frame window is
                     minimized.
 
FCF_ACCELTABLE       Loads an accelerator table from the application's
                     resources on disk. The accelerator table is used for
                     all keyboard input to the frame window.
 
FCF_SYSMODAL         Creates a system-modal frame window. Setting this flag
                     is the same as using the WinSetSysModalWindow
                     function.
 
FCF_SCREENALIGN      Aligns the initial position of the frame window
                     relative to the screen origin instead of to the parent
                     window.
 
FCF_MOUSEALIGN       Aligns the initial position of the frame window
                     relative to the mouse position instead of to the parent
                     window. An application can use this flag to position
                     the default button in a dialog window under the mouse
                     pointer.
 
FCF_STANDARD         Combines the FCF_TITLEBAR, FCF_SYSMENU, FCF_MENU,
                     FCF_SIZEBORDER, FCF_MINMAX, FCF_ICON, FCF_ACCELTABLE,
                     FCF_SHELLPOSITION, and FCF_TASKLIST styles.
 
When the WinCreateStdWindow function is called without any of these flags
set, the standard window is created invisible, behind all its sibling
windows, in Z order, with a width and height of zero, positioned at the
lower-left of its parent window. When WinCreateStdWindow returns, you can
call WinSetWindowPos to change the window's size, x- and y-positions,
Z-order position, and visibility.
 
When WinCreateStdWindow is called with the FCF_SHELLPOSITION frame-control
flag, the window is created in front of its sibling windows, in Z order,
with a standard size and x- and y-positions obtained from the shell
program.
 
Frame-Window Styles
 
The frame-window class, like other preregistered window classes, provides
many class-specific window styles that applications can use to adapt the
appearance and behavior of a frame window. The frame-window styles,
specified as constants starting with the FS_ prefix, can be combined with
the standard window styles when creating a frame window. For a list of
frame-window styles, see the topic Frame styles.
 
Frame-Window Resources
 
If the FCF_MENU, FCF_ICON, FCF_ACCELTABLE, FCF_STANDARD, FS_ICON,
FS_ACCELTABLE, or FS_STANDARD style is specified when creating the frame
window, the application must provide the appropriate resources to support
these styles. Depending on the style, a frame window may attempt to load one
or more resources from the application's resources on disk.
 
You can use Resource Compiler to add icon 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 the WinCreateWindow function or in the idResources
parameter of the WinCreateStdWindow function.
 
The following list gives the frame-control flags and styles that require
resources and describes what the resource should be:
 
Style                            Resource
────────────────────────────────────────────────────────────────────────────
FCF_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_ICON or FS_ICON              Requires an icon resource. The frame window
                                 draws the icon whenever the window is
                                 minimized.
 
FCF_ACCELTABLE or FS_ACCELTABLE  Requires an accelerator-table resource. The
                                 frame window uses the accelerator table to
                                 translate WM_CHAR messages to WM_COMMAND,
                                 WM_SYSCOMMAND, or WM_HELP messages.
 
FCF_STANDARD or FS_STANDARD      Requires a menu template, an accelerator
                                 table, and an icon resource.
 
The application must specify the module containing the resources (typically
the application's executable file) when it creates the frame window. The
resources must have the same resource identifier and the application must
supply this identifier when creating the window.
 
Frame-Window Class Data
 
An application can specify class-specific data for a frame window by passing
a FRAMECDATA structure to the WinCreateWindow function. The class-specific
data contains the frame-control flags, resource-module handle, and resource
identifier to be used when creating the frame window.
 
Frame-control flags specify what controls to create for the frame window and
what window styles to apply to the frame window. The frame-control flags are
the same flags (FCF_) used in the WinCreateStdWindow function. The
resource-module handle and the resource identifier specify where to find
resources for the frame window.
 
Supplying class-specific data with WinCreateWindow is similar to using the
WinCreateStdWindow function without creating a client window.
 
Frame-Window Data
 
Frame-window data specifies the state of the frame window at a given time.
An application can retrieve the frame-window data by calling the
WinQueryWindowUShort function. A frame window has the following state
flags:
 
Flag                Description
────────────────────────────────────────────────────────────────────────────
FF_ACTIVE           The frame window is activated.
 
FF_DLGDISMISSED     A frame window that is a dialog window has been
                    dismissed by a call to the WinDismissDlg function.
 
FF_FLASHHILITE      The frame window is flashing and its flash state is
                    TRUE.
 
FF_FLASHWINDOW      The frame window flashes as the result of a call to the
                    WinFlashWindow function or a WM_FLASHWINDOW message.
 
FF_NOACTIVATESWP    The system should do no Z ordering on this frame
                    window.
 
FF_OWNERHIDDEN      The frame window's owner window is hidden or minimized
                    so the frame window is also hidden.
 
FF_OWNERDISABLED    For a frame window that is a dialog window, this flag
                    indicates whether the owner window was enabled or
                    disabled when the dialog window was loaded.
 
FF_SELECTED         The frame window has selection turned on.
 
FI_FRAME            The window is a frame window.
 
FI_OWNERHIDE        The frame window should be hidden or shown as a result
                    of its owner window being hidden, shown, minimized, or
                    maximized.
 
FI_ACTIVATEOK       The window can be activated.
 
FI_NOMOVEWITHOWNER  The window should move when its owner window moves.
 
Frame-Window Operation
 
The frame window maintains the size, position, and visibility of itself, its
frame controls, and its client window. It responds to user requests to move,
size, minimize, maximize, and redraw the window. It also responds to
requests to close (destroy) the window and to change the focus and
activation.
 
When moving or sizing a frame window, all owned windows maintain their
position relative to the owner window's upper-left corner.
 
Whenever the frame window redraws itself (for example, after moving or
sizing), it draws the frame controls first, then lets the application draw
the client window. This order ensures that the rapidly drawn frame controls
are drawn before the relatively slowly drawn client window.
 
The order in which the frame controls are drawn depends on the Z-order
position of the controls. Because the frame controls are sibling windows,
the Z-order position of one is relative to the others. The following list
specifies the Z-order position of the frame controls (from top to bottom):
 
     FID_SYSMENU
     FID_TITLEBAR
     FID_MENU
     FID_VERTSCROLL
     FID_HORZSCROLL
     FID_CLIENT
 
Although an application can change the Z-order position of any window,
changing the relative positions of frame controls is not recommended.
 
When a frame window receives a request to minimize the window, it locates an
available icon space in the lower part of the screen, hides all frame
controls and the client window, and draws its icon. If the frame window has
no icon (that is, the window was created without the FCF_ICON style), the
frame window hides all but the client window. The client window must then
draw the minimized window. An application can determine the size of a
minimized frame window by calling the WinQueryWindowUShort function and
specifying the QWS_XMINIMIZE and QWS_YMINIMIZE indexes.
 
When a frame window is maximized, it grows to the size of its parent window,
plus an additional amount on each of its four sides equal to the width of
its sizing border. Because a window is always clipped to its parent window,
a maximized standard frame window does not show its sizing border.
 
Frame controls owned by a frame window or windows owned by child windows of
a frame window are automatically destroyed when the frame window processes
the WM_DESTROY message.
 
Nonstandard Frame Windows
 
Although most applications use frame windows to create main window and
dialog windows, they are not limited to frame windows. Applications can
create nonstandard frame windows and still use the standard frame controls,
such as the title bar and System menu, within the nonstandard windows. One
reason for creating nonstandard frame windows is to expand the capability of
the frame window to support special features such as the multiple-document
interface.
 
There are two ways to create nonstandard frame windows: subclass a frame
window or create a private frame-window class. An application that
subclasses a frame window can intercept the messages sent to the window and
process them in new ways. An application that creates private frame-window
classes essentially rewrites the frame-window procedure. In either case, the
application gains much more control over the placement of frame controls in
the frame window by creating nonstandard frame windows.
 
The WM_FORMATFRAME, WM_UPDATEFRAME, and WM_CALCVALIDRECTS messages control
the arrangement of frame controls for applications that subclass. By
intercepting these messages, an application can rearrange the placement of
frame controls in a frame window.
 
For applications that create private frame-window classes, the
WinCreateFrameControls, WinCalcFrameRect, and WinFormatFrame functions
provide much the same capability as frame windows to maintain the size and
position of frame controls.
 
Default Frame-Window Behavior
 
This section describes all the messages specifically handled by the
predefined frame-window class.
 
Message             Description
────────────────────────────────────────────────────────────────────────────
WM_ACTIVATE         Sent to a title bar or sizing border so its highlight
                    state matches the frame window's activation state.
 
WM_BUTTON1DOWN      If the frame window is minimized, captures the mouse. If
                    the window is not minimized, activates the window.
 
WM_BUTTON2DOWN      Activates the frame window.
 
WM_BUTTON3DOWN      Activates the frame window.
 
WM_BUTTON1UP        Processes messages from minimized window frames.
 
WM_BUTTON2UP        Not processed.
 
WM_BUTTON3UP        Not processed.
 
WM_BUTTON1DBLCLIK   If the frame window is minimized, posts a WM_SYSCOMMAND
                    message to itself. Otherwise, activates the frame window
                    and any control clicked.
 
WM_BUTTON2DBLCLIK   Not processed.
 
WM_BUTTON3DBLCLIK   Not processed.
 
WM_HITTEST          If the frame control is minimized this message returns
                    HT_ERROR if disabled; otherwise, it returns TF_MOVE.
 
WM_CALCVALIDRECTS   If there is no client window or the client window has
                    CS_SIZEREDRAW style, this message returns CVR_REDRAW to
                    invalidate the entire window.
 
WM_CLOSE            If there is a client window, this message passes to it;
                    otherwise, returns WinDefWindowProc.
 
WM_CONTROLHEAP      Attempts to allocate a heap for the frame controls.
                    Returns a handle if successful or NULL if not.
 
WM_CREATE           Creates specified frame controls by calling
                    WinCreateFrameControls. Also creates any accelerator
                    tables, loads icons, and adds itself to the switch list
                    in Task Manager. These actions depend on the frame
                    window and frame-control styles specified for the
                    window.
 
WM_DESTROY          If the focus is held by a child window of the frame
                    window, sets the focus to the frame window's parent.
                    Destroys any windows owned by the frame window. Destroys
                    any child windows. Frees any control heaps. Destroy any
                    icon created using the FS_ICON style. Destroy any
                    accelerator table created using the FS_ACCELTABLE
                    style.
 
WM_ENABLE           Returns WinDefWindowProc.
 
WM_ERASEBACKGROUND  Sent by the frame window to itself during WM_PAINT
                    processing. Returns TRUE, signaling that the window
                    should erase the client-window area.
 
WM_FORMATFRAME      Calls WinFormatFrame and WinSetMultWindowPos to format
                    and position the frame controls.
 
WM_MINMAXFRAME      If there is a client window, passes message to it;
                    otherwise, passes a message via the WinDefWindowProc
                    function.
 
WM_MOUSEMOVE        Determines the correct mouse pointer to use and returns
                    WinDefWindowProc.
 
WM_PAINT            If the frame window is minimized, sends WM_QUERYICON and
                    WM_ERASEBACKGROUND to itself and draws the icon.
                    Otherwise, paints all its controls, sends a
                    WM_ERASEBACKGROUND to the client, and paints the client
                    window.
 
WM_QUERYTRACKINFO   Obtains the default tracking information.
 
WM_SHOW             Returns WinDefWindowProc.
 
WM_SIZE             Sends a WM_FORMATFRAME message to itself.
 
WM_SYSCOMMAND       If the mouse is captured, ignores the system command.
                    Otherwise, uses one of the following commands:
                    SC_RESTORE, SC_SIZE, SC_MOVE, SC_CLOSE, SC_TASKMANAGER,
                    SC_NEXT, SC_NEXTFRAME, SC_SYSMENU, SC_APPMENU.
 
WM_UPDATEFRAME      Calls WinFormatFrame to format the frame controls.
 
 
                                      ♦