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

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

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

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

Property	Description
FillColor	The property FillColor stores the color to fill the area behind the line segments. Set to transparent color to disable the fill.
LineColor	The property LineColor stores the color to draw the line segments connecting the data points.
LineWidth	The property LineWidth stores the width of the drawn line segments expressed in pixel units.
NoOfValues	The property NoOfValues stores how many data points 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 point. The slot method receives no parameters. Instead, within the slot method implementation you access the Index variable to identify which point is being loaded, and set the Value, Color and Frame variables to specify the point's data.
Orientation	The property Orientation determines whether the chart should be displayed with normal or rotated orientation.
PointBitmap	The property PointBitmap stores the bitmap resource used to display all data points. If the bitmap contains multiple frames, individual frames can be selected for each point by setting the Frame variable in the OnLoadValue slot method. If the bitmap is an alpha-only bitmap, each point can be colorized individually by setting the Color variable.

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

The Line Chart is intended to display multiple data points connected by line segments. The number of points is determined by the widget's property NoOfValues. By evaluating this property you can query how many points are currently displayed in the affected widget. When you modify the property NoOfValues, the Line Chart will automatically update to show the correct number of points and connecting line segments. For example:

The appearance of the line segments and filled area is controlled by several properties:

Property	Description
LineColor	Specifies the color of the line segments connecting the points.
LineWidth	Specifies the width of the line segments in pixel units (minimum value is 1).
FillColor	Specifies the color to fill the area behind the line segments. Set to transparent #00000000 to disable filling.
PointBitmap	Specifies the bitmap resource used to display all data points. Can be a multi-frame bitmap or alpha-only bitmap for colorization.

For example, to configure the chart's visual appearance:

The points are arranged automatically within the chart area with equal spacing and are distributed evenly across the available space. The following figures demonstrate different Line Chart configurations:

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

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

Variable	Description
Index	This variable identifies which point is being loaded. The first point has index 0, the second point 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 vertical (or horizontal for rotated orientations) position of the point. The value ranges from 0.0 to 1.0, where 0.0 means the bottom edge (or left edge for rotated orientations) and 1.0 means the top edge (or right edge).
Color	This variable should be set by your slot method to specify the color of the point. This is particularly useful when using alpha-only bitmaps for PointBitmap, allowing each point to be colorized individually.
Frame	This variable should be set by your slot method to specify which frame from the PointBitmap should be displayed for this point. This is useful when using multi-frame bitmaps to show different icons for different data points.

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 Line 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 points to reload:

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

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

Orientation	Description
Views::Orientation.Normal	Points are arranged horizontally from left to right. The Value determines the vertical position (0.0 at bottom, 1.0 at top).
Views::Orientation.Rotated_90	Points are arranged vertically from top to bottom. The Value determines the horizontal position (0.0 at right, 1.0 at left).
Views::Orientation.Rotated_180	Points are arranged horizontally from right to left. The Value determines the vertical position (0.0 at top, 1.0 at bottom).
Views::Orientation.Rotated_270	Points are arranged vertically from bottom to top. The Value determines the horizontal position (0.0 at left, 1.0 at right).

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 Line 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 Line Chart appears with an empty canvas area. The line segments and data points are created dynamically at runtime using path-based views and image views. Our intention is to keep the component templates as minimalistic as possible so they don't distract you with less important design details. The line segments are displayed using Views::StrokePath view, the filled area is displayed using Views::FillPath view, and the data points are displayed as Views::Image views, each configured and positioned according to the data provided through the OnLoadValue callback mechanism.

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

