IWindow

The IWindow class is the base window class and provides behavior common to all windows. Although this class contains behavior requiring the existence of a presentation window, you must construct the presentation window itself using a derived class.
Note: Although you can construct objects of this class directly, you do not generally do so.

Portability Considerations

This class is portable across the OS/2, AIX, and Windows environments. Most of the member functions are also portable. See individual member functions for details.

AIX Considerations

In Motif, the Open Class Library does not support dialog templates. However, there is still an IWindow constructor that takes a parent IWindow and a resource ID. This is useful in case there is an existing widget you want to create an IWindow for, but you only know the following:

IWindow wraps and enhances the X Windows System and Motif widget set. The implementation uses calls to the Motif toolkit (Xt...) and Motif helper (Xm...) routines, as well as calls directly to the X Library (XLib...) when Xt does not offer the necessary function.


IWindow - Member Functions and Data by Group

Constructors & Destructor

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


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

Cleans up as this IWindow object is being destroyed. Clean up includes the following:

Exception

IAccessError The operating system was unable to reset the default window procedure; a possible cause is an invalid window handle.
IInvalidRequest An attempt was made to destroy a window from within a handler which was handling an event for the same window. To avoid this situation, delete the object from outside the handler or use setAutoDeleteObject to cause the library to automatically delete the object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IWindow


Overload 1
public:
IWindow(const IWindowHandle& handle)

Constructs an IWindow object for an existing window, typically created by having previously called a window system API (for example, WinCreateWindow(...), XtCreateWidget(...) ). The window is not automatically destroyed when the IWindow object is destroyed; you can change this by using setAutoDestroyWindow.

This constructor reserves the user data word of the control for application or control use. You can improve performance of a derived class that uses this constructor by calling reserveUserWindowWord(false).

Exception

IInvalidParameter The specified handle is invalid. You must specify the handle of an existing window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IWindow(unsigned long identifier, IWindow* parent)

Constructs an IWindow object for an existing window that is a known child of a known IWindow object. For example, when a dialog template is loaded, you can use this function to create an IWindow object for one of its child controls; you must know the window identifier of the child control.

This constructor reserves the user data word of the control for application or control use. You can improve performance of a derived class that uses this constructor by calling reserveUserWindowWord(false).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
protected:
IWindow()

Used by derived classes to create objects of this class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Accelerator Key Support

Accelerator keys are shortcut keys for performing an action. The action can be an application command, system command, or request for help. You can assign accelerator keys to any window.

If you press an accelerator key used by the window with the input focus, that window is sent the resulting command or help request. If the window does not translate the key into a command or help request, a window in the parent window chain (up to and including the first frame window) could translate the key. In this case, the parent window that has the key in its accelerator table receives a command event, or the window with the input focus receives a help request.

You can define the accelerator keys for a window using any of the following means:


[view class]
acceleratorHandle
public:
IAccelTblHandle acceleratorHandle() const

Returns a handle for the accelerator keys used by the window. If the window has no accelerator keys, this function returns a zero IAccelTblHandle object. Accelerator keys provided by the system (for example, F10 and Alt+F4) are not reflected in the returned object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
acceleratorTable
public:
IAcceleratorTable acceleratorTable() const

Returns the accelerator keys used by the window. If the window has no accelerator keys, this function returns an IAcceleratorTable object that contains no keys. Accelerator keys provided by the system (for example, F10 and Alt+F4) are not included in the returned object.

Calling this function is equivalent to using the IAcceleratorTable constructor that accepts a const IWindow* parameter.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAcceleratorHandle
public:
IWindow& setAcceleratorHandle( const IAccelTblHandle& handle )

Replaces the accelerator keys used by the window. Specify a zero IAccelTblHandle object to remove the window's accelerator keys.

Calling this function is equivalent to any of the following:

Exception

IAccessError The operating system is unable to associate the accelerator table with the window (OS/2 only).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAcceleratorTable
public:
IWindow& setAcceleratorTable( const IAcceleratorTable* acceleratorTable )

Replaces the accelerator keys used by the window. Specify a zero pointer or an empty IAcceleratorTable object to remove the window's accelerator keys.

Calling this function is equivalent to any of the following:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

Use these members to query and set the accessible attributes of objects of this class.


[view class]
desktopWindow
public:
static IWindow* desktopWindow()

Returns the object representing the system desktop window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Returns the Open Class Library object representing the X root window. Actually, the desktopWindow is the application shell widget. It is sometimes used like the root window, however. In other window systems, the desktop is the root of all windows and its handle can be obtained and used. In X-Motif, the user does not know the actual handle of the root window. Instead, the X library provides the user a set of routines for creating children of the root. These children cannot be visible widgets: they are only invisible shell widgets. Therefore, they are used as the parent of the actual visible widgets you want to hang off the root. The Open Class Library hides this difference from you if you use IWindow objects, including derived classes, and not window handles.


[view class]
enable
public:
virtual IWindow& enable(bool enableWindow = true)

Enables the window to accept keyboard and mouse input.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the window handle.

Exception

IInvalidRequest The window does not have a valid handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the handle that should be used as the parent of a child when the child is created. This member function is usefull for aggregate controls, like an IViewPort, where the handle of the IViewport is not the appropriate parent of its children.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleWithPointerCaptured
public:
static IWindowHandle handleWithPointerCaptured()

Returns the window handle that currently has the mouse captured.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hasFocus
public:
virtual bool hasFocus() const

If the window has the input focus, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the window identifier of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Motif's equivalent of window IDs are widget names. The Open Class Library has established the convention of numeric IDs for portability. The library converts the numeric to a character string and uses the string as the name of the widget on XmCreate... By doing so, the library can extract the name from the widget instead of keeping a local copy of the ID:

      IString resid( XtName( (Widget)handle() );
      return ( resid.asInt() );
In Motif, the Open Class Library classes are the only classes that use the IWindow::id value as an integer.

If this IWindow was constructed from an existing widget, the widget name is typically a string of any alphanumeric characters, not just 0-9. In this case, the return value is undefined. If you use the IWindowHandle constructor for IWindow or any of its derived classes and you did not adhere to the Open Class Library convention of numeric window IDs, do not use this member function. Instead, use XtNameToWidget.
Note: Using IResourceId objects instead of the primitives for int or char* ensure adherence to the convention.


[view class]
isFrameWindow
public:
virtual bool isFrameWindow() const

If this object represents a frame window, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isValid
public:
virtual bool isValid() const

If this object represents a valid window in the window system, true is returned. If the window has yet to be created or has already been destroyed, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isWindowValid
public:
static bool isWindowValid(const IWindow* window)

If the specified pointer is the address of an IWindow object managed by the Open Class Library, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
messageQueue
public:
IMessageQueueHandle messageQueue() const

Returns the handle for the window's message queue.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
objectWindow
public:
static IWindow* objectWindow()

Returns the object representing the system object window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The operating system does not provide a separate object window hierarchy. Instead, Open Class Library creates an invisible window that is a child of the desktopWindow that you can use for message processing or other purposes where you need an invisible window object.

Windows Considerations

The operating system does not provide a separate object window hierarchy. Instead, Open Class Library creates an invisible window that is a child of the desktopWindow that you can use for message processing or other purposes where you need an invisible window object.


[view class]
setFocus
public:
virtual IWindow& setFocus()

Sets the input focus to the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setId
public:
virtual IWindow& setId(unsigned long newIdentifier)

Sets the window identifier of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
windowWithHandle
public:
static IWindow* windowWithHandle( const IWindowHandle& windowHandle, bool allThreads = true )

Returns the IWindow object for the specified window handle. If the specified window handle is not associated with any IWindow object, 0 is returned. If allThreads is set to true, all threads are searched. Otherwise, only the current thread is searched. This is a static function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
windowWithOwner
public:
static IWindow* windowWithOwner( unsigned long identifier, const IWindow* owner, bool allThreads = true )

Returns the IWindow object with the specified window identifier and owner. If allThreads is set to true, all threads are searched. Otherwise, only the current thread is searched. This is a static function.
Note: This function replaces IWindow::windowWithId.

If the specified window identifier is not associated with any IWindow object, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
windowWithParent
public:
static IWindow* windowWithParent( unsigned long identifier, const IWindow* parent, bool allThreads = true )

Returns the IWindow object for the specified window identifier and parent. If allThreads is set to true, all threads are searched. Otherwise, only the current thread is searched. If you are searching for a primary or secondary window, you should specify IWindow::desktopWindow for parent. This is a static function.

If the specified window identifier is not associated with any IWindow object, 0 is returned.

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 IWindow& setBidiSettings( const IBidiSettings& bidiSettings, bool childInherit, bool refresh )

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

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.

If you override this function in a derived class, the overridden version must call this version of the function.

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.

Windows Considerations

This function sets extended window styles that IBidiSettings uses to query the text and layout orientation of a window.


Canvas Support

Layout support members supply information used by the canvas classes to provide dialog-like behavior. The virtual functions contain implementations which can be overridden in derived classes.


[view class]
disableMinimumSizeCaching
public:
IWindow& disableMinimumSizeCaching()

Disables the caching of minimum sizes. When you disable caching, you cause each call to IWindow::minimumSize to call calcMinimumSize.

By default, a window caches its minimum sizes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableMinimumSizeCaching
public:
IWindow& enableMinimumSizeCaching( bool enableCaching = true )

Enables or disables the caching of minimum sizes as an optimization for not calling calcMinimumSize. When enabled, this optimization causes IWindow::minimumSize to call calcMinimumSize, but thereafter to return the previously calculated value. When you disable caching, you cause each call to IWindow::minimumSize to call calcMinimumSize. See IWindow::minimumSize for details.

By default, a window caches its minimum sizes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isLayoutDistorted
public:
virtual bool isLayoutDistorted( unsigned long layoutAttribute ) const

If changes have been made in a window that requires updating the layout of the window in a canvas, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns if the IWindow object will call IWindow::savedMinimumSize as an optimization for not calling calcMinimumSize. By default, a window uses this optimization.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

The layout adjustment is the dimensions that a window is moved or sized or both after a canvas runs its layout routines. This function exists to support controls such as the drop-down combination box where the displayed size of the control is different from its actual size. The default IWindow implementation of this function returns IRectangle(0,0,0,0).

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]
minimumSize
public:
ISize minimumSize(bool windowCalculatedSize = false) const

