QWidget类

成员函数文档

这些便利函数创建一个新的动作，具有文本text、图标icon和快捷键shortcut，如果有。

这些函数将新创建的动作添加到部件的动作列表中，并返回它。

QWidget 接管返回的 QAction 的所有权。

此函数自Qt 6.3起引入。

这是一个重载函数。

此便利函数创建一个带文本 text、图标 icon 和快捷键 shortcut（如果有）的新操作。

操作触发信号的 triggered() 与接收者 receiver 的 member 端口连接。函数将新创建的操作添加到小部件的操作列表中，并返回它。

QWidget 接管返回的 QAction 的所有权。

此函数自Qt 6.3起引入。

这是一个重载函数。

这些便捷函数将为文本 text、图标 icon 和快捷键 shortcut 创建一个新动作。

该动作的 triggered() 信号被连接，就像调用 QObject::connect(action, &QAction::triggered, args...)) 一样，完美地传递了 args，包括可能的 Qt::ConnectionType。

此函数将新创建的动作添加到小部件的动作列表，并返回它。

QWidget 接管返回的 QAction 的所有权。

此函数自Qt 6.3起引入。

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

构建一个子窗口 parent，并将窗口标志设置为 f。

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

窗口标志参数 f 通常为 0，但可以设置来自定义窗口框架（即 parent 必须是 nullptr）。要自定义框架，请使用组合任意窗口标志的逐位或值。

如果你将子窗口添加到已经可见的小部件，你必须显式显示子窗口才能使其可见。

请注意，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 添加到此小部件的操作列表中。

所有 QWidgets 都包含一个 QAction 列表。但是，它们可以以许多不同的方式图形表示。默认情况下，使用 QAction 列表（如actions() 返回的）是为了创建一个上下文 QMenu。

QWidget 应只包含一个每种操作，添加同一个操作不会使得相同的操作在 widget 中出现两次。

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

另见 removeAction()，insertAction()，actions()，以及 QMenu。

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

将操作 actions 添加到此小部件的操作列表中。

另见 removeAction()，QMenu，以及 addAction。

void QWidget::adjustSize()

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

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

对于窗口，也考虑了屏幕大小。如果《a href="qwidget.html#sizeHint-prop" translate="no">sizeHint() 小于（200，100）并且大小策略是 expanding，则窗口至少为（200，100）。窗口的最大大小是屏幕宽度和大小的 2/3。

另见 sizeHint() 和 childrenRect。

QPalette::ColorRole QWidget::backgroundRole() const

返回小部件的后台角色。

后台角色定义了从小部件的 palette 中使用以渲染后台的画笔。

如果没有设置明确的背景角色，小部件将继承其父小部件的背景角色。

另请参阅 setBackgroundRole() 和 foregroundRole。

QBackingStore *QWidget::backingStore() const

返回将在这个小部件中绘制的 QBackingStore。

[虚保护] 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 的可见子控件。

void QWidget::clearFocus()

将键盘输入焦点从控件中移除。

如果控件有活动焦点，将发送一个 focus out event 到此控件，告诉它已失去焦点。

这个控件必须启用焦点设置来获取键盘输入焦点；也就是说，它必须调用 setFocusPolicy。

另请参阅 hasFocus()、setFocus()、focusInEvent()、focusOutEvent()、setFocusPolicy() 和 QApplication::focusWidget

void QWidget::clearMask()

移除通过 setMask 设置的任何掩码。

另请参阅setMask。

[槽] bool QWidget::close()

关闭此控件。如果控件已关闭则返回 true，否则返回 false。

首先，它会向小部件发送一个QCloseEvent。如果小部件接受关闭事件，它会被隐藏。如果它忽略了事件，则不会发生任何事。QWidget::closeEvent()的默认实现接受关闭事件。

如果小部件具有Qt::WA_DeleteOnClose标志，则小部件也会被删除。无论小部件是否可见，都会向小部件传递关闭事件。

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

[虚保护] 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。

[保护] void QWidget::contextMenuEvent(QContextMenuEvent *event)

此事件处理器，针对event事件，可以在子类中重新实现以接收小部件上下文菜单事件。

当小部件的contextMenuPolicy为Qt::DefaultContextMenu时，会调用处理器。

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

另请参阅event、QContextMenuEvent和customContextMenuRequested。

[保护] void QWidget::create(WId 窗口 = 0, bool initializeWindow = true, bool destroyOldWindow = true)

创建新的小部件窗口。

在 Qt 5 中，参数 window，initializeWindow 以及 destroyOldWindow 被忽略。请使用 QWindow::fromWinId() 创建一个包装外部窗口的 QWindow，并将其传递给 QWidget::createWindowContainer()。

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

[静态] 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 的子节点使用时，它将为其父链中的每个小部件创建一个原生窗口，以允许在当前用例中进行适当的堆叠和剪裁。为窗口容器创建原生窗口也允许进行适当的堆叠和剪裁。这必须在显示窗口容器之前完成。拥有许多原生子窗口的应用程序可能会出现性能问题。

