QWidget Class

成员函数文档

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

创建一个作为parent 子窗口的小部件，其小部件标志设置为f 。

如果parent 是nullptr ，则新小部件将成为一个窗口。如果parent 是另一个小部件，则该小部件将成为parent 内的子窗口。当其parent 被删除时，新小部件也将被删除。

控件标志参数f 通常为 0，但可进行设置以自定义窗口边框（即parent 必须为nullptr ）。要自定义边框，请使用由任意window flags 按位或运算组合而成的值。

如果将子控件添加到已显示的控件中，必须显式地显示该子控件才能使其可见。

请注意，Qt 的 X11 版本可能无法在所有系统上提供所有样式标志的组合。这是因为在 X11 环境下，Qt 只能向窗口管理器请求设置，而窗口管理器可以覆盖应用程序的设置。在 Windows 系统上，Qt 可以设置您所需的任何标志。

另请参阅 windowFlags 。

[virtual noexcept] QWidget::~QWidget()

销毁该控件。

首先会删除该控件的所有子控件。如果该控件是主控件，则应用程序将退出。

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

每当控件的操作发生变化时，系统都会调用此事件处理程序，并传入给定的event 。

另请参阅 addAction()、insertAction()、removeAction()、actions() 以及QActionEvent 。

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

返回该控件的操作列表（该列表可能为空）。

另请参阅 contextMenuPolicy 、insertAction() 和removeAction()。

void QWidget::activateWindow()

将包含此控件的顶级控件设置为活动窗口。

活动窗口是指可见且拥有键盘输入焦点的顶级窗口。

此函数的作用等同于在顶级窗口的标题栏上单击鼠标。在 X11 环境中，结果取决于窗口管理器。若要确保该窗口同时位于最前，还应调用raise()。请注意，窗口必须处于可见状态，否则 activateWindow() 不会生效。

在 Windows 系统上，如果当前应用程序并非活动窗口时调用此函数，则不会使其成为活动窗口。该函数会更改任务栏条目的颜色，以指示该窗口已发生某种变化。这是因为微软不允许应用程序中断用户在其他应用程序中的当前操作。

另请参阅 isActiveWindow()、window() 和show()。

void QWidget::addAction(QAction *action)

将操作action 追加到该小部件的操作列表中。

所有 QWidget 都拥有一个QAction列表。不过，这些 可以通过多种不同的方式在图形界面中呈现。QAction 列表（由actions() 返回）的默认用途是创建一个上下文QMenu 。

一个QWidget 应仅包含每种操作的一个实例，若添加其已有的操作，不会导致该操作在小部件中出现两次。

action 的所有权不会转移到此QWidget 上。

另请参阅 removeAction()、insertAction()、actions() 以及QMenu 。

这些便捷函数会创建一个新操作，其文本为text ，图标为icon ，如有快捷键则为shortcut 。

这些函数会将新创建的操作添加到小部件的操作列表中，并返回该操作。

QWidget 将获取返回的QAction 的所有权。

这些函数在 Qt 6.3 中引入。

这些便捷函数会创建一个新的操作，其文本为text ，图标为icon ，如有快捷键则为shortcut 。

该操作的triggered() 信号连接方式与调用QObject::connect(action, &QAction::triggered, args...) 完全一致，能够完美转发args ，包括可能的Qt::ConnectionType 。

该函数将新创建的操作添加到控件的操作列表中，并返回该操作。

QWidget 该函数将接管返回的QAction 的所有权。

这些函数在 Qt 6.3 中引入。

此便捷函数会创建一个新的操作，其文本为text ，图标为icon ，并带有快捷方式shortcut （如有）。

该动作的 `triggered()` 信号与 `receiver` 的 `member ` 槽相连。该函数将新创建的动作添加到控件的动作列表中，并返回该动作。

QWidget 该函数将接管返回的QAction 的所有权。

这些函数是在 Qt 6.3 中引入的。

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

将操作actions 添加到该控件的操作列表中。

另请参阅 removeAction()、QMenu 以及addAction()。

void QWidget::adjustSize()

调整控件的大小以适应其内容。

如果sizeHint() 有效（即大小提示的宽度和高度均≥0），则此函数会使用该大小提示；否则，它会将大小设置为覆盖所有子控件的子矩形（即所有子控件矩形的并集）。

对于窗口，还会考虑屏幕尺寸。如果 `sizeHint()` 小于 (200, 100)，且大小策略为 `expanding`，则窗口的最小尺寸将不小于 (200, 100)。窗口的最大尺寸为屏幕宽度和高度的 2/3。

另请参阅 sizeHint() 和childrenRect()。

QPalette::ColorRole QWidget::backgroundRole() const

返回控件的背景角色。

背景角色定义了用于渲染背景的、取自小部件palette 中的画笔。

如果未显式设置背景角色，则控件将继承其父控件的背景角色。

另请参阅 setBackgroundRole() 和foregroundRole()。

QBackingStore *QWidget::backingStore() const

返回该控件将绘制内容的QBackingStore 对象。

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

可以重新实现此事件处理程序来处理状态变化。

可以通过提供的event 获取该事件中正在变化的状态。

状态变化事件包括：QEvent::ToolBarChange 、QEvent::ActivationChange 、QEvent::EnabledChange 、QEvent::FontChange 、QEvent::StyleChange 、QEvent::PaletteChange 、QEvent::WindowTitleChange 、QEvent::IconTextChange 、QEvent::ModifiedChange 、QEvent::MouseTrackingChange 、QEvent::ParentChange 、QEvent::WindowStateChange 、QEvent::LanguageChange 、QEvent::LocaleChange 、QEvent::LayoutDirectionChange 、QEvent::ReadOnlyChange 。

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

返回位于小部件坐标系中位置 (x,y) 处的可见子小部件。如果指定位置处没有可见的子小部件，则该函数返回nullptr 。

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

返回位于坐标点p 处（在控件自身的坐标系中）的可见子控件。

[since 6.8] QWidget *QWidget::childAt(const QPointF &p) const

返回在小部件自身坐标系中位于坐标点 (p ) 的可见子小部件。

该函数于 Qt 6.8 中引入。

void QWidget::clearFocus()

从该控件上移除键盘输入焦点。

如果该小部件当前处于焦点状态，系统会向该小部件发送一个focus out event 事件，告知其已失去焦点。

该控件必须启用焦点设置才能获得键盘输入焦点；也就是说，它必须调用setFocusPolicy() 方法。

另请参阅 hasFocus()、setFocus()、focusInEvent()、focusOutEvent()、setFocusPolicy() 以及QApplication::focusWidget()。

void QWidget::clearMask()

删除由setMask() 设置的任何遮罩。

另请参阅 setMask()。

[slot] bool QWidget::close()

关闭此小部件。如果小部件已被关闭，则返回true ；否则返回false 。

首先，它会向控件发送一个QCloseEvent 。如果控件accepts 了关闭事件，则该控件为hidden 。如果它ignores 了该事件，则不会发生任何变化。QWidget::closeEvent()的默认实现会接受关闭事件。

如果小部件设置了Qt::WA_DeleteOnClose 标志，则该小部件也会被删除。无论小部件是否可见，都会向其发送关闭事件。

当最后一个可见的主窗口（即没有父窗口的窗口）且该窗口设置了Qt::WA_QuitOnClose 属性时，会发出QGuiApplication::lastWindowClosed()信号。默认情况下，除临时窗口（如启动画面、工具窗口和弹出菜单）外，所有小部件都设置了此属性。

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

