The microGraphics Framework (mgf) module is used to create a Graphical User Interface (GUI) and supports input via touchscreen and buttons.
A User Interface is created by displaying one or more Widgets and assigning ActionListeners to respond to input from users. This document discusses the following topics:
Creating a Widget
Widgets are created by calling the appropriate create function of the mgf module.
|Widget||mgf.createWidget()||Generic widget, can be used to design custom widgets. All other widgets are derived from Widget.|
|Button||mgf.createButton( label[, font] )||Enables user-actions via touchscreen or physical buttons.|
|Label||mgf.createLabel( label[, font] )||Single line text field.|
|TextArea||mgf.createTextArea( text[, font] )||Multi-line text field.|
|Slider||mgf.createSlider( minimum, maximum )||Slider to enter or display a numeric value.|
|Switch||mgf.createSwitch( [font] )||On/Off switch.|
|ItemView||mgf.createItemView()||Displays a list of Items|
|Item||mgf.createItem( label, description )||Single entry in an ItemView|
|Image||mgf.createImage( filename [, x, y ] )||Displays a TGA image stored on the SD-Card|
|Panel||mgf.createPanel()||Collection of sub-widgets.|
|Dialog||mgf.createDialog( widget, title [, mode] )||Dialog style Panel with title, border, and buttons.|
|ListEditor||mgf.createListEditor()||Allows picking a value from a list of values.|
|NumberEditor||mgf.createNumberEditor()||Allows entering a numeric value.|
Displaying a Widget
The microGraphics Framework allows to display only a single Widget on the screen. Complex user interfaces can however be created by using the Panel widget to group several child-widgets together.
The Widget being displayed is changed by calling thesetWidget function:
By default the widget is displayed as full screen. Optionally the location on the display and size of the widget can be defined:
The x value corresponds to the horizontal position of the widget and the y value to the vertical position of the widget (relative to the display orientation).
Position [0,0] is at the top left of the display, with x increasing to the right and y increasing to the bottom.
Auto size and position
When using the value 0xFFFF for x or y position, the widget will be centered in respectively the horizontal or vertical axis of the display.
When using the value 0xFFFF for width or height, the widget will displayed as full width or full height of the display.
The value 0xFFFF can be used for one, more, or all parameters.
The orientation of the display can be changed by calling mgf.setRotation. Possible value are:
Default, portrait orientation
|90||Display rotated 90 degrees clockwise|
|270||Display rotated 90 degrees counter-clockwise|
The width and height of the display can be queried by calling the mgf.getSize function. The first return value is the width, the second the height of the display. This function takes the current display rotation into account.
Interacting with a widget using action listeners
Some widgets like labels are usually only used to display information. Other widgets like buttons are intended to receive input from users. The microGraphics Framework uses ActionListeners to receive information from user interactions. An action listener is a user-defined function that will be called when the user interacts with the widget. All widgets support setting an action listener, but not all widgets actually implement calling the action listener (e.g. a Label will never call its action listener).
An action listener is assigned by setting the actionListener field of a widget:
When an action listener is called by the microGraphics Framework, the following parameters are provided:
|widget||The Widget that calls this action listener.|
|action||The type of action (numeric value). The possible values for the action field depend on the type of Widget.|
Using the widget parameter, you can find out which widget called the action listener when you have multiple widgets sharing a single action listener function.
Most widgets have only a single action in which case the action parameter can be ignored. Some widgets like a Dialog however have two actions, namely mgf.ActionDialogOK and mgf.ActionDialogCancel.
Redrawing a widget
When properties of a widget are changed (e.g. the content of a Label is changed), you need to explicitly tell mgf to redraw the GUI. This is done by calling mgf.repaint() which schedules a GUI repaint. For more explanation about threads in the Lua framework, see Lua Threading.
When mgf redraws the GUI, it does not redraw every widget that is displayed. Instead, widgets have a dirty property that indicates whether or not it should be redrawn. Standard widgets mark themselves as dirty when necessary (e.g. when updating the value of a Slider). A Widget can be explicitly marked as dirty by calling Widget:setDirty().
The setDirty is generally only used in the paint function of a custom widget. Prior to calling the paint function, the widget is marked as not-dirty automatically.
The microGraphics Framework supports different fonts to draw text.
It is currently not possible to define user fonts in the Lua development framework. You can change the font of a Widget by setting the font field.
Changing the Look and Feel of a Widget
The Look and Feel of each Widget can be individually changed by assigning a (color) Theme and by settings the Font used when drawing the Widget (if applicable).
A Theme is created by calling createTheme function of the mgf module.
The Theme can then be modified to change the colors of a Widget. A Theme supports changing the following colors:
|Field||Value of default Theme||Description|
|foreground||COLOR_WHITE||Defines the foreground color.|
|background||COLOR_BLACK||Defines the background color.|
|border||0x00404040||Defines the border color.|
|selection||0x000088CC||Defines the color used for selected items.|
|fontonforeground||COLOR_BLACK||Defines the color of text displayed on top of the foreground.|
|fontonbackground||COLOR_WHITE||Defines the color of text displayed on top of the background.|
Changing Theme colors
A color is a 24-bit RGB value, formatted as a numeric value in the format: 0x00RRGGBB
Using predefined colors
For convenience the graphics module defines the following colors:
Assigning a Theme to a Widget
Each Widget can have its own individual Theme assigned by setting the theme field of a Widget:
A single Theme can be assigned to multiple Widgets, there is no need to create a Theme for each Widget if they share the same color scheme.
Changing the default Theme
By default a black & white color theme is used. To avoid changing the theme of all individual widgets, you can create a theme and set is as default.