Skip to main content
`Ctrl`+`K`

# vispy.scene.widgets package

## Subpackages

- vispy.scene.widgets.tests package
  - Submodules
    - vispy.scene.widgets.tests.test_colorbar module
  - Module contents

## Submodules

- vispy.scene.widgets.anchor module
  - `Anchor`
- vispy.scene.widgets.axis module
  - `AxisWidget`
    - `AxisWidget.link_view()`
    - `AxisWidget.on_resize()`
- vispy.scene.widgets.colorbar module
  - `ColorBarWidget`
    - `ColorBarWidget.border_color`
    - `ColorBarWidget.border_width`
    - `ColorBarWidget.clim`
    - `ColorBarWidget.cmap`
    - `ColorBarWidget.label`
    - `ColorBarWidget.on_resize()`
    - `ColorBarWidget.orientation`
    - `ColorBarWidget.ticks`
- vispy.scene.widgets.console module
  - `Console`
    - `Console.clear()`
    - `Console.font_size`
    - `Console.on_resize()`
    - `Console.text_color`
    - `Console.write()`
  - `ConsoleVisual`
    - `ConsoleVisual.clear()`
    - `ConsoleVisual.font_size`
    - `ConsoleVisual.size`
    - `ConsoleVisual.text_color`
    - `ConsoleVisual.write()`
- vispy.scene.widgets.grid module
  - `Grid`
    - `Grid.add_grid()`
    - `Grid.add_view()`
    - `Grid.add_widget()`
    - `Grid.grid_size`
    - `Grid.layout_array`
    - `Grid.next_row()`
    - `Grid.remove_widget()`
    - `Grid.resize_widget()`
- vispy.scene.widgets.label module
  - `Label`
    - `Label.on_resize()`
    - `Label.text`
- vispy.scene.widgets.viewbox module
  - `ViewBox`
    - `ViewBox.add()`
    - `ViewBox.camera`
    - `ViewBox.get_scene_bounds()`
    - `ViewBox.is_in_scene()`
    - `ViewBox.on_resize()`
    - `ViewBox.scene`
- vispy.scene.widgets.widget module
  - `Widget`
    - `Widget.add_grid()`
    - `Widget.add_view()`
    - `Widget.add_widget()`
    - `Widget.bgcolor`
    - `Widget.border_color`
    - `Widget.height`
    - `Widget.height_max`
    - `Widget.height_min`
    - `Widget.inner_rect`
    - `Widget.margin`
    - `Widget.padding`
    - `Widget.picking`
    - `Widget.pos`
    - `Widget.rect`
    - `Widget.remove_widget()`
    - `Widget.size`
    - `Widget.stretch`
    - `Widget.width`
    - `Widget.width_max`
    - `Widget.width_min`

## Module contents

The vispy.scene.widgets namespace provides a range of widgets to allow user interaction. Widgets are rectangular Visual objects such as buttons and sliders.

class vispy.scene.widgets.AxisWidget(orientation='left', **kwargs)

  Bases: `Widget`

  Widget containing an axis

  Parameters:
    orientation str

      Orientation of the axis, ‘left’ or ‘bottom’.

    **kwargs dict

      Keyword arguments to pass to AxisVisual.

  link_view(view)

    Link this axis to a ViewBox

    This makes it so that the axis’s domain always matches the visible range in the ViewBox.

    Parameters:
      view instance of ViewBox

        The ViewBox to link.

  on_resize(event)

    Resize event handler

    Parameters:
      event instance of Event

        The event.