Returns the minimum allowable size that is set by a derived class. If setMinimumSize has not been called or windowCalculatedSize is true, it returns the value of calcMinimumSize or savedMinimumSize. Otherwise, it returns the value specified by setMinimumSize.

Because calcMinimumSize can be a potentially time-consuming function, IWindow::minimumSize will save the value returned by that function and return the saved value until the window has a new minimum size. This function saves the minimum size using saveMinimumSize and then calls setLayoutDistorted to clear the window's minimumSizeChanged flag. It retrieves the saved value using savedMinimumSize. It determines if the window has a new minimum size by checking if any of the following are true:

If the window's minimum size has changed, this function returns the minimum size set by setMinimumSize or returned by calcMinimumSize.

You can disable this optimization using disableMinimumSizeCaching.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetMinimumSize
public:
IWindow& resetMinimumSize()

Resets the minimum allowable size as if setMinimumSize had not been called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Indicates that changes have occurred in the window causing the layout of the window in a canvas to be updated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMinimumSize
public:
IWindow& setMinimumSize(const ISize& size)

Sets the minimum allowable size of the window. In the Open Class Library this applies only to windows on a canvas. Calling this function causes minimumSize to not call calcMinimumSize.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the painted rectangle for controls like the drop-down combination box where the painted rectangle of the control is different from its actual rectangle. The default behavior of this function returns the actual rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
calcMinimumSize
protected:
virtual ISize calcMinimumSize() const

Returns the recommended minimum size of this IWindow object. The library uses this size in the canvas layout routine. If no derived classes override this function, the default size is 100 x 100 pels.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
savedMinimumSize
protected:
ISize savedMinimumSize() const

Returns the calculated minimum size of this IWindow object saved using IWindow::saveMinimumSize. As an optimization for not calling calcMinimumSize, IWindow::mininumSize may return the value returned by this function. See IWindow::minimumSize and enableMinimumSizeCaching for details.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
saveMinimumSize
protected:
IWindow& saveMinimumSize(const ISize& size)

Saves the calculated minimum size of this IWindow object. IWindow::minimumSize uses this function to store values returned by calcMinimumSize. See IWindow::minimumSize for details.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Child Cursor Support

These members provide child cursor support.


[view class]
childAt
public:
IWindowHandle childAt(const ChildCursor& cursor) const

Returns the window handle of the child window at the current position of the specified cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
childWindowAt
public:
IWindow* childWindowAt(const ChildCursor& cursor) const

Returns the IWindow pointer of the child window at the current position of the specified cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to query, set, and reset colors for IWindow classes and their derived classes. The only portable color areas are foreground and background.

There are restrictions for specifying the color of controls based on the platform and which style of control you use. For example, Windows does not allow you to change the color of an individual push button. For more information on the behavior of these color member functions for a particular control, refer to the platform specific notes for that control.


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

Returns the active color value of the window area. If you have not set the color for the area, the default color is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default active color value of the window area.


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

Returns the background color value of the window. If you have not set the background color for the window, the default background color is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the disabled background color value of the window area. If you have not set the color for the area, the default color is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default disabled background color value of the window area.


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

Returns the disabled foreground color value of the window area. If you have not set the color for the area, the default color is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default disabled foreground color value of the window area.


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

Returns the foreground color value of the window or the default if no foreground color for the window has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default highlight background color value of the window area.


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

Returns the highlight foreground color value of the window area or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default highlight foreground color value of the window area.


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

Returns the inactive color value of the window area or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Returns the default inactive color value of the window area.


[view class]
resetActiveColor
public:
virtual IWindow& resetActiveColor()

Resets the active color by undoing the previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


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

Resets the background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Resets the disabled background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetDisabledForegroundColor
public:
virtual IWindow& resetDisabledForegroundColor()

Resets the disabled foreground color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetForegroundColor
public:
virtual IWindow& resetForegroundColor()

Resets the foreground color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetHiliteBackgroundColor
public:
virtual IWindow& resetHiliteBackgroundColor()

Resets the highlight background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetHiliteForegroundColor
public:
virtual IWindow& resetHiliteForegroundColor()

Resets the highlight foreground color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetInactiveColor
public:
virtual IWindow& resetInactiveColor()

Resets the inactive color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetShadowColor
public:
virtual IWindow& resetShadowColor()

Resets the shadow color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setActiveColor
public:
virtual IWindow& setActiveColor(const IColor& color)

Sets the active color to the indicated color. The window area is identified by a system-defined presentation parameter value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setBackgroundColor
public:
virtual IWindow& setBackgroundColor(const IColor& color)

Sets the background color to the indicated color.

The background color is also propagated down to the children of the IWindow object on Motif and Windows. This is to simulate PM's behavior with colors. The color is propagated to all children that inherit background color from their parent IWindow. The inheritance of background color is controlled by an attribute that can be added to an the IWindow object. The attribute is IInheritColorAttribute. An example of a control that does not inherit background color from its parent is IEntryField. IEntryField

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The Motif version of this function uses XmChangeColor to set the background color. XmChangeColor also sets the shadow and foreground colors to various shades of the background color to achieve a three-dimensional look for the widget. If you want the foreground color to be a different color than the color set by XmChangeColor, set the foreground color after setting the background color using IWindow::setForegroundColor.


[view class]
setDisabledBackgroundColor
public:
virtual IWindow& setDisabledBackgroundColor( const IColor& color )

Sets the disabled background color to the indicated color. The window area is identified by a system-defined presentation parameter value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setDisabledForegroundColor
public:
virtual IWindow& setDisabledForegroundColor( const IColor& color )

Sets the disabled foreground color to the indicated color. The window area is identified by a system-defined presentation parameter value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setForegroundColor
public:
virtual IWindow& setForegroundColor(const IColor& color)

Sets the foreground color to the indicated color.

The foreground color is also propagated down to the children of the IWindow object on Motif and Windows. This is to simulate PM's behavior with colors. The color is propagated to all children that inherit foreground color from their parent IWindow. The inheritance of foreground color is controlled by an attribute that can be added to an the IWindow object. The attribute is IInheritColorAttribute. , and the attribute name is IInheritColorAttribute.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setHiliteBackgroundColor
public:
virtual IWindow& setHiliteBackgroundColor( const IColor& color )

Sets the highlight background color to the indicated color. The window area is identified by a system-defined presentation parameter value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setHiliteForegroundColor
public:
virtual IWindow& setHiliteForegroundColor( const IColor& color )

Sets the highlight foreground color to the indicated color. The window area is identified by a system-defined presentation parameter value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setInactiveColor
public:
virtual IWindow& setInactiveColor(const IColor& color)

