Copyright: Copyright © 2001-2008 Developer Express Inc. ALL RIGHTS RESERVED


cxPC Unit Overview
cxPC Unit

Classes

TcxCustomTabControl

TcxPageControl

TcxTab

TcxTabControl

TcxTabs

TcxTabSheet

TcxTabSlants

Other Types

TcxPCNavigatorPosition


TcxCustomTabControl
TcxCustomTabControl Object

Hierarchy          Properties          Methods          Events          See Also

Serves as the base class for tab controls.

Unit

cxPC

TcxCustomTabControl = class(TcxControl)

Description

Tab controls allow you to arrange controls across a number of pages.  An end user can switch between pages by clicking corresponding tabs.  This allows you to create a multiple page dialog box.  Tab controls provide a number of properties and events that allow you to control the look & feel of tabs and to respond to changes to the selected tab.  There are also nine predefined painting styles provided and XP painting style.

The TcxCustomTabControl class implements all the above mentioned functionality.  It serves as the base for the TcxTabControl and TcxPageControl controls.  The TcxPageControl manages a number of pages (container controls) that are displayed when the corresponding tab is selected.  The TcxTabControl, in turn, provides a single page whose contents must be updated when the selected tab changes.


TcxCustomTabControl Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |


Properties for TcxCustomTabControl
TcxCustomTabControl Properties

TcxCustomTabControl          Legend

In TcxCustomTabControl

DisplayRect

HideTabs

HotTrack

ImageBorder

Images

MaxRotatedTabWidth

MultiLine

MultiSelect

NavigatorPosition

Options

OwnerDraw

Painter

RaggedRight

Rotate

RowCount

ScrollOpposite

ShowFrame

Style

TabHeight

TabIndex

TabPosition

Tabs

TabSlants

TabWidth

TopOrLeftPartRowCount

Derived from TcxControl

ActiveCanvas

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel

PopupMenu

Derived from TWinControl

TabStop


Methods for TcxCustomTabControl
TcxCustomTabControl Methods

TcxCustomTabControl          Legend

In TcxCustomTabControl

 Create

 Destroy

 IndexOfTabAt

 ScrollTabs

 SetStandardStyle

 SetStyleByStyleName

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxCustomTabControl
TcxCustomTabControl Events

TcxCustomTabControl          Legend

In TcxCustomTabControl

 OnCanClose

 OnChange

 OnChanging

 OnDrawTab

 OnDrawTabEx

 OnGetImageIndex

Derived from TcxControl

OnMouseEnter

OnMouseLeave


TcxCustomTabControl.DisplayRect

TcxCustomTabControl

Returns the active page’s bounding rectangle.

property DisplayRect: TRect;

Description

Use the DisplayRect property to access the bounding rectangle of the active page.  Control borders and tab area are not included in the returned value.  All returned coordinates are in pixels and are calculated from the top-left control corner.

ReadOnly Property


TcxCustomTabControl.HideTabs

TcxCustomTabControl          Concepts

Specifies whether the tab panel is hidden.

property HideTabs: Boolean;

Description

Use the HideTabs property to specify whether the tab panel is hidden.  Set this property to True to hide it.  Otherwise it is visible.

The default value of the HideTabs property is False.


TcxCustomTabControl.HotTrack

TcxCustomTabControl

Gets or sets a value specifying whether tab captions are highlighted when the mouse pointer hovers over tabs.

property HotTrack: Boolean;

Description

Use the HotTrack property to specify whether tab captions are highlighted when the mouse pointer hovers over tabs.  Set this property to True to enable tab highlighting.  Otherwise tabs don’t respond to mouse movements.

The default value of the HotTrack property is False.


TcxCustomTabControl.ImageBorder

TcxCustomTabControl          Concepts

Specifies the width of tab image borders in pixels.

property ImageBorder: Integer;

Description

Use the ImageBorder property to control the width of tab image borders.  This value is set in pixels and is applied to all tab images.

Changing the ImageBorder property value affects the indent between tab images and tab captions.  This property also influences the height and width of tabs.  Tabs are automatically resized to fit their images with the borders specified.

Assigning a negative value to the ImageBorder property is not in effect.

The default value of the ImageBorder property is 4.


TcxCustomTabControl.Images

TcxCustomTabControl          Concepts

Specifies the source of tab images.

property Images: TImageList;

Description

Use the Images property to assign the source of tab images.  You must use the TImageList component in order to set this property’s value.


TcxCustomTabControl.MaxRotatedTabWidth

TcxCustomTabControl          See Also

Specifies the maximum width tabs can have when they are rotated relative to the tab panel.

property MaxRotatedTabWidth: Integer;

Description

Tabs can be rotated relative to the tab panel orientation.  The Rotate property must be set to True for this purpose.  Use the MaxRotatedTabWidth property to limit the width of rotated tabs.  This property value is set in pixels.

If the MaxRotatedTabWidth property is set to 0, the required width of tabs is calculated automatically.  Tabs completely display their content in this instance.  If this property is set to a positive value, this value limits the width of tabs.  Tab content can be truncated in this instance.

Note: the value assigned to this property is automatically modified to the minimum tab width required for painting tabs using the applied style.


TcxCustomTabControl.MultiLine

TcxCustomTabControl          Concepts

Specifies whether tabs are arranged across several rows.

property MultiLine: Boolean;

Description

Tabs can be arranged across a number of rows.  Set the MultiLine property to True for this purpose.  If so, tabs are automatically arranged into the minimum number of rows required to fit all of them.

If the MiltiLine property value is False, tabs are displayed within a single row.  In such an instance, they may not fit into the tab control area.  The navigator bar is used to navigate through pages in such a case.


TcxCustomTabControl.MultiSelect

TcxCustomTabControl          Concepts          See Also

Specifies whether multiple tabs can be selected at a time.

property MultiSelect: Boolean;

Description

The TcxTabControl control allows you to select multiple tabs at a time.  Set its MultiSelect property to True for this purpose.  If it is done, a user can select multiple tabs by clicking them when the CTRL key is pressed.  If the MultiSelect property is False, selecting a tab deselects the previously selected tab.

Note:	The MultiSelect property is in effect only when the buttons painting style or flat buttons painting style is applied to a control.  Otherwise, a user cannot select multiple pages simultaneously.


TcxCustomTabControl.NavigatorPosition

TcxCustomTabControl          Concepts

Specifies the control corner in which the navigator bar resides.

TcxPCNavigatorPosition = (npLeftTop, npLeftBottom, npRightTop, npRightBottom);

property NavigatorPosition: TcxPCNavigatorPosition;

Description

Navigator bar can reside both at the beginning and at the end of the tab panel.  The tab panel, in turn, can be oriented horizontally or vertically.  The NavigatorPosition property specifies the navigator bar’s location with respect to tab panel orientation.

The following values are available for the NavigatorPosition property:

Value	Description
npLeftTop	If the tab panel is horizontally oriented, the navigator bar is located at its left end.  Otherwise it is located at the top end.
npLeftBottom	If the tab panel is horizontally oriented, the navigator bar is located at its left end.  Otherwise it is located at the bottom end.
npRightTop	If the tab panel is horizontally oriented, the navigator bar is located at its right end.  Otherwise it is located at the top end.
npRightBottom	If the tab panel is horizontally oriented, the navigator bar is located at its right end.  Otherwise it is located at the bottom end.

The default value of the NavigatorPosition property is npRightTop.


TcxCustomTabControl.Options

TcxCustomTabControl          Concepts

Specifies tab control options.

type

  TcxPCOption = (pcoAlwaysShowGoDialogButton, pcoCloseButton, pcoFixedTabWidthWhenRotated, pcoGoDialog, pcoGradient, pcoGradientClientArea, pcoNoArrows, pcoRedrawOnResize, pcoSort, pcoTopToBottomText, pcoUsePageColorForTab);

  TcxPCOptions = set of TcxPCOption;

property Options: TcxPCOptions;

Description

The Options property specifies a set of options affecting the appearance and behavior of a tab control.  Consider the following table for a description of each option:

Option	Description
pcoAlwaysShowGoDialogButton	If active, the Go Dialog button is always visible within the navigator bar.  Otherwise, this button is displayed only when all visible tabs cannot fit into a tab control. Note: This option is effective only when the pcoGoDialog option is active.
pcoCloseButton	If active, the Close Button is displayed within the navigator bar.  The Close Button lets end-users close the currently selected tab and remove it from the tabs displayed within a tab control.
pcoFixedTabWidthWhenRotated	If active, the width of the tab panel is determined by the maximum width of all the tabs including what is not currently displayed within the control (accessible via the navigator bar) and excluding invisible tabs.  Otherwise, the width of the tab panel is determined by the maximum width of the tabs which are currently visible within the control. Note: This option is effective only when the tabs are rotated (the Rotate property is set to True).
pcoGoDialog	If active, the Go Dialog button is displayed within the navigator bar. Note: When the pcoAlwaysShowGoDialogButton option is disabled, the Go Dialog button is displayed only if all visible tabs cannot fit into a tab control.
pcoGradient	If active, gradient filling is used to paint the background of the tabs within a tab control which has the Office11, Slanted or OneNote painting styles applied to it and also the client area of a tab control which has the Office11 painting style applied to it.  Otherwise, the background is painted as a single fixed color.
pcoGradientClentArea	If active, gradient filling is used to paint the background of the client area of a tab control which has the Office11 painting style applied to it. Note: This option has no effect when either the pcoGradient option is inactive or a page of the TcxPageControl control has a specific color assigned to it (i.e. the page’s ParentColor property is set to False and the color is specified via its Color property).
pcoNoArrows	If active, arrow buttons are not displayed within the navigator bar.
pcoRedrawOnResize	If active, all the child controls within a tab control are redrawn when the tab control is resized.  This option is required to ensure that controls which have transparent backgrounds (for instance, TcxLabel controls) are painted correctly within a tab control.  The pcoRedrawOnResize option has no effect within a tab control which has a style other than the Office11 or XP painting styles applied to it. Note: When this option is active, resizing of a tab control might make the child controls flicker.
pcoSort	If active, tab captions are sorted alphabetically within the Go Dialog.  Otherwise, tab captions have the same order as the corresponding tabs.
pcoTopToBottomText	If active, vertical text is written from top to bottom.  Otherwise it is written from bottom to top.  Please refer to the Tabs Position and Arrangement topic for additional information.
pcoUsePageColorForTab	If active, tabs are painted using the same color as the corresponding pages (as specified by the page’s Color property).  Otherwise, the color of a particular tab is determined by its Color property. Note: This option isn’t in effect for a particular bar when its ParentColor property is set to True.  Upon setting the color of a particular page the page’s Color property automatically sets its ParentColor property to False.

By default, pcoAlwaysShowGoDialogButton, pcoGradient, pcoGradientClientArea, and pcoRedrawOnResize options are enabled.


TcxCustomTabControl.OwnerDraw

TcxCustomTabControl          Concepts

Specifies whether the tab control uses default tab drawing.

property OwnerDraw: Boolean;

Description

Tab controls provide default tab drawing according to the Style property value.  Default tab drawing is used only when the OwnerDraw property value is False.

Set the OwnerDraw property to True to provide your own tab drawing.  You must write an OnDrawTab and/or OnDrawTabEx event handler for this purpose.


TcxCustomTabControl.Painter

TcxCustomTabControl

Provides access to the control’s painter.

property Painter: TcxPCCustomPainter;

Description

Every tab control has a painter which is used to paint the tab control according to its painting style and look and feel settings.  Use the Painter property to access the painter of the current tab control.

Note:	Please refer to the Applying Painting Styles topic for details on applying various painting styles.

ReadOnly Property


TcxCustomTabControl.RaggedRight

TcxCustomTabControl          Concepts

Specifies whether tabs are stretched to fit the control’s area.

property RaggedRight: Boolean;

Description

