[Up] | Reference for unit 'ExtCtrls' (#lcl)

## Multi-PageControls - controls that offer a selection of alternative pages for display

Multi-PageControls - controls that offer a selection of alternative pages for display

A number of controls, found in Units ExtCtrls and ComCtrls, offer the ability to create multi-page forms with a series of Tabs along one edge that allow the user to select one of the Pages for display and interaction.

These include: TPageControl, TNoteBook, TTabControl and THeaderControl (the Header Control components have a very different structure and function). Icons for all of these exist on the Additional or Common Controls tabs of the Component Palette in the Lazarus IDE.

While the various components may look superficially similar, they differ in properties, inheritance, method of adding additional pages, behaviour at run-time, methods for referencing pages and so on.

We have to be very clear when using the various properties, to distinguish between the word 'Tab' as referring to a Tab indicating an identifier for a page, and 'Tab' as referring to the TAB key on the standard keyboard. In common with most Lazarus components, it is possible to enable each control to be included in the TabOrder of TabStops for a Form, so that the component can be reached by repeated pressing of the TAB key, and we must not confuse this use of 'Tab' with the use to denote a Page.

The properties CanTab, TabStop and TabOrder refer to the use of the TAB key to navigate to the relevant control.

Properties such as Tabs, TabIndex, IndexOfTabAt(), TabIndexAtClientPos(), TabPosition, TabHeight, TabWidth, TabVisible, OnCloseTabClicked refer to the use for Page selection.

TNoteBook and TPageControl are both descended from TCustomNoteBook (which is in turn descended from TWinControl) and have many inherited properties in common. TPageControl has, in general, more advanced features and is probably intended to replace TNoteBook.

The following table summarises the main differences between the two components.

Property or method | TNoteBook | TPageControl
--- | --- | ---
Pages, ActivePage | String, TPage | TTabSheet, a more advanced version of TPage
Drag/Drop/Dock | Drag properties, but minimal Dock or Drop | Full Drag, Drop, Dock properties and methods
Indexing | PageIndex | ActivePageIndex, TabIndex
Showing/Hiding Tabs | ShowTabs | TabVisible in TTabSheet
Hints | No Hinting methods | ShowHint, ParentShowHint
Font | No Font properties | Font, ParentFont
Sensing position of Tab | None | TabPosition, OnGetSiteInfo
Options | Published property Options, include nboShowCloseButtons, nboMultiLine | No published Options property, but inherits Options (public property) from TCustomNoteBook, so they could be set explicitly in code

The individual Pages in both of the above controls (descended from TCustomNoteBook) are separate and can have their own specific collections of widgets which appear only when the relevant Page is selected by its Tab.

In contrast, the TTabControl component (descended from TCustomTabControl) has only one display area (Protected property DisplayRect), but the image displayed in it is determined by which tab has been selected. Each Tab has an index value which is used to select the appropriate image from an indexed ImageList and display it in the Display Rectangle.

The properties of the Tabs in TTabControl are very configurable compared with those in the controls derived from TCustomNoteBook, allowing for instance the creation of multi-line captions, the placement of images on Tabs, the possibility of the Owner routine determining the drawing of the tab, the configuration of Tab size, the selection of multiple tabs. The trade-off is that the display area is restricted in what it can display, and is essentially confined to display of images.

To use any of the above controls, select them from the relevant tab on the IDE Component Palette and drop them on the form in the required position. Fill in as many relevant properties as you can in the Object Inspector.

To add Tabs or Pages to the controls, select the control with a left mouse click or by selecting from the Component menu in the Object Inspector, then right-click on the component to get a pop-up menu, whose first item will be 'Add Page' or 'Add Tab'.

The Tabs in TTabControl can be edited by selecting 'Tabs' in the Object Inspector, clicking on the ellipsis (...) and using the string editor that pops up.

The pages inTNoteBook or TPageControl can be edited by selecting the ActivePage in the Object Inspector and then editing the properties of the individual page.

THeaderControl offers a widget that could be placed along the edge of a Panel or Form, allowing a highly customised mechanism for selection. However, there are no intrinsically associated display areas, and it is the developer's responsibility to supply an index associated with the selection from the THeaderControl and determining what action is to occur or what is to be displayed in any attached Panel or Form.

When the control is first selected from the Component Palette and placed on a Form, it consists of an unadorned rectangle. However, selecting the control and right-clicking (or selecting the 'Sections' property in the Object Inspector) gives access to a Sections editor (a StringList editor) and Sections can be added to the control. The sections are separated by vertical lines, and each section can have a string inserted as a label, associated with an Index value. The Sections can be rearranged, re-ordered, or be individually painted.

In a typical application a THeaderControl and a TPanel or TForm would be docked together, and code would be written to find which Section of the Header had been selected, then use its index to control the display in the other docked control.

The latest version of this document can be found at lazarus-ccr.sourceforge.net .