QGraphicsWidget Class

Member Function Documentation

QGraphicsWidget::QGraphicsWidget(QGraphicsItem *parent = nullptr, Qt::WindowFlags wFlags = Qt::WindowFlags())

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

[slot] bool QGraphicsWidget::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.

[signal] void QGraphicsWidget::geometryChanged()

This signal gets emitted whenever the geometry is changed in setGeometry().

Note: Notifier signal for property geometry. Notifier signal for property size.

[virtual] QGraphicsWidget::~QGraphicsWidget()

Destroys the QGraphicsWidget instance.

QList<QAction *> QGraphicsWidget::actions() const

Returns the (possibly empty) list of this widget's actions.

See also insertAction(), removeAction(), QWidget::actions(), QAction::associatedWidgets(), and QAction::associatedGraphicsWidgets().

void QGraphicsWidget::addAction(QAction *action)

Appends the action action to this widget's list of actions.

All QGraphicsWidgets have a list of QActions, however they can be represented graphically in many different ways. The default use of the QAction list (as returned by actions()) is to create a context QMenu.

A QGraphicsWidget should only have one of each action and adding an action it already has will not cause the same action to be in the widget twice.

See also removeAction(), insertAction(), actions(), and QWidget::addAction().

void QGraphicsWidget::addActions(const QList<QAction *> &actions)

Appends the actions actions to this widget's list of actions.

See also removeAction(), QMenu, addAction(), and QWidget::addActions().

void QGraphicsWidget::adjustSize()

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

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

See also effectiveSizeHint() and Qt::MinimumSize.

[override virtual] QRectF QGraphicsWidget::boundingRect() const

Reimplements: QGraphicsItem::boundingRect() const.

