API. Canvas

Canvas API

This document describes the full specification of the Canvas API

Overview

Canvas is an abstraction designed to allow basic interaction with a variety of GUI toolkits. A Canvas is roughly equivalent to a widget in Qt or a window in pyglet. It is a subclass of EventReceiver, and thus can notify the user about window-system and input events.

Interface

Canvas class:

• Represents a single widget or window, meant to be subclassed by the user (but can also be used as-is)
• Has user-modifiable hooks for window-system and input events: initialize, resize, paint, mouse, keyboard, stylus, touch, close
• Subclass of EventReceiver, so hooks can be implemented either as subclass methods (like 'resize_event') or by connecting to callback functions.
• Provides basic widget/window interaction: show(), update(), resize(), close()
• Also includes run() method, which invokes backend-specific event loop
• Has a 'backend' attribute which points to an instance of CanvasBackend

CanvasBackend class:

• Abstraction layer that translates a particular GUI toolkit to the Canvas API. Contains some stub methods which must be reimplemented by each backend.
• Handles events from the GUI toolkit and calls canvas.call_event(...) to initiate event propagation
• I considered making Canvas and CanvasBackend the same class, but this would make it very difficult for users to subclass Canvas.

Examples

from vispy.opengl.canvas import Canvas
canvas = Canvas()  ## can optionally specify the backend name here
canvas.resize(500, 500)
canvas.show() 

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

@canvas.events.mouse.connect
def mouse_event(event):
    if event.action == 'clicked':
        print "clicked at:", event.pos

canvas.run()  ## start event loop

Full specification