With this template you can add a new Bar Chart component to your project. Bar Chart is a component intended to display bar diagrams. 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 Bar 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 Bar Chart wherever you need in your GUI project. Because it serves as template, it is intentionally kept very simple. Nevertheless, Bar 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 Bar 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 Bar Chart from scratch you can use the available template. The second function is more educative. The template implements fully working Bar 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 Bar 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 Bar Chart component.

To create a new Bar 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 Bar Chart component from a template:

In order to demonstrate the usage of the Bar 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 bar 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 Bar 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 Bar Chart component, you can use it to assemble more complex components. Technically seen, you embed an instance of the Bar 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 Bar Chart component:

As long as the Bar 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 Bar 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 Bar 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 Bar Chart are only few following properties:

Property	Description
BarSize	The property BarSize stores the width (or the height in case of the chart being rotated by 90° or 270°) of a single bar expressed in pixel.
NoOfValues	The property NoOfValues stores how many bars 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 bar. The slot method receives no parameters. Instead, within the slot method implementation you access the Index variable to identify which bar is being loaded, and set the Value and Color variables to specify the bar's data. When the referred property is modified by other widget or the application logic, the Bar Chart is automatically notified to remain in sync with the property.
Orientation	The property Orientation determines whether the chart should be displayed with normal or rotated orientation.

Once added to the component, you can freely move the Bar 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 Bar Chart to appear behind other views you can reorder it explicitly.

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

The width (or height, depending on the orientation) of each individual bar is controlled by the property BarSize expressed in pixel units. For example:

The bars are arranged automatically within the chart area with equal spacing and are distributed evenly across the available space. The following left figure demonstrates a Bar Chart configured with NoOfValues set 11 and BarSize being 25 pixel. Please note, when the available space is not sufficient for all bars with the specified size, the bars will overlap as demonstrated in the right figure:

Ideally (and of course depending on your application case) you would configure the Bart Chart so that its width corresponds to the number of bars multiplied by the size of a bar. In this manner, the bars are displayed without gaps between them. You can calculate the width of the bar dynamically when the number of bars changes:

The Bar Chart loads data dynamically at runtime through a callback mechanism. To provide the data (value and color) for each bar, 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 bar.

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

Variable	Description
Index	This variable identifies which bar is being loaded. The first bar has index 0, the second bar 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 height (or width) of the bar. The value ranges from 0.0 to 1.0, where 0.0 means an empty bar and 1.0 means a bar that fills the entire chart height (or width for rotated orientations).
Color	This variable should be set by your slot method to specify the color of the bar.

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 Bar 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 bars to reload:

After calling InvalidateValues, the Bar Chart will automatically invoke your OnLoadValue slot method for each affected bar to reload its data. This mechanism allows you to efficiently update only the bars that have changed, without needing to refresh the entire chart.

The Bar Chart can display bars in four different orientations controlled by the property Orientation. This property accepts values from the enumeration Views::Orientation:

Orientation	Description
Views::Orientation.Normal	Bars grow upward from the bottom edge of the chart. The BarSize property determines the width of each bar.
Views::Orientation.Rotated_90	Bars grow leftward from the right edge of the chart. The BarSize property determines the height of each bar.
Views::Orientation.Rotated_180	Bars grow downward from the top edge of the chart. The BarSize property determines the width of each bar.
Views::Orientation.Rotated_270	Bars grow rightward from the left edge of the chart. The BarSize property determines the height of each bar.

You can configure the orientation in the Inspector window or programmatically:

The following figure demonstrates the four different orientations:

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 Bar 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 Bar Chart appears with an empty canvas area. The bars 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 bars are displayed as Filled Rectangle views, each positioned and colored according to the data provided through the OnLoadValue callback mechanism.

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

Icon	Member	Description
	NoOfValues	The property NoOfValues stores how many bars 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 bars.
	BarSize	The property BarSize stores the width (or height for rotated orientations) of a single bar expressed in pixels.
	OnSetBarSize	The onset method belongs to the property BarSize. Each time the value of the property is changed, the code implemented in the method is executed to request an update of all bars.
	Orientation	The property Orientation determines whether the chart should be displayed with normal or rotated orientation.
	OnSetOrientation	The onset method belongs to the property Orientation. Each time the value of the property is changed, the code implemented in the method is executed to reload all bar data with the new orientation.
	OnLoadValue	The property OnLoadValue can refer to any slot method that should be invoked to load the data for a bar. When the Bar Chart needs to load data, it will invoke this slot method.
	Index	This variable identifies the bar which is about to be loaded by the external slot method OnLoadValue. The external slot method should read this variable to determine which bar's data to provide.
	Value	This variable is intended to receive the value for the currently loaded bar. The external slot method OnLoadValue should set this variable. The value ranges from 0.0 to 1.0 corresponding to the bar's height or width.
	Color	This variable is intended to receive the color for the currently loaded bar. The external slot method OnLoadValue should set this variable.
	invalidFirstValue	This internal variable stores the index of the first bar which needs an update. Used internally by the update logic.
	invalidLastValue	This internal variable stores the index of the last bar 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 bars.
	updateChart	This internal slot method manages the creation, positioning, and updating of all bar views. It is invoked automatically when bars need to be loaded or reloaded.
	InvalidateValues	This method forces the chart component to reload the data for one or more bars. It accepts two parameters specifying the range of bars to reload.
	Outline	This Outline view serves as the container for all bar views. The Outline manages the bars.
	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 bars.
	UpdateViewState	This method is invoked automatically after the state of the component has changed. In case of the Bar Chart, this method can be used to update the chart's appearance based on state changes (enabled, focused, etc.).

