QWidget Class

The QWidget class is the base class of all user interface objects. More…

List of all members, including inherited members

Public Functions

Reimplemented Public Functions

Public Slots

Signals

Protected Functions

Reimplemented Protected Functions

Detailed Description

A widget is a rectangle that paints itself and receives events from the window system: mouse, keyboard and focus events, and paint events when part of it needs to be drawn. A widget without a parent is a window; a widget with a parent is a child that is drawn inside it.

QWidget window;
window.setWindowTitle("Hello");
QVBoxLayout *layout = new QVBoxLayout(&window);
layout->addWidget(new QLabel("Hello, widgets"));
layout->addWidget(new QPushButton("OK"));
window.show();

To make your own widget, subclass QWidget and reimplement paintEvent(), which paints with a QPainter on the widget, and the event handlers you need. Call update() when the widget has to be painted again.

The widgets of a window are painted into the backing store of one native window, so child widgets are not native windows of their own.

See also QWindow, QPainter, QLayout and QApplication.

Differences from Qt

Member Function Documentation

[explicit] QWidget::QWidget(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

Constructs a widget that is a child of parent, or a window if parent is nullptr or the window flags f have Qt::Window. A window with a parent, such as a dialog, has a window of its own; it is deleted with its parent and the window system keeps it above the window of its parent. A QApplication must exist. The widget is hidden until show() is called, or until its parent is shown if it is a child.

See also windowFlags().

[override] QWidget::~QWidget()

Destroys the widget, its child widgets and its layout. A window is closed without a close event.

[virtual, protected] void QWidget::actionEvent(QActionEvent *event)

Handles the action event: an action of the widget has been added, removed or changed. The default does nothing; QMenu and QMenuBar update what they show. When an action is deleted, the event has no action.

See also addAction() and QActionEvent.

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

Returns the actions that the widget has, in order. A menu shows them, and an action with a shortcut works when the window of the widget has the focus.

See also addAction(), insertAction() and removeAction().

void QWidget::activateWindow()

Asks the window system to make the window that contains the widget the active window.

See also isActiveWindow().

void QWidget::addAction(QAction *action)

Adds action at the end of the actions of the widget. The widget does not own the action.

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

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

Adds all the actions at the end of the actions of the widget.

See also addAction().

void QWidget::adjustSize()

Resizes the widget to its size hint (at least its minimum size hint). Nothing happens if the widget has no size hint.

See also sizeHint().

bool QWidget::autoFillBackground() const

Returns whether the widget paints its background with the Window color of its palette before painting itself. It is always done for windows. The default is false.

See also setAutoFillBackground().

[virtual, protected] void QWidget::changeEvent(QEvent *event)

Handles the change event, which is of the type EnabledChange, FontChange, PaletteChange, StyleChange, ParentChange, WindowTitleChange, WindowActivate, WindowDeactivate or MouseTrackingChange. The default repaints the widget, and lays it out again if its size hint may have changed.

QWidget * QWidget::childAt(const QPoint &pos) const

Returns the visible child widget at pos, in the coordinates of the widget. It is the deepest one that contains the point. Returns nullptr if there is none.

QWidget * QWidget::childAt(int x, int y) const

This is an overloaded function.

Returns the child widget at (x, y).

[slot] void QWidget::clearFocus()

Takes the keyboard focus away from the widget, if it has it.

See also setFocus().

[slot] bool QWidget::close()

Closes the widget. For a window this sends a close event, which the window can ignore, and returns whether the window closed. A child widget is hidden. The application quits when its last window is closed (see QGuiApplication::quitOnLastWindowClosed()).

See also closeEvent().

[virtual, protected] void QWidget::closeEvent(QCloseEvent *event)

Handles the close event event, sent when a window is asked to close. Call event->ignore() to keep it open. The default accepts the event.

See also close().

QCursor QWidget::cursor() const

Returns the cursor that shows while the mouse is over the widget: its own if setCursor() gave it one, otherwise that of the nearest ancestor that has one, and the standard arrow if none has.

See also setCursor() and unsetCursor().

[virtual, protected] void QWidget::enterEvent(QEnterEvent *event)

Handles the enter event: the mouse entered the widget. The default does nothing but repaint.

See also leaveEvent().

[override, protected] bool QWidget::event(QEvent *event)

Reimplements QObject::event().

[virtual, protected] void QWidget::focusInEvent(QFocusEvent *event)

Handles the focus-in event: the widget got the keyboard focus. The default does nothing but repaint.

bool QWidget::focusNextChild()

Moves the focus to the next widget; see focusNextPrevChild().

[virtual, protected] bool QWidget::focusNextPrevChild(bool next)

Moves the focus to the next widget in the window that accepts focus by tabbing, or to the previous one if next is false, and returns true if it did. The order is the one in which the widgets were created. The focus wraps around.

[virtual, protected] void QWidget::focusOutEvent(QFocusEvent *event)

Handles the focus-out event: the widget lost the keyboard focus. The default does nothing but repaint.

Qt::FocusPolicy QWidget::focusPolicy() const

Returns the focus policy of the widget, which is Qt::NoFocus by default.

See also setFocusPolicy().

bool QWidget::focusPreviousChild()

Moves the focus to the previous widget; see focusNextPrevChild().

QWidget * QWidget::focusWidget() const

Returns the widget that has the focus in the window that contains this widget, or nullptr.

const QFont & QWidget::font() const

Returns the font of the widget: the one set with setFont(), or else the one of its parent, or the application font.

See also setFont().

QFontMetrics QWidget::fontMetrics() const

Returns the metrics of the widget's font.

QRect QWidget::geometry() const

Returns the geometry of the widget. For a child widget it is relative to the parent; for a window it is in screen coordinates and excludes the window frame.

See also setGeometry() and rect().

bool QWidget::hasFocus() const

Returns true if the widget has the keyboard focus: it is the focus widget of an active window.

See also setFocus().

bool QWidget::hasMouseTracking() const

Returns whether mouse tracking is on.

See also setMouseTracking().

int QWidget::height() const

Returns the height of the widget.

[slot] void QWidget::hide()

Hides the widget. This is the same as setVisible(false).

See also show().

[virtual, protected] void QWidget::hideEvent(QHideEvent *event)

Handles the hide event: the widget has been hidden. The default does nothing.

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

Adds action in front of the action before, or at the end if before is nullptr or is not an action of the widget. An action that the widget has already is moved. The widget gets a QEvent::ActionAdded.

See also addAction() and removeAction().

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

Adds all the actions in front of the action before.

See also insertAction().

bool QWidget::isActiveWindow() const

Returns true if the window that contains the widget is the active window.

See also activateWindow().

bool QWidget::isEnabled() const

Returns true if the widget is enabled, which it is unless setEnabled(false) was called on it or on an ancestor. A disabled widget does not get mouse and keyboard events and is drawn with the disabled colors.

See also setEnabled().

bool QWidget::isHidden() const

Returns true if the widget is hidden: hide() was called, or it was not shown yet. This is not the same as the opposite of isVisible(), because a widget under a hidden parent is not visible but not hidden.

See also isVisible().

bool QWidget::isModal() const

Returns true if windowModality() is not Qt::NonModal.

See also setWindowModality().

bool QWidget::isVisible() const

Returns true if the widget is shown: it, and all its ancestors, are shown, and the window is visible.

See also isHidden() and setVisible().

bool QWidget::isWindow() const

Returns true if the widget is a window: it has no parent, or its window flags have Qt::Window.

See also window() and windowFlags().

bool QWidget::isWindowModified() const

Returns whether the window has changes that are not saved.

See also setWindowModified().

[virtual, protected] void QWidget::keyPressEvent(QKeyEvent *event)

Handles the key press event. Only the widget that has the focus gets it. The default ignores the event, so that the parent gets it.

[virtual, protected] void QWidget::keyReleaseEvent(QKeyEvent *event)

Handles the key release event. The default ignores it.

QLayout * QWidget::layout() const

Returns the layout that manages the children of the widget, or nullptr.

See also setLayout().

[virtual, protected] void QWidget::leaveEvent(QEvent *event)

Handles the leave event: the mouse left the widget. The default does nothing but repaint.

See also enterEvent().

[slot] void QWidget::lower()

Lowers the widget below its siblings. Nothing happens for a window.

See also raise().

QPoint QWidget::mapFrom(const QWidget *parent, const QPoint &pos) const

Returns pos, a point in parent, which must be an ancestor, as a point in the widget.

QPoint QWidget::mapFromGlobal(const QPoint &pos) const

Returns pos, a point on the screen, as a point in the widget.

See also mapToGlobal().

QPoint QWidget::mapFromParent(const QPoint &pos) const

Returns pos, a point in the parent, as a point in the widget.

QPoint QWidget::mapTo(const QWidget *parent, const QPoint &pos) const

Returns pos, a point in the widget, as a point in parent, which must be an ancestor.

QPoint QWidget::mapToGlobal(const QPoint &pos) const

Returns pos, a point in the widget, as a point on the screen.

See also mapFromGlobal().

QPoint QWidget::mapToParent(const QPoint &pos) const

Returns pos, a point in the widget, as a point in its parent.

QSize QWidget::maximumSize() const

Returns the maximum size that was set with setMaximumSize(). It is very large by default.

[override, protected] int QWidget::metric(PaintDeviceMetric metric) const

Reimplements QPaintDevice::metric().

QSize QWidget::minimumSize() const

Returns the minimum size that was set with setMinimumSize(), (0, 0) by default. A layout never makes the widget smaller than its minimum size.

See also minimumSizeHint().

[virtual] QSize QWidget::minimumSizeHint() const

Returns the smallest size at which the widget is still usable. The default is the minimum size of the widget's layout, or an invalid size if there is none.

See also sizeHint().

[virtual, protected] void QWidget::mouseDoubleClickEvent(QMouseEvent *event)

Handles the double click event. The default calls mousePressEvent().

[virtual, protected] void QWidget::mouseMoveEvent(QMouseEvent *event)

Handles the mouse move event. The default ignores it. The widget gets it when a button is down, and when mouse tracking is on.

See also setMouseTracking().

[virtual, protected] void QWidget::mousePressEvent(QMouseEvent *event)

Handles the mouse press event. If the widget does not use the event, it should ignore it, which the default does, so that the parent gets it.

[virtual, protected] void QWidget::mouseReleaseEvent(QMouseEvent *event)

Handles the mouse release event. The default ignores it.

void QWidget::move(const QPoint &pos)

Moves the widget to pos in its parent, or on the screen for a window.

See also pos() and setGeometry().

void QWidget::move(int x, int y)

This is an overloaded function.

Moves the widget to (x, y).

[virtual, protected] void QWidget::moveEvent(QMoveEvent *event)

Handles the move event. The default does nothing.

See also move().

[override] QPaintEngine * QWidget::paintEngine() const

Reimplements QPaintDevice::paintEngine().

[virtual, protected] void QWidget::paintEvent(QPaintEvent *event)

Handles a paint event: paint the widget with a QPainter, at least the part that event names. Painting outside the widget or its visible part has no effect. The default does nothing.

See also update().

const QPalette & QWidget::palette() const

Returns the palette of the widget: the one set with setPalette(), or else the one of its parent, or the application palette.

See also setPalette().

QWidget * QWidget::parentWidget() const

Returns the parent widget, or nullptr for a window.

See also window().

QPoint QWidget::pos() const

Returns the position of the widget in its parent, or on the screen for a window.

See also move().

[slot] void QWidget::raise()

Raises the widget above its siblings, or asks the window system to put a window in front of the others.

See also lower().

QRect QWidget::rect() const

Returns the rectangle of the widget in its own coordinates: its size, with the top left corner at the origin.

[override, protected] QPaintDevice * QWidget::redirected(QPoint *offset) const

Reimplements QPaintDevice::redirected().

void QWidget::removeAction(QAction *action)

Removes action from the actions of the widget. The widget gets a QEvent::ActionRemoved.

See also addAction().

void QWidget::render(QPaintDevice *target, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion())

Paints the widget and its visible children on target, with the top left corner of the widget at targetOffset. Only sourceRegion of the widget is painted if it is not empty. The widget need not be shown: it is painted as it would look, at its current size, with its layout done, and a widget that is hidden with hide() is left out. A window has its background painted first.

The pixels of target are those of the device, so a QImage with a device pixel ratio of 2 gets a picture with twice as many pixels. Use it to take a picture of a widget:

QImage image(widget->size() * 2, QImage::Format_ARGB32_Premultiplied);
image.setDevicePixelRatio(2.0);
widget->render(&image);

See also QPainter and QImage::setDevicePixelRatio().

[slot] void QWidget::repaint()

Paints the whole widget now, instead of from the event loop.

See also update().

void QWidget::repaint(const QRect &rect)

This is an overloaded function.

Paints rect of the widget now.

void QWidget::resize(const QSize &size)

Resizes the widget to size, within its minimum and maximum size.

See also size() and setGeometry().

void QWidget::resize(int w, int h)

This is an overloaded function.

Resizes the widget to w by h pixels.

[virtual, protected] void QWidget::resizeEvent(QResizeEvent *event)

Handles the resize event. The default does nothing; layouts are updated by the widget itself.

See also resize().

void QWidget::setAttribute(Qt::WidgetAttribute attribute, bool on = true)

Sets the attribute attribute of the widget if on is true, and clears it otherwise. Qt::WidgetAttribute lists the attributes and what they do. Several of them are other names for a property of the widget: setting Qt::WA_Disabled, Qt::WA_MouseTracking, Qt::WA_UpdatesDisabled or Qt::WA_WindowModified is the same as calling the function for it.

auto *about = new AboutDialog(this);
about->setAttribute(Qt::WA_DeleteOnClose);
about->show();

See also testAttribute().

void QWidget::setAutoFillBackground(bool enabled)

Sets whether the widget fills its background to enabled.

See also autoFillBackground().

void QWidget::setCursor(const QCursor &cursor)

Sets the cursor that shows while the mouse is over the widget, and over its children that have no cursor of their own, to cursor. A text field has an I-beam and a link a pointing hand:

link->setCursor(Qt::PointingHandCursor);

An override cursor of the application shows instead for as long as there is one; see QGuiApplication::setOverrideCursor().

See also cursor(), unsetCursor() and Qt::WA_SetCursor.

[slot] void QWidget::setDisabled(bool disable)

Disables the widget if disable is true, and enables it otherwise.

See also setEnabled().

[slot] void QWidget::setEnabled(bool enabled)

Enables the widget if enabled is true, and disables it, with its children, otherwise.

See also isEnabled().

void QWidget::setFixedHeight(int h)

Sets the minimum and the maximum height to h.

void QWidget::setFixedSize(const QSize &size)

Sets both the minimum and the maximum size to size, so that the widget has exactly this size.

void QWidget::setFixedSize(int w, int h)

This is an overloaded function.

Sets the size to exactly w by h pixels.

void QWidget::setFixedWidth(int w)

Sets the minimum and the maximum width to w.

[slot] void QWidget::setFocus()

Gives the keyboard focus to the widget. If the window is not active, the widget gets the focus when the window is activated. The widget receives a focus-in event, and the widget that had the focus a focus-out event.

See also hasFocus() and clearFocus().

void QWidget::setFocusPolicy(Qt::FocusPolicy policy)

Sets the focus policy to policy, which says how the widget gets the keyboard focus.

See also focusPolicy().

void QWidget::setFont(const QFont &font)

Sets the font of the widget to font. Children that have no font of their own use it too.

See also font().

void QWidget::setGeometry(const QRect &rect)

Sets the geometry of the widget to rect, in the coordinates of the parent, or on the screen for a window. The size is kept between minimumSize() and maximumSize(). The widget receives a move and a resize event for what changed.

See also geometry(), move() and resize().

void QWidget::setGeometry(int x, int y, int w, int h)

This is an overloaded function.

Sets the geometry to the rectangle at (x, y) of w by h pixels.

void QWidget::setLayout(QLayout *layout)

Makes layout the layout of the widget, which takes ownership of it. The widgets in the layout become children of this widget. A widget can have one layout; setting another when there is one does nothing but print a warning.

See also layout().

void QWidget::setMaximumHeight(int maxh)

Sets the maximum height to maxh, and keeps the maximum width.

See also setMaximumSize().

void QWidget::setMaximumSize(const QSize &size)

Sets the maximum size of the widget to size. The widget shrinks if it is larger.

See also maximumSize().

void QWidget::setMaximumSize(int maxw, int maxh)

This is an overloaded function.

Sets the maximum size to maxw by maxh pixels.

void QWidget::setMaximumWidth(int maxw)

Sets the maximum width to maxw, and keeps the maximum height.

See also setMaximumSize().

void QWidget::setMinimumHeight(int minh)

Sets the minimum height to minh, and keeps the minimum width.

See also setMinimumSize().

void QWidget::setMinimumSize(const QSize &size)

Sets the minimum size of the widget to size. The widget grows if it is smaller.

See also minimumSize().

void QWidget::setMinimumSize(int minw, int minh)

This is an overloaded function.

Sets the minimum size to minw by minh pixels.

void QWidget::setMinimumWidth(int minw)

Sets the minimum width to minw, and keeps the minimum height.

See also setMinimumSize().

void QWidget::setMouseTracking(bool enable)

Sets whether the widget gets mouse move events when no mouse button is down to enable. Without it, the widget only gets them while a button is pressed.

See also hasMouseTracking().

void QWidget::setPalette(const QPalette &palette)

Sets the palette of the widget to palette. Children that have no palette of their own use it too.

See also palette().

void QWidget::setParent(QWidget *parent)

Makes parent the parent of the widget, or makes the widget a window if parent is nullptr. The widget becomes hidden; call show() to show it again. As in Qt the kind of window is dropped from the window flags, so a dialog given a parent this way becomes a child widget; setParent() with flags keeps it a window.

void QWidget::setParent(QWidget *parent, Qt::WindowFlags f)

This is an overloaded function.

Makes parent the parent of the widget and sets the window flags to f. With Qt::Window in f the widget is a window of its own, with a parent.

See also windowFlags().

void QWidget::setSizePolicy(QSizePolicy policy)

Sets the size policy to policy.

See also sizePolicy().

void QWidget::setSizePolicy(QSizePolicy::Policy horizontal, QSizePolicy::Policy vertical)

This is an overloaded function.

Sets the size policy to horizontal and vertical.

void QWidget::setStyle(QStyle *style)

Sets the style of the widget to style, which the widget does not own and which must outlive it. A nullptr restores the application style. The style of the children is not changed.

See also style().

void QWidget::setToolTip(const QString &text)

Sets the tool tip of the widget to text, which may have several lines. An empty text removes it. The tool tip is shown for a disabled widget too. A widget can show a tool tip that depends on the position of the mouse if it handles the QEvent::ToolTip event.

See also toolTip() and QHelpEvent.

void QWidget::setUpdatesEnabled(bool enable)

Turns the repainting of the widget and its children on if enable is true, and off otherwise. While it is off, update() and repaint() do nothing and the screen keeps what it shows. This avoids flicker while a lot is changed at once:

list->setUpdatesEnabled(false);
fillWithManyItems(list);
list->setUpdatesEnabled(true);

Turning it on again repaints the widget.

See also updatesEnabled() and update().

[slot, virtual] void QWidget::setVisible(bool visible)

Shows the widget if visible is true, and hides it otherwise. Showing a window creates the native window the first time and gives it its size hint as the size if no size was set.

See also show() and hide().

void QWidget::setWindowFlags(Qt::WindowFlags type)

Sets the window flags of the widget to type. Making a child widget a window, or a window with a parent a child, hides it, as setParent() does; call show() to show it again.

See also windowFlags().

void QWidget::setWindowModality(Qt::WindowModality windowModality)

Sets which windows the widget blocks the input of while it is a window that is shown to windowModality. A modal window blocks the mouse, the keyboard and closing for the windows it blocks; they are still painted.

See also windowModality() and QApplication::activeModalWidget().

[slot] void QWidget::setWindowModified(bool modified)

Sets whether the window has changes that are not saved to modified. The title of the window shows it, if windowTitle() has the placeholder [*]: an asterisk is shown in its place while the window is modified, and nothing otherwise. Write [*][*] for a literal [*].

editor->setWindowTitle("notes.txt[*] - Editor");
editor->setWindowModified(true);   // shows "notes.txt* - Editor"

See also isWindowModified() and setWindowTitle().

[slot] void QWidget::setWindowTitle(const QString &title)

Sets the window title to title.

See also windowTitle().

[slot] void QWidget::show()

Shows the widget. This is the same as setVisible(true).

See also hide().

[virtual, protected] void QWidget::showEvent(QShowEvent *event)

Handles the show event: the widget has been, or is about to be, shown. The default does nothing.

QSize QWidget::size() const

Returns the size of the widget.

See also resize().

[virtual] QSize QWidget::sizeHint() const

Returns the size that the widget would like to have. Layouts use it, together with sizePolicy(). The default is the size hint of the widget's layout, or an invalid size if there is none. Reimplement it in a custom widget.

See also minimumSizeHint() and updateGeometry().

QSizePolicy QWidget::sizePolicy() const

Returns the size policy, which tells layouts how the widget may be resized. The default is Preferred in both directions.

See also setSizePolicy().

QStyle * QWidget::style() const

Returns the style that draws the widget: the one set with setStyle() or the application style.

See also setStyle().

[override, protected] bool QWidget::systemClip(QRegion *region) const

Reimplements QPaintDevice::systemClip().

bool QWidget::testAttribute(Qt::WidgetAttribute attribute) const

Returns true if the attribute attribute of the widget is set; otherwise returns false.

See also setAttribute().

QString QWidget::toolTip() const

Returns the tool tip of the widget: the text that appears next to the mouse when it rests on the widget for a moment. It is empty by default, and then the tool tip of the parent applies, if it has one.

See also setToolTip() and QToolTip.

bool QWidget::underMouse() const

Returns true if the mouse is over the widget and no other visible widget on top of it.

void QWidget::unsetCursor()

Takes the cursor of the widget away, so that the widget shows the cursor of its parent again.

See also setCursor().

[slot] void QWidget::update()

Updates the whole widget. The paint event is delivered from the event loop, and several calls are merged into one.

See also repaint().

void QWidget::update(const QRect &rect)

This is an overloaded function.

Updates rect of the widget.

void QWidget::update(const QRegion &region)

This is an overloaded function.

Updates region of the widget.

void QWidget::updateGeometry()

Tells the layout that contains the widget that its size hint, minimum size or size policy changed, so that the layout does its work again.

bool QWidget::updatesEnabled() const

Returns whether the widget is repainted when it is asked to. It is not if setUpdatesEnabled() turned that off for it or for one of its ancestors.

See also setUpdatesEnabled().

[virtual, protected] void QWidget::wheelEvent(QWheelEvent *event)

Handles the wheel event. The default ignores it.

int QWidget::width() const

Returns the width of the widget.

QWidget * QWidget::window() const

Returns the window that contains the widget: its top-level ancestor, or the widget itself if it is a window.

See also isWindow().

Qt::WindowFlags QWidget::windowFlags() const

Returns the window flags of the widget: the kind of window it is and the hints for its decoration. A widget has none, Qt::Widget, unless they were given to the constructor, setParent() or setWindowFlags().

See also setWindowFlags() and windowType().

QWindow * QWidget::windowHandle() const

Returns the QWindow of the window that contains the widget, or nullptr if it has not been shown yet.

Qt::WindowModality QWidget::windowModality() const

Returns which windows the widget blocks the input of while it is a window that is shown. The default is Qt::NonModal.

See also setWindowModality() and isModal().

QString QWidget::windowTitle() const

Returns the window title of the widget, which is only used when the widget is a window.

See also setWindowTitle().

[signal] void QWidget::windowTitleChanged(const QString &title)

This signal is emitted when the window title changes to title.

Qt::WindowType QWidget::windowType() const

Returns the kind of window the widget is: the part of windowFlags() that Qt::WindowType_Mask selects.

See also windowFlags().

int QWidget::x() const

Returns the x coordinate of the widget in its parent.

int QWidget::y() const

Returns the y coordinate of the widget in its parent.