Configuration

An object that defines configuration options for the dxPieChart widget.

adaptiveLayout

Specifies adaptive layout options.

Type: Object

When your scenario provides the capability to change the size of the widget container, this container may become too small for the widget to display all of its elements. In this case, the adaptive layout removes accessory widget elements, thus saving space for the most important ones. The elements are being removed in the following sequence.

  1. Chart margins
  2. Title margins or the whole title
  3. Legend
  4. Point labels (can be saved by setting the adaptiveLayout | keepLabels option to true)

To specify the container's size to be small enough for the layout to begin adapting, use the height and width options of the adaptiveLayout object.

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
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 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
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 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
    The argument of the point.
  • value
    The value of the point.
  • tag
    The tag of the point.
  • index
    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.

Cannot be used in themes.

To provide data for a chart, introduce an array of objects. These objects must contain a property representing an argument value and property(ies) representing the value(s) that corresponds to that argument in each series. Assign this array to the dataSource property. In addition, 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.


                                    

                                    

diameter

Specifies the diameter of the pie.

Type: Number
Default Value: undefined

This option accepts a number that identifies the ratio between the pie's diameter and the container's width or height (depending on which of them is lesser). For example, assume that the widget's container is 300x500 pixels and the diameter option is set to 0.5. Then, the resulting diameter of the pie will be:

0.5 * min(300,500) = 0.5 * 300 = 150 pixels

done

Deprecated

Use the onDone option instead.

Show Example:
jQuery

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


                                    

                                    

drawn

Deprecated

Use the onDrawn option instead.

incidentOccured

Deprecated

Use the onIncidentOccurred option instead.

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

Deprecated

Use the onLegendClick option instead.

loadingIndicator

Specifies the appearance of the loading indicator.

Type: Object

Usually, the widget is quick enough to draw itself instantly for a viewer. There are, however, cases, when the widget takes longer to be drawn. In such cases, displaying the loading indicator is recommended. To display the loading indicator, assign true to the show field of the loadingIndicator object. Use other fields of this object to change the appearance of the loading indicator.

Show Example:
jQuery

In this example, the data source is assigned to the chart 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.


                                    

                                    

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

onDisposing

A handler for the disposing event.

Type: function
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

Default Value: null

Assign a function to perform a custom action when you dispose of this component.

onDone

A handler for the done event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

Cannot be used in themes.

onDrawn

A handler for the drawn event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

Cannot be used in themes.

If you need to perform specific actions when the widget has finished drawing itself, assign a callback function to the drawn option. When implementing this function, you can access the drawn widget using the function's parameter.

onIncidentOccurred

A handler for the incidentOccurred event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

target: Object

Information about the occurred incident.

When an error or warning appears, the widget notifies you by passing a message to the browser console. This message contains the ID of the incident, a brief description, and a link to the Errors and Warnings section where further information about this incident can be found. However, you can handle errors and warnings in the way that you require. To do this, implement a callback function performing the required actions and assign it to the onIncidentOccurred option. Within this function, you can use information about the incident that occurred. This information can be accessed from the target field of the object passed to the callback function as a parameter. This information includes the following.

  • id
    Contains the ID of the incident. The full list of IDs can be found in the Errors and Warnings section.
  • type
    Contains the type of the incident. This field equals 'error' for errors or 'warning' for warnings.
  • args
    Contains the argument of the incident's message. The content of this field varies greatly, depending on the incident. For example, it may contain the name of the data source field that was not specified correctly, or the name of the option that was not set properly.
  • text
    Contains the text passed to the browser console. This text includes the content of the args field, if there are any.
  • widget
    Contains the name of the widget that produced the error or warning.
  • version
    Contains the currently used version of the ChartJS library.
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, the widget produces a warning. The function assigned to the onIncidentOccurred field is used to display the warning message under the widget. Uncheck the check box to restore the previous size of the chart container.


                                    

                                    

onLegendClick

A handler for the legendClick event.

Function parameters:

Information about the event.

Object structure:
component: Object
element: Object

The widget's container.

jQueryEvent: jQuery.Event

The jQuery event.

target: Point

The point that corresponds to the clicked legend item.

Cannot be used in themes.

When implementing a handling function, use the object passed to it as its parameter. Among the fields of this object, you can find the point that corresponds to the clicked legend item. To learn about point members you can use, refer to the description of the Point object.

NOTE: A click on the legend causes the pointClick event to fire after the legendClick event. To prevent this behavior, assign true to the jQueryEvent.cancel field of the object passed to the legendClick event handler as the argument.

Alternatively, you can navigate to a specific URL when the legendClick event fires. For this purpose, assign this URL to the onLegendClick option.

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.


                                    

                                    

onOptionChanged

A handler for the optionChanged event.

Type: function
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

value: any

Specifies a new value for the option.

Default Value: null

Assign a function to perform a custom action after an option of the component is changed.

