This document describes the specification of the application API.

The app package provides an abstraction designed to allow basic interaction with a variety of GUI toolkits. It provides simplicity, so users don't have to know about qt/wx/pyglet/... On the other hand, it provides flexibility to embed a visualization as a widget in an application, or e.g. use multiple application frameworks simultaneously.

Note: this document is currently limited to GUI applications. Whether other backends (like VNC-to-browser, or WebGL) will fit into this picture or get a separate package is yet to be determined.

The app package defines three public classes:

• Application
  • Represents (wraps) a backend application
  • Has method use to select the backend.
  • Has methods run, quit, process_events.
  • Has property native to obtain the backend application object.
• Canvas
  • Represents (wraps) a single widget or window.
  • Can be subclassed or used as-is.
  • Has user-modifiable hooks for window-system and input events: initialize, resize, paint, mouse, keyboard, etc.
  • Provides basic widget/window interaction: show(), update(), resize(), close()
  • Has a native attribute which points to the backend widget object.
• Timer
  • Represents (wraps) a backend timer.
  • Provides methods start and stop, and properties running, interval.
  • Has an timeout event emitter (or is it events.timeout?)

When vispy.app is imported, a default Application instance is created. The package further contains a few functions that hook into this default app object: use, run, quit, process_events. This makes usage very simple when only one application is required (>95% of cases).

Example 1:

from vispy import app
class MyCanvas(app.Canvas):
   def on_paint(self):
       ...
 canvas = MyCanvas()
 app.run()

Example 2:

from vispy import app
app.use('qt')  # Select Qt as the backend

canvas = app.Canvas()
canvas.resize(500, 500)
canvas.show() 

@canvas.events.paint.connect
def paint(event):
    glClear(GL_COLOR_BUFFER_BIT)
    . . .

@canvas.events.mouse_press.connect
def mouse_event(event):        
    print("clicked at:", event.pos)

app.run()  ## start event loop

For each of the three classes mentioned above, there is a corresponding Backend class. Backends are required to mix these classes with the native backend application/widget/timer (or wrap it). These backend classes thus provide an abstraction layer that translates the backend-specific API's to vispy' generic API.

To implement a backend, all stub methods of ApplicationBackend, CanvasBackend, and TimerBackend must be implemented, and all required events should be emitted from the corresponding EventEmitters.

This approach makes it possible to subclass Canvas (and Application and Timer), enabling very easy creation of small applications.