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

XPTaskBarBox Level

XPTaskBarItem Level

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