Class XPTaskBar

Represents a Windows XP like task menu panel.

Inheritance

System.Object

XPTaskBar

Implements

System.ComponentModel.ISupportInitialize

INonClientPaintingSupport

IVisualStyle

Namespace: Syncfusion.Windows.Forms.Tools

Assembly: Syncfusion.Tools.Windows.dll

Syntax

[DefaultChildType(typeof(XPTaskBarBox))]
public class XPTaskBar : Panel, ISupportInitialize, INonClientPaintingSupport, IVisualStyle

Remarks

An XPTaskBar is a panel that can display a set of command items (XPTaskBarItem) or frequently used features (like "Search", "Advanced Search", etc) in panels, that can be classified, contained and displayed within one or more command boxes (XPTaskBarBox). The command boxes themselves can be expanded and collapsed by the user, to show or hide its set of command items and optionally a child panel.

This task bar panel can be used to provide quick and easy shortcuts to commonly used commands and features.

To enable themes support in XP turn on the ThemesEnabled property.

This is the look-and-feel used in the Windows XP Control Panel Window.

Examples

The following example creates a XPTaskBar with 2 XPTaskBarBoxs and few XPTaskBarItems.

Use the Syncfusion.Windows.Forms.Tools namespace for this code.

XPTaskBar xpTaskBar1 = new XPTaskBar();
XPTaskBarBox taskBarBox1 = new XPTaskBarBox();
taskBarBox1.HeaderBackColor = Color.Blue;
taskBarBox1.ImageList = this.imageList1;
taskBarBox1.Text = "Header Text";
taskBarBox1.ItemBackColor = Color.WhiteSmoke;
taskBarBox1.Items.Add(new XPTaskBarItem("Item 1", Color.Black, 0, "Tag1"));
taskBarBox1.Items.Add(new XPTaskBarItem("Item 2", Color.Black, 0, "Tag2"));
taskBarBox1.ItemClick += new XPTaskBarItemClickHandler(xpTaskBarBox_ItemClick);
XPTaskBarBox taskBarBox2 = new XPTaskBarBox();
taskBarBox2.HeaderBackColor = Color.Blue;
taskBarBox2.ImageList = this.imageList1;
taskBarBox2.Text = "Another Header Text";
taskBarBox2.ItemBackColor = Color.WhiteSmoke;
taskBarBox2.Items.Add(new XPTaskBarItem("Item 3", Color.Black, 0, "Tag3"));
taskBarBox2.ItemClick += new XPTaskBarItemClickHandler(this.xpTaskBarBox_ItemClick);
this.xpTaskBar1.Controls.Add(taskBarBox1);
this.xpTaskBar1.Controls.Add(taskBarBox2);

Dim xpTaskBar1 As XPTaskBar = New XPTaskBar()
Dim taskBarBox1 As XPTaskBarBox
taskBarBox1 = New XPTaskBarBox()
taskBarBox1.HeaderBackColor = Color.Blue
taskBarBox1.ImageList = Me.imageList1
taskBarBox1.Text = "Header Text"
taskBarBox1.ItemBackColor = Color.WhiteSmoke
taskBarBox1.Items.Add(New XPTaskBarItem("Item 1", Color.Black, 0, "Tag1"))
taskBarBox1.Items.Add(New XPTaskBarItem("Item 2", Color.Black, 0, "Tag2"))
AddHandler taskBarBox1.ItemClick, New XPTaskBarItemClickHandler(AddressOf taskMenuBox_ItemClick)
Dim taskBarBox2 As XPTaskBarBox
taskBarBox2 = New XPTaskBarBox()
taskBarBox2.HeaderBackColor = Color.Blue
taskBarBox2.ImageList = Me.imageList1
taskBarBox2.Text = "Another Header Text"
taskBarBox2.ItemBackColor = Color.WhiteSmoke
taskBarBox2.Items.Add(New XPTaskBarItem("Item 3", Color.Black, 0, "Tag3"))
AddHandler taskBarBox2.ItemClick, New XPTaskBarItemClickHandler(AddressOf taskMenuBox_ItemClick)
Me.xpTaskBar1.Controls.Add(taskBarBox1)
Me.xpTaskBar1.Controls.Add(taskBarBox2)

Constructors

XPTaskBar()

Initializes a new instance of the XPTaskBar class.

Declaration

public XPTaskBar()

Fields

m_Enabledefaultpady

Declaration

public bool m_Enabledefaultpady

Field Value

Type
System.Boolean

Properties

AutoPersistStates

Gets or sets a value indicating whether to automatically persists the collapsed state of the child boxes.

