app module

Note

The app package is experimental. Functionality and interface are still in flux and subject to change.

class libavg.app.App

Bases: object

This class handles global application affairs. Among these are setting up a root node along with window size (and possibly screen resolution) and screen rotation, and creating an environment for the user’s MainDiv. Global user interface items such as a debug panel and keyboard manager are also set up. Additionally, App handles configuration settings and command line argument support.

App usually does not need to be subclassed. Instead, subclass MainDiv and pass an instance of the derived class to run().

debugPanel

An instance of debugpanel.DebugPanel.

mainDiv

The instance passed as first argument of the run() method.

overlayPanel

DivNode that stands always on top of the MainDiv.

settings

An instance of settings.Settings.

dumpTextObjectCount()

Dumps on the console the current number of initialized objects. Normally bound to the keypress CTRL-b.

onBeforeLaunch()

Called just before starting the main loop (Player.play()). Useful only for subclassing. The display hasn’t been initialized at this point.

run(mainDiv, **kargs)

Starts the application using the provided mainDiv (an instance of MainDiv).

The optional additional kargs are used to set default settings - see settings.Settings.

takeScreenshot(targetFolder='.')

Takes a screenshot of what is currently visible on the screen. Normally bound to the keypress CTRL-p. Screenshots are saved to the disk under the name ‘App-nnn.png’, where nnn is a sequence number.

class libavg.app.MainDiv(**kargs)

Bases: libavg.avg.DivNode

This abstract class must be subclassed to write a libavg application. It is the main application entry point and should be the parent node for all application-created nodes. All the public methods are empty and don’t do anything if not overridden.

VERSION

A version string. This is shown using the -v or --version command-line option.

onArgvParsed(options, args, parser)

This method is called after command-line arguments have been parsed and should be used to retrieve any application-specific options. The arguments options and args are the result of calling options, args = parser.parse_args(), where parser is an instance of optparse.OptionParser configured by calling onArgvParserCreated().

onArgvParserCreated(parser)

Called with an empty optparse.OptionParser instance. Allows the application to add additional command line options. App adds it’s own parameters as well. If this is overridden, onArgvParsed() should probably be overridden as well.

onExit()

Called after the main loop exits. Release resources and run cleanups here.

Note

onExit() doesn’t get called if an exception is raised on the main thread.

onFrame()

Called every frame.

onInit()

Called by a libavg timer as soon as the main loop starts. At this point in time, the window has been created and all render functions are available. Build the application node tree here.

onStartup()

Called before libavg has been setup, just after the App().run() call. The window has not been created at this time.

keyboardmanager Module

This module makes it possible to attach event handlers to individual keypresses. Keys that are bound through the keyboard manager are also be shown in the debug panel via the keyboard bindings widget along with their help string. libavg.app.App defines a range of keyboard bindings by default. The keyboardmanager is usually set up by libavg.app.App. libavg.app.App also reserves all keys modified by CTRL.

For all the binding methods, keystring can be a python string or a unicode object. Plain strings are matched to libavg.avg.KeyEvent.keystring, while unicode objects are matched to libavg.avg.KeyEvent.unicode. The modifiers are described under libavg.avg.KeyEvent.modifiers, with the additional modifiers KEYMOD_SHIFT, KEYMOD_CTRL and KEYMOD_ALT available to simplify checking for left and right modifier keys at one time.

libavg.app.keyboardmanager.bindKeyDown(keystring, handler, help, modifiers=avg.KEYMOD_NONE)

Sets up a key handler so that handler is called whenever keystring is pressed.

libavg.app.keyboardmanager.bindKeyUp(keystring, handler, help, modifiers=avg.KEYMOD_NONE)

Sets up a key handler so that handler is called whenever keystring is released.

libavg.app.keyboardmanager.disable()

Companion to enable(), disables all handlers.

libavg.app.keyboardmanager.enable()

Companion to disable(), enables all handlers.

libavg.app.keyboardmanager.getCurrentBindings()

Returns the currently assigned bindings as a list of named tuples.

libavg.app.keyboardmanager.init()

Called by App. Should not be called by user programs.

libavg.app.keyboardmanager.pop()

Companion to push(), restores the non-modified key bindings previously pushed onto the stack via push().

libavg.app.keyboardmanager.push()

Pushes all the non-modified key bindings onto a stack and clears them all. Useful when the application flow branches to a state where a different key bindings set is needed. The bindings can be then restored with pop().

libavg.app.keyboardmanager.unbindAll()

Removes all the defined key bindings at once.

libavg.app.keyboardmanager.unbindKeyDown(keystring, modifiers=avg.KEYMOD_NONE)

Removes a previously defined key binding for a KEY_DOWN event.

libavg.app.keyboardmanager.unbindKeyDown(keystring, modifiers=avg.KEYMOD_NONE)

Removes a previously defined key binding for a KEY_UP event.

flashmessage Module

Simple user notification API to report information to the user

class libavg.app.flashmessage.FlashMessage(text, timeout=DEFAULT_TIMEOUT, parent=None, isError=False, acknowledge=False)

Bases: object

A FlashMessage is an easy way to show debug notification and similar text in the libavg window. The message can have an optional timeout or stay visible until clicked on by the user. It inserts itself into node tree at the top. Multiple FlashMessage instances are shown in the order they get created.

Parameters:

• timeout – The time in milliseconds the message should persist on screen before it gets removed. Only valid if acknowledge is False.
• parent – When specified, the parent node the message should be appending itself to.
• isError – A boolean flag to mark the message as error. Error-flagged messages are shown in a different color and are routed to the logger as well.
• acknowledge – A flag to indicate whether the message should remove itself automatically (after timeout has elapsed) or needs to be acknowledged by the user (by clicking / touching on it).