Use the RaggedRight property to specify whether tab rows populate the entire width (or height, if the tab panel is oriented vertically) of the control.  If this property value is False, tab rows are stretched.  Otherwise, the width of tabs is specified by the TabWidth property.

Note: The RaggedRight property is not in effect when tabs are arranged into a single row.

The default value of the RaggedRight property is False.


TcxCustomTabControl.Rotate

TcxCustomTabControl          Concepts

Specifies whether tabs are rotated relative to tab panel orientation.

property Rotate: Boolean;

Description

Use the Rotate property to change the orientation of tabs.  Setting this property to True rotates tabs by 90 degrees.  In such a case, if the tab panel is oriented horizontally, tabs will be oriented vertically and vice versa.  If the Rotate property value is False, tabs are oriented the same way as the tab panel.

The default value of the Rotate property is False.


TcxCustomTabControl.RowCount

TcxCustomTabControl          Concepts

Returns the number of tab rows.

property RowCount: Integer;

Description

Use the RowCount property to access the total number of tab rows.

ReadOnly Property


TcxCustomTabControl.ScrollOpposite

TcxCustomTabControl          Concepts

Specifies whether tab rows can be scrolled to the opposite side of a tab control.

property ScrollOpposite: Boolean;

Description

Tabs can be arranged into a number of rows.  When a tab is selected, its row becomes the bottommost row.  The rows that resided under it (closer to the page) are either moved to the opposite side of a tab control or become the topmost row.  This behavior depends on the ScrollOpposite property setting.  If this property value is True, tabs rows are moved to the opposite side of a control.  Otherwise tab rows simply change their order.

The following image displays initial tab layout before switching to the Alignment tab.

The images below display various results of selecting a tab depending on the ScrollOpposite property setting.

The ScrollOpposite property’s value is False	The ScrollOpposite property’s value is True
Note:	The ScrollOpposite property is in effect only when tabs don’t appear as buttons.  Otherwise, tabs are represented by buttons and thus there is no need to change their order in the tab row.

The default value of the ScrollOpposite property is False.


TcxCustomTabControl.ShowFrame

TcxCustomTabControl          Concepts

Specifies whether a border is drawn around pages.

property ShowFrame: Boolean;

Description

Use the ShowFrame property to specify whether to display page borders.  If this property value is True, borders are displayed.  Otherwise, borders are not drawn.

The Images below display the difference between ShowFrame property values.

The ShowFrame property’s value is False	The ShowFrame property’s value is True
Note: The ShowFrame property is in effect only when the buttons painting style or flat buttons painting style is applied to a control.  Otherwise borders are not drawn around pages.

The default value of the ShowFrame property is False.


TcxCustomTabControl.Style

TcxCustomTabControl          Concepts

Specifies the painting style of a tab control.

type

  TcxPCStyleID = -1 .. High(Integer);

property Style: TcxPCStyleID;

Description

Tab controls support nine predefined painting styles.  Use the Style property to switch between them.  The following values are available for this property:

Design-time value	Runtime value	Description
Default	0	Applies the Flat Painting Style to the control.
Tabs	1	Applies the Tabs Painting Style to the control.
Buttons	2	Applies the Buttons Painting Style to the control.
FlatButtons	3	Applies the Flat Buttons Painting Style to the control.
ExtraFlat	5	Applies the Extra Flat Painting Style to the control.
UltraFlat	6	Applies the Ultra Flat Painting Style to the control.
Flat	7	Applies the Flat Painting Style to the control.
Office11	8	Applies the Office11 Painting Style to the control.
Slanted	9	Applies the Slanted Painting Style to the control.
OneNote	10	Applies the OneNote Painting Style to the control.
Skin	11	Applies the Skin Painting Style to the control.

Property values are described here without taking into account the LookAndFeel property.  Please see the Applying Painting Styles topic for details on using the Style and LookAndFeel properties in conjunction with one another.


TcxCustomTabControl.TabHeight

TcxCustomTabControl          Concepts

Specifies the height of tabs in pixels.

property TabHeight: Smallint;

Description

Use the TabHeight property to set or get the height of tabs in pixels.  This property cannot be set to a value less than that required to fit the contents of tabs.  Tab contents include tab caption and tab image.

Note:	When the TabHeight property is set to a value of 0, the height of tabs is calculated automatically to entirely fit their contents.  To determine the calculated height, use the Painter.CalculateTabNormalHeight function.

Note:	When tabs are oriented vertically, the height of tabs is the width of the rectangles they occupy.


TcxCustomTabControl.TabIndex

TcxCustomTabControl          Concepts

Specifies the selected tab index.

property TabIndex: Integer;

Description

Use the TabIndex property to obtain the selected tab index or to select a tab at runtime.  Note that tabs are zero-based indexed.

If the TabIndex property is set to –1, none of the tabs are selected.  Setting this property to a value less than –1 and greater than the last tab index has no effect.

The default value of the TabIndex property is -1.


TcxCustomTabControl.TabPosition

TcxCustomTabControl          Concepts

Specifies tab panel position.

TcxTabPosition = (tpTop, tpBottom, tpLeft, tpRight);

property TabPosition: TcxTabPosition;

Description

Use the TabPosition property to specify the side of a tab control, where the tab panel resides.  The following values are available for this property.

Value	Description
tpTop	The tab panel resides at the top of a control.
tpBottom	The tab panel resides at the bottom of a control.
tpLeft	The tab panel resides to the left of a control.
tpRight	The tab panel resides to the right of a control.

The default value of the TabPosition property is tpTop.


TcxCustomTabControl.Tabs

TcxCustomTabControl          Concepts

Returns the collection of tabs displayed by a control.

property Tabs: TcxTabs;

Description

Use the Tabs property to access the collection of tabs displayed by a tab control.  This property gives you the ability to access properties of each individual tab, represented by TcxTab objects.

Use this property at design-time to specify the number of tabs and their captions via the String List Editor.


TcxCustomTabControl.TabSlants

TcxCustomTabControl          Concepts

Specifies the appearance aspects of tab slants.

property TabSlants: TcxTabSlants;

Description

Use the TabSlants property to specify the appearance aspects of tab slants (such as their kind and positions) within a tab control which has the Slanted painting style applied.


TcxCustomTabControl.TabWidth

TcxCustomTabControl          Concepts

Specifies the width of tabs in pixels.

property TabWidth: Smallint;

Description

Use the TabWidth property to adjust the width of tabs displayed by a tab control.  If this property value is 0, each tab has the minimum width required to fit its contents.  Tab contents include tab caption and tab image.

Note that setting the TabWidth property to a value less than the minimum tab width has no effect.  Minimum tab width depends on the painting style applied.

The default value of the TabWidth property is 0.


TcxCustomTabControl.TopOrLeftPartRowCount

TcxCustomTabControl          Concepts

Returns the number of tab rows displayed in the top or left side of a tab control.

property TopOrLeftPartRowCount: Integer;

Description

If the ScrollOpposite property value is True, the tab panel may display tab rows on the opposite sides of a tab control.  Use the TopOrLeftPartRowCount property to read the number of tab rows currently displayed in the top or left side of a control.  If tab rows are oriented horizontally, the number of top side rows is returned.  Otherwise the TopOrLeftPartRowCount property returns the number of left side rows.

ReadOnly Property


TcxCustomTabControl.Create

TcxCustomTabControl

Creates an instance of the TcxCustomTabControl class.

procedure Create(AOwner: TComponent); override;

Description

The Create method is used to instantiate the TcxCustomTabControl class.  It sets properties to their default values after calling the inherited constructor.  The AOwner parameter specifies the owner of the newly created control.

Do not create instances of the TcxCustomTabControl class.  Instantiate one of its descendant controls instead.


TcxCustomTabControl.Destroy

TcxCustomTabControl

Destroys the TcxCustomTabControl object.

procedure Destroy; override;

Description

The Destroy method is used to dispose the TcxCustomTabControl object and free any allocated memory.

Do not create and destroy TcxCustomTabControl objects in applications.  Manipulate one of its descendant controls instead.


TcxCustomTabControl.IndexOfTabAt

TcxCustomTabControl

Returns the index of the tab to which the specified point belongs.

function IndexOfTabAt(X, Y: Integer): Integer;

Description

Use the IndexOfTabAt method to obtain the index of the tab located under the specified point.  The X and Y parameters specify the horizontal and vertical coordinates of the point.  Note that tab indexes are zero-based.  If none of the tabs are under the specified point, the IndexOfTabAt method returns –1.

You can access tabs and pages by their indexes via the Tabs property (the TcxTabControl control) and the Pages property (the TcxPageControl control).


TcxCustomTabControl.ScrollTabs

TcxCustomTabControl

Scrolls the tab panel by the specified number of tabs.

procedure ScrollTabs(Delta: Integer);

Description

If the total width of tabs exceeds the width of a tab control and tabs are arranged into a single row, some tabs may be invisible.  Use the ScrollTabs method to scroll the tab panel by the number of tabs specified via the Delta parameter.  If the parameter value is positive, the tab panel is scrolled forward.  Otherwise it is scrolled backward.  If the Delta parameter is 0, no scrolling is performed.

Note: The ScrollTabs method doesn’t change the active page.


TcxCustomTabControl.SetStandardStyle

TcxPageControl          Concepts

Applies the specified painting style to a tab control.

TcxPCStandardStyle = (tsTabs, tsButtons, tsFlatButtons);

procedure SetStandardStyle(StandardStyle: TcxPCStandardStyle);

Description

Use the SetStandardStyle method to apply the specified painting style to a tab control.  The applied painting style is specified by the StandardStyle parameter.  There are nine predefined painting styles provided by tab control.  Consider the table below for the list of these styles and corresponding values for the StandardStyle parameter.

Style name	Description
tsTabs	Applies the Tabs Painting Style to a control.
tsButtons	Applies the Buttons Painting Style to a control.
tsFlatButtons	Applies the Flat Buttons Painting Style to a control.

These method parameter descriptions assume that the LookAndFeel property has no effect on the painting style applied to the control.  Please refer to the Applying Painting Styles topic for more information on how the painting style of the control can be changed.


TcxCustomTabControl.SetStyleByStyleName

TcxPageControl            Concepts

Applies the painting style with the specified name.

procedure SetStyleByStyleName(StyleName: TCaption);

Description

Use the SetStyleByStyleName method to apply a painting style to a tab control.  The applied painting style is specified by its name via the StyleName parameter.  There are nine predefined painting styles provided by tab control.  Consider the table below for the list of these styles and corresponding values of the StyleName parameter.

Style name	Description
Tabs	Applies the Tabs Painting Style to a control.
Buttons	Applies the Buttons Painting Style to a control.
FlatButtons	Applies the Flat Buttons Painting Style to a control.
ExtraFlat	Applies the Extra Flat Painting Style to a control.
UltraFlat	Applies the Ultra Flat Painting Style to a control.
Flat	Applies the Flat Painting Style to a control.
Office11	Applies the Office11 Painting Style to a control.
Slanted	Applies the Slanted Painting Style to a control.
OneNote	Applies the OneNote Painting Style to a control.
Skin	Applies the Skin Painting Style to a control.

The SetStyleByStyleName method’s parameters are described here assuming that the LookAndFeel property has no influence on the control’s painting style.  The Applying Painting Styles topic provides information on how these members are used in conjunction with one another.


TcxCustomTabControl.OnCanClose

TcxCustomTabControl

Fires when the Close Button is clicked.

type

  TcxPCCanCloseEvent = procedure(Sender: TObject; var ACanClose: Boolean) of object;

property OnCanClose: TcxPCCanCloseEvent;

Description

Each time the Close Button is clicked the OnCanClose event is fired.  Handle the OnCanClose event to specify whether the currently selected tab should be closed and removed from the tabs displayed within the tab control which is specified by the Sender parameter.  Set the ACanClose parameter (whose value is True initially) to False to prohibit the currently selected tab from being closed.


