Magic Logo
top
page content
tab indicator
operation
constructors
properties
events
sample code
Class TabPage
A TabPage object is used to describe the contents of an individual tab for the TabControl, which manages a collection of TabPage instances.
Page content
The TabPage class derives from the Panel base class and so can be used in the designer as a surface for placing controls onto. This allows the developer to drag and drop controls from the toolbox onto the individual pages of the TabControl to achieve the required runtime layout.

However, you are not obliged to use the TabPage object itself as the control for display when the page is selected. Instead you may assign any Control derived instance to the TabPage.Control property which will then be displayed whenever the tab is selected. This is particularly useful when you do not know the control that will be displayed until runtime, or if you need to show a control that derives from UserControl or Form.

This property has the added benefit of allowing the creation of more flexible designs that achieve greater code reuse. Placing controls onto a TabPage surface is restrictive as it implies the layout can only be used within a TabControl. Instead create a Form derived class that contains the layout of controls as desired along with any and associated control logic. When this layout is needed inside a TabControl simply create a TabPage instance along with an instance of your new class which is then assigned to the TabPage.Control property.

You now have the added benefit that your new class can be reused. Anywhere you need the same user interface layout you just instantiate a new instance and add as a child form. Alternatively you might derive a class that adds 'Ok' and 'Cancel' buttons and a few extra lines of code to create a dialog box.

Maybe the greatest benefit is the ability to change the TabPage.Control on the fly which will immediately change the control displayed in the TabControl. This gives maximum flexibility to the developer.

Tab indicator
As you would expect for the design of any TabPage class you can define the text that is displayed for a particular instance. Assign a string to the TabPage.Title property.

An image can be displayed along with the title text by supplying appropriate values to the TabPage.ImageList and TabPage.ImageIndex properties. Note that the TabControl also has a property called ImageList that is used whenever a TabPage instance specifies an ImageIndex value but does not provide an ImageList reference value. If you know all your images come from the same strip then simply set the strip into the TabControl and then specify the correct image index into each TabPage instance. If the images come from several different strips then you can specify the strip and index with each individual page.

You are not restricted to just images, alternatively you can provide an Icon that always takes priority over any ImageList values that may have been specified.

Operation
The developer can store page specific information relevant to their application using the TabPage.Tag property. No use is ever made of this by the TabControl or the TabPage classes. In the sample code example an integer value of 99 is boxed and stored for later use.

The TabPage.Selected property can be set to indicate if the page should be selected when it is added into the TabControl. Once added the value will reflect the current selected status of the page and can be set to make a page become the currently selected one. Note that you cannot set this value to false as the TabControl would not know which other page should become the newly selected one.

If your TabPage is quite complex it may have several child controls. In this case you might want to define which of the child controls starts with the focus when the page is selected. Use the TabPage.StartFocus property by assigning a reference to a child control. Note that when the user moves away from the current page it will update this property with the control that currently has focus so that when the user returns the focus will be restored to the same place it left off.

Constructors

        public TabPage()
        public TabPage(string title)
        public TabPage(string title, Control control)
        public TabPage(string title, Control control, int imageIndex)
        public TabPage(string title, Control control, Icon icon)
        
        public TabPage(string title, Control control, 
                       ImageList imageList, int imageIndex)
        

Properties
public string Title
Title text to display for this tab.
Default: "Page"

public Control Control
Control derived object to display when tab is selected.
Default: null

public int ImageIndex
Index into the provided TabPage.ImageList property that should be used for display alongside the title text. If the TabPage.ImageList is null then the TabControl.ImageList property will be used instead. Note that any Icon value takes priority over any image setting.
Default: -1

public ImageList ImageList
Images that TabPage.ImageIndex property indexes.
Default: null

public Icon Icon
Icon to be displayed.
Default: null

public bool Selected
Indicates if this tab is the currently selected one.
Default: true

public Object Tag
Arbitrary data associated with the object by developer.
Default: null

public Control StartFocus
Control that should take foucs when the tab becomes selected.
Default: null

Events
public event PropChangeHandler PropertyChanged
Used by the TabControl to monitor changes in properties

Delegate Signatures

                        
   void PropChangeHandler(TabPage page, Property prop, object oldValue);
        
Sample code
C#

   // Create a new TabPage instance
   Crownwood.Magic.Controls.TabPage newPage = 
        new Crownwood.Magic.Controls.TabPage();

   // Define control to be shown when page selected
   newPage.Control = new RichTextBox();

   // Define text used on tab indicator
   newPage.Title = "Notes";

   // Set either the Icon or the Image properties
   if (_myIcon != null)
      newPage.Icon = _myIcon;
   else
   {	        
      newPage.ImageList = _myImageList;
      newPage.ImageIndex = 2;
   }

   // Remember application specific information
   newPage.Tag = (object)999;
   
   // Make this page the selected one when it is added
   newPage.Selected = true;

   _myTabControl.TabPages.Add(newPage);
   
VB.NET

   ' Create a new TabPage instance
   Dim newPage as New Crownwood.Magic.Controls.TabPage()

   ' Define control to be shown when page selected
   newPage.Control = New RichTextBox()

   ' Define text used on tab indicator
   newPage.Title = "Notes"

   ' Set either the Icon or the Image properties
   If Not (_myIcon Is Nothing) Then
      newPage.Icon = _myIcon
   Else
      newPage.ImageList = _myImageList
      newPage.ImageIndex = 2
   End If

   ' Remember application specific information
   newPage.Tag = (Object)999
   
   ' Make this page the selected one when it is added
   newPage.Selected = true;

   _myTabControl.TabPages.Add(newPage)