窗口容器有几个已知的限制

• 堆叠顺序；嵌入的窗口将作为一个不透明的盒子堆叠在部件层次结构的顶部。多个重叠窗口容器实例的堆叠顺序是未定义的。
• 渲染集成；窗口容器不与 QGraphicsProxyWidget，QWidget::render() 或类似功能交互。
• 焦点处理；窗口容器实例可以具有任何焦点策略，并将焦点通过调用 QWindow::requestActivate() 传递给窗口。但是，从 QWindow 实例返回的正常焦点链将由 QWindow 实例实现自行处理。例如，当进入基于 Qt Quick 的窗口并使用标签焦点时，进一步按标签键很可能会导致仅循环在 QML 应用程序内。此外，QWindow::requestActivate() 是否真正给予窗口焦点，取决于平台。
• 在一个基于 QWidget 的应用程序中使用许多窗口容器实例，可能会极大地损害应用程序的整体性能。
• 从 6.7 版本开始，如果 window 属于一个部件（即，window 是在调用 windowHandle() 时接收的），则不会创建容器。相反，此函数将在将窗口重新父化为 parent 后返回该部件本身。由于不会创建容器，flags 将被忽略。换句话说，如果 window 属于一个部件，请考虑只将此部件重新父化为 parent，而不是使用此函数。

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

当小部件的 contextMenuPolicy 为 Qt::CustomContextMenu，并且用户在小部件上请求了上下文菜单时，会发射这个信号。位置 pos 是小部件收到的上下文菜单事件的坐标。通常这发生在小部件坐标内。对此规则的一个例外是 QAbstractScrollArea 及其子类，它们将上下文菜单事件映射到 viewport 的坐标。

另请参阅mapToGlobal()，QMenu，和 contextMenuPolicy。

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

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

destroy() 会递归地对所有子小部件进行调用，为 destroyWindow 参数传递 destroySubWindows。要更精细地控制子小部件的销毁，先选择性销毁子小部件。

此函数通常从小部件的析构函数中调用。

[虚保护] void QWidget::dragEnterEvent(QDragEnterEvent *event)

当鼠标拖拽动作正在进行并进入此小部件时，调用此事件处理器。事件通过 event 参数传递。

如果忽略事件，则小部件不会接收到任何 拖拽事件。

有关如何在应用中提供拖拽操作的概述，请参阅拖拽和放置文档。

另请参阅QDrag 和 QDragEnterEvent。

[虚保护] void QWidget::dragLeaveEvent(QDragLeaveEvent *event)

当鼠标拖拽动作正在进行并离开此小部件时，调用此事件处理器。事件通过 event 参数传递。

有关如何在应用中提供拖拽操作的概述，请参阅拖拽和放置文档。

另请参阅QDrag 和 QDragLeaveEvent。

[虚保护] void QWidget::dragMoveEvent(QDragMoveEvent *event)

鼠标拖拽动作正在进行时，满足以下条件之一时调用此事件处理器：光标进入此小部件、光标在此小部件内移动或按下键盘上的修饰键而此小部件获得焦点。事件通过 event 参数传递。

有关如何在应用中提供拖拽操作的概述，请参阅拖拽和放置文档。

另请参阅QDrag 和 QDragMoveEvent。

[虚保护] void QWidget::dropEvent(QDropEvent *event)

当鼠标拖拽动作在此小部件上放下时，调用此事件处理器。事件通过 event 参数传递。

有关如何在应用中提供拖拽操作的概述，请参阅拖拽和放置文档。

另请参阅QDrag 和 QDropEvent。

WId QWidget::effectiveWinId() const

返回小部件的有效窗口系统标识符，即原生父窗口的窗口系统标识符。

如果小部件是本地的，则此函数返回原生小部件ID。否则，返回第一个原生父小部件的窗口ID，即包含此小部件的顶级小部件。

另请参阅：nativeParentWidget()。

void QWidget::ensurePolished() const

确保小部件及其子部件已被QStyle（即，具有适当的字体和调色板）修饰。

QWidget在完全构建后、首次显示之前调用此函数。如果您想在小部件修饰前进行操作（例如，在重写sizeHint()时可能需要正确的字体大小），您可以调用此函数。请注意，此函数从sizeHint()的默认实现中调用。

修饰对于在所有构造函数（无论是基类还是子类的）调用之后发生的最终初始化很有用。

如果您需要在修饰小部件时更改某些设置，重写event()并处理QEvent::Polish事件类型。

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

另请参阅：event()。

[虚拟保护] void QWidget::enterEvent(QEnterEvent *event)

可以在此子类中重写此事件处理器以接收包含在event参数中的小部件进入事件。

当鼠标光标进入小部件时向小部件发送事件。

