Configuration

An object that defines configuration options for the dxPieChart widget.

animation

Specifies animation options.

Type: Object|Boolean

To make your chart "live", enable animation for it. To do this, set the enabled option of the animation object to true. In this instance, the chart series will appear in motion. The animation object provides more options to set up chart animation. Refer to their description for details.

Show Example:
jQuery

In the example below, the animation's duration option is altered to 3000 milliseconds and the type of easing is set to linear.


                                    

                                    

customizeLabel

Specifies a callback function that returns an object with options for a specific point label.

Type: function(labelInfo)
Function parameters:
labelInfo: Object
Information on the label to be customized
Return Value: Label
A configuration object for the label

By default, all point labels on a chart are displayed identically. But you can specify a different appearance for specific labels using the customizeLabel field. Assign a function to this field. This function should return an object with options that should be changed for a certain label. Refer to the label object description to learn about the options that can be changed.

When implementing a callback function for this option, you can access the following fields of the function's parameter.

  • argument
    The argument of the label's point.
  • value
    The value of the label's point.
  • tag
    The tag of the label's point.
  • index
    The index of the label's point in the points array.

In addition, these values can be accessed using the this object.

Show Example:
jQuery

In this example, if a pie slice has a value greater than 500 million, its label is colored in 'deepskyblue' using the customizeLabel option. If not, the slice label is painted in a color from a predefined palette.


                                    

                                    

customizePoint

Specifies a callback function that returns an object with options for a specific point.

Type: function(pointInfo)
Function parameters:
pointInfo: Object
Information on the point to be customized.
Return Value: Point
A configuration object for the point.

By default, all the points of a pie are displayed identically. But you can specify a different appearance for certain points using the customizePoint field. Assign a function to this field. This function should return an object with options that should be changed for a certain point. The following pie options can be changed.

When implementing a callback function for this option, use the argument or value of a point. They can be accessed using the following fields of the function's parameter.

  • argument
    Represents the argument of the point.
  • value
    Represents the value of the point.
  • tag
    Represents the tag of the point.
  • index
    Represents the index of the point in the points array.

In addition, these values can be accessed using the this object.

Show Example:
jQuery

In this example, those pie slices that have a value greater than 500 million are colored in 'pink' using the customizePoint option. The other slices are painted in a color from a predefined palette.


                                    

                                    

dataSource

Specifies a data source for the chart.

Type: Array

To provide data for a chart, use the dataSource option. This option takes on one of the following:

  • An Array of objects
    These objects must contain a field representing an argument value and field(s) representing the value(s) that corresponds to that argument in each series.

  • A DataSource object
    This object is specially designed to provide an easy way to get data from any storage (local, memory or a data service). The DataSource is a stateful object that includes options for data sorting, grouping, filtering; it also keeps data transformation options and applies them each time data is loaded. It also provides events intended to handle changing data and the state. The DataSource underlying data access logic is isolated in a Store. Unlike the DataSource, a Store is a stateless object implementing a universal interface for reading and modifying data. To learn more, refer to the Data Layer description.

In addition to a data source, specify which data source field must be used as a source for arguments and which one(s) as a source for values. To do this, use the argumentField and valueField properties of the series object. For details, refer to the Data Binding topic.

Show Example:
jQuery

In this example, the data source is declared as an array of objects, each of which contain the 'continent' and 'population' fields. The 'continent' field is used as an argument field for the pie series. The 'population' field is used as a value field for the pie series.


                                    

                                    

done

A callback function that is called when chart rendering is complete.

Type: function()
Default Value: Empty function ($.noop)

Show Example:
jQuery

In this example, when chart rendering is complete, a message with the corresponding content appears.


                                    

                                    

incidentOccured

Specifies a callback function that is called when an error or warning occurs.

Type: function(message)
Function parameters:
message: String
Specifies information about the incident.
Default Value: Empty function ($.noop)

When an error or warning occurs, nothing passes to the browser console, but the function specified for the incidentOccured option is called. Information about the incident is available via the parameter of the function. For example, you will be notified when data is input in the wrong format, or when the chart container is too small.

Show Example:
jQuery

Use the check box below to change the size of the chart container. When checking the check box, the chart container becomes too small to display the chart. As a result, an error occurs. The function assigned to the incidentOccured field is used to receive the message about the error. Uncheck the check box to restore the previous size of the chart container.


                                    

                                    

legend

Specifies dxPieChart legend options.

Type: Object

The dxPieChart widget can include a legend. It helps you distinguish and identify the points of the displayed series. Each point is presented by an item on the legend. An item marker identifies the point's (slice's) color. An item label displays a value corresponding to the point. Use the legend property to set up dxPieChart legend options to the required values. To learn more about the legend and its options, refer to the Legend topic.

Show Example:
jQuery

In this example, the legend's horizontalAlignment and verticalAlignment options are changed.


                                    

                                    

legendClick

Specifies a function that is called when an item on the chart legend is clicked.

