# vispy.app.canvas module

class vispy.app.canvas.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)

  Bases: `object`

  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.

    backend_kwargs dict

      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.

  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.

  property fullscreen
  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(alpha=True)

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

    Parameters:
      alpha bool

        If True (default) produce an RGBA array (M, N, 4). If False, remove the Alpha channel and return the RGB array (M, N, 3). This may be useful if blending of various elements requires a solid background to produce the expected visualization.

    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. If `alpha` is `False`, then only 3 channels will be returned (RGB).

  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.canvas.DrawEvent(type, region=None, **kwargs)

  Bases: `Event`

  Draw event class

  This type of event is sent to Canvas.events.draw when a redraw is required.

  Note that each event object has an attribute for each of the input arguments listed below.

  Parameters:
    type str

      String indicating the event type (e.g. mouse_press, key_release)

    region(int, int, int, int) or None

      The region of the canvas which needs to be redrawn (x, y, w, h). If None, the entire canvas must be redrawn.

    native object (optional)

      The native GUI event object

    **kwargs extra keyword arguments

      All extra keyword arguments become attributes of the event object.

  property region

class vispy.app.canvas.KeyEvent(type, key=None, text='', modifiers=None, **kwargs)

  Bases: `Event`

  Key event class

  Note that each event object has an attribute for each of the input arguments listed below.

  Parameters:
    type str

      String indicating the event type (e.g. mouse_press, key_release)

    key vispy.keys.Key instance

      The Key object for this event. Can be compared to string names.

    text str

      The text representation of the key (can be an empty string).

    modifiers tuple of Key instances

      Tuple that specifies which modifier keys were pressed down at the time of the event (shift, control, alt, meta).

    native object (optional)

      The native GUI event object

    **kwargs keyword arguments

      All extra keyword arguments become attributes of the event object.

  property key
  property modifiers
  property text

class vispy.app.canvas.MouseEvent(type, pos=None, button=None, buttons=None, modifiers=None, delta=None, last_event=None, press_event=None, **kwargs)

  Bases: `Event`

  Mouse event class

  Note that each event object has an attribute for each of the input arguments listed below, as well as a “time” attribute with the event’s precision start time.

  Parameters:
    type str

      String indicating the event type (e.g. mouse_press, key_release)

    pos(int, int)

      The position of the mouse (in screen coordinates).

    button int | None

      The button that generated this event (can be None). Left=1, right=2, middle=3. During a mouse drag, this will return the button that started the drag (same thing as `event.press_event.button`).

    buttons[int, …]

      The list of buttons pressed during this event.

    modifiers tuple of Key instances

      Tuple that specifies which modifier keys were pressed down at the time of the event (shift, control, alt, meta).

    delta(float, float)

      The amount of scrolling in horizontal and vertical direction. One “tick” corresponds to a delta of 1.0.

    press_event MouseEvent

      The press event that was generated at the start of the current drag, if any.

    last_event MouseEvent

      The MouseEvent immediately preceding the current event. During drag operations, all generated events retain their last_event properties, allowing the entire drag to be reconstructed.

    native object (optional)

      The native GUI event object

    **kwargs keyword arguments

      All extra keyword arguments become attributes of the event object.

  property button
  property buttons
  property delta
  drag_events()

    Return a list of all mouse events in the current drag operation.

    Returns None if there is no current drag operation.

  property is_dragging

    Indicates whether this event is part of a mouse drag operation.

  property last_event
  property modifiers
  property pos
  property press_event
  property time
  trail()

    Return an (N, 2) array of mouse coordinates for every event in the current mouse drag operation.

    Returns None if there is no current drag operation.

class vispy.app.canvas.ResizeEvent(type, size=None, physical_size=None, **kwargs)

  Bases: `Event`

  Resize event class

  Note that each event object has an attribute for each of the input arguments listed below.

  Parameters:
    type str

      String indicating the event type (e.g. mouse_press, key_release)

    size(int, int)

      The new size of the Canvas, in points (logical pixels).

    physical_size(int, int)

      The new physical size of the Canvas, in pixels.

    native object (optional)

      The native GUI event object

    **kwargs extra keyword arguments

      All extra keyword arguments become attributes of the event object.

  property physical_size
  property size

previous

vispy.app.base module

next

vispy.app.qt module