另请参阅：leaveEvent ()，mouseMoveEvent ()和event()。

[覆盖虚拟保护] 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。

[静态] QWidget *QWidget::find(WId id)

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

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

[虚保护] void QWidget::focusInEvent(QFocusEvent *event)

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

小部件通常必须设置 focusPolicy() 为非 Qt::NoFocus 以接收焦点事件。（注意，应用程序程序员可以在任何小部件上调用 setFocus()，即使那些通常不接受焦点的小部件也可以。）

默认实现更新小部件（除未指定 focusPolicy 的窗口外）。

另请参阅 focusOutEvent，setFocusPolicy，keyPressEvent，keyReleaseEvent，event 和 QFocusEvent

[保护] bool QWidget::focusNextChild()

查找一个新的小部件来提供键盘焦点，如有效用于 Tab，并在找到新的小部件时返回 true，或者在无法找到新的小部件时返回 false。

另请参阅 focusPreviousChild

[虚保护] bool QWidget::focusNextPrevChild(bool next)

查找一个新的小部件来提供键盘焦点，如有效用于 Tab 和 Shift+Tab，并在找到新的小部件时返回 true，或者在无法找到新的小部件时返回 false。

如果 next 为true，则查找向前，如果 next 为 false，则查找向后。

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

子小部件在其父小部件上调用 focusNextPrevChild()，但只有包含子小部件的窗口决定在哪里重新定向焦点。通过为对象重新实现此函数，您可以控制所有子小部件的焦点遍历。

另请参阅 focusNextChild() 和 focusPreviousChild

[虚拟受保护] void QWidget::focusOutEvent(QFocusEvent *event)

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

小部件通常必须设置 focusPolicy() 为非 Qt::NoFocus 以接收焦点事件。（注意，应用程序程序员可以在任何小部件上调用 setFocus()，即使那些通常不接受焦点的小部件也可以。）

默认实现更新小部件（除未指定 focusPolicy 的窗口外）。

另请参阅focusInEvent()，setFocusPolicy()，keyPressEvent()，keyReleaseEvent()，event()和QFocusEvent。

[受保护] 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

返回前景角色。

前景角色定义了从组件的QPalette中使用的颜色，用于绘制前景。

如果没有设置显式的 foregroundRole，则函数返回一个与背景角色形成对比的角色。

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

[调用者可为此调用函数] 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)

此函数重载了 QWidget::grabMouse。

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

光标将具备 cursor 形状（在使用鼠标捕获焦点期间），并且直到调用 releaseMouse()，该小部件将是唯一接收到鼠标事件的小部件。

参见 releaseMouse()，grabKeyboard()，releaseKeyboard() 和 setCursor()。

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

向 Qt 的快捷键系统添加一个快捷键，该快捷键会在给定的 key 序列和 context 中监控。如果 context 是 Qt::ApplicationShortcut，则此快捷键适用于整个应用程序。否则，它可以是此小部件的本地快捷键，Qt::WidgetShortcut，或者自身的窗口快捷键，Qt::WindowShortcut。

如果有多个小部件已经抓取了相同的 key 序列，当此 key 序列触发时，会向所有相关联的小部件发送非确定顺序的 QEvent::Shortcut 事件，但带有设置为 true 的“模糊”标志。

参见 releaseShortcut() 和 setShortcutEnabled()。

QGraphicsEffect *QWidget::graphicsEffect() const

图形效果函数返回小部件的图形效果的指针。

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

参见 setGraphicsEffect()。

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

返回对应嵌入小部件的代理小部件；否则返回 nullptr。

参见 QGraphicsProxyWidget::createProxyForChildWidget() 和 QGraphicsScene::addWidget()。

bool QWidget::hasEditFocus() const

如果此小部件当前具有编辑焦点，则返回 true，否则返回 false。

此功能仅在 Qt for Embedded Linux 中可用。

参见 setEditFocus() 和 QApplication::navigationMode()。

[虚拟] bool QWidget::hasHeightForWidth() const

如果小部件的首选高度依赖于其宽度，则返回 true，否则返回 false。

[虚拟] 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，可以在子类中重新实现以接收输入法组合事件。此处理器在输入法状态更改时调用。

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

默认实现调用 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。

窗口是一个不视觉上是任何其他小部件的子级的小部件，通常有一个框架和一个 窗口标题。

窗口可以有一个 父级小部件。如果小部件与父级一起删除，它将被删除，如果父级最小化，它将被最小化等。如果窗口管理器支持，它还将与父级共享一个任务栏入口。

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

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

[虚受保护的] void QWidget::keyPressEvent(QKeyEvent *event)

可以为事件 event 实现此事件处理器，以便接收小部件的按键事件。

小部件必须调用 setFocusPolicy() 才能接受初始焦点并拥有焦点以便接收按键事件。

如果重新实现此处理程序，如果不对按键进行操作，则调用基类实现非常重要。

