Skip to Content

Base Widget Documentation

Last modified by Microchip on 2025/02/18 13:53

Introduction

This document describes the properties common to all widgets. These properties can be set using the the Microchip Graphics Suite (MGS) Harmony Composer Object Editor as shown in the "Microchip Graphics Suite (MGS) Harmony Composer User Guide" tutorial . 

This document also includes Application Program Interfaces (APIs) that are applicable to all widgets. For APIs that are unique to a specific widget, kindly consult the specific widget's page.

Properties in MGS Harmony Composer

Windget Properties

Figure 1: Widget Properties

Back to Top

List of Properties

This section describes the expected behavior of each property performed by the graphics library at runtime. The properties listed in the table are available for all widgets. Other widget-specific properties are explained in the corresponding widget section.

NameName of the widget. The content of this property impacts the generated code. The generated widget will be named <ScreenName>_<WidgetName>.
PositionThe X,Y position in pixels of the widget in parent space. The parent can be a layer or another widget.
SizeThe width, and height in pixels of the widget. The size describes the rectangle space limit that the widget is permitted to render in. It also describes the touch input detection area.
EnabledToggles the enable state of the widget. The enable state is not used by the graphics library. The state's API is accessible by application code.
VisibleToggles the visibility state of the widget. The visibility state determines whether the widget is rendered or not by the graphics library. The visibility status of a parent widget is inherited by any child widget also irrespective of the visibility setting of the child.
SchemeAssociates a scheme to the widget. The color of the scheme is applied to the widget. Colors from the scheme are only applied if no images are used for the widget. To see which colors are used and how it is applied to the widget, click on the ? to bring up the visual scheme helper window. If left empty, the generated code will associate a default system scheme to the widget.
BackgroundAt the None setting, the graphics will not paint the background of the widget. At the Filled setting, the graphics library will paint the background with the color determined by the scheme associated with the widget. To see which color in the scheme is used for the background color by the widget, click on the ? button beside the Scheme property to bring up the visual scheme helper window. The effect of the setting is previewed within the Graphics Composer.
BorderThis property instructs the graphics library on what type of border to procedurally render. The border will occupy around the rectangular space as determined by the Size property. At the None setting, no border is drawn. The effect of the setting is previewed within the Graphics Composer.
AlignmentThis property sets the horizontal and vertical alignment of the widget within the size allocated for it. The effect of the setting is previewed within the Graphics Composer.
MarginsThis property adds spacing between the widget boundary and the element in the widget. For example, if the widget is a label, a margin is placed between the boundary of the label widget and the string. If the Alignment property is middle, then the margin will not have any effect. The effects of the setting are previewed within the Graphics Composer.
Alpha BlendingSelecting this check box sets an alpha value entered in the Alpha Level property to the widget.
Alpha LevelIf the Alpha Blending check box is selected, the widget is set with an alpha value specified in this property.
LockedThis editor option prevents the user from selecting the widget in the screen preview window though it can still be selected from the tree view to change its property.
HiddenThis editor option has an effect only in the preview window but not on the actual state of visibility of the widget when it is drawn on the target. Please note that the Visible property controls the visibility of the widget on the target.

Back to Top

Code Generation

Once a widget is designed and its properties are set using the MGS Harmony Composer, the MPLAB Code Configurator (MCC), which is tightly coupled with the MPLAB X IDE, generates code for it. In the section below, the common API framework for widgets is described. Please note that you can also create and set widget properties directly using the API framework.

To learn more about the workflow of application development with MGS Harmony Composer, MCC, and MPLAB X IDE, please refer to the tutorial "Designing an Application with Microchip Graphics Suite (MGS)".

Back to Top

Widget APIs Description

This section describes the APIs common to all widgets. 

getType()

leWidgetType getType(const leWidgetWidget* _this)
  • Gets the widget type
  • Returns Widget type

setPosition() setX() setY()

leResult setPosition(leWidgetWidget* _this,
                    int32_t x,
                    int32_t y);
  • Sets the widget x and y position

Parameters

leWidgetWidget*_thisWidget to operate on
int32xThe new X position
int32yThe new y position
  • Returns LE_SUCCESS or LE_FAILURE

Note: You can also set the position of the widget using setX() and setY().

leResult setX(leWidgetWidget* _this,
             int32_t x)

leResult setY(leWidgetWidget* _this,
            int32_t y)

getX() getY()

int32_t getX(const leWidgetWidget* _this)
int32_t getY(const leWidgetWidget* _this)
  • Gets the widget's x and y position on the screen with reference to (0,0) origin
  • Returns int32 x and y value of the widget

setSize() setWidth() setHeight()

leResult setSize(leWidgetWidget* _this,
                uint32_t w,
                uint32_t h)
  • Sets the widget size

Parameters

leWidgetWidget*_thisWidget to operate on
int32wThe width value
int32hThe height value
  • Returns LE_SUCCESS or LE_FAILURE

Note: You can also set the size of the widget using setWidth() and setHeight().

leResult setWidth(leWidgetWidget* _this,
                 uint32_t w)
leResult setHeight(leWidgetWidget* _this,
                 uint32_t h)