Type: jQuery.Event
Event Handler Argument:
series: Series
The series to which the currently clicked legend item belongs.
jQueryEvent: jQuery.Event
The event object.

When implementing a callback function for this option, use the object that represents the series to which the currently clicked legend item belongs. To access this object, use the function's first parameter or the this object. In addition, you can access the jQuery-event object using the function's second parameter.

NOTE: If the legendClick option is not specified, a click on the legend will invoke the function assigned to the pointClick option. To prevent this behavior, assign at least an empty function to the legendClick field.

To learn about the point members you can use, refer to the description of the Point object.

To learn more about handling click operations and to see an example, refer to the Click Handling topic.

Show Example:
jQuery

Click one of the legend items and the information on the point corresponding to this legend item will appear below.


                                    

                                    

loadingIndicator

Specifies the appearance of the loading indicator.

Type: Object

In most cases, a chart is quick enough to draw itself instantly for a viewer. There are, however, cases when the chart takes longer to be drawn. In such cases, it is recommended that the loading indicator be shown. Use the chart's showLoadingIndicator() and hideLoadingIndicator() methods to manage the loading indicator. To specify its appearance, use the loadingIndicator configuration object.

Show Example:
jQuery

In this example, the chart options are assigned 3000 ms after the example is loaded. Until that time, the loading indicator is displayed. Its background and font are changed using the backgroundColor and font options respectively. Make a note that these options should be specified at design-time so that the changes are applied at the right time.


                                    

                                    

margin

Specifies the blank space between the chart's extreme elements and the boundaries of the area provided for the widget (see size) in pixels.

Type: Object

Set the required values for the left, right, top and bottom margins using the corresponding properties of the margin object.

PieChartMargin ChartJS

palette

Sets the name of the palette to be used in the chart. Alternatively, an array of colors can be set as a custom palette to be used within this chart.

Type: Array|String
Default Value: 'Default'
Accepted Values: 'Default' | 'Soft Pastel' | 'Harmony Light' | 'Pastel' | 'Bright' | 'Soft' | 'Ocean' | 'Vintage' | 'Violet'

Use this property to set a predefined or custom palette. The colors listed in the specified palette will be used to draw series points (chart slices), their labels and tooltips. If the number of points is greater than the number of colors in a palette, the palette colors are repeated, but slightly modified.
You can define a custom palette and use it in your charts. To learn how to do this, refer to the Palettes topic.

Show Example:
jQuery

This example shows how to create a custom palette and apply it to a chart.


                                    

                                    

pathModified

Notifies a widget that it is embedded into the HTML page that uses a path modifier.

Type: Boolean
Default Value: false
Accepted Values: true|false

If you place a widget on a page that uses a path modifier, notify the widget about it by setting the pathModified option to true. As an example of such modifiers, the base HTML tag can be considered. Also, we recommend you to enable this option if you place the widget inside the <iframe> tag.

pointClick

Specifies a function that is called when a series data point is clicked.

Type: jQuery.Event
Event Handler Argument:
point: Point
The clicked point.
jQueryEvent: jQuery.Event
The event object.

When implementing a callback function for this option, use the object that represents the currently clicked point. To access this object, use the function's first parameter or the this object. In addition, you can access the jQuery-event object using the function's second parameter.

NOTE: The function assigned to the pointClick option is also called by clicking the legend when no function is assigned to the legendClick option.

For information on which point members you can use, refer to the Point class description. For instance, you can access the series to which the point belongs. To learn about which series members you can use, refer to the description of any series type in the chart Series Types section.

To learn more about handling click operations and to see an example, refer to the Click Handling topic.

Show Example:
jQuery

Click one of the points on the chart, and information on this point will appear below.


                                    

                                    

pointHover

Deprecated

Use the pointHoverChanged option instead.

Specifies the function that is called when a data point is hovered over.

Type: function

When implementing a callback function for this property, use the object that represents the currently hovered point. To access this object, use the function's parameter or the this object.

To learn about which point members you can use, refer to the Point class description. For instance, you can access the series to which the point belongs. To learn about which series members you can use, refer to the description of any series type in the chart Series Types section.

To learn more about handling hover operations and to see an example, refer to the Hover Handling topic.

pointHoverChanged

Specifies the function that is called when the hover state of a point has been changed.

Type: function(point)
Function parameters:
point: Point
The point whose hover state has been currently changed.

When implementing a callback function for this option, use the object that represents the point whose hover state has been currently changed. To access this object, use the function's parameter or the this object. To identify whether the point, whose hover state has been currently changed, was hovered over or hovered out, call the isHovered() method of this point.

To find out which point fields and methods you can use, refer to the Point class description within the Chart Elements reference section.

To learn more about the handling of hover operations, refer to the Hover Handling topic.

pointSelected

Deprecated

Use the pointSelectionChanged option instead.

Specifies the function that is called after a series data point has been selected.

Type: function

When implementing a callback function for this property, use the object that represents the currently selected point. To access this object, use the function's parameter or the this object.

To learn about which point members you can use, refer to the Point class description. For instance, you can access the series to which the point belongs. To learn about which series members you can use, refer to the description of any series type in the chart Series Types section.

