m-shell.net

Module abguibase

m GUI base classes and basic functions implementing the architectural essentials.

The m GUI framework offers the following functionality:

An extensible hierarchy of widgets.
Predefined widgets like abgui.Label, abgui.Button, abgui.Table, etc.
Automatic columnwise or manual layout of widgets in instances of abguibase.Box
Configurable default colors, backgrounds and dimensions via the theme property array.
Support for transparent widgets via Widget.alpha.
Support for multiple asynchronous inputs via addStream().
Regular heartbeat callbacks via setIdleTick().
Delayed callbacks (e.g. for animations) via addDelayedCall().

This module and its accompanying modules abgui, abfilegui can serve as a standard framework for graphical m applications. If set up properly, the abguibase.run event loop will serialize user input, external events or input, and call the corresponding handlers, thus providing a common callback-driven application framework.

A simple example showing an image, a table and three radio buttons:

use abgui, abguibase, ui, graph

// build the UI
view:abguibase.Box=abguibase.Box();
view.add(abgui.Image("tests\\mShell.png"));
table:abgui.Table=abgui.Table([
  ["Strawberry",1.5,false],
  ["Vanilla",1.3,true],
], ["Flavour", "Price", "Ok"]);
view.add(table);
row:abguibase.Box=abguibase.Box(3); // three horizontal buttons
view.add(row);
group:abgui.RadioButton=abgui.RadioButton("Now");
row.add(group);
row.add(abgui.RadioButton("Later", group));
row.add(abgui.RadioButton("Never", group));
// show the view
abguibase.setRoot(view);
// setup the menu
ui.menu("GuiSample", ["Buy", "Exit"]);
do
  cmd=abguibase.run();
  case cmd
  in "Buy": // do something
  end
until cmd=null or cmd="Exit"

Classes

Background	The base class drawing a widget background.
Box	A box capable of holding child widgets.
ImageBackground	An image background drawing an image with optional border.
RoundedBackground	A somewhat fancier background with rounded corners.
Widget	The base class of all widgets.

Variables

debugDraw Set to true to debug drawing, i.e. wait for a keystroke before drawing each widget.

theme

The "theme" property array. The base array defines the following properties:

Key	Meaning
`fg`	foreground color
`bg`	default Background
`fieldbg`	Background for text fields
`buttonbg`	Background for buttons
`clickedbg`	Background for clicked buttons
`tablebg`	Background for tables
`progresscolor`	color for progress bar
`selcolor`	background color for selected items
`inset`	inset of content in widgets
`cellinset`	inset of content in cells
`bordercolor`	cell border color

Functions

addDelayedCall(delay, f)	Add a function which will be called once after some (minimal) delay.
addStream(s, handler)	Add an input stream to check for input, and its handler.
clearIdleTick()	Clear the handler to be called repeatedly after a minimal delay.
exit()	Exit from the event loop.
getFocus():abguibase.Widget	Get the widget which currently has the focus.
moveFocus(backwards)	Move the focus forward or backwards.
removeStream(s)	Remove an input stream checked for input, and the handler which was added with it.
requestEvents()	Setup the UI module such that the standard ui.cmd() events are requested, on which focusable widgets rely.
run()	Run the event handling loop.
setIdleTick(delay, handler)	Set a handler to be called regularly after a minimal delay, whenever the event loop is idle.
setRoot(root:abguibase.Widget):abguibase.Widget	Set the root of the widget hierarchy to show.
update()	Update the UI, i.e. perform all necessary redraws.

function moveFocus(backwards)

Move the focus forward or backwards.

function setRoot(root:abguibase.Widget):abguibase.Widget

Set the root of the widget hierarchy to show.
Parameters:
root – the new root widget, or null to not show any widgets.
Returns:the old root.

function getFocus():abguibase.Widget

Get the widget which currently has the focus.
Returns:the focused widget, null if there is no focused widget.

function addStream(s, handler)

Add an input stream to check for input, and its handler. Whenever input becomes available on the stream, handler(s) will be called.
Parameters:
s – the stream to add.
handler – the input handler, an (instance) function reference.

function removeStream(s)

Remove an input stream checked for input, and the handler which was added with it.
Parameters:
s – the stream to remove.

function addDelayedCall(delay, f)

Add a function which will be called once after some (minimal) delay. This can be used to create widget animations.
Parameters:
delay – the minimal delay in milliseconds.
f – the function to call, an (instance) function reference.

function setIdleTick(delay, handler)

Set a handler to be called regularly after a minimal delay, whenever the event loop is idle.
Parameters:
delay – the minimal delay in milliseconds.
handler – the handler to call, an (instance) function reference.

function clearIdleTick()

Clear the handler to be called repeatedly after a minimal delay.

function update()

Update the UI, i.e. perform all necessary redraws.

function requestEvents()

Setup the UI module such that the standard ui.cmd() events are requested, on which focusable widgets rely. This needs only to be called to reset to the normal state after modifying the requested event types via ui.keys() or ui.ptr().

function run()

Run the event handling loop. This updates the UI, handles UI commands, idle timer ticks, and, if set, reads from streams. Returns if either exit() has been called, or a menu command has been executed.
Returns:the menu command, or null if exit() has been called.

function exit()

Exit from the event loop.