IFrameWindow

The IFrameWindow class creates and manages frame windows. Typically, these windows are children of the desktop and the parent or owner windows of the Open Class Library dialogs and controls. The primary distinction between an IFrameWindow and a generic IWindow is that frames are conceptually comprised of a number of child windows.

The frame's client window is the control corresponding to the rectangular portion of the frame window not occupied by frame extensions and accessory windows that can be added through frame styles (such as the title bar, system menu, and borders). You do not give the client area an initial size because the client area is automatically sized to fill the frame window.

Use a client window if you intend to draw the client area yourself using the Open Class Library graphics classes, system graphics primitives, or another other drawing package. By doing so, you can avoid concern with operating system dependent behavior of the underlying frame window in your drawing code.

In addition to the standard frame controls, IFrameWindow supports additional frame extensions. These extensions are primarily application-specific, although IInfoArea provides a general-purpose information area extension.

You can add extensions to the frame window by providing an IWindow and then specifying the portion of the frame that the IWindow will occupy. The extension can fill a portion of the standard title-bar area or the standard client area.

An IFrameWindow object supports owning child IFrameWindow objects. There are several portable behaviors of an owned IFrameWindow object including:

AIX Considerations

AIX does not support windows constructed from dialog templates. Resource support does not include dialog template support.

Frames include some or all of the following:

If you set the titleBar style, the window has a title. If you specify a title, your title is used. If you do not specify a title, the title defaults to the application name.

Frame extensions are only supported in the client area.

The IFrameWindow constructors create an object of this class using several Motif widgets. A TopLevelShell widget provides the frame decorations and window manager communications. An XmMainWindow and an XiclCanvas widget provides the menu bar support and client area.

OS/2 Considerations

Frame windows include some or all of the following:

You can construct frame windows from dialog templates loaded from resource libraries. You can then use showModally to display these frame windows as dialogs. In addition, you can use showModally to show frame windows not constructed from dialog templates as application modal.

Windows Considerations

You can construct frame windows from dialog templates loaded from resource libraries. Use WC_DIALOG as the style of the dialog. You can then use showModally to display these frame windows as dialogs.

In addition, you can use showModally to show frame windows not constructed from dialog templates as application modal.


IFrameWindow - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IFrameWindow objects because both the copy constructor and assignment operator are private functions.

Three constructors use the given window or resource ID to attempt to create the frame from a dialog template These constructors have the optional parameter source. See IFrameWindow::FrameSource for details on this parameter.

The constructors without the source do not attempt to load a dialog from a dialog resource. Instead, the frame attributes are specified as additional constructor arguments.


[view class]
~IFrameWindow
public:
virtual ~IFrameWindow()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IFrameWindow


Overload 1
public:
IFrameWindow( const IResourceId& resId, IWindow* parent, IWindow* owner, const IRectangle& initRect, const IFrameWindow::Style& style = defaultStyle ( ), const char* title = 0 )

Construct an IFrameWindow object from a full set of frame attributes: a resource ID, parent, owner, initial rectangle (position and size), and, optionally, a style and title.

Use this constructor when you want to supply the values instead of using the default values, such as initializing the size and title. This constructor gives you full control over the attributes of nondialog frame windows. If you do not specify style, the constructor calls IFrameWindow::defaultStyle to return the default style.

The default for title is 0. If you set the style IFrameWindow::titleBar, the frame has a title. If you supply a nonzero parameter, the title is the specified string. Otherwise, the constructor attempts to load a string from the resource library with the frame window's ID. If the attempt fails, the constructor uses a default title, typically the name of the executable file.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IFrameWindow( const char* title, const IResourceId& resId = IC_DEFAULT_FRAME_ID, const IFrameWindow::Style& style = defaultStyle ( ) )

Construct an IFrameWindow from a title, and optionally, a resource ID and frame style.

Use this constructor to customize the title for a frame window without specifying a resource ID or frame style. If you do not specify resId, the constructor uses the default resource ID IC_DEFAULT_FRAME_ID that is defined in <ICCONST.H>. If you do not specify style, the constructor calls IFrameWindow::defaultStyle to return the default style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IFrameWindow( const IResourceId& resId, const IFrameWindow::Style& style )

Construct an IFrameWindow object from a specified resource ID and library, and frame window style.

Use this constructor if your frame window is not a dialog and requires frame resources, such as a menu bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IFrameWindow( unsigned long id = IC_DEFAULT_FRAME_ID, FrameSource source = tryDialogResource )

Constructs a primary frame window with the specified window identifier.

If source is IFrameWindow::dialogResource, this constructor attempts to load a dialog resource identified by id. If the dialog cannot be loaded, an exception is thrown.

If source is IFrameWindow::noDialogResource, this constructor creates a new frame window with the style returned by IFrameWindow::defaultStyle. The resource library identified by id is used to load the menu bar, accelerator table, title bar text, and icon for the frame if IFrameWindow::defaultStyle returns these styles.

If source is IFrameWindow::tryDialogResource, this constructor attempts to load a dialog resource identified by id. If the dialog resource cannot be found, a new frame window is created with the style returned by IFrameWindow::defaultStyle. The resource library identified by id is used to load the menu bar, accelerator table, and icon for the frame if IFrameWindow::defaultStyle returns these styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, this constructor always operates as if you specified noDialogSource for source.


Overload 5
public:
IFrameWindow( const IResourceId& resId, IWindow* owner = 0, FrameSource source = tryDialogResource )

Constructs a primary or secondary frame window from a specified resource ID and, optionally, an owner window pointer.

You must specify a resource ID. The owner window pointer defaults to 0. To construct a secondary window, you must specify a nonzero owner.

If source is IFrameWindow::dialogResource, this constructor attempts to load a dialog resource identified by resId. If the dialog cannot be loaded, an exception is thrown.

If source is IFrameWindow::noDialogResource, this constructor creates a new frame window with the style returned by IFrameWindow::defaultStyle. The resource library identified by resId is used to load the menu bar, accelerator table, and icon for the frame if IFrameWindow::defaultStyle returns these styles.