Declaration

public bool AutoPersistStates { get; set; }

Property Value

Type	Description
System.Boolean	True to persist the expanded state every time the control is disposed; false otherwise. Default is true.

Remarks

When this property is true, the expanded states of the child task bar boxes are cached as the users expands/collapses them and when this control is disposed, the cached state is persisted in the Isolated Storage.

When the application loads again and when child task bar boxes are added to this control, the saved state is reapplied on the task bar boxes.

State is saved in the Isolated Storage of the system, scoped by the current user identity.

You can also optionally, explicitly control the persistent store and/or the time of persistence using explicit calls to LoadBoxExpandedStates() and SaveBoxExpandedStates() methods.

AutoSize

Gets or sets a value indicating whether the control is automatically resized to display its entire contents.

Declaration

public override bool AutoSize { get; set; }

Property Value

Type
System.Boolean

BackColor

Gets or sets the backcolor. (overridden property)

Declaration

public override Color BackColor { get; set; }

Property Value

Type
System.Drawing.Color

BeforeTouchSize

Gets/Sets Control size before touch enabled

Declaration

public Size BeforeTouchSize { get; set; }

Property Value

Type
System.Drawing.Size

BorderColor

Declaration

public Color BorderColor { get; set; }

Property Value

Type
System.Drawing.Color

BoxItemsAlignment

Gets or sets the Taskbar box's items alignment.

Declaration

public XPTaskBar.ItemsAlignment BoxItemsAlignment { get; set; }

Property Value

Type
XPTaskBar.ItemsAlignment

ColWidthOnHorizontalAlignment

Gets or sets the width for each column when in horizontal alignment mode.

Declaration

public int ColWidthOnHorizontalAlignment { get; set; }

Property Value

Type	Description
System.Int32	Default is 100.

Remarks

This property will be used when the XPTaskBarBoxs are aligned horizontally, by setting the VerticalLayout property to false.

CreateParams

Declaration

protected override CreateParams CreateParams { get; }

Property Value

Type
System.Windows.Forms.CreateParams

DefaultSize

Declaration

protected override Size DefaultSize { get; }

Property Value

Type
System.Drawing.Size

EnabledefaultPADY

Enable / disable the default padding property

Declaration

public bool EnabledefaultPADY { get; set; }

Property Value

Type
System.Boolean

EnableTouchMode

Declaration

public bool EnableTouchMode { get; set; }

Property Value

Type
System.Boolean

FlowLayout

Gets the FlowLayout component used to manage the layout of the XPTaskBarBoxs inside this control.

Declaration

public FlowLayout FlowLayout { get; }

Property Value

Type
FlowLayout

HeaderImageList

Gets or sets the ImageList that will be used to draw the header images in the individual XPTaskBarBox.

Declaration

public ImageList HeaderImageList { get; set; }

Property Value

Type	Description
System.Windows.Forms.ImageList	An System.Windows.Forms.ImageList instance. Default is null.

Remarks

This ImageList will automatically be used by the child XPTaskBarBox instances. You can override this behavior by setting a different ImageList in the ImageList property.

HorizontalPadding

Gets or sets the horizontal spacing between the layout task bar.

Declaration

public int HorizontalPadding { get; set; }

Property Value

Type
System.Int32

Location

Gets or sets the coordinates of the upper-left corner of the control relative to the upper-left corner of its container.

Declaration

public Point Location { get; set; }

Property Value

Type
System.Drawing.Point

MetroColor

Gets or Sets the Metrocolor

Declaration

public Color MetroColor { get; set; }

Property Value

Type
System.Drawing.Color

MinimumSize

Gets or sets minimum size for XPTaskBar.

Declaration

public Size MinimumSize { get; set; }

Property Value

Type
System.Drawing.Size

NeedLayout

Gets a value indicating whether need layout Internal method, not to be used directly.

Declaration

public bool NeedLayout { get; }

Property Value

Type
System.Boolean

Remarks

Indicates whether this control's content needs to be laid out.

Office2007ColorScheme

Gets or sets office 2007 color scheme.

Declaration

public Office2007Theme Office2007ColorScheme { get; set; }

Property Value

Type
Office2007Theme

Office2010ColorScheme

Gets or sets office 2010 color scheme.

Declaration

public Office2010Theme Office2010ColorScheme { get; set; }

Property Value

Type
Office2010Theme

PADY

Gets / sets the vertical padding provided in pixels between contents of the header and the header's top and bottom borders.

Declaration

public int PADY { get; set; }

Property Value

Type
System.Int32

ScrollerFrame

Gets the ScrollerFrame

