## Overview

The New Gantt widget enables the visualization and editing of planning elements and hybrid elements. Built on the Bryntum Gantt framework, it displays tasks as horizontal bars on a timeline, showing start dates, end dates, duration, and progress. The widget supports hierarchical task structures with expandable/collapsible tree views and allows users to manage dependencies between tasks.

Key capabilities include:
- **Visual timeline representation** of tasks with bars showing duration and progress
- **Interactive editing** through drag-and-drop repositioning and bar resizing
- **Dependency management** for creating and visualizing task relationships
- **Hierarchical structure** with parent-child task relationships
- **Multi-schedule support** for displaying tasks from one or multiple schedules
- **Real-time synchronization** between the chart and cplace backend
- **Hybrid element support** for tasks referenced from external systems

## Use Cases

### Project Planning Visualization
Display the entire project timeline at a glance to understand task sequences, identify critical paths and bottlenecks, and monitor progress through percent completion indicators.

### Interactive Schedule Management
Adjust task dates by dragging bars, modify durations by resizing, create predecessor/successor relationships, and update task properties inline without leaving the chart view.

### Multi-Schedule Planning
Consolidate and compare timelines across different projects or work packages by displaying tasks from multiple schedules in a single unified view for portfolio-level planning.

### Hybrid Element Planning
Work with both native planning elements and hybrid elements that reference tasks from other systems, including delegated tasks sourced from external schedules and mirrored tasks that reflect changes from source tasks.

## Design Considerations

### When to Use
- Users need a graphical timeline view rather than a table/list view
- Visual planning and scheduling is important for understanding the project
- Users need to interactively adjust dates through drag-and-drop
- Understanding task relationships and dependencies is critical
- Working with complex project hierarchies that benefit from tree + timeline views
- Real-time collaboration on schedule adjustments is needed

### When to Consider Alternatives
- Users only need a simple task list without timeline visualization (use Schedule Tree Widget)
- Primary focus is on data entry and bulk editing (table views may be more efficient)
- Detailed attribute editing is the main activity (use detail pages or forms)
- Very large datasets (1000+ tasks) may require filtering for performance

### Configuration Options
- **Schedule Selection**: Either explicitly specify schedules via the SCHEDULE attribute, or automatically load from the embedding page (SCHEDULE_SELECTION attribute)
- **Widget Title**: Custom title for display (defaults to "Gantt chart for the schedules {names}")
- **Height**: Fixed height setting for vertical space allocation
- **Root Node Configuration**: Specify which nodes should appear as root elements in the hierarchy

### Embedding Restrictions
- Only one Gantt widget instance allowed per page
- Requires the Gantt2 feature to be enabled
- Cannot be configured directly in view mode

## Related Patterns/Alternatives

| Widget | When to Use Instead |
|--------|---------------------|
| **Schedule Tree Widget** (`cf.projektplanung.scheduleTreeTable`) | For table-based schedule views without timeline visualization; better suited for data-heavy operations and bulk editing. Often used alongside the Gantt on the same page. |
| **Schedule Lock State Widget** (`cf.projektplanung.scheduleLockState`) | Used alongside Gantt to show lock state of schedules and prevent concurrent editing conflicts |
| **Single Gantt Widget** (`cf.projektplanung.singleGantt`) | For simpler single-schedule Gantt views |