当 Qt 从窗口系统收到针对顶级小部件的窗口关闭请求时，会使用给定的event 调用此事件处理程序。

默认情况下，该事件会被接受，小部件也会随之关闭。您可以重写此函数，以更改小部件响应窗口关闭请求的方式。例如，您可以在所有事件中调用 `ignore()` 来阻止窗口关闭。

主窗口应用程序通常会重写此函数，以检查用户的工作是否已保存，并在关闭前征得用户许可。

另请参阅 event()、hide()、close() 以及QCloseEvent 。

QMargins QWidget::contentsMargins() const

contentsMargins 函数返回小部件的内容边距。

另请参阅 setContentsMargins() 和contentsRect()。

QRect QWidget::contentsRect() const

返回小部件边距内部的区域。

另请参阅 setContentsMargins() 和contentsMargins()。

[virtual protected] void QWidget::contextMenuEvent(QContextMenuEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收小部件的上下文菜单事件。

当小部件的contextMenuPolicy 属性设置为Qt::DefaultContextMenu 时，将调用该处理程序。

默认实现会忽略上下文事件。更多详细信息请参阅QContextMenuEvent 文档。

另请参阅 event()、QContextMenuEvent 以及customContextMenuRequested()。

[protected] void QWidget::create(WId window = 0, bool initializeWindow = true, bool destroyOldWindow = true)

创建一个新的控件窗口。

在 Qt 5 中，参数window 、initializeWindow 和destroyOldWindow 将被忽略。请改用QWindow::fromWinId() 创建一个包裹外部窗口的QWindow ，并将该对象传递给QWidget::createWindowContainer()。

另请参阅 createWindowContainer() 和QWindow::fromWinId()。

[static] QWidget *QWidget::createWindowContainer(QWindow *window, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

创建一个QWidget ，使其能够将window 嵌入到基于QWidget 的应用程序中。

该窗口容器作为parent 的子窗口创建，并带有窗口标志flags 。

一旦窗口被嵌入到容器中，容器将控制该窗口的几何属性与可见性。不建议对嵌入的窗口显式调用QWindow::setGeometry()、QWindow::show() 或QWindow::hide() 方法。

容器将接管window 的所有权。可通过调用QWindow::setParent()将窗口从窗口容器中移除。

窗口容器作为原生子窗口附加到其父窗口（即顶级窗口）上。当窗口容器作为QAbstractScrollArea 或QMdiArea 的子窗口使用时，它会为其父链中的每个小部件创建一个native window ，以便在此用例中实现正确的堆叠和裁剪。 为窗口容器创建原生窗口也能确保正确的堆叠和裁剪。此操作必须在显示窗口容器之前完成。包含大量原生子窗口的应用程序可能会出现性能问题。

窗口容器存在以下已知限制：

• 堆叠顺序；嵌入的窗口将作为不透明框叠加在控件层次结构之上。多个重叠的窗口容器实例的堆叠顺序未定义。
• 渲染集成：窗口容器不与 `QGraphicsProxyWidget`、`QWidget::render()` 或类似功能互操作。
• 焦点处理；窗口容器实例可以采用任何焦点策略，它将通过调用QWindow::requestActivate()将焦点委托给窗口。但是，从QWindow 实例返回至正常焦点链的行为取决于QWindow 实例本身的实现。此外，QWindow::requestActivate()是否实际将焦点赋予窗口，取决于具体平台。

  如果嵌入基于Qt Quick 的窗口，Qt 将自动确保按 Tab 键时焦点会在嵌入的 QML 窗口之间切换，从而允许焦点移至窗口容器链中的下一个或上一个可获得焦点的对象。

• 在基于QWidget 的应用程序中使用过多的窗口容器实例，会严重影响应用程序的整体性能。

[signal] void QWidget::customContextMenuRequested(const QPoint &pos)

当控件的contextMenuPolicy 为Qt::CustomContextMenu ，且用户请求在该控件上显示上下文菜单时，会发出此信号。位置pos 即为控件接收到的上下文菜单事件的位置。通常该位置采用控件坐标系。此规则的例外是QAbstractScrollArea 及其子类，它们会将上下文菜单事件映射到viewport()的坐标系中。

另请参阅 mapToGlobal()、QMenu 以及contextMenuPolicy 。

[protected] void QWidget::destroy(bool destroyWindow = true, bool destroySubWindows = true)

释放窗口系统资源。如果destroyWindow 为真，则销毁该小部件窗口。

destroy() 会递归调用自身，处理所有子控件，并将destroySubWindows 作为destroyWindow 参数传递。若需更精细地控制子控件的销毁，请先有选择地销毁子控件。

该函数通常由QWidget 的析构函数调用。

[virtual protected] void QWidget::dragEnterEvent(QDragEnterEvent *event)

当拖动操作正在进行且鼠标进入此控件时，会调用此事件处理程序。该事件通过event 参数传递进来。

如果忽略该事件，控件将不会收到任何drag move events 。

请参阅“拖放”文档，了解如何在您的应用程序中实现拖放功能。

另请参阅 QDrag 和QDragEnterEvent 。

[virtual protected] void QWidget::dragLeaveEvent(QDragLeaveEvent *event)

当拖动操作正在进行且鼠标离开此控件时，会调用此事件处理程序。该事件通过event 参数传递进来。

有关如何在应用程序中实现拖放功能的概述，请参阅“拖放”文档。

另请参阅 QDrag 和QDragLeaveEvent 。

[virtual protected] void QWidget::dragMoveEvent(QDragMoveEvent *event)

当拖动操作正在进行时，且出现以下任一情况时，将调用此事件处理程序：光标进入该控件、光标在该控件内移动，或者当该控件获得焦点时按下键盘上的修饰键。该事件通过event 参数传递进来。

有关如何在应用程序中实现拖放功能的概述，请参阅“拖放”文档。

另请参阅 QDrag 和QDragMoveEvent 。

[virtual protected] void QWidget::dropEvent(QDropEvent *event)

当拖动操作在此控件上释放时，会调用此事件处理程序。该事件通过event 参数传递进来。

有关如何在应用程序中实现拖放功能的概述，请参阅“拖放”文档。

另请参阅 QDrag 和QDropEvent 。

WId QWidget::effectiveWinId() const

返回该控件的有效窗口系统标识符，即其本机父控件的窗口系统标识符。

如果该小部件是本机小部件，则此函数返回本机小部件 ID。否则，将返回第一个本机父级小部件（即包含该小部件的顶级小部件）的窗口 ID。

另请参阅 nativeParentWidget()。

void QWidget::ensurePolished() const

确保该控件及其子控件已由QStyle 进行美化处理（即拥有正确的字体和配色方案）。

QWidget 在控件完全构建完成之后、首次显示之前调用此函数。 如果您希望在执行某项操作之前确保控件已完成“润色”，可以调用此函数，例如，在控件的sizeHint() 重写实现中可能需要正确的字体大小。请注意，此函数是由sizeHint() 的默认实现调用的。

“完善”操作适用于必须在所有构造函数（包括基类和子类的构造函数）调用完毕后才进行的最终初始化。

若需在小部件进行“polishing”时更改某些设置，请重写event() 并处理QEvent::Polish 事件类型。

注意：该函数被声明为 const，以便可以从其他 const 函数（例如sizeHint()）中调用它。

另请参阅 event()。

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

可以在子类中重新实现此事件处理程序，以接收通过event 参数传递的控件进入事件。

当鼠标光标进入小部件时，会向该小部件发送一个事件。

另请参阅 leaveEvent()、mouseMoveEvent() 和event()。

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

重写：QObject::event(QEvent *e)。

这是主要的事件处理函数；它处理event 事件。您可以在子类中重写此函数，但我们建议改用其中一个专门的事件处理函数。

按键按下和释放事件的处理方式与其他事件不同。event() 会检查是否按下了 Tab 和 Shift+Tab 键，并尝试相应地移动焦点。如果没有可移动焦点的控件（或者按下的键不是 Tab 或 Shift+Tab），event() 会调用keyPressEvent()。

鼠标和平板设备的事件处理也略有特殊：只有当控件处于enabled 状态时，event()才会调用专门的处理程序（如mousePressEvent()）；否则将丢弃该事件。

如果事件被识别，该函数返回true ；否则返回false 。如果被识别的事件被接受（参见QEvent::accepted ），则任何后续处理（例如向父控件传播事件）都会停止。

另请参阅 closeEvent()、focusInEvent()、focusOutEvent()、enterEvent()、keyPressEvent()、keyReleaseEvent()、leaveEvent()、mouseDoubleClickEvent()、mouseMoveEvent()、mousePressEvent()、mouseReleaseEvent()、moveEvent()、paintEvent()、resizeEvent()、QObject::event() 以及QObject::timerEvent()。

[static] QWidget *QWidget::find(WId id)

返回指向具有窗口标识符/句柄id 的控件的指针。

窗口标识符的类型取决于底层窗口系统，具体定义请参见qwindowdefs.h 。如果不存在具有此标识符的小部件，则返回nullptr 。

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

可以在子类中重新实现此事件处理程序，以接收小部件的键盘焦点事件（焦点被获取）。该事件通过event 参数传递

控件通常必须将setFocusPolicy()的返回值设置为Qt::NoFocus 以外的值，才能接收焦点事件。（请注意，应用程序开发人员可以对任何控件调用setFocus()，即使这些控件通常不接受焦点。）

默认实现会更新该控件（未指定focusPolicy() 的窗口除外）。

另请参阅 focusOutEvent()、setFocusPolicy()、keyPressEvent()、keyReleaseEvent()、event() 以及QFocusEvent 。

[protected] bool QWidget::focusNextChild()

查找一个新的控件以将键盘焦点赋予其，以符合Tab 的要求，并在找到新控件时返回true ，否则返回false。

另请参阅 focusPreviousChild()。

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

根据情况为“Tab”和“Shift+Tab”键操作查找一个新的控件来获取键盘焦点，如果能找到新的控件，则返回true ；否则返回false。

如果next 为true，则该函数向前搜索；如果next 为false，则向后搜索。

有时，您可能需要重写此函数。例如，网页浏览器可能会重写它，以便将“当前活动链接”向前或向后移动，并且仅当到达“页面”上的最后一个或第一个链接时才调用 focusNextPrevChild()。

子控件会调用其父控件上的 focusNextPrevChild()，但只有包含这些子控件的窗口才能决定将焦点重定向到何处。因此，通过为某个对象重写此函数，您便可以控制所有子控件的焦点遍历。

另请参阅 focusNextChild() 和focusPreviousChild()。

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

可以在子类中重写此事件处理程序，以接收该小部件的键盘焦点事件（焦点丢失）。事件通过event 参数传递进来。

小部件通常必须将setFocusPolicy()的返回值设置为Qt::NoFocus 以外的值，才能接收焦点事件。（请注意，应用程序开发人员可以对任何小部件调用setFocus()，即使这些小部件通常不接受焦点。）

默认实现会更新该控件（未指定focusPolicy() 的窗口除外）。

另请参阅 focusInEvent()、setFocusPolicy()、keyPressEvent()、keyReleaseEvent()、event() 以及QFocusEvent 。

[protected] bool QWidget::focusPreviousChild()

查找一个新的控件以将键盘焦点赋予其，使其符合Shift+Tab 的要求；若能找到新的控件，则返回true ；若找不到，则返回false。

另请参阅 focusNextChild()。

QWidget *QWidget::focusProxy() const

返回焦点代理；如果不存在焦点代理，则返回nullptr 。

另请参阅 setFocusProxy()。

QWidget *QWidget::focusWidget() const

返回此控件中最后一个曾调用过setFocus 方法的子控件。对于顶级控件，如果该窗口被激活，此控件将获得焦点

这与QApplication::focusWidget() 不同，后者返回当前活动窗口中的焦点小部件。

QFontInfo QWidget::fontInfo() const

返回小部件当前字体的字体信息。相当于QFontInfo(widget->font()) 。

另请参阅 font()、fontMetrics() 和setFont()。

QFontMetrics QWidget::fontMetrics() const

返回小部件当前字体的字体度量数据。等同于QFontMetrics(widget->font()) 。

另请参阅 font()、fontInfo() 和setFont()。

QPalette::ColorRole QWidget::foregroundRole() const

返回前景色。

前景角色定义了控件的palette 中用于绘制前景的颜色。

如果未显式设置前景角色，该函数将返回一个与背景角色形成对比的角色。

另请参阅 setForegroundRole() 和backgroundRole()。

[invokable] QPixmap QWidget::grab(const QRect &rectangle = QRect(QPoint(0, 0), QSize(-1, -1)))

将控件渲染到由给定的rectangle 限制的位图中。如果控件有任何子控件，则也会将其绘制在相应的位置。

如果指定了一个尺寸无效的矩形（默认情况），则会绘制整个小部件。

另请参阅 render() 和QPixmap 。

void QWidget::grabGesture(Qt::GestureType gesture, Qt::GestureFlags flags = Qt::GestureFlags())

将小部件订阅到指定的gesture ，并设置具体的flags 。

另请参阅 ungrabGesture() 和QGestureEvent 。

void QWidget::grabKeyboard()

捕获键盘输入。

该控件将接收所有键盘事件，直到调用releaseKeyboard()；其他控件则完全无法接收键盘事件。鼠标事件不受影响。若需捕获鼠标事件，请使用grabMouse()。

焦点控件不受影响，只是它不会接收任何键盘事件。setFocus() 会照常移动焦点，但新的焦点控件只有在调用releaseKeyboard() 之后才会接收键盘事件。

如果当前有其他小部件正在捕获键盘输入，则会先释放该小部件的捕获状态。

另请参阅 releaseKeyboard()、grabMouse()、releaseMouse() 和focusWidget()。

void QWidget::grabMouse()

捕获鼠标输入。

该控件将接收所有鼠标事件，直到调用releaseMouse()为止；其他控件将完全无法接收到鼠标事件。键盘事件不受影响。若需捕获键盘事件，请使用grabKeyboard()。

在使用 Qt 时，通常无需手动捕获鼠标，因为 Qt 会合理地自动捕获和释放鼠标。特别是，当鼠标按钮被按下时，Qt 会捕获鼠标，并一直保持捕获状态直到最后一个按钮被释放。

另请参阅 releaseMouse()、grabKeyboard() 和releaseKeyboard()。

void QWidget::grabMouse(const QCursor &cursor)

捕获鼠标输入并更改光标形状。

光标将变为cursor 形状（只要鼠标焦点被捕获），并且在调用releaseMouse()之前，该控件将是唯一接收鼠标事件的控件。

另请参阅 releaseMouse()、grabKeyboard()、releaseKeyboard() 和setCursor()。

int QWidget::grabShortcut(const QKeySequence &key, Qt::ShortcutContext context = Qt::WindowShortcut)

向 Qt 的快捷键系统添加一个快捷键，该快捷键会在指定的context 中监听给定的key 序列。如果context 为Qt::ApplicationShortcut ，则该快捷键适用于整个应用程序。否则，它要么仅限于此控件（Qt::WidgetShortcut ），要么仅限于窗口本身（Qt::WindowShortcut ）。

如果同一组key 序列已被多个控件捕获，当key 序列发生时，系统会向所有适用的控件发送QEvent::Shortcut 事件，发送顺序是非确定性的，但会将``ambiguous''标志设置为true。

另请参阅 releaseShortcut() 和setShortcutEnabled()。

QGraphicsEffect *QWidget::graphicsEffect() const

graphicsEffect 函数返回指向该控件图形效果的指针。

如果小部件没有图形效果，则返回 `nullptr `。

另请参阅 setGraphicsEffect()。

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

返回图形视图中相应嵌入式控件的代理控件；否则返回nullptr 。

另请参阅 QGraphicsProxyWidget::createProxyForChildWidget() 和QGraphicsScene::addWidget()。

[virtual] bool QWidget::hasHeightForWidth() const

如果控件的首选高度取决于其宽度，则返回true ；否则返回false 。

[virtual] int QWidget::heightForWidth(int w) const

根据宽度w ，返回此控件的首选高度。

如果该控件具有布局，则默认实现返回布局的首选高度；如果没有布局，则默认实现返回 -1，表示首选高度不依赖于宽度。

[slot] void QWidget::hide()

隐藏控件。该函数与setVisible(false) 效果相同。

另请参阅 hideEvent()、isHidden()、show()、setVisible()、isVisible()，以及close()。

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

可以在子类中重新实现此事件处理程序，以接收小部件的隐藏事件。该事件通过event 参数传递进来。

小部件被隐藏后，隐藏事件会立即发送给该小部件。

注意：当窗口系统更改小部件的映射状态时，该小部件会接收自发显示和隐藏事件，例如：当用户将窗口最小化时会触发自发隐藏事件，而当窗口被恢复时会触发自发显示事件。在接收自发隐藏事件后，从isVisible()的角度来看，该小部件仍被视为可见。

另请参阅 visible 、event() 以及QHideEvent 。

[override virtual protected] void QWidget::initPainter(QPainter *painter) const

将painter 的画笔、背景和字体初始化为与给定控件相同的设置。当在QWidget 上打开绘图器时，该函数会自动调用。

[virtual protected] void QWidget::inputMethodEvent(QInputMethodEvent *event)

该事件处理程序（针对event 事件）可在子类中重新实现，以接收输入法组合事件。当输入法状态发生变化时，会调用此处理程序。

请注意，在创建自定义文本编辑控件时，必须显式设置Qt::WA_InputMethodEnabled 窗口属性（使用setAttribute()函数），才能接收输入法事件。

默认实现会调用 event->ignore()，从而拒绝该输入法事件。更多详情请参阅QInputMethodEvent 的文档。

另请参阅 event() 和QInputMethodEvent 。

[virtual] QVariant QWidget::inputMethodQuery(Qt::InputMethodQuery query) const

该方法仅适用于输入控件。输入法通过该方法查询控件的一组属性，以便支持复杂的输入法操作，例如对周边文本的支持和重新转换。

query 指定要查询的属性。

另请参阅 inputMethodEvent(),QInputMethodEvent,QInputMethodQueryEvent 以及inputMethodHints 。

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

将操作action 插入到该小部件的操作列表中，位于操作before 之前。如果before 为nullptr ，或者before 不是该小部件的有效操作，则会将该操作追加到列表末尾。

一个QWidget 应仅包含每种操作的一个实例。

另请参阅 removeAction()、addAction()、QMenu 、contextMenuPolicy 以及actions()。

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

将操作actions 插入到该控件的操作列表中，位置在操作before 之前。如果before 的值为nullptr ，或者before 不是该控件的有效操作，则将该操作追加到列表末尾。

一个QWidget 中，每种操作最多只能出现一次。

另请参阅 removeAction()、QMenu 、insertAction() 和contextMenuPolicy 。

bool QWidget::isAncestorOf(const QWidget *child) const

如果该控件是给定child 的父控件（或祖辈控件，以此类推至任意层级），且这两个控件位于同一窗口内，则返回true ；否则返回false 。

bool QWidget::isEnabledTo(const QWidget *ancestor) const

如果当ancestor 启用时，该控件也会被启用，则返回true ；否则返回false 。

当小部件本身及其所有父级（直至但不包括ancestor ）均未被显式禁用时，即满足此条件。

如果此小部件或其任何祖先小部件被显式禁用，则 isEnabledTo(0) 返回 false。

此处的“祖先”是指同一窗口内的父控件。

因此，isEnabledTo(0) 仅限于此小部件所在的窗口，这与isEnabled() 不同，后者还会考虑父窗口。

另请参阅 setEnabled() 和enabled 。

bool QWidget::isHidden() const

如果小部件处于隐藏状态，则返回true ；否则返回false 。

隐藏的小部件只有在对其调用show() 时才会显示。当父容器显示时，它不会自动显示。

要检查可见性，请改用 !isVisible()（请注意感叹号）。

isHidden() 等同于 !isVisible()，但一个小部件可能同时处于不可见且未隐藏的状态。当小部件的父级不可见时，其子级小部件即属于这种情况。

在以下情况下，控件会被隐藏：

• 它们作为独立窗口创建时，
• 作为可见控件的子控件创建时，
• hide调用了 () 或setVisible(false)。

bool QWidget::isVisibleTo(const QWidget *ancestor) const

如果当ancestor 显示时，该小部件也会变得可见，则返回true ；否则返回false 。

当小部件本身及其所有父级（直至但不包括ancestor ）均未被显式隐藏时，该条件为真。

如果小部件被屏幕上的其他窗口遮挡，但只要移动这些窗口，该小部件在物理上仍可见，则此函数仍将返回 true。

isVisibleTo(0) 与isVisible() 完全相同。

另请参阅 show()、hide() 和isVisible()。

bool QWidget::isWindow() const

如果该小部件是一个独立窗口，则返回true ；否则返回false 。

窗口是一种在视觉上不作为任何其他小部件子元素的小部件，通常具有边框和window title 。

窗口可以拥有一个parent widget 。此时，它将与其父窗口分组，并在父窗口被删除时被删除，在父窗口被最小化时被最小化等。如果窗口管理器支持，它还将与其父窗口共享一个任务栏条目。

QDialog 此外，QMainWindow 小部件默认即为窗口，即使在构造函数中指定了父小部件也是如此。此行为由Qt::Window 标志所规定。

另请参阅 window()、isModal()，以及parentWidget()。

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

该事件处理程序（针对event 事件）可在子类中重新实现，以便接收该控件的按键事件。

小部件必须调用setFocusPolicy() 来初始化焦点，并且必须处于焦点状态，才能接收按键事件。

如果您重写了此处理程序，那么如果您不处理该键，调用基类的实现就非常重要。

默认实现会在用户按下QKeySequence::Cancel 的键序列（通常是 Escape 键）时关闭弹出控件。否则，该事件将被忽略，以便控件的父控件能够对其进行解释。

请注意，QKeyEvent 开始时 isAccepted() == true，因此您无需调用QKeyEvent::accept() —— 只要您对该键采取了处理措施，就不要调用基类的实现。

另请参阅 keyReleaseEvent()、setFocusPolicy()、focusInEvent()、focusOutEvent()、event() 以及QKeyEvent 。

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

该事件处理程序（针对事件event ）可在子类中重新实现，以接收该小部件的键释放事件。

小部件必须先调用accept focus ，然后调用have focus ，才能接收键释放事件。

如果您重写了此处理程序，那么如果不对该键采取任何操作，务必调用基类的实现，这一点非常重要。

默认实现会忽略该事件，以便小部件的父级对其进行解释。

请注意，QKeyEvent 开始时 isAccepted() == true，因此您无需调用QKeyEvent::accept()——只要您对该键采取了操作，就不要调用基类的实现即可。

另请参阅 keyPressEvent()、QEvent::ignore()、setFocusPolicy()、focusInEvent()、focusOutEvent()、event() 以及QKeyEvent 。

[static] QWidget *QWidget::keyboardGrabber()

返回当前占用键盘输入的控件。

如果该应用程序中当前没有小部件占用键盘，则返回nullptr 。

另请参阅 grabMouse() 和mouseGrabber()。

QLayout *QWidget::layout() const

返回安装在此控件上的布局管理器；如果未安装任何布局管理器，则返回nullptr 。

布局管理器用于设置已添加到布局中的小部件子元素的几何属性。

另请参阅 setLayout()、sizePolicy()以及“布局管理”。

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

可以在子类中重新实现此事件处理程序，以接收通过event 参数传递的控件离开事件。

当鼠标光标离开控件时，会向该控件发送一个离开事件。

另请参阅 enterEvent()、mouseMoveEvent() 和event()。

[slot] void QWidget::lower()

将该控件移至父控件堆栈的底部。

调用此方法后，该小部件在视觉上将位于任何重叠的同级小部件之后（因此会被这些小部件遮挡）。

另请参阅 raise() 和stackUnder()。

[since 6.0] QPointF QWidget::mapFrom(const QWidget *parent, const QPointF &pos) const

将控件坐标pos 从坐标系parent 转换为该控件的坐标系。parent 不能为nullptr ，且必须是调用该控件的父控件。

该函数在 Qt 6.0 中引入。

另请参阅 mapTo()、mapFromParent()、mapFromGlobal() 以及underMouse()。

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

[since 6.0] QPointF QWidget::mapFromGlobal(const QPointF &pos) const

将全局屏幕坐标pos 转换为控件坐标。

该函数在 Qt 6.0 中引入。

另请参阅 mapToGlobal()、mapFrom() 以及mapFromParent()。

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

[since 6.0] QPointF QWidget::mapFromParent(const QPointF &pos) const

将父控件坐标pos 转换为控件坐标。

如果小部件没有父级，则与mapFromGlobal() 相同。

该函数自 Qt 6.0 起引入。

另请参阅 mapToParent()、mapFrom()、mapFromGlobal() 和underMouse()。

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

[since 6.0] QPointF QWidget::mapTo(const QWidget *parent, const QPointF &pos) const

将控件坐标pos 转换为坐标系parent 。parent 不能是nullptr ，并且必须是调用该控件的控件的父控件。

该函数在 Qt 6.0 中引入。

另请参阅 mapFrom()、mapToParent()、mapToGlobal() 和underMouse()。

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

[since 6.0] QPointF QWidget::mapToGlobal(const QPointF &pos) const

将控件坐标pos 转换为全局屏幕坐标。例如，mapToGlobal(QPointF(0,0)) 将返回控件左上角像素的全局坐标。

该函数在 Qt 6.0 中引入。

另请参阅 mapFromGlobal()、mapTo()，以及mapToParent()。

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

[since 6.0] QPointF QWidget::mapToParent(const QPointF &pos) const

将小部件坐标pos 转换为父级小部件中的坐标。

如果控件没有父控件，则与mapToGlobal() 相同。

该函数在 Qt 6.0 中引入。

另请参阅 mapFromParent()、mapTo()、mapToGlobal() 和underMouse()。

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

QRegion QWidget::mask() const

返回当前在小部件上设置的遮罩。如果未设置遮罩，则返回值为一个空区域。

另请参阅 setMask()、clearMask() 和QRegion::isEmpty()。

[override virtual protected] int QWidget::metric(QPaintDevice::PaintDeviceMetric m) const

重写了：QPaintDevice::metric(QPaintDevice::PaintDeviceMetric metric) const。

虚拟函数QPaintDevice::metric() 的内部实现。

m 是要获取的度量。

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

该事件处理程序（针对event 事件）可在子类中重新实现，以接收该控件的鼠标双击事件。

默认实现会调用mousePressEvent()。

另请参阅 mousePressEvent()、mouseReleaseEvent()、mouseMoveEvent()、event() 以及QMouseEvent 。

[static] QWidget *QWidget::mouseGrabber()

返回当前捕获鼠标输入的控件。

如果该应用程序中当前没有小部件捕获鼠标，则返回nullptr 。

另请参阅 grabMouse() 和keyboardGrabber()。

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

该事件处理程序（针对event 事件）可在子类中重新实现，以接收该控件的鼠标移动事件。

如果关闭了鼠标跟踪功能，则只有在移动鼠标的同时按下鼠标按钮时，才会触发鼠标移动事件。如果启用了鼠标跟踪功能，即使未按下任何鼠标按钮，也会触发鼠标移动事件。

QMouseEvent::position() 报告相对于该小部件的鼠标光标位置。对于按下和释放事件，该位置通常与上一次鼠标移动事件的位置相同，但如果用户的手在抖动，位置可能会有所不同。这是底层窗口系统的特性，而非 Qt Widgets 的特性。

如果您希望在鼠标移动时立即显示工具提示（例如，通过QMouseEvent::position() 获取鼠标坐标并将其作为工具提示显示），则必须首先按照上述说明启用鼠标跟踪。 然后，为了确保工具提示能立即更新，在实现 mouseMoveEvent() 时，必须调用QToolTip::showText() 而不是setToolTip()。

另请参阅 setMouseTracking()、mousePressEvent()、mouseReleaseEvent()、mouseDoubleClickEvent()、event()、QMouseEvent 以及Scribble 示例。

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

该事件处理程序（针对event 事件）可在子类中重新实现，以接收该小部件的鼠标按下事件。

如果你在 `mousePressEvent()` 中创建了新的控件，那么 `mouseReleaseEvent()` 可能不会如你所愿地结束执行，这取决于底层窗口系统（或 X11 窗口管理器）、控件的位置以及其他因素。

默认实现会在您点击窗口外部时关闭弹出小部件。对于其他类型的小部件，它不会执行任何操作。

另请参阅 mouseReleaseEvent()、mouseDoubleClickEvent()、mouseMoveEvent()、event()、QMouseEvent 以及Scribble 示例。

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

该事件处理程序（针对event 事件）可在子类中重新实现，以接收该控件的鼠标释放事件。

另请参阅 mousePressEvent()、mouseDoubleClickEvent()、mouseMoveEvent()、event()、QMouseEvent 以及“涂鸦示例”。

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

这对应于 move(QPoint(x,y))。

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

可以在子类中重新实现此事件处理程序，以接收通过event 参数传递的控件移动事件。当控件接收到此事件时，它已位于新位置。

可通过QMoveEvent::oldPos() 获取旧位置。

另请参阅 resizeEvent()、event()、move() 以及QMoveEvent 。

[virtual protected] bool QWidget::nativeEvent(const QByteArray &eventType, void *message, qintptr *result)

可以在子类中重写此特殊事件处理程序，以接收由eventType 标识的原生平台事件，这些事件通过message 参数传递进来。

在重写此函数时，若要阻止 Qt 处理该事件，请返回 true 并设置result 。result 参数仅在 Windows 系统上有效。若返回 false，则该本机事件将回传给 Qt，Qt 会将其转换为 Qt 事件并发送给小部件。

另请参阅 QAbstractNativeEventFilter 。

QWidget *QWidget::nativeParentWidget() const

返回此控件的原生父控件，即具有系统标识符的下一个祖先控件；如果该控件没有原生父控件，则返回nullptr 。

另请参阅 effectiveWinId()。

QWidget *QWidget::nextInFocusChain() const

返回该控件焦点链中的下一个控件。

另请参阅 previousInFocusChain()。

void QWidget::overrideWindowFlags(Qt::WindowFlags flags)

将控件的窗口标志设置为flags ，但不会通知窗口系统。

另请参阅 setWindowFlags()。

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

重写：QPaintDevice::paintEngine() const。

返回小部件的绘制引擎。

请注意，用户不应显式调用此函数，因为它仅用于重写目的。该函数由 Qt 在内部调用，且默认实现并不总是返回有效的指针。

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

可以在子类中重写此事件处理程序，以接收通过event 传递的绘制事件。

绘制事件是要求重新绘制小部件全部或部分内容的请求。它可能因以下任一原因而触发：

• repaint() 或update() 被调用，
• 控件曾被遮挡，现已恢复可见，或
• 以及其他多种原因。

许多控件在收到请求时可以直接重绘其整个表面，但某些运行较慢的控件需要通过仅重绘请求区域来优化性能：QPaintEvent::region()。这种速度优化不会改变结果，因为在事件处理过程中，重绘操作会被裁剪到该区域内。例如，QListView 和QTableView 就采用了这种做法。

Qt 还会通过将多个绘制事件合并为一个来尝试加快绘制速度。当update() 被多次调用，或者窗口系统发送了多个绘制事件时，Qt 会将这些事件合并为一个绘制区域更大的事件（参见QRegion::united()）。repaint() 函数不支持此优化，因此我们建议尽可能使用update()。

当绘制事件发生时，更新区域通常已被清空，因此您是在小部件的背景上进行绘制。

背景可通过setBackgroundRole() 和setPalette() 进行设置。

自 Qt 4.0 以来，QWidget 会自动对绘制操作进行双缓冲，因此无需在 paintEvent() 中编写双缓冲代码来避免闪烁。

另请参阅 event()、repaint()、update()、QPainter 、QPixmap 、QPaintEvent 以及Analog Clock。

QWidget *QWidget::parentWidget() const

返回该控件的父控件；如果该控件没有父控件，则返回nullptr 。

QWidget *QWidget::previousInFocusChain() const

InFocusChain 函数返回该小部件焦点链中的上一个小部件。

另请参阅 ` nextInFocusChain()`。

[slot] void QWidget::raise()

将此控件提升至父控件堆栈的最顶层。

调用此函数后，该控件在视觉上将位于任何重叠的同级控件之前。

另请参阅 lower() 和stackUnder()。

void QWidget::releaseKeyboard()

释放键盘锁定。

另请参阅 grabKeyboard()、grabMouse() 和releaseMouse()。

void QWidget::releaseMouse()

释放鼠标抓取。

另请参阅 grabMouse()、grabKeyboard()，以及releaseKeyboard()。

void QWidget::releaseShortcut(int id)

从 Qt 的快捷键系统中删除具有指定id 的快捷键。该控件将不再接收针对该快捷键键序列的QEvent::Shortcut 事件（除非该控件还有其他具有相同键序列的快捷键）。

另请参阅 grabShortcut() 和setShortcutEnabled()。

void QWidget::removeAction(QAction *action)

从该控件的操作列表中移除操作action 。

另请参阅 insertAction() 和actions()。

void QWidget::render(QPaintDevice *target, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion(), QWidget::RenderFlags renderFlags = RenderFlags(DrawWindowBackground | DrawChildren))

将此控件的sourceRegion 渲染到target 中，并使用renderFlags 来确定渲染方式。渲染从target 中的targetOffset 开始。例如：

QPixmap pixmap(widget->size());
widget->render(&pixmap);

如果sourceRegion 是一个空区域，则该函数将使用QWidget::rect()作为区域，即整个小部件。

请确保在渲染之前，为target 设备的活动绘制器（如有）调用QPainter::end()。例如：

QPainter painter(this);
...
painter.end();
myWidget->render(this);

void QWidget::render(QPainter *painter, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion(), QWidget::RenderFlags renderFlags = RenderFlags(DrawWindowBackground | DrawChildren))

将控件渲染到painter 的QPainter::device()中。

渲染时将应用painter 上已设置的变换和配置。

另请参阅 QPainter::device()。

[slot] void QWidget::repaint()

通过立即调用 `paintEvent()` 直接重绘控件，除非更新已被禁用或控件处于隐藏状态。

我们建议仅在需要立即重绘时（例如在动画过程中）才使用 repaint()。在大多数情况下，update() 是更好的选择，因为它允许 Qt 进行速度优化并最大限度地减少闪烁。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        widget, qOverload<>(&QWidget::repaint));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        widget, [receiver = widget]() { receiver->repaint(); });