Sets the inactive color to the specified color. The window area is identified by a system-defined presentation parameter value.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setShadowColor
public:
virtual IWindow& setShadowColor(const IColor& color)

Resets the shadow color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


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

Returns the shadow color value of the window area or the default if no color for the area has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetColor
protected:
virtual IWindow& resetColor(unsigned long colorArea)

Resets the color of a window back to its default value by undoing any previous calls to setColor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setColor
protected:
virtual IWindow& setColor( unsigned long colorArea, const IColor& color )

Sets the window area to the specified color. You can identify the window area using a system-defined presentation parameter value.

The arguments are the following:

colorArea
The area for which the color is being set. The values are OS/2 Presentation Manager Toolkit presentation parameters color areas, such as PP_FOREGROUNDCOLOR. It is not limited to these values; you can define your own, but then you must also supply the support for these new values. You can only choose the values that refer to RGB colors; you cannot use ones that refer to index colors.
color
The area to be set to this color. This member function should be overriden the color behavior needs to be augmented.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Data Handle Members

Use these member functions for setting and querying window data.


[view class]
adoptWindowData
public:
IWindow& adoptWindowData( const DataHandle& typeToken, IWindowData* windowData )

Allows adopting window data that can be associated with an IWindow for later retrieval.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dataHandleWithKey
public:
static DataHandle dataHandleWithKey( const char* dataKeyName )

Returns the data handle for the window data with the key name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
windowData
public:
IWindowData* windowData(const DataHandle& typeToken) const

Returns the window data associated with the specified data handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Diagnostics

Use these members to output diagnostic information for the window.


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

Returns a string containing detailed information about the window, including the information provided by IWindow::asString.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns a string containing the window handle and ID.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Drag and Drop Support

Use these members to query and set the drag-item provider for objects of this class.


[view class]
itemProvider
public:
IDMItemProvider* itemProvider() const

Returns a pointer to the drag-item provider (IDMItemProvider) for this window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support this function.


[view class]
setItemProvider
public:
IWindow& setItemProvider(IDMItemProvider* dragProvider)

Sets a pointer to the drag-item provider (IDMItemProvider) for this window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

AIX does not support this function.


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

The event is either a mouse button down, mouse button up, or a mouse move message. This member function exists to help determine whether or not a drag condition is occurring for this control. If proper drag conditions are met then true is returned. Otherwise, false is returned.

The default implementation looks for a button down event. If the mouse then moves more than two pels before a mouse button event is received, then a drag is occurring. If the criteria for a drag from a derived control is more elaborate than the default implementation, then the derived class needs to override this member function.

Supported Platforms

Windows OS/2 AIX
Yes No No


Event Send and Post

Use these members to send or post an event to a window.


[view class]
postEvent

Posts an event constructed from the arguments to the window. If you specify an enumerator from IWindow::EventType, the library constructs an event with the appropriate message identifier.


