HypernovaDesktop Components · docs
Binarymission
WinForms › Power Tab Strip › BinaryPowerTabPage

BinaryPowerTabPage

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.TabControls

One tab of a BinaryPowerTabStrip: a panel for the tab's controls, together with everything its header shows – caption, image, tooltip, colours and close button.

public class BinaryPowerTabPage : BinaryExtendedPanel

Inherits from / implements: BinaryExtendedPanel

Remarks

Put the tab's controls in the page's Control.Controls, usually one control docked to fill it, and add the page to a strip with BinaryPowerTabStrip.AddTab() or BinaryPowerTabStrip.TabPages. The strip docks the page and shows it while its tab is selected. A page belongs in a strip: given any other kind of parent it throws InvalidCastException.

The header

The caption is Text and the picture Image. Colours left empty – TabPageHeaderForeColor, CustomStartColor, CustomEndColor, TabPageSideBarFillColor – fall back to the strip's. IsHeaderEnabled greys a header out so it cannot be clicked, and Visible takes the tab off the strip altogether.

Examples

var overdue = new BinaryPowerTabPage
{
    Text = "Overdue invoices",
    Image = Image.FromFile(@"Icons\invoice-warning-16.png"),
    ToolTipText = "Invoices more than 30 days past their due date",
    TabPageHeaderForeColor = Color.Firebrick,
    ShouldRenderCloseButton = false            // this tab cannot be closed
};

overdue.Controls.Add(new DataGridView { Dock = DockStyle.Fill, DataSource = overdueInvoices });
tabs.AddTab(overdue, true);

See also

Members at a glance

Constructors
BinaryPowerTabPageCreates a page with no caption, a window-coloured background and a one-pixel border, its header enabled and showing a close button.
BinaryPowerTabPageCreates a page with the given caption, its header enabled and showing a close button.
Properties
BorderSizeGets or sets the width of the border the page draws round its content area, in BinaryExtendedPanel.BorderColor.
CurrentlySelectedGets or sets a flag the strip keeps in step with the selection: true while this is the selected tab.
CustomEndColorGets or sets the colour this header's fill ends at in the RenderingStyle.Custom and RenderingStyle.TrapeziumTop styles.
CustomStartColorGets or sets the colour this header's fill starts from in the RenderingStyle.Custom and RenderingStyle.TrapeziumTop styles.
DisabledImageGets or sets the picture drawn in place of Image while this tab's header is disabled.
HeaderTextFontGets or sets the font of this tab's header text.
ImageGets or sets the picture drawn before the caption in this tab's header.
IsBackgroundTransparentGets or sets whether the page's background is transparent, so whatever is behind the strip shows through.
IsHeaderEnabledGets or sets whether this tab's header can be clicked.
OverflowMenuImageGets or sets the image shown beside this tab's entry in the strip's overflow menu.
ShouldRenderCloseButtonGets or sets whether this tab's header shows a close button.
SizeGets or sets the size of the page. The strip sizes its pages to fill the page area, so this is hidden from the designer and the editor's completion lists.
TabPageContentIsDirtyGets or sets whether the page holds changes the user has not saved – a flag for your own code.
TabPageHeaderForeColorGets or sets the colour of this tab's header text.
TabPageSideBarFillColorGets or sets the colour of this header's side bar, when the strip draws side bars.
TextGets or sets the caption shown in this tab's header and in the overflow menu.
ToolTipTextGets or sets the tooltip shown when the pointer rests on this tab's header.
VisibleGets or sets whether this tab is on the strip at all – its header drawn and listed in the overflow menu.
Methods
DisposeReleases the page's resources, including its Image.
OnPaintDraws the page's border (BorderSize, BinaryExtendedPanel.BorderColor), then raises the Control.Paint event.
OnParentChangedRaises the Control.ParentChanged event, and takes the new strip's BinaryPowerTabStrip.HeaderFont as HeaderTextFont.
ShouldSerializeControlsTells the designer to write the page's child controls into the designer file when it has any.
ShouldSerializeDockTells the designer not to write Control.Dock into the designer file: the strip docks its pages itself. Always returns false.
ShouldSerializeIsPaintingCompletePart of the designer's serialisation support; not for use from application code. Always returns false.
ShouldSerializeVisibleTells the designer always to write Visible into the designer file. Always returns true.
Events
TabPageChangedOccurs when the page's Visible setting changes.

Constructors

BinaryPowerTabPage

public BinaryPowerTabPage() : this(string.Empty)

Creates a page with no caption, a window-coloured background and a one-pixel border, its header enabled and showing a close button.

