1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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).
|