If source is IFrameWindow::tryDialogResource, this constructor attempts to load a dialog resource identified by resId. If the dialog resource cannot be found, a new frame window is created with the style returned by IFrameWindow::defaultStyle. The resource library identified by resId is used to load the menu bar, accelerator table, title bar text, and icon for the frame if IFrameWindow::defaultStyle returns these styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, this constructor always operates as if you specified noDialogSource for source.


Overload 6
public:
IFrameWindow( const IResourceId& resId, IWindow* parent, IWindow* owner, FrameSource source = tryDialogResource )

Constructs a child window from a specified resource ID, parent window, and owner window.

If source is IFrameWindow::dialogResource, this constructor attempts to load a dialog resource identified by resId. If the dialog cannot be loaded, an exception is thrown.

If source is IFrameWindow::noDialogResource, this constructor creates a new frame window with the style returned by IFrameWindow::defaultStyle. The resource library identified by resId is used to load the menu bar, accelerator table, title bar text, and icon for the frame if IFrameWindow::defaultStyle returns these styles.

If source is IFrameWindow::tryDialogResource, this constructor attempts to load a dialog resource identified by resId. If the dialog resource cannot be found, a new frame window is created with the style returned by IFrameWindow::defaultStyle. The resource library identified by resId is used to load the menu bar, accelerator table, and icon for the frame if IFrameWindow::defaultStyle returns these styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, this constructor always operates as if you specified noDialogSource for source.


Overload 7
public:
IFrameWindow( const IFrameWindow::Style& style, const IResourceId& resId = IC_DEFAULT_FRAME_ID )

Construct an IFrameWindow object from a frame style and, optionally, a resource ID.

Use this constructor to customize the style of a frame window without having to specify a resource ID. If you do not specify resID, the constructor uses the default resource ID IC_DEFAULT_FRAME_ID that is defined in <ICCONST.H>.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
public:
IFrameWindow(const IWindowHandle& hwnd)

Construct an IFrameWindow object from the window handle of an existing frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

AIX does not support this constructor.

OS/2 Considerations

This constructor permits you to migrate from existing OS/2 Presentation Manager code that creates the frame window directly. This constructor wraps an existing Presentation Manager frame window (created outside the Open Class Library) with an IFrameWindow C++ object.


Application Icon

Use these members to manage the application icon used in the frame's system menu and displayed when the frame is minimized.


[view class]
icon
public:
virtual IPointerHandle icon() const

Returns the pointer handle of the window icon.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setIcon

Use these functions to indicate the icon to use as the application icon.


Overload 1
public:
virtual IFrameWindow& setIcon(const IResourceId& iconResId)

Set the icon by specifying an IResourceId. If you want to load the icon from a specific resource library, use this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The Motif Window Manager expects the application icon's size to be 50 pixels by 50 pixels. If you supply an icon with a size other than 50x50 to setIcon, the library scales the icon to 50x50. Because scaling can cause a significant loss of resolution, keep the icon size as close to 50x50 as possible.


Overload 2
public:
virtual IFrameWindow& setIcon(const IPointerHandle& icon)

Set the application icon using an existing icon handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The Motif Window Manager expects the application icon's size to be 50 pixels by 50 pixels. If you supply an icon with a size other than 50x50 to setIcon, the library scales the icon to 50x50. Because scaling can cause a significant loss of resolution, keep the icon size as close to 50x50 as possible.


Overload 3
public:
virtual IFrameWindow& setIcon(unsigned long iconResId)

Set the application icon using an icon from the default resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The Motif Window Manager expects the application icon's size to be 50 pixels by 50 pixels. If you supply an icon with a size other than 50x50 to setIcon, the library scales the icon to 50x50. Because scaling can cause a significant loss of resolution, keep the icon size as close to 50x50 as possible.


Attributes

Use these member functions to set and query attributes of the IFrameWindow.


[view class]
handleForChildCreation
public:
virtual IWindowHandle handleForChildCreation() const

This member function returns the handle that should be used when creating children of the IFrameWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Bidirectional Language Support

These members allow a window to support bidirectional languages, such as Arabic and Hebrew. These languages are written and read right-to-left, but text in these languages may also contain strings that are written and read left-to-right.


[view class]
setBidiSettings
protected:
virtual IFrameWindow& setBidiSettings( const IBidiSettings& bidiSettings, bool childInherit, bool refresh )

This function allows a frame window to provide special processing to support a change in its bidirectional characteristics. This function is called just before the bidirectional characteristics of the window change. This function is not called when you create a window.

This function allows a frame window to update the positions of its frame extensions and update the bidirectional characteristics of a floating tool bar.

bidiSettings
The new bidirectional settings for the window.
childInherit
This flag specifies if the child windows of the window will inherit the new bidirectional attributes.
refresh
This flag specifies if the window will paint after receiving the new directional attributes.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not provided because you cannot change the bidirectional attributes of a window on that platform after you create it.


Border Size

Use these members to set and query the width and height of the frame window's border.


[view class]
borderHeight
public:
unsigned long borderHeight() const

Returns the height of the frame window's top and bottom borders.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
borderSize
public:
ISize borderSize() const

Returns the width of the frame window's left and right borders and the height of the frame window's top and bottom borders.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

In AIX, this function always returns ISize(1,1).


[view class]
borderWidth
public:
unsigned long borderWidth() const

Returns the width of the frame window's left and right borders.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
setBorderHeight
public:
IFrameWindow& setBorderHeight(unsigned long cy)

Sets the height of the frame window's top and bottom borders.

Exception

IInvalidParameter The system could not set the frame window's border height. The IFrameWindow::sizingBorder style is required for a frame to be able to change its border size.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setBorderSize

Sets the width of the frame window's left and right borders and the height of the frame window's top and bottom borders.


Overload 1
public:
IFrameWindow& setBorderSize( unsigned long cx, unsigned long cy )

Use this function to set the width and height of the borders.

cx
The width of the left and right borders.
cy
The height of the top and bottom borders.

Exception

IInvalidParameter The system could not set the frame window's border size. The IFrameWindow::sizingBorder style is required for a frame to be able to change its border size.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Overload 2
public:
IFrameWindow& setBorderSize(unsigned long cxcy)