BinaryPowerTabPage

public BinaryPowerTabPage(string tabPageText)

Creates a page with the given caption, its header enabled and showing a close button.

Parameters
tabPageText
The header caption (Text).
Remarks

Unlike the parameterless constructor, this leaves Control.BackColor at the panel default and BorderSize at 0. To get those defaults with a caption, use new BinaryPowerTabPage { Text = "Orders" }.

Properties

BorderSize

public int BorderSize

Gets or sets the width of the border the page draws round its content area, in BinaryExtendedPanel.BorderColor.

Value
The width in pixels. Negative values are stored as 0. The default is 1, or 0 for a page made with the BinaryPowerTabPage() constructor.
Remarks

Setting it also sets Control.Padding to the same width (at least 1), so docked controls sit inside the border.

CurrentlySelected

public bool CurrentlySelected

Gets or sets a flag the strip keeps in step with the selection: true while this is the selected tab.

Value
The default is false.
Default
false
Remarks

Setting it does not select or deselect the tab; use BinaryPowerTabStrip.SelectedTabPage, which is also the reliable way to ask which tab is selected.

CustomEndColor

public Color CustomEndColor

Gets or sets the colour this header's fill ends at in the RenderingStyle.Custom and RenderingStyle.TrapeziumTop styles.

Value
The default is Color.Empty: the strip's BinaryPowerTabStrip.CustomEndColor.

CustomStartColor

public Color CustomStartColor

Gets or sets the colour this header's fill starts from in the RenderingStyle.Custom and RenderingStyle.TrapeziumTop styles.

Value
The default is Color.Empty: the strip's BinaryPowerTabStrip.CustomStartColor.
Remarks

Use it with CustomEndColor to colour-code tabs – one colour per customer, project or environment. While the tab is selected it is filled with the strip's selection colours instead, if BinaryPowerTabStrip.UseTabCurrentSelectionIndicatorColor is on.

Example
tabs.TabRenderingStyle = RenderingStyle.Custom;
productionPage.CustomStartColor = Color.MistyRose;
productionPage.CustomEndColor = Color.White;

DisabledImage

public Image DisabledImage

Gets or sets the picture drawn in place of Image while this tab's header is disabled.

Value
The default is null: a grey copy of Image is made each time the header is drawn.
Default
null
See also

HeaderTextFont

public Font HeaderTextFont

Gets or sets the font of this tab's header text.

Value
The default is the system's default user-interface font. Must not be null.
Remarks

The strip gives every page its BinaryPowerTabStrip.HeaderFont when the page joins it and whenever that is set, replacing this value; set a page's own font after those. Setting it does not lay the headers out again; call BinaryPowerTabStrip.RefreshLayout. The selected tab may be drawn in BinaryPowerTabStrip.SelectedTabPageHeaderFont instead.

Image

public Image Image

Gets or sets the picture drawn before the caption in this tab's header.

Value
The default is null: no picture.
Default
null
Remarks

The image is drawn at its own size, in pixels, and the headers are made tall enough for the tallest image. It is also shown beside the tab's entry in the overflow menu, unless OverflowMenuImage is set. While the header is disabled, DisabledImage or a grey copy is drawn instead.

The page disposes this image when it is disposed, so give each page an image of its own rather than one shared with other pages or controls.

IsBackgroundTransparent

public bool IsBackgroundTransparent

Gets or sets whether the page's background is transparent, so whatever is behind the strip shows through.

Value
The default is false.
Remarks

Turning it on sets Control.BackColor to Color.Transparent; turning it off sets it to SystemColors.Window, whatever it was before. The strip's own BinaryPowerTabStrip.IsBackgroundTransparent sets this on every page it holds.

IsHeaderEnabled

public bool IsHeaderEnabled

Gets or sets whether this tab's header can be clicked.

Value
The default is true.
Remarks

A disabled header is drawn with grey text (unless it is the selected tab) and a grey image (DisabledImage), has no close button, ignores clicks and double-clicks, and is left out of the overflow menu. The page can still be selected from code through BinaryPowerTabStrip.SelectedTabPage.

Example
// The "Approvals" tab is available to managers only.
approvalsPage.IsHeaderEnabled = currentUser.IsManager;

OverflowMenuImage

public Image OverflowMenuImage

Gets or sets the image shown beside this tab's entry in the strip's overflow menu.

Value
The default is null: Image is used there as well.
Default
null
Remarks

