Base Widget Documentation
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
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.
| Name | Name of the widget. The content of this property impacts the generated code. The generated widget will be named <ScreenName>_<WidgetName>. |
| Position | The X,Y position in pixels of the widget in parent space. The parent can be a layer or another widget. |
| Size | The 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. |
| Enabled | Toggles 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. |
| Visible | Toggles 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. |
| Scheme | Associates 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. |
| Background | At 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. |
| Border | This 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. |
| Alignment | This 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. |
| Margins | This 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 Blending | Selecting this check box sets an alpha value entered in the Alpha Level property to the widget. |
| Alpha Level | If the Alpha Blending check box is selected, the widget is set with an alpha value specified in this property. |
| Locked | This 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. |
| Hidden | This 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. |
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)".
Widget APIs Description
This section describes the APIs common to all widgets.
getType()
Gets the widget type.
Returns Widget type.
setPosition() setX() setY()
int32_t x,
int32_t y);
Sets the widget x and y position.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| int32 | x | The new X position |
| int32 | y | The new y position |
Returns LE_SUCCESS or LE_FAILURE.
int32_t x)
leResult setY(leWidgetWidget* _this,
int32_t y)
getX() getY()
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()
uint32_t w,
uint32_t h)
Sets the widget size.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| int32 | w | The width value |
| int32 | h | The height value |
Returns LE_SUCCESS or LE_FAILURE.
uint32_t w)
leResult setHeight(leWidgetWidget* _this,
uint32_t h)
getWidth() getHeight()
uint32_t getHeight(const leWidgetWidget* _this)
Gets the widget's width and height pixel position.
Returns width and height value of the widget.
resize()
Resizes the widget.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| int32 | w | The width value |
| int32 | h | The height value |
Returns LE_SUCCESS or LE_FAILURE.
translate()
Translates (shifts) the widget by x pixels in the X direction and y pixels in the Y direction.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| int32 | x | x value |
| int32 | y | y value |
Returns LE_SUCCESS or LE_FAILURE.
setEnabled()
leBool enbl)
Sets the enable flag of the widget.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leBool | enbl | LE_FALSE or LE_TRUE |
Returns LE_SUCCESS or LE_FAILURE.
getEnabled()
Gets the widget's enabled flag.
Returns LE_FALSE or LE_TRUE.
setVisible()
leBool vis)
Sets the visibility flag of the widget.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leBool | vis | LE_FALSE or LE_TRUE |
Returns LE_SUCCESS or LE_FAILURE.
getVisible()
Gets the visibility flag of the widget.
Returns LE_FALSE or LE_TRUE.
setScheme()
leScheme* schm)
Sets the widget's scheme.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leScheme* | schm | The scheme pointer |
Returns LE_SUCCESS or LE_FAILURE.
rectToParent()
Gets the widget's bounding rectangle in parent space.
Returns the bounding rectangle.
rectToScreen()
Gets the widget's bounding rectangle in screen space.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leRect* | res | The resultant rectangle |
Returns None.
getScheme()
Gets the widget's scheme.
Returns scheme pointer.
setBackgroundType()
leBackgroundType type)
Sets this widget's background type.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leBackgroundType | type | The background type: LE_WIDGET_BACKGROUND_NONE LE_WIDGET_BACKGROUND_FILL |
Returns LE_SUCCESS or LE_FAILURE.
getBackgroundType()
Gets this widget's background type.
Returns LE_WIDGET_BACKGROUND_NONE or LE_WIDGET_BACKGROUND_FILL.
setBorderType()
leBorderType type)
Sets this widget's border type.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leBorderType | type | The border type: LE_WIDGET_BORDER_NONE LE_WIDGET_BORDER_LINE LE_WIDGET_BORDER_BEVEL |
Returns LE_SUCCESS or LE_FAILURE.
getBorderType()
Gets this widget's border type.
Returns LE_WIDGET_BORDER_NONE or LE_WIDGET_BORDER_LINE or LE_WIDGET_BORDER_BEVEL.
setHAlignment()
leHAlignment halgn)
Sets this widget's horizontal alignment.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leHAlignment | halgn | The horizontal alignment: LE_HALIGN_LEFT LE_HALIGN_CENTER LE_HALIGN_RIGHT |
Returns LE_SUCCESS or LE_FAILURE.
getHAlignment()
Gets this widget's horizontal alignment setting.
Returns LE_HALIGN_LEFT or LE_HALIGN_CENTER or LE_HALIGN_RIGHT.
setVAlignment()
leVAlignment valgn)
Sets this widget's vertical alignment.
Parameters
| leWidgetWidget* | _this | Widget to operate on |
| leVAlignment | valgn | The vertical alignment: LE_VALIGN_TOP LE_VALIGN_MIDDLE LE_VALIGN_BOTTOM |
Returns LE_SUCCESS or LE_FAILURE.
getVAlignment()
Gets this widget's vertical alignment setting.
Returns LE_VALIGN_TOP or LE_VALIGN_MIDDLE or LE_VALIGN_BOTTOM.
setMargins()
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* | _this | Widget to operate on |
| int32 | l | The left margin value |
| int32 | t | The top margin value |
| int32 | r | The right margin value |
| int32 | b | The bottom margin value |
Returns LE_SUCCESS or LE_FAILURE.
getMargins()
Gets this widget's margins.
Returns leMargin structure containing margin values.
setAlphaEnabled()
leBool enbl)
Sets the widget's alpha flag enable state.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leBool | enbl | 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()
Sets this widget's alpha amount.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| int32 | a | The alpha amount |
Returns LE_SUCCESS or LE_FAILURE.
getAlphaAmount()
Gets the widget alpha blending value.
Returns alpha amount.
addChild()
leWidget* chld)
Adds a child widget to the widget.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidget* | chld | The child widget |
Returns LE_SUCCESS or LE_FAILURE.
insertChild()
leWidget* chld,
uint32_t idx)
Adds child to widget at given index.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidget* | chld | The child widget |
| int32 | idx | Index to insert at |
Returns LE_SUCCESS or LE_FAILURE.
removeChild()
leWidget* chld)
Removes a child widget from this widget.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidget* | chld | The child widget |
Returns LE_SUCCESS or LE_FAILURE.
removeChildAt()
Removes child from widget at given index.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| int32 | idx | Index to insert at |
Returns LE_SUCCESS or LE_FAILURE.
removeAllChildren()
Removes all children from this widget.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
Returns None.
setChildIndex()
leWidget* child,
uint32_t idx)
Sets a child's index.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidget* | chld | The child widget |
| int32 | idx | The new index for the child |
Returns None.
getChildCount()
Gets the number of children this widget owns.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
Returns number of children.
getChildAtIndex()
uint32_t idx)
Gets a widget child at a given index.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| int32 | idx | Index |
Returns the child widget.
getIndexofChild()
const leWidget* chld)
Get the index of a given child widget.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidget* | chld | The child widget |
Returns index.
invalidate()
Invalidates the widget so that it will redraw itself.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
Returns None.
installEventFilter()
leWidgetEventFilter fltr)
Installs a widget event filter.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidgetEventFilter | fltr | callback pointer |
Returns LE_SUCCESS or LE_FAILURE.
removeEventFilter()
leWidgetEventFilter fltr)
Removes a widget event filter.
Parameter
| leWidgetWidget* | _this | Widget to operate on |
| leWidgetEventFilter | fltr | callback pointer |
Returns LE_SUCCESS or LE_FAILURE.