另请参阅 update()、paintEvent() 和setUpdatesEnabled()。

void QWidget::repaint(const QRect &rect)

此版本会重新绘制控件内部的一个矩形rect 。

void QWidget::repaint(const QRegion &rgn)

此版本会重新绘制控件内的区域rgn 。

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

此版本会重绘小部件内部的一个矩形（x 、y 、w 、h ）。

如果w 为负数，则将其替换为width() - x ；如果h 为负数，则将其替换为height() - y 。

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

这对应于 resize(QSize(w,h))。

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

可以在子类中重写此事件处理程序，以接收通过event 参数传递的控件重设大小事件。当调用resizeEvent()时，控件已具有新的几何属性。可通过QResizeEvent::oldSize()获取旧的大小。

在处理完调整大小事件后，控件将立即被清空并接收一个绘制事件。无需（也不应）在此处理程序内进行任何绘制操作。

另请参阅 moveEvent()、event()、resize()、QResizeEvent 、paintEvent() 以及Scribble 示例。

bool QWidget::restoreGeometry(const QByteArray &geometry)

恢复存储在字节数组geometry 中的顶级控件的几何形状和状态。成功时返回true ；否则返回false 。

如果恢复后的几何位置超出屏幕范围，系统会将其调整为位于可用屏幕几何范围之内。

