The app module

The app module defines three classes: Application, Canvas, and Timer. On loading, vispy creates a default Application instance which can be used via functions in the module's namespace.


vispy.app.use_app(backend_name=None, call_reuse=True)

Get/create the default Application object

It is safe to call this function multiple times, as long as backend_name is None or matches the already selected backend.

Parameters:

backend_name : str | None

The name of the backend application to use. If not specified, Vispy tries to select a backend automatically. See vispy.use() for details.

call_reuse : bool

Whether to call the backend's reuse() function (True by default). Not implemented by default, but some backends need it. For example, the notebook backends need to inject some JavaScript in a notebook as soon as use_app() is called.

vispy.app.create()

Create the native application.

vispy.app.run()

Enter the native GUI event loop.

vispy.app.quit()

Quit the native GUI event loop.

vispy.app.process_events()

Process all pending GUI events

If the mainloop is not running, this should be done regularly to keep the visualization interactive and to keep the event system going.


class vispy.app.Application(backend_name=None)

Representation of the vispy application

This wraps a native GUI application instance. Vispy has a default instance of this class that can be created/obtained via vispy.app.use_app().

Parameters:

backend_name : str | None

The name of the backend application to use. If not specified, Vispy tries to select a backend automatically. See vispy.use() for details.

Notes

Upon creating an Application object, a backend is selected, but the native backend application object is only created when create() is called or native is used. The Canvas and Timer do this automatically.

Methods

create() Create the native application.
is_interactive() Determine if the user requested interactive mode.
process_events() Process all pending GUI events.
quit() Quit the native GUI event loop.
reuse() Called when the application is reused in an interactive session.
run([allow_interactive]) Enter the native GUI event loop.
sleep(duration_sec) Sleep for the given duration in seconds.
backend_module

The module object that defines the backend.

backend_name

The name of the GUI backend that this app wraps.

create()

Create the native application.

is_interactive()

Determine if the user requested interactive mode.

native

The native GUI application instance.

process_events()

Process all pending GUI events. If the mainloop is not running, this should be done regularly to keep the visualization interactive and to keep the event system going.

quit()

Quit the native GUI event loop.

reuse()

Called when the application is reused in an interactive session. This allow the backend to do stuff in the client when use_app() is called multiple times by the user. For example, the notebook backends need to inject JavaScript code as soon as use_app() is called.

run(allow_interactive=True)

Enter the native GUI event loop.

Parameters:

allow_interactive : bool

Is the application allowed to handle interactive mode for console terminals? By default, typing python -i main.py results in an interactive shell that also regularly calls the VisPy event loop. In this specific case, the run() function will terminate immediately and rely on the interpreter's input loop to be run after script execution.

sleep(duration_sec)

Sleep for the given duration in seconds.

This is used to reduce CPU stress when VisPy is run in interactive mode. see inputhook.py for details

Parameters:

duration_sec: float :

Time to sleep in seconds


class vispy.app.Canvas(title='Vispy canvas', size=(800, 600), position=None, show=False, autoswap=True, app=None, create_native=True, vsync=False, resizable=True, decorate=True, fullscreen=False, config=None, shared=None, keys=None, parent=None, dpi=None, always_on_top=False, px_scale=1)

Representation of a GUI element with an OpenGL context

Parameters:

title : str

The widget title

size : (width, height)

The size of the window.

position : (x, y)

The position of the window in screen coordinates.

show : bool

Whether to show the widget immediately. Default False.

autoswap : bool

Whether to swap the buffers automatically after a draw event. Default True. If True, the swap_buffers Canvas method will be called last (by default) by the canvas.draw event handler.

app : Application | str

Give vispy Application instance to use as a backend. (vispy.app is used by default.) If str, then an application using the chosen backend (e.g., 'pyglet') will be created. Note the canvas application can be accessed at canvas.app.

create_native : bool

Whether to create the widget immediately. Default True.

vsync : bool

Enable vertical synchronization.

resizable : bool

Allow the window to be resized.

decorate : bool

Decorate the window. Default True.

fullscreen : bool | int

If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.

config : dict

A dict with OpenGL configuration options, which is combined with the default configuration options and used to initialize the context. See canvas.context.config for possible options.

shared : Canvas | GLContext | None

An existing canvas or context to share OpenGL objects with.

keys : str | dict | None

Default key mapping to use. If 'interactive', escape and F11 will close the canvas and toggle full-screen mode, respectively. If dict, maps keys to functions. If dict values are strings, they are assumed to be Canvas methods, otherwise they should be callable.

parent : widget-object

The parent widget if this makes sense for the used backend.

dpi : float | None

Resolution in dots-per-inch to use for the canvas. If dpi is None, then the value will be determined by querying the global config first, and then the operating system.

always_on_top : bool

If True, try to create the window in always-on-top mode.

px_scale : int > 0

