ITabPage

An ITabPage object represents a tab control page. You must use objects of this class in conjunction with an ITabControl object. Refer to the ITabControl class for additional information.

You need to construct ITabPage objects or objects of derived classes to manage the windows and attributes associated with a tab control page. The windows associated with the tab page include the page window and optional tab page buttons. The tab page attributes include the tab text, tab bitmap, and tab background color.

After constructing the ITabPage, you must add it to an ITabControl. Use the member functions described in ITabControl Page Addition to add an ITabPage to an ITabControl.

When you add an ITabPage object to a tab control, a tab and page window area are displayed for the tab page. You must set the window to be displayed in the page window area. You can set this page window at any time by calling the setPageWindow member function. Alternatively, you can implement delayed page window creation by overriding the createPageWindow member function in a class derived from ITabPage. The Open Class Library calls createPageWindow when the page is first displayed. Your override must construct and return a pointer to the IWindow object to be used for the page window. You can also add page specific push buttons in your createPageWindow override.

You can implement page window validation by overriding the validatePageWindow member function in a derived class. The Open Class Library calls this member function whenever a new page is selected in the tab control. Your override can prevent the page selection from completing if the page window validation fails.

You can update the page window of a newly selected tab page by overriding the updatePageWindow member function in a derived class. The Open Class Library calls this member function after a page selection has occurred.

The other windows associated with a tab page are the optional page specific buttons. These page buttons are visible in the tab control's button area when the tab page is the top page. Use the member functions described in Button Support to manage page buttons. To process the command events generated by tab control buttons, create a handler of an ICommandHandler derived class and attach it to either the tab control or frame window.

If you want to display page specific help when the input focus is on a tab, set the help panel for a tab page with the setHelpId member function. You do not need to specify the page specific help panel in a help subtable.

AIX Considerations

This class is not supported in the AIX environment.


ITabPage - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

The page window object for this page is not deleted by this destructor. The presentation page window is destroyed when its parent window is destroyed. If you allocated the page window object with the operator new, either use IWindow::setAutoDeleteObject to automatically delete the page window object or explicitly delete the page window object in the destructor of your ITabPage subclass.

Similarly, if you create and add custom IPushButton objects as page buttons, the presentation windows are destroyed when the button parent is destroyed. If you allocated these page buttons with the operator new, either enable automatic object deletion of these buttons or explicitly delete the page buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
ITabPage


Overload 1
public:
ITabPage(const Style& style = defaultStyle ( ))

Constructs an ITabPage object by specifying a style for the tab page.

style
The style of this tab page. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
ITabPage( const IBitmapHandle& tabBitmap, const Style& style = defaultStyle ( ) )

Constructs an ITabPage object by specifying a tab bitmap and a style for the tab page.

tabBitmap
The handle for the bitmap that appears on the tab when this page is added to an ITabControl object.
style
The style of this tab page. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 3
public:
ITabPage( const IText& tabText, const IBitmapHandle& tabBitmap, const Style& style = defaultStyle ( ) )

Constructs an ITabPage object by specifying tab text, a tab bitmap, and a style for the tab page.

tabText
The text that appears on the tab when this page is added to an ITabControl object.
tabBitmap
The handle for the bitmap that appears on the tab when this page is added to an ITabControl object.
style
The style of this tab page. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

OS/2 Considerations

Tab text and a tab bitmap cannot be displayed simulaneously on tabs in the OS/2 environment. If you use this constructor, only the tab bitmap is displayed.


Overload 4
public:
ITabPage( const IText& tabText, const Style& style = defaultStyle ( ) )

Constructs an ITabPage object by specifying the tab text and a style for the tab page.

tabText
The text that appears on the tab when this page is added to an ITabControl object.
style
The style of this tab page. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Automatic Sizing

Use the following member to query whether the page window for this tab page is automatically sized by the tab control to fill the entire area for page window display.


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

Returns true if the autoPageSize style is set for this tab page.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Button Support