要恢复使用QSettings 保存的几何信息，可以使用如下代码：

QSettings settings("MyCompany", "MyApp");
myWidget->restoreGeometry(settings.value("myWidget/geometry").toByteArray());

有关窗口几何相关问题的概述，请参阅“窗口几何”文档。

使用QMainWindow::restoreState() 来恢复几何形状以及工具栏和停靠小部件的状态。

另请参阅 saveGeometry()、QSettings 、QMainWindow::saveState() 和QMainWindow::restoreState()。

QByteArray QWidget::saveGeometry() const

保存顶级控件的当前几何形状和状态。

若要在窗口关闭时保存几何尺寸，可以像这样实现一个关闭事件：

void MyWidget::closeEvent(QCloseEvent *event)
{
    QSettings settings("MyCompany", "MyApp");
    settings.setValue("geometry", saveGeometry());
    QWidget::closeEvent(event);
}

有关窗口几何形状问题的概述，请参阅“窗口几何形状”文档。

使用 `QMainWindow::saveState()` 来保存工具栏和停靠控件的几何尺寸及状态。

另请参阅 restoreGeometry()、QMainWindow::saveState() 和QMainWindow::restoreState()。

QScreen *QWidget::screen() const

返回该控件所在的屏幕。

另请参阅 setScreen() 和windowHandle()。