Declaration

public ScrollersFrame ScrollerFrame { get; }

Property Value

Type
ScrollersFrame

Size

Gets or sets the height and width of the control.

Declaration

public Size Size { get; set; }

Property Value

Type
System.Drawing.Size

Style

Gets or sets an advanced appearance for the xpTaskBar.

Declaration

public XPTaskBarStyle Style { get; set; }

Property Value

Type
XPTaskBarStyle

Text

Gets or sets the text associated with the control.

Declaration

public override string Text { get; set; }

Property Value

Type
System.String

ThemesEnabled

Gets or sets a value indicating whether XP Themes (visual styles) should be used for this control when available.

Declaration

public bool ThemesEnabled { get; set; }

Property Value

Type
System.Boolean

Remarks

This property will also affect the XPTaskBarBox children's themes usage.

UseCustomScrollerFrame

Gets or Sets whether to have custom scrollbar

Declaration

public bool UseCustomScrollerFrame { get; set; }

Property Value

Type
System.Boolean

VerticalLayout

Gets or sets a value indicating whether the XPTaskBarBoxs should be aligned vertically or horizontally in this control.

Declaration

public bool VerticalLayout { get; set; }

Property Value

Type	Description
System.Boolean	True to align vertically, one below the other; false to align horizontally. Default is true.

Remarks

When you set this property to false, you should typically also set the ColWidthOnHorizontalAlignment property.

VerticalPadding

Gets or sets the vertical spacing between the layout task bar.

Declaration

public int VerticalPadding { get; set; }

Property Value

Type
System.Int32

Methods

ApplyDeserializedStates(Hashtable)

Applies the deserialized expanded state information on the current task bar boxes.

Declaration

protected virtual void ApplyDeserializedStates(Hashtable htStates)

Parameters

Type	Name	Description
System.Collections.Hashtable	htStates	A System.Collections.Hashtable instance.

Remarks

This method will be called to apply the persisted expanded-state of the task bar boxes. The hash table should contain text-boolean pairs indicating the text of the task bar box and it's collapsed state (true for collapsed, false for expanded).

ApplyScaleToControl(Single)

Declaration

public void ApplyScaleToControl(float scaleFactor)

Parameters

Type	Name	Description
System.Single	scaleFactor

BeginInit()

Signals the object that initialization is starting.

Declaration

public virtual void BeginInit()

Dispose(Boolean)

Overridden. See System.Windows.Forms.Control.Dispose(System.Boolean).

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	bool disposing

EndInit()

Signals the object that initialization is complete.

Declaration

public virtual void EndInit()

FlowLayout_VGapChanged(Object, ValueChangedEventArgs)

Declaration

public void FlowLayout_VGapChanged(object sender, ValueChangedEventArgs e)

Parameters

Type	Name	Description
System.Object	sender
ValueChangedEventArgs	e

Layout(Graphics)

Lays out its children.

Declaration

protected virtual void Layout(Graphics g)

Parameters

Type	Name	Description
System.Drawing.Graphics	g	The Graphics object based on which to determine the sizes and positions.

Remarks

Note that the XPTaskBar control follows a different layout pattern from the usual Windows Forms Control. When requested a layout by the default Windows Forms Layout event, this control will only mark its child positions as dirty and recalculate its child positions when a subsequent Paint event occurs, with a call to this Layout method. This technique is followed to reduce flicker.

LayoutTaskBarBoxes(Int32)

Internal method used to layout the XPTaskBarBoxs.

Declaration

protected virtual void LayoutTaskBarBoxes(int nTaskBarBoxesHeght)

Parameters

Type	Name	Description
System.Int32	nTaskBarBoxesHeght	TaskBar Box height

LoadBoxExpandedStates()

Overloaded. Loads the expanded state of the child task bar boxes from the Isolated Storage.

Declaration

public bool LoadBoxExpandedStates()

Returns

Type	Description
System.Boolean	Returns Load expanded states

Remarks

Call this method whenever you want to load the saved expanded states of the task bar boxes from the Isolated Storage.

Note that you do not have to call this method to persist state. You could use the AutoPersistStates property instead.

LoadBoxExpandedStates(AppStateSerializer)

Loads the expanded state of the child task bar boxes from the specified AppStateSerializer.

Declaration

public virtual bool LoadBoxExpandedStates(AppStateSerializer serializer)

Parameters

Type	Name	Description
AppStateSerializer	serializer	A AppStateSerializer instance.

Returns

Type	Description
System.Boolean	True if loaded successfully; false otherwise.

Remarks

Call this method whenever you want to load the saved expanded states of the task bar boxes from a specific location.

