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)[source]¶ 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_namestr | 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_reusebool
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.
process_events
()[source]¶ 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)[source]¶ 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_namestr | 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.
-
property
backend_module
¶ The module object that defines the backend.
-
property
backend_name
¶ The name of the GUI backend that this app wraps.
-
property
native
¶ The native GUI application instance.
-
process_events
()[source]¶ 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.
-
reuse
()[source]¶ 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)[source]¶ Enter the native GUI event loop.
Parameters: - allow_interactivebool
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.
-
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, backend_kwargs=None)[source]¶ Representation of a GUI element with an OpenGL context
Parameters: - titlestr
The widget title
- size(width, height)
The size of the window.
- position(x, y)
The position of the window in screen coordinates.
- showbool
Whether to show the widget immediately. Default False.
- autoswapbool
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 thecanvas.draw
event handler.- appApplication | 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_nativebool
Whether to create the widget immediately. Default True.
- vsyncbool
Enable vertical synchronization.
- resizablebool
Allow the window to be resized.
- decoratebool
Decorate the window. Default True.
- fullscreenbool | int
If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.
- configdict
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.- sharedCanvas | GLContext | None
An existing canvas or context to share OpenGL objects with.
- keysstr | 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.- parentwidget-object
The parent widget if this makes sense for the used backend.
- dpifloat | 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_topbool
If True, try to create the window in always-on-top mode.
- px_scaleint > 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.
- backend_kwargsdict
Keyword arguments to be supplied to the backend canvas object.
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.
Backend-specific arguments can be given through the backend_kwargs argument. Currently this can be used to control the webGL context requested by the ipynb_webgl backend, for example:
canvas = Canvas(backend_kwargs={'webgl': dict(preserveDrawingBuffer=True)})
-
property
app
¶ The vispy Application instance on which this Canvas is based.
-
close
()[source]¶ 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)[source]¶ 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: - funcallable
The function.
-
property
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
()[source]¶ Create the native widget if not already done so. If the widget is already created, this function does nothing.
-
property
dpi
¶ The physical resolution of the canvas in dots per inch.
-
property
fps
¶ The fps of canvas/window, as the rate that events.draw is emitted
-
measure_fps
(window=1, callback='%1.1f FPS')[source]¶ Measure the current FPS
Sets the update window, connects the draw event to update_fps and sets the callback function.
Parameters: - windowfloat
The time-window (in seconds) to calculate FPS. Default 1.0.
- callbackfunction | 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.
-
property
native
¶ The native widget object on which this Canvas is based.
-
property
physical_size
¶ The physical size of the canvas/window, which may differ from the size property on backends that expose HiDPI
-
property
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). When writing Visuals or SceneGraph visualisations, this value is exposed as TransformSystem.px_scale.
-
property
position
¶ The position of canvas/window relative to screen
-
render
()[source]¶ Render the canvas to an offscreen buffer and return the image array.
Returns: - imagearray
Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.
-
show
(visible=True, run=False)[source]¶ Show or hide the canvas
Parameters: - visiblebool
Make the canvas visible.
- runbool
Run the backend event loop.
-
property
size
¶ The size of canvas/window
-
swap_buffers
(event=None)[source]¶ Swap GL buffers such that the offscreen buffer becomes visible
Parameters: - eventNone
Not used.
-
property
title
¶ The title of canvas/window
-
class
vispy.app.
Timer
(interval='auto', connect=None, iterations=- 1, start=False, app=None)[source]¶ Timer used to schedule events in the future or on a repeating schedule
Parameters: - intervalfloat | ‘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.
- connectfunction | None
The function to call.
- iterationsint
Number of iterations. Can be -1 for infinite.
- startbool
Whether to start the timer.
- appinstance of vispy.app.Application
The application to attach the timer to.
-
property
app
¶ The vispy Application instance on which this Timer is based.
-
property
native
¶ The native timer on which this Timer is based.
-
start
(interval=None, iterations=None)[source]¶ 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).