Dundas Chart for ASP.NET
Working with Commands
See Also Send comments on this topic.
Using Dundas Chart > User Interface > Working with Commands



Glossary Item Box

Overview

Enterprise Edition Only Feature.

Commands are the means to interact with user-interface elements. Each command contains a chart function that you can utilize to build your own customized toolbar, context menu, or both. Each command can be added as an item in the CommandUIItem collection. Commands are displayed as buttons contained in the toolbar, and menu items contained in the context menu.

All commands can have one or more sub-commands. The SubCommands collection is a collection of Command objects. As an example, the LoadGroup command has four sub-commands by default:

Types of Commands

Standard commands are provided for more than 100 common chart tasks, including 2D/3D toggling, chart type selection, 3D rotation, and more.

User-defined commands allow you to extend existing commands, or to create your own commands. Any command (or sub-command) can have user-defined functionality. As part of the chart UI, events are fired to allow you to provide user-defined customized functionality.

Visual Attributes

The Description property defines a textual description of the command that will be displayed as a tooltip in the toolbar. There is also a Text property, that is used to define the text of the command as it will appear in the context menu. These properties should both be set if you wish to display a command on both the toolbar and context menu.

Behavior

By default, each command contains built-in logic that determines the initial behavior of the command. However, this behavior can also be controlled by using several properties.

Showing and Hiding Commands

When the Enabled property is set to False, the command will appear in the toolbar as a grayed out item. When the Visible property is set to False, the command will not appear in the toolbar and context menu.

Display Styles

The PopupStyle property is used when a group of items is displayed on the UI. If PopupStyle is set to Menu, the UI will display the command as a menu item, with text, and an adjacent icon. If PopupStyle is set to Table, the UI will display the command as an icon within a table.

 

Figure 1: PopupStyle=Table (shown left), and PopupStyle=Menu (shown right).

 

Toggling

Toggling behaviors are most commonly defined to reflect different states of the chart. The Toggled property is simply a Boolean value that sets toggling on or off. The ToggleStyle property will further define the toggling behavior of the command. Its possible values are:

The ToggleStyle, ToggleGroupID, and Toggled properties all work in concert with each other. The default value of ToggleGroupID is zero, and this ID will work with other grouped commands that use this group ID. However, if other toggle groups are used, then the ToggleGroupID must be unique for each group.

Example

This example demonstrates how to add a toggled group of commands. This will allow the user to switch between a Line, Spline and StepLine chart type, simulating a radio button list, on the toolbar.

Visual Basic Copy Code
Imports Dundas.Charting.WebControl
...

Protected Sub Page_Load(sender As Object, e As EventArgs)

   If Not Me.IsPostBack Then
      ' Add a separator into the toolbar.
      Dim separator As Command = Chart1.UI.Commands.FindCommand(ChartCommandType.Separator)
      Chart1.UI.Toolbar.Items.Add(separator)
      
      ' Create new instance of line chart command.
      Dim selectLine As Command = Chart1.UI.Commands.FindCommand(ChartCommandType.SelectChartLine)
      selectLine.ToggleStyle = ToggleStyle.Grouped
      selectLine.ToggleGroupID = 100
      
      ' Set the line chart to be the toggled item by default.
      selectLine.Toggled = True
      
      ' Create new instance of spline chart command.
      Dim selectSpline As Command = Chart1.UI.Commands.FindCommand(ChartCommandType.SelectChartSpline)
      selectSpline.ToggleStyle = ToggleStyle.Grouped
      selectSpline.ToggleGroupID = 100
      
      ' Create new instance of step line chart command.
      Dim selectStepLine As Command = Chart1.UI.Commands.FindCommand(ChartCommandType.SelectChartStepLine)
      selectStepLine.ToggleStyle = ToggleStyle.Grouped
      selectStepLine.ToggleGroupID = 100
      
      ' Add all three commands to the toolbar.       
      Chart1.UI.Toolbar.Items.Add(selectLine)
      Chart1.UI.Toolbar.Items.Add(selectSpline)
      Chart1.UI.Toolbar.Items.Add(selectStepLine)
   End If   
End Sub
C# Copy Code
using Dundas.Charting.WebControl;
...

