Skip to end of metadata
Go to start of metadata

What?

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.

TypeConstructorDescription
Widgetmgf.createWidget()Generic widget, can be used to design custom widgets. All other widgets are derived from Widget.
Buttonmgf.createButton( label[, font] )Enables user-actions via touchscreen or physical buttons.
Labelmgf.createLabel( label[, font] )Single line text field.
TextAreamgf.createTextArea( text[, font] )Multi-line text field.
Slidermgf.createSlider( minimum, maximum )Slider to enter or display a numeric value.
Switchmgf.createSwitch( [font] )On/Off switch.
ItemViewmgf.createItemView()Displays a list of Items
Itemmgf.createItem( label, description )Single entry in an ItemView
Imagemgf.createImage( filename [, x, y ] )Displays a TGA image stored on the SD-Card
Panelmgf.createPanel()Collection of sub-widgets.
Dialogmgf.createDialog( widget, title [, mode] )Dialog style Panel with title, border, and buttons.
ListEditormgf.createListEditor()Allows picking a value from a list of values.
NumberEditormgf.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:

Displaying a widget
mgf.setWidget( someWidget )

By default the widget is displayed as full screen. Optionally the location on the display and size of the widget can be defined:

Displaying a widget with location and size
-- Display widget at location x = 10, y = 50, width = 100 and height = 25
mgf.setWidget( someWidget, 10, 50, 100, 25 )

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.

Display Orientation

The orientation of the display can be changed by calling mgf.setRotation. Possible value are:

ValueImageDescription
0 

Default, portrait orientation

90 Display rotated 90 degrees clockwise
180 Display upside-down
270 Display rotated 90 degrees counter-clockwise
Change display rotation
-- Turn the display upside-down
mgf.setRotation( 180 )

Display Size

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.

Getting the display size
width, height = mgf.getSize()

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:

function listener()
  print( "Pressed" )
end

button = mgf.createButton( "Press me" )
button.actionListener = listener

ActionListener data

When an action listener is called by the microGraphics Framework, the following parameters are provided:

ParameterDescription
widgetThe Widget that calls this action listener.
actionThe 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.

function listener( widget )
  label.label = "Pressed button " .. widget.label
  mgf.repaint()
end

button_first  = mgf.createButton( "First" )
button_first.actionListener = listener
button_second = mgf.createButton( "Second" )
button_second.actionListener = listener

label = mgf.createLabel( "" )

panel = mgf.createPanel()

panel:addWidget( button_first, 10, 10, 100, 30 )
panel:addWidget( button_second, 130, 10, 100, 30 )
panel:addWidget( label, 0, 50, 240, 25 )

mgf.setWidget( panel )

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.

function listener( widget, action )
  if( action == mgf.ActionDialogOK ) then
    -- Actions for OK
  else
    -- Actions for Cancel
  end
end  

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.

Calling mgf.repaint()
function listener()
  slider.value = slider.value + 1
  -- Need to call repaint to force a redraw of the GUI.
  mgf.repaint()
end

Dirty widgets

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().

Mark a Widget as dirty
function listener()
  -- Force a redraw of label as example, even though this makes no sense.
  label:setDirty()
  mgf.repaint()
end

label = mgf.createLabel( "Test Label" )
button = mgf.createButton( "Redraw" )
button.actionListener = listener

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.

Fonts

The microGraphics Framework supports different fonts to draw text.

FontFont Size
mgf.FontSmall11
mgf.FontMedium20
mgf.FontBig48

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 font of a widget
button = mgf.createButton( "SmallText" )
button.font = mgf.FontSmall

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.

Create a Theme
theme = mgf.createTheme()

The Theme can then be modified to change the colors of a Widget. A Theme supports changing the following colors:

FieldValue of default ThemeDescription
foregroundCOLOR_WHITEDefines the foreground color.
backgroundCOLOR_BLACKDefines the background color.
border0x00404040Defines the border color.
selection0x000088CCDefines the color used for selected items.
fontonforegroundCOLOR_BLACKDefines the color of text displayed on top of the foreground.
fontonbackgroundCOLOR_WHITEDefines 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

Assigning a color
-- Create a Theme
theme = mgf.createTheme()

-- Set foreground color to ( r = 128, g = 0, b = 255 )
theme.foreground = 0x008000FF

Using predefined colors

For convenience the graphics module defines the following colors:

IDValue
graphics.COLOR_BLACK0x00000000
graphics.COLOR_RED0x00FF0000
graphics.COLOR_GREEN0x0000FF00
graphics.COLOR_BLUE0x000000FF
graphics.COLOR_WHITE0x00FFFFFF
graphics.COLOR_YELLOW0x00FFFF00
graphics.COLOR_CYAN

0x0000FFFF

graphics.COLOR_PURPLE0x00FF00FF
Using a predefined color
-- Create a Theme
theme = mgf.createTheme()

-- Set background color to purple
theme.background = graphics.COLOR_PURPLE

Assigning a Theme to a Widget

Each Widget can have its own individual Theme assigned by setting the theme field of a Widget:

Assigning a Theme to a Widget
label = mgf.createLabel( "Hello World!" )

theme = mgf.createTheme()
theme.fontonbackground = graphics.COLOR_YELLOW

label.theme = theme

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.

theme = mgf.createTheme()
theme.fontonbackground = graphics.COLOR_YELLOW

label1 = mgf.createLabel( "Hello World!" )
label2 = mgf.createLabel( "From Screvle." )

label1.theme = theme
label2.theme = theme

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.

Setting the default theme
theme = mgf.createTheme()

-- Modify the theme

-- Assign the theme as default
mgf.setDefaultTheme( theme )
  • No labels