Application
This class encapsulates the application window in an object-oriented interface.
Instantiation
The Application constructor accepts one string parameter, for the application name (which will appear in the panel bar). Optionally, you can give a Server object as the second parameter. If you don't, the constructor will instantiate one with the default arguments (localhost:0).
Widget operations
The Application class is a subclass of Widget, so all Widget operations apply. In particular, the top-level widgets in your window are created using application.addWidget()
.
Event handling
Each Application object performs event handling in a subscription-based system. The application object has a link()
method used to subscribe to events. It accepts three arguments, handler
, widget
and event
, where event
and widget
can be omitted.
Linking to a specific event
link(myhandler, mybutton, "activate")
will register myhandler
to be called whenever mybutton
receives an "activate"
event (when it is clicked).
Linking to any event of a widget
link(myhandler, mybutton)
will register myhandler
to be called whenever mybutton
receives any event.
Linking to a generic event
link(myhandler, "activate")
or link(myhandler, event="activate")
will register myhandler
to be called whenever any widget receives an "activate"
event (when it is clicked).
Monitoring events
link(myhandler)
will register myhandler
to be called whenever any widget receives any event.
Writing handlers
Event handlers are called with two arguments. The first is the event object - see [EventModule]?. The second is a Widget object representing the widget that received the event, or None if it was a no-widget event.
As the server has no idea about our object wrappers, there are some issues about the second argument:
- If the handler was registered to a particular widget object, the second argument will always be this same object.
- If the widget was created in the usual way, with
addWidget()
starting from this same application object, then the widget object will be in a registry and thus will be returned. - If, however, the widget was created outside the widget object tree, then a new widget object representing the same widget will be instantiated and returned. This is safe, as the only state saved in the widget object is a reference to its parent (which will not be available in this case).
Sending events
You can send "internal" events that don't go trough the server by calling the send()
method in the application object. It takes two arguments, the first is a widget to send the event to (or None
) and the second is the event name string. Note that these events have no meaning as far as ../PicoGUI is concerned, they're just for internal communication in the Python level.
Receiving events
The run()
method first sends an update
request to the server, then sits in an event loop receiving and dispatching events. The event loop exits if the application object receives a "close"
(../PicoGUI) or "stop"
(internal) event. If it was stopped by "stop"
, you may call run()
again to resume the loop.
Examples
See CodingRecipes - all of them use Application objects.