class vispy.scene.widgets.ColorBarWidget(cmap, orientation, label='', label_color='black', clim=('', ''), border_width=0.0, border_color='black', padding=(0.2, 0.2), axis_ratio=0.05, **kwargs)

  Bases: `Widget`

  Widget containing a ColorBar

  Parameters:
    cmap str | vispy.color.ColorMap

      Either the name of the ColorMap to be used from the standard set of names (refer to vispy.color.get_colormap), or a custom ColorMap object. The ColorMap is used to apply a gradient on the colorbar.

    orientation{‘left’, ‘right’, ‘top’, ‘bottom’}

      The orientation of the colorbar, used for rendering. The orientation can be thought of as the position of the label relative to the color bar.

      When the orientation is ‘left’ or ‘right’, the colorbar is vertically placed. When it is ‘top’ or ‘bottom’, the colorbar is horizontally placed. The colorbar automatically resizes when its container’s dimension changes.

      > - ‘top’: the colorbar is horizontal. Color is applied from left to right. Minimum corresponds to left and maximum to right. Label is to the top of the colorbar

      > - ‘bottom’: Same as top, except that label is to the bottom of the colorbar

      > - ‘left’: the colorbar is vertical. Color is applied from bottom to top. Minimum corresponds to bottom and maximum to top. Label is to the left of the colorbar

      > - ‘right’: Same as left, except that the label is placed to the right of the colorbar

    label str

      The label that is to be drawn with the colorbar that provides information about the colorbar.

    label_color str | vispy.color.Color

      The color of labels. This can either be a str as the color’s name or an actual instace of a vipy.color.Color

    clim tuple (min, max)

      the minimum and maximum values of the data that is given to the colorbar. This is used to draw the scale on the side of the colorbar.

    border_width float (in px)

      The width of the border the colormap should have. This measurement is given in pixels

    border_color str | vispy.color.Color

      The color of the border of the colormap. This can either be a str as the color’s name or an actual instace of a vipy.color.Color

    padding tuple (major_axis, minor_axis) [0, 1]

      padding with respect to the major and minor axis

    axis_ratio float

      ratio of minor axis to major axis

  property border_color

    The color of the border around the ColorBar in pixels

  property border_width

    The width of the border around the ColorBar in pixels

  property clim
  property cmap
  property label
  on_resize(event)

    Resize event handler

    Parameters:
      event instance of Event

        The event.

  property orientation
  property ticks

class vispy.scene.widgets.Console(text_color='black', font_size=12.0, **kwargs)

  Bases: `Widget`

  Fast and failsafe text console

  Parameters:
    text_color instance of Color

      Color to use.

    font_size float

      Point size to use.

  clear()

    Clear the console

  property font_size

    The font size (in points) of the text

  on_resize(event)

    Resize event handler

    Parameters:
      event instance of Event

        The event.

  property text_color

    The color of the text

  write(text='', wrap=True)

    Write text and scroll

    Parameters:
      text str

        Text to write. `''` can be used for a blank line, as a newline is automatically added to the end of each line.

      wrap str

        If True, long messages will be wrapped to span multiple lines.

class vispy.scene.widgets.Grid(spacing=6, **kwargs)

  Bases: `Widget`

  Widget for proportionally dividing its internal area into a grid.

  This widget will automatically set the position and size of child widgets according to provided constraints.

  Parameters:
    spacing int

      Spacing between widgets.

    **kwargs dict

      Keyword arguments to pass to Widget.

  add_grid(row=None, col=None, row_span=1, col_span=1, **kwargs)

    Create a new Grid and add it as a child widget.

    Parameters:
      row int

        The row in which to add the widget (0 is the topmost row)

      col int

        The column in which to add the widget (0 is the leftmost column)

      row_span int

        The number of rows to be occupied by this widget. Default is 1.

      col_span int

        The number of columns to be occupied by this widget. Default is 1.

      **kwargs dict

        Keyword arguments to pass to the new Grid.

  add_view(row=None, col=None, row_span=1, col_span=1, **kwargs)

    Create a new ViewBox and add it as a child widget.

    Parameters:
      row int

        The row in which to add the widget (0 is the topmost row)

      col int

        The column in which to add the widget (0 is the leftmost column)

      row_span int

        The number of rows to be occupied by this widget. Default is 1.

      col_span int

        The number of columns to be occupied by this widget. Default is 1.

      **kwargs dict

        Keyword arguments to pass to ViewBox.

  add_widget(widget=None, row=None, col=None, row_span=1, col_span=1, **kwargs)

    Add a new widget to this grid.

    This will cause other widgets in the grid to be resized to make room for the new widget. Can be used to replace a widget as well.

    Parameters:
      widget Widget | None

        The Widget to add. New widget is constructed if widget is None.

      row int

        The row in which to add the widget (0 is the topmost row)

      col int

        The column in which to add the widget (0 is the leftmost column)

      row_span int

        The number of rows to be occupied by this widget. Default is 1.

      col_span int

        The number of columns to be occupied by this widget. Default is 1.

      **kwargs dict

        parameters sent to the new Widget that is constructed if widget is None

    Notes

    The widget’s parent is automatically set to this grid, and all other parent(s) are removed.

  property grid_size
  property layout_array
  next_row()
  remove_widget(widget)

    Remove a widget from this grid.

    Parameters:
      widget Widget

        The Widget to remove

  resize_widget(widget, row_span, col_span)

    Resize a widget in the grid to new dimensions.

    Parameters:
      widget Widget

        The widget to resize

      row_span int

        The number of rows to be occupied by this widget.

      col_span int

        The number of columns to be occupied by this widget.