Note that you do not have to call this method to persist state. You could use the AutoPersistStates property instead.

OnControlAdded(ControlEventArgs)

Declaration

protected override void OnControlAdded(ControlEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.ControlEventArgs	e

OnControlRemoved(ControlEventArgs)

Declaration

protected override void OnControlRemoved(ControlEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.ControlEventArgs	e

OnFontChanged(EventArgs)

Declaration

protected override void OnFontChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e

OnLayout(LayoutEventArgs)

Declaration

protected override void OnLayout(LayoutEventArgs levent)

Parameters

Type	Name	Description
System.Windows.Forms.LayoutEventArgs	levent

OnMinimumSizeChanged()

Raises the MinimumSizeChanged event.

Declaration

protected virtual void OnMinimumSizeChanged()

OnPaint(PaintEventArgs)

Declaration

protected override void OnPaint(PaintEventArgs e)

Parameters

Type	Name	Description
System.Windows.Forms.PaintEventArgs	e

OnSizeChanged(EventArgs)

Declaration

protected override void OnSizeChanged(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e

OnUpdateFlowLayoutBeforeLayout()

This method gets called every time before the XPTaskBarBoxes get laid out by the FlowLayout component.

Declaration

protected virtual void OnUpdateFlowLayoutBeforeLayout()

Remarks

You shouldn't have to override this method typically. Do so when you need a different layout logic than the default one. When overriding this method, make sure to call the base class. The base class will set up the margins and bounds for the layout.

The FlowLayout component used internally can be accessed using the FlowLayout property.

ResetBackColor()

Resets the back color to it's default value. (overridden method)

Declaration

public override void ResetBackColor()

ResetEnabledefaultPADY()

To reset EnableDefaultPADY

Declaration

public void ResetEnabledefaultPADY()

SaveBoxExpandedStates()

Overloaded. Saves the expanded state of the child task bar boxes in the Isolated Storage.

Declaration

public void SaveBoxExpandedStates()

Remarks

Call this method whenever you want to save the current expanded state of the task bar boxes in the Isolated Storage.

Note that you do not have to call this method to persist state. You could use the AutoPersistStates property instead.

SaveBoxExpandedStates(AppStateSerializer)

Saves the expanded state of the child task bar boxes into the specified serializer.

Declaration

public virtual void SaveBoxExpandedStates(AppStateSerializer serializer)

Parameters

Type	Name	Description
AppStateSerializer	serializer	A AppStateSerializer instance.

Remarks

Call this method whenever you want to save the current expanded state of the task bar boxes in a custom location (instead of the default Isolated Storage).

Note that you do not have to call this method to persist state. You could use the AutoPersistStates property instead.

ScrollToControl(Control)

Declaration

protected override Point ScrollToControl(Control activeControl)

Parameters

Type	Name	Description
System.Windows.Forms.Control	activeControl

Returns

Type
System.Drawing.Point

SetBoundsCore(Int32, Int32, Int32, Int32, BoundsSpecified)

Declaration

protected override void SetBoundsCore(int x, int y, int width, int height, BoundsSpecified specified)

Parameters

Type	Name	Description
System.Int32	x
System.Int32	y
System.Int32	width
System.Int32	height
System.Windows.Forms.BoundsSpecified	specified

ShouldSerializeEnabledefaultPADY()

To Specify EnabledefaultPADY to be serialized or not

Declaration

public bool ShouldSerializeEnabledefaultPADY()

Returns

Type
System.Boolean

WndProc(ref Message)

Declaration

protected override void WndProc(ref Message m)

Parameters

Type	Name	Description
System.Windows.Forms.Message	m

Events

MinimumSizeChanged

Occurs when the MinimumSize property changes.

Declaration

public event EventHandler MinimumSizeChanged

Event Type

Type
System.EventHandler

Explicit Interface Implementations

INonClientPaintingSupport.NonClientPaint(PaintEventArgs, Rectangle, Rectangle)

Declaration

IntPtr INonClientPaintingSupport.NonClientPaint(PaintEventArgs e, Rectangle displayRect, Rectangle windowRectInScreen)

Parameters

Type	Name	Description
System.Windows.Forms.PaintEventArgs	e
System.Drawing.Rectangle	displayRect
System.Drawing.Rectangle	windowRectInScreen

Returns

Type
System.IntPtr

IVisualStyle.VisualTheme

Declaration

string IVisualStyle.VisualTheme { get; set; }

Returns

Type
System.String

Implements

System.ComponentModel.ISupportInitialize

INonClientPaintingSupport

IVisualStyle