A scale factor to apply between logical and physical pixels in addition to the actual scale factor determined by the backend. This option allows the scale factor to be adjusted for testing.

Notes

The Canvas receives the following events:

  • initialize
  • resize
  • draw
  • mouse_press
  • mouse_release
  • mouse_double_click
  • mouse_move
  • mouse_wheel
  • key_press
  • key_release
  • stylus
  • touch
  • close

The ordering of the mouse_double_click, mouse_press, and mouse_release events are not guaranteed to be consistent between backends. Only certain backends natively support double-clicking (currently Qt and WX); on other backends, they are detected manually with a fixed time delay. This can cause problems with accessibility, as increasing the OS detection time or using a dedicated double-click button will not be respected.

Methods

close() Close the canvas
connect(fun) Connect a function to an event
create_native() Create the native widget if not already done so.
measure_fps([window, callback]) Measure the current FPS
set_current([event]) Make this the active GL canvas
show([visible, run]) Show or hide the canvas
swap_buffers([event]) Swap GL buffers such that the offscreen buffer becomes visible
update([event]) Inform the backend that the Canvas needs to be redrawn
app

The vispy Application instance on which this Canvas is based.

close()

Close the canvas

Notes

This will usually destroy the GL context. For Qt, the context (and widget) will be destroyed only if the widget is top-level. To avoid having the widget destroyed (more like standard Qt behavior), consider making the widget a sub-widget.

connect(fun)

Connect a function to an event

The name of the function should be on_X, with X the name of the event (e.g. 'on_draw').

This method is typically used as a decorator on a function definition for an event handler.

Parameters:

fun : callable

The function.

context

The OpenGL context of the native widget

It gives access to OpenGL functions to call on this canvas object, and to the shared context namespace.

create_native()

Create the native widget if not already done so. If the widget is already created, this function does nothing.

dpi

The physical resolution of the canvas in dots per inch.

fps

The fps of canvas/window, as the rate that events.draw is emitted

measure_fps(window=1, callback='%1.1f FPS')

Measure the current FPS

Sets the update window, connects the draw event to update_fps and sets the callback function.

Parameters:

window : float

The time-window (in seconds) to calculate FPS. Default 1.0.

callback : function | str

The function to call with the float FPS value, or the string to be formatted with the fps value and then printed. The default is '%1.1f FPS'. If callback evaluates to False, the FPS measurement is stopped.

native

The native widget object on which this Canvas is based.

physical_size

The physical size of the canvas/window, which may differ from the size property on backends that expose HiDPI

pixel_scale

The ratio between the number of logical pixels, or 'points', and the physical pixels on the device. In most cases this will be 1.0, but on certain backends this will be greater than 1. This should be used as a scaling factor when writing your own visualisations with Gloo (make a copy and multiply all your logical pixel values by it) but you should rarely, if ever, need to use this in your own Visuals or SceneGraph visualisations; instead you should apply the canvas_fb_transform in the SceneGraph canvas.

position

The position of canvas/window relative to screen

set_current(event=None)

Make this the active GL canvas

Parameters:

event : None

Not used.

show(visible=True, run=False)

Show or hide the canvas

Parameters:

visible : bool

Make the canvas visible.

run : bool

Run the backend event loop.

size

The size of canvas/window

swap_buffers(event=None)

Swap GL buffers such that the offscreen buffer becomes visible

Parameters:

event : None

Not used.

title

The title of canvas/window

update(event=None)

Inform the backend that the Canvas needs to be redrawn

Parameters:

event : None

Not used.


class vispy.app.Timer(interval='auto', connect=None, iterations=-1, start=False, app=None)

Timer used to schedule events in the future or on a repeating schedule

Parameters:

interval : float | 'auto'

Time between events in seconds. The default is 'auto', which attempts to find the interval that matches the refresh rate of the current monitor. Currently this is simply 1/60.

connect : function | None

The function to call.

iterations : int

Number of iterations. Can be -1 for infinite.

start : bool

Whether to start the timer.

app : instance of vispy.app.Application

The application to attach the timer to.

Methods

connect(callback) Alias for self.events.timeout.connect()
disconnect([callback]) Alias for self.events.timeout.disconnect()
start([interval, iterations]) Start the timer.
stop() Stop the timer.
app

The vispy Application instance on which this Timer is based.

connect(callback)

Alias for self.events.timeout.connect()

disconnect(callback=None)

Alias for self.events.timeout.disconnect()

native

The native timer on which this Timer is based.

start(interval=None, iterations=None)

Start the timer.

A timeout event will be generated every interval seconds. If interval is None, then self.interval will be used.

If iterations is specified, the timer will stop after emitting that number of events. If unspecified, then the previous value of self.iterations will be used. If the value is negative, then the timer will continue running until stop() is called.

If the timer is already running when this function is called, nothing happens (timer continues running as it did previously, without changing the interval, number of iterations, or emitting a timer start event).

stop()

Stop the timer.