To learn how to select a point, refer to the Selection Handling topic.

pointSelectionChanged

Specifies the function that is called when the selection state of a point has been changed.

Type: function(point)
Function parameters:
point: Point
The point that was selected or deselected.

When implementing a callback function for this option, use the object representing the point that was selected or deselected. To access this object, use the function's parameter or the this object. To identify whether the point was selected or deselected, call the isSelected() method of this point.

To find out which point fields and methods you can use, refer to the Point class description within the Chart Elements reference section.

To learn more about the handling of selection operations, refer to the Selection Handling topic.

pointSelectionMode

Specifies whether a single point or multiple points can be selected in the chart.

Type: String
Default Value: 'single'
Accepted Values: 'single' | 'multiple'

To set the points to highlight along with the selected point, set the series | selectionMode option.

To learn how to select a point, refer to the Selection Handling topic.

Show Example:
jQuery

In this example, click a point to select/deselect this point. The pointSelectionMode option is set to multiple so that you can select multiple points.


                                    

                                    

redrawOnResize

Indicates whether to redraw the chart when the size of the parent browser window changes or a mobile device is rotated.

Type: Boolean
Default Value: true
Accepted Values: true|false

The size of the chart is never changed when its container has a fixed size. Alternatively, its size changes proportionally when the parent window size changes and the redrawOnResize is set to true.

series

Specifies options for the series of the dxPieChart widget.

Type: Object|Array
Default Value: undefined

A series represents a grouping of related data points. The most important characteristic of a series is its type, which determines a particular visual representation of data. You can find more details on each series type in the corresponding topics in the Series help section.
To define a series, assign an object defining the series to the series configuration object. In the series' object, specify the series type, data source fields and other options.

size

Specifies the size of the widget in pixels.

Type: Object

The widget occupies the entire area of the parent container (division). If the container size (width or height) is set to zero, the widget is not displayed.

If you need to set a particular size for the widget, different from the container's size, use the size configuration object. Assign a height and width in pixels to height and width properties.

Show Example:
jQuery

In this example, the size of the chart is set smaller than the size of the chart container using the size option.


                                    

                                    

theme

Sets the name of the theme to be used in the chart.

Type: String
Default Value: 'desktop'

Use this property to set a predefined or custom theme. The options defining chart appearance will be set to the values that are set in the specified theme. You can override some of these values within the chart's configuration object. To learn more about themes, their implementation and customization, refer to the Themes topic.

Show Example:
jQuery

In this example, a custom theme is first defined on the base of the 'desktop' theme and then applied.


                                    

                                    

title

Specifies a title for the chart.

Type: Object|String

Use this property to set the text to be displayed as a chart title. If you need to specify the title's position on the chart, assign an object to the title property with the required title options specified. In this instance, set the title's text using the text property. When a text is not specified for a title, the widget is displayed without a title.

Show Example:
jQuery

In the example below, the chart's title text is assigned directly to the title field.


                                    

                                    

tooltip

Specifies tooltip options.

Type: Object

A tooltip is a small pop-up rectangle that displays information about a hovered series point. You can enable or disable tooltips, format or customize the displayed text, and change the default appearance. Use the properties of the tooltip configuration object to do this. To learn more about tooltips and their options, refer to the Tooltips topic.

Show Example:
jQuery

In this example, tooltips are enabled. Hover over any point to see a tooltip.


                                    

                                    

tooltipHidden

A callback function that is called when a point tooltip becomes hidden.

Type: function(point)
Function parameters:
point: Point
The point whose tooltip becomes hidden.
Default Value: Empty function ($.noop)

The point tooltip becomes invisible when another point is hovered. In addition, you can hide a tooltip in code, using the hideTooltip() method of the chart or point.

When a tooltip is made hidden, you can perform specific actions. To do this, implement a callback function and assign it to the tooltipHidden option. When implementing this callback function, use the object that represents the point whose tooltip becomes hidden. To access this object, use the function's parameter or the this object.

Show Example:
jQuery

In this example, when a tooltip is made hidden, the function assigned to the tooltipHidden option is called. When a tooltip is shown, the function assigned to the tooltipShown option is called. These functions display messages with corresponding content.


                                    

                                    

tooltipShown

A callback function that is called when a point tooltip becomes visible.

Type: function(point)
Function parameters:
point: Point
The point whose tooltip becomes shown
Default Value: Empty function ($.noop)

The point tooltip becomes visible when the point is hovered. In addition, you can show a tooltip in code, using the showTooltip() method of the chart or point.

When a tooltip is made visible, you can perform specific actions. To do this, implement a callback function and assign it to the tooltipShown option. When implementing this callback function, use the object that represents the point whose tooltip becomes shown. To access this object, use the function's parameter or the this object.

Show Example:
jQuery

In this example, when a tooltip is made hidden, the function assigned to the tooltipHidden option is called. When a tooltip is shown, the function assigned to the tooltipShown option is called. These functions display messages with corresponding content.