# 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.

  property `backend_module`

    The module object that defines the backend.

  property `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.

  `is_notebook`()

    Determine if the user is executing in a Jupyter Notebook

  property `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.

  property `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.

  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`()

    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')

    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.

  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`()

    Render the canvas to an offscreen buffer and return the image array.

    Returns:

    image array

      Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

  `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.

  property `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.

  property `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.

  property `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()

  property `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.