19/02/2013
Class TabControl
The TabControl is used to manage a collection of TabPage instances which themselves are used to describe an individual page. Only a single page can be displayed at any time and a row of tabs are shown to allow the user to select between the available pages.
Creating objects
Creating tab pages in Visual Studio .NET
You can use the designer to modify a TabControl instance along with its TabPage instances. First you will need to add the control to the toolbox by right-clicking the toolbox window and selecting the customize option. Navigate to the appropriate directory and select the Magic Library DLL. The toolbox will now list the extra controls that are exposed by the library including the TabControl. Drag and drop a new instance onto your Form and select the TabPages property.
This will cause a dialog to appear that allows the creation and removal of pages to the control instance. It also allows you to modify the properties for each page added. Dismiss this dialog and you can now click on the control tabs in order to select the page you want to configure. As the TabPage class is derived from the Panel class you can now drag and drop other controls onto the page as desired. The designer will automatically generate the code needed to cause this configuration to be persisted as code in your Form.
Creating your TabControl manually
If you prefer to create your TabControl manually then use the following simple example.
Crownwood.Magic.Controls.TabControl tab1 =
new Crownwood.Magic.Controls.TabControl();
Because the control class name is called TabControl and this is the same name as an existing control in the System.Windows.Forms namespace, you will need to fully qualify the name of the class to be created. Otherwise the compiler will not be able to choose between the two available classes with the same names. This is also true of the TabPage as shown above, hence the use of fully qualified names in all the example code.
TabPage collection
The TabControl exposes a property called TabPages that allows the developer to add, remove and modify pages displayed by the control. Use the standard methods to modify this collection as you would with any of the framework collections.
Here is an example that shows the collection being manipulated: -
Crownwood.Magic.Controls.TabControl tab =
new Crownwood.Magic.Controls.TabControl();
Crownwood.Magic.Controls.TabPage tabPage1 =
new Crownwood.Magic.Controls.TabPage();
Crownwood.Magic.Controls.TabPage tabPage2 =
new Crownwood.Magic.Controls.TabPage();
// Add a range of pages to the collection
tab.TabPages.AddRange(new TabPage[] pages{tabPage1, tabPage2});
// Remove all the contents
tab.TabPages.Clear();
// Add a single entry
tab.TabPages.Add(tabPage1);
// Insert a single entry at a given position
tab.TabPages.Insert(0, tabPage2);
// Use index accessor for retrieving a page reference
Console.WriteLine("TabPages[0] name = {0}",
tab.TabPages[0].Text);
// Test if the collection contains an entry
Console.WriteLine("Contains tabPage1 = {0}",
tab.TabPages.Contains(tabPage1));
// Gain access to a Page by its Title
Console.WriteLine("Contains a named page? {0}",
tab.TabPages["Page1"] != null);
// Remove by object reference
tab.TabPages.Remove(tabPage1);
// Remove by index
tab.TabPages.RemoveAt(0);
Appearance
The first property you should modify is the Appearance which, as the name suggests, is used to define the appearance of the control. When the value of this property is changed it will automatically alter the values of other properties to the defaults for the defined appearance. Therefore this is the first property to be set otherwise previous changes to other properties will be overwritten once this is set.
The three possible values for the property are VisualAppearance.MultiDocument, VisualAppearance.MultiForm and VisualAppearance.MultiBox. The first of these will place the page tabs at the top of the control and show both arrow and close buttons. An example use of this would be to control which of a group of documents is displayed. For example, use this appearance to achieve the same effect as the Visual Studio .NET control that contains the open documents.
The second appearance VisualAppearance.MultiForm places the page tabs at the bottom of the control and does not show any buttons. Instead all the tabs are sized to fit within whatever width the control is defined as. Use this appearance to mimic the style of tab control seen in Visual Studio .NET inside docking windows.
Use the third appearance VisualAppearance.MultiBox to create the high contrast appearance you get when editing an HTML document in Visual Studio .NET, where the document has two options at the bottom of the window.
Once the appearance has been set the developer can still modify the other properties to alter the exact look and feel wanted. For example, the PositionTop property could be used to shift the default position of the tabs for the MultiForm appearance from the bottom of the control to the top. Use the SampleTabControl project included in the library to experiment and achieve the look required.
Notifications
There are several possible events that can be generated by the TabControl but only two are of interest to most developers. These are the ClosePressed event that gets fired when the user presses the close button, and SelectionChanged which notifies a change in the current selection.
To see how to hook into these events see the following code: -
public void SomeMethod()
{
Crownwood.Magic.Controls.TabControl tab =
new Crownwood.Magic.Controls.TabControl();
tab.ClosePressed += new EventHandler(OnClosePressed);
tab.SelectionChanged += new EventHandler(OnSelectionChanged);
...
}
protected void OnClosePressed(object sender, EventArgs e)
{
Console.WriteLine("OnClosePressed");
}
protected void OnSelectionChanged(object sender, EventArgs e)
{
Crownwood.Magic.Controls.TabControl tab =
(Crownwood.Magic.Controls.TabControl)sender;
Console.WriteLine("New selection = {0}", tab.SelectedIndex);
}
Methods
public void MakePageVisible(TabPage page)
Use this method to bring the specified TabPage into view.
public void MakePageVisible(int index)
As above method but takes an index rather than TabPage reference.
public TabPage TabPageFromPoint(Point mousePos)
Find the TabPage using the client based mouse position.
Properties
public virtual VisualAppearance Appearance
Has three possible values.
VisualAppearance.MultiDocument shows tabs at top with scrolling/close buttons
VisualAppearance.MultiForm shows tabs at bottom without buttons and shrinks tabs to fit space
VisualAppearance.MultiBox shows tabs at bottom in high contrast colors
Default: VisualAppearance.MultiForm
public virtual TabPagesCollection TabPages
Provides access to the list of tab pages.
public virtual VisualStyle Style
Has two possible values.
VisualStyle.IDE shows in Visual Studio .NET style
VisualStyle.Plain shows in a simpler Visual C++ v6 style
Default: VisualStyle.IDE
public virtual bool Multiline When there are too many tabs to fit on a single line, should multiple lines be shown.
Default: False
public virtual bool MultilineFullWidth Should all lines stretch to fit whole line length, or just those lines that are full.
Default: False
public override Font Font
Defines the Font used for drawing the tab page text.
Default: SystemInformation.MenuFont
public override Color BackColor
Defines the Color used for drawing background areas in the control.
Default: SystemColors.Control
public override Color ForeColor
Defines the Color used for drawing foreground areas in the control
Default: base.DefaultForeColor
public virtual Color ButtonActiveColor
Defines the Color used for drawing arrows/close buttons when they are active.
Default: Color.FromArgb(128, this.ForeColor)
public virtual Color ButtonInactiveColor
Defines the Color used for drawing arrows/close buttons when they are inactive.
Default: Color.FromArgb(128, this.ForeColor)
public virtual bool HotTrack
When defined the text of the page under the mouse will be highlighted in HotTextColor.
Default: false
public virtual Color HotTextColor
Color is used to highlight text when the page is under the mouse and the HotTrack property set.
Default: SystemColors.ActiveCaption
public virtual Color TextColor
Color for drawing the text of tab pages.
Default: this.DefaultForeColor
public virtual Color TextInactiveColor
Color for drawing the text of tab pages.
Default: Color.FromArgb(128, this.DefaultForeColor)
public virtual PopupMenu ContextPopupMenu Instance of a PopupMenu to the shown when right-click occurs in tabs area.
Default: null
public virtual ImageList ImageList
Used when a TabPage has ImageIndex defined but not ImageList.
Default: null
public virtual bool PositionTop
When defined this will show the tab pages at the top of the control, otherwise at the bottom.
Default: false
public virtual bool ShrinkPagesToFit
When defined will reduce the size of the tab page so that all tabs fit inside control width.
Default: false
public virtual bool BoldSelectedPage
Should the text for the selected page be drawn in bold.
Default: true
public virtual nt SelectedIndex
Returns the index into the TabPages collection of the currently selected page.
Set this value to change the current selection.
Default: -1
public virtual TabPage SelectedTab
Returns the TabPage from the TabPages collection of the currently selected page.
Set this value to change the current selection.
Default: null
public virtual bool ShowClose
When defined the close button will appear on far right of the control.
Default: false
public virtual bool ShowArrows
When defined the left and right arrows will appear on far right of the control.
Default: false
public virtual bool InsetPlain
When the VisualStyle.Plain style is defined this determines if the control area is flat or bumped.
Default: true
public virtual bool SelectedTextOnly
When defined only the selected tab has its text drawn.
Default: false
public virtual HideTabsModes HideTabsMode
Determines when the tabs area should be made visible. Has four values.
HideTabsModes.ShowAlways show tabs area all the time
HideTabsModes.HideAlways hides tabs area all the time
HideTabsModes.HideUsingLogic hides unless two or more pages exist
HideTabsModes.HideWithoutMouse hides unless mouse is over control
Default: HideTabsModes.ShowAlways
public virtual int LeaveTimeout
Delay when mouse leaves tab control before tabs area is shown again. Use when then HideTabsMode is defined to be HideWithoutMouse.
Default: 200ms
public virtual bool DragFromControl
Generates page dragging events when the user drags a page outside of the control area. When this property is set to False then it generates the event sequence when the page is dragged outside the double-click box from the mouse down position.
Default: True
public virtual bool DragOverSelect
When an external drag moves over the tab headres this property determines if the page under the mouse becomes selected. There is a short delay between hovering over and selecting the page to prevent rapid flickering when using multiple lines.
Default: True
public virtual bool HoverSelect
When defined the selected tab will change whenever the mouse moves over a new tab.
Default: false
public virtual int ControlLeftOffset
Defines how far from the Left edge the tab controls should be indented.
Default: 0
public virtual int ControlTopOffset
Defines how far from the Top edge the tab controls should be indented.
Default: 0
public virtual int ControlRightOffset
Defines how far from the Right edge the tab controls should be indented.
Default: 0
public virtual int ControlBottomOffset
Defines how far from the Bottom edge the tab controls should be indented.
Default: 0
public virtual bool InsetBorderPagesOnly
When in Plain style it will only show the inset border nearest the tabs and not all four borders.
Default: False
public virtual bool RecordFocus
Remembers which Control had focus when a different page is selected and restores it when page is reselected.
Default: True
public virtual bool IDEPixelBorder
When the IDE visual style is selected this places a single pixel border around the entire control.
Default: False
public virtual bool IDEPixelArea
When the IDE visual style is selected this places a single pixel border on outside edge of tabs area.
Default: False
Events
public event EventHandler ClosePressed
Fired whenever the close button is pressed.
public event EventHandler SelectionChanging
Fired whenever a change in tab selection is about to occur.
public event EventHandler SelectionChanged
Fired whenever a change in tab selection occurs.
public event EventHandler PageGotFocus
Fired whenever focus arrives on a tab page control.
public event EventHandler PageLostFocus
Fired whenever focus leaves a tab page control.
public event MouseEventHandler PageDragStart
Fired when the user drags a page tab using the mouse outside the client area.
public event MouseEventHandler PageDragMove
Fired when the mouse moves and currently in page dragging mode.
public event MouseEventHandler PageDragEnd
Fired when the mouse is released when in page dragging mode.
public event DoubleClickTabHandler DoubleClickTab
Fired whenever a mouse double click occurs on a page tab.
Delegate Signatures
void DoubleClickTabHandler(TabControl sender, TabPage page);
