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.
This class is not supported in the AIX environment.
Constructors & DestructorYou can construct and destruct objects of this class.
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
public:
ITabPage(const Style& style = defaultStyle ( ))
Constructs an ITabPage object by specifying a style for the tab page.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
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.
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Automatic SizingUse 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.
![]() |
public:
bool isAutoPageSize() const
Returns true if the autoPageSize style is set for this tab page.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Button SupportITabControl 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.
![]() |
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.
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.
| 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. |
| Windows | OS/2 | AIX |
| Yes | Yes | No |
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.
| 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. |
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
Removes a page specific button from the button sequence for this tab page.
public:
ITabPage& removePageButton(IPushButton* button)
Removes an IPushButton object constructed by the application and previously added as a page button.
| IAccessError | The specified button was not present in the page button sequence. |
| Windows | OS/2 | AIX |
| Yes | Yes | No |
public:
ITabPage& removePageButton(ITabControl::EButton buttonType)
Removes one of the predefined push buttons from the sequence of buttons for this page.
| IAccessError | A standard button for the specified buttonType was not present in the page button sequence. |
| Windows | OS/2 | AIX |
| Yes | Yes | No |
ColorsUse these members to query, set, and reset the tab background color.
![]() |
public:
virtual ITabPage& resetTabBackgroundColor()
Resets the tab background color by changing to the tab background color that was previously set.
| Windows | OS/2 | AIX |
| Ignored | Yes | No |
The tab background color cannot be changed for tab controls in the Windows environment. This member function has no effect in that environment.
![]() |
public:
virtual ITabPage& setTabBackgroundColor( const IColor& color )
Sets the tab background color for this tab page.
| Windows | OS/2 | AIX |
| Ignored | Yes | No |
The tab background color cannot be changed for tab controls in the Windows environment. This member function has no effect in that environment.
![]() |
public:
virtual IColor tabBackgroundColor() const
Returns the tab background color for this tab page.
| Windows | OS/2 | AIX |
| Ignored | Yes | No |
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 SupportUse 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.
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Layout SupportThe layout support member is used during tab control minimum size calculation.
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Page Window AssociationUse these members to query and associate the application page window for this tab page.
![]() |
public:
virtual IWindow* pageWindow() const
Returns the current page window for this page.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
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.
| IInvalidParameter | pageWindow must be a nonzero pointer. |
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Page Window SelectionOverride the following members to implement page window content validation and to update page window content during page selections.
![]() |
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:
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
StylesThese style members provide a set of valid styles for this class. Use these members to query and set the tab control styles.
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
public:
static Style defaultStyle()
Returns the current default style. The default style is classDefaultStyle unless you have changed the style by using setDefaultStyle.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
public:
static void setDefaultStyle(const Style& style)
Sets the default style for all subsequently constructed tab controls.
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
public:
static const Style classDefaultStyle
Provides the original default style for this class, which is ITabPage::autoPageSize.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
public:
static const Style noStyle
Sets all styles off.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Tab Control AssociationUse this member to query the ITabControl object to which this tab page has been added.
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
Tab Text & BitmapUse these members to set and query the tab text or bitmaps for the tab page.
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.
![]() |
Sets the bitmap to be displayed in the tab for this page.
public:
virtual ITabPage& setTabBitmap(const IBitmapHandle& bitmap)
| Windows | OS/2 | AIX |
| Yes | Yes | No |
public:
virtual ITabPage& setTabBitmap( const IResourceId& resourceId )
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
Sets the text to be displayed in the tab for this page.
public:
virtual ITabPage& setTabText(const IResourceId& resourceId)
| Windows | OS/2 | AIX |
| Yes | Yes | No |
public:
virtual ITabPage& setTabText(const IText& tabText)
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
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.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
![]() |
public:
virtual IText tabText() const
Returns a text object for the tab text.
| Windows | OS/2 | AIX |
| Yes | Yes | No |