QWidget Class

Header：#include < QWidget >
qmake：QT += widgets
Inherits：QObject and QPaintDevice

Public Types

enum RenderFlag {
    DrawWindowBackground, DrawChildren, IgnoreMask }
flags RenderFlags

Properties

QWidget(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
virtual ~QWidget()
bool acceptDrops() const
QString accessibleDescription() const
QString accessibleName() const
QList<QAction *> actions() const
void activateWindow()
void addAction(QAction *action)
void addActions(QList<QAction *> actions)
void adjustSize()
bool autoFillBackground() const
QPalette::ColorRole backgroundRole() const
QBackingStore *backingStore() const
QSize baseSize() const
QWidget *childAt(int x, int y) const
QWidget *childAt(const QPoint &p) const
QRect childrenRect() const
QRegion childrenRegion() const
void clearFocus()
void clearMask()
QMargins contentsMargins() const
QRect contentsRect() const
Qt::ContextMenuPolicy contextMenuPolicy() const
QCursor cursor() const
WId effectiveWinId() const
void ensurePolished() const
Qt::FocusPolicy focusPolicy() const
QWidget *focusProxy() const
QWidget *focusWidget() const
const QFont &font() const
QFontInfo fontInfo() const
QFontMetrics fontMetrics() const
QPalette::ColorRole foregroundRole() const
QRect frameGeometry() const
QSize frameSize() const
const QRect &geometry() const
QPixmap grab(const QRect &rectangle = QRect(QPoint(0, 0), QSize(-1, -1)))
void grabGesture(Qt::GestureType gesture, Qt::GestureFlags flags = Qt::GestureFlags())
void grabKeyboard()
void grabMouse()
void grabMouse(const QCursor &cursor)
int grabShortcut(const QKeySequence &key, Qt::ShortcutContext context = Qt::WindowShortcut)
QGraphicsEffect *graphicsEffect() const
QGraphicsProxyWidget *graphicsProxyWidget() const
bool hasEditFocus() const
bool hasFocus() const
virtual bool hasHeightForWidth() const
bool hasMouseTracking() const
bool hasTabletTracking() const
int height() const
virtual int heightForWidth(int w) const
Qt::InputMethodHints inputMethodHints() const
virtual QVariant inputMethodQuery(Qt::InputMethodQuery query) const
void insertAction(QAction *before, QAction *action)
void insertActions(QAction *before, QList<QAction *> actions)
bool isActiveWindow() const
bool isAncestorOf(const QWidget *child) const
bool isEnabled() const
bool isEnabledTo(const QWidget *ancestor) const
bool isFullScreen() const
bool isHidden() const
bool isMaximized() const
bool isMinimized() const
bool isModal() const
bool isVisible() const
bool isVisibleTo(const QWidget *ancestor) const
bool isWindow() const
bool isWindowModified() const
QLayout *layout() const
Qt::LayoutDirection layoutDirection() const
QLocale locale() const
QPoint mapFrom(const QWidget *parent, const QPoint &pos) const
QPoint mapFromGlobal(const QPoint &pos) const
QPoint mapFromParent(const QPoint &pos) const
QPoint mapTo(const QWidget *parent, const QPoint &pos) const
QPoint mapToGlobal(const QPoint &pos) const
QPoint mapToParent(const QPoint &pos) const
QRegion mask() const
int maximumHeight() const
QSize maximumSize() const
int maximumWidth() const
int minimumHeight() const
QSize minimumSize() const
virtual QSize minimumSizeHint() const
int minimumWidth() const
void move(const QPoint &)
void move(int x, int y)
QWidget *nativeParentWidget() const
QWidget *nextInFocusChain() const
QRect normalGeometry() const
void overrideWindowFlags(Qt::WindowFlags flags)
const QPalette &palette() const
QWidget *parentWidget() const
QPoint pos() const
QWidget *previousInFocusChain() const
QRect rect() const
void releaseKeyboard()
void releaseMouse()
void releaseShortcut(int id)
void removeAction(QAction *action)
void render(QPaintDevice *target, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion(), QWidget::RenderFlags renderFlags = RenderFlags(DrawWindowBackground | DrawChildren))
void render(QPainter *painter, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion(), QWidget::RenderFlags renderFlags = RenderFlags(DrawWindowBackground | DrawChildren))
void repaint(int x, int y, int w, int h)
void repaint(const QRect &rect)
void repaint(const QRegion &rgn)
void resize(const QSize &)
void resize(int w, int h)
bool restoreGeometry(const QByteArray &geometry)
QByteArray saveGeometry() const
QScreen *screen() const
void scroll(int dx, int dy)
void scroll(int dx, int dy, const QRect &r)
void setAcceptDrops(bool on)
void setAccessibleDescription(const QString &description)
void setAccessibleName(const QString &name)
void setAttribute(Qt::WidgetAttribute attribute, bool on = true)
void setAutoFillBackground(bool enabled)
void setBackgroundRole(QPalette::ColorRole role)
void setBaseSize(const QSize &)
void setBaseSize(int basew, int baseh)
void setContentsMargins(int left, int top, int right, int bottom)
void setContentsMargins(const QMargins &margins)
void setContextMenuPolicy(Qt::ContextMenuPolicy policy)
void setCursor(const QCursor &)
void setEditFocus(bool enable)
void setFixedHeight(int h)
void setFixedSize(const QSize &s)
void setFixedSize(int w, int h)
void setFixedWidth(int w)
void setFocus(Qt::FocusReason reason)
void setFocusPolicy(Qt::FocusPolicy policy)
void setFocusProxy(QWidget *w)
void setFont(const QFont &)
void setForegroundRole(QPalette::ColorRole role)
void setGeometry(const QRect &)
void setGeometry(int x, int y, int w, int h)
void setGraphicsEffect(QGraphicsEffect *effect)
void setInputMethodHints(Qt::InputMethodHints hints)
void setLayout(QLayout *layout)
void setLayoutDirection(Qt::LayoutDirection direction)
void setLocale(const QLocale &locale)
void setMask(const QBitmap &bitmap)
void setMask(const QRegion &region)
void setMaximumHeight(int maxh)
void setMaximumSize(const QSize &)
void setMaximumSize(int maxw, int maxh)
void setMaximumWidth(int maxw)
void setMinimumHeight(int minh)
void setMinimumSize(const QSize &)
void setMinimumSize(int minw, int minh)
void setMinimumWidth(int minw)
void setMouseTracking(bool enable)
void setPalette(const QPalette &)
void setParent(QWidget *parent)
void setParent(QWidget *parent, Qt::WindowFlags f)
void setShortcutAutoRepeat(int id, bool enable = true)
void setShortcutEnabled(int id, bool enable = true)
void setSizeIncrement(const QSize &)
void setSizeIncrement(int w, int h)
void setSizePolicy(QSizePolicy)
void setSizePolicy(QSizePolicy::Policy horizontal, QSizePolicy::Policy vertical)
void setStatusTip(const QString &)
void setStyle(QStyle *style)
void setTabletTracking(bool enable)
void setToolTip(const QString &)
void setToolTipDuration(int msec)
void setUpdatesEnabled(bool enable)
void setWhatsThis(const QString &)
void setWindowFilePath(const QString &filePath)
void setWindowFlag(Qt::WindowType flag, bool on = true)
void setWindowFlags(Qt::WindowFlags type)
void setWindowIcon(const QIcon &icon)
void setWindowModality(Qt::WindowModality windowModality)
void setWindowOpacity(qreal level)
void setWindowRole(const QString &role)
void setWindowState(Qt::WindowStates windowState)
void setupUi(QWidget *widget)
QSize size() const
virtual QSize sizeHint() const
QSize sizeIncrement() const
QSizePolicy sizePolicy() const
void stackUnder(QWidget *w)
QString statusTip() const
QStyle *style() const
QString styleSheet() const
bool testAttribute(Qt::WidgetAttribute attribute) const
QString toolTip() const
int toolTipDuration() const
bool underMouse() const
void ungrabGesture(Qt::GestureType gesture)
void unsetCursor()
void unsetLayoutDirection()
void unsetLocale()
void update(int x, int y, int w, int h)
void update(const QRect &rect)
void update(const QRegion &rgn)
void updateGeometry()
bool updatesEnabled() const
QRegion visibleRegion() const
QString whatsThis() const
int width() const
WId winId() const
QWidget *window() const
QString windowFilePath() const
Qt::WindowFlags windowFlags() const
QWindow *windowHandle() const
QIcon windowIcon() const
Qt::WindowModality windowModality() const
qreal windowOpacity() const
QString windowRole() const
Qt::WindowStates windowState() const
QString windowTitle() const
Qt::WindowType windowType() const
int x() const
int y() const

Public Slots

bool close()
void hide()
void lower()
void raise()
void repaint()
void setDisabled(bool disable)
void setEnabled(bool)
void setFocus()
void setHidden(bool hidden)
void setStyleSheet(const QString &styleSheet)
virtual void setVisible(bool visible)
void setWindowModified(bool)
void setWindowTitle(const QString &)
void show()
void showFullScreen()
void showMaximized()
void showMinimized()
void showNormal()
void update()

Signals

void customContextMenuRequested(const QPoint &pos)
void windowIconChanged(const QIcon &icon)
void windowTitleChanged(const QString &title)

Static Public Members

QWidget *createWindowContainer(QWindow *window, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
QWidget *find(WId id)
QWidget *keyboardGrabber()
QWidget *mouseGrabber()
void setTabOrder(QWidget *first, QWidget *second)

Protected Functions

virtual void actionEvent(QActionEvent *event)
virtual void changeEvent(QEvent *event)
virtual void closeEvent(QCloseEvent *event)
virtual void contextMenuEvent(QContextMenuEvent *event)
void create(WId window = 0, bool initializeWindow = true, bool destroyOldWindow = true)
void destroy(bool destroyWindow = true, bool destroySubWindows = true)
virtual void dragEnterEvent(QDragEnterEvent *event)
virtual void dragLeaveEvent(QDragLeaveEvent *event)
virtual void dragMoveEvent(QDragMoveEvent *event)
virtual void dropEvent(QDropEvent *event)
virtual void enterEvent(QEvent *event)
virtual void focusInEvent(QFocusEvent *event)
bool focusNextChild()
virtual bool focusNextPrevChild(bool next)
virtual void focusOutEvent(QFocusEvent *event)
bool focusPreviousChild()
virtual void hideEvent(QHideEvent *event)
virtual void inputMethodEvent(QInputMethodEvent *event)
virtual void keyPressEvent(QKeyEvent *event)
virtual void keyReleaseEvent(QKeyEvent *event)
virtual void leaveEvent(QEvent *event)
virtual void mouseDoubleClickEvent(QMouseEvent *event)
virtual void mouseMoveEvent(QMouseEvent *event)
virtual void mousePressEvent(QMouseEvent *event)
virtual void mouseReleaseEvent(QMouseEvent *event)
virtual void moveEvent(QMoveEvent *event)
virtual bool nativeEvent(const QByteArray &eventType, void *message, long *result)
virtual void paintEvent(QPaintEvent *event)
virtual void resizeEvent(QResizeEvent *event)
virtual void showEvent(QShowEvent *event)
virtual void tabletEvent(QTabletEvent *event)
virtual void wheelEvent(QWheelEvent *event)

Reimplemented Protected Functions

virtual bool event(QEvent *event) override
virtual void initPainter(QPainter *painter) const override
virtual int metric(QPaintDevice::PaintDeviceMetric m) const override

Protected Slots

void updateMicroFocus()

Macros

QWIDGETSIZE_MAX
	定义QWidget对象的最大大小。
	小部件允许的最大大小是QSize(QWIDGETSIZE_MAX, QWIDGETSIZE_MAX)，即QSize(16777215,16777215)。
See also QWidget::setMaximumSize(). 

Detailed Description

小部件是用户界面的原子:它接收来自窗口系统的鼠标、键盘和其他事件，并在屏幕上描绘自己的表示。每个小部件都是矩形的，它们按z轴顺序排序。一个小部件被它的父部件和它前面的小部件剪切。
没有嵌入父小部件的小部件称为窗口。通常，窗口有一个框架和标题栏，尽管也可以使用合适的窗口标志创建没有这种装饰的窗口)。在Qt中，QMainWindow和QDialog的各种子类是最常见的窗口类型。
每个小部件的构造函数接受一个或两个标准参数:
QWidget *parent = nullptr是新小部件的父组件。如果它是nullptr(默认值)，则新的小部件将是一个窗口。如果不是，它将是parent的一个子部件，并受到parent的几何形状的约束(除非您指定Qt::Window作为窗口标志)。
Qt::WindowFlags f = 0(如果可用)设置窗口标志;默认值适用于几乎所有小部件，但要获得(例如)没有窗口系统框架的窗口，必须使用特殊标志。
QWidget有很多成员函数，但是有些成员函数的直接功能很少;例如，QWidget有一个font属性，但它自己从不使用这个属性。实际上是在许多子类中实现了具体功能，如QLabel、QPushButton、QListWidget和QTabWidget。

Top-Level and Child Widgets

没有父小部件的小部件始终是一个独立的窗口(顶级小部件)。对于这些小部件，setWindowTitle()和setWindowIcon()分别设置标题栏和图标。
非窗口小部件是子小部件，显示在父小部件中。Qt中的大多数小部件主要用作子部件。例如，可以将按钮显示为顶级窗口，但大多数人更喜欢将按钮放在其他小部件(如QDialog)中。

上图显示了QGroupBox小部件用于在QGridLayout提供的布局中保存各种子小部件。QLabel子部件已被概述以指示它们的完整尺寸。
如果希望使用QWidget来容纳子部件，通常需要向父QWidget添加一个布局。有关更多信息，请参阅布局管理。

Composite Widgets

当一个小部件被用作容器来对许多子小部件进行分组时，它被称为复合小部件。可以通过构造具有所需可视属性的小部件(例如QFrame)并向其添加子小部件(通常由布局管理)来创建这些小部件。上图显示了这样一个使用Qt Designer创建的复合小部件。
复合小部件还可以通过创建标准小部件(如QWidget或QFrame)的子类，并在子类的构造函数中添加必要的布局和子小部件来创建。Qt提供的许多示例都使用了这种方法，Qt教程也介绍了这种方法。

Custom Widgets and Painting

因为QWidget是QPaintDevice的一个子类，所以子类可以用来显示定制的内容，这些内容是通过QPainter类的一个实例使用一系列绘画操作组成的。这种方法与图形视图框架使用的画布风格的方法形成对比，在画布风格的方法中，项目由应用程序添加到场景中，并由框架本身渲染。
每个小部件在其paintEvent()函数中执行所有绘画操作。每当小部件需要重新绘制时(由于某些外部更改或应用程序请求)，都会调用此方法。
Analog Clock示例展示了一个简单的小部件如何处理绘制事件。

Size Hints and Size Policies

在实现新小部件时，重新实现sizeHint()为小部件提供合理的默认大小并使用setSizePolicy()设置正确的大小策略几乎总是有用的。
默认情况下，不提供大小提示的复合小部件将根据其子小部件的空间需求调整大小。
大小策略允许您为布局管理系统提供良好的默认行为，以便其他小部件可以轻松地包含和管理您的小部件。默认大小策略表明大小提示表示小部件的首选大小，这对于许多小部件来说通常已经足够好了。
注意:顶级小部件的大小被限制为桌面高度和宽度的2/3。如果这些边界不够，可以手动调整小部件的大小。

Events

小部件响应通常由用户操作引起的事件。Qt通过调用带有QEvent子类实例的特定事件处理函数来传递事件给小部件，这些实例包含每个事件的信息。
如果您的小部件只包含子小部件，则可能不需要实现任何事件处理程序。如果您想检测子部件中的鼠标点击，请在小部件的mousePressEvent()中调用子部件的underMouse()函数。
Scribble示例实现了一组更广泛的事件来处理鼠标移动、按钮按下和窗口大小调整。
您将需要为您自己的小部件提供行为和内容，但这里是与QWidget相关的事件的简要概述，从最常见的事件开始:
每当需要重新绘制小部件时，就调用paintEvent()。每个显示自定义内容的小部件都必须实现它。使用QPainter进行绘画只能在paintEvent()或由paintEvent()调用的函数中进行。
resizeEvent()在小部件被调整大小时调用。
当鼠标光标在小部件内部时按下鼠标按钮，或者小部件使用grabMouse()抓取鼠标时，调用mousePressEvent()。按下鼠标而不释放它实际上与调用grabMouse()相同。
当鼠标按钮被释放时，调用mouseReleaseEvent()。小部件在接收到相应的鼠标按下事件时接收鼠标释放事件。这意味着，如果用户在您的小部件内按下鼠标，然后在释放鼠标按钮之前将鼠标拖动到其他地方，那么您的小部件将接收到释放事件。有一个例外:如果在按住鼠标按钮时出现一个弹出式菜单，这个弹出式菜单会立即窃取鼠标事件。
当用户在小部件中双击时调用mouseDoubleClickEvent()。如果用户双击，则小部件接收鼠标按下事件、鼠标释放事件、(鼠标单击事件)第二次鼠标按下、此事件以及最后的第二次鼠标释放事件。(如果在此操作期间鼠标没有保持稳定，也可能会接收到一些鼠标移动事件。)在第二次单击到来之前，无法区分单击和双击。(这就是为什么大多数GUI书籍建议将双击作为单击的扩展，而不是触发不同的操作的原因之一。)
接受键盘输入的小部件需要重新实现更多的事件处理程序:
keyPressEvent()在按键被按下时调用，当按键被按下足够长的时间使其自动重复时再次调用。Tab和Shift+Tab键只有在焦点更改机制不使用时才传递给小部件。要强制小部件处理这些键，必须重新实现QWidget::event()。
当小部件获得键盘焦点时调用focusInEvent()(假设您调用了setFocusPolicy())。行为良好的小部件表明它们以一种清晰而谨慎的方式拥有键盘焦点。
当小部件失去键盘焦点时调用focusOutEvent()。
您可能还需要重新实现一些不太常见的事件处理程序:
每当鼠标移动而按住鼠标按钮时调用mouseMoveEvent()。这在拖放操作中很有用。如果调用setMouseTracking(true)，即使没有按下按钮，也会得到鼠标移动事件。(请参见拖放指南。)
keyReleaseEvent()在键被释放和按住时(如果键是自动重复的)被调用。在这种情况下，小部件将在每次重复时接收一对键释放和键按事件。Tab和Shift+Tab键只有在焦点更改机制不使用时才传递给小部件。要强制小部件处理这些键，必须重新实现QWidget::event()。
每当用户在小部件具有焦点时转动鼠标滚轮时，就调用wheelEvent()。
当鼠标进入小部件的屏幕空间时调用enterEvent()。(这不包括小部件的任何子部件所拥有的屏幕空间。)
当鼠标离开小部件的屏幕空间时调用leaveEvent()。如果鼠标进入子部件，则不会引起leaveEvent()。
当小部件相对于其父部件移动时，将调用moveEvent()。
当用户关闭小部件时(或调用close()时)调用closeEvent()。
在QEvent::Type的文档中还描述了一些相当模糊的事件。要处理这些事件，需要直接重新实现event()。
event()的默认实现处理Tab和Shift+Tab(移动键盘焦点)，并将大多数其他事件传递给上述更专门的处理程序之一。
事件和用于交付事件的机制将在事件系统中介绍。

Groups of Functions and Properties

Context	Functions and Properties
Window functions	show(), hide(), raise(), lower(), close().
Top-level windows	windowModified, windowTitle, windowIcon, isActiveWindow, activateWindow(), minimized, showMinimized(), maximized, showMaximized(), fullScreen, showFullScreen(), showNormal().
Window contents	update(), repaint(), scroll().
Geometry	pos, x(), y(), rect, size, width(), height(), move(), resize(), sizePolicy, sizeHint(), minimumSizeHint(), updateGeometry(), layout(), frameGeometry, geometry, childrenRect, childrenRegion, adjustSize(), mapFromGlobal(), mapToGlobal(), mapFromParent(), mapToParent(), maximumSize, minimumSize, sizeIncrement, baseSize, setFixedSize()
Mode	visible, isVisibleTo(), enabled, isEnabledTo(), modal, isWindow(), mouseTracking, updatesEnabled, visibleRegion().
Look and feel	style(), setStyle(), styleSheet, cursor, font, palette, backgroundRole(), setBackgroundRole(), fontInfo(), fontMetrics().
Keyboard focus functions	focus, focusPolicy, setFocus(), clearFocus(), setTabOrder(), setFocusProxy(), focusNextChild(), focusPreviousChild().
Mouse and keyboard grabbing	grabMouse(), releaseMouse(), grabKeyboard(), releaseKeyboard(), mouseGrabber(), keyboardGrabber().
Event handlers	event(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), keyPressEvent(), keyReleaseEvent(), focusInEvent(), focusOutEvent(), wheelEvent(), enterEvent(), leaveEvent(), paintEvent(), moveEvent(), resizeEvent(), closeEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), childEvent(), showEvent(), hideEvent(), customEvent(). changeEvent(),
System functions	parentWidget(), window(), setParent(), winId(), find(), metric().
Context menu	contextMenuPolicy, contextMenuEvent(), customContextMenuRequested(), actions()
Interactive help	setToolTip(), setWhatsThis()

Widget Style Sheets

除了每个平台的标准小部件样式外，还可以根据样式表中指定的规则对小部件进行样式设置。此特性使您能够自定义特定小部件的外观，以便向用户提供有关其用途的视觉提示。例如，可以用特定的方式对按钮进行样式设计，以表明它执行破坏性操作。
Qt样式表文档中更详细地描述了小部件样式表的使用。

Transparency and Double Buffering

自Qt 4.0以来，QWidget自动双缓冲其绘制，因此不需要在paintEvent()中编写双缓冲代码来避免闪烁。
自Qt 4.1以来，Qt::WA_ContentsPropagated小部件属性已被弃用。相反，只要Qt::WA_PaintOnScreen未设置，父窗口小部件的内容就会在默认情况下传播给它们的每个子窗口小部件。定制小部件可以通过更新不规则区域(以创建非矩形子小部件)或使用小于完整alpha分量的颜色进行绘画来利用此特性。下图显示了如何对自定义小部件的属性和属性进行微调以实现不同的效果。

• 在上面的图中，构造了一个移除区域的半透明矩形子小部件，并将其添加到父小部件(显示像素图的QLabel)。然后，设置不同