[virtual protected] void QGraphicsWidget::changeEvent(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.

[virtual protected] void QGraphicsWidget::closeEvent(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.

[override virtual protected] bool QGraphicsWidget::event(QEvent *event)

Reimplements: QGraphicsObject::event(QEvent *ev).

Handles the event. QGraphicsWidget handles the following events:

[override virtual protected] void QGraphicsWidget::focusInEvent(QFocusEvent *event)

Reimplements: QGraphicsItem::focusInEvent(QFocusEvent *event).

[virtual protected] bool QGraphicsWidget::focusNextPrevChild(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().

[override virtual protected] void QGraphicsWidget::focusOutEvent(QFocusEvent *event)

Reimplements: QGraphicsItem::focusOutEvent(QFocusEvent *event).

QGraphicsWidget *QGraphicsWidget::focusWidget() const

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 widget has input focus, nullptr is returned.

See also QGraphicsItem::focusItem() and QWidget::focusWidget().

[override virtual] void QGraphicsWidget::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const

Reimplements: QGraphicsLayoutItem::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const.

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

See also setContentsMargins().

void QGraphicsWidget::getWindowFrameMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const

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

See also setWindowFrameMargins() and windowFrameRect().

[virtual protected] void QGraphicsWidget::grabKeyboardEvent(QEvent *event)

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

See also grabKeyboard() and grabMouse().

[virtual protected] void QGraphicsWidget::grabMouseEvent(QEvent *event)

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

See also grabMouse() and grabKeyboard().

int QGraphicsWidget::grabShortcut(const QKeySequence &sequence, Qt::ShortcutContext context = Qt::WindowShortcut)

Adds a shortcut to Qt's shortcut system that watches for the given key sequence in the given context. If the context is Qt::ApplicationShortcut, the shortcut applies to the application as a whole. Otherwise, it is either local to this widget, Qt::WidgetShortcut, or to the window itself, Qt::WindowShortcut. For widgets that are not part of a window (i.e., top-level widgets and their children), Qt::WindowShortcut shortcuts apply to the scene.

If the same key sequence has been grabbed by several widgets, when the key sequence occurs a QEvent::Shortcut event is sent to all the widgets to which it applies in a non-deterministic order, but with the ``ambiguous'' flag set to true.

See also releaseShortcut(), setShortcutEnabled(), and QWidget::grabShortcut().

[virtual protected] void QGraphicsWidget::hideEvent(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.

[override virtual protected] void QGraphicsWidget::hoverLeaveEvent(QGraphicsSceneHoverEvent *event)

Reimplements: QGraphicsItem::hoverLeaveEvent(QGraphicsSceneHoverEvent *event).

[override virtual protected] void QGraphicsWidget::hoverMoveEvent(QGraphicsSceneHoverEvent *event)

Reimplements: QGraphicsItem::hoverMoveEvent(QGraphicsSceneHoverEvent *event).

[virtual protected] void QGraphicsWidget::initStyleOption(QStyleOption *option) const

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.

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

void QGraphicsWidget::insertAction(QAction *before, QAction *action)

Inserts the action action to this widget's list of actions, before the action before. It appends the action if before is nullptr or before is not a valid action for this widget.

A QGraphicsWidget should only have one of each action.

See also removeAction(), addAction(), QMenu, actions(), and QWidget::insertActions().

void QGraphicsWidget::insertActions(QAction *before, const QList<QAction *> &actions)

Inserts the actions actions to this widget's list of actions, before the action before. It appends the action if before is nullptr or before is not a valid action for this widget.

A QGraphicsWidget can have at most one of each action.

See also removeAction(), QMenu, insertAction(), and QWidget::insertActions().

bool QGraphicsWidget::isActiveWindow() const

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(), QGraphicsScene::setActiveWindow(), and isActive().

[override virtual protected] QVariant QGraphicsWidget::itemChange(QGraphicsItem::GraphicsItemChange change, const QVariant &value)

Reimplements: QGraphicsItem::itemChange(QGraphicsItem::GraphicsItemChange change, const QVariant &value).

QGraphicsWidget uses the base implementation of this function to catch and deliver events related to state changes in the item. Because of this, it is very important that subclasses call the base implementation.

change specifies the type of change, and value is the new value.

For example, QGraphicsWidget uses ItemVisibleChange to deliver Show and Hide events, ItemPositionHasChanged to deliver Move events, and ItemParentChange both to deliver ParentChange events, and for managing the focus chain.

QGraphicsWidget enables the ItemSendsGeometryChanges flag by default in order to track position changes.

See also QGraphicsItem::itemChange().

QGraphicsLayout *QGraphicsWidget::layout() const

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

Note: Getter function for property layout.

See also setLayout().

[virtual protected] void QGraphicsWidget::moveEvent(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.

[override virtual] void QGraphicsWidget::paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr)

Reimplements: QGraphicsItem::paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget).

[virtual] void QGraphicsWidget::paintWindowFrame(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr)

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

[virtual protected] void QGraphicsWidget::polishEvent()

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.

QRectF QGraphicsWidget::rect() const

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

See also setGeometry() and resize().

void QGraphicsWidget::releaseShortcut(int id)

Removes the shortcut with the given id from Qt's shortcut system. The widget will no longer receive QEvent::Shortcut events for the shortcut's key sequence (unless it has other shortcuts with the same key sequence).

See also grabShortcut(), setShortcutEnabled(), and QWidget::releaseShortcut().

void QGraphicsWidget::removeAction(QAction *action)

Removes the action action from this widget's list of actions.

See also insertAction(), actions(), insertAction(), and QWidget::removeAction().

void QGraphicsWidget::resize(qreal w, qreal h)

This is an overloaded function.

Constructs a resize with the given width (w) and height (h). This convenience function is equivalent to calling resize(QSizeF(w, h)).

Note: Setter function for property size.

See also setGeometry() and setTransform().

[virtual protected] void QGraphicsWidget::resizeEvent(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().

[override virtual protected] bool QGraphicsWidget::sceneEvent(QEvent *event)

Reimplements: QGraphicsItem::sceneEvent(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.

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

See also QGraphicsItem::sceneEvent().

void QGraphicsWidget::setAttribute(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().

[since 5.14] void QGraphicsWidget::setContentsMargins(QMarginsF margins)

Sets the widget's contents margins to margins.

Contents margins are used by the assigned layout to define the placement of subwidgets and layouts. Margins are particularly 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.

This function was introduced in Qt 5.14.

See also getContentsMargins() and setGeometry().

void QGraphicsWidget::setContentsMargins(qreal left, qreal top, qreal right, qreal bottom)

This is an overloaded function.

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

void QGraphicsWidget::setGeometry(qreal x, qreal y, qreal w, qreal h)

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

Note: Setter function for property geometry.

See also geometry() and resize().

void QGraphicsWidget::setLayout(QGraphicsLayout *layout)

Sets the layout for this widget to layout. Any existing layout manager is deleted before the new layout is assigned. If layout is nullptr, 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.

Note: Setter function for property layout.

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

void QGraphicsWidget::setShortcutAutoRepeat(int id, bool enabled = true)

If enabled is true, auto repeat of the shortcut with the given id is enabled; otherwise it is disabled.

See also grabShortcut(), releaseShortcut(), and QWidget::setShortcutAutoRepeat().

void QGraphicsWidget::setShortcutEnabled(int id, bool enabled = true)

If enabled is true, the shortcut with the given id is enabled; otherwise the shortcut is disabled.

See also grabShortcut(), releaseShortcut(), and QWidget::setShortcutEnabled().

void QGraphicsWidget::setStyle(QStyle *style)

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

If no style is assigned, or style is nullptr, 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 nullptr; otherwise it clears the attribute.

See also style().

[static] void 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 nullptr, 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 nullptr, 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 in Widgets.

[since 5.14] void QGraphicsWidget::setWindowFrameMargins(QMarginsF margins)

Sets the widget's window frame margins to margins. 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.

This function was introduced in Qt 5.14.

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

void QGraphicsWidget::setWindowFrameMargins(qreal left, qreal top, qreal right, qreal bottom)

This is an overloaded function.

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

[override virtual] QPainterPath QGraphicsWidget::shape() const

Reimplements: QGraphicsItem::shape() const.

[virtual protected] void QGraphicsWidget::showEvent(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.

[override virtual protected] QSizeF QGraphicsWidget::sizeHint(Qt::SizeHint which, const QSizeF &constraint = QSizeF()) const

Reimplements: QGraphicsLayoutItem::sizeHint(Qt::SizeHint which, const QSizeF &constraint) const.

QStyle *QGraphicsWidget::style() const

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(Qt::WidgetAttribute attribute) const

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

See also setAttribute().

[override virtual] int QGraphicsWidget::type() const

Reimplements: QGraphicsItem::type() const.

[virtual protected] void QGraphicsWidget::ungrabKeyboardEvent(QEvent *event)

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

See also ungrabKeyboard() and ungrabMouse().

[virtual protected] void QGraphicsWidget::ungrabMouseEvent(QEvent *event)

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

See also ungrabMouse() and ungrabKeyboard().

void QGraphicsWidget::unsetWindowFrameMargins()

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

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

[override virtual protected] void QGraphicsWidget::updateGeometry()

Reimplements: QGraphicsLayoutItem::updateGeometry().

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.

See also QGraphicsLayout::invalidate().

[virtual protected] bool QGraphicsWidget::windowFrameEvent(QEvent *event)

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

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

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

QRectF QGraphicsWidget::windowFrameRect() const

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

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

[virtual protected] Qt::WindowFrameSection QGraphicsWidget::windowFrameSectionAt(const QPointF &pos) const

Returns the window frame section at position pos, or Qt::NoSection 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.

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

Qt::WindowType QGraphicsWidget::windowType() const

Returns the widgets window type.

See also windowFlags(), isWindow(), and isPanel().