|  | Home · All Classes · Modules

# QGraphicsWidget Class Reference
[QtGui module]

The QGraphicsWidget class is the base class for all widget items in a QGraphicsScene. More...

Inherits QObject, QGraphicsItem and QGraphicsLayoutItem.

Inherited by QGraphicsProxyWidget.

### Methods

- __init__ (self, QGraphicsItem parent = None, Qt.WindowFlags wFlags = 0)
- adjustSize (self)
- QRectF boundingRect (self)
- changeEvent (self, QEvent event)
- QObject-list children (self)
- bool close (self)
- closeEvent (self, QCloseEvent event)
- bool event (self, QEvent event)
- focusInEvent (self, QFocusEvent event)
- bool focusNextPrevChild (self, bool next)
- focusOutEvent (self, QFocusEvent event)
- Qt.FocusPolicy focusPolicy (self)
- QGraphicsWidget focusWidget (self)
- QFont font (self)
- (float left, float top, float right, float bottom) getContentsMargins (self)
- (float left, float top, float right, float bottom) getWindowFrameMargins (self)
- grabKeyboardEvent (self, QEvent event)
- grabMouseEvent (self, QEvent event)
- hideEvent (self, QHideEvent event)
- hoverLeaveEvent (self, QGraphicsSceneHoverEvent event)
- hoverMoveEvent (self, QGraphicsSceneHoverEvent event)
- initStyleOption (self, QStyleOption option)
- bool isActiveWindow (self)
- QVariant itemChange (self, QGraphicsItem.GraphicsItemChange change, QVariant value)
- QGraphicsLayout layout (self)
- Qt.LayoutDirection layoutDirection (self)
- moveEvent (self, QGraphicsSceneMoveEvent event)
- paint (self, QPainter painter, QStyleOptionGraphicsItem option, QWidget widget = None)
- paintWindowFrame (self, QPainter painter, QStyleOptionGraphicsItem option, QWidget widget = None)
- QPalette palette (self)
- polishEvent (self)
- QVariant propertyChange (self, QString propertyName, QVariant value)
- QRectF rect (self)
- resize (self, QSizeF size)
- resize (self, float w, float h)
- resizeEvent (self, QGraphicsSceneResizeEvent event)
- bool sceneEvent (self, QEvent event)
- setAttribute (self, Qt.WidgetAttribute attribute, bool on = True)
- setContentsMargins (self, float left, float top, float right, float bottom)
- setFocusPolicy (self, Qt.FocusPolicy policy)
- setFont (self, QFont font)
- setGeometry (self, QRectF rect)
- setGeometry (self, float ax, float ay, float aw, float ah)
- setLayout (self, QGraphicsLayout layout)
- setLayoutDirection (self, Qt.LayoutDirection direction)
- setPalette (self, QPalette palette)
- setStyle (self, QStyle style)
- setWindowFlags (self, Qt.WindowFlags wFlags)
- setWindowFrameMargins (self, float left, float top, float right, float bottom)
- setWindowTitle (self, QString title)
- QPainterPath shape (self)
- showEvent (self, QShowEvent event)
- QSizeF size (self)
- QSizeF sizeHint (self, Qt.SizeHint which, QSizeF constraint = QSizeF())
- QStyle style (self)
- bool testAttribute (self, Qt.WidgetAttribute attribute)
- int type (self)
- ungrabKeyboardEvent (self, QEvent event)
- ungrabMouseEvent (self, QEvent event)
- unsetLayoutDirection (self)
- unsetWindowFrameMargins (self)
- updateGeometry (self)
- Qt.WindowFlags windowFlags (self)
- bool windowFrameEvent (self, QEvent e)
- QRectF windowFrameGeometry (self)
- QRectF windowFrameRect (self)
- Qt.WindowFrameSection windowFrameSectionAt (self, QPointF pos)
- QString windowTitle (self)
- Qt.WindowType windowType (self)

### Static Methods

- setTabOrder (QGraphicsWidget first, QGraphicsWidget second)

## Detailed Description

The QGraphicsWidget class is the base class for all widget items in a QGraphicsScene.

QGraphicsWidget is an extended base item that provides extra functionality over QGraphicsItem. It is similar to QWidget in many ways:

