With this template you can add a new Pie Chart component to your project. Pie Chart is a component intended to display diagrams composed of slices. As such this widget is not suitable to be controlled by the user interactively.

Components created with this template are intended to be adapted to your particular design expectations. After adding the new Pie Chart you should edit the component, change its appearance and if desired also its behavior. Once you have adapted the component, you can embed instances of this Pie Chart wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Pie Charts created by the template are working widgets. If desired, they can already be used as they are. The following figure demonstrates the default appearance of the Pie Chart created by using the here described component template:

The approach with component templates has two functions. Primarily the templates should simplify the development of new components. Instead of creating the Pie Chart from scratch you can use the available template. The second function is more educative. The template implements fully working Pie Chart component you can investigate and learn about the corresponding programming aspects. The template is well documented. It contains annotations and inline comments with instructions helping you to understand how the component works and how it can be adapted to your particular needs.

This chapter provides an overview how the Pie Chart component template is used within your own application and how you adapt this component according to your particular needs. You will find here also further details concerning the internal implementation of the Pie Chart component.

To create a new Pie Chart component from a template you simply Drag & Drop it between the Templates window and the Composer with an opened unit. This is important in that by using the component templates you add in fact a new class to your project. Classes, in turn, can exist within units only. The following are the typical steps to create a new Pie Chart component from a template:

In order to demonstrate the usage of the Pie Chart component, the template includes an Example component. This example demonstrates practical usage patterns including how to implement the data loading via OnLoadValue slot method and how to animate slice values using animation effects. It is recommended to study this example component before deletion to understand these important concepts. If not needed afterwards, just select and delete the Example class.

The new created Pie Chart component appears accompanied by annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Once you have created the Pie Chart component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Pie Chart class in-place within some superior GUI component. At the runtime, the superior GUI component takes care of the correct initialization and the displaying of all embedded components, so they appear similarly as you have composed them at the design time.

The following are the typical steps to create a new instance of an already existing Pie Chart component:

As long as the Pie Chart is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below. This is in so far worth mentioning as diverse features of the Pie Chart are controlled by the corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

The Pie Chart component descends from the Mosaic class Core::Group. Consequently, most of the properties listed in the above screenshot are inherited from this base class. Particular to the Pie Chart are only few following properties:

Property	Description
Displacement	The property Displacement stores the offset in pixel to move the slices away from the center of the chart. This results in the slices being separated.
NoOfValues	The property NoOfValues stores how many slices are currently managed within the chart component. This value should correspond to the number of data entries the chart presents to the user.
OnLoadValue	The property OnLoadValue should refer to a slot method, which will be invoked by the chart component in order to load the data for a given slice. The slot method receives no parameters. Instead, within the slot method implementation you access the Index variable to identify which slice is being loaded, and set the Value and Color variables to specify the slice's data. When the referred property is modified by other widget or the application logic, the Pie Chart is automatically notified to remain in sync with the property.
Radius	The property Radius specifies the outer radius of the pie slices expressed in pixel. If this value is 0 (zero), the radius is calculated automatically from the bounds of the Pie Chart component.
StartAngle	The property StartAngle specifies the angle in degrees where the first slice starts. Changing this property has the effect of the entire chart being rotated. For example, in order to arrange the first slice at the clock position 12:00, initialize this property with the value -90.
Width	The property Width specifies the width of a ring (or donut) expressed in pixel. If this value is 0 (zero), the chart displays slices instead of rings.

Once added to the component, you can freely move the Pie Chart instance, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the component also by directly modifying its property Bounds. If you want the Pie Chart to appear behind other views you can reorder it explicitly.

The Pie Chart is intended to display multiple slices representing individual data values. The number of slices is determined by the widget's property NoOfValues. By evaluating this property you can query how many slices are currently displayed in the affected widget. When you modify the property NoOfValues, the Pie Chart will automatically update to show the correct number of slices. For example:

The appearance of the slices is controlled by several properties that define their size, rotation, and spacing:

Property	Description
Displacement	The property Displacement stores the offset in pixel to move the slices away from the center of the chart. This results in the slices being separated.
Radius	The property Radius specifies the outer radius of the pie slices expressed in pixel. If this value is 0 (zero), the radius is calculated automatically from the bounds of the Pie Chart component.
StartAngle	The property StartAngle specifies the angle in degrees where the first slice starts. Changing this property has the effect of the entire chart being rotated. For example, in order to arrange the first slice at the clock position 12:00, initialize this property with the value -90.
Width	The property Width specifies the width of a ring (or donut) expressed in pixel. If this value is 0 (zero), the chart displays slices instead of rings.

The outer radius of the slices is controlled by the property Radius expressed in pixel units. If set to 0 (zero), the radius is calculated automatically to fit within the component's bounds. When the radius is calculated automatically, the chart will always fit within its bounds. If you specify an explicit radius value, you need to ensure the component is large enough to accommodate the chart, especially when using displacement. For example:

