ViewBox

class pyqtgraph.ViewBox(parent=None, border=None, lockAspect=False, enableMouse=True, invertY=False, enableMenu=True, name=None, invertX=False, defaultPadding=0.02)[source]

Bases: GraphicsWidget

Box that allows internal scaling/panning of children by mouse drag. This class is usually created automatically as part of a PlotItem or Canvas or with GraphicsLayout.addViewBox().

Features:

  • Scaling contents by mouse or auto-scale when contents change

  • View linking–multiple views display the same data ranges

  • Configurable by context menu

  • Item coordinate mapping methods

__init__(parent=None, border=None, lockAspect=False, enableMouse=True, invertY=False, enableMenu=True, name=None, invertX=False, defaultPadding=0.02)[source]

Arguments:

parent

(QGraphicsWidget) Optional parent widget

border

(QPen) Do draw a border around the view, give any single argument accepted by mkPen

lockAspect

(False or float) The aspect ratio to lock the view coorinates to. (or False to allow the ratio to change)

enableMouse

(bool) Whether mouse can be used to scale/pan the view

invertY

(bool) See invertY

invertX

(bool) See invertX

enableMenu

(bool) Whether to display a context menu when right-clicking on the ViewBox background.

name

(str) Used to register this ViewBox so that it appears in the “Link axis” dropdown inside other ViewBox context menus. This allows the user to manually link the axes of any other view to this one.

defaultPadding

(float) fraction of the data range that will be added as padding by default

addItem(item, ignoreBounds=False)[source]

Add a QGraphicsItem to this view. The view will include this item when determining how to set its range automatically unless ignoreBounds is True.

allChildren(item=None)[source]

Return a list of all children and grandchildren of this ViewBox

autoRange(padding=None, items=None, item=None)[source]

Set the range of the view box to make all children visible. Note that this is not the same as enableAutoRange, which causes the view to automatically auto-range whenever its contents are changed.

Arguments:

padding

The fraction of the total data range to add on to the final visible range. By default, this value is set between the default padding and 0.1 depending on the size of the ViewBox.

items

If specified, this is a list of items to consider when determining the visible range.

childTransform()[source]

Return the transform that maps from child(item in the childGroup) coordinates to local coordinates. (This maps from inside the viewbox to outside)

childrenBounds(frac=None, orthoRange=(None, None), items=None)[source]

Return the bounding range of all children. [[xmin, xmax], [ymin, ymax]] Values may be None if there are no specific bounds for an axis.

disableAutoRange(axis=None)[source]

Disables auto-range. (See enableAutoRange)

enableAutoRange(axis=None, enable=True, x=None, y=None)[source]

Enable (or disable) auto-range for axis, which may be ViewBox.XAxis, ViewBox.YAxis, or ViewBox.XYAxes for both (if axis is omitted, both axes will be changed). When enabled, the axis will automatically rescale when items are added/removed or change their shape. The argument enable may optionally be a float (0.0-1.0) which indicates the fraction of the data that should be visible (this only works with items implementing a dataRange method, such as PlotDataItem).

getAspectRatio()[source]

return the current aspect ratio

getState(copy=True)[source]

Return the current state of the ViewBox. Linked views are always converted to view names in the returned state.

invertX(b=True)[source]

By default, the positive x-axis points rightward on the screen. Use invertX(True) to reverse the x-axis.

invertY(b=True)[source]

By default, the positive y-axis points upward on the screen. Use invertY(True) to reverse the y-axis.

itemBoundingRect(item)[source]

Return the bounding rect of the item in view coordinates

keyPressEvent(ev)[source]

This routine should capture key presses in the current view box. Key presses are used only when mouse mode is RectMode The following events are implemented: ctrl-A : zooms out to the default “full” view of the plot ctrl-+ : moves forward in the zooming stack (if it exists) ctrl– : moves backward in the zooming stack (if it exists)

linkView(axis, view)[source]

Link X or Y axes of two views and unlink any previously connected axes. axis must be ViewBox.XAxis or ViewBox.YAxis. If view is None, the axis is left unlinked.

locate(item, timeout=3.0, children=False)[source]

Temporarily display the bounding rect of an item and lines connecting to the center of the view. This is useful for determining the location of items that may be out of the range of the ViewBox. if allChildren is True, then the bounding rect of all item’s children will be shown instead.

mapFromItemToView(item, obj)[source]

Maps obj from the local coordinate system of item to the view coordinates

mapFromView(obj)[source]

Maps from the coordinate system displayed inside the ViewBox to the local coordinates of the ViewBox

mapFromViewToItem(item, obj)[source]

Maps obj from view coordinates to the local coordinate system of item.

mapSceneToView(obj)[source]

Maps from scene coordinates to the coordinate system displayed inside the ViewBox

mapToView(obj)[source]

Maps from the local coordinates of the ViewBox to the coordinate system displayed inside the ViewBox

mapViewToScene(obj)[source]

Maps from the coordinate system displayed inside the ViewBox to scene coordinates

register(name)[source]

Add this ViewBox to the registered list of views.