Lets the menu entry carry an image without the header showing one, or a different one. The menu scales images to 16 logical pixels, so give one drawn for the display – 16 pixels at 100%, 40 at 250% – to keep it sharp.

ShouldRenderCloseButton

public bool ShouldRenderCloseButton

Gets or sets whether this tab's header shows a close button.

Value
The default is true.
Remarks

The button is drawn only while the strip's BinaryPowerTabStrip.EnableTabPageLevelCloseButtonRendering and this page's IsHeaderEnabled are on. Turn it off for tabs that must stay open.

Size

public new Size Size

Gets or sets the size of the page. The strip sizes its pages to fill the page area, so this is hidden from the designer and the editor's completion lists.

TabPageContentIsDirty

public bool TabPageContentIsDirty

Gets or sets whether the page holds changes the user has not saved – a flag for your own code.

Value
The default is false.
Remarks

The strip does not read or change it. Set it as the page's data changes, and check it in BinaryPowerTabStrip.TabPageClosing to ask before a tab with unsaved work is closed.

TabPageHeaderForeColor

public Color TabPageHeaderForeColor

Gets or sets the colour of this tab's header text.

Value
The default is Color.Empty: the strip's BinaryPowerTabStrip.TabPageHeaderForeColor.
Remarks

A disabled header (IsHeaderEnabled) that is not selected is drawn in SystemColors.GrayText regardless.

TabPageSideBarFillColor

public Color TabPageSideBarFillColor

Gets or sets the colour of this header's side bar, when the strip draws side bars.

Value
The default is Color.Empty: the strip's BinaryPowerTabStrip.TabPageSideBarFillColor.
Remarks

Side bars are drawn while the strip's BinaryPowerTabStrip.TabPageHeaderShowsSideBar is on, in the RenderingStyle.Custom style.

Text

public string Text

Gets or sets the caption shown in this tab's header and in the overflow menu.

Value
The default is an empty string.
Default
Name
Remarks

Setting it repaints the strip, unless the strip's BinaryPowerTabStrip.PreventInvalidation is on. A caption wider than the strip's BinaryPowerTabStrip.TabPageHeaderWidth is shortened with an ellipsis.

ToolTipText

public string ToolTipText

Gets or sets the tooltip shown when the pointer rests on this tab's header.

Value
The default is an empty string, which shows no tooltip.
Remarks

Shown while the strip's BinaryPowerTabStrip.ShowToolTip is on, styled by its BinaryPowerTabStrip.ToolTipConfiguration.

Visible

public new bool Visible

Gets or sets whether this tab is on the strip at all – its header drawn and listed in the overflow menu.

Value
The default is true.
Default
true
Remarks

This is not Visible: the strip shows and hides the page itself as the selection changes. Setting this to false takes the tab off the strip without removing the page from BinaryPowerTabStrip.TabPages, and raises TabPageChanged.

Selecting a hidden page through BinaryPowerTabStrip.SelectedTabPage makes it visible again.

Methods

Dispose

protected override void Dispose(bool disposing)

Releases the page's resources, including its Image.

Parameters
disposing
true when called from Dispose; false from the finalizer.
Remarks

DisabledImage and OverflowMenuImage are not disposed.

OnPaint

protected override void OnPaint(PaintEventArgs e)

Draws the page's border (BorderSize, BinaryExtendedPanel.BorderColor), then raises the Control.Paint event.

Parameters
e
The event data.

OnParentChanged

protected override void OnParentChanged(EventArgs e)

Raises the Control.ParentChanged event, and takes the new strip's BinaryPowerTabStrip.HeaderFont as HeaderTextFont.

Parameters
e
The event data.
Exceptions
System.InvalidCastException
The new parent is not a BinaryPowerTabStrip.

ShouldSerializeControls

public bool ShouldSerializeControls()

Tells the designer to write the page's child controls into the designer file when it has any.

ShouldSerializeDock

public bool ShouldSerializeDock()

Tells the designer not to write Control.Dock into the designer file: the strip docks its pages itself. Always returns false.

ShouldSerializeIsPaintingComplete

public bool ShouldSerializeIsPaintingComplete()

Part of the designer's serialisation support; not for use from application code. Always returns false.

ShouldSerializeVisible

public bool ShouldSerializeVisible()

Tells the designer always to write Visible into the designer file. Always returns true.

Events

TabPageChanged

public event EventHandler TabPageChanged

Occurs when the page's Visible setting changes.

Remarks

The strip's collection listens for it, lays the headers out again and raises BinaryPowerTabStrip.TabPageSelectionChanged with TabPageChangeTriggerSource.Changed.