onPointClick

A handler for the pointClick event.

Function parameters:

Information about the event.

Object structure:
component: Object
element: Object

The widget's container.

jQueryEvent: jQuery.Event

The jQuery event.

target: Point

The clicked series point.

Cannot be used in themes.

When implementing a handling function, use the object passed to it as its parameter. Among the fields of this object, you can find the clicked series point. To learn about point members, refer to the description of the Point object.

NOTE: The function handling the pointClick event is also called when a user clicks the legend, but only if it is not canceled in the legendClick event handler.

Alternatively, you can navigate to a specific URL when the pointClick event fires. For this purpose, assign this URL to the onPointClick option.

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

View Demo

Show Example:
jQuery

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


                                    

                                    

onPointHoverChanged

A handler for the pointHoverChanged event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

target: Point

The series point whose hover state has been changed.

Cannot be used in themes.

When implementing a handling function, use the object passed to it as its parameter. Among the fields of this object, you can find the series point whose hover state has been changed. To identify whether this point was hovered over or hovered out, call its isHovered() method. To discover point fields and methods, refer to the Point class description.

To learn more about how to handle hover operations, refer to the Hover Handling topic.

onPointSelectionChanged

A handler for the pointSelectionChanged event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

target: Point

The series point whose selection state has been changed.

Cannot be used in themes.

When implementing a handling function, use the object passed to it as its parameter. Among the fields of this object, you can find the series point whose selection state has been changed. To identify whether this point was selected or deselected, call its isSelected() method. To discover point fields and methods that you can use, refer to the Point class description.

To learn more about how to handle selection, refer to the Selection Handling topic.

onTooltipHidden

A handler for the tooltipHidden event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

target: Point

The series point whose tooltip becomes hidden.

Cannot be used in themes.

The point's tooltip becomes invisible when a user hovers the mouse cursor over another series point. 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 by handling the tooltipHidden event. To do this, implement a handling function and assign it to the onTooltipHidden option. When implementing this function, use the object passed to it as its parameter. Among the fields of this object, you can find the series point whose tooltip becomes hidden.

Show Example:
jQuery

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


                                    

                                    

onTooltipShown

A handler for the tooltipShown event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: Object

The widget's container.

target: Point

The series point whose tooltip appears.

Cannot be used in themes.

The point's tooltip appears when a user hovers the mouse cursor over the point. In addition, you can show a tooltip in code, using the showTooltip() method of the chart or point.

When a tooltip appears, you can perform specific actions by handling the tooltipShown event. To do this, implement a handling function and assign it to the onTooltipShown option. When implementing this function, use the object passed to it as its parameter. Among the fields of this object, you can find the series point whose tooltip appears.

Show Example:
jQuery

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


                                    

                                    

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 an HTML page that uses a path modifier.

Type: Boolean
Default Value: false
Cannot be used in themes.

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 enable this option if you place the widget inside the <iframe> tag.

pointClick

Deprecated

Use the onPointClick option instead.

pointHoverChanged

Deprecated

Use the onPointHoverChanged option instead.

pointSelectionChanged

Deprecated

Use the onPointSelectionChanged option instead.

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

Specifies whether to redraw the widget when the size of the parent browser window changes or a mobile device rotates.

Type: Boolean
Default Value: true
Cannot be used in themes.

When this option is set to true, the widget will be redrawn automatically in case the size of its parent window changes.

NOTE: To redraw the widget after the size of its container has changed, call the render() method of the widget instance.

resolveLabelOverlapping

Specifies how the chart must behave when series point labels overlap.

Type: String
Default Value: "none"
Accepted Values: "none" | "hide" | "shift"

Series point labels display series point values. If the series in your pie chart contains a large number of points, point labels may overlap. In this case, specify how the chart must resolve overlapping using the resolveLabelOverlapping option. To hide certain labels, set this option to 'hide'. Labels to be hidden will be determined automatically. To resolve overlapping by shifting labels from their positions, set the resolveLabelOverlapping option to 'shift'. In this case, we recommend displaying label connectors so that pie segments are connected with their labels.

NOTE
If there is not enough space for all labels after they are shifted, labels with the smallest values will be hidden.

View Demo

rtlEnabled

Specifies whether or not the widget supports right-to-left representation.

Type: Boolean
Default Value: false
Cannot be used in themes.

The most common scenario is switching all the widgets to a right-to-left reading order. In this instance, set the DevExpress.rtlEnabled field to true. If you need to switch the reading order in a particular widget, use the rtlEnabled configuration option of this widget.

series

Specifies options for the series of the dxPieChart widget.

Type: Object
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'
Accepted Values: 'desktop'|'desktop-dark'|'android'|'android-holo-light'|'ios'|'win8'|'win8-white'

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

Deprecated

Use the onTooltipHidden option instead.

tooltipShown

Deprecated

Use the onTooltipShown option instead.