diff options
Diffstat (limited to 'sphinxdoc/app.rst')
| -rw-r--r-- | sphinxdoc/app.rst | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/sphinxdoc/app.rst b/sphinxdoc/app.rst new file mode 100644 index 0000000..2fe03d1 --- /dev/null +++ b/sphinxdoc/app.rst @@ -0,0 +1,217 @@ +app module +========== + +.. automodule:: libavg.app + + .. note:: + + The app package is experimental. Functionality and interface are still in flux and + subject to change. + + .. autoclass:: App + + 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 :py:class:`MainDiv`. + Global user interface items such as a debug panel and keyboard manager are also + set up. Additionally, :py:class:`App` handles configuration settings and command + line argument support. + + :py:class:`App` usually does not need to be subclassed. Instead, subclass + :py:class:`MainDiv` and pass an instance of the derived class to :py:meth:`run()`. + + .. py:attribute:: debugPanel + + An instance of debugpanel.DebugPanel. + + .. py:attribute:: mainDiv + + The instance passed as first argument of the :py:meth:`run()` method. + + .. py:attribute:: overlayPanel + + DivNode that stands always on top of the MainDiv. + + .. py:attribute:: settings + + An instance of settings.Settings. + + .. py:method:: dumpTextObjectCount() + + Dumps on the console the current number of initialized objects. Normally + bound to the keypress :kbd:`CTRL-b`. + + .. py:method:: onBeforeLaunch() + + Called just before starting the main loop (:samp:`Player.play()`). Useful only + for subclassing. The display hasn't been initialized at this point. + + .. py:method:: run(mainDiv, **kargs) + + Starts the application using the provided :py:attr:`mainDiv` (an instance of + :py:class:`MainDiv`). + + The optional additional kargs are used to set default settings - see + :py:class:`settings.Settings`. + + .. py:method:: takeScreenshot(targetFolder='.') + + Takes a screenshot of what is currently visible on the screen. Normally + bound to the keypress :kbd:`CTRL-p`. Screenshots are saved to the disk under + the name 'App-nnn.png', where nnn is a sequence number. + + + .. autoclass:: MainDiv + + 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. + + .. py:attribute:: VERSION + + A version string. This is shown using the :option:`-v` or :option:`--version` + command-line option. + + .. py:method:: 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 + :py:attr:`options` and :py:attr:`args` are the result of calling + :samp:`options, args = parser.parse_args()`, where parser is an instance of + :py:class:`optparse.OptionParser` configured by calling + :py:meth:`onArgvParserCreated`. + + .. py:method:: onArgvParserCreated(parser) + + Called with an empty :py:class:`optparse.OptionParser` instance. Allows the + application to add additional command line options. :py:class:`App` adds it's + own parameters as well. If this is overridden, :py:meth:`onArgvParsed()` + should probably be overridden as well. + + .. py:method:: 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. + + .. py:method:: onFrame() + + Called every frame. + + .. py:method:: 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. + + .. py:method:: onStartup() + + Called before libavg has been setup, just after the :samp:`App().run()` call. + The window has not been created at this time. + + +keyboardmanager Module +---------------------- + +.. automodule:: libavg.app.keyboardmanager + :no-members: + + 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. + :py:class:`libavg.app.App` defines a range of keyboard bindings by default. + The keyboardmanager is usually set up by :py:class:`libavg.app.App`. + :py:class:`libavg.app.App` also reserves all keys modified by :kbd:`CTRL`. + + For all the binding methods, keystring can be a python string or a unicode object. + Plain strings are matched to :py:attr:`libavg.avg.KeyEvent.keystring`, while unicode + objects are matched to :py:attr:`libavg.avg.KeyEvent.unicode`. The modifiers are + described under :py:attr:`libavg.avg.KeyEvent.modifiers`, with the additional modifiers + :py:const:`KEYMOD_SHIFT`, :py:const:`KEYMOD_CTRL` and :py:const:`KEYMOD_ALT` available + to simplify checking for left and right modifier keys at one time. + + .. py:function:: bindKeyDown(keystring, handler, help, modifiers=avg.KEYMOD_NONE) + + Sets up a key handler so that :py:attr:`handler` is called whenever + :py:attr:`keystring` is pressed. + + .. py:function:: bindKeyUp(keystring, handler, help, modifiers=avg.KEYMOD_NONE) + + Sets up a key handler so that :py:attr:`handler` is called whenever + :py:attr:`keystring` is released. + + .. py:function:: disable() + + Companion to :py:meth:`enable()`, disables all handlers. + + .. py:function:: enable() + + Companion to :py:meth:`disable()`, enables all handlers. + + .. py:function:: getCurrentBindings() + + Returns the currently assigned bindings as a list of named tuples. + + .. py:function:: init() + + Called by :py:class:`App`. Should not be called by user programs. + + .. py:function:: pop() + + Companion to :py:meth:`push()`, restores the non-modified key bindings + previously pushed onto the stack via :py:meth:`push()`. + + .. py:function:: 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 :py:meth:`pop()`. + + .. py:function:: unbindAll() + + Removes all the defined key bindings at once. + + .. py:function:: unbindKeyDown(keystring, modifiers=avg.KEYMOD_NONE) + + Removes a previously defined key binding for a KEY_DOWN event. + + .. py:function:: unbindKeyDown(keystring, modifiers=avg.KEYMOD_NONE) + + Removes a previously defined key binding for a KEY_UP event. + + +flashmessage Module +------------------- + +.. automodule:: libavg.app.flashmessage + :no-members: + + .. autoclass:: FlashMessage(text, timeout=DEFAULT_TIMEOUT, parent=None, isError=False, acknowledge=False) + + A :py:class:`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 :py:class:`FlashMessage` instances are shown in the order they get + created. + + :param timeout: The time in milliseconds the message should persist on screen + before it gets removed. Only valid if :py:attr:`acknowledge` is + :py:const:`False`. + + :param parent: When specified, the parent node the message should be appending + itself to. + + :param 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. + + :param 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). + + + |