Bar Graph Widget Documentation

Introduction

Bar Graph widgets are interactive elements within a Graphical User Interface (GUI) that enables users to display specific numerical data on a touchscreen display. When implemented, Bar Graph widgets will display inputted data categories such as quarterly numbers or varying masses of objects. They play a crucial role in providing an interactive user experience as they can be integrated with other widgets on the Microchip Graphics Suite (MGS) Harmony Composer to create a customizable and specialized user experience.

This Bar Graph widget page covers the following topics:

1. Creating and customizing Bar Graph widgets using Microchip Graphics Suite (MGS) Harmony Composer
2. Bar Graph widget properties
3. Handling Bar Graph widget properties and events through application code
4. Bar Graph widget example project
5. Application Program Interfaces (APIs) specific to Bar Graph widgets

Designing Bar Graph Widget Using MGS Harmony Composer

Follow these steps to add a Bar Graph widget to your design:

Select and drag the BarGraphWidget from the Tool Box to your screen designer workspace as shown in Figure 1.

Back to Top

To customize the bar graph, select it on the screen designer and modify its properties using the Object Editor.

You can add data entries to your bar graph using the Configure Data property. Let us suppose you want to create a bar graph as shown in Figure 2:

The bar graph shown in Figure 2 has four data categories along the X -axis. For each category, there are three data series.

To configure bar graph data, click the Press button next to the Configure Data property as shown in Figure 3.

Back to Top

Then from the Configure Graph Data window as shown in Figure 4, follow these steps:

To add a new Data Category (refer Figure 2) for the X-axis, click on the + icon.

Double-click on the new label to launch the Select String window and choose a label from the list. Note that labels must be added through the String Manager prior to this step.

If you have multiple Data Series (refer Figure 2) in your bar graph, click on the + icon to add a new Data Series.

Double-click on the new Data Series and provide a unique Name for the series.

In the table highlighted in green in Figure 4, double-click on the required data and enter the desired data.

Information

Note: To learn how to set strings for the widget, please refer to the "Using Strings in Microchip Graphics Suite (MGS)" page.

To set the stacked property on the bar graph, select the option from the Object Editor as shown in Figure 5:

Back to Top

Managing Bar Graph Widget Schemes

Schemes control the look and feel of a widget.

To learn how to set the scheme for a bar graph, click on the   button next to the Scheme property editor from the Object Editor.

This launches the Bar Graph Scheme Helper window containing tips on how different sections of the scheme color table manipulate various elements of the widget.

The following is an example color scheme and the resulting bar graph appearance. Note that if your bar graph has more than one Data Series, it is helpful to assign each series with a unique color scheme to easily distinguish between them. 

The information from the button scheme helper and the example color scheme used is summarized in the following table.

Back to Top

Bar Graph Widget Properties

You can set the following properties of the bar graph using the Object Editor:

Figure 10,11,12 show the detailed information for the Bar Graph Value Axis.

Back to Top

Managing Bar Graph Widget Through Programming

Once the graphical design is completed using MGS Harmony Composer, MCC generates the required code for all the widgets based on the properties set in the Object Editor. To learn more about the process flow between designing a UI and developing application code, refer to the "Designing an Application with Microchip Graphics Suite (MGS)" page.

Let us suppose that a new Bar Graph widget is created with the following properties in MGS Harmony Composer:

For the Bar Graph widget with the properties shown in the figure above, MCC will automatically generate the following lines of code in src\config\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c

• A new Bar Graph widget is created by the variable name Screen0_BarGraphWidget_0

 Screen0_Bar GraphWidget_0 = leBar GraphWidget_New();

• Its position is set to pixel location 384x86

 Screen0_Bar GraphWidget_0 ->fn->setPosition(Screen0_BarGraphWidget_0, 384, 86);

• The Bar Graph size is set to have a width of 350 pixels and a height of 327 pixels

Screen0_Bar GraphWidget_0 ->fn->setSize(Screen0_BarGraphWidget_0, 350, 327);

• If the scheme is altered, the following code is implemented:

Screen0_Bar GraphWidget_0 ->setScheme(Screen0_BarGraphWidget_0, &Scheme);

• Sets the minimum value on the Y-axis

Screen0_Bar GraphWidget_0 ->fn->setMinValue(Screen0_BarGraphWidget_0, 0);

• Sets the maximum value on the Y-axis

Screen0_Bar GraphWidget_0 ->fn->setMaxValue(Screen0_BarGraphWidget_0, 100);

• Sets the tick interval on the Y-axis

Screen0_Bar GraphWidget_0 ->fn->setValueAxisTickInterval(Screen0_BarGraphWidget, BAR_GRAPH_AXIS_0, 10);

• Its graph area value is set to none so that the background of the bar graph isn't filled with any color

Screen0_Bar GraphWidget_0 ->fn->setFillGraphArea(Screen0_BarGraphWidget_0, LE_FALSE);

• The Bar Graph is set to have a line border. However, you could have no border or a bevel border

Screen0_Bar GraphWidget_0 ->fn->setBorderType(Screen0_BarGraphWidget_0, LE_WIDGET_BORDER_LINE);

• Finally, the Bar Graph is added to the screen