默认实现关闭弹出小部件，如果用户按下 QKeySequence::Cancel（通常是 Escape 键）的键序列。否则，事件被忽略，以便小部件的父级可以解释它。

请注意，QKeyEvent 以 isAccepted() == true 开始，因此无需调用 QKeyEvent::accept() - 只需不要调用基类实现即可。

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

[虚受保护的] void QWidget::keyReleaseEvent(QKeyEvent *event)

此事件处理器对应于 event 事件，可以在子类中重新实现以接收部件的关键释放事件。

部件最初必须 接收焦点 并 拥有焦点 才能接收关键释放事件。

如果重新实现此处理程序，如果不对按键进行操作，则调用基类实现非常重要。

默认实现忽略事件，以便部件的父部件可以解释它。

请注意，QKeyEvent 以 isAccepted() == true 开始，因此无需调用 QKeyEvent::accept() - 只需不要调用基类实现即可。

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

[静态] QWidget *QWidget::keyboardGrabber()

返回当前正在抓取键盘输入的部件。

如果此应用程序中没有部件正在抓取键盘，则返回 nullptr。

另请参阅grabMouse 和 mouseGrabber。

QLayout *QWidget::layout() const

返回此部件上安装的布局管理器，如果没有安装布局管理器，则返回 nullptr。

布局管理器设置布局中添加的子部件的几何形状。

另请参阅setLayout、sizePolicy 和 布局管理。

[虚拟保护] void QWidget::leaveEvent(QEvent *event)

可以在子类中实现此事件处理器以接收通过 event 参数传递的部件离开事件。

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

另请参阅enterEvent、mouseMoveEvent 和 event。

[槽] void QWidget::lower()

将部件降低到父部件堆栈的底部。

此调用后，部件将视觉上位于任何重叠的兄弟部件之后（因此被它们遮挡）。

另请参阅raise 和 stackUnder。

[自 6.0 开始] QPointF QWidget::mapFrom(const QWidget *parent, const QPointF &pos) const

将父部件 parent 的坐标系中的部件坐标 pos 转换为该部件的坐标系。函数参数 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()。

[重写虚受保护] int QWidget::metric(QPaintDevice::PaintDeviceMetric m) const

重新实现: QPaintDevice::metric(QPaintDevice::PaintDeviceMetric metric) const。

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

m 是要获取的度量。

[虚受保护] void QWidget::mouseDoubleClickEvent(QMouseEvent *event)

此事件处理器，对于事件 event，可以由子类重新实现以接收小部件的鼠标双击事件。

默认实现调用 mousePressEvent。

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

[静态] QWidget *QWidget::mouseGrabber()

返回当前正在捕获鼠标输入的小部件。

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

另请参阅grabMouse() 以及 keyboardGrabber。

[虚受保护] void QWidget::mouseMoveEvent(QMouseEvent *event)

此事件处理器，对于事件 event，可以由子类重新实现以接收小部件的鼠标移动事件。

如果关闭了鼠标跟踪，只有当在鼠标移动时按下鼠标按钮时，才会触发鼠标移动事件。如果开启了鼠标跟踪，即使没有按下鼠标按钮也会发生鼠标移动事件。

QMouseEvent::pos() 报告鼠标光标相对于此小部件的位置。对于按下和释放事件，位置通常与最后鼠标移动事件的位置相同，但如果用户的手抖动，则可能不同。这是底层窗口系统的特性，而不是 Qt 的特性。

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

另请参阅：setMouseTracking()，mousePressEvent()，mouseReleaseEvent()，mouseDoubleClickEvent()，event()，QMouseEvent 和 Scribble 示例。

[虚保护] void QWidget::mousePressEvent(QMouseEvent *event)

此事件处理器适用于事件 event，可以在子类中重新实现以接收小部件的鼠标按下事件。

如果在 mousePressEvent() 中创建新的小部件，则 mouseReleaseEvent() 可能不会如预期那样结束，这取决于底层窗口系统（或 X11 窗口管理器）、小部件的位置以及其他因素。

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

另请参阅：mouseReleaseEvent()，mouseDoubleClickEvent()，mouseMoveEvent()，event()，QMouseEvent 和 Scribble 示例。

[虚保护] void QWidget::mouseReleaseEvent(QMouseEvent *event)

此事件处理器适用于事件 event，可以在子类中重新实现以接收小部件的鼠标释放事件。

另请参阅：mousePressEvent()，mouseDoubleClickEvent()，mouseMoveEvent()，event()，QMouseEvent 和 Scribble 示例。

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

这是一个重载函数。

这相当于 move(QPoint(x, y))。

[虚保护] void QWidget::moveEvent(QMoveEvent *event)

此事件处理器可以在子类中重新实现以接收传递给event参数的 widget 移动事件。当小部件接收到此事件时，它已经处于新位置。