getWidth() getHeight()

uint32_t getWidth(const leWidgetWidget* _this)
uint32_t getHeight(const leWidgetWidget* _this)
  • Gets the widget's width and height pixel position
  • Returns width and height value of the widget

resize()

leResult resize(leWidgetWidget* _this, int32_t w, int32_t h)                  
  • Resizes the widget

Parameters

leWidgetWidget*_thisWidget to operate on
int32wThe width value
int32hThe height value
  • Returns LE_SUCCESS or LE_FAILURE

translate()

leResult translate(leWidgetWidget* _this, int32_t x, int32_t y)
                       
  • Translates (shifts) the widget by x pixels in the X direction and y pixels in the Y direction

Parameters

leWidgetWidget*_thisWidget to operate on
int32xx value
int32yy value
  • Returns LE_SUCCESS or LE_FAILURE

setEnabled()

leResult setEnabled(leWidgetWidget* _this,
                    leBool enbl)
  • Sets the enable flag of the widget

Parameters

leWidgetWidget*_thisWidget to operate on
leBoolenblLE_FALSE or LE_TRUE
  • Returns LE_SUCCESS or LE_FAILURE

getEnabled()

  leBool getEnabled(const leWidgetWidget* _this)
  • Gets the widget's enabled flag
  • Returns LE_FALSE or LE_TRUE

setVisible()

leResult setVisible(leWidgetWidget* _this,
                    leBool vis)
  • Sets the visibility flag of the widget

Parameters

leWidgetWidget*_thisWidget to operate on
leBoolvisLE_FALSE or LE_TRUE
  • Returns LE_SUCCESS or LE_FAILURE

getVisible()

leBool getVisible(const leWidgetWidget* _this)
  • Gets the visibility flag of the widget
  • Returns LE_FALSE or LE_TRUE

setScheme()

leResult setScheme(const leWidgetWidget* _this,
                   leScheme* schm)
  • Sets the widget's scheme

Parameters

leWidgetWidget*_thisWidget to operate on
leScheme*schmThe scheme pointer
  • Returns LE_SUCCESS or LE_FAILURE

rectToParent()

leRect rectToParent(const leWidgetWidget* _this)
  • Gets the widget's bounding rectangle in parent space
  • Returns the bounding rectangle

rectToScreen()

void rectToScreen(const leWidgetWidget* _this, leRect* res)
  • Gets the widget's bounding rectangle in screen space

Parameters

leWidgetWidget*_thisWidget to operate on
leRect*resThe resultant rectangle
  • Returns None

getScheme()

leScheme* getScheme(const leWidgetWidget* _this)
  • Gets the widget's scheme
  • Returns scheme pointer

setBackgroundType()

leResult setBackgroundType(leWidgetWidget* _this,
                           leBackgroundType type)
  • Sets this widget's background type

Parameters

leWidgetWidget*_thisWidget to operate on
leBackgroundTypetype

The background type:

LE_WIDGET_BACKGROUND_NONE

LE_WIDGET_BACKGROUND_FILL

  • Returns LE_SUCCESS or LE_FAILURE

getBackgroundType()

leBackgroundType getBackgroundType(const leWidgetWidget* _this)
  • Gets this widget's background type
  • Returns LE_WIDGET_BACKGROUND_NONE or LE_WIDGET_BACKGROUND_FILL

setBorderType()

leResult setBorderType(leWidgetWidget* _this,
                       leBorderType type)
  • Sets this widget's border type

Parameters

leWidgetWidget*_thisWidget to operate on
leBorderTypetype

The border type:

LE_WIDGET_BORDER_NONE

LE_WIDGET_BORDER_LINE

LE_WIDGET_BORDER_BEVEL

  • Returns LE_SUCCESS or LE_FAILURE

getBorderType()

  leBorderType getBorderType(const leWidgetWidget* _this)
  • Gets this widget's border type
  • Returns LE_WIDGET_BORDER_NONE or LE_WIDGET_BORDER_LINE or LE_WIDGET_BORDER_BEVEL

setHAlignment()

leResult setHAlignment(leWidgetWidget* _this,
                       leHAlignment halgn)
  • Sets this widget's horizontal alignment

Parameters

leWidgetWidget*_thisWidget to operate on
leHAlignmenthalgn

The horizontal alignment:

LE_HALIGN_LEFT

LE_HALIGN_CENTER

LE_HALIGN_RIGHT

  • Returns LE_SUCCESS or LE_FAILURE

getHAlignment()

leHAlignment getHAlignment(const leWidgetWidget* _this)
  • Gets this widget's horizontal alignment setting
  • Returns LE_HALIGN_LEFT or LE_HALIGN_CENTER or LE_HALIGN_RIGHT

setVAlignment()

leResult setVAlignment(leWidgetWidget* _this,
                       leVAlignment valgn)
  • Sets this widget's vertical alignment

Parameters

leWidgetWidget*_thisWidget to operate on
leVAlignmentvalgn

The vertical alignment:

LE_VALIGN_TOP

LE_VALIGN_MIDDLE

LE_VALIGN_BOTTOM

  • Returns LE_SUCCESS or LE_FAILURE