Use this function to set the borders of the frame to a uniform size.

cxcy
The uniform size of all borders.

Exception

IInvalidParameter The system could not set the frame window's border size. The IFrameWindow::sizingBorder style is required for a frame to be able to change its border size.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Overload 3
public:
IFrameWindow& setBorderSize(const ISize& size)

Use this function to use an ISize object to set the size of the borders.

size
The width of the left and right borders and the height of the top and bottom borders.

Exception

IInvalidParameter The system could not set the frame window's border size. The IFrameWindow::sizingBorder style is required for a frame to be able to change its border size.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setBorderWidth
public:
IFrameWindow& setBorderWidth(unsigned long cx)

Sets the width of the frame window's left and right borders.

Exception

IInvalidParameter The system could not set the frame window's border width. The IFrameWindow::sizingBorder style is required for a frame to be able to change its border size.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Client Window

Use these members to manipulate the frame client window. The frame client is similar to the other frame controls, but this control receives notification of certain events not handled by the frame itself. For example, it receives notification for most ICommandEvents that originate from the frame menu bar.


[view class]
client
public:
virtual IWindow* client() const

Returns a pointer to the IWindow corresponding to the client window. If no client window exists, or it is not represented by an IWindow object, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
clientHandle
public:
virtual IWindowHandle clientHandle() const

Returns the IWindowHandle of the client window. If no client window exists, a 0 handle is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setClient
public:
virtual IFrameWindow& setClient(IWindow* newClient)

Sets the IWindow used as the frame window's client area.

Exception

IInvalidParameter The specified window is null. Specify a valid window for the client window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

Changes the ID of client IWindow to IC_FRAME_CLIENT_ID.

Windows Considerations

Changes the ID of client IWindow to IC_FRAME_CLIENT_ID.


Color

Use these members to set and query the background color of the frame window.


[view class]
backgroundColor
public:
virtual IColor backgroundColor() const

Returns the color of the frame window background or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default color of the frame window background.


[view class]
disabledBackgroundColor
public:
virtual IColor disabledBackgroundColor() const

Returns the color of the frame window background when the window is disabled, or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default color of the frame window background when the window is disabled.


[view class]
resetBackgroundColor
public:
virtual IFrameWindow& resetBackgroundColor()

Resets the background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetDisabledBackgroundColor
public:
virtual IFrameWindow& resetDisabledBackgroundColor()

Resets the disabled background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
usesDialogBackground
public:
bool usesDialogBackground() const

Returns whether the frame window uses the system dialog background color rather than the system window background color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


DBCS Support

DBCS support members share DBCS information between a parent and child frame.


[view class]
shareParentDBCSStatus
public:
virtual IFrameWindow& shareParentDBCSStatus()

Causes a child frame to share the DBCS status control of its parent. If either the child or parent do not have the style IFrameWindow::appDBCSStatus set, this function has no effect.

Supported Platforms

Windows OS/2 AIX
No Yes Ignored


Event-Handling Implementation

Event-handling implementation members perform processing that allows handlers to receive GUI events and to route these events.


[view class]
passEventToOwner
protected:
virtual bool passEventToOwner(IEvent& event)

Controls the propagation of events up the owner chain. The override for IFrameWindow stops mouse events from propagating to the owner of the IFrameWindow object.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Fonts

Use these members to modify the current font.


[view class]
setFont
public:
virtual IWindow& setFont(const IFont& font)

Sets a new font to be used by the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Frame Extensions

Use these members to add extensions to the standard frame window. Such extensions are simply additional windows placed in specific locations. The information area implemented by the IInfoArea class is an example of such an extension.


[view class]
addExtension

Adds a window as a frame extension.


Overload 1
public:
virtual IFrameWindow& addExtension( IWindow* newExtension, Location location, SeparatorType separator = thinLine )

Use this function when you want the frame extension to use the minimum size of the associated control.

newExtension
The frame extension window.
location
The relative location (left, right, top, or bottom) and frame window area (title bar area, menu bar area, or client area) to be occupied by the frame extension. Use the enumeration Location to specify the location for the frame extension.
separator
The separator type. Use the enumeration SeparatorType to specify the type of separator delimiting the frame extension.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IFrameWindow& addExtension( IWindow* newExtension, Location location, unsigned long widthOrHeight, SeparatorType separator = thinLine )

Use this function when you want the frame extension to be a fixed width or height.

newExtension
The frame extension window.
location
The relative location (left, right, top, or bottom) and frame window area (title bar area, menu bar area, or client area) to be occupied by the frame extension. Use the enumeration Location to specify the location for the frame extension.
widthOrHeight
The portion of the frame window area allocated to the frame extension, in a fixed width or height.
separator
The separator type. Use the enumeration SeparatorType to specify the type of separator delimiting the frame extension.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IFrameWindow& addExtension( IWindow* newExtension, Location location, double percentage, SeparatorType separator = thinLine )

Use this function to add a relative type of frame extension.

newExtension
The frame extension window.
location
The relative location (left, right, top, or bottom) and frame window area (title bar area, menu bar area, or client area) to be occupied by the frame extension. Use the enumeration Location to specify the location for the frame extension.
percentage
The portion of the frame window area allocated to the frame extension, in a floating point percentage (0 < x < 1.0).
separator
The separator type. Use the enumeration SeparatorType to specify the type of separator delimiting the frame extension.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IFrameWindow& addExtension( IWindow* newExtension, Location location, int widthOrHeight, SeparatorType separator = thinLine )

Use this function when you want the frame extension to be a fixed width or height.

newExtension
The frame extension window.
location
The relative location (left, right, top, or bottom) and frame window area (title bar area, menu bar area, or client area) to be occupied by the frame extension. Use the enumeration Location to specify the location for the frame extension.
widthOrHeight
The portion of the frame window area allocated to the frame extension, in a fixed width or height.
separator
The separator type. Use the enumeration SeparatorType to specify the type of separator delimiting the frame extension.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isAnExtension
public:
virtual bool isAnExtension(const IWindow* window) const

Returns true if the specified IWindow object is a frame extension.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeExtension
public:
virtual IFrameWindow& removeExtension( IWindow* extension, bool updateDisplay = true )