旧位置可通过 QMoveEvent::oldPos() 访问。

另请参阅：resizeEvent()，event()，move() 和 QMoveEvent。

[虚拟受保护] bool QWidget::nativeEvent(const QByteArray &eventType, void *message, qintptr *result)

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

在您对这个函数的重写中，如果您想要阻止 Qt 处理该事件，返回 true 并设置 result。只有在 Windows 上，result 参数才有意义。如果返回 false，此原生事件将被传递回 Qt，Qt 将将其转换为 Qt 事件并发送到小部件。

另请参阅：QAbstractNativeEventFilter.

QWidget *QWidget::nativeParentWidget() const

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

另请参阅：effectiveWinId。

QWidget *QWidget::nextInFocusChain() const

返回小部件焦点链中的下一个小部件。

另请参阅：previousInFocusChain。

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

将小部件的窗口标志设置为 flags，不 告知窗口系统。

另请参阅：setWindowFlags。

[覆盖虚函数] QPaintEngine *QWidget::paintEngine() const

重实现：QPaintDevice::paintEngine() const。

返回小部件的绘图引擎。

注意，用户不应明确调用此函数，因为它是仅用于重写的目的。此函数由 Qt 内部调用，默认实现可能并不总是返回一个有效的指针。

[虚拟受保护] 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

previousInFocusChain 函数返回此小部件焦点链中的前一个小部件。

另请参阅：nextInFocusChain。

[slot] void QWidget::raise()

将此小部件提升到父小部件堆栈的顶部。

在此调用之后，小部件将 visuals 地显示在所有重叠的兄弟小部件之前。

另请参阅：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()，以及 insertAction()。

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

使用 renderFlags 确定渲染方式，将此部件的 sourceRegion 渲染到 target 上。渲染从 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's QPainter::device 上。

当渲染时，会用到对油漆工 painter 应用的变换和设置。

另请参阅QPainter::device()。

[槽函数] void QWidget::repaint()

直接通过调用 paintEvent() 立即重绘小部件，除非禁止更新或小部件被隐藏。

我们建议只在需要立即重绘的情况下使用 repaint()，例如在动画过程中。在大多数情况下，update() 更好，因为它允许 Qt 优化速度并最小化闪烁。

另请参阅：update()，paintEvent()，和 setUpdatesEnabled()。

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

这是一个重载函数。

此版本将重绘小部件内部的一个矩形 (x, y, w, h)。

如果 w 为负值，则替换为 width() - x，如果 h 为负值，则替换为 height() - y。

void QWidget::repaint(const QRect &rect)

这是一个重载函数。

此版本将重绘小部件内部的一个矩形 rect。

void QWidget::repaint(const QRegion &rgn)

这是一个重载函数。

此版本将重绘小部件内部的一个区域 rgn。

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 Example。

bool QWidget::restoreGeometry(const QByteArray &geometry)

此函数将恢复存储在字节数组 geometry 中顶层小部件的几何形状和状态。成功则返回 true，否则返回 false。

如果恢复的几何形状在屏幕外，它将被修改为位于可用的屏幕几何形状内。

要恢复使用 QSettings 保存的几何形状，可以使用如下代码

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

有关窗口 geometry 问题概述，请参阅窗口 Geometry 文档。

使用 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);
}

有关窗口 geometry 问题概述，请参阅窗口 Geometry 文档。

使用 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 知道是不可透明的_widget，这仅是新的曝光部分。例如，如果一个不可透明的小部件向左滚动 8 像素，则只需更新右边缘 8 像素宽的条纹。

由于小部件默认通过其父级别联内容，您需要设置 autoFillBackground 属性或使用 setAttribute() 来设置 Qt::WA_OpaquePaintEvent 属性，以使小部件不可透明。

对于使用内容级联的小部件，滚动会导致整个滚动区域更新。

另请参阅 透明度和双缓冲。

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。

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

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

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

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

另请参阅isEnabledTo、QKeyEvent、QMouseEvent 和 changeEvent。

void QWidget::setEditFocus(bool enable)

如果 enable 为 true，则让此小部件具有编辑焦点，这时 Qt::Key_Up 和 Qt::Key_Down 将正常传递给小部件；否则，使用 Qt::Key_Up 和 Qt::Key_Down 来更改焦点。

此功能仅在 Qt for Embedded Linux 中可用。

另请参阅：hasEditFocus() 和 QApplication::navigationMode()。

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)

如果此小部件或其父级之一是 活动窗口，则将键盘输入焦点给予此小部件（或其焦点代理）。reason 参数将传递给从此函数发送的任何焦点事件，用于解释导致小部件获得焦点的原因。如果窗口不是活动窗口，则当窗口变为活动窗口时，小部件将被给予焦点。