getVAlignment()

  leVAlignment getVAlignment(const leWidgetWidget* _this)
  • Gets this widget's vertical alignment setting
  • Returns LE_VALIGN_TOP or LE_VALIGN_MIDDLE or LE_VALIGN_BOTTOM

setMargins()

leResult setMargins(leWidgetWidget* _this,
                   uint32_t l,
                   uint32_t t,
                   uint32_t r,
                   uint32_t b)
  • Sets the spacing between the widget boundary (as specified by the widget size) and the element in the widget

Parameters

leWidgetWidget*_thisWidget to operate on
int32lThe left margin value
int32tThe top margin value
int32rThe right margin value
int32bThe bottom margin value
  • Returns LE_SUCCESS or LE_FAILURE

getMargins()

  leMargin getMargins(const leWidgetWidget* _this)
  • Gets this widget's margins
  • Returns leMargin structure containing margin values

setAlphaEnabled()

leResult setAlphaEnabled(leWidgetWidget* _this,
                         leBool enbl)
  • Sets the widget's alpha flag enable state

Parameter

leWidgetWidget*_thisWidget to operate on
leBoolenbl

LE_FALSE or LE_TRUE

  • Returns LE_SUCCESS or LE_FAILURE

getAlphaEnabled()

  • Gets the widget alpha enabled flag
  • Returns LE_FALSE or LE_TRUE

setAlphaAmount()

  leResult setAlphaAmount(leWidgetWidget* _this, uint32_t a)
  • Sets this widget's alpha amount

Parameter

leWidgetWidget*_thisWidget to operate on
int32a

The alpha amount

  • Returns LE_SUCCESS or LE_FAILURE

getAlphaAmount()

uint32_t getAlphaAmount(const leWidgetWidget* _this)
  • Gets the widget alpha blending value
  • Returns alpha amount

addChild()

leResult addChild(leWidgetWidget* _this,
                  leWidget* chld)
  • Adds a child widget to the widget

Parameter

leWidgetWidget*_thisWidget to operate on
leWidget*chld

The child widget

  • Returns LE_SUCCESS or LE_FAILURE

insertChild()

leResult insertChild(leWidgetWidget* _this,
         leWidget* chld,
        uint32_t idx)
  • Adds child to widget at given index

Parameter

leWidgetWidget*_thisWidget to operate on
leWidget*chld

The child widget

int32idxIndex to insert at
  • Returns LE_SUCCESS or LE_FAILURE

removeChild()

leResult removeChild(leWidgetWidget* _this,
                     leWidget* chld)
  • Removes a child widget from this widget

Parameter

leWidgetWidget*_thisWidget to operate on
leWidget*chld

The child widget

  • Returns LE_SUCCESS or LE_FAILURE

removeChildAt()

  leResult removeChildAt(leWidgetWidget* _this, uint32_t idx)
  • Removes child from widget at given index

Parameter

leWidgetWidget*_thisWidget to operate on
int32idxIndex to insert at
  • Returns LE_SUCCESS or LE_FAILURE

removeAllChildren()

void removeAllChildren(leWidgetWidget* _this)
  • Removes all children from this widget

Parameter

leWidgetWidget*_thisWidget to operate on
  • Returns None

setChildIndex()

void setChildIndex(leWidgetWidget* _this,
                   leWidget* child,
                  uint32_t idx)
  • Sets a child's index

Parameter

leWidgetWidget*_thisWidget to operate on
leWidget*chld

The child widget

int32idxThe new index for the child
  • Returns None

getChildCount()

uint32_t getChildCount(const leWidgetWidget* _this)
  • Gets the number of children this widget owns

Parameter

leWidgetWidget*_thisWidget to operate on
  • Returns number of children

getChildAtIndex()

leWidget* getChildAtIndex(const leWidgetWidget* _this,
                         uint32_t idx)
  • Gets a widget child at a given index

Parameter

leWidgetWidget*_thisWidget to operate on
int32idxIndex
  • Returns the child widget

getIndexofChild()

uint32_t getIndexOfChild(const leWidgetWidget* _this,
                        const leWidget* chld)
  • Get the index of a given child widget

Parameter

leWidgetWidget*_thisWidget to operate on
leWidget*chld

The child widget

  • Returns index

invalidate()

void invalidate(const leWidgetWidget* _this)
  • Invalidates the widget so that it will redraw itself

Parameter

leWidgetWidget*_thisWidget to operate on
  • Returns None

installEventFilter()

leResult installEventFilter(leWidgetWidget* _this,
                            leWidgetEventFilter fltr)
  • Installs a widget event filter

Parameter

leWidgetWidget*_thisWidget to operate on
leWidgetEventFilter fltr

callback pointer

  • Returns LE_SUCCESS or LE_FAILURE

removeEventFilter()

eResult removeEventFilter(leWidgetWidget* _this,
                          leWidgetEventFilter fltr)
  • Removes a widget event filter

Parameter

leWidgetWidget*_thisWidget to operate on
leWidgetEventFilter fltr

callback pointer

  • Returns LE_SUCCESS or LE_FAILURE

Back to Top