This allows users to manually link the axes of any other ViewBox to this one. The specified name will appear in the drop-down lists for axis linking in the context menus of all other views.

The same can be accomplished by initializing the ViewBox with the name attribute.

removeItem(item)[source]

Remove an item from this view.

scaleBy(s=None, center=None, x=None, y=None)[source]

Scale by s around given center point (or center of view). s may be a Point or tuple (x, y).

Optionally, x or y may be specified individually. This allows the other axis to be left unaffected (note that using a scale factor of 1.0 may cause slight changes due to floating-point error).

screenGeometry()[source]

return the screen geometry of the viewbox

setAspectLocked(lock=True, ratio=1)[source]

If the aspect ratio is locked, view scaling must always preserve the aspect ratio. By default, the ratio is set to 1; x and y both have the same scaling. This ratio can be overridden (xScale/yScale), or use None to lock in the current ratio.

setAutoPan(x=None, y=None)[source]

Set whether automatic range will only pan (not scale) the view.

setAutoVisible(x=None, y=None)[source]

Set whether automatic range uses only visible data when determining the range to show.

setBackgroundColor(color)[source]

Set the background color of the ViewBox.

If color is None, then no background will be drawn.

Added in version 0.9.9

setBorder(*args, **kwds)[source]

Set the pen used to draw border around the view

If border is None, then no border will be drawn.

Added in version 0.9.10

See mkPen for arguments.

setDefaultPadding(padding=0.02)[source]

Sets the fraction of the data range that is used to pad the view range in when auto-ranging. By default, this fraction is 0.02.

setLimits(**kwds)[source]

Set limits that constrain the possible view ranges.

Panning limits. The following arguments define the region within the viewbox coordinate system that may be accessed by panning the view.

xMin

Minimum allowed x-axis value

xMax

Maximum allowed x-axis value

yMin

Minimum allowed y-axis value

yMax

Maximum allowed y-axis value

Scaling limits. These arguments prevent the view being zoomed in or out too far.

minXRange

Minimum allowed left-to-right span across the view.

maxXRange

Maximum allowed left-to-right span across the view.

minYRange

Minimum allowed top-to-bottom span across the view.

maxYRange

Maximum allowed top-to-bottom span across the view.

Added in version 0.9.9

setMouseEnabled(x=None, y=None)[source]

Set whether each axis is enabled for mouse interaction. x, y arguments must be True or False. This allows the user to pan/scale one axis of the view while leaving the other axis unchanged.

setMouseMode(mode)[source]

Set the mouse interaction mode. mode must be either ViewBox.PanMode or ViewBox.RectMode. In PanMode, the left mouse button pans the view and the right button scales. In RectMode, the left button draws a rectangle which updates the visible region (this mode is more suitable for single-button mice)

setRange(rect=None, xRange=None, yRange=None, padding=None, update=True, disableAutoRange=True)[source]

Set the visible range of the ViewBox. Must specify at least one of rect, xRange, or yRange.

Arguments:

rect

(QRectF) The full range that should be visible in the view box.

xRange

(min,max) The range that should be visible along the x-axis.

yRange

(min,max) The range that should be visible along the y-axis.

padding

(float) Expand the view by a fraction of the requested range. By default, this value is set between the default padding value and 0.1 depending on the size of the ViewBox.

update

(bool) If True, update the range of the ViewBox immediately. Otherwise, the update is deferred until before the next render.

disableAutoRange

(bool) If True, auto-ranging is diabled. Otherwise, it is left unchanged.

setState(state)[source]

Restore the state of this ViewBox. (see also getState)

Link this view’s X axis to another view. (see LinkView)

setXRange(min, max, padding=None, update=True)[source]

Set the visible X range of the view to [min, max]. The padding argument causes the range to be set larger by the fraction specified. (by default, this value is between the default padding and 0.1 depending on the size of the ViewBox)

Link this view’s Y axis to another view. (see LinkView)

setYRange(min, max, padding=None, update=True)[source]

Set the visible Y range of the view to [min, max]. The padding argument causes the range to be set larger by the fraction specified. (by default, this value is between the default padding and 0.1 depending on the size of the ViewBox)

showAxRect(ax, **kwargs)[source]

Set the visible range to the given rectangle Passes keyword arguments to setRange

targetRect()[source]

Return the region which has been requested to be visible. (this is not necessarily the same as the region that is actually visible– resizing and aspect ratio constraints can cause targetRect() and viewRect() to differ)

translateBy(t=None, x=None, y=None)[source]

Translate the view by t, which may be a Point or tuple (x, y).

Alternately, x or y may be specified independently, leaving the other axis unchanged (note that using a translation of 0 may still cause small changes due to floating-point error).

unregister()[source]

Remove this ViewBox from the list of linkable views. (see register())

viewPixelSize()[source]

Return the (width, height) of a screen pixel in view coordinates.

viewRange()[source]

Return a the view’s visible range as a list: [[xmin, xmax], [ymin, ymax]]

viewRect()[source]

Return a QRectF bounding the region visible within the ViewBox