syncfusion-winforms-xptaskbar

Implementing XPTaskBar in Windows Forms

Table of Contents

• When to Use This Skill
• Component Overview
• Quick Start Example
• Documentation Navigation Guide
• Common Patterns
• Key Configuration Properties

When to Use This Skill

Use XPTaskBar when you need to:

• Create expandable task panels - Display command items or features in collapsible grouped boxes
• Build Windows XP-style menus - Recreate the classic task sidebar UI pattern
• Organize navigation hierarchically - Group related commands into categorized boxes
• Implement interactive task lists - Allow users to expand/collapse task categories with animations
• Add custom animations and events - Control expand/collapse behavior and respond to user interactions

Component Overview

XPTaskBar is a Windows Forms control that displays command items organized within collapsible boxes, mimicking the Windows XP task sidebar. The component hierarchy includes:

• XPTaskBar - Main container control that can hold multiple boxes
• XPTaskBarBox - Collapsible section with header and items area
• XPTaskBarItem - Individual command items displayed within a box

Key Features

• Hierarchical layout - Organize items into categorized boxes
• Collapse/expand animation - Smooth transitions with configurable animation speed
• Multiple layout modes - Vertical (default) or horizontal orientation
• State persistence - Remember expanded/collapsed state across sessions
• Rich customization - Control colors, fonts, images, and spacing
• Event-driven - Handle clicks, animations, and state changes
• Child control support - Host panels and other controls within boxes

Quick Start Example

using Syncfusion.Windows.Forms.Tools;

// Create XPTaskBar control
XPTaskBar xpTaskBar1 = new XPTaskBar();
xpTaskBar1.Dock = DockStyle.Fill;
this.Controls.Add(xpTaskBar1);

// Create first task box
XPTaskBarBox box1 = new XPTaskBarBox();
box1.Text = "File Operations";
xpTaskBar1.Controls.Add(box1);

// Add items to the box
box1.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("New Document", System.Drawing.Color.Empty, -1, "NewDoc"),
    new XPTaskBarItem("Open File", System.Drawing.Color.Empty, -1, "OpenFile"),
    new XPTaskBarItem("Save", System.Drawing.Color.Empty, -1, "Save")
});

// Handle item clicks
box1.ItemClick += (sender, e) => {
    switch (e.XPTaskBarItem.Tag as string) {
        case "NewDoc":
            // Handle new document
            break;
        case "OpenFile":
            // Handle file open
            break;
    }
};

// Create second task box
XPTaskBarBox box2 = new XPTaskBarBox();
box2.Text = "Editing Tools";
xpTaskBar1.Controls.Add(box2);

box2.Items.AddRange(new XPTaskBarItem[] {
    new XPTaskBarItem("Cut", System.Drawing.Color.Empty, -1, "Cut"),
    new XPTaskBarItem("Copy", System.Drawing.Color.Empty, -1, "Copy"),
    new XPTaskBarItem("Paste", System.Drawing.Color.Empty, -1, "Paste")
});

Documentation Navigation Guide

Read the reference documentation in the order that matches your implementation needs:

Getting Started

📄 Read: references/getting-started.md

• Assembly and package dependencies
• Adding control via designer or code
• Basic XPTaskBar, box, and item setup
• Assembly references required

Building the Structure

📄 Read: references/box-structure.md

• XPTaskBar box hierarchy and anatomy
• Header customization (text, font, alignment, direction)
• Collapse/expand button configuration
• Integrating child panels and controls

📄 Read: references/items-and-content.md

• Creating and managing XPTaskBarItems
• Working with Items collection
• Item properties and configuration
• Hosting nested controls with PreferredChildPanelHeight

Layout and Orientation

📄 Read: references/layout-orientation.md

• Vertical layout mode (default)
• Horizontal layout mode and column width
• Switching orientations dynamically
• Responsive layout behavior

Behavior and Interactivity

📄 Read: references/behavior-and-events.md

• Animation configuration and timing
• Collapse/expand event handling
• ItemClick event with Tag-based routing
• State preservation (AutoPersistStates)
• Drag-and-drop support
• Event examples and patterns

Appearance and Customization

📄 Read: references/appearance-customization.md

• Header color and forecolor customization
• Font styling for headers
• Brush customization via ProvideHeaderBackgroundBrush and ProvideItemsBackgroundBrush events
• Adding images to headers and items
• Tooltip configuration and display
• Custom background drawing techniques

Spacing and Scrolling

📄 Read: references/padding-spacing-scrolling.md

• XPTaskBar interior padding (DockPadding, HorizontalPadding, VerticalPadding)
• Box header padding (PADX, PADY)
• Auto-scroll behavior
• Scroll margin and minimum size configuration

Common Patterns

Pattern 1: Multi-Box Task Menu

Create a sidebar with multiple collapsible task categories:

var taskBar = new XPTaskBar { VerticalLayout = true };

// Create boxes for different task categories
foreach (var category in new[] { "File", "Edit", "View", "Help" }) {
    var box = new XPTaskBarBox { Text = category };
    taskBar.Controls.Add(box);
    // Add items to box
}

Pattern 2: Item Click Routing

Use the Tag property to implement event routing:

box.ItemClick += (sender, e) => {
    var command = e.XPTaskBarItem.Tag as string;
    ExecuteCommand(command);
};

Pattern 3: Stateful Persistence

Remember user preferences across sessions:

xpTaskBar1.AutoPersistStates = true;

Pattern 4: Animated State Changes

Control animation behavior during expand/collapse:

box.AnimationDelay = 50;           // Milliseconds between frames
box.AnimationPositionsCount = 15;  // Number of animation steps
box.UseAdditionalAnimation = true; // Animate when adding/removing items

Key Configuration Properties

XPTaskBar Level

Property	Type	Purpose
VerticalLayout	bool	Set true for vertical mode (default), false for horizontal
ColWidthOnHorizontalAlignment	int	Column width in horizontal layout mode
HorizontalPadding	int	Interior horizontal spacing
VerticalPadding	int	Interior vertical spacing
AutoScroll	bool	Enable automatic scrollbars when needed
AutoPersistStates	bool	Persist expanded/collapsed state between sessions
AllowDrop	bool	Enable drag-and-drop support
MinimumSize	Size	Minimum control dimensions

XPTaskBarBox Level

Property	Type	Purpose
Text	string	Box header display text
Collapsed	bool	Set true to collapse, false to expand
ShowCollapseButton	bool	Show/hide collapse button
ToggleByButton	bool	Allow button to toggle state
HeaderBackColor	Color	Header background color
HeaderForeColor	Color	Header text color
HeaderFont	Font	Header text font
HeaderTextAlign	StringAlignment	Header text alignment
AnimationDelay	int	Delay in ms between animation frames
AnimationPositionsCount	int	Number of animation steps
PreferredChildPanelHeight	int	Height reserved for child controls
ShowToolTip	bool	Enable tooltips for items
PADX	int	Horizontal header padding
PADY	int	Vertical header padding

XPTaskBarItem Level

Property	Type	Purpose
Text	string	Item display text
ImageIndex	int	Index in parent box's ImageList
ToolTipText	string	Tooltip text on hover
Tag	object	Custom data for event routing

---

Next Step: Start with references/getting-started.md to set up your first XPTaskBar control.