Removes a frame extension (window).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setExtensionSize

Sets a frame extension to the specified size.


Overload 1
public:
virtual IFrameWindow& setExtensionSize( IWindow* extension, int widthOrHeight )

Use this function to set the size of a fixed-type extension.

extension
The frame extension window.
widthOrHeight
The portion of the frame window area (title bar area, menu bar area, or client area) allocated to the frame extension, in a fixed width or height (int).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IFrameWindow& setExtensionSize( IWindow* extension, double widthOrHeight )

Use this function to set the size of a fixed-type extension.

extension
The frame extension window.
widthOrHeight
The portion of the frame window area (title bar area, menu bar area, or client area) allocated to the frame extension, in a floating point percentage (double, 0 < x < 1.0).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IFrameWindow& setExtensionSize( IWindow* extension, unsigned long widthOrHeight )

Use this function to set the size of a fixed-type extension.

extension
The frame extension window.
widthOrHeight
The portion of the frame window area (title bar area, menu bar area, or client area) allocated to the frame extension, in a fixed width or height (unsigned long).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
update
public:
virtual IFrameWindow& update(bool forceUpdate = false)

Reconfigures all of the controls and extensions for the frame window. The functions IFrameWindow::addExtension and IFrameWindow::setClient automatically call this function.

The code is optimized with an internal flag so that an update will only occur when it is needed. To override this behavior call update with the forceUpdate parameter set to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
useExtensionMinimumSize
public:
virtual IFrameWindow& useExtensionMinimumSize( IWindow* extension )

Sizes the width or height of the frame extension based on the minimum size of the window it contains.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Frame Extensions Management

These protected members maintain information about the frame window's collection of frame extensions. You can query the location of a specific frame extension within the frame extension collection.


[view class]
extensions
protected:
IFrameExtensions* extensions() const

Returns a pointer to the IFrameExtensions collection for the frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
findExtension
protected:
unsigned findExtension(IWindow* window)

Returns the index of the frame extension corresponding to the specified control IWindow. The index locates the IFrameExtension in the IFrameExtensions collection of the frame window.

Exception

IInvalidParameter The specified control did not match any currently defined frame extension's control. The specified control has not been defined as an frame extension.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setExtensions
protected:
IFrameWindow& setExtensions(IFrameExtensions* extensions)

Sets a pointer to the IFrameExtensions collection for the frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These members create the frame window. The loading of a dialog window, creating a frame window, and adding default handlers are handled by members in this group. A derived class can override these functions to customize frame-window processing. For example, a derived class can use the IFrameWindow::deferCreation style to indicate that it will create the frame window.


[view class]
setColorMap
public:
virtual IFrameWindow& setColorMap(IColorMap* colorMap)

Establishes the color map used by the frame window and the children of the frame window.

This function is currently for library use only.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addDefaultHandler
protected:
IFrameWindow& addDefaultHandler()

Adds the default frame handler to a newly created frame.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
create

Creates a frame window by calling the inherited IWindow::create. One of the first functions that is called is to initialize the GUI by calling ICurrentThread::initializeGUI. This function will then check the styles that were used to construct the IFrameWindow object to control the characteristics of the frame window. The accelerator style is checked and if set then the accelerator table for the frame window is loaded from a resource file. The title of the frame is also set if specified during construction of the IFrameWindow object.


Overload 1
protected:
IWindowHandle create( unsigned long id, const char* title, const IBitFlag& style, const char* windowClass, const IWindow* parent, const IWindow* owner, const IRectangle& initRect, const void* ctlData, const void* presParams, IWindow::SiblingOrder ordering = defaultOrdering ( ) )

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
protected:
IWindowHandle create( unsigned long id, const char* title, unsigned long style, IXmCreateFunction createFunction, const IWindowHandle& parent, const IWindowHandle& owner, const IRectangle& initRect, const void* callerArgList, unsigned int callerNumberArguments, IWindow::SiblingOrder ordering = defaultOrdering ( ), unsigned long extendedStyle = 0 )

Supported Platforms

Windows OS/2 AIX
No No Yes


Overload 3
protected:
IWindowHandle create( unsigned long id, const char* title, const IBitFlag& style, IXmCreateFunction createFunction, const IWindow* parent, const IWindow* owner, const IRectangle& initRect, IWindow::SiblingOrder ordering = defaultOrdering ( ) )

Supported Platforms

Windows OS/2 AIX
No No Yes


Overload 4
protected:
IWindowHandle create( unsigned long id, const char* title, unsigned long style, const char* windowClass, const IWindowHandle& parent, const IWindowHandle& owner, const IRectangle& initRect, const void* ctlData, const void* presParams, IWindow::SiblingOrder ordering = defaultOrdering ( ), unsigned long extendedStyle = 0 )

This function creates the frame window.

id
The frame window's resource ID.
title
The frame window's title.
style
The default style specification for the frame window. Use the styles provided by IFrameWindow::Styles and IWindow::Styles to specify the default style.
windowClass
The window class of the frame window.
parent
The parent of the frame window.
owner
The owner of the frame window.
initRect
The initial frame window rectangle, defined by IFrameWindow::nextShellRect.
ctlData
Control data for the window.
presParams
Presentation parameters for the window.
ordering
Sibling window order. Use the enumeration IWindow::SiblingOrder to specify the order of sibling window creation.
extendedStyle
The extended style for the frame window (Windows only).

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
initialize
protected:
IFrameWindow& initialize( const IResourceId& resId, const Style& style, IWindow* parent = 0, IWindow* owner = 0, const IRectangle& initRect = nextShellRect ( ), const char* title = 0 )

Initializes the object by creating a standard frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
registerFrameClass
protected:
unsigned long registerFrameClass( const Style& style, const IResourceId& resId )

Registers the window class for the frame.

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
removeDefaultHandler
protected:
IFrameWindow& removeDefaultHandler()

Removes the default frame handler from the frame window. If the default handler is attached to the frame window, the destructor automatically calls this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
start
protected:
IFrameWindow& start(const IWindowHandle& hwnd)