The property Width determines whether the chart displays as regular pie slices or as donut rings. When set to 0 (zero), the chart displays traditional pie slices. When set to a value greater than zero, the chart displays rings (donuts) with the specified width. For example:

The property StartAngle specifies the angle in degrees where the first slice begins. This effectively rotates the entire chart. The angle is measured clockwise from the positive X-axis (3 o'clock position). For example:

The property Displacement specifies an offset in pixels to move the slices away from the center of the chart. This creates an "exploded" pie chart effect where slices are separated with gaps between them. The displacement is automatically scaled based on the size of each slice to create uniform gaps. Larger slices move less distance than smaller slices, resulting in equal spacing between all slices. For example:

The following figures demonstrate a Pie Chart configured with Width set to 0 (left image - traditional slices) and Width set to 70 (middle image - donut rings). The right image shows a Pie Chart with Displacement set to 5 and StartAngle set to 0:

The Pie Chart loads data dynamically at runtime through a callback mechanism. To provide the data (value and color) for each slice, you need to implement a slot method and connect it to the chart's OnLoadValue property. The chart will invoke this slot method automatically whenever it needs to load or reload data for a slice.

The data exchange between the Pie Chart and your slot method uses three variables that are members of the Pie Chart component:

Variable	Description
Index	This variable identifies which slice is being loaded. The first slice has index 0, the second slice has index 1, and so on. Your slot method should read this variable to determine which data to provide.
Value	This variable should be set by your slot method to specify the size of the slice. The value ranges from 0.0 to 1.0, where 0.0 means an empty slice and 1.0 means a slice that fills the entire circle (360 degrees).
Color	This variable should be set by your slot method to specify the color of the slice.

The following example demonstrates a typical implementation pattern:

A simpler example without external data sources could look like this:

When the underlying data changes and the Pie Chart needs to update its appearance, you must explicitly request the reload operation by calling the method InvalidateValues. This method accepts two parameters specifying the range of slices to reload:

After calling InvalidateValues, the Pie Chart will automatically invoke your OnLoadValue slot method for each affected slice to reload its data.

Component templates are intended to create widgets which can be adapted and enhanced to your particular design expectations. For this purpose, once you have added a new Pie Chart component to your project, you can open the component class for editing. Thereupon the implementation of the component appears in a new Composer page:

Originally, if not yet modified, the Pie Chart appears with an empty canvas area. The slices are created dynamically at runtime within an Outline view. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The slices are displayed as Filled Path views, each positioned, shaped, and colored according to the data provided through the OnLoadValue callback mechanism.

This default functionality is implemented by following members belonging to the Pie Chart. These members are explicitly intended to be modified. Understanding this internal structure is thus the first step before you start to adapt the Pie Chart to your particular needs:

Icon	Member	Description
	NoOfValues	The property NoOfValues stores how many slices are currently managed within the chart component. This value should correspond to the number of data entries the chart presents to the user.
	OnSetNoOfValues	The onset method belongs to the property NoOfValues. Each time the value of the property is changed, the code implemented in the method is executed to schedule an update of all slices.
	Displacement	The property Displacement stores the offset in pixel to move the slices away from the center of the chart.
	OnSetDisplacement	The onset method belongs to the property Displacement. Each time the value of the property is changed, the code implemented in the method is executed to request an update of all slices.
	StartAngle	The property StartAngle determines the angle where the first slice starts, effectively controlling the rotation of the entire chart.
	OnSetStartAngle	The onset method belongs to the property StartAngle. Each time the value of the property is changed, the code implemented in the method is executed to reload all slice data with the new rotation angle.
	Width	The property Width determines the width of rings when displaying the chart as a donut. A value of 0 displays traditional pie slices.
	OnSetWidth	The onset method belongs to the property Width. Each time the value of the property is changed, the code implemented in the method is executed to request an update of all slices.
	Radius	The property Radius specifies the outer radius of the slices. A value of 0 enables automatic radius calculation based on component bounds.
	OnSetRadius	The onset method belongs to the property Radius. Each time the value of the property is changed, the code implemented in the method is executed to request an update of all slices.
	OnLoadValue	The property OnLoadValue can refer to any slot method that should be invoked to load the data for a slice. When the Pie Chart needs to load data, it will invoke this slot method.
	Index	This variable identifies the slice which is about to be loaded by the external slot method OnLoadValue. The external slot method should read this variable to determine which slice's data to provide.
	Value	This variable is intended to receive the value for the currently loaded slice. The external slot method OnLoadValue should set this variable. The value ranges from 0.0 to 1.0 corresponding to the slice's proportion of the complete circle.
	Color	This variable is intended to receive the color for the currently loaded slice. The external slot method OnLoadValue should set this variable.
	invalidFirstValue	This internal variable stores the index of the first slice which needs an update. Used internally by the update logic.
	invalidLastValue	This internal variable stores the index of the last slice which needs an update. Used internally by the update logic.
	size	This internal variable stores the previous size of the chart component. It is used to detect when the component is resized and needs a complete update of all slices.
	updateChart	This internal slot method manages the creation, positioning, and updating of all slice views. It is invoked automatically when slices need to be loaded or reloaded.
	InvalidateValues	This method forces the chart component to reload the data for one or more slices. It accepts two parameters specifying the range of slices to reload.
	Outline	This Outline view serves as the container for all slice views. The Outline manages the slices and provides potential scrolling capabilities.
	UpdateLayout	This method is invoked automatically after the size of the component has changed. It detects size changes and triggers a complete reload of all slices.
	UpdateViewState	This method is invoked automatically after the state of the component has changed. In case of the Pie Chart, this method can be used to update the chart's appearance based on state changes (enabled, focused, etc.).

The Pie Chart component manages slices dynamically at runtime. Unlike static views that are defined at design time, the slices are created, positioned, and removed automatically as needed. This dynamic behavior is controlled by the above mentioned slot method updateChart and the method InvalidateValues.

The update workflow follows these steps:

The following code snippet from the updateChart method demonstrates the core update logic:

The shape of each slice is calculated using vector path operations. The algorithm creates either pie slices or donut rings depending on the Width property. Parameters affecting slice shape:

Parameter	Description
Value	The normalized value (0.0 to 1.0) determining what proportion of the circle the slice occupies. Multiplied by 360° to get the slice angle.
StartAngle	The rotation angle for the entire chart, added to the calculated start position of each slice.
Radius	The outer radius of the slices. If 0, automatically calculated from component bounds.
Width	The width of rings for donut display. If 0, displays traditional pie slices.
Displacement	The offset to move slices away from center, scaled by slice size for uniform gaps.
Accumulated sum	The sum of all previous slice values, used to calculate where the current slice starts.

For each slice, the following calculations are performed:

Vector shapes created in Embedded Wizard are internally composed of straight line segments (so-called edges). The more edges used for a curve, the more smooth will it appear. On the other hand, the more edges used, the more CPU intensive will be the rendering of the shape. The implementation of the Pie Chart estimates the number of edges for each arc based on the arc length:

The slice shape is constructed using Graphics::Path operations:

Furthermore, for each view, its Bounds property is set to cover the entire Outline area, and its Offset property is set to the center of that area, establishing the coordinate system origin at the chart's center:

The InvalidateValues method allows marking specific slice ranges for reload:

This mechanism is particularly useful when animating individual slices or updating data. For example, in the Example component, only slice #2 is invalidated when the animation effect changes its value:

Originally, if not yet modified, the Pie Chart displays slices as simple filled path views with solid colors arranged within an Outline view. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. It's up to you to adapt the widget to have the expected appearance. The available possibilities are explained in the following sections. Please note, that you can combine the different approaches according to your application case:

The Outline view defines the area where slices are displayed. You can adjust its size, position, and layout behavior:

In its default implementation, the Pie Chart uses FillPath views to display slices. You can modify the updateChart method to use other view types instead, such as:

To replace the view type, follow these steps:

Following figure demonstrates the effect of the above modification. The slices appear now outlined and not filled:

The default shape calculation creates circular slices or rings with slices arranged consecutively without gaps. You can modify this behavior in the updateChart method to implement custom layouts. Instead of slices being arranged directly adjacent to each other, you can introduce angular gaps (e.g., 5 degrees) between each slice. This creates a visually separated appearance while keeping all slices at the same radius. To implement angular gaps, modify the angle calculation in the updateChart slot method:

The following figure demonstrates the effect of this modification. Please note the gaps between the slices:

Another example demonstrating the possibilities to modify the Pie Chart shape calculation could be to create elliptical slices instead of circular ones. To achieve that you modify the scaling of the coordinate system. For example, to squash the Pie Chart to 70% of its original height invoke path.Scale( 1.0, 0.7 ) immediately after initializing the coordinate system:

The following figure demonstrates the effect of this modification. Please note the gaps between the slices:

You can enhance the Pie Chart by adding decorative views such as backgrounds, labels, legends, or center decorations:

You can display labels for each slice by creating text views dynamically alongside the slice views. This requires managing pairs of views (one for the slice shape, one for the label) in the updateChart method.

The approach involves:

This approach is explained in detail in Extend the data loading mechanism.

The initial size of the Pie Chart is determined by the thick blue border surrounding the Canvas area. It corresponds to the size that all instances of this Pie Chart component will have by default. If desired, you can adjust the Canvas area and change this default size accordingly. For this purpose you click and drag the edges of the surrounding border (see also Resize the Canvas area). Once the size is changed, you can then adapt (move, resize) the views existing within the component, particularly the Outline view. For example, to make the Pie Chart taller you adjust its bottom edge:

The resulting size of the Pie Chart, however, is not necessarily fixed. It can be adjusted for each component instance individually when the instance is arranged within a superior GUI component or it can change dynamically at the runtime. The GUI application can thus contain multiple instances of the Pie Chart, each with another size. From this arises the question, how the Pie Chart will react to its size alternation?

In case of the Outline view existing per default in the Pie Chart template, the view is automatically adjusted to fill the area of the widget. All other views you have eventually added later to the Pie Chart are not adjusted automatically.

To control the adjustment you have to explicitly configure for each view its Layout property. (see also Configure component layout). Let's assume, in order to display a background decoration you have added a Rectangle view to the Pie Chart. Then you have arranged the view within the Canvas area according to your design expectation. If you want now that the view grows and shrinks according to size changes of the Pie Chart, you enable in the property Layout of this view following settings:

Now the Pie Chart knows how to react to its size changes. Each widget instance can have individual size and the enclosed views are automatically arranged within the available area.

When the Pie Chart component is resized, the UpdateLayout method is invoked automatically. This method detects the size change and triggers a complete reload of all slices by calling InvalidateValues. This ensures that the slices are resized and repositioned correctly to fill the new available space:

If you add views that should update their position or size when the chart is resized, you can extend the UpdateLayout method with your own calculations as alternative approach to configuring the view's property Layout. For example, to position a caption text at the top center of the chart:

The automatic radius calculation (when Radius property is 0) takes the new component size into account, ensuring that slices always fit within the available bounds even when displaced.

When creating your own Pie Chart component you should ensure that instances of the widget can be configured to control all the features implemented in it. For example, if you have enhanced the component to display some caption text or a legend, you should allow this text to be specified individually for each instance. In this way several Pie Chart instances can exist at the same time, each displaying another caption or having different visual characteristics.

To control the features in your component you use properties. A property can be understood as variable where the corresponding setting is stored, e.g. the caption text to display in the Pie Chart or whether a legend should be visible. When the value of the property changes, the component can react to it and update its appearance accordingly. The properties reflect thus the settings within your widget. Together they form the interface of the component.

Usually, each particular setting within a component is represented by the corresponding property. Thus, a Pie Chart where caption and legend visibility can be configured will require two properties: one for the caption text and one for the legend visibility flag. In its original version, the Pie Chart contains already six properties NoOfValues, Displacement, StartAngle, Width, Radius and OnLoadValue. These allow the component instance to configure the number of slices, their appearance, and the data source. In order to enhance this interface by your own properties, following steps are necessary:

Another example: if you have added a property to control whether a center decoration should be visible:

That is all. Now when you deal with instances of the Pie Chart component, you can evaluate and modify the properties similarly to how you access variables. Especially, when an instance is selected, you see in Inspector window the property and can change it there. The modification is immediately visible in the Composer window:

If desired, the properties can also be modified at the runtime of your application. The caption, for example, can be adapted to provide useful information for the user concerning the displayed data. For this purpose you access and modify the affected property directly within Chora code:

In its original implementation, the Pie Chart loads only two attributes for each slice: the Value (determining the slice's size) and the Color. These attributes are stored in the corresponding variables and are set by the external OnLoadValue slot method during the data loading process. If your application requires more sophisticated slice representations, you can extend this mechanism by adding additional variables to store extra attributes.

Common scenarios for extending the data loading mechanism include:

The following steps demonstrate how to add a new attribute to be loaded for each slice. As an example, we will add support for displaying text labels on each slice:

If your slices consist of multiple views (e.g., a filled path for the slice itself and a text view for the label), you need to manage both view types in the updateChart method. The recommended approach is to arrange the views in pairs: FillPath1, Text1, FillPath2, Text2, FillPath3, Text3, and so on.

This approach requires modifying the loop to search for views of a common base type (Core::View or Core::RectView), then checking each view's actual type. Since each slice manages two views, you need to call FindNextView twice per iteration.

Here's the general pattern for managing paired views:

The following figures show the result of this adaptation assuming the OnLoadValue slot method provides for each slice the corresponding label text:

If you want to add outlines around filled slices, you can manage three views per slice: a FillPath for the fill, a StrokePath for the outline, and optionally a Text view for labels. The approach is similar to the paired views pattern, but with three views per iteration instead of two.

The key is to ensure that both the FillPath and StrokePath views use the same Graphics::Path object, so they render the same shape:

When you update the path data for the slice shape, both views will automatically use the updated path, ensuring the outline perfectly matches the filled area.