Icon	Member	Description
	NoOfValues	The property NoOfValues stores how many data points 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 adjust the internal path data structures and schedule an update of all points.
	PointBitmap	The property PointBitmap stores the bitmap resource used to display all data points.
	OnSetPointBitmap	The onset method belongs to the property PointBitmap. Each time the value of the property is changed, the code implemented in the method is executed to request an update of all points.
	LineColor	The property LineColor stores the color to draw the line segments connecting the data points.
	OnSetLineColor	The onset method belongs to the property LineColor. Each time the value of the property is changed, the code implemented in the method is executed to update the StrokePath view's color.
	LineWidth	The property LineWidth stores the width of the drawn line segments expressed in pixels.
	OnSetLineWidth	The onset method belongs to the property LineWidth. Each time the value of the property is changed, the code implemented in the method is executed to update the StrokePath view's width.
	FillColor	The property FillColor stores the color to fill the area behind the line segments.
	OnSetFillColor	The onset method belongs to the property FillColor. Each time the value of the property is changed, the code implemented in the method is executed to update the FillPath view's color and visibility.
	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 point 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 point. When the Line Chart needs to load data, it will invoke this slot method.
	Index	This variable identifies the point which is about to be loaded by the external slot method OnLoadValue. The external slot method should read this variable to determine which point's data to provide.
	Value	This variable is intended to receive the value for the currently loaded point. The external slot method OnLoadValue should set this variable. The value ranges from 0.0 to 1.0 corresponding to the point's vertical or horizontal position.
	Color	This variable is intended to receive the color for the currently loaded point. The external slot method OnLoadValue should set this variable. The value determines the color of the image frame shown at point's position.
	Frame	This variable is intended to receive the frame number from the PointBitmap for the currently loaded point. The external slot method OnLoadValue should set this variable.
	invalidFirstValue	This internal variable stores the index of the first point which needs an update. Used internally by the update logic.
	invalidLastValue	This internal variable stores the index of the last point 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 points.
	updateChart	This internal slot method manages the creation, positioning, and updating of all point views and the path data for line segments. It is invoked automatically when points need to be loaded or reloaded.
	InvalidateValues	This method forces the chart component to reload the data for one or more points. It accepts two parameters specifying the range of points to reload.
	strokePathData	This Graphics::Path object stores the coordinates for the line segments connecting the points. The object is used by the StrokePath view.
	fillPathData	This Graphics::Path object stores the coordinates for the filled area behind the line segments. The object is used by the FillPath view.
	StrokePath	This Views::StrokePath view displays the line segments connecting the data points using the coordinates from strokePathData.
	FillPath	This Views::FillPath view displays the filled area behind the line segments using the coordinates from fillPathData.
	Outline	This Outline view serves as the container for all point image views. The Outline manages the points.
	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 points.
	UpdateViewState	This method is invoked automatically after the state of the component has changed. In case of the Line Chart, this method can be used to update the chart's appearance based on state changes (enabled, focused, etc.).

The Line Chart component manages data points and line segments dynamically at runtime. Unlike static views that are defined at design time, the points are created, positioned, and removed automatically as needed, and the line segments are calculated and updated in path data structures. 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 point is calculated based on several factors:

Factor	Description
Orientation	Determines the arrangement direction and which axis the Value affects.
PointBitmap	The size of the bitmap determines how much space each point occupies and affects the available drawing area.
Value	The normalized value (0.0 to 1.0) determining the point's position along the value axis.
Available space	The bounds of the Outline view, reduced by the point bitmap size to ensure points are fully visible.
Point index	The position of the point in the sequence, used to calculate spacing along the data axis.

For example, with Views::Orientation.Normal orientation (left to right arrangement, bottom to top values):

The Line Chart uses two Graphics::Path objects to store the coordinates of the line segments:

Path Object	Description
strokePathData	Contains the coordinates for the line segments connecting the data points. Used by the StrokePath view to draw the lines.
fillPathData	Contains a closed shape created from strokePathData plus additional edges to close the area. Used by the FillPath view to fill the area behind the line segments.

The strokePathData is built incrementally during the point processing loop by calling SetNode for each point. After all points are processed, the fillPathData is created by copying the stroke path and adding closing edges:

The InvalidateValues method allows efficient updates of specific point ranges without reloading all points:

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