首先，发送一个焦点即将更改事件到焦点小部件（如果有），以告知它即将失去焦点。然后更改焦点，发送一个焦点消失事件到先前的焦点项，并给新项发送一个焦点进入事件，告知它刚刚获得了焦点。（如果焦点进入和焦点消失的小部件相同，则不发生任何操作。）

setFocus()会给予小部件焦点，不管其焦点策略如何，但不会清除任何键盘捕获（请参阅 grabKeyboard）。

请注意，如果小部件被隐藏，它将不会接受焦点，直到它被显示出来。

参阅：hasFocus，clearFocus，focusInEvent，focusOutEvent，setFocusPolicy，focusWidget，QApplication::focusWidget，grabKeyboard，grabMouse，小部件中的键盘焦点 和 QEvent::RequestSoftwareInputPanel。

[slot] void QWidget::setFocus()

这是一个重载函数。

如果此小部件或其父级之一是 活动窗口，则给予此小部件（或其焦点代理）键盘输入焦点。

void QWidget::setFocusProxy(QWidget *w)

将小部件的焦点代理设置为小部件w。如果w是nullptr，则函数将重置此小部件以没有焦点代理。

一些小部件“可以拥有焦点”，但创建子小部件，例如QLineEdit，来实际处理焦点。在这种情况下，小部件可以将文本框设置为它的焦点代理。

setFocusProxy()用于设置一个当“此小部件”获得焦点时实际上会获得焦点的窗口小部件。如果存在焦点代理，则setFocus()和hasFocus()操作的是焦点代理。如果“此小部件”是焦点窗口小部件，则setFocusProxy()将焦点移动到新的焦点代理。

另请参阅focusProxy。

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

设置窗口小部件的前景色为role。

前景角色定义了从组件的QPalette中使用的颜色，用于绘制前景。

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

请注意，样式可以自由选择调色板中的任何颜色。如果你通过setForegroundRole()没有达到想要的结果，你可以修改调色板或设置样式表。

另请参阅foregroundRole和backgroundRole。

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

这是一个重载函数。

这等同于setGeometry(QRect(x, y, w, h))).

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);
    setLayout(layout);

调用此函数的另一种方法是传递此窗口小部件到布局的构造函数。

QWidget将接管layout的所有权。

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

void QWidget::setMask(const QBitmap &bitmap)

仅使具有对应 1 位的 widget 像素可见。如果区域包括 widget 的rect()() 坐标系之外的像素，则该区域的窗口系统控件可能可见或不可见，这取决于平台。

注意，如果区域特别复杂，这种效果可能会很慢。

以下代码示例演示如何使用具有 alpha 通道的图像为 widget 生成遮罩。

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

此代码显示的标签使用包含的图像进行遮罩，给人一种不规则形状的图像被直接绘制在屏幕上的外观。

仅对有遮罩的 widget 的可见部分接收鼠标事件。

另请参阅mask，clearMask 和 windowOpacity。

void QWidget::setMask(const QRegion &region)

这是一个重载函数。

仅使 widget 与 region 重叠的部分可见。如果区域包括 widget 的rect()() 坐标系之外的像素，则该区域的窗口系统控件可能可见或不可见，这取决于平台。

由于 QRegion 允许创建任意复杂的区域，因此可以创建合适的 widget 遮罩，即使窗口形态非常独特，甚至允许 widget 在其中显示有洞的图像。请注意，如果区域特别复杂，这种效果可能会很慢。

Widget 遮罩用于向窗口系统提供提示，告知应用程序不希望对遮罩外部区域进行鼠标事件。在大多数系统上，这还导致视觉效果粗略裁剪。为了获得平滑的窗口边缘，请使用透明背景和抗锯齿绘制，如下 Transparent Background 示例所示。

另请参阅windowOpacity。

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

这是一个重载函数。

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

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

这是一个重载函数。

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

void QWidget::setParent(QWidget *parent)

将 widget 的父对象设置为 parent，并重置窗口标记。widget 将在新父窗口中的位置 (0, 0)。

如果新的父 widget 在不同的窗口中，则被重新父化的 widget 及其子 widget 将按照它们原来的内部顺序附加到新父 widget 的tab 链 的末尾。如果移动的 widget 之一拥有键盘焦点，则 setParent() 会调用 clearFocus() 以该 widget 为参数。

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

如果“新”的父小部件是旧父小部件，则此功能不执行任何操作。

另请参阅：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 为 true，则会启用给定 id 的快捷键的自动重复；否则，它会被禁用。

另请参阅：grabShortcut() 和 releaseShortcut().

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

如果 enable 为 true，则启用给定 id 的快捷键；否则，该快捷键会被禁用。

另请参阅：grabShortcut() 和 releaseShortcut().

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

这是一个重载函数。

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

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

这是一个重载函数。

将小部件的大小策略设置为 horizontal 和 vertical，具有标准拉伸和没有高度为宽度的策略。

另请参阅：QSizePolicy::QSizePolicy().

void QWidget::setStyle(QStyle *style)

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