Calls IWindow::startHandlingEventsFor for the IFrameWindow object. It also creates the default frame handlers and addsthem to the IFrameWindow object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tryToLoadDialog
protected:
IFrameWindow& tryToLoadDialog( const IResourceId& resId, IWindow* parent = 0, IWindow* owner = 0, FrameSource source = tryDialogResource )

Attempts to load a dialog window from a dialog template resource if source is IFrameWindow::dialogResource. If source is IFrameWindow::noDialogResource, or source is IFrameWindow::tryDialogResource and the dialog cannot be loaded, this function calls IFrameWindow::initialize.

Exception

IAccessError The frame window could not be created from the specified dialog template. Verify that the specified owner and parent window are valid.
IInvalidParameter source did not contain one of the FrameSource enumerator values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, this function always behaves as if noDialogResource was specified for source


[view class]
deferCreation
protected:
static const Style deferCreation

When a derived class creates the frame window, the derived class specifies this style to obtain more control over the frame window creation process. For example, a derived class could call IFrameWindow::initialize, IFrameWindow::create, or IFrameWindow::tryToLoadDialog to create a frame window.

Use the deferCreation style when you need to control things such as the type or style of of the underlying presentation system control that is used for the frame window, the default handlers that are attached to it, or the ordering of these handlers. For example, the default IFrameHandler is usually attached by the IFrameWindow::initialize function before any other handlers. This means that it is the last handler to process events sent to the frame window. If you want to have your own handler be the last handler, you could use the deferCreation style to keep the frame window constructor from adding the default handler. In your constructor, you add your handler first, and then call IFrameWindow::initialize to complete the frame window initialization process. Some events are not passed on by the default IFrameHandler, so in this scenario your handler will not see these events. It would, however, see them in the more typical case where the default IFrameHandler is attached first.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

Layout support members supply information used by the IFrameWindow class to provide dialog-like behavior. These members override members of IWindow.


[view class]
defaultEmphasisButton
public:
virtual IWindowHandle defaultEmphasisButton() const

Returns the push button that currently has the focus emphasis if this frame window is in its parent window chain.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultPushButton
public:
virtual IWindowHandle defaultPushButton() const

Returns the current default push button if this frame window is in its parent window chain.

Pressing the Enter key causes the default push button to be selected.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
matchForMnemonic
public:
virtual IWindowHandle matchForMnemonic( unsigned short character ) const

Returns the first child window using the specified character as a mnemonic.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultEmphasisButton
protected:
virtual IFrameWindow& setDefaultEmphasisButton( const IWindowHandle& defaultEmphasisButton, bool enable )

Sets the default emphasis button. This member function is typically called by IPushButton when focus is taken away from one push button and given to another by a user. The IFrameWindow keeps track of the current emphasis button this way. Emphasis buttons are typically set by user interaction with the application, not programmatically.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultPushButton
protected:
virtual IFrameWindow& setDefaultPushButton( const IWindowHandle& defaultPushButton )

Sets the default button. The typical way to set a default button is to use IPushButton::enableDefault. IPushButton::enableDefault will call IWindow::setDefaultPushButton, which passes the default button up the parent chain until an IFrameWindow object is found. IFrameWindow will save the default button so it can be activated when requested by the user of an application.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Modal Display

Use these members to manage frame windows (dialogs) in an application-modal fashion. When you display an application-modal frame window, its owner window becomes disabled. The user cannot interact with the owner window until first dismissing the application-modal frame window.


[view class]
dismiss
public:
virtual IFrameWindow& dismiss(unsigned long result = 0)

Removes a frame window from the display by hiding it and, if modal, completes the calls to IFrameWindow::showModally, which triggered the window's display. The dismiss function does not destroy the underlying presentation system window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notifyOwner
public:
virtual IFrameWindow& notifyOwner( unsigned long id, ICommandEvent::Source source = ICommandEvent::unknown, bool pointerDevice = false )

Posts a command event to the frame window's (or dialog's) owner.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
result
public:
virtual unsigned long result() const

Returns the frame result value. You set this value previously by calling either IFrameWindow::setResult or IFrameWindow::dismiss.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setResult
public:
virtual IFrameWindow& setResult(unsigned long result)

Sets the result value for the frame. This is typically used to indicate what action the user selected on a modal dialog. For example, if the user selects an OK button, you call setResult(DID_OK). If the user selects a Cancel button, you call setResult(DID_CANCEL). Subsequently, you can query the result to see what action the user requested using IFrameWindow::result. For example:

                    
  IFrameWindow dialog( MY_DIALOG );
  dialog.showModally();            
  if ( dialog.result() == DID_OK ) 
    // User said to go ahead...    
  else                             
    // User changed his mind...  

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
showModally
public:
virtual unsigned long showModally()

Displays the frame window modally. While the frame window is being shown modally, its parent or owner or both windows are disabled. Other top level windows belonging to the application are not disabled.

Exception

IInvalidParameter The frame window's owner and parent windows must not be the same when the frame is shown modally.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

Modal frame windows do not receive system command events with a command ID of ISystemMenu::idClose (SC_CLOSE) when they are closed from the task list. Frame windows that require this close notification should not be shown modally or should not be added to the task list.


Moving and Sizing

Use these members to move and size the frame and its client window.


[view class]
clientRectFor
public:
virtual IRectangle clientRectFor( const IRectangle& frameRect ) const

Returns a rectangle indicating the size and position the client window has if the frame is sized and positioned according to the specified rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
frameRectFor
public:
virtual IRectangle frameRectFor( const IRectangle& clientRect ) const

Returns a rectangle indicating the frame window's size and position required to produce the specified client window.

Exception

IAccessError The system could not calculate the frame window's rectangle. Possible causes include an invalid window handle was specified or the calculated rectangle was empty.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maximumFrameSize
public:
virtual ISize maximumFrameSize() const

Returns the maximum size that the frame window can be sized to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minimumFrameSize
public:
virtual ISize minimumFrameSize() const

Returns the smallest size that the frame window can be sized to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
moveSizeToClient
public:
virtual IFrameWindow& moveSizeToClient( const IRectangle& clientRect )

Sizes and positions the frame window around the specified client window's rectangle.

Exception