void QWidget::scroll(int dx, int dy)

将小部件及其子项向右滚动dx 像素，向下滚动dy 像素。dx 和dy 均可为负值。

滚动完成后，小部件将收到需要重绘区域的绘制事件。对于 Qt 识别为不透明的小部件，仅需更新新暴露的部分。例如，如果将一个不透明的小部件向左滚动 8 像素，则只需更新右边缘处一条 8 像素宽的条带。

由于小部件默认会传播其父项的内容，您需要设置autoFillBackground 属性，或使用setAttribute()来设置Qt::WA_OpaquePaintEvent 属性，才能使小部件变为不透明。

对于使用内容传播的小部件，滚动操作将导致整个滚动区域更新。

另请参阅 Transparency and Double Buffering 。

void QWidget::scroll(int dx, int dy, const QRect &r)

此版本仅滚动 `r `，不会移动该控件的子元素。

如果r 为空或无效，则结果未定义。

另请参阅 QScrollArea 。

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

如果 `on ` 为真，则设置此控件的 `attribute ` 属性；否则清除该属性。

另请参阅 testAttribute()。

void QWidget::setBackgroundRole(QPalette::ColorRole role)

将控件的背景角色设置为role 。

背景角色定义了用于渲染背景的、来自控件palette 的画笔。

