TPageControl

Description

Provides a set of pages used to make a multiple page dialog box.

Remarks

Use TPageControl to create a multiple page dialog. TPageControl displays multiple overlapping pages that are TTabSheet controls. The user selects a page by clicking the page's tab that appears at the top of the control.

When using this control using the ScriptIDE, you can add a new page to a TPageControl object at design time, by right-clicking the TPageControl control and choosing New Page.

TPageControl Properties

Property ActivePage: Tabsheet object (R/W)

Specifies the page currently displayed by the page control. Read ActivePage to determine which page is selected by the user. The user selects a page by clicking the mouse on its tab. Set ActivePage to bring a page to the foreground. Only one page can be active at a time. To change the ActivePage to the page that precedes or follows the active page, use the SelectNextPage method.

Property ActivePageIndex: Integer (R/W)

Specifies the page currently displayed by the page control. Use ActivePageIndex to get or set the active page by index rather than by object. The value of ActivePageIndex identifies a page in the Pages property array. Changing the value of ActivePageIndex changes the ActivePage property, and vice versa. If there is no active page, reading ActivePageIndex gives a value of -1. Setting ActivePageIndex to a value that is out of bounds (less than 0 or greater than PageCount - 1) results in the page control having no active page.

Property PageCount: Integer (R)

Indicates the number of pages in the TPageControl object. Use PageCount to determine the number of pages listed by the Pages property. If the MultiLine property is false, not all pages may have tabs visible to the user.

Property Pages(Index: Integer): TTabsheet object (R)

Lists all the pages in the TPageControl. Use Pages to gain direct access to a particular page in the page control. For example, use Pages to disable individual pages in the page control. Specify which page to access using Index, where an Index of 0 specifies the first page, an Index of 1 specifies the second page, and so on. Each page is a TTabSheet object.

Note: Pages is a read-only property. To add a tab sheet to a page control at design time, right click and select New Page. To add a tab sheet to a page control at runtime, create the tab sheet and set its PageControl property to the page control.

Property HotTrack: Boolean (R/W)

Determines whether labels on the tab under the mouse are automatically highlighted. Set HotTrack to true to provide visual feedback to the user about which tab would be selected if the mouse button is clicked. HotTrack is especially useful when the tab control contains multiple rows of tabs.

Property MultiLine: Boolean (R/W)

Determines whether the tabs can appear on more than one row. Use MultiLine to determine how the tabs are displayed. If MultiLine is true, the tabs are displayed on more than one row when the number of tabs exceeds the number that fits across the top of the tab control. How many rows is determined by how many tabs are in the tab control. If MultiLine is false, the tabs are displayed on one row only, and the user must scroll the displayed scroll arrows to view all the tabs.

Property Style: Enumeration (tsTabs, tsButtons, tsFlatButtons) (R/W)

Specifies the style of the page control. Use Style to determine the appearance of the tabs. These can appear as notebook tabs or as buttons.

Property TabHeight: Integer (R/W)

Specifies the height, in pixels, of the tabs in the tab control. Set TabHeight to control the height of the tabs that appear above the client region of the tab control. The TabHeight property is the vertical size in pixels of the individual tabs. If TabHeight is set to 0, the tabs automatically size themselves to fit their text.

Property TabIndex: Integer (R/W)

Identifies the selected tab on a tab control. Read TabIndex to determine which tab was selected by the user. TabIndex is the index of the tab in the list of labels maintained by the Tabs property. The first (leftmost) tab has a TabIndex of 0, the next has 1, and so on. If no tabs are selected, TabIndex has a value of -1. Set TabIndex to programmatically change the selected tab in the tab control.

Property TabPosition: Enumeration (tpTop, tpBottom, tpLeft, tpRight) (R/W)

Set TabPosition to tpTop to display the tabs at the top of the tab control. Set TabPosition to tpBottom to display the tabs at the bottom. If the ScrollOpposite property is true, tabs can appear at both top and bottom, with the row containing the current tab and all subsequent rows on the side indicated by TabPosition. Due to a limitation in the windows common control, if TabPosition is tpLeft or tpRight, Font must be a True Type font. Otherwise, tab text may paint incorrectly.

Property TabWidth: Integer (R/W)

Specifies the horizontal size, in pixels, of the tabs in the tab control. TabWidth specifies a fixed width for all tabs. If TabWidth is 0, then each tab is automatically made wide enough to show its caption.

TPageControl Methods

Method NewPage: TTabSheet

Call NewPage to create a new tabsheet in the page control. NewPage returns the new created tabsheet.

Method SelectNextPage(GoForward: Boolean)

Changes the ActivePage to the first visible page that is before or after the currently active page. Use SelectNextPage to select the page next to the currently active page.

If the GoForward parameter is true, SelectNextPage selects the first page after ActivePage; if GoForward is false, SelectNextPage selects the first page previous to ActivePage.

Note: To select a page at design-time, right-click the TPageControl and choose Previous Page or Next Page.

TPageControl Events

Event OnChange

Occurs after a new tab is selected. Write an OnChange event handler to take specific action immediately after the selected tab changes. Use the TabIndex property to determine which tab is now selected. This is the opportunity to make any changes to the control that reflect the new state implied by the selected tag. Before the value of TabIndex changes, an OnChanging event occurs.

Event OnChanging

Occurs immediately before a new tab is selected. Write an OnChanging event handler to take specific action immediately before the selected tab changes. Set the AllowChange parameter to false to prevent the change. Use an OnChanging event handler to prevent the user from leaving a tab setting until certain conditions have been met. An OnChanging event handler can also be used to save information about the current state of the tab control before it is changed by a new tab selection.