# Taskbar Styles

A tutorial on how to set styles for taskbars in SpreadJS GanttSheets, including UI and code examples

## Content

In Gantt charts, taskbar styles play an important role in visualizing project data. By changing taskbar styles, you can increase the clarity and emphasis of specific tasks. You can modify the style of a specific taskbar using the specified style rules, and then the style will be applied to all tasks that match the rule. In a Gantt chart, you can customize the taskbars' color, shape, end type, patterns, and text using the **GANTT** **CHART FORMAT** \> **Format** \> **Bar Styles** option in the Spread Designer UI.

![GS-barstyles](https://cdn.mescius.io/document-site-files/images/ef9b66d1-0ae2-4e94-b8cb-f9f893aacc8d/GS-barstyles.548ee3.png?width=691)

> **Note**: The taskbar style can only be changed if a primary key exists.

## Built-in Taskbar Types

The type of a taskbar based on its field values. For example, if you change the "Mode" field of a normal task from "Auto" to "Manually", the task will change to a manually scheduled task, and then it will display different styles to separate itself from other normal taskbars. 
The modified taskbar styles always correspond to the specific taskbar type. The following table lists the rule names for each task types.

| @cols=1:**Name** | @cols=1:**Show For**  | @cols=1:**From** | @cols=1:**To** |
| ---- | --------- | ---- | --- |
| @cols=1:@rows=1:task | @cols=1:@rows=1:Normal tasks, not manually scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:progress | @cols=1:@rows=1:Normal tasks, not manually scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Complete Through |
| @cols=1:@rows=1:manualTask | @cols=1:@rows=1:Normal tasks, manually scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:manualProgress | @cols=1:@rows=1:Normal tasks, manually Scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Complete Through |
| @cols=1:@rows=1:milestone | @cols=1:@rows=1:Milestone tasks, not manually scheduled | @cols=1:@rows=1:Task Finish | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:summary | @cols=1:@rows=1:Summary tasks, not manually scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:manualSummary | @cols=1:@rows=1:Summary tasks, manually scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:projectSummary | @cols=1:@rows=1:Project Summary | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:durationOnly | @cols=1:@rows=1:Active tasks, manually scheduled, but not a Milestone task | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:startOnly | @cols=1:@rows=1:Manually scheduled, not Milestone tasks | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Start |
| @cols=1:@rows=1:finishOnly | @cols=1:@rows=1:Manually scheduled, not Milestone tasks | @cols=1:@rows=1:Task Finish | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:manualMilestone | @cols=1:@rows=1:Milestone tasks, active, manually scheduled | @cols=1:@rows=1:Task Finish | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:durationOnlyMilestone | @cols=1:@rows=1:Milestone tasks, manually scheduled | @cols=1:@rows=1:Task Finish | @cols=1:@rows=1:Task Finish |
| @cols=1:@rows=1:startOnlyMilestone | @cols=1:@rows=1:Milestone tasks, manually scheduled | @cols=1:@rows=1:Task Start | @cols=1:@rows=1:Task Start |
| @cols=1:@rows=1:finishOnlyMilestone | @cols=1:@rows=1:Milestone, Manually Scheduled | @cols=1:@rows=1:Task Finish | @cols=1:@rows=1:Task Finish |

## Get Built-In Style Rules

SpreadJS provides several built-in style rules for each taskbar type based on [GC.Spread.Sheets.GanttSheet.TaskbarStyleRuleName](/spreadjs/api/modules/GC.Spread.Sheets.GanttSheet#taskbarstylerulename) type. Each taskbar has **Start**, **Middle**, and **End** areas that can be customized independently. Taskbar start and end areas allow changes to shape, type, and color, whereas the middle area customization includes options for shape, pattern, and color. Moreover, you can also add text information on different sides of a taskbar, such as left, right, top, bottom, and inside.

##### Example 1

The following code samples show how to change the color of a taskbar start area and add left and top texts for a taskbar. Here, the `getRule()` method of the [taskStyleRules ](/spreadjs/api/classes/GC.Spread.Sheets.GanttSheet.Collection)collection is used to get the style rule and then the taskbar style of the target style rule is updated with the modified style object.

```javascript
// Change the color of the taskbar start area.
var targetBuiltInStyleRuleName = "task";
var targetStyleRule = ganttSheet.project.taskStyleRules.getRule(targetBuiltInStyleRuleName);
var targetStyle = targetStyleRule.style.taskbarStyle;
targetStyle.startColor = "red";
targetStyleRule.style.taskbarStyle = targetStyle;

// Configure left text and top text.
var targetBuiltInStyleRuleName = "task";
var targetStyleRule = ganttSheet.project.taskStyleRules.getRule(targetBuiltInStyleRuleName);
var targetStyle = targetStyleRule.style.taskbarStyle;
targetStyle.leftText = "taskNumber";
targetStyle.topText = "=[@duration]";
targetStyleRule.style.taskbarStyle = targetStyle;
```

Let's have another example to get a task instance from the project, and then update the taskbar styles with some specific fields using the [GC.Spread.Sheets.GanttSheet.TaskbarStyle](/spreadjs/api/modules/GC.Spread.Sheets.GanttSheet#taskbarstyle) type.

##### Example 2

```javascript
// Get the style of a task and change its style properties.
var task = ganttSheet.project.getTask(8);
console.log(task);
var newBarStyles = {};
newBarStyles["summary"] = {
      taskbarStyle: {
             startShape: "lineShape",
             startType: "solid",
             startColor: "Red",
             middlePattern: "diagonalLeft",
             middleShape: "rectangleBar",
             middleColor: "Yellow",
             endShape: "lineShape",
             endType: "solid",
             endColor: "Green",
             leftText: "taskNumber",
             bottomText: "duration",
             topText: '="Task Name: " & [@name]',
       }
}
task.style = newBarStyles;

var summaryTask = ganttSheet.project.getTask(4);
var summaryTaskStyles = {};
summaryTaskStyles["summary"] = {
        taskbarStyle: {
               startShape: "triangleRight",
               startType: "dashed",
               startColor: "#3a5823",
               middlePattern: "lineVertical",
               middleShape: "rectangleMiddle",
               middleColor: "#579863",
               endShape: "triangleLeft",
               endType: "dashed",
               endColor: "#3a5823",
               topText: "duration",
        }
}
summaryTask.style = summaryTaskStyles;
```

The output of the above code will look like below.

![GS-taskbarStyles](https://cdn.mescius.io/document-site-files/images/ef9b66d1-0ae2-4e94-b8cb-f9f893aacc8d/GS-taskbarStyles.c40266.png?width=892)

## Create Custom Style Rules

SpreadJS also allows you to create a custom style rule based on the [GC.Spread.Sheets.GanttSheet.TaskbarStyleRule](/spreadjs/api/classes/GC.Spread.Sheets.GanttSheet.TaskbarStyleRule) class. Once created, taskbar style rule will change the style of tasks that match the rule.

```javascript
// Create new the custom style rule.
var ruleName = "My Progress";
class MyProgressRule extends GC.Spread.Sheets.GnattSheet.TaskBarStyleRule {
    constructor() {
        super(ruleName);
        this.style = {
            taskbarStyle: {
                middleColor: "#3B87D4",
                middleShape: "rectangleMiddle",
                middlePattern: "solidFill"
            }
        };
    }
    match(task: GC.Spread.Sheet.GanttSheet.Task): boolean {
        return task.complete > 0;
    }
    getFromDate(task: GC.Spread.Sheet.GanttSheet.Task) {
        return task.startDisplayed;
    }
    getToDate(task: GC.Spread.Sheet.GanttSheet.Task) {
        return task.completeThrough;
    }
}

// Add the custom style rule to the taskbar style rule collection.
var styleRules = ganttSheet.project.taskStyleRules;
var customStyleRule = new MyProgressRule();
styleRules.add(customStyleRule);

// Update an existing custom style rule.
var ruleName = "My Progress";
var styleRules = ganttSheet.project.taskStyleRules;
var customStyleRule = styleRules.getRule(ruleName);
if (customStyleRule) {
    var style = customStyleRule.style.taskbarStyle;
    // Update style.
    style.middleColor = "red";
    // Change style.
    customStyleRule.style.taskbarStyle = style;
}
```

## Remove Custom Style Rules

In addition to adding or updating the style of taskbar style rules, you can also delete or clear rules using the `remove()` and `clear()` methods of the `TaskStyleRules` <span style="color: rgb(34, 34, 34); font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, Noto Sans, Liberation Sans, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji, Font Awesome 5 Free; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;">collection</span> of the [GC.Spread.Sheets.GanttSheet.Project](/spreadjs/api/classes/GC.Spread.Sheets.GanttSheet.Project#taskstylerules) class.