ITitle

The ITitle class creates and updates the title bar area of your frame window. The ITitle class consists of the following three components:

When you construct a title, you must provide the object text, while the other two are optional. The Open Class Library separates the object text and view text with a hyphen (-). The library separates the view text and view number with a colon (:). For example:

OS/2 System - Icon View:2
Use ITitle if you want the Common User Access (CUA) support for the object, view, and view number. If you do not, you can specify a title using an IFrameWindow constructor.

OS/2 Considerations

While a title may exceed 60 bytes in length, only the first 60 bytes appear in a Window List entry. See the function IFrameWindow::addToWindowList for information on adding entries to the window list.

Only one ITitle object is supported for each IFrameWindow object. The construction of the second ITitle object for the same IFrameWindow object will result in an IInvalidParameter exception.

Windows Considerations

Because ITitle is not a separate window in the Windows operating system, the mechanism of autoDeleteObject (which deletes the object when the window is deleted) does not occur because there is no window being deleted. Therefore, do not use autoDeleteObject but instead perform your own delete's of the objects that your application creates using new.


ITitle - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ITitle


Overload 1
public:
ITitle( IWindow* owner, const IResourceId& objectName, const IResourceId& viewName = 0, unsigned long viewNumber = 0 )

Use this function to construct ITitle objects from IResourceIds of STRINGTABLE items.

Exception

.* This exception actually thrown in static function private to class.

IInvalidRequest The owner window of the ITitle object does not have a title bar. Make sure you have specified the correct owner window for the constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
ITitle( IWindow* owner, const char* objectName = 0, const char* viewName = 0, unsigned long viewNumber = 0 )

Use this function to construct ITitle objects from char*.

Exception

.* This exception actually thrown in static function private to class.

IInvalidRequest The owner window of the ITitle object does not have a title bar. Make sure you have specified the correct owner window for the constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

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


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

Returns the window handle.

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]
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


Colors

Use these members to query and set colors of the title area. You can query and set the active and inactive colors of the title area. You can query, set, and reset the active and inactive colors of the title's text foreground or background. You can query the border color of the title area.


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

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

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default active color value of the title area.


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

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

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default active text background color value of the title area.


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

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

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default active text foreground color value of the title area.


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

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

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default inactive color value of the title area.


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

Returns the inactive text background color value of the title area. If you have not set the color for the area, the default is returned.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default inactive text background color value of the title area.


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

Returns the inactive text foreground color value of the title area. If you have not set the color for the area, the default is returned.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Windows Considerations

Returns the default inactive text foreground color value of the title area.


[view class]
resetActiveTextBackgroundColor
public:
virtual ITitle& resetActiveTextBackgroundColor()

Resets the active text background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetActiveTextForegroundColor
public:
virtual ITitle& resetActiveTextForegroundColor()

Resets the active text foreground color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetInactiveTextBackgroundColor
public:
virtual ITitle& resetInactiveTextBackgroundColor()

Resets the inactive text background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
resetInactiveTextForegroundColor
public:
virtual ITitle& resetInactiveTextForegroundColor()

Resets the inactive text foreground color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
setActiveTextBackgroundColor
public:
virtual ITitle& setActiveTextBackgroundColor( const IColor& color )

Sets the active text background 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]
setActiveTextForegroundColor
public:
virtual ITitle& setActiveTextForegroundColor( const IColor& color )

Sets the active text foreground 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]
setInactiveTextBackgroundColor
public:
virtual ITitle& setInactiveTextBackgroundColor( const IColor& color )

Sets the inactive text background 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]
setInactiveTextForegroundColor
public:
virtual ITitle& setInactiveTextForegroundColor( const IColor& color )

Sets the inactive text foreground 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


Notification Members

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


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

Enables the title to send notifications to any added observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
activeTextBackgroundColorId
public:
static INotificationId const activeTextBackgroundColorId

Notification identifier provided to observers when the active text background color of the title changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
activeTextForegroundColorId
public:
static INotificationId const activeTextForegroundColorId

Notification identifier provided to observers when the active text foreground color of the title changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
inactiveTextBackgroundColorId
public:
static INotificationId const inactiveTextBackgroundColorId

Notification identifier provided to observers when the inactive text background color of the title changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
inactiveTextForegroundColorId
public:
static INotificationId const inactiveTextForegroundColorId

Notification identifier provided to observers when the inactive text foreground color of the title changes.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
objectTextId
public:
static INotificationId const objectTextId

Notification identifier provided to observers when the object text of the title changes. ITitle provides a pointer to the new text string in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
viewNumberId
public:
static INotificationId const viewNumberId

Notification identifier provided to observers when the view number of the title changes. ITitle provides the new view number in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
viewTextId
public:
static INotificationId const viewTextId

Notification identifier provided to observers when the view text of the title changes. ITitle provides a pointer to the new text string in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text Processing

Use these members to manage the title's text. You can query and set the text as well as query the length of the text of the title.

AIX Considerations

These functions were overloaded in Motif because of the Motif Window Manager. The title is a resource of the Motif Window Manager and not a separate control. Therefore there is not a valid handle for ITitle.


[view class]
setText

Sets the title text.


Overload 1
public:
virtual ITitle& setText(const char* text)

Use this function to set the title's text using a char*.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITitle& setText(const IResourceId& textResId)

Use this function to set the title's text using an IResourceId.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the title text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the current length of the title text, in bytes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Title Components

Use these members to query and set the title's components. You can set and query the text for the object or view. You can set and query the view number.


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

Returns the object text.

Exception

.* This exception actually thrown in static function private to class.

IInvalidRequest The owner window of the ITitle object does not have a title bar. Make sure you have specified the correct owner window for the constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setObjectText

Sets the object text.
Note: This function enforces the guideline that every window have a title. Therefore, you cannot use this function to put a null string in a frame window title. If you need to use a null string for a frame window title, call ITextControl::setText instead of this function.


Overload 1
public:
virtual ITitle& setObjectText(const char* objectName)

Use this function to set the object text using a char*.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITitle& setObjectText( const IResourceId& objectNameResId )

Use this function to set the object text from a string table ID from a specified resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTitleText

Sets all three components of a title (object text, view text, and view number) at once.


Overload 1
public:
virtual ITitle& setTitleText( const char* objectName, const char* viewName = 0, unsigned long viewNum = 0 )

Use this function to set the object name and view name using character strings.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITitle& setTitleText( const IResourceId& objectNameResId, const IResourceId& viewNameResId = 0, unsigned long viewNum = 0 )

Use this function to load the object and view text from a specified resource ID and resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setViewNumber
public:
virtual ITitle& setViewNumber(unsigned long viewNumber)

Sets the view number.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setViewText

Sets the view text.


Overload 1
public:
virtual ITitle& setViewText(const char* viewName)

Use this function to set the view text using a char*.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITitle& setViewText( const IResourceId& viewNameResId )

Use this function to set the view text from a string table ID from a specified resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the view number.

Exception

.* This exception actually thrown in static function private to class.

IInvalidRequest The owner window of the ITitle object does not have a title bar. Make sure you have specified the correct owner window for the constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the view text.

Exception

.* This exception actually thrown in static function private to class.

IInvalidRequest The owner window of the ITitle object does not have a title bar. Make sure you have specified the correct owner window for the constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Positioning

Use these members to 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]
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
public:
virtual ISize parentSize() const

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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITitle - Inherited Member Functions and Data

Inherited Public Functions

IControl
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
ITextControl

Inherited Protected Functions

IWindow
INotifier
IControl
ITextControl

Inherited Protected Data