IAccessError The system could not calculate the frame window's rectangle. Possible causes include an invalid window handle was specified or the calculated rectangle was empty.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMaximumFrameSize
public:
virtual IFrameWindow& setMaximumFrameSize( const ISize& maximumFrameSize )

Use this function to limit the biggest size that a frame window can be sized to. Resizing , either by dragging the frame border or via the IWindow and IFrameWindow sizing member functions, is restricted once you call this function.

Exception

IInvalidParameter The proposed minimum size is greater than the current maximum size.Specify a smaller size.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMinimumFrameSize
public:
virtual IFrameWindow& setMinimumFrameSize( const ISize& minimumFrameSize )

Use this function to limit the smallest size that a frame window can be sized to. Resizing , either by dragging the frame border or via the IWindow and IFrameWindow sizing member functions, is restricted once you call this function. Minimizing is not affected by this function.

Exception

IInvalidParameter The proposed maximum is smaller than the current minimum size. Specify a bigger size.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Event Descriptions

Use these INotificationId strings for all notifications that IFrameWindow provides to its observers.


[view class]
activateId
public:
static INotificationId const activateId

Notification identifier provided to observers when the frame window is activated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
closeId
public:
static INotificationId const closeId

Notification identifier provided to observers when the frame window is closed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
deactivateId
public:
static INotificationId const deactivateId

Notification identifier provided to observers when the frame window is deactivated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
titleTextId
public:
static INotificationId const titleTextId

Notification identifier provided to observers when the frame window title is changed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Observer Notification

Observer notification members implement the INotifier protocol for IWindow classes.


[view class]
enableNotification
public:
virtual IFrameWindow& enableNotification( bool enable = true )

Enables the frame window to send notifications to any observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Sibling Order

These members affect the ordering of windows with their siblings. The window order (or Z-order) is used when tabbing or painting sibling windows. Window painting starts from the bottom sibling and proceeds to the topmost sibling window. Cursor tabbing occurs from the topmost sibling and proceeds to the bottom sibling window.


[view class]
defaultOrdering
public:
static IWindow::SiblingOrder defaultOrdering()

Returns the order in which new windows are created relative to their sibling windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultOrdering
public:
static void setDefaultOrdering( IWindow::SiblingOrder ordering )

Specifies whether the Open Class Library creates new windows on top of their sibling windows or behind them. By default, the library creates windows behind their other siblings.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Standard Control Access

Use these members to get information about the standard frame controls.


[view class]
handleFor
public:
virtual IWindowHandle handleFor( const Style& standardControl ) const

Returns the IWindowHandle corresponding to a standard frame control. If the control is not present, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In AIX, this function only supports the horizontalScroll and verticalScroll control styles.

Windows Considerations

In Windows, this function only supports the horizontalScroll and verticalScroll control styles.


Styles

IFrameWindow defines objects of the nested class IFrameWindow::Style. You can use these styles with IFrameWindow::setDefaultStyle and with constructors for the IFrameWindow class. You can combine IFrameWindow::Style objects with the objects of the class IWindow::Style.

Use these members to customize a window at the time you create it. Once you have constructed an IFrameWindow object, you can use IFrameWindow and IWindow member functions to query and change individual styles.

AIX Considerations

AIX does not support the following styles:

Some of the supported styles have behavior that is slightly different from OS/2 Presentation Manager if you specify:

Certain styles will affect the system menu function choices. If you do not specify the style:


[view class]
convertToArgList
public:
virtual IArgList convertToArgList( const IBitFlag& style ) const

Converts the style bits into an IArgList object that can be used by IWindow::create to create the appropriate widget.

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts style bits into the style value that can be processed by the GUI. The default action is to return the base GUI style for the platform. Extended styles that are defined by the Open Class Library can be returned by setting the extendedOnly parameter to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. This style is IFrameWindow::classDefaultStyle unless you have changed the style using IFrameWindow::setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent frame windows.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
accelerator
public:
static const Style accelerator

Associates an accelerator key table with the frame window. The frame window constructor loads the table from its resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alignNoAdjust
public:
static const Style alignNoAdjust

Restricts adjustment of the frame position. If you specify this style, you lose performance optimizations provided by frame position adjustment.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
animated
public:
static const Style animated

Shows the frame window with animation when it is opened, closed, or restored.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
appDBCSStatus
public:
static const Style appDBCSStatus

Includes a DBCS status area in the frame window when it is displayed in a DBCS environment.
Note: If you use a DBCS-operating system or machine, there is always one status area, even if you do not specify it.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
border
public:
static const Style border

Puts a border around the frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you specify this style, the window will also have a title bar. Use the IFrameWindow::dialogBorder style if you want a border without a title bar.


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IFrameWindow::titleBar | IFrameWindow::systemMenu | IFrameWindow::minimizeButton | IFrameWindow::windowList | IFrameWindow::maximizeButton | IFrameWindow::sizingBorder | IFrameWindow::appDBCSStatus.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dialogBackground
public:
static const Style dialogBackground

Gives the system dialog's background color to a frame that was not created from a dialog template. Without this style, the frame has the system window background color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dialogBorder
public:
static const Style dialogBorder

Puts a dialog border around the frame window. This style takes precedence over the sizeBorder style, a frame window that uses the dialogBorder style can not be resized.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

There is no difference between the IFrameWindow::dialogBorder style and the IFrameWindow::border style, except that dialogBorder can exist without a title bar.


[view class]
hideButton
public:
static const Style hideButton

Gives the frame window a hide button.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

OS/2 Considerations

This style is mutually exclusive with the IFrameWindow::minimizeButton style.

Windows Considerations

This style is interpreted exactly like the minimizeButton style. If you are using the Windows 95 desktop, setting this style will cause the systemMenu style to be set automatically.


[view class]
horizontalScroll
public:
static const Style horizontalScroll

Gives the frame window a horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maximizeButton
public:
static const Style maximizeButton

Gives the frame window a maximize button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you specify this style for a window that has an owner other than the desktop window, it is ignored when the default settings for the Motif Window Manager are in effect.