- Provides a palette, a font and a style().
- Has a defined geometry().
- Supports layouts with setLayout() and layout().

Unlike QGraphicsItem, QGraphicsWidget is not an abstract class; you can create instances of a QGraphicsWidget without having to subclass it. This approach is useful for widgets that only serve the purpose of organizing child widgets into a layout.

QGraphicsWidget can be used as a base item for your own custom item if you require advanced input focus handling, e.g., tab focus and activation, or layouts.

Since QGraphicsWidget resembles QWidget and has similar API, it is easier to port a widget from QWidget to QGraphicsWidget, instead of QGraphicsItem.

Note: QWidget-based widgets can be directly embedded into a QGraphicsScene using QGraphicsProxyWidget.

Noticeable differences between QGraphicsWidget and QWidget are:

QGraphicsWidget | QWidget
--- | ---
Coordinates and geometry are defined with qreals (doubles or floats, depending on the platform). | QWidget uses integer geometry (QPoint, QRect).
The widget is already visible by default; you do not have to call show() to display the widget. | QWidget is hidden by default until you call show().
A subset of widget attributes are supported. | All widget attributes are supported.
A top-level item's style defaults to QGraphicsScene.style | A top-level widget's style defaults to QApplication.style
Graphics View provides a custom drag and drop framework, different from QWidget. | Standard drag and drop framework.
Widget items do not support modality. | Full modality support.

QGraphicsWidget supports a subset of Qt's widget attributes, (Qt.WidgetAttribute), as shown in the table below. Any attributes not listed in this table are unsupported, or otherwise unused.

Widget Attribute | Usage
--- | ---
Qt.WA_SetLayoutDirection | Set by setLayoutDirection(), cleared by unsetLayoutDirection(). You can test this attribute to check if the widget has been explicitly assigned a layoutDirection. If the attribute is not set, the layoutDirection() is inherited.
Qt.WA_RightToLeft | Toggled by setLayoutDirection(). Inherited from the parent/scene. If set, the widget's layout will order horizontally arranged widgets from right to left.
Qt.WA_SetStyle | Set and cleared by setStyle(). If this attribute is set, the widget has been explicitly assigned a style. If it is unset, the widget will use the scene's or the application's style.
Qt.WA_Resized | Set by setGeometry() and resize().

Although QGraphicsWidget inherits from both QObject and QGraphicsItem, you should use the functions provided by QGraphicsItem, not QObject, to manage the relationships between parent and child items. These functions control the stacking order of items as well as their ownership.

Note: The QObject.parent() should always return 0 for QGraphicsWidgets, but this policy is not strictly defined.

See also QGraphicsProxyWidget, QGraphicsItem, and Widgets and Layouts.

## Method Documentation

### QGraphicsWidget.__init__ (self, QGraphicsItem parent = None, Qt.WindowFlags wFlags = 0)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

Constructs a QGraphicsWidget instance. The optional parent argument is passed to QGraphicsItem's constructor. The optional wFlags argument specifies the widget's window flags (e.g., whether the widget should be a window, a tool, a popup, etc).

### QGraphicsWidget.adjustSize (self)

Adjusts the size of the widget to its effective minimum size hint.

This function is called implicitly when the item is shown for the first time.

See also effectiveSizeHint() and Qt.MinimumSize.

### QRectF QGraphicsWidget.boundingRect (self)

### QGraphicsWidget.changeEvent (self, QEvent event)

This event handler can be reimplemented to handle state changes.

The state being changed in this event can be retrieved through event.

Change events include: QEvent.ActivationChange, QEvent.EnabledChange, QEvent.FontChange, QEvent.StyleChange, QEvent.PaletteChange, QEvent.ParentChange, QEvent.LayoutDirectionChange, and QEvent.ContentsRectChange.

### QObject-list QGraphicsWidget.children (self)

This function returns the same value as QObject.children(). It's provided to differentiate between the obsolete member QGraphicsItem.children() and QObject.children(). QGraphicsItem now provides childItems() instead.

### bool QGraphicsWidget.close (self)

This method is also a Qt slot with the C++ signature `bool close()`.