ITabControl objects constructed with the ITabControl::buttons style manage an area for push buttons. These push buttons are either specific to one page in the tab control or they are common to all of the pages in the tab control that do not have any page specific buttons. Use the following member functions to manage the page specific tab control buttons. Refer to the ITabControl class for additional information related to common buttons.


[view class]
addPageButton

Adds a page button to the sequence of buttons for this tab page. The push buttons for this page appear in the button area in the order they were added as page buttons.

A push button can be added to both the tab control common buttons and one or more sequences of page specific buttons. Use the member functions in ITabControl Button Support to add tab control common buttons.


Overload 1
public:
ITabPage& addPageButton( ITabControl::EButton buttonType, bool isDefaultButton = false )

Adds one of the push buttons provided by the ITabControl::EButton enumeration as a page specific button.

buttonType
Use one of the enumerators defined by the ITabControl::EButton enumeration to specify which push button to add.
isDefaultButton
Indicates whether this push button is to be the initial default button when the buttons for this page are displayed. Subsequent specification of a default button replaces this button as the default. This parameter is optional.

Exception

IInvalidRequest The tab control was not constructed with the buttons style.
IInvalidRequest A button of the specified buttonType was already been added to the page buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
ITabPage& addPageButton(IPushButton* button)

Adds an IPushButton object constructed by the application as a page specific button. You must use the window returned by ITabControl::buttonParent as the parent of any page specific buttons you construct. Note that the push button styles, including IPushButton::defaultButton, are effective if set on the IPushButton. The last default push button added is the actual default when the buttons for this page are displayed.

Exception

IInvalidParameter button must be a nonzero pointer.
IInvalidRequest The tab control was not constructed with the buttons style or the button parent is not the window returned by ITabControl::buttonParent.
IInvalidRequest The specified button has already been added to the page buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
removePageButton

Removes a page specific button from the button sequence for this tab page.


Overload 1
public:
ITabPage& removePageButton(IPushButton* button)

Removes an IPushButton object constructed by the application and previously added as a page button.

Exception

IAccessError The specified button was not present in the page button sequence.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
ITabPage& removePageButton(ITabControl::EButton buttonType)

Removes one of the predefined push buttons from the sequence of buttons for this page.

buttonType
Use one of the enumerators defined by the ITabControl::EButton enumeration to specify which push button to remove.

Exception

IAccessError A standard button for the specified buttonType was not present in the page button sequence.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Colors

Use these members to query, set, and reset the tab background color.


[view class]
resetTabBackgroundColor
public:
virtual ITabPage& resetTabBackgroundColor()

Resets the tab background color by changing to the tab background color that was previously set.

Supported Platforms

Windows OS/2 AIX
Ignored Yes No

Windows Considerations

The tab background color cannot be changed for tab controls in the Windows environment. This member function has no effect in that environment.


[view class]
setTabBackgroundColor
public:
virtual ITabPage& setTabBackgroundColor( const IColor& color )

Sets the tab background color for this tab page.

Supported Platforms

Windows OS/2 AIX
Ignored Yes No

Windows Considerations

The tab background color cannot be changed for tab controls in the Windows environment. This member function has no effect in that environment.


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

Returns the tab background color for this tab page.

Supported Platforms

Windows OS/2 AIX
Ignored Yes No

Windows Considerations

The tab background color cannot be changed for tab controls in the Windows environment. This member function returns the default tab background color in that environment.


Help Support

Use the following members to set or query the identifier for the help panel that is to be displayed when contextual help is requested while focus is on the tab for this page. In order for the help panel to be displayed, the frame window containing this tab control must be associated with a help instance. See the IHelpWindow class for more information.


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

Returns the identifier of the help panel that is displayed when contextual help is requested while focus is on the tab for this page.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setHelpId
public:
virtual ITabPage& setHelpId(unsigned long helpId)

Sets the identifier of the help panel that is displayed when contextual help is requested while focus is on the tab for this page.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Layout Support

The layout support member is used during tab control minimum size calculation.


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