The Bar Chart component manages bars dynamically at runtime. Unlike static views that are defined at design time, the bars 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 position of each bar is calculated based on several factors:

Factor	Description
Orientation	Determines whether bars grow upward, downward, leftward, or rightward.
BarSize	The width (for vertical bars) or height (for horizontal bars) of each bar.
Value	The normalized value (0.0 to 1.0) determining the bar's length.
Available space	The bounds of the Outline view, reduced by BarSize to ensure bars are fully visible.
Bar index	The position of the bar in the sequence, used to calculate spacing between bars.

For example, with Views::Orientation.Normal orientation (bars growing upward from bottom):

The InvalidateValues method allows efficient updates of specific bar ranges without reloading all bars:

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

Originally, if not yet modified, the Bar Chart displays bars as simple colored rectangles 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 bars are displayed. You can adjust its size, position, and layout behavior:

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

To replace the view type, follow these steps:

The default positioning algorithm distributes bars evenly across the available space. You can modify this behavior in the updateChart method to implement custom layouts. For example, instead of even distribution, you can use fixed pixel spacing:

Or you can implement grouping by adding extra spacing at certain indices:

You can enhance the Bar Chart by adding decorative views such as backgrounds, grid lines, axis labels, or legends:

For example, to add a background grid:

The initial size of the Bar Chart is determined by the thick blue border surrounding the Canvas area. It corresponds to the size that all instances of this Bar 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 Bar Chart taller you adjust its bottom edge:

The resulting size of the Bar 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 Bar Chart, each with another size. From this arises the question, how the Bar Chart will react to its size alternation?

In case of the Outline view existing per default in the Bar Chart template, the view is automatically adjusted to fill the area of the widget. All other views you have eventually added later to the Bar 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 Bar 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 Bar Chart, you enable in the property Layout of this view following settings:

Now the Bar 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 Bar Chart component is resized, the UpdateLayout method is invoked automatically. This method detects the size change and triggers a complete reload of all bars by calling InvalidateValues. This ensures that the bars are 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 text label at the bottom center of the chart:

When creating your own Bar 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 Bar 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 Bar Chart or whether a grid 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 Bar Chart where caption and grid visibility can be configured will require two properties: one for the caption text and one for the grid visibility flag. In its original version, the Bar Chart contains already four properties NoOfValues, BarSize, Orientation and OnLoadValue. These allow the component instance to configure the number and size of bars, their orientation, 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 the visibility of a background grid:

That is all. Now when you deal with instances of the Bar 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 Bar Chart loads only two attributes for each bar: the Value (determining the bar's height or width) 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 bar 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 bar. As an example, we will add support for gradients in the displayed bars. In this manner each bar can be configured with two colors, color at the upper and another color at the bottom edge of the bar:

If you want each bar to display a different bitmap (useful when using Wallpaper or Bitmap Frame views), add a variable of type Resources::Bitmap:

If your bars consist of multiple views (e.g., a rectangle for the bar itself and a text view for the label), you need to manage both view types in the updateChart method. The simplest approach is arrange the views pairwise (e.g. Rectangle1, Text1, Rectangle2, Text2, Rectangle3, Text3, ...). This approach requires the loop to be modified to search for views of the common type (Core::View or Core::RectView if all your views are rectangle-based), and then check each view's actual type. Since each bar manages two views, you need to call FindNextView twice per iteration.

Here's the general pattern for managing pairwise views:

The following figures show the result of this adaptation assuming the OnLoadValue slot method provides for each value the corresponding string, e.g. "0.5":

When your Bar Chart needs to display a large number of bars that exceeds the available screen space, the recommended approach is to embed the entire Bar Chart component within an Outline view. This allows users to scroll through all the chart content interactively.

When implemented this way:

You can enhance the scrolling behavior by configuring the Slide Touch Handler:

For detailed information about the Outline view and its scrolling capabilities, please refer to the Outline documentation.