Skip to content

Home News Screenshots Wiki Themes Bugtracker Members Logos Search
  You are not logged in Link icon Log in Link icon Join
You are here: Home » PicoGUI Wiki » cli_python documentation » Application

Log in
FrontPage » ReferenceByClass »


This class encapsulates the application window in an object-oriented interface.


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:

  1. If the handler was registered to a particular widget object, the second argument will always be this same object.
  2. 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.
  3. 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.


See CodingRecipes - all of them use Application objects.