如果 `role ` 为 `QPalette::NoRole`，则小部件将继承其父级小部件的背景角色。

请注意，样式可以从调色板中自由选择任何颜色。如果使用 setBackgroundRole() 无法达到预期效果，您可以修改调色板或设置样式表。

另请参阅 backgroundRole() 和foregroundRole()。

void QWidget::setBaseSize(int basew, int baseh)

这相当于 setBaseSize(QSize(basew,baseh))。将小部件的基础尺寸设置为宽度basew 和高度baseh 。

另请参阅 baseSize()。

void QWidget::setContentsMargins(int left, int top, int right, int bottom)

将小部件内容周围的边距设置为left 、top 、right 和bottom 。这些边距由布局系统使用，子类也可利用它们来指定绘制区域（例如，不包括边框）。

更改边距将触发resizeEvent()。

另请参阅 contentsRect() 和contentsMargins()。

void QWidget::setContentsMargins(const QMargins &margins)

setContentsMargins 函数用于设置控件内容周围的边距。

将小部件内容周围的边距大小设置为由 `margins` 确定的值。这些边距由布局系统使用，子类也可利用它们来指定绘制区域（例如，排除边框）。

更改边距将触发一个 `resizeEvent()` 事件。

另请参阅 contentsRect()和contentsMargins()。

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