Overload 1
public:
virtual const IWindow& postEvent( unsigned long eventId, const IEventParameter1& parm1 = 0, const IEventParameter2& parm2 = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual const IWindow& postEvent(const IEvent& event) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

Events (or messages) posted using this member function are subject to the restrictions and limitations of the underlying operating system.


Overload 3
public:
virtual const IWindow& postEvent( EventType eventType, const IEventParameter1& parm1 = 0, const IEventParameter2& parm2 = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Events (or messages) posted using this member function are subject to the restrictions and limitations of the underlying operating system since the Open Class Library converts IWindow::EventType enum values to system defined event identifiers.


[view class]
sendEvent

Sends an event constructed from the arguments to the window. If you specify an enumerator from IWindow::EventType, the library constructs an event with the appropriate message identifier.


Overload 1
public:
virtual IEventResult sendEvent(const IEvent& event) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IEventResult sendEvent( EventType eventType, const IEventParameter1& parm1 = 0, const IEventParameter2& parm2 = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Events (or messages) posted using this member function are subject to the restrictions and limitations of the underlying operating system since the Open Class Library converts IWindow::EventType enum values to system defined event identifiers.


Overload 3
public:
virtual IEventResult sendEvent( unsigned long eventId, const IEventParameter1& parm1 = 0, const IEventParameter2& parm2 = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event-Handling Implementation

Event-handling implementation members perform processing needed to allow handlers to properly receive GUI events and to route these events.


[view class]
dispatchRemainingHandlers
public:
bool dispatchRemainingHandlers( IEvent& event, bool callDefProc = true )

Dispatches the event to all handlers that the event has not yet been dispatched to. This function stops dispatching if any handler it calls returns true. If all remaining handlers return false, this function optionally calls IHandler::defaultProcedure depending on the value of the callDefProc parameter.

When this function is called, the event passed to it must be the same event that was passed to the handler you are calling this function from or an event constructed from that event.

If false is returned from this function, the caller must take one of the following actions:

The caller of this function must always return true from the handler this function was called from.

If this function returns true, it means that either a handler the event was dispatched to handled the event, or none of the handlers handled the event and IHandler::defaultProcedure was called. If false is returned, it means that all handlers called returned false and did not handle the event and IHandler::defaultProcedure was not called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addToWindowSet
protected:
static void addToWindowSet( IWindow* window, const IWindowHandle& windowHandle )

Adds a window to the current thread's collection of windows. You must provide a valid window handle.

Exception

IInvalidParameter Either the specified window or windowHandle is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultProcedure
protected:
IWindow& defaultProcedure(IEvent& event)

Provides default processing behavior for a window event. This function calls the window procedure that was returned from the window derived class during the call to IWindow::startHandlingEventsFor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, this function is not called during normal event processing and has no effect if it is called. There is no default window procedure that you must explicitly call or that you can avoid by not calling it. The window itself (that is, the widget) determines what default or standard processing occurs prior to application code (such as the Open Class Library) being called. The window also determines what processing occurs afterward. Additionally, you cannot prevent X-Motif from calling other portions of application code, which might be registered with this widget as callbacks. You cannot affect the order reliably. However, widgets and other callbacks are designed with this fact in mind.


[view class]
deleteIsInProcess
protected:
bool deleteIsInProcess() const

If the IWindow object destructor has been called or the presentation window is being destroyed, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Dispatches events to the handlers associated with a window. If a handler does not process the event or no handlers exist for the window, the library calls IWindow::defaultProcedure to process the event.

The library also performs post-processing for certain events. For example, the library uses destroy events to clean up the related IWindow object, if needed. The library uses resize events to verify that re-coordination is current.

The preferred way to pass an IEvent object to a window for processing is to call IWindow::sendEvent function. If you must call dispatch directly, do not pass an IEvent object to this function that is already being processed by a handler. Make a copy of the IEvent and pass the copy to dispatch().

Exception

IInvalidRequest The window dispatcher found a handler that was invalid. The handler must be removed prior to deletion.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isUserWindowWordReserved
protected:
bool isUserWindowWordReserved() const

Returns true if Open Class Library is not using the user data area of the presentation system control to cache information used to locate IWindow objects. See reserveUserWindowWord for more information about this setting.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Determines if an event is passed on to the owner.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


[view class]
removeFromWindowSet
protected:
static void removeFromWindowSet(IWindow* window)

Removes a window from the current thread's collection of windows.

Exception

IInvalidParameter The specified window is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
reserveUserWindowWord
protected:
IWindow& reserveUserWindowWord(bool reserve = true)

Use this function to reserve the user data area of the presentation system control for your application or custom control. If the user data area is not reserved, Open Class Library uses the user data area of the presentation system control to cache information for locating the associated IWindow object. Ths causes the Open Class Library event processing to run faster because it can find the IWindow object associated with each event much more quickly. However, if your application uses the user data area of the presentation system control for another purpose, it is likely that your application will fail because of the conflicting uses of the same storage location. In this case, you can call reserveUserWindowWord( true ) to reserve the user data area for your use. Another way to resolve the conflict is to change your code to use another storage area, such as C++ class member data, for the information you are storing in the control user data area.

You can call this function from within your IWindow-derived class at any time. However, the most efficient way is to call reserveUserWindowWord before you call IWindow::startHandlingEventsFor.

By default, Open Class Library uses the user data area of all controls created with the IWindow::create function. Most of the constructors for IWindow derived classes within Open Class Library either use IWindow::create to create the underlying presentation system control or call reserveUserWindowWord(false) to enable faster processing. You must call reserverUserWindowWord(true) before modifying the user data area of the control associated with these objects.

The user window word is not used by Open Class Library for objects created by the IWindow constructor that accepts an IWindowHandle or the IWindow constructor that accepts an unsigned long identifier and an IWindow* for the parent window. In addition, Open Class Library does not, by default, modify the user window word in the following cases:

Use isUserWindowWordReserved to determine if the user data word is available for application or control use.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is ignored and the user data word is always reserved. The Open Class Library uses the client data area of the callbacks it installs to efficiently locate the IWindow object associated with an event, and therefore does not need to use widget resources for this purpose. The resource XmNuserData, defined by the XmPrimitive, XmManager, and XmGadget widget classes, is not affected by this function.

OS/2 Considerations

The user data area used by Open Class Library is the 32-bit word at the QWL_USER index defined in the developer's toolkit.

Windows Considerations

The user data area used by Open Class Library is the 32-bit word at the GWL_USERDATA index defined in the Win32 SDK.


[view class]
startHandlingEventsFor

Starts processing events for the window. This is a combination of subclassing the window procedure and storing the window in the current thread's collection of windows. You can only call this function once per window, typically during construction of the window.


Overload 1
protected:
IWindow& startHandlingEventsFor( unsigned long identifier, IWindow* parent )

Exception

IInvalidParameter The specified parent is invalid. You must specify a nonzero parent window.
IInvalidRequest No window with the specified identifier could be found.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IWindow& startHandlingEventsFor( const IWindowHandle& windowHandle )

Exception

IInvalidParameter The specified windowHandle is invalid, or identifies a window for which a window object already exists.
IInvalidRequest The default procedure for the window could not be replaced. Possibly a window object already exists for the window identified by windowHandle, or the window was created by a different process or application.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exception Processing

Use these members to process C++ exceptions in the IWindow dispatcher.


[view class]
exceptionFunction
public:
static IWindow::ExceptionFn* exceptionFunction()

Returns a pointer to the current exception function. If one has not been registered, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleException
public:
virtual bool handleException( IException& dispatcherException, IEvent& exceptionEvent )

Called when the library detects an exception during the dispatch of an event. The default behavior determines if an IWindow::ExceptionFn object has been registered and calls it. Otherwise, false is returned and the exception is thrown again.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setExceptionFunction
public:
static IWindow::ExceptionFn* setExceptionFunction( IWindow::ExceptionFn* exceptionFunction )

Stores an IWindow::ExceptionFn object to be called when an uncaught exception is detected while dispatching window events. If an object has already been registered, the IWindow::ExceptionFn is returned. Otherwise, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Fonts

Use these members to set, reset, and query fonts.


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

Calculates and returns the average character width and maximum character height for the currently set font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the font used by the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetFont
public:
virtual IWindow& resetFont()

Causes the window to disregard a font set by a call to setFont. Following a call to this function, the window uses a default font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

OS/2 Considerations

If a font has been set in the owner window chain, the window inherits the font used by its owner window. Otherwise, the window uses the default system 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


Help Support

Information about using your application can be displayed in help windows using the IHelpWindow class. Each topic of help information is displayed in a help panel that is identified by a number, help ID, that is unique to that application. You can associate each IWindow object in your application with a help panel by either providing a help table to your IHelpWindow object, see IHelpWindow::setHelpTable, or by storing the help panel identifier with each IWindow object.

These functions allow you to set and query the help identifier for this IWindow object.


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

Returns the identifier of the help panel that is to be displayed when help is requested for the window. To display the help panel, you must first associate the frame window containing this window with a help instance. See the IHelpWindow class for more information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setHelpId
public:
IWindow& setHelpId(unsigned long helpTopicId)

Stores the identifier of the help panel that is to be displayed when help is requested for the window. To display the help panel, you must first associate the frame window containing this window with a help instance. See the IHelpWindow class for more information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These members provide utilities used to implement this class.


[view class]
addHandler
protected:
IWindow& addHandler(IHandler* newHandler)

Adds an IHandler object to the window.

Exception

IInvalidParameter The specified handler, newHandler, is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bindMessageQueue
protected:
IWindow& bindMessageQueue(bool bindToMessageQueue = true)

This member function is used to bind this IWindow object to the message queue. A WM_QUIT message is posted to the message queue when the last window bound to the message queue is destroyed. In general, only primary windows like an IFrameWindow should be bound to the message queue. Primary windows are automatically bound to the message queue. A window can be unbound from the message queue by passing a value of false for parameter bindToMessageQueue.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
color

Returns the color value of the specified window area. If the window area has no color set, the area's color is set to the specified default color and the default color is returned. You identify the window area using a system-defined presentation parameter value.

The arguments are the following:

colorArea
The area for which the color is being queried. The values are OS/2 Presentation Manager Toolkit presentation parameters color areas, such as PP_FOREGROUNDCOLOR. It is not limited to these values; you can define your own, but then you must also supply the support for these new values. You can only choose the values referring to RGB colors; you cannot use ones referring to index colors.
defaultColor
If you specify defaultColor and the window area has no color set, this color is returned.

Note: This function is obsolete and may be removed in a future release of the library. The Open Class Library provides this function for backward compatibility only. Instead, you should use the explicit color setting, resetting, and querying functions, such as setBackgroundColor.


Overload 1
protected:
IColor color(unsigned long colorArea) const

Exception

IInvalidRequest A color could not be found for the specified color area.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IColor color( unsigned long colorArea, const IColor& defaultColor ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
create

Calls the graphical presentation system to create a window object.

In the environments where it is used, this function allocates the user data area of the control for Open Class Library use. See reserveUserWindowWord for more information.


Overload 1
protected:
virtual IWindowHandle create( unsigned long id, const char* text, 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 2
protected:
virtual IWindowHandle create( unsigned long id, const char* text, 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 3
protected:
virtual IWindowHandle create( unsigned long id, const char* text, 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 4
protected:
virtual IWindowHandle create( unsigned long id, const char* text, 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 )

Exception

IAccessError The operating system is unable to create the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

You should limit id to values between 0 and 65535. Using other values can give unpredictable results.


[view class]
extendedStyle
protected:
virtual unsigned long extendedStyle() const

Returns an unsigned long representing the window's extended style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isBoundToMessageQueue
protected:
bool isBoundToMessageQueue() const

Returns true if this IWindow object is bound to the message queue.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isPrimaryWindow
protected:
bool isPrimaryWindow() const

If this window has no owner and the parent is the desktop (root) window, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
prepareForUse
protected:
virtual IWindow& prepareForUse( const IWindowHandle& windowHandle )

Prepares this object to use the specified window object (created elsewhere). Typically, this function is called from a wrapper constructor (for example, one that takes only a window handle).

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
removeHandler
protected:
IWindow& removeHandler(IHandler* oldHandler)

Removes a previously added handler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setExtendedStyle
protected:
virtual IWindow& setExtendedStyle( unsigned long extendedStyle )

Sets the window's extended style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStyle
protected:
virtual IWindow& setStyle(unsigned long style)

Sets the window's style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is ignored in AIX. Use the style flags on the constructors for IWindow and derived classes to portably control window styles.


[view class]
setWindowData

Sets the specified window word as an unsigned short or unsigned long. The result indicates whether it was successful.


Overload 1
protected:
IWindow& setWindowData( long index, unsigned short dataValue )

Exception

IAccessError The operating system is unable to set the unsigned short in the window data.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not supported in AIX. Motif widgets do not all have a window word; widgets of type Primitive have a word of user data (XmNuserData), but not all IWindows are based on Primitive widgets. You can use member data of a class you derive from IWindow, use addOrReplaceAttribute , or use adoptWindowData to store information with the window.


Overload 2
protected:
IWindow& setWindowData(long index, unsigned long dataValue)

Exception

IAccessError The operating system is unable to set the unsigned long in the window data.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not supported in AIX. Motif widgets do not all have a window word; widgets of type Primitive have a word of user data (XmNuserData), but not all IWindows are based on Primitive widgets. You can use member data of a class you derive from IWindow, use addOrReplaceAttribute , or use adoptWindowData to store information with the window.


[view class]
style
protected:
virtual unsigned long style() const

Returns an unsigned long representing the window's style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is ignored; it returns 0 always.


[view class]
unbindMessageQueue
protected:
IWindow& unbindMessageQueue()

This member function is used to unbind this IWindow object from the message queue.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
windowULong
protected:
unsigned long windowULong(long index) const

Returns the specified window word as an unsigned long.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not supported in AIX. Motif widgets do not all have a window word; widgets of type Primitive have a word of user data (XmNuserData), but not all IWindows are based on Primitive widgets. You can use member data of a class you derive from IWindow, use addOrReplaceAttribute , or use adoptWindowData to store information with the window.


[view class]
windowUShort
protected:
unsigned short windowUShort(long index) const

Returns the specified window word as an unsigned short.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not supported in AIX. Motif widgets do not all have a window word; widgets of type Primitive have a word of user data (XmNuserData), but not all IWindows are based on Primitive widgets. You can use member data of a class you derive from IWindow, use addOrReplaceAttribute , or use adoptWindowData to store information with the window.


Layout Support

Layout support members supply information used by the canvas classes to provide dialog-like behavior. The virtual functions contain minimal implementations, which can be overridden in derived classes.


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

Passes the query to the IWindow object's parent. The query is passed up the parent chain until IFrameWindow::defaultEmphasisButton is called, returning the window that is stored as the default emphasis button, if one exists.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Passes the query to the IWindow object's parent. The query is passed up the parent chain until IFrameWindow::defaultPushButton is called, returning the window that is stored as the default push button, if one exists.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Passes the default emphasis button to the IWindow object's parent. The default emphasis button is passed up the parent chain until IFrameWindow::setDefaultEmphasisButton is called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Passes the default push button to the IWindow object's parent. The default push button is passed up the parent chain until IFrameWindow::setDefaultPushButton is called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Mouse Pointer Appearance

The mouse pointer can have different appearances, such as an arrow, a hand, or a clock, to indicate the kind of user interaction a window allows. Use these members to set and query the appearance of the mouse pointer when it is positioned over a window.


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

Returns the handle of the mouse pointer used when the mouse is over the window. If the handle is 0, the default mouse pointer is used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMousePointer
public:
virtual IWindow& setMousePointer( const IPointerHandle& mousePointer )

Sets the appearance used by the mouse pointer when it is over the window. If you specify a mouse pointer handle of 0, the default mouse pointer is used.

If the window has child windows, they will also use the mouse pointer you specify, unless they have their own window-specific pointer (for example, set by calling IWindow::setMousePointer).

Overriding IMouseHandler::mousePointerChange also provides a way to set the appearance of the mouse pointer when over a window. Use IWindow::setMousePointer to use the same mouse pointer everywhere within the window. If you need the appearance of the mouse pointer to be dependent on where the pointer is over the window (for example, so that the mouse pointer looks different when it is over the edge of the window than over the rest of the window), use a handler overriding IMouseHandler::mousePointerChange.
Note: Do not use both the IWindow::setMousePointer function and a handler overriding IMouseHandler::mousePointerChange on the same window. Unpredictable results may occur.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function is more efficient on AIX than using a handler overriding IMouseHandler::mousePointerChange.


Mouse Pointer Capture Support

Use these members to query, capture, and release the mouse pointer. If a window has captured the pointer, pointer events are only sent to the window that has captured the pointer, even if the pointer is outside this window. If no window has captured the pointer, mouse events are sent to the window underneath the pointer.


[view class]
capturePointer
public:
virtual IWindow& capturePointer(bool capture = true)

If capture is true, pointer events are sent only to this window even if the pointer is outside of this window. If capture is false, the window releases the pointer capture. If you attempt to capture the pointer when another window currently is capturing the pointer, an exception is thrown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hasPointerCaptured
public:
virtual bool hasPointerCaptured() const

If this window is currently capturing pointer events, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
releasePointer
public:
virtual IWindow& releasePointer()

Causes the window to release the pointer capture (pointer capture is set with the function capturePointer).

This function causes mouse events to again be dispatched to the window underneath the mouse pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Mouse Pointer Positioning

Use these members to set and query the position of the mouse pointer.


[view class]
movePointerTo
public:
static void movePointerTo(const IPoint& position)

Sets the pointer to the point specified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
pointerPosition
public:
static IPoint pointerPosition()

Returns the position of the pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

Use these members to identify and enable notifications sent to observer objects.


[view class]
disableNotification
public:
virtual IWindow& disableNotification()

Causes the window to stop sending notifications to all added observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isEnabledForNotification
public:
virtual bool isEnabledForNotification() const

If the window is sending notifications to observer objects, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
activeColorId
public:
static INotificationId const activeColorId

Notification identifier provided to observers when the active color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
attributeAddReplaceId
public:
static INotificationId const attributeAddReplaceId

Notification identifier provided to observers when an attribute is added or replaced.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
attributeRemoveId
public:
static INotificationId const attributeRemoveId

Notification identifier provided to observers when an attribute is removed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
backgroundColorId
public:
static INotificationId const backgroundColorId

Notification identifier provided to observers when the background color of a window changes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
borderColorId
public:
static INotificationId const borderColorId

Notification identifier provided to observers when the border color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
commandId
public:
static INotificationId const commandId

Notification identifier provided to observers when an IWindow::command event occurs. IWindow provides a pointer to the IEvent in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disabledBackgroundColorId
public:
static INotificationId const disabledBackgroundColorId

Notification identifier provided to observers when the disabled background color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
disabledForegroundColorId
public:
static INotificationId const disabledForegroundColorId

Notification identifier provided to observers when the disabled foreground color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
enableId
public:
static INotificationId const enableId

Notification identifier provided to observers when the keyboard- and mouse-enabled state of the window changes. IWindow provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value will be true if the window is now enabled and false if the window is now disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
focusId
public:
static INotificationId const focusId

Notification identifier provided to observers when the window receives or loses the focus. IWindow provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if the window now has the focus and false if the window just lost the focus.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
fontId
public:
static INotificationId const fontId

Notification identifier provided to observers when the font of a window changes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
foregroundColorId
public:
static INotificationId const foregroundColorId

Notification identifier provided to observers when the foreground color of a window changes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hiliteBackgroundColorId
public:
static INotificationId const hiliteBackgroundColorId

Notification identifier provided to observers when the highlight background color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
hiliteForegroundColorId
public:
static INotificationId const hiliteForegroundColorId

Notification identifier provided to observers when the highlight foreground color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
inactiveColorId
public:
static INotificationId const inactiveColorId

Notification identifier provided to observers when the inactive color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
positionId
public:
static INotificationId const positionId

Notification identifier provided to observers when the position of a window changes. When both the size and position of a window changes, IWindow sends the size change notification first, followed by the position change notification. IWindow provides a pointer to an IPoint object for the new position in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
shadowColorId
public:
static INotificationId const shadowColorId

Notification identifier provided to observers when the shadow color of a window changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
sizeId
public:
static INotificationId const sizeId

Notification identifier provided to observers when the size of a window changes. When both the size and position of a window changes, IWindow sends the size change notification first, followed by the position change notification. IWindow provides a pointer to an ISize object for the new size in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
systemCommandId
public:
static INotificationId const systemCommandId

Notification identifier provided to observers when an IWindow::systemCommand event occurs. IWindow provides a pointer to the IEvent in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
visibleId
public:
static INotificationId const visibleId

Notification identifier provided to observers when the visibility of a window changes. IWindow provides a boolean value in the INotificationEvent::eventData field of the INotificationEvent. This value is true if the window is now visible and false if it is now hidden.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Object Deletion

Use these members to manage the destruction of the window object.


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

If the window object is deleted when a destroy event is dispatched to the window, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the presentation window is destroyed when the window object is deleted, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAutoDeleteObject
public:
IWindow& setAutoDeleteObject(bool autoDelete = true)

Determines whether to delete the IWindow object when the presentation window is destroyed. The deletion occurs when the window system dispatches a destroy event to the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAutoDestroyWindow
public:
IWindow& setAutoDestroyWindow(bool autoDestroy = false)

Determines whether to destroy the presentation window when the IWindow object is deleted. This is used in cases where an IWindow is a wrapper for a presentation window whose creation and destruction are handled outside the C++ object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Observer Notification

Use these members to implement the INotifier protocol for IWindow classes.


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

Enables or disables the window to send notifications to any added observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notifierAddress
public:
virtual INotifierAddress notifierAddress() const

Returns the notifier address.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notifyObservers

Notifies all observers in a part's collection.


Overload 1
public:
virtual IWindow& notifyObservers( const INotificationEvent& event )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
virtual IWindow& notifyObservers( const INotificationId& notification )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notifyObserversAsync
public:
virtual IWindow& notifyObserversAsync( const INotificationEvent& event )

Notifies all observers in a part's collection asynchronously.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addObserver
protected:
virtual IWindow& addObserver( IObserver& observer, const IInterest& interest )

Adds an observer to the part's collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
notificationHandler
protected:
IWindowNotifyHandler* notificationHandler() const

Returns this window's notification handler. If the window does not have a notification handler, 0 is returned. IWindow creates the notification handler when processing the first enableNotification request.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
observerList
protected:
IObserverList& observerList( const IInterest* interest = 0 ) const

Returns the collection of IObservers.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAllObservers
protected:
virtual IWindow& removeAllObservers()

Removes all observers from the part's collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeObserver

Removes an observer from the part's collection.


Overload 1
protected:
virtual IWindow& removeObserver( IObserver& observer, const IInterest& interest )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
virtual IWindow& removeObserver(IObserver& observer)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setNotificationHandler
protected:
IWindow& setNotificationHandler( IWindowNotifyHandler* notifyHandler )

Stores the window's notification handler. This handler captures window events and notifies observers of the window.

If there is already a notification handler stored for this window when you call this function, it deletes the previous handler and stores the new handler specified. Once you call this function, IWindow takes over ownership of the handler object. This includes deleting it when the IWindow object is destructed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Parent and Owner Support

Use these members to query and set a window's relationship and ownership.


[view class]
handleWithParent
public:
static IWindowHandle handleWithParent( unsigned long identifier, const IWindowHandle& parent )

Returns the window handle for the specified window identifier and parent.
Note: This function replaces IWindow::handleWithId.

Exception

IInvalidParameter The specified parent is invalid. You must specify a parent window. To specify the desktop window, use the handle of the window returned by IWindow::desktopWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Motif's equivalent of window IDs are widget names. The Open Class Library has established the convention of numeric IDs (which the library converts to a character string internally) for portability.


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

Returns the window's owner. This function may return 0 if either of the following occurs:

Because a pointer value of 0 can cause unpredictable behavior, check the value of the returned pointer before using it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The Open Class Library keeps track of the owner in an IWindow class data member. Motif does not have owners, only parents. For portability, the Open Class Library has modeled the behavior to simulate owner handling in window systems that do not themselves support it.

Windows Considerations
The Open Class Library keeps track of the owner in an IWindow class data member. Motif does not have owners, only parents. For portability, the Open Class Library has modeled the behavior to simulate owner handling in window systems that do not themselves support it.

[view class]
parent
public:
IWindow* parent() const

Returns the window's parent. This function may return 0 if the following occurs:

Because a pointer value of 0 can cause unpredictable behavior, check the value of the returned pointer before using it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function ensures that the Open Class Library returns the correct parent, even for IWindows consisting of more than one widget combined (for example, IFrameWindow). The library continues up the widget chain until it finds a parent widget that is one of the following:

  • An IWindow
  • The desktopWindow
  • The objectWindow
Use this function instead of XtParent wherever possible.

[view class]
setOwner
public:
virtual IWindow& setOwner(const IWindow* newOwner)

Changes the window's owner.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

In Motif, the Open Class Library keeps track of the owner in an IWindow class data member. Motif does not have owners, only parents. For portability, the Open Class Library has modeled the behavior to simulate owner handling in window systems that do not themselves support it.

Windows Considerations

The owner of a top level control can not be changed after the control has been created. This member function allows changing the owner of a child control within Open Class Library for events that are dispatched up the owner chain.


[view class]
setParent
public:
virtual IWindow& setParent(const IWindow* newParent)

Changes the window's parent.

Exception

IInvalidParameter The specified newParent is invalid. You must specify a nonzero parent window. To specify the desktop window, use the window returned by IWindow::desktopWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

Motif does not support this function. The X Window System does not support any way to re-parent widgets. Re-parenting X windows separately from their widgets, although possible, is considered too dangerous for general use. If you are trying to re-parent a window to effectively hide it, you must use IWindow::hide if you want system-independent, portable code.


Selective Event Processing

Use these members to control whether the event handlers attached to a window receive specific types of events. Receiving all types of events could negatively affect performance, especially receiving all mouse-movement events with the client-server architecture of AIX. However, preventing the handlers of a window from receiving certain types of events may cause the window to lose certain behavior.

AIX Considerations

By default, no windows call their event handlers to process mouse-movement events.

OS/2 Considerations

By default, the event handlers of all windows are enabled to receive all types of mouse events.

Windows Considerations

By default, the event handlers of all windows are enabled to receive all types of mouse events.


[view class]
isHandling
public:
bool isHandling(const EventMask& events) const

Identifies if any event handler objects attached to the window will be called to process any of the specified event types.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
startHandling
public:
IWindow& startHandling(const EventMask& events)

Causes the event handlers attached to the window to be called to process the specified types of events.

This function also increments a count for the event mask(s) in the specified window. Calling IWindow::stopHandling decrements the count. As a result, at least the same number of calls to stopHandling as made to startHandling are needed before the handlers of a window stop receiving the specified events.

Generally you should not need to call this function, because calling IMouseHandler::handleEventsFor (depending on the styles used when calling its constructor) results in calls to this function.

However, you should call startHandling if any of the following are true:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The count for all of the event masks for a window is intially 0.

OS/2 Considerations

The count for all of the event masks for a window is intially 1.

Windows Considerations

The count for all of the event masks for a window is intially 1.


[view class]
stopHandling
public:
IWindow& stopHandling(const EventMask& events)

This function decrements a count for the specified event mask(s) in the specified window. When the count reaches 0, the window no longer calls its handlers to process the specified types of events. However, the window will continue to call IWindow::defaultProcedure to process the specified types of events if it continues to receive them.

Generally you should not need to call this function, because calling IMouseHandler::stopHandlingEventsFor (depending on the styles specified when calling its constructor) results in calls to this function.

However, you should consider calling stopHandling if any of the following are true:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

When the count for an event mask reaches 0 for a window, Open Class Library calls to no longer have the AIX server call the IWindow object to process the event type. This may result in noticable performance improvements, especially with the IWindow::allMouseMoves event mask.

The count for all of the event masks for a window is intially 0.

OS/2 Considerations

Calling this function can cause event handlers that Open Class Library creates and attaches to a window to no longer be called, thus changing the behavior of a window.

The count for all of the event masks for a window is intially 1.

Windows Considerations

Calling this function can cause event handlers that Open Class Library creates and attaches to a window to no longer be called, thus changing the behavior of a window.

The count for all of the event masks for a window is intially 1.


[view class]
allMouseMoves
public:
static const EventMask allMouseMoves

Represents fine-grained events generated each time the user moves the mouse. This value is mutually exclusive with IWindow::someMouseMoves.

You can specify this mask value when calling IWindow::startHandling or IWindow::stopHandling.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Calling IWindow::startHandling with this mask value causes the window to receive more events than it would when using the IWindow::someMouseMoves mask value. The number of mouse-movement events may adversely affect the performance of the window.

OS/2 Considerations

Equivalent to using IWindow::someMouseMoves.

Windows Considerations

Equivalent to using IWindow::someMouseMoves.


[view class]
mouseEntersLeaves
public:
static const EventMask mouseEntersLeaves

Represents the events notifying when the mouse pointer crosses into and crosses out of a window.

You can specify this mask value when calling IWindow::startHandling or IWindow::stopHandling.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
someMouseMoves
public:
static const EventMask someMouseMoves

Represents course-grained events generated each time the user moves the mouse. This value is mutually exclusive with IWindow::allMouseMoves.

You can specify this mask value when calling IWindow::startHandling or IWindow::stopHandling.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Calling IWindow::startHandling with this mask value causes the window to receive fewer events than it would when using the IWindow::allMouseMoves mask value.

OS/2 Considerations

Equivalent to using IWindow::allMouseMoves.

Windows Considerations

Equivalent to using IWindow::allMouseMoves.


Sibling Order

Use these members to 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 top window. Cursor tabbing occurs from the top sibling and proceeds to the bottom window.


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

Returns the order in which the library creates the new windows relative to their sibling windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
positionBehindSibling
public:
virtual IWindow& positionBehindSibling( const IWindowHandle& siblingWindow )

Puts this window in the Z-order behind the specified sibling window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
positionBehindSiblings
public:
virtual IWindow& positionBehindSiblings()

Puts this window in the Z-order behind all its sibling windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
positionOnSiblings
public:
virtual IWindow& positionOnSiblings()

Puts this window in the Z-order on top of all its sibling windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Determines whether new windows are created on top of their sibling windows or behind them. By default, the library creates windows behind their siblings. If you call this function using the enumerator IWindow::onTopOfSiblings, the library creates new windows on top of their siblings.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide a set of valid styles for the IWindow class. Use these members to set and query window styles.


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

Returns an IArgList that is created from the specified styles. IWindow::create uses the IArgList object to create the 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 a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
clipChildren
public:
static const Style clipChildren

Excludes the area occupied by the children of the window when drawing in the window. Child windows are always clipped to their parent window. When the system paints a parent window, this style controls whether the invalidated region of the parent window includes the area occupied by its children, thus preventing a window from painting over its child windows.
Note: Do not use this style for the parent of an IComboBox that already has the style simpleType.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
clipSiblings
public:
static const Style clipSiblings

When the library displays multiple siblings, this style controls which sibling window the library displays on top. Sibling windows are windows that share the same parent window. Assign this style to the sibling window that the library should display on top of the other siblings, in Z-order.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
clipToParent
public:
static const Style clipToParent

Allows a window to paint outside of its window boundary up to the window boundary of its parent.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
disabled
public:
static const Style disabled

Specifies that keyboard and mouse input are no longer dispatched to the window, preventing the window from being used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
group
public:
static const Style group

Identifies the window as being the first in a group. Windows in a group are sibling windows consecutively ordered by sibling order. You can navigate between windows in a group using the keyboard arrow keys. Moving forward from the last window in the group causes the input focus to return to the first window in the group. Moving backward from the first window in the group causes the input focus to return to the last window in the group.

Groups also define some behavior for radio buttons and check boxes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This style does has no affect on cursoring between windows. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
leftToRight
public:
static const Style leftToRight

Specifies that the text and layout of a window will have a left-to-right appearance. Use of this style takes precedence over application-level bidirectional characteristics that you can set with IBidiSettings::setApplicationDefaults.

If a window is created without this style or IWindow::rightToLeft, its direction is determined as follows:

Do not create a window with both this style and IWindow::rightToLeft.

This style is ignored if IBidiSettings::isBidiSupported returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noStyle
public:
static const Style noStyle

Sets all styles off.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightToLeft
public:
static const Style rightToLeft

Specifies that the text and layout of a window will have a right-to-left appearance. Use of this style takes precedence over application-level bidirectional characteristics that you can set with IBidiSettings::setApplicationDefaults.

If a window is created without this style or IWindow::leftToRight, its direction is determined as follows:

Do not create a window with both this style and IWindow::leftToRight.

This style is ignored if IBidiSettings::isBidiSupported returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
saveBits
public:
static const Style saveBits

Optimizes the painting of a window by saving the screen image of the area under the window as a bitmap and then using the bitmap to redraw the window when necessary.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
synchPaint
public:
static const Style synchPaint

Synchronously repaints the window. Without this style, painting only occurs if there are no other events waiting to be processed.
Note: The only way to turn off this style is to call the protected member function IWindow::setStyle to reset it after you create the window.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
tabStop
public:
static const Style tabStop

Identifies the window as one the user can move the input focus to using the Tab key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This style does has no affect on tabbing between windows. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
visible
public:
static const Style visible

Causes the window to be visible. In general, controls are constructed as visible and frame windows as invisible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Tab Stops and Groups

Tab stops and groups define how the input focus is moved between windows when the user presses the Tab or cursor arrow keys. These settings, however, typically have effect only for child windows of a canvas or frame window.

AIX Considerations

These members have no affect on cursor movement. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
disableGroup
public:
virtual IWindow& disableGroup()

Removes the group setting from the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function has no effect on cursoring between windows. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
disableTabStop
public:
virtual IWindow& disableTabStop()

Identifies the window as one the user cannot move the input focus to using the Tab key. Calling this function does not necessarily prevent the user from moving the input focus to the window using the mouse or cursor arrow keys, however.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function has no effect on tabbing between windows. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
enableGroup
public:
virtual IWindow& enableGroup(bool enable = true)

Identifies the window as being the first in a group. Windows in a group are sibling windows consecutively ordered by sibling order. You can navigate between windows in a group using the keyboard arrow keys. Moving forward from the last window in the group causes the input focus to return to the first window in the group. Moving backward from the first window in the group causes the input focus to return to the last window in the group.

Groups also define some behavior for radio buttons and check boxes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function has no effect on cursoring between windows. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
enableTabStop
public:
virtual IWindow& enableTabStop(bool enable = true)

Identifies the window as one the user can move the input focus to using the Tab key.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function has no effect on tabbing between windows. The Motif operating environment determines how the input focus is changed via the keyboard.


[view class]
isGroup
public:
virtual bool isGroup() const

If the control has the group style set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function always returns false.


[view class]
isTabStop
public:
virtual bool isTabStop() const

If the user can tab to the window, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function always returns false.


Window Attributes

Use these member functions for adding and removing window attributes. An attribute must be derived from IAttribute and is attached to an IWindow object with a name associated with it. The name can then be used later when retrieving the attribute. These members make it convenient to add attributes to an IWindow object without having to store the attribute as member data.


[view class]
addOrReplaceAttribute
public:
IWindow& addOrReplaceAttribute( const IAttributeName& name, const IAttribute& attribute )

Adds the attribute to the attribute cursor associated with the IWindow object. The name of the attribute must be unique per IWindow object. If an attribute with the specified name already exists then the attribute is replaced.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
attributeNameAt
public:
IAttributeName attributeNameAt( const AttributeCursor& cursor ) const

Returns the name of the attribute at the cursor position of the specified cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
attributeWithName
public:
const IAttribute* attributeWithName( const IAttributeName& name, ESearchType search = kWindowOnly ) const

Returns the attribute with the specified name. There are two search methods available. kWindowOnly will look for the attribute on the current IWindow object only, and kWindowAndParents will search for the attribute starting at the current IWindow object and continue up the parent chain. The first match found is the attribute that will be returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAllAttributes
public:
IWindow& removeAllAttributes()

Removes all attributes from the current IWindow object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAttribute
public:
IWindow& removeAttribute(const IAttributeName& name)

Removes the attribute with the attribute name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Enablement

Use these members to enable and disable a window and to determine the enablement of a window.


[view class]
disable
public:
virtual IWindow& disable()

Prevents keyboard and mouse input from being sent to the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the window is sent mouse and keyboard input, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Painting

Use these members to display a window and determine the visibility of a window.


[view class]
disableUpdate
public:
virtual IWindow& disableUpdate()

Prevents changes to a window from being drawn on the screen. Typically, you can use this function to make a series of changes to a window without displaying each change as it is made. Call IWindow::show to allow changes to draw on the screen. Do not destroy a window while it is in the update-disabled state. If you do, the library will not remove the destroyed window from the screen.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Motif ignores this function, because the X Window System is designed to avoid the need to disable or enable during most complex drawing.


[view class]
enableUpdate
public:
virtual IWindow& enableUpdate(bool enableWindow = true)

Enables or disables drawing changes to a window on the screen. Note that calling enableUpdate on a hidden window will cause that window to be shown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hide
public:
virtual IWindow& hide()

Hides the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hideSourceEmphasis
public:
virtual IWindow& hideSourceEmphasis()

Called by a pop-up menu handler to notify the window to remove pop-up menu emphasis. The library provides this function so that derived classes needing to remove pop-up menu emphasis can override it. The default behavior of IWindow is to do nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns a rectangle that indicates the invalidated rectangle for the window. This information is used during the processing of a paint message, typically during IPaintHandler::paintWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
invalidatedRegion
public:
virtual IRegionHandle invalidatedRegion() const

Returns a region that indicates the invalidated region for the window. This information is used during the processing of a paint message, typically during IPaintHandler::paintWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If any part of the window is showing, true is returned. Otherwise, false is returned.
Note: A window can be visible and yet not be showing if it is covered by another window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

If the window is in the update-disabled state, false is returned.

Windows Considerations

This function returns the same result as isVisible.


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

Returns true if update is enabled, see IWindow::enableUpdate and IWindow::disableUpdate.

Note that this member function only returns the update status for the object queried. The call does not check the update status of the parent objects.

The canvas classes use this function to determine whether or not to run their layout routines.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the window's style is set to visible, true is returned. Otherwise, false is returned.
Note: A window can have the style visible and yet not be showing if it is covered by another window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
presSpace
public:
virtual IPresSpaceHandle presSpace() const

Acquires and returns the presentation space handle (also known as graphics context, or GC) for the window.

Exception

IAccessError The operating system is unable to allocate a presentation space for the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function returns a writable graphics context (GC) for this widget, as returned by the Xlib function XCreateGC. If there has been a prior call to this function (without an intervening call to releasePresSpace), an existing GC is returned. This allows various client functions to draw using a shared GC so that line styles, fonts, and so forth are uniform. If this is not the behavior you want, you can create your own GC using X functions.


[view class]
refresh

Invalidates or updates all or part of the window.


Overload 1
public:
virtual IWindow& refresh(RefreshType type = paintAll)

Invalidates or updates all or part of the window, depending on the state of the type parameter. If type is set to IWindow::paintAll, then the entire window is invalidated. Painting may or may not occur before the call returns. If type is set to IWindow::immediate, then the current invalidated area of the window is painted. Painting is completed before the call returns. If type is set to IWindow::paintAllImmediate, the entire window is invalidated and then painted. Painting is completed before the call returns.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IWindow& refresh( const IRectangle& invalidRectangle, bool immediate = false )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
releasePresSpace
public:
virtual void releasePresSpace( const IPresSpaceHandle& presentationSpaceHandle ) const

Releases the window's presentation space handle.

Exception

IInvalidRequest. The operating system is unable to deallocate the presentation space.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This function frees the graphics context (GC), previously obtained via presSpace, using XtFreeGC. The GC freed by this function is shared, so it might not be freed until other client functions have also called releasePresSpace. See presSpace for details. If this is not the behavior you want, you can create your own GC using X-toolkit functions and free it using XtFreeGC.


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

Makes the window visible.
Note: Another window occurring earlier in the Z-order might still obscure this window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
showSourceEmphasis
public:
virtual IWindow& showSourceEmphasis(bool show = true)

Called by a pop-up menu handler to notify the window to draw pop-up menu emphasis. The library provides this function so that derived classes needing to remove pop-up menu emphasis can override it. The default behavior of IWindow is to do nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
validateRect
public:
virtual IWindow& validateRect( const IRectangle& validatedRectangle )

Allows validating a portion or all of the invalidated region. This is useful if several handlers are used to perform the drawing of an invalidated region. Each handle can validate the portion that was drawn and return false from the handler so the event is then dispatched to other handlers attached to the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
validateRegion
public:
virtual IWindow& validateRegion( const IRegionHandle& validatedRegion )

Allows validating a portion or all of the invalidated region. This is useful if several handlers are used to perform the drawing of an invalidated region. Each handle can validate the portion of the window that was drawn and return false from the handler. This will allow the event to then be dispatched to other handlers attached to the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Positioning

Use these members to set and query the size and position of windows. Unless otherwise noted, the orientation of the coordinates accepted and returned by these members is the application orientation. For more information about coordinate orientation, see ICoordinateSystem.


[view class]
mapPoint
public:
static IPoint mapPoint( const IPoint& point, const IWindowHandle& from, const IWindowHandle& to )

Maps a point from one window's coordinate space to another's, such as mapping from screen coordinates to window coordinates.
Note: This is a static function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
moveSizeTo
public:
virtual IWindow& moveSizeTo( const IRectangle& newSizeAndPosition )

Changes the position and size of the window.
Note: If you override moveSizeTo, moveTo, or sizeTo, you should call the inherited version of the function you override during your processing. Since these functions are implemented in terms of each other in some environments, you could cause recursion if, for example, you implement part of your version of moveSizeTo by calling IWindow::moveTo and IWindow::sizeTo. Instead, perform your processing and then call IWindow::moveSizeTo.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

When this member function is invoked on an IFrameWindow object the requested position is a suggestion to the window manager. The actual position of the IFrameWindow object is usually slighty off from the requested position.


[view class]
moveTo
public:
virtual IWindow& moveTo(const IPoint& newPosition)

Changes the position of the window.
Note: If you override moveSizeTo, moveTo, or sizeTo, you should call the inherited version of the function you override during your processing. Since these functions are implemented in terms of each other in some environments, you could cause recursion if, for example, you implement part of your version of moveSizeTo by calling IWindow::moveTo and IWindow::sizeTo. Instead, perform your processing and then call IWindow::moveSizeTo.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

When this member function is invoked on an IFrameWindow object the requested position is a suggestion to the window manager. The actual position of the IFrameWindow object is usually slighty off from the requested position.


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

Returns a rectangle representing the position and size of the window. Unlike IWindow::rect, this function always returns the position in the native GUI orientation.
Note: This function returns IRectangle(0,0,0,0) for a frame window if it is constructed using the shell position and the window has not been shown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
parentSize

Returns an ISize object representing the size of the client rectangle in the parent window. The client rectangle is the coordinate space used by child windows to specify their location. If the current window or parent is determined to be the desktop, the size of the desktop is returned.


Overload 1
public:
virtual ISize parentSize() const

Returns the size of the parent of this window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
static ISize parentSize(const IWindowHandle& windowHandle)

Returns the size of the parent window of the window with the handle windowHandle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
position
public:
virtual IPoint position() const

Returns the position of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns a rectangle representing the position and size of the window. If the application uses a different coordinate orientation than the window system orientation, this function converts from native window system coordinates to the application orientation. Refer to ICoordinateSystem for information about coordinate orientation.
Note: This function returns IRectangle(0,0,0,0) for a frame window if it is constructed using the shell position and the window has not been shown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the size of the window in window coordinates.
Note: This function returns ISize(0,0) for a frame window if it is constructed using the shell position and the window has not been shown.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizeTo
public:
virtual IWindow& sizeTo(const ISize& newSize)

Changes the size of the window.
Note: If you override moveSizeTo, moveTo, or sizeTo, you should call the inherited version of the function you override during your processing. Since these functions are implemented in terms of each other in some environments, you could cause recursion if, for example, you implement part of your version of moveSizeTo by calling IWindow::moveTo and IWindow::sizeTo. Instead, perform your processing and then call IWindow::moveSizeTo.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IWindow - Enumerations


[view class]
ESearchType
enum ESearchType { kWindowOnly, 
                   kWindowAndParents }

Use these enumerators to specify search type when looking up attributes:

kWindowOnly
Searches the current IWindow object only.
kWindowAndParents
Searches the current IWindow object and then continues up the parent chain.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
EventType
enum EventType { command=1, 
                 systemCommand, 
                 control, 
                 help, 
                 character }

Use these enumerators to specify windowing system message identifiers:

command
Specifies the user command event type.
systemCommand
Specifies the system command event type.
help
Specifies the help event type.
character
Specifies the key character event type.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The EventType values map to the following system defined messages:

command
WM_COMMAND. For processing by a command handler, parameter 2 must be 0. Non zero values for parameter 2 are defined by the operating system.
systemCommand
WM_SYSCOMMAND.
help
WM_HELP.
character
WM_CHAR.

[view class]
Layout
enum Layout { windowCreated=1, 
              colorChanged=2, 
              sizeChanged=4, 
              minimumSizeChanged=8, 
              childMinimumSizeChanged=16, 
              fontChanged=32, 
              fontPropogated=64, 
              layoutChanged=128, 
              immediateUpdate=256, 
              childWindowCreated=512, 
              windowDestroyed=1024, 
              childWindowDestroyed=2048 }

Use the preceding enumerators to specify window layout values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
RefreshType
enum RefreshType { paintAll, 
                   immediate, 
                   paintAllImmediate }

Use these enumerators to specify the refresh type when updating a window using refresh.

paintAll
Invalidates the entire window. Painting occurs as part of the normal screen update processing provided by the operating system.
immediate
Causes a synchronous paint of the current invalidated region of the window. This means painting is complete when refresh returns.
paintAllImmediate
Causes a synchronous paint of the entire window. This means painting is complete when refresh returns.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
SiblingOrder
enum SiblingOrder { onTopOfSiblings, 
                    behindSiblings }

Use these enumerators to specify the sibling order of newly created windows:

onTopOfSiblings
Creates new windows on top of their sibling windows.
behindSiblings
Creates new windows behind their sibling windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IWindow - Type Definitions


[view class]
DataHandle
typedef unsigned long DataHandle

Handle for accessing window data. See dataHandleWithKey.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IWindow - Inherited Member Functions and Data

Inherited Public Functions

INotifier

Inherited Public Data

INotifier

Inherited Protected Functions

INotifier

Inherited Protected Data