The window manager resources transientDecoration and transientFunctions control this behavior. When these resources have their system default values of menu title resizeh (that is, not including minimize maximize), owned windows do not have minimize or maximize buttons on the title bar and do not offer these options in the system menu.

Windows Considerations

If you specify this style, the window will also have a title bar, border, and system menu.


[view class]
maximized
public:
static const Style maximized

Creates the frame window in the maximized state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
menuBar
public:
static const Style menuBar

Gives the frame window a menu bar, which is loaded from the application's resource library. If you want to construct the frame window dynamically instead of from a resource library, use the class IMenuBar instead of this style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minimizeButton
public:
static const Style minimizeButton

Gives the frame window a minimize button. This style is mutually exclusive with the IFrameWindow::hideButton style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

If you specify this style for a window that has an owner other than the desktop window, it is ignored when the default settings for the Motif Window Manager are in effect.

The window manager resources transientDecoration and transientFunctions control this behavior. When these resources have their system default values of menu title resizeh (that is, not including minimize maximize), owned windows do not have minimize or maximize buttons on the title bar and do not offer these options in the system menu.

Windows Considerations

If you specify this style, the window will also have a title bar, border, and system menu.


[view class]
minimized
public:
static const Style minimized

Causes the frame window to be created in the minimized state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minimizedIcon
public:
static const Style minimizedIcon

Associates an icon with the frame window. The system uses this icon when it minimizes the frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noMoveWithOwner
public:
static const Style noMoveWithOwner

Disables the frame window's default behavior of automatically moving with its owner.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

This style is always set, meaning that frame windows do not move with their owner.


[view class]
shellPosition
public:
static const Style shellPosition

Sets the initial position of the window to a location and size dictated by the system shell.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizingBorder
public:
static const Style sizingBorder

Puts a sizing border around the frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
systemMenu
public:
static const Style systemMenu

Gives the frame window a system menu.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you specify this style, the window will also have a title bar and border.


[view class]
systemModal
public:
static const Style systemModal

Sets the frame window in system-modal mode.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
titleBar
public:
static const Style titleBar

Gives the frame window a title bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you specify this style, the window will also have a border.


[view class]
verticalScroll
public:
static const Style verticalScroll

Gives the frame window a vertical scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
windowList
public:
static const Style windowList

Adds an entry representing the frame window to the system window list.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

This style has no effect with the Windows Program Manager shell. With the Windows 95 shell, setting this style causes an entry for the window to be placed into the task bar when the frame is a secondary window or dialog window. An entry is always created in the task bar for the primary window of the application, regardless of the setting of this style.


System-Menu-Related Actions

Use these members with frame operations related to the actions on the system menu.

These operations include minimizing and maximizing a frame window. You can also restore a frame window after it has been minimized or maximized. You can query the rectangle value for a maximized or minimized window or the rectangle to which the frame window is restored after minimizing or maximizing the frame.

You can close the frame window or query the recommended rectangle value for the next frame window.


[view class]
close
public:
virtual IFrameWindow& close()

Closes the frame window. Closing a frame window causes all child windows of the frame window to close, as well as all other frame windows owned by the frame window. Closing the last primary window in your application causes the event (message) queue to terminate. When the queue terminates, the run member function in your main routine ends.

The closing of a frame window is distinct from the destruction of the underlying presentation system window. The IFrameWindow class provides facilities you can use to connect these two events, thereby forcing the presentation system window to be destroyed when the user closes the frame window. The attribute used to link the closing of a frame window and the destruction of the underlying presentation system window is called destroyOnClose. By default, IFrameWindow sets destroyOnClose to true.

Occasionally, you may want to close the window without destroying the presentation system window, such as for modal frame window dialogs you use over and over in your application. In such cases, use the member function setDestroyOnClose to set this attribute off. Use willDestroyOnClose to query this setting.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
maximize
public:
virtual IFrameWindow& maximize()

If the window has a maximize button, this function maximizes the window. If the window does not have a maximize button, this function does nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
maximizeRect
public:
virtual IRectangle maximizeRect() const

Returns a rectangle indicating the size and position the frame window has when it is maximized.

Exception

IAccessError The system could not determine the frame window's maximized position. A possible cause is an invalid window handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

AIX does not support this function; therefore, it returns a default IRectangle.


[view class]
minimize
public:
virtual IFrameWindow& minimize()

Minimizes the window. If the window does not have a minimize button, this function does nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
minimizeRect
public:
virtual IRectangle minimizeRect() const

Returns a rectangle indicating the size and position the frame window has when it is minimized.

Exception

IAccessError The system could not determine the frame window's minimized position. A possible cause is an invalid window handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

AIX does not support this function; therefore, it returns a default IRectangle.

Windows Considerations

The position of the rectangle returned is not valid until the window is or has been actually minimized.

If you are using the Windows 95 desktop, you should ignore the position of the rectangle returned at all times. The size of the rectangle is the default size of items placed into the taskbar.


[view class]
nextShellRect
public:
static IRectangle nextShellRect()

Returns the system-recommended coordinates of the next main window.

Exception

IAccessError The system could not generate recommended values for the size and position of the frame window. A possible cause is an invalid anchor block for the current thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function returns a rectangle computed by the Open Class Library This rectangle is approximately 2/3 the size of the screen, and usually located 25 pixels further to the right and bottom than the previous rectangle returned by this function.

Windows Considerations
This function returns a rectangle computed by the Open Class Library This rectangle is approximately 2/3 the size of the screen, and usually located 25 pixels further to the right and bottom than the previous rectangle returned by this function.

[view class]
restore
public:
virtual IFrameWindow& restore()

Restores a maximized or minimized window to its previous size and position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function only restores a window from its minimized state.


[view class]
restoreRect
public:
virtual IRectangle restoreRect() const

Returns the window rectangle coordinates to which the window will be restored.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function returns a default IRectangle object.


[view class]
setRestoreRect
public:
virtual IFrameWindow& setRestoreRect( const IRectangle& rect )

Sets the rectangle coordinates indicating the size and position to which the window is restored. If the size of the specified rectangle is larger than the size of the screen, the actual restore rectangle set is the size of the screen.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Testing