如果 `disable ` 为 `true`，则禁用小部件的输入事件；否则启用输入事件。

有关更多信息，请参阅enabled 的文档。

另请参阅 isEnabledTo()、QKeyEvent 、QMouseEvent 以及changeEvent()。

void QWidget::setFixedHeight(int h)

将控件的最小高度和最大高度均设置为h ，同时保持宽度不变。此功能仅为方便起见而提供。

另请参见 sizeHint()、minimumSize()、maximumSize() 以及setFixedSize()。

void QWidget::setFixedSize(const QSize &s)

将控件的最小和最大尺寸均设置为s ，从而防止其扩大或缩小。

这将覆盖由QLayout 设定的默认尺寸约束。

要取消约束，请将大小设置为 `QWIDGETSIZE_MAX`。

或者，如果您希望小部件根据其内容具有固定大小，可以调用QLayout::setSizeConstraint （QLayout::SetFixedSize ）；

另请参阅 maximumSize 和minimumSize 。

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

将控件的宽度设置为w ，高度设置为h 。

void QWidget::setFixedWidth(int w)

将控件的最小宽度和最大宽度均设置为w ，同时保持高度不变。此功能仅为方便起见而提供。

另请参阅 sizeHint()、minimumSize()、maximumSize() 和setFixedSize()。

void QWidget::setFocus(Qt::FocusReason reason)

如果该控件或其父控件之一是active window ，则将键盘输入焦点赋予该控件（或其焦点代理）。reason 参数将被传递给该函数发出的任何焦点事件，用于说明导致该控件获得焦点的原因为何。 如果窗口当前非活动状态，则当窗口变为活动状态时，该小部件将获得焦点。

首先，会向焦点控件（如有）发送一个“焦点即将改变”事件，以告知其即将失去焦点。 随后焦点发生切换：系统会向先前拥有焦点的控件发送“焦点移出”事件，并向新获得焦点的控件发送“焦点进入”事件，以告知其刚刚获得了焦点。（如果“焦点进入”和“焦点移出”的控件是同一个，则不会发生任何操作。）

setFocus() 会将焦点赋予小部件，无论其焦点策略如何，但不会清除任何键盘锁定（参见grabKeyboard()）。

请注意，如果小部件处于隐藏状态，则在显示之前不会接受焦点。

另请参阅 hasFocus()、clearFocus()、focusInEvent()、focusOutEvent()、setFocusPolicy()、focusWidget()、QApplication::focusWidget()、grabKeyboard()、grabMouse()、小部件中的键盘焦点以及QEvent::RequestSoftwareInputPanel 。

[slot] void QWidget::setFocus()

如果该控件或其父控件之一是active window ，则将键盘输入焦点赋予该控件（或其焦点代理）。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        widget, qOverload<>(&QWidget::setFocus));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        widget, [receiver = widget]() { receiver->setFocus(); });

void QWidget::setFocusProxy(QWidget *w)

将控件的焦点代理设置为控件w 。如果w 的值为nullptr ，则该函数会将此控件重置为不设置焦点代理。

某些控件可以“获得焦点”，但会创建一个子控件（例如QLineEdit ）来实际处理焦点。在这种情况下，该控件可以将行编辑框设置为其焦点代理。

setFocusProxy() 用于设置当“此控件”获得焦点时，实际接收焦点的控件。如果存在焦点代理，则setFocus() 和hasFocus() 将对该焦点代理进行操作。如果“此控件”本身即是焦点控件，则 setFocusProxy() 会将焦点转移到新的焦点代理上。

另请参阅 focusProxy()。

void QWidget::setForegroundRole(QPalette::ColorRole role)

将控件的前景色设置为role 。

前景角色定义了从控件的palette 中提取的、用于绘制前景的颜色。

如果role 为QPalette::NoRole ，则小部件将使用与背景角色形成对比的前景角色。

请注意，样式可以从调色板中自由选择任何颜色。如果使用 setForegroundRole() 无法达到预期效果，您可以修改调色板或设置样式表。

另请参阅 foregroundRole() 和backgroundRole()。

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

这对应于 setGeometry(QRect(x,y,w,h))。

另请参阅 geometry()。

void QWidget::setGraphicsEffect(QGraphicsEffect *effect)

setGraphicsEffect 函数用于设置控件的图形效果。

将effect 设置为控件的效果。如果该控件上已经安装了效果，QWidget 会在安装新的effect 之前删除现有效果。

如果effect 是安装在另一个小部件上的效果，setGraphicsEffect() 将从该小部件上移除该效果，并将其安装到此小部件上。

QWidget 将effect 的所有权移交。

另请参阅 graphicsEffect()。

[slot] void QWidget::setHidden(bool hidden)

便捷函数，等同于setVisible(!hidden)。

另请参见 isHidden()。

void QWidget::setLayout(QLayout *layout)