TcxCustomTabControl.OnChange

TcxCustomTabControl          See Also

Fires after a tab has been selected.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnChange: TNotifyEvent;

Description

Write an OnChange event handler to perform specific actions each time after a tab has been selected.  This event also fires after all tabs have been deselected.  The currently selected tab index can be obtained via the TabIndex property.  The Sender parameter specifies the tab control, whose selected tab has been changed.

This event allows you to update a tab control each time the selected tab changes.  This is required by the TcxTabControl control since its page must be updated manually when a user selects a tab.


TcxCustomTabControl.OnChanging

TcxCustomTabControl          See Also

Fires immediately before a tab is selected.

type

  TcxTabChangingEvent = procedure(Sender: TObject; var AllowChange: Boolean) of object;

property OnChanging: TcxTabChangingEvent;

Description

Write an OnChanging event handler to perform specific actions each time before a user selects a tab.  This event also fires after all tabs have been deselected.  The Sender parameter specifies the tab control, whose selected tab is about to be changed.  You can prohibit changing the selected tab by setting the AllowChange parameter to False.

Use an OnChanging event handler to prevent a user from leaving the tab until certain conditions have been met.  It can also be used to save information about the current state of the tab control before it is changed by a new tab selection.


TcxCustomTabControl.OnDrawTab

TcxCustomTabControl          Concepts

Enables you to paint tabs using custom draw.

type

  TcxDrawTabEvent = procedure(AControl: TcxCustomTabControl; ATab: TcxTab; var DefaultDraw: Boolean) of object;

property OnDrawTab: TcxDrawTabEvent;

Description

Write an OnDrawTab event handler to perform custom drawing of tabs.  If the OwnerDraw property value is True, the event fires for every tab within the control each time the control is repainted.

The AControl parameter specifies the tab control whose tab is to be painted.  The ATab parameter specifies the painted tab.  Use the DefaultDraw parameter to specify whether default drawing must be performed.  If a tab has been painted in the event handler, set this property to False.


TcxCustomTabControl.OnDrawTabEx

TcxCustomTabControl          Concepts

Enables you to provide custom fonts for captions of individual tabs.

type

  TcxDrawTabExEvent = procedure(AControl: TcxCustomTabControl; ATab: TcxTab; Font: TFont) of object;

property OnDrawTabEx: TcxDrawTabExEvent;

Description

Write an OnDrawTabEx event handler to change the font applied to individual tab captions.  This event fires for every tab each time the control is repainted.

The AControl parameter specifies the tab control.  The ATab parameter provides access to the tab whose font settings are to be specified.  Use the Font parameter to change the tab caption’s font, if needed.


TcxCustomTabControl.OnGetImageIndex

TcxCustomTabControl          Concepts

Fires when the tab image needs to be assigned to a tab.

type

  TcxGetTabImageEvent = procedure(Sender: TObject; TabIndex: Integer; var ImageIndex: Integer) of object;

property OnGetImageIndex: TcxGetTabImageEvent;

Description

Write an OnGetImageIndex event handler to assign images to tabs.  This event fires for a tab before its contents are painted.

The Sender parameter specifies the tab control, whose tab needs an image to be assigned.  The TabIndex property specifies the tab index.  The index of the image to be assigned must be written to the ImageIndex parameter.  Image indexes must correspond to images specified by the Images property.


TcxPageControl
TcxPageControl Object

Hierarchy          Properties          Methods          Events

Represents a page control.

Unit

cxPC

TcxPageControl = class(TcxCustomTabControl)

Description

Use the TcxPageControl control to add a multiple page dialog onto a form.  This control allows you to create a number of pages (container controls).  Each page can contain its own collection of controls.  An end user can switch between pages by means of clicking tabs.

The TcxCustomTabControl class implements the basic functionality of a page control.  The TcxPageControl class introduces several properties and methods used for page management.

If you don’t need to use a separate page for each tab, use the TcxTabControl instead.  This control provides a single page whose contents can be updated when the selected tab is changed.


TcxPageControl Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomTabControl


Properties for TcxPageControl
TcxPageControl Properties

TcxPageControl          Legend

In TcxPageControl

ActivePage

ActivePageIndex

Focusable

PageCount

Pages

TabCount

Derived from TcxCustomTabControl

DisplayRect

HideTabs

HotTrack

ImageBorder

Images

MaxRotatedTabWidth

MultiLine

MultiSelect

NavigatorPosition

Options

OwnerDraw

Painter

RaggedRight

Rotate

RowCount

ScrollOpposite

ShowFrame

Style

TabHeight

TabIndex

TabPosition

Tabs

TabSlants

TabWidth

TopOrLeftPartRowCount

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxPageControl
TcxPageControl Methods

TcxPageControl          Legend

In TcxPageControl

 Create

 Destroy

 FindNextPage

 SelectNextPage

Derived from TcxCustomTabControl

 Create

 Destroy

 IndexOfTabAt

 ScrollTabs

 SetStandardStyle

 SetStyleByStyleName

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxPageControl
TcxPageControl Events

TcxPageControl          Legend

In TcxPageControl

 OnPageChanging

Derived from TcxCustomTabControl

 OnCanClose

 OnChange

 OnChanging

 OnDrawTab

 OnDrawTabEx

 OnGetImageIndex

Derived from TcxControl

OnMouseEnter

OnMouseLeave

Derived from TControl

 OnClick

 OnDblClick


TcxPageControl.ActivePage

TcxPageControl           Concepts

Specifies the active page of the page control.

property ActivePage: TcxTabSheet;

Description

Use the ActivePage property to obtain the TcxTabSheet object representing the active page or navigate to the specified page.


TcxPageControl.ActivePageIndex

TcxPageControl          Concepts

Specifies the active page via its index.

property ActivePageIndex: Integer;

Description

Use the ActivePageIndex property to read the active page index or navigate to the page with the specified index.  Note that pages are zero-based indexed.  If the ActivePageIndex property is set to a value less than 0 or greater than the last page index, none of pages are active. The last page index is always one less than the PageCount property value.


TcxPageControl.Focusable

TcxPageControl

Specifies whether the page control can be focused.

property Focusable: Boolean;

Description

Use the Focusable property to specify whether focusing the page control is allowed.  If set to True, end users can focus the page control either using the TAB key or by clicking a tab with the mouse.  The control can also be focused via code by calling its SetFocus method.  When focused, you can switch between tabs using the arrow keys.  If the Focusable property is set to False, the page control cannot be focused.  End users can only switch between tabs using the mouse.

Note: controls residing on pages of the page control can be focused independently of the Focusable property value.

The default value of the Focusable property is True.


TcxPageControl.PageCount

TcxPageControl          Concepts

Returns the number of pages owned by the page control.

property PageCount: Integer;

Description

Use the PageCount property to obtain the total number of pages owned by the page control.

ReadOnly Property


TcxPageControl.Pages

TcxPageControl          Concepts

Provides indexed access to pages owned by the page control.

property Pages[Index:Integer]: TcxTabSheet;

Description

Use the Pages property to obtain the TcxTabSheet object representing the specified page.  Pages are specified by their indexes via the Index parameter.  Indexes are zero-based.  The last index is always one less than the PageCount property value.  If the page index is specified incorrectly, an error is raised.

ReadOnly Property


TcxPageControl.TabCount

TcxPageControl          Concepts

Returns the number of visible tabs.

property TabCount: Integer;

Description

Use the TabCount property to obtain the number of tabs currently displayed by the page control.  This number also specifies the number of pages a user can access by clicking tabs.  The visibility of a tab is specified by the TabVisible property of the corresponding TcxTabSheet object.

ReadOnly Property


TcxPageControl.Create

TcxPageControl

Creates a page control.

procedure Create(AOwner: TComponent); override;

Description

Use the Create method to create a new page control at runtime.  The AOwner parameter specifies the owner of the newly created control (typically the form).  Be sure to specify the Parent property of the newly created control.  Otherwise the control will not be displayed.


TcxPageControl.Destroy

TcxPageControl

Destroys the page control.

procedure Destroy; override;

Description

The Destroy method is used to dispose the TcxPageControl control and free any allocated memory.  Do not use this method in applications.  Use the Free method instead.


TcxPageControl.FindNextPage

TcxPageControl          Concepts

Returns the page located before or after the specified page.

function FindNextPage(CurrentPage: TcxTabSheet; GoForward, CheckTabVisible: Boolean): TcxTabSheet;

Description

Use the FindNextPage method to obtain the TcxTabSheet object representing the page located before or after the specified page.  The page starting page is specified via the CurrentPage parameter.  If the GoForward parameter value is True, the next page after that specified is returned.  Otherwise the FindNextPage method returns the previous page.  Set the CheckTabVisible parameter to True to ignore invisible pages when searching.

If the page control has no pages or all the pages are invisible, the FindNextPage method returns nil.  If the method reaches the last page when searching forward, the search is started from the first page and vice versa.


TcxPageControl.SelectNextPage

TcxPageControl          Concepts

Activates the page located before or after the active page.

procedure SelectNextPage(GoForward: Boolean; CheckTabVisible: Boolean = True);

Description

Use the SelectNextPage method to navigate to the page located before or after the currently active page.  If the GoForward parameter is set to True, the next page after the current is selected.  Otherwise the SelectNextPage method selects the previous page.  If the CheckTabVisible parameter is set to True, pages with invisible tabs are ignored.  Otherwise such pages can be selected, but their tabs remain invisible.

If the method reaches the last page when searching forward, the search is started from the first page and vice versa.


TcxPageControl.OnPageChanging

TcxPageControl

Fires immediately before an active page changes.

type

  TcxPageChangingEvent = procedure(Sender: TObject; NewPage: TcxTabSheet; var AllowChange: Boolean) of object;

property OnPageChanging: TcxPageChangingEvent;

Description

Write an OnPageChanging event handler to perform specific actions each time an active page is about to be changed.  You can prevent the change by setting the AllowChange parameter to False.

The Sender parameter specifies the page control, whose active page is about to be changed.  The NewPage parameter allows you to access the page which is about to be activated.


TcxTabControl
TcxTabControl Object

Hierarchy          Properties          Methods          Events

Represents a tab control.

Unit

cxPC

TcxTabControl = class(TcxCustomTabControl)

Description

Use the TcxTabControl control to add a multiple page dialog onto a form.  This control provides a single page and allows you to create a set of tabs.  The page’s contents should be updated when a user clicks a tab.

The TcxCustomTabControl class completely implements the functionality of a tab control.  The TcxTabControl class simply changes the visibility of certain class members.

If you need to use a separate page for each tab, use the TcxPageControl instead.  This control gives you the ability to manipulate individual tabs and pages.


TcxTabControl Hierarchy
Hierarchy

TCustomControl

     |

TcxControl

     |

TcxCustomTabControl


Properties for TcxTabControl
TcxTabControl Properties

TcxTabControl          Legend

Derived from TcxCustomTabControl

DisplayRect

HideTabs

HotTrack

ImageBorder

Images

MaxRotatedTabWidth

MultiLine

MultiSelect

NavigatorPosition

Options

OwnerDraw

Painter

RaggedRight

Rotate

RowCount

ScrollOpposite

ShowFrame

Style

TabHeight

TabIndex

TabPosition

Tabs

TabSlants

TabWidth

TopOrLeftPartRowCount

Derived from TcxControl

Bounds

Canvas

ClientBounds

IsDesigning

IsDestroying

IsFocused

IsLoading

LookAndFeel


Methods for TcxTabControl
TcxTabControl Methods

TcxTabControl          Legend

Derived from TcxCustomTabControl

 Create

 Destroy

 IndexOfTabAt

 ScrollTabs

 SetStandardStyle

 SetStyleByStyleName

Derived from TcxControl

 Create

 Destroy

 InvalidateRect