class vispy.scene.widgets.Label(text, rotation=0.0, **kwargs)

  Bases: `Widget`

  Label widget

  Parameters:
    text str

      The label.

    rotation float

      The rotation of the label.

    **kwargs dict

      Keyword arguments to pass to TextVisual.

  on_resize(event)

    Resize event handler

    Parameters:
      event instance of Event

        The event.

  property text

class vispy.scene.widgets.ViewBox(camera=None, **kwargs)

  Bases: `Widget`

  Provides a rectangular widget to which its subscene is rendered.

  Three classes work together when using a ViewBox: * The `SubScene` class describes a “world” coordinate system and the entities that live inside it. * ViewBox is a “window” through which we view the subscene. Multiple ViewBoxes may view the same subscene. * `Camera` describes both the perspective from which the subscene is rendered, and the way user interaction affects that perspective.

  In general it is only necessary to create the ViewBox; a SubScene and Camera will be generated automatically.

  Parameters:
    camera instance of Camera | str | None

      The camera through which to view the SubScene. If None, then a PanZoomCamera (2D interaction) is used. If str, then the string is used as the argument to `make_camera()`.

    **kwargs dict

      Extra keyword arguments to pass to Widget.

  add(node)

    Add an Node to the scene for this ViewBox.

    This is a convenience method equivalent to node.parent = viewbox.scene

    Parameters:
      node instance of Node

        The node to add.

  property camera: BaseCamera

    Get/set the Camera in use by this ViewBox

    If a string is given (e.g. ‘panzoom’, ‘turntable’, ‘fly’). A corresponding camera is selected if it already exists in the scene, otherwise a new camera is created.

    The camera object is made a child of the scene (if it is not already in the scene).

    Multiple cameras can exist in one scene, although only one can be active at a time. A single camera can be used by multiple viewboxes at the same time.

  get_scene_bounds(dim=None)

    Get the total bounds based on the visuals present in the scene

    Parameters:
      dim int | None

        Dimension to return.

    Returns:
      bounds list | tuple

        If `dim is None`, Returns a list of 3 tuples, otherwise the bounds for the requested dimension.

  is_in_scene(node)

    Get whether the given node is inside the scene of this viewbox.

    Parameters:
      node instance of Node

        The node.

  on_resize(event)

    Resize event handler

    Parameters:
      event instance of Event

        The event.

  property scene

    The root node of the scene viewed by this ViewBox.

class vispy.scene.widgets.Widget(pos=(0, 0), size=(10, 10), border_color=None, border_width=1, bgcolor=None, padding=0, margin=0, **kwargs)

  Bases: `Compound`

  A widget takes up a rectangular space, intended for use in a 2D pixel coordinate frame.

  The widget is positioned using the transform attribute (as any node), and its extent (size) is kept as a separate property.

  Parameters:
    pos(x, y)

      A 2-element tuple to specify the top left corner of the widget.

    size(w, h)

      A 2-element tuple to spicify the size of the widget.

    border_color color

      The color of the border.

    border_width float

      The width of the border line in pixels.

    bgcolor color

      The background color.

    padding int

      The amount of padding in the widget (i.e. the space reserved between the contents and the border).

    margin int

      The margin to keep outside the widget’s border.

  add_grid(*args, **kwargs)

    Create a new Grid and add it as a child widget.

    All arguments are given to Grid().

  add_view(*args, **kwargs)

    Create a new ViewBox and add it as a child widget.

    All arguments are given to ViewBox().

  add_widget(widget)

    Add a Widget as a managed child of this Widget.

    The child will be automatically positioned and sized to fill the entire space inside this Widget (unless _update_child_widgets is redefined).

    Parameters:
      widget instance of Widget

        The widget to add.

    Returns:
      widget instance of Widget

        The widget.

  property bgcolor

    The background color of the Widget.

  property border_color

    The color of the border.

  property height

    The actual height of the widget

  property height_max

    The maximum height of the widget

  property height_min

    The minimum height of the widget

  property inner_rect

    The rectangular area inside the margin, border, and padding.

    Generally widgets should avoid drawing or placing sub-widgets outside this rectangle.

  property margin
  property padding
  property picking

    Boolean that determines whether this node (and its children) are drawn in picking mode.

  property pos
  property rect
  remove_widget(widget)

    Remove a Widget as a managed child of this Widget.

    Parameters:
      widget instance of Widget

        The widget to remove.

  property size

    The size (w, h) of this widget.

    If the widget is a child of another widget, then its size is assigned automatically by its parent.

  property stretch

    Stretch factors (w, h) used when determining how much space to allocate to this widget in a layout.

    If either stretch factor is None, then it will be assigned when the widget is added to a layout based on the number of columns or rows it occupies.

  property width

    The actual width of this widget

  property width_max

    The maximum width the widget can have

  property width_min

    The minimum width the widget can have