如果没有设置样式，小部件将使用应用程序的样式，而不是QApplication::style()。

设置小部件的样式对现有或将来子小部件没有影响。

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

[静态] void QWidget::setTabOrder(QWidget *first, QWidget *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

如果 第一个 或 第二个 有焦点代理，则 setTabOrder() 会正确替换代理。

另请参阅：setFocusPolicy()，setFocusProxy() 和 Widgets 中的键盘焦点。

[静态，自 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

调用不会创建封闭的选项卡焦点循环。如果有更多具有 Qt::TabFocus 焦点策略的小部件，按 d 选项卡将使焦点移动到这些窗口之一，而不是回到 a。

此函数是在 Qt 6.6 中引入的。

另请参阅：setFocusPolicy()，setFocusProxy() 和 Widgets 中的键盘焦点。

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

如果 on 为 true，则将窗口标志 flag 设置在此小部件上；否则清除标志。

另请参阅：setWindowFlags()，windowFlags() 和 windowType()。

void QWidget::setWindowRole(const QString &role)

将窗口的角色设置为 role。此操作只适用于 X11 上的窗口。

另请参阅：windowRole()。

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

将窗口状态设置为 windowState。窗口状态是 Qt::WindowState 的 OR 组合：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

void QWidget::setupUi(QWidget *widget)

为指定的 widget 设置用户界面。

另请参阅：在使用 Designer UI 文件的应用程序中使用 Designer UI 文件

[slot] void QWidget::show()

显示小部件及其子小部件。

对于子窗口，这相当于调用 setVisible(true)。否则，相当于调用 showFullScreen()、showMaximized() 或 setVisible(true)，具体取决于平台对窗口标志的默认行为。

另请参阅：raise、showEvent、hide、setVisible、showMinimized、showMaximized、showNormal、isVisible 和 windowFlags

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

可以在子类中重写此事件处理程序，以接收通过 event 参数传入的 widget 显示事件。

非自发性显示事件在显示小部件之前立即发送。窗口的自发性显示事件将在之后发送。

注意：当窗口系统更改小部件的映射状态时，小部件接收自发的显示和隐藏事件，例如，当用户最小化窗口时，发生自发的隐藏事件，当窗口再次恢复时，发生自发的显示事件。接收到自发的隐藏事件后，小部件仍然被视为在 isVisible() 的意义上可见。

另请参阅：visible、event 和 QShowEvent

[slot] void QWidget::showFullScreen()

以全屏模式显示小部件。

调用此函数将仅影响窗口。

要从全屏模式返回，请调用 showNormal() 或 close()。

另一种选择是完全不通过窗口管理器，并使用具有Qt::X11BypassWindowManagerHint标志的窗口。但这会有其他严重问题，比如破坏键盘焦点，以及当用户打开或关闭其他窗口时的非常奇怪的效果。

遵循现代后ICCCM规范的X11窗口管理器可以正确支持全屏模式。

在macOS上，显示全屏窗口会将整个应用程序置于全屏模式，为其提供一个专用桌面。当应用程序处于全屏模式运行时，显示另一个窗口可能会自动使该窗口也切换为全屏。为了避免这种情况，可以在显示另一个窗口之前调用showNormal()或close()关闭全屏窗口来退出全屏模式。

另请参阅：showNormal()，showMaximized()，show()，isVisible()和close()。

[槽] void QWidget::showMaximized()

显示最大化的小部件。

调用此函数将仅影响窗口。

在X11上，此函数可能无法与某些窗口管理器正确工作。关于解释，请参阅窗口几何形状文档。

另请参阅：setWindowState()，showNormal()，showMaximized()，show()，hide()和isVisible()。

[槽] void QWidget::showMinimized()

以图标形式显示最小化的小部件。

调用此函数将仅影响窗口。

另请参阅：showNormal()，showMaximized()，show()，hide()，isVisible()和isMinimized()。

[槽] void QWidget::showNormal()

在最大化或最小化后恢复小部件。

调用此函数将仅影响窗口。

另请参阅：setWindowState()，showMinimized()，showMaximized()，show()，hide()和isVisible()。

void QWidget::stackUnder(QWidget *w)

将小部件放置在其父小部件堆中的w之下。

为此，小部件本身及其w必须是兄弟关系。

另请参阅：raise()和lower()。

QStyle *QWidget::style() const

另请参阅：QWidget::setStyle()，QApplication::setStyle()和QApplication::style()。

[虚拟受保护] void QWidget::tabletEvent(QTabletEvent *event)

此事件处理程序，用于处理事件 event，可以在子类中重新实现以接收小部件的平板电脑事件。

如果您重新实现了此处理程序，如果您未处理它，则非常重要，您必须调用ignore()事件，以便小部件的父项可以解释它。

默认实现忽略该事件。

如果关闭了平板电脑跟踪，只有在笔触碰到平板电脑或者在移动笔的同时至少按下一个笔按钮时，才会发生平板电脑移动事件。如果打开了平板电脑跟踪，即使笔靠近平板电脑而未按下任何按钮，也会发生平板电脑移动事件。

另请参阅QEvent::ignore()、QEvent::accept()、event()、setTabletTracking()和QTabletEvent。

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

如果在这个小部件上设置了属性attribute，则返回true；否则返回false。

另请参阅setAttribute。

bool QWidget::underMouse() const

如果小部件位于鼠标光标下，则返回true；否则返回false。

在拖放操作期间，此值不会正确更新。

另请参阅enterEvent()和leaveEvent。

void QWidget::ungrabGesture(Qt::GestureType gesture)

取消为给定的gesture类型订阅小部件

另请参阅grabGesture()和QGestureEvent。

[槽函数] void QWidget::update()

如果未禁用更新或小部件是隐藏的，则更新小部件。

此函数不会立即引起重绘；相反，它在Qt返回到主事件循环时安排一个绘图事件进行处理。这允许Qt在速度和减少闪烁方面比repaint()调用优化。

通常情况下，多次调用update()只会产生一次paintEvent()调用。

在paintEvent()调用之前，Qt通常会清除小部件的区域。如果设置了Qt::WA_OpaquePaintEvent小部件属性，则小部件负责使用不透明的颜色绘制所有像素。

另请参阅repaint()、paintEvent()、setUpdatesEnabled()和Analog Clock。

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

这是一个重载函数。

此版本更新小部件内的矩形的版本（x、y、w、h）。

void QWidget::update(const QRect &rect)

这是一个重载函数。

此版本更新小部件内矩形rect。

void QWidget::update(const QRegion &rgn)

这是一个重载函数。

此版本将重绘小部件内部的一个区域 rgn。

void QWidget::updateGeometry()

通知布局系统该小部件已更改，可能需要更改几何形状。

如果有更改 sizeHint() 或 sizePolicy()，请调用此函数。

对于显式隐藏的小部件，updateGeometry() 无操作。一旦小部件显示，布局系统将立即通知。

[protected slot] void QWidget::updateMicroFocus(Qt::InputMethodQuery query = Qt::ImQueryAll)

更新小部件的微焦点，并通知输入法已更改由 query 指定的状态。

QRegion QWidget::visibleRegion() const

返回未遮挡的区域内可以发生绘制事件。

对于可见小部件，这是不被其他小部件覆盖的区域的一个近似值；否则，这是一个空区域。

在必要时，repaint() 函数将调用此函数，因此通常不需要调用它。

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

此事件处理器，对于事件 event，可以在子类中重写以获取小部件的轮事件。

如果您重新实现了此处理程序，如果您未处理它，则非常重要，您必须调用ignore()事件，以便小部件的父项可以解释它。

默认实现忽略该事件。

另请参阅 QEvent::ignore()，QEvent::accept()，event() 和 QWheelEvent。

WId QWidget::winId() const

返回小部件的窗口系统标识符。

在原则上具有可移植性，但如果你使用它，你可能即将进行某些不可移植的操作。请小心。

如果小部件是非原生的（外星），并且在其上调用 winId()，则该小部件将获得一个原生句柄。

此值可能会在运行时更改。在窗口系统标识符更改后，将向小部件发送类型为 QEvent::WinIdChange 的事件。

另请参阅 find。

QWidget *QWidget::window() const

返回此小部件的窗口，即具有（或可能具有）窗口系统框架的下一个祖先小部件。

如果小部件是窗口，则返回该小部件本身。

典型用途是更改窗口标题

aWidget->window()->setWindowTitle("New Window Title");

另请参阅 isWindow。

QWindow *QWidget::windowHandle() const

如果是原生小部件，则返回相关的 QWindow。否则返回 null。

原生小部件包括顶层小部件、QGLWidget 和在其上调用 winId() 的子小部件。

另请参阅 winId() 和 screen。

[signal] void QWidget::windowIconChanged(const QIcon &icon)

当窗口图标更改时发出此信号，其中新 icon 作为参数。

QString QWidget::windowRole() const

返回窗口的角色，或一个空字符串。

另请参阅 setWindowRole()，windowIcon，以及windowTitle。

Qt::WindowStates QWidget::windowState() const

返回当前的窗口状态。窗口状态是Qt::WindowState的组合，这些状态可以通过位或（OR）操作组合起来：Qt::WindowMinimized，Qt::WindowMaximized，Qt::WindowFullScreen，以及Qt::WindowActive。

另请参阅 Qt::WindowState和setWindowState。

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

当窗口标题更改时，会发出此信号，并将新的title作为参数传递。

Qt::WindowType QWidget::windowType() const

返回此小部件的窗口类型。这等于windowFlags() & Qt::WindowType_Mask。

另请参阅 windowFlags。