Events for TcxTabControl
TcxTabControl Events

TcxTabControl          Legend

Derived from TcxCustomTabControl

 OnCanClose

 OnChange

 OnChanging

 OnDrawTab

 OnDrawTabEx

 OnGetImageIndex

Derived from TcxControl

OnMouseEnter

OnMouseLeave

Derived from TControl

 OnClick

 OnDblClick


TcxTabSlants
TcxTabSlants Object

Hierarchy          Properties

Represents the options available for tab slants.

Unit

cxPC

TcxTabSlants = class(TPersistent)

Description

The manner in which tab slants for tabs within the TcxTabControl control with the Slanted painting style applied are painted is determined by the options specified by an instance of the TcxTabSlants class.  These options include the kind of slants and the positions (sides) at which the tabs are bent.


TcxTabSlants Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxTabSlants
TcxTabSlants Properties

TcxTabSlants          Legend

Kind

Positions


TcxTabSlants.Kind

TcxTabSlants

Specifies the kind of tab slants.

type

  TcxTabSlantKind = (skCutCorner, skSlant);

property Kind: TcxTabSlantKind;

Description

Set the Kind property to specify the appearance aspects (kind) of tab slants used to bend the tabs.

All the possible values are listed in the following table.

Value	Meaning	Example
skCutCorner	Tabs appear with cut corners.
skSlant	Tabs appear with their sides bent by slants.

The default value of the Kind property is skSlant.


TcxTabSlants.Positions

TcxTabSlants

Specifies the positions (sides) at which the tabs are bent.

type

  TcxTabSlantPosition = (spLeft, spRight);

  TcxTabSlantPositions = set of TcxTabSlantPosition;

property Positions: TcxTabSlantPositions;

Description

Set the Positions property to specify the sides at which the tabs are bent by slants.

All the possible values are listed in the following table.

Value	Meaning
spLeft	Slants bend left sides of the tabs.
spRight	Slants bend right sides of the tabs.

Here is a sample screenshot of a tab control when its Positions property is set to [spLeft, spRight].

The default value of the Positions property is [spLeft].


TcxTab
TcxTab Object

Hierarchy          Properties          Methods

Represents an individual tab within the TcxTabControl control.

Unit

cxPC

TcxTab = class(TPersistent)

Description

The TcxTabControl gives you the ability to create and customize a number of tabs.  Tabs are accessed via its Tabs property and can be created at design-time using the String List Editor.  The Tabs property is represented by the TcxTabs class and stores a collection of TcxTab objects each representing an individual tab.

The TcxTab class provides a number of properties affecting the appearance and behavior of a tab.


TcxTab Hierarchy
Hierarchy

TPersistent

     |


Properties for TcxTab
TcxTab Properties

TcxTab          Legend

In TcxTab

Caption

Color

Enabled

FullRect

Highlighted

HotTrack

ImageIndex

Index

IsMainTab

PaintingPosition

Pressed

RealEnabled

RealVisible

Selected

Tracking

Visible

VisibleIndex

VisibleRect

VisibleRow


Methods for TcxTab
TcxTab Methods

TcxTab          Legend

In TcxTab

 Create

 Destroy


TcxTab.Caption

TcxTab

Specifies tab caption.

property Caption: string;

Description

Use the Caption property to specify tab caption.  You can access tab captions by using the String List Editor at design time.


TcxTab.Color

TcxTab

Specifies the color of the tab.

property Color: TColor;

Description

Use the Color property to specify the color of the current tab.  When the value of clDefault is assigned to this property, the actual color of the tab is determined by the painting style applied to a tab control.

Note:	By setting the pcoUsePageColorForTab option using the Options property of a tab control you can explicitly specify that the color of tabs is the same as the color of their corresponding tab pages (provided that the ParentColor property of these tab pages is set to False).

The default value of the Color property is clDefault.


TcxTab.Enabled

TcxTab

Specifies whether the tab is enabled.

property Enabled: Boolean;

Description

Use the Enabled property to specify whether the tab responds to user clicks.  If this property value is True, the tab is enabled.  Otherwise, it is grayed and doesn’t respond to user clicks.

The following line of code disables the second tab:

// Delphi

cxTabControl1.Tabs.Tabs[1].Enabled := False;

The default value of the Enabled property is True.


TcxTab.FullRect

TcxTab          Concepts

Returns the rectangle occupied by the tab in coordinate system of the tab control.

property FullRect: TRect;

Description

Use the FullRect property to determine the area occupied by the tab.  Coordinates are calculated with respect to the top-left corner of the tab control.

ReadOnly Property


TcxTab.Highlighted

TcxTab          Concepts

Specifies whether the tab is highlighted.

property Highlighted: Boolean;

Description

Use the Highlighted property to specify whether the tab’s background is painted using a different color.  Set this property to True to highlight the tab.  Otherwise the tab has a default appearance.

Tabs are highlighted with a clHighlight color.


TcxTab.HotTrack

TcxTab          Concepts

property HotTrack: Boolean;

Description

The value returned by the HotTrack property depends on the HotTrack property of a tab control.  If the tab control’s HotTrack property value is set to True, the HotTrack property returns a value indicating whether the mouse pointer is currently over the tab.  Otherwise the HotTrack property returns False.

ReadOnly Property


TcxTab.ImageIndex

TcxTab

Specifies the image displayed in the tab.

property ImageIndex: TImageIndex;

Description

Use the ImageIndex property to specify the corresponding tab image.  The image is specified by its index within the source images collection.  The source of images is assigned via the Images property of a tab control.

If the ImageIndex property is set to –1, no image is displayed in the tab.  This property cannot be set to a value less than –1 or greater than the last available image index.

The default value of the ImageIndex property is -1.


TcxTab.Index

TcxTab

Returns the tab index within the tabs collection.

property Index: Integer;

Description

Tabs are stored in a collection represented by the TcxTabs object.  Use the Index property to obtain the tab index within the owning collection.  Tabs are zero-based indexed.

You can access a tab by its index via the Tabs property of the TcxTabs object.

ReadOnly Property


TcxTab.IsMainTab

TcxTab          Concepts

Returns a value indicating whether the tab is a main tab.

property IsMainTab: Boolean;

Description

Use the IsMainTab property to determine whether the tab is the main tab.  If so, this property returns True.  Otherwise False is returned.

ReadOnly Property


TcxTab.PaintingPosition

TcxTab          Concepts

Returns a value indicating the side of the control onto which the tab is located.

TcxPCTabPaintingPosition = (tppTop, tppBottom, tppLeft, tppRight);

property PaintingPosition: TcxPCTabPaintingPosition;

Description

Tabs are located on the side specified by the TabPosition property of a tab control.  However, if the ScrollOpposite property is set to True, certain tabs can be located on the opposite side of a control.  Use the PaintingPosition property to determine the side on which the tab is actually located.

The PaintingPosition property can return one of the following values.

Value	Description
tppTop	The tab is located at the top side of the control.
tppBottom	The tab is located at the bottom side of the control.
tppLeft	The tab is located at the left side of the control.
tppRight	The tab is located at the right side of the control.

ReadOnly Property


TcxTab.Pressed

TcxTab          Concepts

Returns a value indicating whether a user is currently pressing the tab.

property Pressed: Boolean;

Description

Use the Pressed property to determine whether a user is currently holding the left mouse button and the mouse pointer is over the tab.  If so, the Pressed property returns True.  Otherwise, False is returned.

ReadOnly Property


TcxTab.RealEnabled

TcxTab

Returns a value indicating whether the tab and the owning control are enabled.

property RealEnabled: Boolean;

Description

You can control the availability of a tab to a user via the tab’s Enabled property.  However, tabs can be disabled by setting the Enabled property of the owning control to False.  In such a case, a tab doesn’t respond to user clicks even if its Enabled property value is True.  You must use the RealEnabled property in such instances.  This property returns True if both the control and the tab are enabled.  Otherwise, False is returned.

ReadOnly Property


TcxTab.RealVisible

TcxTab          Concepts

Returns a value indicating whether the tab is currently visible to an end-user.

property RealVisible: Boolean;

Description

Tab visibility is controlled via the Visible property.  However, if tabs are arranged into a single row and they don’t fit into the control’s area, some of the tabs may not be currently visible to an end-user.  The RealVisible property returns True when an end-user can see the tab.  Otherwise, False is returned.

ReadOnly Property


TcxTab.Selected

TcxTab          Concepts          See Also

Specifies whether the tab is selected.

property Selected: Boolean;

Description

Use the Selected property to specify whether the tab is selected.  Set this property to True to select the tab.  Setting this property value to False deselects the tab.

This property returns False for the main tabs.  Setting the Selected property to True within a tab control which already has selected tab(s) automatically sets the tab control’s MultiSelect property to True.

Note:	Setting the Selected property to True has no effect for the main tabs or when neither the buttons painting style nor flat buttons painting style are applied to a tab control.


TcxTab.Tracking

TcxTab

Indicates whether the tab is currently tracked.

property Tracking: Boolean;

Description

End users can navigate through tabs using arrow keys without changing the active tab.  This can only be performed if the Buttons Painting Style or Flat Buttons Painting Style is applied to the control.  Users can press the ENTER or SPACE key to make the currently tracked tab active.

The Tracking property returns True if the tab is currently tracked.  The image below displays a tab control whose Alignment tab is active while the Background tab is tracked.

ReadOnly Property


TcxTab.Visible

TcxTab

Specifies whether the tab is visible.

property Visible: Boolean;

Description

Use the Visible property to control tab visibility.  Set this property to False to hide the tab.  Otherwise the tab is visible.

The default value of the Visible property is True.


TcxTab.VisibleIndex

TcxTab

Returns the tab’s visible index.

property VisibleIndex: Integer;

Description

Use the VisibleIndex property to determine the tab index in the visible tabs collection.  Indexes are zero-based.

If the tab is invisible, the VisibleIndex property returns –1.  Invisible tabs are not taken into account when calculating this property value.  Thus, if the first tab is invisible, the VisibleIndex property will return 0 for the second tab in the collection.

ReadOnly Property


TcxTab.VisibleRect

TcxTab          Concepts

Returns the rectangle occupied by the tab portion visible to a user.

property VisibleRect: TRect;

Description

If tabs are arranged into a single row and they don’t fit into the control’s area, certain tabs may be invisible to a user.  In such an instance, one of tabs can be partially visible.  Use the VisibleRect property to determine the rectangle occupied by the visible portion of the tab.  If the entire tab is visible to a user, the VisibleRect property returns the same value as the FullRect property.  If the entire tab is invisible, the VisibleRect returns an empty rectangle (all its coordinates are zeros).

Coordinates returned by the VisibleRect property are expressed in the coordinate system of the owner tab control.

ReadOnly Property


TcxTab.VisibleRow

TcxTab

Returns the visible index of the tab row that contains this tab.

property VisibleRow: Integer;

Description

Tabs are arranged within several rows if the following conditions are met:

•	The total width of visible tabs exceeds the width of the control;

•	The MultiLine property is set to True.

In such instances, you can read the tab’s VisibleRow property value to determine the zero-based visible index of the tab row containing the tab.

Note that tabs can change their visible order only if the ScrollOpposite property is set to False.  The following image displays an example of changing row order:

If the ScrollOpposite property is set to True, rows always have their initial order.  The image below illustrates this situation.

Note: tab row indexes are calculated from the top (from the left if the TabPosition property is set to tpLeft or tpRight).

ReadOnly Property


TcxTab.Create

TcxTab

Creates an instance of the TcxTab class.

procedure Create(ATabs: TcxTabs; Index: Integer);

Description

The Create method is used to instantiate the TcxTab object.  The ATabs parameter specifies the owning collection of tabs.  The position of a newly created tab object within the collection is specified by the Index parameter.

Do not create instances of the TcxTab class in applications.  Use the Add or Insert method of the TcxTabs class to add a new tab to the collection.