Call this function to close the widget.

Returns true if the widget was closed; otherwise returns false. This slot will first send a QCloseEvent to the widget, which may or may not accept the event. If the event was ignored, nothing happens. If the event was accepted, it will hide() the widget.

If the widget has the Qt.WA_DeleteOnClose attribute set it will be deleted.

### QGraphicsWidget.closeEvent (self, QCloseEvent event)

This event handler, for event, can be reimplemented in a subclass to receive widget close events. The default implementation accepts the event.

See also close() and QCloseEvent.

### bool QGraphicsWidget.event (self, QEvent event)

### QGraphicsWidget.focusInEvent (self, QFocusEvent event)

### bool QGraphicsWidget.focusNextPrevChild (self, bool next)

Finds a new widget to give the keyboard focus to, as appropriate for Tab and Shift+Tab, and returns true if it can find a new widget; returns false otherwise. If next is true, this function searches forward; if next is false, it searches backward.

Sometimes, you will want to reimplement this function to provide special focus handling for your widget and its subwidgets. For example, a web browser might reimplement it to move its current active link forward or backward, and call the base implementation only when it reaches the last or first link on the page.

Child widgets call focusNextPrevChild() on their parent widgets, but only the window that contains the child widgets decides where to redirect focus. By reimplementing this function for an object, you gain control of focus traversal for all child widgets.

See also focusPolicy().

### QGraphicsWidget.focusOutEvent (self, QFocusEvent event)

### Qt.FocusPolicy QGraphicsWidget.focusPolicy (self)

### QGraphicsWidget QGraphicsWidget.focusWidget (self)

If this widget, a child or descendant of this widget currently has input focus, this function will return a pointer to that widget. If no descendant has input focus, 0 is returned.

See also QWidget.focusWidget().

### QFont QGraphicsWidget.font (self)

### (float left, float top, float right, float bottom) QGraphicsWidget.getContentsMargins (self)

Gets the widget's contents margins. The margins are stored in left, top, right and bottom, as pointers to qreals. Each argument can be omitted by passing 0.

Reimplemented from QGraphicsLayoutItem.

See also setContentsMargins().

### (float left, float top, float right, float bottom) QGraphicsWidget.getWindowFrameMargins (self)

Gets the widget's window frame margins. The margins are stored in left, top, right and bottom as pointers to qreals. Each argument can be omitted by passing 0.

See also setWindowFrameMargins() and windowFrameRect().

### QGraphicsWidget.grabKeyboardEvent (self, QEvent event)

This event handler, for event, can be reimplemented in a subclass to receive notifications for Qt.GrabKeyboard events.

See also grabKeyboard() and grabMouse().

### QGraphicsWidget.grabMouseEvent (self, QEvent event)

This event handler, for event, can be reimplemented in a subclass to receive notifications for Qt.GrabMouse events.

See also grabMouse() and grabKeyboard().

### QGraphicsWidget.hideEvent (self, QHideEvent event)

This event handler, for Hide events, is delivered after the widget has been hidden, for example, setVisible(false) has been called for the widget or one of its ancestors when the widget was previously shown.

You can reimplement this event handler to detect when your widget is hidden. Calling QEvent.accept() or QEvent.ignore() on event has no effect.

See also showEvent(), QWidget.hideEvent(), and ItemVisibleChange.

### QGraphicsWidget.hoverLeaveEvent (self, QGraphicsSceneHoverEvent event)

### QGraphicsWidget.hoverMoveEvent (self, QGraphicsSceneHoverEvent event)

### QGraphicsWidget.initStyleOption (self, QStyleOption option)

Populates a style option object for this widget based on its current state, and stores the output in option. The default implementation populates option with the following properties.

state & QStyle.State_Enabled | Corresponds to QGraphicsItem.isEnabled().
state & QStyle.State_HasFocus | Corresponds to QGraphicsItem.hasFocus().
state & QStyle.State_MouseOver | Corresponds to QGraphicsItem.isUnderMouse().
direction | Corresponds to QGraphicsWidget.layoutDirection().
rect | Corresponds to QGraphicsWidget.rect().toRect().
palette | Corresponds to QGraphicsWidget.palette().
fontMetrics | Corresponds to QFontMetrics(QGraphicsWidget.font()).