You should override this member if you want to provide a minimum page window size for this page prior to setting the page window. This is useful for setting a minimum page window size when you use delayed page window creation. The page window size returned from minimumPageWindowSize is used to calculate the minimum tab control size. The default implementation returns either the page window's minimum size or a default size if the page window has not been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Page Window Association

Use these members to query and associate the application page window for this tab page.


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

Returns the current page window for this page.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setPageWindow
public:
virtual ITabPage& setPageWindow(IWindow* pageWindow)

Sets the application page window for this tab page. Construct the page window with the tab control as its parent. You can construct and set an application page window in the ITabPage prior to adding the tab page to the tab control.

Exception

IInvalidParameter pageWindow must be a nonzero pointer.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
createPageWindow
protected:
virtual IWindow* createPageWindow()

Override this member function if you want to implement delayed page window construction. This function is called by the Open Class Library when this page becomes the topmost page and the page window has not been set. You must construct and return a pointer to the page window in your createPageWindow override. You can also construct and set page specific buttons in your createPageWindow override. The default implementation does nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Page Window Selection

Override the following members to implement page window content validation and to update page window content during page selections.


[view class]
validatePageWindow
public:
virtual bool validatePageWindow()

Override this member function in a derived class to perform validity checking of the application page window contents. The Open Class Library calls this function when a new tab page is selected. If the validity check on the page window contents fails, return false from your validatePageWindow override to prevent the page selection from continuing. Return true from your validatePageWindow override if the validation succeeds.


Note: The Open Class Library calls this member function for page selection only. It does not call validatePageWindow in response to command events generated by tab control buttons. Call this function directly from your command handler when validation of the top page window contents is necessary.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
updatePageWindow
protected:
virtual void updatePageWindow()

Override this function if you want to update the page window contents when this page is selected. The Open Class Library calls this member function following a page selection if a page window has been set for the page. The default implementation of updatePageWindow does nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Styles

These style members provide a set of valid styles for this class. Use these members to query and set the tab control styles.


[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 No


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

Returns the current default style. The default style is classDefaultStyle unless you have changed the style by using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Sets the default style for all subsequently constructed tab controls.

style
Use the styles provided by ITabPage::Styles to specify the default style.

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

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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
autoPageSize
public:
static const Style autoPageSize

Indicates that the page window for this page is automatically sized by its associated tab control. The page window is sized to fit the entire area available for page window display.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is ITabPage::autoPageSize.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
noStyle
public:
static const Style noStyle

Sets all styles off.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Tab Control Association

Use this member to query the ITabControl object to which this tab page has been added.


[view class]
tabControl
public:
virtual ITabControl* tabControl() const

Returns the tab control for this tab page. If the tab page has not yet been added to a tab control, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Tab Text & Bitmap

Use these members to set and query the tab text or bitmaps for the tab page.

OS/2 Considerations

This environment does not support the simultaneous display of text and a bitmap in an individual tab. Only the last of these attributes set will appear on the tab. Both the text and the bitmap reference will be stored in the ITabPage and each will be returned if queried.


[view class]
setTabBitmap

Sets the bitmap to be displayed in the tab for this page.


Overload 1
public:
virtual ITabPage& setTabBitmap(const IBitmapHandle& bitmap)

bitmap
Reference to the handle of the bitmap to be used.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
virtual ITabPage& setTabBitmap( const IResourceId& resourceId )

resourceId
Reference to a resource identifier object that identifies the bitmap to be used.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setTabText

Sets the text to be displayed in the tab for this page.


Overload 1
public:
virtual ITabPage& setTabText(const IResourceId& resourceId)

resourceId
Reference to a resource identifier object that identifies the text to be used.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
virtual ITabPage& setTabText(const IText& tabText)

tabText
Reference to the text object to be used.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
tabBitmap
public:
virtual IBitmapHandle tabBitmap() const

Returns the bitmap handle for this tab page. If there is no bitmap for this page, the handle returned is 0.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
tabText
public:
virtual IText tabText() const

Returns a text object for the tab text.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


ITabPage - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data