TcxTab.Destroy

TcxTab

Destroys the TcxTab object.

procedure Destroy; override;

Description

The Destroy method is used to dispose the TcxTab object and free any memory allocated.  This method notifies the owning collection of tab deletion before calling the inherited destructor.

Do not destroy TcxTab objects directly in applications.  Use the Delete or Remove methods of the TcxTabs object to remove a tab instead.


TcxTabs
TcxTabs Object

Hierarchy          Properties          Methods           See Also

Represents a collection of tabs in the TcxTabControl.

Unit

cxPC

TcxTabs = class(TStrings)

Description

The TcxTabControl control allows you to create and manage a set of tabs.  The collection of tabs is represented by the TcxTabs object and can be accessed via the Tabs property of the TcxTabControl object.

At design time the collection of tabs is created using the String List Editor, as displayed in the image below.  The entered strings are assigned to tab captions.

At runtime, you can access each individual tab represented by the TcxTab object.  Use its Tabs and VisibleTabs properties to access all the created and visible tabs, respectively.


TcxTabs Hierarchy
Hierarchy

TStrings

     |


Properties for TcxTabs
TcxTabs Properties

TcxTabs          Legend

In TcxTabs

TabNormalHeight

Tabs

VisibleTabs

VisibleTabsCount


Methods for TcxTabs
TcxTabs Methods

TcxTabs          Legend

In TcxTabs

 Clear

 Create

 Delete

 Destroy

 Insert


TcxTabs.TabNormalHeight

TcxTabs

Returns the minimum height required by a tab to fit its caption and image.

property TabNormalHeight: Integer;

Description

Use the TabNornalHeight property to read the minimum height a tab can have to fit its caption and image.  The value is returned in pixels.

ReadOnly Property


TcxTabs.Tabs

TcxTabs

Provides indexed access to tabs.

property Tabs[TabIndex: Integer]: TcxTab;

Description

Use the Tabs property to obtain the TcxTab object representing the specified tab.  Tabs are specified by their indexes within the collection via the Index parameter.  Indexes are zero-based.  If the Index parameter value is negative or greater than the last available index, an error is raised.  The last available index is always one less than the Count property value.


TcxTabs.VisibleTabs

TcxTabs

Provides indexed access to visible tabs.

property VisibleTabs[TabVisibleIndex: Integer]: TcxTab;

Description

Use the VisibleTabs property to access the tab which is currently visible within the TcxTabControl using the zero-based index which is specified by the TabVisibleIndex parameter.  If the TabVisibleIndex parameter’s value is negative or greater than the last available index, an error is raised.  The last available index is always one less than the total number of visible tabs which is accessible via the VisibleTabsCount property.

ReadOnly Property


TcxTabs.VisibleTabsCount

TcxTabs

Returns the number of tabs which are currently visible within the tab control.

property VisibleTabsCount: Integer;

Description

Use the VisibleTabsCount property to determine the number of tabs which are currently visible within the TcxTabControl.  Use the VisibleTabs property to access specific visible tab using its index.

ReadOnly Property


TcxTabs.Clear

TcxTabs

Clears the tab collection.

procedure Clear; override;

Description

Use the Clear method to remove all tabs from the tabs collection.


TcxTabs.Create

TcxTabs

Creates an instance of the TcxTabs class.

procedure Create(AParent: TcxCustomTabControl);

Description

The Create method is used to instantiate a TcxTabs object.  The AParent parameter specifies the tab control, to which the created tab collection will belong.

Do not create or destroy TcxTabs objects in applications.  They are created and destroyed automatically by tab controls whose Tabs property they represent.


TcxTabs.Delete

TcxTabs

Deletes the tab specified by its index.

procedure Delete(Index: Integer); override;

Description

Use the Delete method to remove the specified tab from the collection.  Tabs are specified by their indexes via the Index parameter.  Indexes are zero-based.

When an item is deleted, the following items are moved up in the collection.  The Count property is decremented.


TcxTabs.Destroy

TcxTabs

Destroys the TcxTabs object.

procedure Destroy; override;

Description

The Destroy method is used to dispose the TcxTabs object and free any allocated memory.  This method clears the collection of tabs and calls the inherited destructor.

Do not create or destroy TcxTabs objects in applications.  They are created and destroyed automatically by tab controls whose Tabs property they represent.


TcxTabs.Insert

TcxTabs

Inserts a tab with the specified caption to the specified position.

procedure Insert(Index: Integer; const S: string); override;

Description

Use the Insert method to add a new tab to the tabs collection.  The S parameter specifies the caption of the added tab.  Its value is assigned to the Caption property of a newly created TcxTab object.

The Index parameter specifies the position within the tabs collection to which a tab is inserted.  Indexes are zero-based.  If the Index parameter value is negative or greater than the last available index, an error is raised.  The last available index is specified by the Count property value.


TcxTabSheet
TcxTabSheet Object

Hierarchy          Properties          Methods          Events          See Also

Represents a page of the TcxPageControl control.

Unit

cxPC

TcxTabSheet = class(TCustomControl)

Description

Each page of the TcxPageControl control is represented by an individual control of the TcxTabSheet type.  Pages serve as containers for other controls, which are displayed when the corresponding tab is clicked.  The tab’s appearance and behavior can be controlled using the properties of the TcxTabSheet class.  For information on additional appearance options of tab controls, see the description of the tab control’s Options property.

The TcxTabSheet class provides two events that allow you to perform specific actions when a page becomes active or inactive.

Pages are accessed via the Pages property of the TcxPageControl control.  You can directly access the active page using the control’s ActivePage property.


TcxTabSheet Hierarchy
Hierarchy

TCustomControl

     |


Properties for TcxTabSheet
TcxTabSheet Properties

TcxTabSheet          Legend

In TcxTabSheet

BorderWidth

Highlighted

ImageIndex

PageControl

PageIndex

TabIndex

TabVisible

Derived from TControl

Caption

Color

Constraints

DragMode

Enabled

Font

Height

Left

ParentColor

ParentFont

ParentShowHint

PopupMenu

ShowHint

Top

Visible

Width


Methods for TcxTabSheet
TcxTabSheet Methods

TcxTabSheet          Legend

In TcxTabSheet

Create

Destroy


Events for TcxTabSheet
TcxTabSheet Events

TcxTabSheet          Legend

In TcxTabSheet

OnHide

OnShow

Derived from TControl

OnContextPopup

OnDragDrop

OnDragOver

OnEndDrag

OnEnter

OnExit

OnMouseDown

OnMouseMove

OnMouseUp

OnResize

OnStartDrag

Derived from TControl

 OnClick

 OnDblClick


TcxTabSheet.BorderWidth

TcxTabSheet

Specifies the page’s border width in pixels.

property BorderWidth: TBorderWidth;

Description

Use the BorderWidth property to specify the page’s borders width.  This property value is set in pixels.  Setting this property value to a greater value reduces the page’s client area and shifts all residing controls right and down.  Setting it to a lesser value enlarges the page’s client area and shifts all residing controls left and up.

The default value of the BorderWidth property is 0.


TcxTabSheet.Highlighted

TcxTabSheet

Specifies whether the corresponding tab is highlighted.

property Highlighted: Boolean;

Description

Use the Highlighted property to highlight the tab corresponding to this page.  Set this property to True for this purpose.  The colors of the highlighted tab are specified by system settings for the highlighted style elements.

Set the Highlighted property to False to remove highlighting from the page’s tab.

The following sample code handles the OnChange event of the TcxPageControl control to highlight the selected tab.

// Delphi

procedure TForm1.cxPageControl1Change(Sender: TObject);

var i: Integer;

begin

  for i := 0 to cxPageControl1.PageCount - 1 do

    cxPageControl1.Pages[i].Highlighted := False;

  cxPageControl1.ActivePage.Highlighted := True;

end;

The image below displays the result of handling the event.  The Alignment tab is selected.


TcxTabSheet.ImageIndex

TcxTabSheet          Concepts

Specifies the image displayed in the corresponding tab.

property ImageIndex: TImageIndex;

Description

Use the ImageIndex property to specify the tab image corresponding to the page.  The image is specified by its index within the source images collection.  The source of images is assigned via the Images property of the TcxPageControl control.

If the ImageIndex property is set to a value less than –1 or greater than the last available index, no image is displayed within the corresponding tab.


TcxTabSheet.PageControl

TcxTabSheet          Concepts

Specifies the owning page control.

property PageControl: TcxPageControl;

Description

Use the PageControl property to specify the page control, which owns the page.  This can be used to move the page from one page control to another or to add a newly created page to a page control.

The following sample code creates a new page and adds it to a page control.

// Delphi

var NewPage: TcxTabSheet;

// ...

NewPage := TcxTabSheet.Create(Form1);

with NewPage do

begin

  Caption := 'New Page';

  PageControl := cxPageControl1;

end;


TcxTabSheet.PageIndex

TcxTabSheet          Concepts

Specifies the page position within the pages collection.

property PageIndex: Integer;

Description

Use the PageIndex property to obtain or set the page index within the pages collection.  This property value specifies the order in which tabs are arranged.  The first available index is 0.

Setting the PageIndex property value to the index of another page swaps page indexes.  Trying to set this property to a value less than 0 or greater than the last available index causes an error.


TcxTabSheet.TabIndex

TcxTabSheet

Returns the tab visible index.

property TabIndex: Integer;

Description

Use the TabIndex property to obtain the corresponding tab ’s visible index.  This property value is zero-based.

If the page is not visible, the TabIndex property returns –1.  Invisible pages are not taken into account when calculating this property value.  Thus, if the first page is invisible, the TabIndex property will return 0 for the second page in the collection.

ReadOnly Property


TcxTabSheet.TabVisible

TcxTabSheet

Specifies whether the corresponding tab is visible.

property TabVisible: Boolean;

Description

Use the TabVisible property to control the visibility of the corresponding tab.  Set this property to True to hide the tab.  Otherwise it is visible.

Hiding a tab prevents a user from selecting it by means of the page control.  However, the page with the invisible tab can be selected via code.  Use the ActivePage property or SelectNextPage method for this purpose.

The default value of the TabVisible property is True.


TcxTabSheet.Create

TcxTabSheet          Concepts

Creates an instance of the TcxTabSheet class.

procedure Create(AOwner: TComponent); override;

Description

Use the Create method to create a new page at runtime.  The AOwner parameter specifies the owner of the generated page (typically, a form).  This method sets properties to their default values after calling the inherited constructor.


TcxTabSheet.Destroy

TcxTabSheet

Destroys the TcxTabSheet object.

procedure Destroy; override;

Description

The Destroy method is used to dispose of the TcxTabSheet object and free any memory allocated.  This method removes the destroyed page from the page control before calling the inherited destructor.

Do not use the Destroy method in applications.  Use the Free method instead.


TcxTabSheet.OnHide

TcxTabSheet          Concepts          See Also

Fires immediately after the page has been hidden.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnHide: TNotifyEvent;

Description

Handle the OnHide event to perform specific actions each time after the page has been temporarily hidden (i.e., its Visible property is set to False).  The Sender parameter specifies the page (TcxTabSheet object) whose visibility has been changed.


TcxTabSheet.OnShow

TcxTabSheet          Concepts          See Also

Fires immediately after the page has become visible.

type

  TNotifyEvent = procedure(Sender: TObject) of object;

property OnShow: TNotifyEvent;

Description

Handle the OnShow event to perform specific actions each time after the page has become visible (i.e., its Visible property is set to True).  The Sender parameter specifies the page (TcxTabSheet object) whose visibility has been changed.


Legend

 Protected

 Published

 ReadOnly


Tab Control Tutorial

This topic will guide you through the process of creating a simple application illustrating the basic capabilities of the TcxTabControl control.

Place the TcxTabControl onto a form first.