Subclasses of QGraphicsWidget should call the base implementation, and then test the type of option using qstyleoption_cast<>() or test QStyleOption.Type before storing widget-specific options.

For example:

             void MyGroupBoxWidget.initStyleOption(QStyleOption *option) const
             {
                 QGraphicsWidget.initStyleOption(option);
                 if (QStyleOptionGroupBox *box = qstyleoption_cast<QStyleOptionGroupBox *>(option)) {
                     // Add group box specific state.
                     box->flat = isFlat();
                     ...
                 }
             }

See also QStyleOption.initFrom().

### bool QGraphicsWidget.isActiveWindow (self)

Returns true if this widget's window is in the active window, or if the widget does not have a window but is in an active scene (i.e., a scene that currently has focus).

The active window is the window that either contains a child widget that currently has input focus, or that itself has input focus.

See also QGraphicsScene.activeWindow() and QGraphicsScene.setActiveWindow().

### QVariant QGraphicsWidget.itemChange (self, QGraphicsItem.GraphicsItemChange change, QVariant value)

### QGraphicsLayout QGraphicsWidget.layout (self)

Returns this widget's layout, or 0 if no layout is currently managing this widget.

See also setLayout().

### Qt.LayoutDirection QGraphicsWidget.layoutDirection (self)

### QGraphicsWidget.moveEvent (self, QGraphicsSceneMoveEvent event)

This event handler, for GraphicsSceneMove events, is delivered after the widget has moved (e.g., its local position has changed).

This event is only delivered when the item is moved locally. Calling setTransform() or moving any of the item's ancestors does not affect the item's local position.

You can reimplement this event handler to detect when your widget has moved. Calling QEvent.accept() or QEvent.ignore() on event has no effect.

See also ItemPositionChange and ItemPositionHasChanged.

### QGraphicsWidget.paint (self, QPainter painter, QStyleOptionGraphicsItem option, QWidget widget = None)

### QGraphicsWidget.paintWindowFrame (self, QPainter painter, QStyleOptionGraphicsItem option, QWidget widget = None)

This virtual function is called by QGraphicsScene to draw the window frame for windows using painter, option, and widget, in local coordinates. The base implementation uses the current style to render the frame and title bar.

You can reimplement this function in a subclass of QGraphicsWidget to provide custom rendering of the widget's window frame.

See also QGraphicsItem.paint().

### QPalette QGraphicsWidget.palette (self)

### QGraphicsWidget.polishEvent (self)

This event is delivered to the item by the scene at some point after it has been constructed, but before it is shown or otherwise accessed through the scene. You can use this event handler to do last-minute initializations of the widget which require the item to be fully constructed.

The base implementation does nothing.

### QVariant QGraphicsWidget.propertyChange (self, QString propertyName, QVariant value)

### QRectF QGraphicsWidget.rect (self)

Returns the item's local rect as a QRectF. This function is equivalent to QRectF(QPointF(), size()).

See also setGeometry() and resize().

### QGraphicsWidget.resize (self, QSizeF size)

### QGraphicsWidget.resize (self, float w, float h)

### QGraphicsWidget.resizeEvent (self, QGraphicsSceneResizeEvent event)

This event handler, for GraphicsSceneResize events, is delivered after the widget has been resized (i.e., its local size has changed). event contains both the old and the new size.

This event is only delivered when the widget is resized locally; calling setTransform() on the widget or any of its ancestors or view, does not affect the widget's local size.

You can reimplement this event handler to detect when your widget has been resized. Calling QEvent.accept() or QEvent.ignore() on event has no effect.

See also geometry() and setGeometry().

### bool QGraphicsWidget.sceneEvent (self, QEvent event)

QGraphicsWidget's implementation of sceneEvent() simply passes event to QGraphicsWidget.event(). You can handle all events for your widget in event() or in any of the convenience functions; you should not have to reimplement this function in a subclass of QGraphicsWidget.

Reimplemented from QGraphicsItem.

See also QGraphicsItem.sceneEvent().

### QGraphicsWidget.setAttribute (self, Qt.WidgetAttribute attribute, bool on = True)