protected void Page_Load(object sender, EventArgs e)    
{  
    if (!this.IsPostBack)        
    {
        // Add a separator into the toolbar.
        Command separator = Chart1.UI.Commands.FindCommand(ChartCommandType.Separator);       
        Chart1.UI.Toolbar.Items.Add(separator);
        
        // Create new instance of line chart command.
        Command selectLine = Chart1.UI.Commands.FindCommand(ChartCommandType.SelectChartLine);
        selectLine.ToggleStyle = ToggleStyle.Grouped;
        selectLine.ToggleGroupID = 100;
        
        // Set the line chart to be the toggled item by default.
        selectLine.Toggled = true;
        
        // Create new instance of spline chart command.
        Command selectSpline = Chart1.UI.Commands.FindCommand(ChartCommandType.SelectChartSpline);
        selectSpline.ToggleStyle = ToggleStyle.Grouped;
        selectSpline.ToggleGroupID = 100;
        
        // Create new instance of step line chart command.
        Command selectStepLine = Chart1.UI.Commands.FindCommand(ChartCommandType.SelectChartStepLine);
        selectStepLine.ToggleStyle = ToggleStyle.Grouped;
        selectStepLine.ToggleGroupID =100;
        
        // Add all three commands to the toolbar.       
        Chart1.UI.Toolbar.Items.Add(selectLine);       
        Chart1.UI.Toolbar.Items.Add(selectSpline);       
        Chart1.UI.Toolbar.Items.Add(selectStepLine);
     }
 }

 

Figure 2: The last three toolbar commands as a toggled group.

 

Parameters

Command parameters are a set of comma-separated values that are used to customize existing commands, or create custom commands. You will need to refer to the Command Parameter List for a list of all commands, and their accepted parameters.

When using parameters in conjunction with formulas on the UI, the Params property of a command defines parameters that are unique to each formula. Formula parameters are generally used to specify time periods for calculations.

 

For more information on how to work with formula parameters, see the topic on Using Financial Formulas.

Customizing

You can customize commands on the toolbar or context menu in one of two ways, either:

 

Each customized command is automatically assigned a CommandID that you can use to identify the command when handling its events. To add a customized command to the UI, follow these steps:

  1. Add a new item to the Command collection.
  2. Set the appearance, and behavior of this user-defined command.
  3. Create a handler for the CommandFiredArgs to achieve the desired behavior for the command.

 

Example

This example demonstrates how to create a custom command and define its behavior when selected.

Visual Basic Copy Code
Imports Dundas.Charting.WebControl
...

Protected Sub Page_Load(sender As Object, e As EventArgs)

   If Not Me.IsPostBack Then
      'Create a new instance of the Command object.
      Dim userCommand As New Command()
      
      ' Set the command ID.
      ' This will be used when handling the command in the CommandFired event
      userCommand.CommandID = 300
      
      'Set the command tooltip that will appear on the toolbar.
      userCommand.Description = "Adds a series to the chart"
      
      ' Set the command text that will appear on the context menu.
      userCommand.Text = "Add Series"
      
      ' Add this user-defined command into the collection.
      Chart1.UI.Commands.Add(userCommand)
      
      ' Add this command on both the toolbar and context menu.
      Chart1.UI.Toolbar.Items.Add(userCommand)
      Chart1.UI.ContextMenu.Items.Add(userCommand)
   End If
   
End Sub 

Protected Sub Chart1_CommandFired(sender As Object, e As CommandFiredArgs)
   
   ' Check command ID.
   If e.Command.CommandID = 300 Then
      Chart1.Series.Clear()
      Chart1.Series.Add("Series1")
   End If
   
End Sub 'Chart1_CommandFired
C# Copy Code
using Dundas.Charting.WebControl;
...

protected void Page_Load(object sender, EventArgs e)
{
    if (!this.IsPostBack)
    {
        //Create a new instance of the Command object.
        Command userCommand = new Command();
            
        // Set the command ID.
        // This will be used when handling the command in the CommandFired event.
        userCommand.CommandID = 300;
        
        //Set the command tooltip that will appear on the toolbar.
        userCommand.Description = "Adds a series to the chart";
          
        // Set the command text that will appear on the context menu.
        userCommand.Text = "Add Series";
        
        // Add this user-defined command into the collection.
        Chart1.UI.Commands.Add(userCommand);
    
        // Add this command on both the toolbar and context menu.
        Chart1.UI.Toolbar.Items.Add(userCommand);
        Chart1.UI.ContextMenu.Items.Add(userCommand);
    }
}

protected void Chart1_CommandFired(object sender,CommandFiredArgs e)
{
    // Check command ID
    if (e.Command.CommandID == 300) 
    {
        Chart1.Series.Clear();
        Chart1.Series.Add("Series1");   
    }
}

 

Limitations

The UseLastSubCommand, and AllowMouseMoving properties, as well as the AddAnnotation commands, are no longer supported in Dundas Chart for ASP.NET. 

See Also

Copyright © 2001 - 2009 Dundas Data Visualization, Inc. and others.