Click the ellipses ‘…’ button corresponding to the Tabs property.  A String List Editor dialog will appear.  Enter tab captions as displayed in the image below.  Click the OK button to close the dialog and save changes.

The result is as follows:

Place a TImageList component onto the form and add four images to it.

Assign the modified TImageList component to the Images property of the TcxTabControl control.  Images will be displayed within tabs in their order within the image list collection.

Place TLabel and TEdit controls onto the control’s page.  Set the label caption to ‘Selected tab index is:’.  Set the edit control’s text to an empty string.  This results in the following look & feel for the tab control.

Write an OnChange event handler as listed below.  It will update the edit control’s text when a tab is selected.

// Delphi

procedure TForm1.cxTabControl1Change(Sender: TObject);

begin

  Edit1.Text := IntToStr(cxTabControl1.TabIndex);

end;

Run the application.  Click tabs to select them.  The edit control will display the current page index.


Page Control Tutorial

This topic will guide you through the process of creating a simple application illustrating the basic capabilities of the TcxPageControl control.

Place a TcxPageControl onto a form first.

Right-click the control and click the New Page item of the context menu.  A new page with its tab will be created.

Add one more tab using the same technique.

Place a TImageList component onto the form and add two images to it.

Assign the modified TImageList component to the Images property of the TcxPageControl control.  Images will be displayed within tabs in their order within the image list collection.  Note that you must click a tab to activate it.  Otherwise the last added page’s properties are displayed within the Object Inspector window.

Switch the control to the first page by clicking the corresponding tab.  Click the page.  Page properties will be displayed in the Object Inspector window.  Set the Caption property of the page to ‘First Page’.

Place a TLabel control onto the page.  Set its caption to ‘The First Page Contents’.

Select the second page by clicking the corresponding tab.  Click the page in order to make its properties available.  Set the page’s Caption property to ‘Second Page’.  This is performed in the same way as for the first page.

Place a TEdit control onto the page.  Set its text to ‘The Second Page Index’.

Run the application.  Click tabs to see the contents of pages.


Using the Tab Control to Display Dataset Records

Follow the steps listed in this topic to create a simple application which uses the TcxTabControl control to display dataset records.  Tabs that display values of the bound dataset field will be added to the control.  Values of other fields will be displayed within the page.

•	Start a new application project.

•	Add a TDataSource component to the form.  Bind it to the Films table of the VideoCatalogDB database supplied with the ExpressQuantumGrid 4.  This example uses a TADOTable component for this purpose.

•	Add a TcxDBTextEdit control to the tab control’s page. Bind it to the TAGLINE field of the dataset as displayed in the image below.

•	Use the same technique to add the following editors and bind them to the listed fields:

•	One more TcxDBTextEdit editor.  Bind it to the YEAR field.

•	A TcxDBMemo control. Bind it to the PHOTOOUTLINE field.

•	A TcxDBImage control. Bind it to the PHOTO field.

•	Select the added TcxDBImage control.  Set its GraphicClassName property to TJPEGImage.  The Stretch property must be set to True to fit images into the control’s area.

After all the required controls have been added, the tab control will look as displayed below.

•	Handle the OnCreate event of the form to initialize the tabs with values from the CAPTION field.  Use the code below for this purpose.

// Delphi

procedure TForm1.FormCreate(Sender: TObject);

begin

  with ADOTable1 do

  begin

    while not Eof do

    begin

      // adding only captions whose length is less than 20 characters

      if Length(FieldByName('Caption').AsString) < 20 then

        cxTabControl1.Tabs.Add(FieldByName('Caption').AsString);

      Next;

    end;

    cxTabControl1.TabIndex := 0;

    First;

  end;

end;

•	Write the code that will navigate through dataset records when switching tabs.  Handle the OnChange event of the tab control for this purpose.  The handler code is listed below.

procedure TForm1.cxTabControl1Change(Sender: TObject);

var s: string;

begin

  s := cxTabControl1.Tabs.Tabs[cxTabControl1.TabIndex].Caption;

  ADOTable1.Locate('Caption', s, []);

end;

Since editors residing on the tab control’s page are bound to data, their content will be automatically updated when switching between tabs.

•	The last thing remaining is to set the tab control’s MultiLine property to True.  This will arrange dynamically added tabs across several rows.

After all the steps have been completed, run the application.  The tab control will have an appearance similar to that shown in the image below.


Navigator Bar Position and Visibility

This topic describes the ways in which the position and visibility of the navigator bar and the visibility of its constituent elements can be specified.  All the examples listed below are applicable to both the TcxTabControl and TcxPageControl controls.

First, it must be noted, that the navigator bar is displayed within the tab panel.  Thus, if the tab panel is invisible the navigator bar is also invisible.  So, if the HideTabs property is set to True, both elements will be hidden.

The second point is that the navigator bar is only visible when tabs are arranged into a single row (i.e. the MultiLine property is set to False).

The tab navigation buttons such as the Go Dialog and arrow buttons are visible only when at least one of its tabs is invisible.  That is, the total width of the tabs exceeds the width of the tab panel.  If the tab panel is oriented horizontally, its width is equal to the control’s width.  Otherwise, it’s the same as the control’s height.  The width of tabs is controlled by the TabWidth property.  Please refer to the Tabs Position and Arrangement topic for details.

The following sample code changes the width of tabs and assures that tabs are arranged across a single line.

// Delphi

with cxPageControl1 do

begin

  TabWidth := Width div 2;

  MultiLine := False;

end;

Execution of the code listed above will appear as follows:

As you can see, the Go Dialog and Close Button are not displayed within the navigator bar by default.  You should enable the pcoGoDialog and pcoCloseButton options in order to make these buttons visible.  The visibility of arrow buttons is controlled via the pcoNoArrows option.  Options are set by means of the Options property.

The following code hides arrow buttons and makes the Go Dialog visible.

// Delphi

cxPageControl1.Options := Options + [pcoGoDialog, pcoNoArrows];

The image below displays changes in the navigator bar’s look & feel after code execution:

Let’s now describe how you can control navigator bar position within the tab panel.  This is controlled via the NavigatorPosition property.  Values available for this property setting specify positions in two dimensions.  If the property is set to npLeftBottom (means left or bottom), the navigator bar will be displayed in the left portion of a horizontally oriented tab panel and in the bottom portion of a vertically oriented tab panel.  The position and orientation of the tab panel is controlled by the TabPosition property.

// Delphi

with cxPageControl1 do

begin

  TabPosition := tpRight;

  NavigatorPosition := npLeftBottom;

end;

Execution of the code listed above will appear as follows:


Displaying Images in Tabs

This topic describes how to display images within tabs.  The mechanism for implementing this feature for both the TcxTabControl and TcxPageControl are considered.

Each tab displayed by a tab control can display an image and text caption.  If you want to display images within tabs you must specify the source of these images.  You should assign a TImageList component, containing the desired images, to the Images property for this purpose.  After doing so, images are displayed in tabs in the order they were stored within the assigned image list.

The following sample code assigns images to tabs in their default order.  Note, that an image list component must exist for this purpose.

// Delphi

cxPageControl1.Images := ImageList1;

Tab controls allow you to assign any image from an assigned image list to any of its tabs.  The manner in which it is implemented is different for the TcxTabControl and TcxPageControl controls.  However, the common element is that you should assign the index of the desired image to the ImageIndex property of the object representing the desired tab.

The following sample code assigns images to tabs of the TcxTabControl control.  The ImageIndex property of TcxTab objects representing tabs is used for this purpose.

// Delphi

var i: Integer;

// ...

for i := 0 to cxTabControl1.Tabs.Count - 1 do

  cxTabControl1.Tabs.Tabs[i].ImageIndex := i;

The same can be implemented for the TcxPageControl control.  The ImageIndex property of TcxTabSheet objects representing pages is used for this purpose.

// Delphi

var i: Integer;

// ...

for i := 0 to cxPageControl1.PageCount - 1 do

  cxPageControl1.Pages[i].ImageIndex := i;

The last method of assigning images to tabs is by writing an OnGetImageIndex event handler.  This approach is the same for both controls.  The event fires for every tab each time the control is repainted.  It gives you the ability to assign an image to the current tab.  Note that writing an OnGetImageIndex event handler has the highest priority of all described methods.  Consider the following sample code:

// Delphi

procedure TForm1.cxPageControl1GetImageIndex(Sender: TObject; TabIndex: Integer; var ImageIndex: Integer);

begin

  ImageIndex := TabIndex;

end;

The three examples above don’t change the default image layout.

Note: You can change the width of borders surrounding tab images.  Use the ImageBorder property for this purpose.


Tab Position and Arrangement

This topic covers the methods used to customize tab position, orientation and arrangement.  It provides a number of ways to manipulate properties affecting tab layout to obtain the desired look & feel of the tab control.  All the examples below are applicable to both the TcxTabControl and TcxPageControl controls.

Let’s consider the TabPosition and Rotate properties of tab controls first.  The first one affects the position (and orientation) of the tab panel, while the second controls the orientation of individual tabs within it.  Thus tabs can be oriented vertically in the following two cases:

•	The tab panel is oriented horizontally (it is located at the top or at the bottom of the control) and the Rotate property is set to True;

•	The tab panel is oriented vertically (it is located to the left or to the right of the control) and the Rotate property is set to False.

You can also control tab caption text direction when a tab is oriented vertically.  Use the pcoTopToBottomText option for this purpose.  Note that options are set via the Options property.

In the following example, the tab panel is located at the bottom (thus, is oriented horizontally), the Rotate property is set to True (its tabs are oriented vertically) and the pcoTopToBottomText option is enabled (tab captions are written from top to bottom):

// Delphi

with cxPageControl1 do

begin

  TabPosition := tpBottom;

  Rotate := True;

  Options := Options + [pcoTopToBottomText];

end;

Execution of the code listed above will appear as follows:

By default every tab has the minimum width necessary to fit its caption and image.  However you can change the width of tabs via the TabWidth property.  (In fact, you can also change their height via the TabHeight property).  If there are too many tabs and they are too wide to fit into the tab control area, tab navigation buttons are displayed within the navigator bar.  Please refer to the Navigator Bar Position and Visibility topic for details.

Tab controls give you the ability to arrange tabs across several rows, so that each is always visible.  To do so, you must set the MultiLine property to True for this purpose.  Note, that tabs are stretched by default to occupy the entire width of the control.  Set the RaggedRight property to True to disable such behavior.

The following sample code changes the width of tabs, arranges them across several lines and disables their stretching along the control’s width.

// Delphi

with cxPageControl1 do

begin

  TabWidth := 130;

  MultiLine := True;

  RaggedRight := True;

end;

The image below displays the appearance of a tab control after code execution:

If tabs don’t appear as buttons, selecting a tab moves its row closest to the page.  The previously closest row becomes the furthermost.  However you can change this default behavior via the ScrollOpposite property.  If it is set to True, selecting a tab moves all rows located between the current row and the page to the opposite side of the control.

The following sample code arranges tabs across several lines and implements the described feature.

// Delphi

with cxPageControl1 do

begin

  MultiLine := True;

  ScrollOpposite := True;

end;

Execution of the code listed above will appear as follows:

Note: The total number of tab rows can be determined via the RowCount property.  If the ScrollOpposite property is set to True, you can also determine the number of rows residing on the left or top portion of the control (when the tab panel is oriented vertically or horizontally).  Use the TopOrLeftPartRowCount property to obtain this value.  Considering the image above, the RowCount property returns 2, while the TopOrLeftPartRowCount property returns 1.


Handling Multiple Selections

The TcxTabControl control allows an end-user to select multiple tabs.  This topic describes the way to implement this feature.  It also covers the ways of selecting multiple tabs in code and determining which tabs are selected.

The following conditions must be met to enable the multi select feature:

•	The MultiSelect property of the TcxTabControl must be set to True (this condition is not necessary when selecting multiple tabs in code);

