Line Widget Documentation

Introduction

A Line Widget is a graphical user interface component used to draw straight lines on the screen.

It's a straightforward and effective way to add visual elements such as dividers, borders, or indicators to the interface. The start and end points of the line can be precisely defined using coordinates, allowing for flexible placement within the Graphical User Interface (GUI). This widget is non-interactive and serves purely as a visual aid to enhance the layout and organization of the interface.

This page covers the following topics:

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

Designing Line Widget Using MGS Harmony Composer

Follow these steps to add a Line Widget to your design:

Select and drag the LineWidget to your screen designer workspace as shown in Figure 1.

To customize the LineWidget, select the widget from the Screen Tree and modify its properties using the Object Editor.

Back to Top

Managing Line Widget Schemes

Schemes control the look and feel of a widget.

To learn how to set the scheme for an image, click on the question mark  button next to the Scheme property editor of the Object Editor.

This will launch the Line Scheme Helper window containing tips on how different sections of the scheme settings manipulate various elements of the line.

The following is an example color scheme and the resulting appearance of the LineWidget:

The information provided by the Line Widget Scheme Helper and the example color scheme is summarized in Figure 6.

Back to Top

Line Widget Properties

You can set the following properties of the Line Widget using the Object Editor:

Name        This will be used to reference the LineWidget by the application. Example-

                  Screen0_LineWidget_0

Line           (P1X, P1Y) and (P2X, P2Y) specify the start and end positions in pixels of the line within the widget. 

Back to Top

Managing Line 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 line widget is created with the following properties in MGS Harmony Composer:

For the Line Widget with the properties shown in Figure 7, MCC will automatically generate the following lines of code in src\confg\default\gfx\legato\generated\screen\le_gen_screen_Screen0.c:

• A new Line Widget is created by the variable name Screen0_LineWidget_0

Screen0_LineWidget_0 = leLineWidget_New();

• Its position is set to pixel location 186x67.

Screen0_LineWidget_0->fn->setPosition(Screen0_LineWidget_0, 186, 67);

• The Line Widget size is set to have a width of 100 and a height of 98.

Screen0_LineWidget_0->fn->setSize(Screen0_LineWidget_0, 100, 98);

• The required scheme for the Line Widget is selected.

Screen0_LineWidget_0->fn->setScheme(Screen0_LineWidget_0, &LineScheme);

• The start point position of the Line within the Widget is set.

Screen0_LineWidget_0->fn->setStartPoint(Screen0_LineWidget_0, 0, 50);

• The endpoint position of the Line within the Widget is also selected.

Screen0_LineWidget_0->fn->setEndPoint(Screen0_LineWidget_0, 100, 50);

• Finally, the Line Widget is added to the screen.

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

Back to Top

Line Widget Example Project

Refer to the Line Widget Example Project in GitHub

In this example, we show:

1. How to create a Line Widget,
2. How to change the color of a line on a button press, by selecting a different color scheme
3. How to rotate the line, by changing the line start and end position

Back to Top

MGS Harmony Web Simulator Output

The callback function for handling the button release event is defined in the app.c file.

Back to Top

Line Widget APIs Description

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

getStartPoint()

• Gets the start point (x1,y1) of the line
• Returns LE_SUCCESS or LE_FAILURE

Parameters

setStartPoint()

• Sets the start point (x1,y1) of the line
• Returns LE_SUCCESS or LE_FAILURE

Parameters

getEndPoint()

• Gets the endpoint (x2,y2) of the line
• Returns LE_SUCCESS or LE_FAILURE

Parameters

setEndPoint()

• Sets the endpoint (x2,y2) of the line
• Returns LE_SUCCESS or LE_FAILURE

Parameters

Back to Top