If on is true, this function enables attribute; otherwise attribute is disabled.

See the class documentation for QGraphicsWidget for a complete list of which attributes are supported, and what they are for.

See also testAttribute() and QWidget.setAttribute().

### QGraphicsWidget.setContentsMargins (self, float left, float top, float right, float bottom)

Sets the widget's contents margins to left, top, right and bottom.

Contents margins are used by the assigned layout to define the placement of subwidgets and layouts. Margins are particularily useful for widgets that constrain subwidgets to only a section of its own geometry. For example, a group box with a layout will place subwidgets inside its frame, but below the title.

Changing a widget's contents margins will always trigger an update(), and any assigned layout will be activated automatically. The widget will then receive a ContentsRectChange event.

See also getContentsMargins() and setGeometry().

### QGraphicsWidget.setFocusPolicy (self, Qt.FocusPolicy policy)

### QGraphicsWidget.setFont (self, QFont font)

### QGraphicsWidget.setGeometry (self, QRectF rect)

Sets the item's geometry to rect. The item's position and size are modified as a result of calling this function. The item is first moved, then resized.

A side effect of calling this function is that the widget will receive a move event and a resize event. Also, if the widget has a layout assigned, the layout will activate.

Reimplemented from QGraphicsLayoutItem.

See also geometry() and resize().

### QGraphicsWidget.setGeometry (self, float ax, float ay, float aw, float ah)

This is an overloaded member function, provided for convenience.

This convenience function is equivalent to calling setGeometry(QRectF( x, y, w, h)).

See also geometry() and resize().

### QGraphicsWidget.setLayout (self, QGraphicsLayout layout)

The layout argument has it's ownership transferred to Qt.

Sets the layout for this widget to layout. Any existing layout manager is deleted before the new layout is assigned. If layout is 0, the widget is left without a layout. Existing subwidgets' geometries will remain unaffected.

All widgets that are currently managed by layout or all of its sublayouts, are automatically reparented to this item. The layout is then invalidated, and the child widget geometries are adjusted according to this item's geometry() and contentsMargins(). Children who are not explicitly managed by layout remain unaffected by the layout after it has been assigned to this widget.

QGraphicsWidget takes ownership of layout.

See also layout(), QGraphicsLinearLayout.addItem(), and QGraphicsLayout.invalidate().

### QGraphicsWidget.setLayoutDirection (self, Qt.LayoutDirection direction)

### QGraphicsWidget.setPalette (self, QPalette palette)

### QGraphicsWidget.setStyle (self, QStyle style)

Sets the widget's style to style. QGraphicsWidget does not take ownership of style.

If no style is assigned, or style is 0, the widget will use QGraphicsScene.style() (if this has been set). Otherwise the widget will use QApplication.style().

This function sets the Qt.WA_SetStyle attribute if style is not 0; otherwise it clears the attribute.

See also style().

### QGraphicsWidget.setTabOrder (QGraphicsWidget first, QGraphicsWidget second)

Moves the second widget around the ring of focus widgets so that keyboard focus moves from the first widget to the second widget when the Tab key is pressed.

Note that since the tab order of the second widget is changed, you should order a chain like this:

             setTabOrder(a, b); // a to b
             setTabOrder(b, c); // a to b to c
             setTabOrder(c, d); // a to b to c to d

not like this:

             // WRONG
             setTabOrder(c, d); // c to d
             setTabOrder(a, b); // a to b AND c to d
             setTabOrder(b, c); // a to b to c, but not c to d

If first is 0, this indicates that second should be the first widget to receive input focus should the scene gain Tab focus (i.e., the user hits Tab so that focus passes into the scene). If second is 0, this indicates that first should be the first widget to gain focus if the scene gained BackTab focus.

By default, tab order is defined implicitly using widget creation order.

See also focusPolicy and Keyboard Focus.

### QGraphicsWidget.setWindowFlags (self, Qt.WindowFlags wFlags)

### QGraphicsWidget.setWindowFrameMargins (self, float left, float top, float right, float bottom)

Sets the widget's window frame margins to left, top, right and bottom. The default frame margins are provided by the style, and they depend on the current window flags.