•	The buttons painting style or flat buttons painting style must be applied to the control.  Please refer to the Applying Painting Styles topic for details on implementing various painting styles.

If the conditions above are satisfied, end-users can select multiple tabs when holding the CTRL key pressed.  Clicking a selected tab when the CTRL key is pressed deselects the tab.

The following sample code provides a multi select feature to the end-users:

// Delphi

with cxTabControl1 do

begin

  MultiSelect := True;

  SetStandardStyle(tsButtons);

end;

The Selected property of the TcxTab object specifies whether the tab is selected.  The following sample code deselects all tabs and then selects the first and third tabs.  Note that it is necessary to set the TabIndex property to –1 in order to deselect the main tab:

// Delphi

var i: Integer;

// ...

with cxTabControl1 do

begin

  TabIndex := -1;

  for i := 0 to Tabs.Count - 1 do

    Tabs[i].Selected := False;

  Tabs[0].Selected := True;

  Tabs[2].Selected := True;

end;

The Selected and IsMainTab properties of the TcxTab object are used to determine the selected and main tabs.  If the IsMainTab property returns True, the corresponding tab is the main tab.  Note, that the Selected property returns False for the main tab.

// Delphi

var i: Integer;

// ...

with cxTabControl1 do

begin

  for i := 0 to Tabs.Count - 1 do

  begin

    if Tabs[i].Selected then

    begin

      // selected tab

    end;

    if Tabs[i].IsMainTab then

    begin

      // main tab

    end;

  end;

end;


Custom Painting

Both tab and page controls enable you to custom paint tabs.  This topic describes the ways in which to do so.

First, you will need to set the OwnerDraw property to True to enable tab custom painting then handle the OnDrawTab event which fires for each tab within the control every time it needs to be repainted.

The code below represents an OnDrawTab event handler.  It fills the background of tabs with a texture brush.  The ‘texture.bmp’ file for used to initialize the brush must reside in the same folder as the project.  A blue rectangle is painted around the main tab.  The caption of the main tab is painted using a bold font.

procedure TForm1.cxTabControl1DrawTab(AControl: TcxCustomTabControl;

  ATab: TcxTab; var DefaultDraw: Boolean);

var

  R: TRect;

  Bitmap: TBitmap;

  ABrush: TBrush;

begin

  // creating a brush

  Bitmap := TBitmap.Create;

  Bitmap.LoadFromFile('texture.bmp');

  ABrush := TBrush.Create;

  ABrush.Bitmap := Bitmap;

  with AControl.Canvas do

  begin

    R := ATab.VisibleRect;

    // painting the focus rectangle

    if ATab.IsMainTab then

    begin

      FrameRect(R, clBlue);

      InflateRect(R, -1, -1);

      FrameRect(R, clBlue);

      InflateRect(R, -1, -1);

    end;

    // painting the background

    Windows.FillRect(Handle, R, ABrush.Handle);

    // painting the tab caption

    Font.Color := clBlack;

    if ATab.IsMainTab then

      Font.Style := [fsBold];

    Brush.Style := bsClear;

    DrawText(ATab.Caption, R, cxAlignHCenter);

    Brush.Style := bsSolid;

    Font.Style := [];

  end;

  Bitmap.Free;

  ABrush.Free;

  // prohibiting default painting

  DefaultDraw := False;

end;

Execution of the code listed above will appear as follows:

You can also use a more simple technique to customize the appearance of individual tabs.  The OnDrawTabEx event enables you to change the font applied to each individual tab caption.  Note that this event also fires only if the OwnerDraw property value is True.

The following code is the handler of the OnDrawTabEx event.  It is used to display the active page’s tab using a bold font.

procedure TForm1.cxTabControl1DrawTabEx(AControl: TcxCustomTabControl;

  ATab: TcxTab; Font: TFont);

begin

  if ATab.IsMainTab then

    Font.Style := [fsBold];

end;

Execution of the code listed above will appear as follows:


Managing the Tabs Collection

The TcxTabControl control maintains a collection of tabs.  This topic covers the ways in which to manipulate tabs in the collection.

First of all it is worth noting that the tabs collection owned by the TcxTabControl control is represented by the Tabs property.  Let’s consider the manner in which tabs are added and inserted into the collection - Add and Insert are used for this purpose.  The following sample code adds three tabs to the TcxTabControl control.

// Delphi

with cxTabControl1.Tabs do

begin

  Add('First Tab');

  Add('Second Tab');

  Insert(0, 'Third Tab');

end;

Execution of the code listed above will appear as follows:

Tabs can be deleted from the collection via the Delete method of the TcxTabs object.  The following code deletes the first tab and the tab with caption ‘First Tab’.

// Delphi

with cxTabControl1.Tabs do

begin

  Delete(0);

  Delete(IndexOf('First Tab'));

end;

Execution of the code listed above will appear as follows:

Note that you can also use the Clear method to remove all tabs from the collection.


Managing the Pages Collection

The TcxPageControl control maintains a collection of pages.  This topic covers the ways in which to manipulate tabs in the collection.

First of all, it is worth noting that each page is represented by a TcxTabSheet control.  The PageControl property of this object specifies the control to which a page belongs.  Thus it is necessary to create a new TcxTabSheet object and set its PageControl property in order to add it to the desired page control.

For instance, you can declare the following procedure that adds a new page with the specified caption to the specified control.

// Delphi

procedure AddPage(ACaption: string; AControl: TcxPageControl);

var NewPage: TcxTabSheet;

begin

  NewPage := TcxTabSheet.Create(AControl.Owner);

  NewPage.PageControl := AControl;

  NewPage.Caption := ACaption;

end;

You can now use the following sample code to add three pages to a page control.

// Delphi

AddPage('First Page', cxPageControl1);

AddPage('Second Page', cxPageControl1);

AddPage('Third Page', cxPageControl1);

The image below displays the result of code execution:

The order of pages can be changed via the PageIndex property of the TcxTabSheet object.  Note, that pages are accessed via the Pages property of the TcxPageControl control.  The total number of pages is returned by the PageCount property.

The following sample code moves the last added page to the first position.

// Delphi

cxPageControl1.Pages[2].PageIndex := 0;

Execution of the code listed above will appear as follows:

There are two ways to remove pages from a page control.  The first is to set the PageControl property of the TcxTabSheet object to nil.  The second is to destroy the page via the Free method.

The following sample code removes the first and the last pages.

// Delphi

cxPageControl1.Pages[2].PageControl := nil;

cxPageControl1.Pages[0].Free;

Execution of the code listed above will appear as follows:


Applying Painting Styles

Tab controls support various painting styles.  There are nine predefined styles and XP painting style provided by both the TcxPageControl and TcxTabControl controls.  This topic describes how you can apply these predefined painting styles to controls.  It also contains information regarding what can and what cannot be implemented when a certain style is applied.

Applying Painting Styles

Two properties can be used at design-time to specify the painting style applied to a control.  These are the LookAndFeel and Style properties.  The LookAndFeel property returns an object that has four properties affecting the look & feel of the control: AssignedValues, Kind, NativeStyle, and SkinName.

The AssignedValues property specifies whether the Kind, NativeStyle, and SkinName properties are available.  Its value is a set that can include lfvKind, lfvNativeStyle, and lfvSkinName.  If an empty set is assigned to this property, the painting style applied to the control specified by the Style property.

The value of the Style property can be changed by calling the SetStyleByStyleName and SetStandardStyle methods.  The table below lists the correlation between the Style property values and parameters of these methods.

Style property’s values	SetStyleByStyleName method parameters	SetStandardStyle method parameters	Description
0	‘Default’	-	Applies the Flat Painting Style to the control.
1	‘Tabs‘	tsTabs	Applies the Tabs Painting Style to the control.
2	‘Buttons‘	tsButtons	Applies the Buttons Painting Style to the control.
3	‘FlatButtons‘	tsFlatButtons	Applies the Flat Buttons Painting Style to the control.
5	‘ExtraFlat‘	-	Applies the Extra Flat Painting Style to the control.
6	‘UltraFlat’	-	Applies the Ultra Flat Painting Style to the control.
7	‘Flat’	-	Applies the Flat Painting Style to the control.
8	‘Office11’	-	Applies the Office11 Painting Style to the control.
9	‘Slanted’	-	Applies the Slanted Painting Style to the control.
10	‘OneNote’	-	Applies the OneNote Painting Style to the control.
11	‘Skin’	-	Applies the Skin Painting Style to the control.

For instance, the following code lines are equivalent:

// Delphi

cxTabControl1.Style := 2;

cxTabControl1.SetStandardStyle(tsButtons);

cxTabControl1.SetStyleByStyleName('Buttons');

The Kind property of the look & feel object has influence on the control’s style only if the Style property is 0 (‘Default’) and the lfvKind value is contained in the AssignedValues property.  The table below lists painting styles corresponding to the Kind property values in such an instance.

Kind property’s values	Description
lfStandard	Applies the Tabs Painting Style to the control.
lfFlat	Applies the Flat Buttons Painting Style to the control.
lfUltraFlat	Applies the Ultra Flat Painting Style to the control.
lfOffice11	Applies the Office11 Painting Style to the control.

The NativeStyle property value is also in effect only when the default style is applied by the Style property and the lfvNativeStyle value is contained in the AssignedValues property.  The NativeStyle property overrides all other settings in this instance.  It applies the XP Painting Style to the control if the end-user’s operating system is Windows XP.  Otherwise, the Tabs Painting Style is applied.

Style Features

The selecting multiple tabs feature is available when the buttons painting style or flat buttons painting style is applied.  To allow multiple tabs to be selected at the same time, set the MultiSelect property to True.  Refer to the Handling Multiple Selections topic for details on this feature.

If tabs don’t appear as buttons, tab rows can be scrolled to opposite sides of a control.  The ScrollOpposite property must be set to True to implement this feature.  Refer to the Tab Position and Arrangement topic for details.


Navigating through Tabs

The TcxTabControl control maintains a collection of tabs, which can be selected by a user.  This topic covers the ways to select tabs in code.  It also describes events, which fire before or after a tab has been selected.

You can select a tab in code by setting the TabIndex property of the tab control to the desired tab index.  The following sample code gets the index of the ‘Alignment’ tab and selects it.

// Delphi

with cxTabControl1 do

  TabIndex := Tabs.IndexOf('Alignment');

If multiple tabs can be selected, the TabIndex property specifies the main tab index.  The Selected property of a particular TcxTab object specifies whether the corresponding tab is selected.  Please refer to the Handling Multiple Selections topic for details.

The OnChanging and OnChange events of the tab control fire immediately before and after a tab has been selected.  You can use an OnChanging event handler to restrict tab selection when certain conditions are met.  Consider the following sample code, which simply prohibits tab changes if the current tab index is 1.

// Delphi

procedure TForm1.cxTabControl1Changing(Sender: TObject;

  var AllowChange: Boolean);

begin

  if cxTabControl1.TabIndex = 1 then AllowChange := False;

end;


Navigating through Pages

The TcxPageControl control maintains a collection of pages, which can be selected by a user by clicking corresponding tabs.  This topic covers the ways in which to select pages in code.  It also describes events which fire before or after a page has been selected.

You can select a page by setting the ActivePage property to the TcxTabSheet object representing the desired page.  The same can be achieved by setting the ActivePageIndex property to the desired page index.  The following two lines of code are equivalent:

// Delphi

cxPageControl1.ActivePageIndex := 1;

cxPageControl1.ActivePage := cxPageControl1.Pages[1];

Note: Setting the described properties can result in activating a page, whose tab is invisible (the TabVisible property of the corresponding TcxTabSheet object is False).  All visible tabs become deselected in such a case.

Another way of selecting pages is using the SelectNextPage method of the TcxPageControl control.  It allows you to select the previous or next page to that currently selected.  The following line of code selects the next page.  Pages with invisible tabs are ignored when searching since the method’s second parameter is not specified.