root0 ->fn->addChild(root0, (leWidget*)Screen0_BarGraphWidget_0);

Back to Top

Application Code

The default code generated by MCC sets the initial state of the widget. The property or behavior of the widgets can be changed by using the APIs discussed above, in the application code. Additional application code discussion related to the Bar Graph widget is presented below.

Here is an example of how other MGS Widgets affect Bar Graph properties (in app.c):

Back to Top

Bar Graph Widget Example Project

Refer to the Bar Graph widget example project in GitHub.

In this example, we show:

1. How to create a Bar Graph Widget 
2. How to alter the data through other widget interactions
3. How to alter the scaling of the Bar Graph Widget

Back to Top

MGS Simulator Output

The callback functions for handling the Checkbox events and Bar Graph updates are defined in the app.c file. In this example, dynamic strings were used for Bar Graph category labels.

As a best practice, changes to the widget are done in the main loop based on the variables that are changed in the timer callback, not in the callback directly.

The code that changes the Bar Graph widget can be found in the app.c file.

• Upon checking CheckBoxWidget_0 or CheckBoxWidget_1, the unit of the input data will be changed, and the bar graph will be updated accordingly.

• If both the checkboxes are unchecked, the bar graph reverts to default data.

Back to Top

Bar Graph Widget APIs Description

This section describes the APIs specific to the Bar Graph widget. For a description of APIs common to all widgets, refer to the "Widget APIs Description" section.

getTickLength()

• Gets the tick length

Parameters

• Returns the tick length value

setTickLength()

• Sets the tick length

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getMinValue()

• Gets the minimum value from the Value Axis

Parameters

• Returns the minimum value

setMinValue()

• Sets the minimum value

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getMaxValue()

• Gets the maximum value from the Value Axis

Parameters

• Returns the maximum value

setMaxValue()

• Sets the maximum value

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getValueAxisLabelsVisible()

• Gets the visible Value Axis label setting

Parameters

• Returns LE_TRUE if set, otherwise LE_FALSE

setValueAxisLabelsVisible()

• Sets the visibility of the Value Axis labels

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getValueAxisTicksVisible()

• Gets the visible value ticks setting

Parameters

• Returns the setting value

setValueAxisTicksVisible()

• Sets the visibility of the value axis ticks

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getValueAxisTickInterval()

• Gets the value axis tick interval setting

Parameters

• Returns the tick interval value

setValueAxisTickInterval()

• Sets the interval of the value axis ticks

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getValueAxisTicksPosition()

• Gets the value axis ticks position

Parameters

• Returns the value axis ticks position

setValueAxisTicksPosition()

• Sets the value axis ticks position

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getValueAxisSubticksVisible()

• Gets the visible value subtick setting

Parameters

• Returns the setting value

setValueAxisSubticksVisible()

• Sets the visibility of the value axis subticks

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getValueAxisSubtickInterval()

• Gets the value axis subtick interval setting

Parameters

• Returns the subticks interval value

setValueAxisSubtickInterval()

• Sets the inverval of the value axis subticks

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getCategoryAxisTicksVisible()

• Gets the category axis ticks visible setting

Parameters

• Returns the setting value

setCategoryAxisTicksVisible()

• Sets the category axis ticks visible setting

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getCategoryAxisTicksPosition()

• Gets the category axis ticks position

Parameters

• Returns the category axis ticks position

setCategoryAxisTicksPosition()

• Sets the category axis ticks position

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getCategoryAxisLabelsVisible()

• Gets the category axis labels visible setting

Parameters

• Returns the setting

setCategoryAxisLabelsVisible()

• Sets the category axis labels visible setting

Parameters

• Returns LE_SUCCESS or LE_FAILURE

addSeries()

• Adds a data series to the graph

Parameters

• Returns the series ID

getSeriesScheme()

• Gets the scheme for a data series

Parameters

• Returns scheme pointer

setSeriesScheme()

• Sets the data series scheme

Parameters

• Returns LE_SUCCESS or LE_FAILURE

addDataToSeries()

• Adds data to an existing series

Parameters

• Returns the ID of the new value

setDataInSeries()

• Sets a new value to an already existing data series

Parameters

• Returns LE_SUCCESS or LE_FAILURE

clearData()

Clears all graph data.

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getTicksLabelFont()

• Gets the Ticks font property

Parameters

• Returns the property

setTicksLabelFont()

• Sets the series point type setting

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getGridLinesVisible()

• Gets the visible grid lines setting

Parameters

• Returns the setting value

setGridLinesVisible()

• Sets the visibility of the grid lines

Parameters

• Returns LE_SUCCESS or LE_FAILURE

addCategory()

• Adds a data category

Parameters

• Returns the category ID

getCategoryString()

• Gets the string currently assigned to a category

Parameters

• Returns string pointer

setCategoryString()

• Sets the category axis ticks visible setting

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getStacked()

• Gets the stacked setting

Parameters

• Returns the setting value

setStacked()

• Sets the stacked status

Parameters

• Returns LE_SUCCESS or LE_FAILURE

getFillGraphArea()

• Gets the graph fill setting

Parameters

Returns the setting value.

setFillGraphArea()

• Sets the graph fill setting

Parameters

• Returns LE_SUCCESS or LE_FAILURE

Back to Top