Use these members to test various attributes of the frame window. These attributes include whether the frame is flashing, the frame is minimized or maximized, or the frame window has been shown modally.


[view class]
isFlashing
public:
bool isFlashing() const

If the frame window is flashing, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

In AIX, this function always returns false.


[view class]
isMaximized
public:
bool isMaximized() const

If the frame window is maximized, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

In AIX, this function always returns false.


[view class]
isMinimized
public:
bool isMinimized() const

If the frame window is minimized, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isModal
public:
bool isModal() const

If the window is displayed in application-modal mode, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Title Support

Use this member functions to set and query the title on an IFrameWindow object.


[view class]
setTitleText

Sets the title text of the IFrameWindow.


Overload 1
public:
virtual IFrameWindow& setTitleText( const IResourceId& titleResId )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IFrameWindow& setTitleText(const char* titleText)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
titleText
public:
virtual IString titleText() const

Returns the title text of the IFrameWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Tool Bar Support

The Open Class Library tool bar implementation uses these members to manage the use of tool bar containers in a frame window.


[view class]
setToolBarList
public:
IFrameWindow& setToolBarList(IToolBarList* toolBarList)

Stores the address of a list containing the toolbars used in this frame window. This function is designed for use by the Open Class Library toolbar implementation. You do not need to call it directly.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
toolBarList
public:
IToolBarList* toolBarList() const

Returns the address of the list of toolbars used in this frame window. This function is designed for use by the Open Class Library toolbar implementation. You do not need to call it directly.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Destruction

These members destroy the GUI window associated with an IFrameWindow object when the window is closed.


[view class]
setDestroyOnClose
public:
virtual IFrameWindow& setDestroyOnClose( bool destroy = true )

Sets the destroy window flag on or off. If the flag is on, the window object is destroyed when the window is closed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
willDestroyOnClose
public:
bool willDestroyOnClose() const

Returns the state of the destroy window flag. The default state is on.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Display

Use the window display members to manage the visibility of the frame window.


[view class]
show
public:
virtual IFrameWindow& show(bool showWindow = true)

Shows or hides the frame window. If the flag is true, the frame window is shown. If the flag is false, the frame window is hidden.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Flashing

Use these members to make the frame start and stop flashing. You could flash the frame window to alert the user to an error situation.


[view class]
beginFlashing
public:
virtual IFrameWindow& beginFlashing()

Starts flashing the frame. Use this to alert the user to something that requires immediate attention.

Exception

IAccessError The system could not flash the frame window. A possible cause is an invalid window handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
endFlashing
public:
virtual IFrameWindow& endFlashing()

Stops flashing the frame window.

Exception

IAccessError An error occurred when the system tried to stop flashing the frame window. A possible cause is an invalid frame window handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Window Layout

Window layout members notify the frame of changes to its layout.


[view class]
setLayoutDistorted
public:
IFrameWindow& setLayoutDistorted( unsigned long layoutAttributesOn, unsigned long layoutAttributesOff )

Indicates that changes have occurred in the window that will cause the layout of the window to be updated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window List

Use these members to add and remove frame titles from the window list.


[view class]
addToWindowList
public:
virtual IFrameWindow& addToWindowList()

Adds this frame window's title as a window list entry. If you construct this frame window with the style IFrameWindow::windowList, the title is automatically added to the window list.

Exception

IAccessError The frame window's title was not added as an entry in the window list. Possible causes include the following: a title bar does not exist for the frame window, the limit has been reached for number of window list entries, or the frame window had a previous window list entry that was invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
removeFromWindowList
public:
virtual IFrameWindow& removeFromWindowList()

Removes this frame's entry from the window list.

Exception

IAccessError The system could not remove the entry from the window list. A possible cause is an invalid window list handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


IFrameWindow - Enumerations


[view class]
FrameSource
enum FrameSource { dialogResource, 
                   noDialogResource, 
                   tryDialogResource }

Use these enumerators to control the processing of a set of the IFrameWindow constructors.

dialogResource
The constructors will attempt to load a dialog resource. If the dialog cannot be loaded, an exception is thrown.
noDialogResource
The constructors will create a new frame window with the style returned by IFrameWindow::defaultStyle. No attempt is made to load a dialog resource.
tryDialogResource
The constructors will attempt to load a dialog resource. If the dialog resource cannot be found, a new frame window is created with the style returned by IFrameWindow::defaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
Location
enum Location { leftOfTitleBar, 
                rightOfTitleBar, 
                leftOfMenuBar, 
                rightOfMenuBar, 
                leftOfClient, 
                rightOfClient, 
                aboveClient, 
                belowClient }

Use these enumerators to specify the possible locations for an extension:

leftOfTitleBar
Specifies left of the frame title area and, if a system menu is present, to the right of the menu.
rightOfTitleBar
Specifies right of the frame title.
leftOfMenuBar
Specifies left of the menu bar.
rightOfMenuBar
Specifies right of the menu bar.
leftOfClient
Specifies the left-hand side of the client area.
rightOfClient
Specifies the right-hand side of the client area.
aboveClient
Specifies the top of the client area.
belowClient
Specifies the bottom of the client area.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support the following locations because it cannot position IFrameExtension objects to the side of the title bar or to the side of the menu.

  • leftOfMenuBar
  • leftOfTitleBar
  • rightOfMenuBar
  • rightOfTitleBar

Windows Considerations

Windows does not support the following locations because it cannot position IFrameExtension objects to the side of the title bar or to the side of the menu.

  • leftOfMenuBar
  • leftOfTitleBar
  • rightOfMenuBar
  • rightOfTitleBar

[view class]
SeparatorType
enum SeparatorType { none, 
                     thinLine, 
                     thickLine }

Use these enumerators to specify the possible types of separators drawn between the extension and the control it is attached to:

none
Draws no separator.
thinLine
Draws a thin separator line (1 pel wide).
thickLine
Draws a thick separator line (3 pels wide).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IFrameWindow - Inherited Member Functions and Data

Inherited Public Functions

INotifier
IWindow
IFrameWindow

Inherited Public Data

IWindow
INotifier

Inherited Protected Functions

IWindow
INotifier

Inherited Protected Data