### 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.

~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

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.

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.

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

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.

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.

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.

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.

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

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.

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.

pageWindow

      public:
      virtual IWindow* pageWindow() const

  Returns the current page window for this page.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

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

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.

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

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.

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

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

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

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

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

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.

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.

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

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None