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

• 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 - 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

Getting Started

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

Building the Structure

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

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

Layout and Orientation

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

Behavior and Interactivity

• 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

• 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

• 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

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

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

Pattern 3: Stateful Persistence

xpTaskBar1.AutoPersistStates = true;

Pattern 4: Animated State Changes

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

VerticalLayout

ColWidthOnHorizontalAlignment

HorizontalPadding

VerticalPadding

AutoScroll

AutoPersistStates

AllowDrop

MinimumSize

XPTaskBarBox Level

Text

Collapsed

ShowCollapseButton

ToggleByButton

HeaderBackColor

HeaderForeColor

HeaderFont

HeaderTextAlign

AnimationDelay

AnimationPositionsCount

PreferredChildPanelHeight

ShowToolTip

PADX

PADY

XPTaskBarItem Level

Text

ImageIndex

ToolTipText

Tag