Originally, if not yet modified, the Line Chart displays points as simple bitmap images connected by line segments, with an optional filled area behind the line. 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 chart component contains three main views that determine its visual appearance:

View	Description
Outline	Defines the area where data points are displayed. Points are managed as children of this view.
StrokePath	Displays the line segments connecting the data points. You can adjust its color (LineColor property) and width (LineWidth property).
FillPath	Displays the filled area behind the line segments. You can adjust its color (FillColor property) or hide it by setting color to transparent.

You can adjust these views' size, position, and layout behavior:

In its default implementation, the Line Chart uses Image views to display data points. 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 points evenly across the available space along one axis, while positioning them according to their Value along the perpendicular axis. 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 non-linear scaling for the value axis:

Beyond the basic LineColor and LineWidth properties, you can enhance the StrokePath view with additional styling:

For example, to create rounded line segments:

Instead of solid colors for the line segments and filled area, you can use gradient fills by configuring the corner color properties of the StrokePath and FillPath views. Both views provide four color properties that determine the color at each corner of the view's bounds:

Property	Description
ColorTL	Color at the top-left corner of the view.
ColorTR	Color at the top-right corner of the view.
ColorBL	Color at the bottom-left corner of the view.
ColorBR	Color at the bottom-right corner of the view.

By setting these properties to different colors, you create a four-point gradient that interpolates smoothly between the corner colors. For example, to add a vertical gradient fill to the area behind the line segments, you could adapt the OnSetFillColor method as shown below. This method assigns the specified color value to the top edge of the FillPath view while the bottom edge is configured with black color:

In its original version, the FillPath view is pre-configured with a common transparent color in its property Color. Modifying the individual corner properties will thus has no effect since the resulting color is derived from both values, the common Color and individual (e.g. ColorTL) properties. You will need to correct it:

Similarly, you could modify the Line Chart to display the line segments with a horizontal gradient. To achieve that adapt the OnSetLineColor method as shown below. This method assigns the specified color value to the right edge of the StrokePath view while the left edge is configured with transparent version of the assigned color. In this manner the line segments are faded-in from the left to the right:

The StrokePath is similarly to the FillPath view pre-configured with a common color, here black opaque in its property Color. Modifying the individual corner properties will thus has no effect since the resulting color is derived from both values, the common Color and the individual (e.g. ColorTL) properties. You will need to correct it:

The following figures show the Line Charts after the above modifications. On the left the filled area appears with a vertical gradient. On the right, the lines appear with a horizontal gradient:

You can enhance the Line 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 Line Chart is determined by the thick blue border surrounding the Canvas area. It corresponds to the size that all instances of this Line 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, StrokePath, and FillPath views. For example, to make the Line Chart taller you adjust its bottom edge:

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

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

Now the Line 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 Line Chart component is resized, the UpdateLayout method is invoked automatically. This method detects the size change and triggers a complete reload of all points by calling InvalidateValues. This ensures that the points and line segments 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 Line 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 Line 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 Line 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 Line 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 Line Chart contains already six properties NoOfValues, PointBitmap, LineColor, LineWidth, FillColor, Orientation and OnLoadValue. These allow the component instance to configure the number of points, their appearance, line styling, filled area color, 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 Line 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 Line Chart loads three attributes for each data point: the Value (determining the point's position), the Frame (for selecting a bitmap frame), and Color (for colorizing the frame bitmap). 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 point 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 point. As an example, we will add support for individual text labels displayed next to each point:

If you want each point to display a completely different bitmap (not just different frames from the same multi-frame bitmap), add a variable of type Resources::Bitmap:

If your points consist of multiple views (e.g., an image for the point marker and a text view for the label), you need to manage both view types in the updateChart method. The simplest approach is to arrange the views pairwise (e.g. Image1, Text1, Image2, Text2, Image3, 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 point 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 point the corresponding label text:

When your Line Chart needs to display a large number of points that exceeds the available screen space, the recommended approach is to embed the entire Line 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.