// Delphi

cxPageControl1.SelectNextPage(True);

The OnChanging and OnChange events of the tab control fire immediately before and after a page has been selected.  These are derived from the TcxCustomTabControl class.  The TcxPageControl class introduces an OnPageChanging event which fires before the active page changes.  The OnChanging and OnPageChanging events can be used to prohibit navigation.  Consider the following code, which restricts navigation to the first page.

// Delphi

procedure TForm1.cxPageControl1PageChanging(Sender: TObject;

  NewPage: TcxTabSheet; var AllowChange: Boolean);

begin

  if NewPage.PageIndex = 0 then AllowChange := False;

end;

You can also perform specific actions when a page becomes active or inactive.  Use the OnShow or OnHide event of the TcxTabSheet object for this purpose.


Traversing through Tabs and Pages

The TcxTabControl and TcxPageControl controls maintain collections of tabs and pages respectively.  This topic describes the ways to traverse through these collections in order to access each page/tab.

First, let’s consider the way in which to visit each tab of the TcxTabControl control.  Its tabs collection is represented by the Tabs property, which is of type TcxTabs.  The Tabs property of this class provides indexed access to individual tabs.  The Count property returns the total number of tabs in the collection.  Consider the code example below:

// Delphi

var

  CurrTab: TcxTab;

  i: Integer;

// ...

for i := 0 to cxTabControl1.Tabs.Count - 1 do

begin

  CurrTab := cxTabControl1.Tabs[i];

  // ...

end;

It must be noted here, that the following two lines of code are of identical effect:

// Delphi

CurrTab := cxTabControl1.Tabs[i];

CurrTab := cxTabControl1.Tabs.Tabs[i];

Let’s now consider how to traverse through the pages of the TcxPageControl control.  This involves using the Pages property to access individual pages by their indexes.  The total number of pages is determined via the PageCount property.  Consider the code below:

// Delphi

var

  CurrPage: TcxTabSheet;

  i: Integer;

// ...

for i := 0 to cxPageControl1.PageCount - 1 do

begin

  CurrPage := cxPageControl1.Pages[i];

  // ...

end;

The TcxPageControl control provides you one more way to traverse through its pages.  The FindNextPage method is used for this purpose.  The following sample code iterates backward through every page in starting from the current page.

// Delphi

var

  CurrPage: TcxTabSheet;

  StartIndex: Integer;

// ...

StartIndex := cxPageControl1.ActivePageIndex;

CurrPage := cxPageControl1.ActivePage;

repeat

  CurrPage := cxPageControl1.FindNextPage(CurrPage, False, False);

  // ...

until CurrPage.PageIndex = StartIndex;


Terms List

Main Tab

Navigator Bar

Go Dialog

Close Button

Page

Selected Tab

Tab

Tab Caption

Tab Image

Tab Panel

Tab Row

Painting Style

Buttons Painting Style

Flat Buttons Painting Style

Tabs Painting Style

Flat Painting Style

Extra Flat Painting Style

Ultra Flat Painting Style

Office11 Painting Style

OneNote Painting Style

Slanted Painting Style

XP Painting Style

Skin Painting Style


Go Dialog

Terms List

The Go Dialog is a part of the navigator bar.  It is represented by a dropdown window, which is invoked by clicking the down arrow button.  The dropdown contains a list of all pages.  Clicking the page name activates the corresponding page.

The image below displays the Go Dialog in action:

Note that the Go Dialog can only be accessed when the navigator bar is visible and the pcoGoDialog option is enabled.  Options are set via the Options property of individual tab controls.

Review the Navigator Bar Position and Visibility topic for more information.


Navigator Bar

Terms List

Navigator Bar is a visual element of tab controls.  It contains three separate sections.

•	The first section is the button invoking the Go Dialog. This dialog allows you to navigate directly to the required page.

•	The second section holds arrow buttons used to navigate to the next/previous tab.  Clicking these buttons doesn’t change the selected page – they are used only to scroll tabs.

•	The third section is the Close Button which lets end-users close the currently selected tab/page and remove it from the tabs/pages displayed within a tab control.

The image below displays a Navigator Bar and its constituent parts:

Note that the Navigator Bar is only visible if tabs are displayed in a single row (the Multiline property is set to False).  Set the pcoGoDialog, pcoNoArrows and pcoCloseButton options via the Options property of tab controls to control the visibility of Navigator Bar elements.

Note:	the Go Dialog and arrow buttons will be displayed only when tabs don’t fit into the tab’s control area.

Please refer to the Navigator Bar Position and Visibility topic for more information regarding Navigator Bar position and visibility.


Page

Terms List

Pages are container controls that represent the contents of tab controls.  Tab controls (TcxTabControl object) contain a single page, whose context is to be updated each time the selected tab changes.  Page controls (TcxPageControl object) contain the number of pages equal to the number of tabs.


Close Button

Terms List          See Also

The Close Button is displayed within the navigator bar and lets end-users close the currently selected tab/page and remove it from the tabs/pages displayed within a tab control.

Note that the Close Button is only visible if tabs are displayed in a single row (the MultiLine property is set to False) and the pcoCloseButton option is set via the Options property of the tab control.


Tab

Terms List          See Also

Tabs are visual elements of tab controls.  Their purpose is to identify pages and switch between them.  Once a tab is clicked, the corresponding page is selected.

Tab visibility is controlled by the HideTabs property of tab controls.


Tab Caption

Terms List          See Also

Tab Caption is text displayed within a tab.  You can assign captions to each of the tabs in a tab control.  For the TcxTabControl control, tab captions are assigned via the Tabs property.  For the TcxPageControl control, these are assigned via the Caption property of TcxTabSheet objects representing pages.


Tab Image

Terms List          See Also

Tab Image is an image displayed within a tab.  Please refer to the Displaying Images in Tabs topic for information on how to display images within tabs.


Tab Panel

Terms List          See Also

Tab Panel is an area containing tabs and the navigator bar (if visible).

If tabs are arranged across several rows (the MultiLine property value is True) and the ScrollOpposite property is set to True, tab panel can be represented by two sub-panels located on the opposite sides of a tab control.


Tab Row

Terms List          See Also

Tabs can be arranged into a number of rows.  Such an arrangement takes place when the MultiLine property value is True and the total width of tabs exceeds the control’s width.  Tab width can be modified via the TabWidth property.

Tab panel can also be vertically oriented.  In such an instance, the total width of tabs must exceed the control’s height in order to arrange tabs across a number of rows.


Painting Style

Terms List

Tab controls can be painted a number of different ways.  There are nine predefined painting styles provided.  Seven of them paint tabs as notebook tabs with various forms.  Two painting styles represent tabs as buttons.  Windows XP users can also apply the XP style to tab and page controls.

Review the following topics for details on each of the styles:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on applying various painting styles.


Tabs Painting Style

Terms List

When the Tabs painting style is applied to a tab control, its tabs are painted as notebook tabs.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Flat Painting Style

Terms List

As with the Tabs painting style the tabs of a tab control with the Flat painting style applied are painted as notebook tabs, but appear lowered slightly.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Extra Flat Painting Style

Terms List

When the Extra Flat painting style is applied to a tab control, the selected tab is painted as a notebook tab.  Other tabs are painted flat.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Ultra Flat Painting Style

Terms List

When the Ultra Flat painting style is applied to a tab control, the selected tab is painted as a plain notebook tab.  Other tabs are painted flat.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Buttons Painting Style

Terms List

When the Buttons painting style is applied to a tab control, the selected tab is painted as a pressed button.  Other tabs are painted as released buttons.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Slanted Painting Style

Terms List          See Also

When the Slanted painting style is applied to a tab control tabs appear slanted.  The selected tab’s top edge is highlighted.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Flat Buttons Painting Style

Terms List

When the Flat Buttons painting style is applied to a tab control, the selected tab is painted as a pressed button.  Other tabs are painted flat.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Office11 Painting Style

Terms List          See Also

Applying the Office11 painting style to a tab control gives an Office 2003 appearance to its tabs.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


OneNote Painting Style

Terms List          See Also

Applying the OneNote painting style to a tab control gives a OneNote 2003 appearance to its tabs.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


XP Painting Style

Terms List

If you use Windows XP, you can apply the XP painting style to a tab control.

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Skin Painting Style

Terms List

Applying the Skin painting style allows you to use skins from the ExpressSkins Library (purchased separately).

There are nine other predefined painting styles provided by tab controls:

•	Tabs Painting Style;

•	Buttons Painting Style;

•	Flat Buttons Painting Style;

•	Flat Painting Style;

•	Extra Flat Painting Style;

•	Ultra Flat Painting Style;

•	Office11 Painting Style;

•	OneNote Painting Style;

•	Slanted Painting Style;

•	XP Painting Style;

•	Skin Painting Style.

Please refer to the Applying Painting Styles topic for details on implementing various painting styles.


Main Tab

Terms List          See Also

A user can select multiple tabs.  Please refer to the Handling Multiple Selections topic for details on this feature’s implementation.

When selecting several tabs, the first selected tab is considered to be the main selection.  The main tab differs in appearance from other selected tabs.  Review the image below for an explanation:


Selected Tab

Terms List          See Also

When a user clicks a tab, the tab is selected.  The only exclusion is clicking a disabled tab, since such tabs don’t respond to user clicks.

If tabs don’t appear as buttons, only a single tab can be selected at a given time.  Review the image below for an explanation:

An end-user can also select multiple tabs.  In such an instance, a main tab exists among those selected.  Please refer to the Handling Multiple Selections topic for details on this feature’s implementation.

The image below displays an example of selecting several tabs at once.


Tab Control Overview

Tab Control Tutorial

The tab control contains a set of tabs and a client area.  The client area of the control can contain any number of other controls.  Note that unlike the page control, the tab control’s client area is a single panel.  Thus, you cannot specify different page contents for different tabs (unless you change the page content dynamically in code).

The tab control is most likely to be used if you want the same set of controls to be displayed within its page.  The content of controls can be dynamically changed by handling the OnChange event.  Thus, one of the common applications of the tab control is to display dataset records.  Tabs display values of the dataset field that can identify a record.  Controls within the page display values of other fields from the selected record.  Please refer to the Using the Tab Control to Display Dataset Records topic for an example of using the tab control in this manner.  The image below displays the tab control after completing the steps listed in that topic.

You can also create more complex structures using the tab control.  See the image below for an example of using the tab control within other tab controls.

Tab and page controls give you approximately the same feature set.  With these controls you can:

•	display tabs on each side of the control;

•	arrange tabs across several rows;

•	change tab orientation with respect to the control;

•	use the Go Dialog to navigate through tabs;

•	use the Close Button to close the currently selected tab and remove it from the tabs displayed within the tab control;

•	display images within tabs;

•	use 9 predefined painting styles and XP painting style;

•	custom paint tabs;

•	and much more.


Page Control Overview

Page Control Tutorial

The page control provides the same features as the tab control.  It also contains a set of tabs and a client area.  The only difference is that the page control provides a separate page panel for each tab within it.  Thus, you can customize the content of each page separately by dropping controls onto it.  When switching between tabs, the control automatically displays the corresponding page.

Use the page control if you need different set of controls to reside on each separate page.  Using this control allows you to break controls needed in your application into categories.  This also enables you to save space on the form.  See the image below for examples of using the page control.

Tab and Page controls provide you approximately the same feature set.  With the controls you can:

•	display tabs on each side of the control;

•	arrange tabs across several rows;

•	change tab orientation with respect to the control;

•	use the Go Dialog to navigate through tabs;

•	use the Close Button to close the currently selected page and remove it from the pages displayed within the page control;

•	display images within tabs;

•	use 9 predefined painting styles and XP painting style;

•	custom paint tabs;

•	and much more.