If you would like to draw your own window decoration, you can set your own frame margins to override the default margins.

See also unsetWindowFrameMargins(), getWindowFrameMargins(), and windowFrameRect().

### QGraphicsWidget.setWindowTitle (self, QString title)

### QPainterPath QGraphicsWidget.shape (self)

### QGraphicsWidget.showEvent (self, QShowEvent event)

This event handler, for Show events, is delivered before the widget has been shown, for example, setVisible(true) has been called for the widget or one of its ancestors when the widget was previously hidden.

You can reimplement this event handler to detect when your widget is shown. Calling QEvent.accept() or QEvent.ignore() on event has no effect.

See also hideEvent(), QWidget.showEvent(), and ItemVisibleChange.

### QSizeF QGraphicsWidget.size (self)

### QSizeF QGraphicsWidget.sizeHint (self, Qt.SizeHint which, QSizeF constraint = QSizeF())

### QStyle QGraphicsWidget.style (self)

Returns a pointer to the widget's style. If this widget does not have any explicitly assigned style, the scene's style is returned instead. In turn, if the scene does not have any assigned style, this function returns QApplication.style().

See also setStyle().

### bool QGraphicsWidget.testAttribute (self, Qt.WidgetAttribute attribute)

Returns true if attribute is enabled for this widget; otherwise, returns false.

See also setAttribute().

### int QGraphicsWidget.type (self)

### QGraphicsWidget.ungrabKeyboardEvent (self, QEvent event)

This event handler, for event, can be reimplemented in a subclass to receive notifications for Qt.UngrabKeyboard events.

See also ungrabKeyboard() and ungrabMouse().

### QGraphicsWidget.ungrabMouseEvent (self, QEvent event)

This event handler, for event, can be reimplemented in a subclass to receive notifications for Qt.UngrabMouse events.

See also ungrabMouse() and ungrabKeyboard().

### QGraphicsWidget.unsetLayoutDirection (self)

### QGraphicsWidget.unsetWindowFrameMargins (self)

Resets the window frame margins to the default value, provided by the style.

See also setWindowFrameMargins(), getWindowFrameMargins(), and windowFrameRect().

### QGraphicsWidget.updateGeometry (self)

If this widget is currently managed by a layout, this function notifies the layout that the widget's size hints have changed and the layout may need to resize and reposition the widget accordingly.

Call this function if the widget's sizeHint() has changed.

Reimplemented from QGraphicsLayoutItem.

See also QGraphicsLayout.invalidate().

### Qt.WindowFlags QGraphicsWidget.windowFlags (self)

### bool QGraphicsWidget.windowFrameEvent (self, QEvent e)

This event handler, for event, receives events for the window frame if this widget is a window. Its base implementation provides support for default window frame interaction such as moving, resizing, etc.

You can reimplement this handler in a subclass of QGraphicsWidget to provide your own custom window frame interaction support.

Returns true if event has been recognized and processed; otherwise, returns false.

See also event().

### QRectF QGraphicsWidget.windowFrameGeometry (self)

Returns the widget's geometry in parent coordinates including any window frame.

See also windowFrameRect(), getWindowFrameMargins(), and setWindowFrameMargins().

### QRectF QGraphicsWidget.windowFrameRect (self)

Returns the widget's local rect including any window frame.

See also windowFrameGeometry(), getWindowFrameMargins(), and setWindowFrameMargins().

### Qt.WindowFrameSection QGraphicsWidget.windowFrameSectionAt (self, QPointF pos)

Returns the window frame section at position pos, or Qt.NoWindowFrameSection if there is no window frame section at this position.

This function is used in QGraphicsWidget's base implementation for window frame interaction.

You can reimplement this function if you want to customize how a window can be interactively moved or resized. For instance, if you only want to allow a window to be resized by the bottom right corner, you can reimplement this function to return Qt.NoSection for all sections except Qt.BottomRightSection.

This function was introduced in Qt 4.4.

See also windowFrameEvent(), paintWindowFrame(), and windowFrameGeometry().

### QString QGraphicsWidget.windowTitle (self)

### Qt.WindowType QGraphicsWidget.windowType (self)

Returns the widgets window type.