将此控件的布局管理器设置为layout 。

如果该小部件上已经安装了布局管理器，则QWidget 不允许您安装另一个。您必须先删除现有的布局管理器（由layout()返回），然后才能使用新的布局调用setLayout()。

如果 `layout ` 是另一个小部件的布局管理器，`setLayout()` 会重新关联该布局，并将其设为此小部件的布局管理器。

示例：

QVBoxLayout *layout = new QVBoxLayout;
layout->addWidget(formWidget);
formWidget->setLayout(layout);

除了调用此函数外，另一种方法是将该小部件传递给布局的构造函数。

QWidget 将接管layout 的所有权。

另请参阅 ` layout()`和“布局管理”。

void QWidget::setMask(const QBitmap &bitmap)

仅使那些在bitmap 中对应的1位所对应的控件像素可见。如果该区域包含控件rect()范围之外的像素，则该区域内的窗口系统控件是否可见，取决于具体平台。

请注意，如果该区域特别复杂，此操作可能会比较慢。

以下代码演示了如何使用带 alpha 通道的图像为小部件生成蒙版：

QLabel topLevelLabel;
QPixmap pixmap(":/images/tux.png");
topLevelLabel.setPixmap(pixmap);
topLevelLabel.setMask(pixmap.mask());

该代码中显示的标签使用其包含的图像进行遮罩处理，从而呈现出仿佛将不规则形状的图像直接绘制在屏幕上的视觉效果。

经过蒙版处理的小部件仅在其可见部分接收鼠标事件。

另请参阅 mask()、clearMask() 和windowOpacity()。

void QWidget::setMask(const QRegion &region)

仅使小部件中与region 重叠的部分可见。如果该区域包含小部件rect()范围外的像素，则该区域内的窗口系统控件是否可见将取决于平台。

由于QRegion 允许创建任意复杂的区域，因此可以制作适合形状最不规则的窗口的控件遮罩，甚至允许显示带有孔洞的控件。请注意，如果区域特别复杂，此效果可能会导致性能下降。

控件遮罩用于向窗口系统提示：应用程序不希望处理遮罩区域外的鼠标事件。在大多数系统中，它们还会导致粗糙的视觉裁剪。若要获得平滑的窗口边缘，请改用半透明背景和抗锯齿绘制，如“半透明背景”示例中所示。

另请参阅 windowOpacity 。

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

该函数对应于 setMaximumSize(QSize(maxw,maxh))。将最大宽度设置为maxw ，最大高度设置为maxh 。

另请参阅 maximumSize()。

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

该函数对应于 setMinimumSize(QSize(minw, minh))。将最小宽度设置为minw ，将最小高度设置为minh 。

另请参阅 minimumSize()。

void QWidget::setParent(QWidget *parent)

将控件的父控件设置为parent ，并重置窗口标志。该控件将被移动到其新父控件中的位置 (0, 0)。

如果新的父控件位于另一个窗口中，则被重新设置父控件的控件及其子控件将按与之前相同的内部顺序，追加到新父控件的tab chain 的末尾。如果被移动的控件中有某个控件拥有键盘焦点，setParent()会为该控件调用clearFocus()。

如果新父控件与旧父控件位于同一窗口中，则设置父控件不会改变标签顺序或键盘焦点。

如果“新”父控件即为旧父控件，则此函数不执行任何操作。

另请参阅 setWindowFlags()。

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

该函数还接受小部件标志（f ）作为参数。

void QWidget::setScreen(QScreen *screen)

将小部件应显示的屏幕设置为screen 。

仅对窗口而言，设置屏幕才有意义。如有必要，小部件的窗口将在screen 上重新创建。

另请参阅 screen() 和QWindow::setScreen()。

void QWidget::setShortcutAutoRepeat(int id, bool enable = true)

如果enable 为真，则启用具有给定id 的快捷键自动重复功能；否则，该功能被禁用。

另请参阅 grabShortcut() 和releaseShortcut()。

void QWidget::setShortcutEnabled(int id, bool enable = true)

如果 `enable ` 为真，则启用具有给定 `id ` 的快捷键；否则，该快捷键将被禁用。

另请参阅 grabShortcut() 和releaseShortcut()。

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

将 x 轴（宽度）的增量设置为w ，将 y 轴（高度）的增量设置为h 。

另请参阅 sizeIncrement()。

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

将控件的大小策略设置为horizontal 和vertical ，采用标准拉伸模式，且不使用“按宽度设定高度”功能。

另请参阅 sizePolicy() 和QSizePolicy::QSizePolicy()。

void QWidget::setStyle(QStyle *style)

将控件的 GUI 样式设置为style 。样式对象的所有权不会被转移。

如果未设置样式，小部件将改用应用程序的默认样式QApplication::style()。

设置控件的样式对现有或未来的子控件没有任何影响。

另请参阅 style()、QStyle 、QApplication::style() 和QApplication::setStyle()。

[static] void QWidget::setTabOrder(QWidget *first, QWidget *second)

将second 控件在焦点顺序中置于first 控件之后。

这实际上将second 控件从其焦点链中移除，并将其插入到first 控件之后。

请注意，由于second 控件的焦点顺序已发生改变，您应按如下方式排列链条：

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

而不是像这样：

// 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

如果first 或second 具有焦点代理，setTabOrder() 会正确地替换该代理。

另请参阅 setFocusPolicy()、setFocusProxy() 以及“控件中的键盘焦点”。

[static, since 6.6] void QWidget::setTabOrder(std::initializer_list<QWidget *> widgets)

通过为每对连续的小部件调用 `QWidget::setTabOrder(QWidget *, QWidget *)`，来设置 `widgets ` 列表中小部件的焦点顺序。

与其像这样手动设置每一对控件：

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

您可以调用：

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

该调用不会形成封闭的Tab焦点循环。如果还有其他采用Qt::TabFocus 焦点策略的小部件，在d 上按Tab键将把焦点移至其中一个小部件，而不会返回a 。

该函数在 Qt 6.6 中引入。

另请参阅 setFocusPolicy()、setFocusProxy()，以及“控件中的键盘焦点”。

void QWidget::setWindowFlag(Qt::WindowType flag, bool on = true)

如果on 为真，则在此控件上设置窗口标志flag ；否则清除该标志。

另请参阅 setWindowFlags()、windowFlags() 和windowType()。

void QWidget::setWindowRole(const QString &role)

将窗口的角色设置为role 。此设置仅对X11上的窗口有效。

另请参阅 windowRole()。

void QWidget::setWindowState(Qt::WindowStates windowState)

将窗口状态设置为windowState 。窗口状态是Qt::WindowState 、Qt::WindowMinimized 、Qt::WindowMaximized 、Qt::WindowFullScreen 和Qt::WindowActive 的按“或”运算组合。

如果窗口不可见（即isVisible() 返回false ），则在调用show() 时，窗口状态才会生效。对于可见窗口，更改会立即生效。例如，要在全屏模式和普通模式之间切换，请使用以下代码：

w->setWindowState(w->windowState() ^ Qt::WindowFullScreen);

要恢复并激活一个已最小化的窗口（同时保留其最大化及/或全屏状态），请使用以下代码：

w->setWindowState((w->windowState() & ~Qt::WindowMinimized) | Qt::WindowActive);

调用此函数将隐藏该控件。您必须调用show() 才能使该控件再次可见。

当窗口状态发生变化时，控件会收到类型为 `QEvent::WindowStateChange` 的 `changeEvent()` 事件。

另请参阅 Qt::WindowState 和windowState()。