QWidget 类

成员函数

QWidget::QWidget(QWidget *parent = Q_NULLPTR, Qt::WindowFlags f = Qt::WindowFlags())

构造函数, parent 父对象指针, f widget标志.

如果 parent 是nullptr, 新创建的widget变成窗口. 如果 parent 是另一个widget, 新创建的widget变成 parent的子窗口. parent 删除时, 新创建的widget也会删除.

参数f默认是0, 但是它可以设置自定义的窗口标志 (即. parent 必须是nullptr). 若自定义参数f, 使用任意的窗口标志, 使用或组合 .

如果你在已经可见的widget上添加子widget, 你必须明确显示子widget.

注意: 在X11上, Qt可能无法提供所有标志的组合. 这是因为在X11上, Qt只能询问窗口管理器, 而窗口管理器可以覆盖应用程序的设置. 在Windows上, Qt可以设置任何你想设置的标志.

参见 windowFlags.

QWidget::~QWidget()

析构函数.

首先删除widget的所有子对象. 若widget是主窗口, 则应用程序退出.

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

widget的action发生改变, 调用这个函数.

参见 addAction(), insertAction(), removeAction(), actions(), QActionEvent.

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

返回widget的action列表, 可能为空.

参见 contextMenuPolicy, insertAction(), removeAction().

void QWidget::activateWindow()

将包含这个widget的顶级widget设置为活动窗口.

活动窗口是具有键盘输入焦点的可见顶层窗口.

这个函数的执行结果与在顶级窗口的标题栏上单击鼠标一样. 在X11上, 函数执行结果取决于窗口管理器. 如果你想确保窗口显示在上面, 你也应该调用 raise(). 注意: 窗口必须可见, 否则activateWindow()无效.

在Windows上, 如果你在应用程序当前不是活动窗口时调用此函数, 则它不会使其成为活动窗口. 它将更改任务栏条目的颜色, 以指示窗口以某种方式发生了更改. 这是因为Microsoft不允许应用程序中断用户当前在另一个应用程序中执行的操作.

参见 isActiveWindow(), window(), show(), QWindowsWindowFunctions::setWindowActivationBehavior().

void QWidget::addAction(QAction *action)

在widget的 action 列表增加action.

每个QWidget都具有 QAction列表, 它们可能是不同方式表示的图标. QAction 列表 ( actions()返回值) 的默认用途是创建上下文 QMenu.

QWidget 应该仅有一个相同的action, 添加相同的action不会导致widget执行两次action操作.

action 的所有权不会转移给 QWidget.

参见 removeAction(), insertAction(), actions(), QMenu.

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

actions追加到widget的action列表.

参见 removeAction(), QMenu, addAction().

void QWidget::adjustSize()

根据widget的内容调整大小.

若 sizeHint() 可用(即., 宽高 >= 0) 则这个函数使用sizeHint(). 否则, 它使用子级对象的区域 (覆盖所有子级对象, 子级对象的组合区域).

对于窗口, 也会考虑屏幕大小. 若 sizeHint() 小于(200, 100), 并且大小策略是 expanding, 则窗口最小是(200, 100). 窗口的最大值是屏幕宽高的2/3.

参见 sizeHint() 和 childrenRect().

QPalette::ColorRole QWidget::backgroundRole() const

返回widget的背景角色.

背景角色定义绘制widget背景的 调色板.

如果没有设置明确的背景角色, 则widget继承父widget的背景角色.

参见 setBackgroundRole() 和 foregroundRole().

QBackingStore *QWidget::backingStore() const

返回widget将要绘制的 QBackingStore.

This function was introduced in Qt 5.0.

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

处理widget状态改变事件.

The state being changed in this event can be retrieved through the event supplied.

改变事件包含: 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

返回widget坐标系中, 坐标点(x, y) 的可见子widget. 如果指定位置没有可见子widget, 则返回nullptr.

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

重载函数.

返回widget坐标系中, p 位置的可见子widget.

void QWidget::clearFocus()

移除widget键盘输入焦点.

若widget有激活焦点, focus out event 发送给widget, 告诉它已经失去焦点.

widget必须启用焦点设置, 才能获取键盘输入焦点, 即. 它必须调用 setFocusPolicy().

参见 hasFocus(), setFocus(), focusInEvent(), focusOutEvent(), setFocusPolicy(), QApplication::focusWidget().

void QWidget::clearMask()

清除 setMask()设置的掩码.

参见 setMask().

[slot] bool QWidget::close()

关闭widget. 若widget已经关闭, 返回 true; 否则返回 false.

首先, 它发给这个widget一个 QCloseEvent. 如果widget接受这个关闭事件, 这个widget 被隐藏. 如果 忽略 这个事件, 不会发生任何事情. QWidget::closeEvent() 默认实现接受关闭事件.

如果widget有 Qt::WA_DeleteOnClose 标识, 这个widget也会被删除. 不管widget是否可见, 关闭事件都会发到这个widget.

最后一个带有Qt::WA_QuitOnClose标识的可见的主窗口(即.窗口没有父对象)关闭时, 会发出 QApplication::lastWindowClosed() 信号. 默认情况下, 除临时窗口(如启动窗口, 工具窗口, 弹出菜单)外, 所有widget都具有Qt::WA_QuitOnClose属性.

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

Qt接收到来自窗口系统的顶级widget的窗口关闭请求时, 调用这个处理函数.

默认情况下, 事件被接受, widget被关闭. 你可以重新实现这个函数, 更改widget响应窗口关闭请求的方式. 例如, 可以通过对所有事件调用ignore()阻止窗口关闭.

主窗口应用程序通常重新实现这个函数, 在关闭前, 检查用户的工作是否已保存. 例如, Application Example 示例使用辅助函数确定是否关闭窗口:

  void MainWindow::closeEvent(QCloseEvent *event)
  {
      if (maybeSave()) {
          writeSettings();
          event->accept();
      } else {
          event->ignore();
      }
  }

参见 event(), hide(), close(), QCloseEvent, Application Example.

QMargins QWidget::contentsMargins() const

widget内容外边距.

This function was introduced in Qt 4.6.

参见 getContentsMargins(), setContentsMargins(), contentsRect().

QRect QWidget::contentsRect() const

widget的内容区域.

参见 setContentsMargins() 和 getContentsMargins().

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

虚函数, 重新实现接收widget的内容菜单事件.

当widget的 contextMenuPolicy 是 Qt::DefaultContextMenu时, 调用这个函数.

默认实现是忽略内容事件, 详见 QContextMenuEvent.

参见 event(), QContextMenuEvent, customContextMenuRequested().

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

创建一个新widget窗口.

Qt 5忽略参数 window, initializeWindow, destroyOldWindow. 调用 QWindow::fromWinId() 创建一个包装外部窗口的 QWindow , 并作为参数传递给 QWidget::createWindowContainer().

Initializes the window (sets the geometry etc.) if initializeWindow is true. If initializeWindow is false, no initialization is performed. This parameter only makes sense if window is a valid window.

Destroys the old window if destroyOldWindow is true. If destroyOldWindow is false, you are responsible for destroying the window yourself (using platform native code).

The QWidget constructor calls create(0,true,true) to create a window for this widget.

参见 createWindowContainer() and QWindow::fromWinId().

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

创建一个 QWidget, 将 window 窗口嵌入基于 QWidget的应用程序中.

窗口容器作为 parent 的子对象创建, 并带有窗口标志 flags.

一旦窗口嵌入到容器中, 容器将控制窗口的几何尺寸和可见性. 不建议对嵌入式窗口直接调用 QWindow::setGeometry(), QWindow::show() 或 QWindow::hide().

容器接管 window的所有权. 调用 QWindow::setParent()从窗口容器删除窗口.

窗口容器作为本地子窗口附加到它所属的顶层窗口. 窗口容器作为QAbstractScrollArea或QMdiArea的子窗口时, 它将为父对象的每个widget创建一个原生窗口, 以便对窗口适当的堆叠和裁剪. 为窗口容器创建一个本地窗口也可以进行适当的堆叠和剪裁. 但是, 这必须在显示窗口容器之前完成. 具有许多本机子窗口的应用程序可能会出现性能问题.

窗口容器有许多已知的限制:

• 堆叠顺序: 嵌入的窗口将作为不透明的框堆叠在widget层次结构的顶部. 多个重叠窗口容器实例的堆叠顺序未定义.
• 渲染集成: 窗口容器不能与 QGraphicsProxyWidget, QWidget::render() 或类似功能进行互操作.
• 焦点处理: 可以让窗口容器实例具有任何焦点策略, 调用 QWindow::requestActivate()将焦点委派给窗口. 然而, 从 QWindow 实例返回到正常的焦点链将取决于 QWindow 实例实现本身. 例如, 当进入具有选项卡焦点的基于Qt Quick的窗口时, 很可能进一步的选项卡按压只会在QML应用程序内循环. 此外, QWindow::requestActivate() 是否真的提供了窗口焦点, 取决于平台.
• 在基于 QWidget的应用程序中使用许多窗口容器实例会极大地损害应用程序的整体性能.

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

This signal is emitted when the widget's contextMenuPolicy is Qt::CustomContextMenu, and the user has requested a context menu on the widget. The position pos is the position of the context menu event that the widget receives. Normally this is in widget coordinates. The exception to this rule is QAbstractScrollArea and its subclasses that map the context menu event to coordinates of the viewport().

参见 mapToGlobal(), QMenu, and contextMenuPolicy.

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

释放窗口系统资源. destroyWindow 是true时, 销毁widget窗口.

destroySubWindows是true时, 递归调用子widget的 destroy(). 这个函数通常在QWidget的析构函数调用.

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

正在进行拖拽, 且鼠标widget时, 会调用这个函数.

若忽略这个事件, widget不接受任何 拖拽移动事件.

如何提供拖拽功能, 参见 Drag-and-drop documentation.

参见 QDrag and QDragEnterEvent.

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

This event handler is called when a drag is in progress and the mouse leaves this widget. The event is passed in the event parameter.

See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.

参见 QDrag and QDragLeaveEvent.

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

正在进行拖动, 且出现以下任何情况时, 会调用这个函数: 光标进入widget, 光标在widget内移动, 或者widget具有焦点时, 按下键盘上的修改键.

如何提供拖拽功能, 参见 Drag-and-drop.

参见 QDrag and QDragMoveEvent.

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

拖拽离开widget时, 调用这个函数.

如何提供拖拽功能, 参见 Drag-and-drop.

参见 QDrag and QDropEvent.

WId QWidget::effectiveWinId() const

返回widget的有效窗口系统标识符, 即. 本地父窗口系统标识符.

如果widget是本地窗口, 则函数返回本地窗口ID. 否则, 返回第一个本地父窗口ID, 即., 包含widget的顶级窗口.

注意: 我们建议你不要存储此值, 因为它可能会在运行时更改.

This function was introduced in Qt 4.4.

参见 nativeParentWidget().

void QWidget::ensurePolished() const

确保widget和它的子对象已经被 QStyle 修饰(即., 具有合适的字体和调色板).

QWidget 在完全构造后, 显示前调用这个函数. 如果你想确保执行操作前, 对widget修饰, 则调用此函数, 例如, 在 sizeHint() 中可能需要正确的字体大小. 注意: 这个函数在 sizeHint()的默认实现中调用.

在调用所有的构造函数(基类和子类)后, 再最终初始化, Polishing是非常有用.

widget已经polished后, 需要做一些设置, 重新实现 event() , 并处理 QEvent::Polish 事件类型.

注意: 这个函数被声明为const, 因此可以在其他const函数中调用它 (如., sizeHint()).

参见 event().

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

虚函数, 接收widget进入事件.

鼠标光标进入widget时, 调用这个函数.

参见 leaveEvent(), mouseMoveEvent(), event().

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

重新实现 QObject::event().

主要的事件处理函数. 你可以在子类中重新实现这个函数, 但是, 建议使用专门的事件处理程序.

键盘的按下和弹起不同于其他事件. event()检测Tab和Shift+Tab, 并尝试适当地移动焦点. 如果没有widget可以转移焦点(或者按键不是Tab或Shift+Tab), 则event()调用 keyPressEvent().

鼠标和平板电脑事件处理也有点特殊: 只有widget 启用时, 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的widget指针.

窗口标识符类型取决于底层窗口系统, 参考 qwindowdefs.h 了解实际定义. 如果没有具有此标识符的widget, 则返回nullptr.

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

虚函数, 处理键盘焦点事件

widget必须调用 setFocusPolicy() , 并设置 Qt::NoFocus 以外的值, 才能接收焦点事件(注意: 应用程序开发人员可以在任意widget上调用 setFocus() , 即便widget不接受焦点.)

默认事件更新widget(不设置 focusPolicy()的窗口除外).

参见 focusOutEvent(), setFocusPolicy(), keyPressEvent(), keyReleaseEvent(), event(), QFocusEvent.

[protected] bool QWidget::focusNextChild()

查找一个新widget, 以便转移焦点. 如Tab按键. 如果找到一个新widget, 返回true. 否则, 返回false.

参见 focusPreviousChild().

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

查找一个新widget, 以便转移焦点, 适用于Tab和Shift+Tab. 如果找到一个新widget, 返回true. 否则, 返回false.

如果next为true, 则向前搜索, 如果next是false, 则向后搜索.

有时, 你希望重新实现这个函数. 例如, web浏览器可能会重新实现向前或向后移动其"当前活动链接", 并仅在到达"页面"上的最后一个或第一个链接时调用focusNextPrevicChild().

子widget在其父widget上调用focusNextPrevidChild(), 但只有包含子widget的窗口决定将焦点重定向到哪里. 通过为对象重新实现这个函数, 你可以控制所有子widget的焦点遍历.

参见 focusNextChild() 和 focusPreviousChild().

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

丢失键盘焦点事件.

widget必须调用 setFocusPolicy() , 并设置 Qt::NoFocus 以外的值, 才能接收焦点事件(注意: 应用程序开发人员可以在任意widget上调用 setFocus() 即便widget不接受焦点.)

默认事件更新widget(不设置 focusPolicy()的窗口除外).

参见 focusInEvent(), setFocusPolicy(), keyPressEvent(), keyReleaseEvent(), event(), QFocusEvent.

[protected] bool QWidget::focusPreviousChild()

查找一个新widget, 以便转移焦点. 如Shift+Tab按键. 如果找到一个新widget, 返回true. 否则, 返回false.

参见 focusNextChild().

QWidget *QWidget::focusProxy() const

返回焦点代理widget, 若没有, 则返回nullptr.

参见 setFocusProxy().

QWidget *QWidget::focusWidget() const

返回最后一个调用 setFocus 的子widget. 对于顶级widget, 返回具有焦点的widget.

不同于 QApplication::focusWidget(), QApplication::focusWidget()返回活动窗口中, 具有焦点的widget.

QFontInfo QWidget::fontInfo() const

widget的字体信息. 等价于 QFontInfo(widget->font()).

参见 font(), fontMetrics(), and setFont().

QFontMetrics QWidget::fontMetrics() const

widget的字体规格. 等价于 QFontMetrics(widget->font()).

参见 font(), fontInfo(), setFont().

QPalette::ColorRole QWidget::foregroundRole() const

返回前景角色.

定义widget的 palette 中绘制前景的颜色.

如果未设置前景角色, 则函数返回与背景角色相对的角色.

参见 setForegroundRole() 和 backgroundRole().

void QWidget::getContentsMargins(int *left, int *top, int *right, int *bottom) const

Returns the widget's contents margins for left, top, right, and bottom.

参见 setContentsMargins() and contentsRect().

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

把widget的 rectangle范围内的内容保存成QPixmap.

若rectangle是无效值(默认值), 则绘制整个widget.

注意: 这个函数可以通过元对象系统和QML调用. 参见Q_INVOKABLE

This function was introduced in Qt 5.0.

参见 render() and QPixmap.

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

Subscribes the widget to a given gesture with specific flags.

This function was introduced in Qt 4.6.

参见 ungrabGesture() and QGestureEvent.

void QWidget::grabKeyboard()

抓取键盘输入.

这个widget接收所有键盘事件, 直到调用 releaseKeyboard() 为止; 其他widget不会接收到键盘事件. 鼠标事件不受影响. 如果你想抓住鼠标事件, 可以调用 grabMouse().

焦点widget不受影响, 只是它不能接收到任何键盘事件. setFocus() 像往常一样移动焦点, 但新的焦点widget只有在调用 releaseKeyboard() 之后才会接收到键盘事件.

如果另一个widget当前正在获取键盘输入, 则会首先释放这个widget的抓取.

参见 releaseKeyboard(), grabMouse(), releaseMouse(), focusWidget().

void QWidget::grabMouse()

抓取鼠标输入.

这个widget接收所有鼠标事件, 直到调用 releaseMouse() 为止; 其他widget不会接收到鼠标事件. 键盘事件不受影响. 如果你想抓住键盘事件, 可以调用 grabKeyboard().

警告: 鼠标抓取应用程序中的错误经常会锁定终端. 使用这个函数时要格外小心, 并考虑在调试时使用 -nograb 命令行选项.

在使用Qt时, 几乎从来没有必要抓住鼠标, 因为Qt会明智地抓住并释放鼠标. 特别是, 当按下鼠标按钮时, Qt会抓住鼠标, 并一直保持到最后一个按钮释放.

注意: 只有可见的widget才能获取鼠标输入. 如果某个widget的 isVisible() 返回 false , 则这个widget无法调用grabMouse().

注意: 在Windows上, grabMouse()仅在鼠标位于进程拥有的窗口内时才起作用. 在 macOS上, grabMouse()只有当鼠标位于widget边框内时才起作用.

参见 releaseMouse(), grabKeyboard(), releaseKeyboard().

void QWidget::grabMouse(const QCursor &cursor)

grabMouse()重载函数.

抓取鼠标输入, 并更改鼠标形状.

鼠标光标改成cursor形状(只要鼠标焦点被抓住), 并且widget将是唯一一个接收鼠标事件的widget, 直到调用 releaseMouse() 为止.

警告: 抓取鼠标可能锁住终端.

Note: See the note in QWidget::grabMouse().

参见 releaseMouse(), grabKeyboard(), releaseKeyboard(), setCursor().

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

在Qt的快捷键系统中添加一个快捷键. 如果context是Qt::ApplicationShortcut, 则快捷键应用于整个应用程序; 如果context是Qt::WidgetShortcut, 则快捷键属于widget; 如果context是Qt::WidgetShortcut, 则快捷键属于窗口. 若key被多个widget抓取, 则key快捷键发生时, QEvent::Shortcut事件以无序方式发送给所有的widget, 但是"ambiguous"标志设置为true.

警告: 你不应该使用这个功能; 相反, 你应该在创建QAction时, 指定快捷键(如果你也需要等效的菜单和工具栏按钮), 或者你仅创建QShortcut. QAction和QShortcut都可以处理事件过滤, 并提供快捷键触发信号, 因此, 这比低级函数更容易使用.

参见 releaseShortcut() 和 setShortcutEnabled().

QGraphicsEffect *QWidget::graphicsEffect() const

返回QGraphicsEffect指针.

若没有, 返回nullptr.

This function was introduced in Qt 4.6.

参见 setGraphicsEffect().

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

返回QGraphicsProxyWidget指针. 若没有, 返回nullptr.

This function was introduced in Qt 4.5.

参见 QGraphicsProxyWidget::createProxyForChildWidget() and QGraphicsScene::addWidget().

bool QWidget::hasEditFocus() const

widget是否有编辑焦点.

这个函数仅在嵌入式Linux系统有效.

参见 setEditFocus() 和 QApplication::keypadNavigationEnabled().

[virtual] bool QWidget::hasHeightForWidth() const

若widget的首选高度取决于高度, 返回true; 否则返回false.

This function was introduced in Qt 5.0.

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

返回宽度w的适合高度.

若widget有布局, 默认实现是返回布局的适合高度. 若无布局, 默认实现返回-1, 表明适宜高度不由宽度决定.

[slot] void QWidget::hide()

隐藏widget. 这个函数等价于 setVisible(false).

注意: 如果你使用 QDialog 或QDialog的子类, 你调用完hide(), 再调用 show()时, 对话框显示在原始位置.

参见 hideEvent(), isHidden(), show(), setVisible(), isVisible(), and close().

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

widget隐藏事件.

widget隐藏后, 立即将隐藏事件发送给widget.

注意: widget被窗口系统改变映射状态时, 接收自发的显示和隐藏事件, 例如. 用户最小化窗口时, 生成一个自发的隐藏事件; 窗口还原时, 生成一个自发的显示事件. 接收到自发的隐藏事件后, widget仍然视为可见的, isVisible())返回true.

参见 visible, event(), QHideEvent.

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

初始化widget的 painter(笔, 背景和字体). 这个函数在QWidget打开painter时, 自动调用.

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

处理输入方法. 这个函数在输入方法状态改变时调用.

注意: 创建自定义文本编辑widget时, 窗口必须设置Qt::WA_InputMethodEnabled属性(调用setAttribute()), 以便接收输入方法事件.

默认实现调用event->ignore(), 忽略输入方法事件. 详见 QInputMethodEvent.

参见 event() and QInputMethodEvent.

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

这个函数与输入widget相关. 这个函数的作用是在具有复杂输入方法的widget(支持环形文字和重置)中查询query属性.

参见 inputMethodEvent(), QInputMethodEvent, QInputMethodQueryEvent, inputMethodHints.

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

在widget的action列表的before前插入action. 若before为空或无效, action追加到列表.

一个QWidget应该仅有一个相同的action.

参见 removeAction(), addAction(), QMenu, contextMenuPolicy, actions().

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

在widget的action列表的before前插入actions. 若before为空或无效, actions追加到列表.

一个QWidget应该仅有一个相同的action.

参见 removeAction(), QMenu, insertAction(), and contextMenuPolicy.

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

判断widget是否是child的父对象(或祖先对象), 这两个widget处于相同的window, 返回true; 否则返回false.

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

若启用ancestor, 且widget变为启用状态, 则返回true; 否则返回false.

除ancestor外, widget及其每个父对象都没有显示禁用, 会出现这种情况.

若widget及其祖先对象被显示禁用, 则isEnabledTo(0)返回false.

ncestor指同一窗口中的父widget.

因此, isEnabledTo(0)局限在widget的窗口中, isEnabled()不同, 它会考虑父窗口.

参见 setEnabled() 和 enabled.

bool QWidget::isHidden() const

widget隐藏, 返回true, 否则返回false.

调用show()后, 隐藏的widget变为可见. 父对象显示时, 这个widget不会自动显示.

使用!isVisible(注意感叹号)判断可见性.

isHiddent() 等价于!isVisible(), 但是, 一个widget不能同时显示和隐藏. 父widget隐藏, 表明所有的子widget也是不可见的.

下列情况, widget是隐藏的:

• 作为独立窗口创建,
• 作为可见widget的子对象,
• 调用hide() or setVisible(false).

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

若ancestor可见, 且widget变为可见状态, 则返回true; 否则返回false.

除ancestor外, widget及其每个父对象都不隐藏, isVisibleTo返回true.

如果widget被屏幕上的其他窗口遮挡, 这个函数仍返回true, 如果它或它们被移动, 则可能在物理上可见.

isVisibleTo(0)等价于isVisible().

参见 show(), hide(), isVisible().

bool QWidget::isWindow() const

如果widget是独立窗口, 则返回true, 否则返回false.

窗口通常有边框和窗口标题.

窗口可以有父widget. 它被父对象管理, 父对象删除时, 也会被删除; 父对象最小化时, 也会被最小化; 等等. 若窗口管理器支持, 它也可公用父对象的公共任务栏.

QDialog和QMainWindow默认是窗口, 即便父对象是widget. 这个行为由Qt::Window指定.

参见 window(), isModal(), parentWidget().

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

处理键盘按下事件.

widget必须调用setFocusPolicy()接收焦点, 具有焦点才能接收键盘按键事件.

如果你重新实现这个函数, 你必须对不处理的按键事件调用基类实现.

用户按下QKeySequence::Cancel(标准键是Escape键)时, 默认实现是关闭弹出widget. 否则忽略事件, 以便父对象处理.

注意: 由于QKeyEvent处理时, 就表明isAccepted() == true, 因此你不需要调用QKeyEvent::accept()-只需要处理完按键事件后, 不调用基类实现.

参见 keyReleaseEvent(), setFocusPolicy(), focusInEvent(), focusOutEvent(), event(), QKeyEvent, Tetrix Example.

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

处理键盘释放事件.

widget必须初始状态时, 可接收焦点, 具有焦点才能接收键盘按键事件.

如果你重新实现这个函数, 你必须对不处理的按键事件调用基类实现.

默认实现忽略这个事件, 以便父widget处理.

注意: 由于QKeyEvent处理时, 就表明isAccepted() == true, 因此你不需要调用QKeyEvent::accept()-只需要处理完按键事件后, 不调用基类实现.

参见 keyPressEvent(), QEvent::ignore(), setFocusPolicy(), focusInEvent(), focusOutEvent(), event(), QKeyEvent.

[static] QWidget *QWidget::keyboardGrabber()

返回当前抓取键盘输入的widget.

若应用程序中没有widget抓取键盘输入, 返回nullptr.

参见 grabMouse() and mouseGrabber().

QLayout *QWidget::layout() const

返回widget的布局管理器, 若没有, 返回nullptr.

布局管理器设置加入布局的所有子widget的几何尺寸.

参见 setLayout(), sizePolicy(), Layout Management.

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

处理widget的离开事件.

鼠标光标离开widget时, 产生离开事件.

参见 enterEvent(), mouseMoveEvent(), event().

[slot] void QWidget::lower()

将widget排到父widget队列底部.

调用完这个函数后, 这个widget将显示在所有同级widget的后面.

参见 raise() 和 stackUnder().

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

将parent坐标系中的坐标点pos转到widget坐标系. parent必须不为nullptr, 必须是调用widget的父对象.

参见 mapTo(), mapFromParent(), mapFromGlobal(), underMouse().

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

屏幕坐标系的坐标点pos转到widget坐标系.

参见 mapToGlobal(), mapFrom(), mapFromParent().

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

将父widget坐标系中的坐标点pos转到widget坐标系.

若widget没有父对象, 相当于mapFromGlobal().

参见 mapToParent(), mapFrom(), mapFromGlobal(), underMouse().

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

将widget坐标系的坐标点pos转到parent坐标系. parent必须不为nullptr, 必须是调用widget的父对象.

参见 mapFrom(), mapToParent(), mapToGlobal(), anda href="qwidget.html#underMouse">underMouse().

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

将widget坐标系的坐标点pos转到屏幕坐标系.

例如, mapToGlobal(QPoint(0,0)) 返回widget左上角在全局坐标系的坐标点.

参见 mapFromGlobal(), mapTo(), mapToParent().

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

将widget坐标系的坐标点pos转到父widget的坐标系.

若widget没有父对象, 相当于mapToGlobal().

参见 mapFromParent(), mapTo(), mapToGlobal(), underMouse().

QRegion QWidget::mask() const

返回widget当前的掩码设置. 若未设置掩码, 返回空QRegion.

参见 setMask(), clearMask(), QRegion::isEmpty(), Shaped Clock Example.

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

重新实现 QPaintDevice::metric().

内部实现调用QPaintDevice::metric().

m is the metric to get.

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

处理widget的鼠标双击事件.

默认实现调用mousePressEvent().

注意: 除双击事件外, widget还接收鼠标按下和鼠标释放事件. 若与widget重叠的另一个widget在响应鼠标按下或释放事件时, 消失, 这个widget将仅接收双击事件. 开发人员应确保应用程序正确处理这些事件.

参见 mousePressEvent(), mouseReleaseEvent(), mouseMoveEvent(), event(), QMouseEvent.

[static] QWidget *QWidget::mouseGrabber()

返回当前抓取鼠标事件的widget.

若应用程序中没有widget抓取鼠标事件, 则返回nullptr.

参见 grabMouse(), keyboardGrabber().

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

处理鼠标移动事件.

如果关闭鼠标追踪, 则只有在按下鼠标移动时, 才会产生鼠标移动事件. 如果开启鼠标追踪, 即使没有按下鼠标, 也会产生鼠标移动事件.

QMouseEvent::pos()返回相对于widget的鼠标位置. 对于鼠标按下和释放事件, 位置通常与上一次鼠标移动事件的位置相同, 但是, 如果用户的手抖动, 位置可能会有不同. 这是底层窗口系统的一个特性, 而不是Qt.

如果你想在鼠标移动时, 立即显示工具提示(如, 调用QMouseEvent::pos()获取鼠标坐标, 再显示工具提示), 则必须启用鼠标追踪. 然后, 为确保工具提示立即更新, 必须在mouseMoveEvent()的实现中调用QToolTip::showText(), 而不是setToolTip().

参见 setMouseTracking(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), event(), QMouseEvent, Scribble Example.

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

处理鼠标按下事件.

如果你在mousePressEvent()或mouseReleaseEvent()中创建新widget, widget可能无法出现在你期望的位置, 这取决于底层窗口系统(或X11窗口管理器), widget的区域或其他因素.

你点击窗口以外的区域时, 默认实现关闭弹出式窗口. 其他类型widget不会做任何事情.

参见 mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), QMouseEvent, Scribble Example.

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

处理鼠标释放事件.

参见 mousePressEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), QMouseEvent, Scribble Example.

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

重载函数.

等价于move(QPoint(x, y)).

Note: Setter function for property pos.

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

处理widget移动事件. widget接收到这个事件时, 已经移动到新位置.

调用QMoveEvent::oldPos()获取以前的位置.

参见 resizeEvent(), event(), move(), QMoveEvent.

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

处理原生系统平台事件.

重新实现这个函数, 如果你想停止事件传递给Qt处理, 返回true, 并设置result. result参数仅在Windows平台有用. 如果你返回false, 本地事件会传递给Qt, 这个事件会转成Qt事件, 并发送给widget.

注意: 只有widget是本地窗口, 才能接收到这个事件.

注意: 这个函数取代Qt4的x11Event(), winEvent()和macEvent().

QWidget *QWidget::nativeParentWidget() const

返回widget的本地父窗口, 即. widget的下一个具有系统窗口id的祖先, 若widget没有任何本地父窗口, 返回nullptr.

This function was introduced in Qt 4.4.

参见 effectiveWinId().

QWidget *QWidget::nextInFocusChain() const

返回widget焦点链的下一个widget.

参见 previousInFocusChain().

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

设置窗口标志, 不会告诉窗口系统.

警告: 除非你确切知道你在做什么, 否则不要调用这个函数.

参见 setWindowFlags().

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

重新实现 QPaintDevice::paintEngine().

返回widget的绘图引擎.

注意: 用户不应该显式调用这个函数, 因为这个函数仅用于重新实现. 它由Qt内部调用, 默认实现并不会总返回有效指针.

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

处理widget的绘制事件.

绘制事件要求重绘widget部分或全部. 它由以下因素产生:

• 调用repaint() 或 update(),
• widget之前被遮挡, 现在重新显示,
• 其他原因.

重绘widget时, 许多widget可以简单地重绘整个界面, 但是一些速度较慢的widget优化后, 仅绘制请求区域: QPaintEvent::region(). 这种速度优化不会改变结果, 因为在事件处理过程中, 绘制会被裁剪到这个区域. 例如, QListView和QTableView.

Qt还试图将多个绘制事件合并为一个来加快绘制速度. 多次调用update()或窗口系统发送多个绘制事件时, Qt会将这些事件合并为一个具有较大区域的事件(参见QRegion::united()). repaint()函数不允许优化, 因此我们建议尽可能使用update().

绘制事件发生时, 更新区域通常已被擦除, 因此你正在widget的背景上绘制.

调用setBackgroundRole()和setPalette()设置背景().

从Qt 4.0开始, QWidget自动使用双缓冲绘制, 因此不需要在paintEvent()中编写双缓冲代码来避免闪烁.

注意: 通常, 你应该避免在paintEvent()内部调用update()或repaint(). 例如, 在paintEvent()中, 调用子widget的update()或repaint()会导致未定义的行为; 子widget可能会, 也可能不会得到绘制事件.

警告: 如果使用没有Qt后台存储的自定义绘制引擎, 则必须设置Qt::WA_PaintOnScreen. 否则, 将永远不会调用QWidget::paintEngine; 使用后台存储替代.

参见 event(), repaint(), update(), QPainter, QPixmap, QPaintEvent, Analog Clock Example.

QWidget *QWidget::parentWidget() const

返回父widget, 若没有父widget, 返回nullptr.

QWidget *QWidget::previousInFocusChain() const

widget焦点链中的前一个widget.

This function was introduced in Qt 4.6.

参见 nextInFocusChain().

[slot] void QWidget::raise()

将widget提升到父widget队列顶部.

调用完这个函数后, 这个widget将显示在所有同级widget的前面.

注意: 调用 activateWindow()后, 你可以调用这个函数, 确保窗口显示在顶部.

参见 lower() 和 stackUnder().

void QWidget::releaseKeyboard()

释放键盘捕获.

参见 grabKeyboard(), grabMouse(), releaseMouse().

void QWidget::releaseMouse()

释放鼠标捕获.

参见 grabMouse(), grabKeyboard(), releaseKeyboard().

void QWidget::releaseShortcut(int id)

从Qt的快捷键系统移除快捷键id. widget不再接收快捷键的QEvent::Shortcut事件(除非hi有其他快捷键).

警告: 你应该不需要使用这个函数, 因为Qt在父widget销毁时, 会自动移除快捷键. 你应该使用QAction或QShortcut处理快捷键, 它们更易于使用. 而且底层函数代价更高.

参见 grabShortcut(), setShortcutEnabled().

void QWidget::removeAction(QAction *action)

从widget的action列表中移除action.

参见 insertAction(), actions(), insertAction().

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

按照renderFlags标志, 将sourceRegion区域的内容绘制到target上, targetOffset是目标区域的起始点. 如下所示:

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

若sourceRegin是空的, 函数调用QWidget::rect作为区域, 即. widget的整个区域.

渲染前, 若有正在绘制的内容, 应调用QPainter::end(), 确保所有内容绘制到目标区域:

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

Note: 注意: 想要获取QOpenGLWidget的内容, 使用QOpenGLWidget::grabFrameBuffer().

注意: 想要获取QGLWidget(已废弃)的内容, 使用QGLWidget::grabFrameBuffer()或QGLWidget::renderPixmap()

This function was introduced in Qt 4.3.

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

重载函数.

将widget绘制到painter的QPainter::device().

Transformations and settings applied to the painter will be used when rendering.

注意: painter必须激活, 在macOS上, widget被保存到QPixmap, 然后被painter绘制.

参见 QPainter::device().

[slot] void QWidget::repaint()

除非禁用更新或widget隐藏, 调用这个函数会立即调用 paintEvent(), 直接重绘widget.

如果你需要立即重绘, 例如动画期间, 我们建议仅使用repaint(). 在大部分情况下, update() 更好, 因为它允许Qt优化速度, 并最大限度地减少闪烁.

警告: 如果你在 paintEvent()内部调用repaint(), 你可能无限递归. The update() 函数没有此问题.

参见 update(), paintEvent(), setUpdatesEnabled().

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

重载函数.

重绘widget的区域 (x, y, w, h).

If w is negative, it is replaced with width() - x, and if h is negative, it is replaced width height() - y.

void QWidget::repaint(const QRect &rect)

重载函数.

重绘widget的区域 rect.

void QWidget::repaint(const QRegion &rgn)

重载函数.

重绘widget的区域 rgn.

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

重载函数.

相当于 resize(QSize(w, h)).

注意: 属性 size的设置函数.

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

处理widget调整大小事件. 调用resizeEvent()前, widget已有新的尺寸. 调用QResizeEvent::oldSize()获取以前的大小.

大小调整事件后, 立即擦除widget, 并生成绘制事件. 不需要(或不应该)在函数中再次绘制.

参见 moveEvent(), event(), resize(), QResizeEvent, paintEvent(), Scribble Example.

bool QWidget::restoreGeometry(const QByteArray &geometry)

从参数geometry中还原顶级widget的几何尺寸和状态. 若成功, 返回true; 否则, 返回false.

If the restored geometry is off-screen, it will be modified to be inside the available screen geometry.

若存储在QSettings中, 你可以使用如下代码:

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

See the Window Geometry documentation for an overview of geometry issues with windows.

调用 QMainWindow::restoreState(), 还原工具条和停靠widget的几何尺寸和状态.

This function was introduced in Qt 4.2.

参见 saveGeometry(), QSettings, QMainWindow::saveState(), and QMainWindow::restoreState().

QByteArray QWidget::saveGeometry() const

保存顶级widget的当前几何尺寸和状态.

若在窗口关闭时, 保存几何尺寸, 你可以在closeEvent()实现如下代码:

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

See the Window Geometry documentation for an overview of geometry issues with windows.

调用 QMainWindow::saveState(), 保存工具条和停靠widget的几何尺寸和状态.

This function was introduced in Qt 4.2.

参见 restoreGeometry(), QMainWindow::saveState(), QMainWindow::restoreState().

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

滚动widget, 向右滚动dx像素, 向下滚动dy像素. dx和dy可能为负值.

滚动后, widget将接收到绘制事件, 重绘需要绘制的区域. 若是不透明窗口, Qt仅更新新暴露的部分. 例如, 若一个不透明的widget向左滚动8个像素, 那么只有右边缘的8个像素宽的区域需要更新.

由于widget默认情况下传播父对象的内容, 因此你需要设置autoFillBackground属性, 或调用setAttribute(), 参数使用Qt::WA_OpaquePaintEvent, 设置widget为不透明.

对于使用内容传播的widget, 滚动将更新整个区域.

参见 Transparency and Double Buffering.

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

重载函数.

这个函数仅滚动r区域, 不移动子widget.

若r是空的或无效的, 则结果未定义.

参见 QScrollArea.

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

若on是true, 设置attribute属性; 否则, 清除属性.

参见 testAttribute().

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

设置widget的背景角色role.

背景角色定义widget的调色板画刷palette, 用于渲染背景.

若role是QPalette::NoRole, widget继承父对象的背景角色.

注意: 样式可以自由选择调色板的任意颜色. 如果调用setBackgroundRole()无法得到你想要的结果, 则你可以修改调色板或设置样式表.

参见 backgroundRole() and foregroundRole().

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

重载函数.

等价于 setBaseSize(QSize(basew, baseh)). 设置widget的 基本宽度basew 和基本高度 baseh.

注意: 这个函数是属性baseSize的设置函数.

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

设置widget内容的外边距. 外边距用于布局系统, 可能被子类用于在特定区域绘制 (如. 不包含边框).

改变外边距将触发 resizeEvent().

参见 contentsMargins(), contentsRect(), getContentsMargins().

void QWidget::setContentsMargins(const QMargins &margins)

重载函数.

设置widget内容的外边距. 外边距用于布局系统, 可能被子类用于在特定区域绘制 (如. 不包含边框).

改变外边距将触发 resizeEvent().

This function was introduced in Qt 4.6.

参见 contentsRect() and getContentsMargins().

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

若 disable 是true, 禁止widget输入事件; 否则, 启用输入事件.

详见 enabled.

参见 isEnabledTo(), QKeyEvent, QMouseEvent, and changeEvent().

void QWidget::setEditFocus(bool enable)

若enable是true, widget具有编辑焦点, Qt::Key_Up和Qt::Key_Down会分发到widget; 否则, Qt::Key_Up和Qt::Key_Down不会改变焦点.

这个特性仅在嵌入式Linux有效.

参见 hasEditFocus(), QApplication::keypadNavigationEnabled().

void QWidget::setFixedHeight(int h)

同时设置widget的最小高度, 最大高度, 且不改变宽度.

参见 sizeHint(), minimumSize(), maximumSize(), setFixedSize().

void QWidget::setFixedSize(const QSize &s)

同时设置widget的最小宽高, 最大宽高, 限制改变宽高.

这会覆盖QLayout的默认大小限制.

设置大小为QWIDGETSIZE_MAX会移除限制.

若你希望widget根据内容有固定的大小, 你可以调用QLayout::setSizeConstraint(QLayout::SetFixedSize);

参见 maximumSize, minimumSize.

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

重载函数.

设置widget的宽高.

void QWidget::setFixedWidth(int w)

同时设置widget的最小宽度, 最大宽度, 且不改变高度.

参见 sizeHint(), minimumSize(), maximumSize(), setFixedSize().

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

若widget或它的父对象之一是激活窗口, 则把键盘的输入焦点设给widget (或它的焦点代理). 参数 reason 表示接受何种焦点事件. 若窗口是未激活状态, 则窗口激活时, widget获取焦点.

首先, 焦点改变事件发送给当前焦点widget(如果有), 告诉它将要失去焦点. 然后, 更改焦点, 将焦点从上一个焦点widget移除, 移入到新的widget, 并告知它收到焦点. (如果焦点进入和移出widget相同, 则不会发生任何事情.)

注意: 在嵌入式平台, setFocus() 不会打开输入面板. 如果你希望调出输入面板, 则你必须向widget发送一个QEvent::RequestSoftwareInputPanel事件.

不管焦点策略是什么, setFocus()设置widget焦点, 但是不清除键盘抓取(参见grabKeyboard()).

注意: widget隐藏时, 无法接收焦点, 只有显示时才可以.

警告: 在focusOutEvent()或focusInEvent()中调用setFocus(), 可能无限递归.

参见 hasFocus(), clearFocus(), focusInEvent(), focusOutEvent(), setFocusPolicy(), focusWidget(), QApplication::focusWidget(), grabKeyboard(), grabMouse(), Keyboard Focus in Widgets, QEvent::RequestSoftwareInputPanel.

[slot] void QWidget::setFocus()

重载函数.

如果widget或父对象之一是激活窗口, 则键盘输入将提供给这个widget(或它的焦点代理).

void QWidget::setFocusProxy(QWidget *w)

设置widget的焦点代理w. 若w是nullptr, 函数重置widget为无代理.

某些widget可以"具有焦点", 但是需要创建一个实际处理焦点的子widget, 如QLineEdit. 这样, 这个widget可以设置QLineEdit作为焦点代理.

widget得到焦点时, 调用setFocusProxy()设置的widget真正得到焦点. 若设置焦点代理, setFocus()和hasFocus()作用于焦点代理. 若这个widget是焦点widget, 则调用setFocusProxy()会将焦点移动到新的焦点代理.

参见 focusProxy().

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

设置widget的前景角色 role.

前景角色定义widget的调色板palette画刷, 用于渲染前景.

若role是QPalette::NoRole, widget继承父对象的前景角色.

注意: 样式可以自由选择调色板的任意颜色. 如果调用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)

设置widget的图形特效.

若widget已存在一个特效, QWidget在初始化新特效前, 删除已存在的特效.

若特效已经在其他widget上初始化, setGraphicsEffect()将从其他widget上移除, 然后初始化在这个widget上.

QWidget具有特效的所有权.

注意: 这个函数将在它和所有子级上应用特效.

注意: 基于OpenGL的widget不支持图形特效, 如QGLWidget, QOpenGLWidget, QQuickWidget.

This function was introduced in Qt 4.6.

参见 graphicsEffect().

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

widget显隐, 等价于 setVisible(!hidden).

参见 isHidden().

void QWidget::setLayout(QLayout *layout)

设置widget的布局管理器 layout.

若widget已初始化一个布局管理器, QWidget不能初始化另一个. 在调用setLayout()设置新布局管理器前, 你必须删除已存在的布局管理器(调用layout()).

若layout是其他widget的布局管理器, 调用setLayout()将重置它的父对象, 使布局管理器管理当前widget.

例如:

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

你也可以在调用布局管理器时, 传入这个widget.

QWidget 具有布局管理器layout的所有权.

参见 layout(), Layout Management.

void QWidget::setMask(const QBitmap &bitmap)

仅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(), Shaped Clock Example.

void QWidget::setMask(const QRegion &region)

重载函数.

仅region区域的widget可见. 若region区域超出widget的rect(), 则窗口系统控制超出部分是否可见, 具体取决于平台.

注意: 若区域很复杂, 会影响性能.

参见 windowOpacity.

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

重载函数.

这个函数等价于setMaximumSize(QSize(maxw, maxh)).

注意: 这个函数是属性 maximumSize的设置函数.

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

重载函数.

这个函数等价于setMinimumSize(QSize(minw, minh)).

注意: 这个函数是属性 minimumSize的设置函数.

void QWidget::setParent(QWidget *parent)

设置widget的父对象, 并重置窗口标志. widget被移动到父对象的(0,0)位置.

若新的父widget在不同的窗口, 则重置父对象的widget和它的子对象按照之前的顺序添加到新的父widget的Tab链表末尾. If one of the moved widgets had keyboard focus, setParent() calls clearFocus() for that widget.

若新的父widget与旧的父widget属于同一个窗口, 重置父对象不会改变Tab顺序和键盘焦点.

若新的父widget与旧的父widget相同, 则这个函数不起任何作用.

注意: 更改父对象, widget将变为不可见, 即使之前可见. 你必须调用show()才能使widget再次可见.

警告: 你不太可能需要这个功能. 如果你需要动态改变widget, 则使用QStackedWidget更合适.

参见 setWindowFlags().

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

重载函数.

这个函数也会设置widget标识f.

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

若enable是ture, 则自动重复快捷键; 否则禁用.

This function was introduced in Qt 4.2.

参见 grabShortcut() and releaseShortcut().

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

若enable是true, 则启用快捷键; 否则禁用.

警告: 你通常不需要调用这个函数, widget隐藏/显示或者失去/得到焦点时, Qt自动禁用/启用快捷键. 最好使用QAction或QShortcut处理快捷方式, 这两个类比低级函数更容易使用.

参见 grabShortcut(), releaseShortcut().

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

重载函数.

设置宽高的增加量.

注意: 这个函数是属性 sizeIncrement的设置函数.

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

重载函数.

设置widget的水平和垂直拉伸策略.

注意: 这个函数是属性 sizePolicy的设置函数.

参见 QSizePolicy::QSizePolicy().

void QWidget::setStyle(QStyle *style)

设置widget的GUI样式. 样式对象的所有权不会转移.

若没有设置样式, 则widget使用应用程序的样式, QApplication::style().

设置widget的样式不会影响已存在或以后的子widget.

警告: 这个函数在演示时特别有用, 你可以在演示中展示Qt的样式功能. 实际的应用程序应该避免它, 而是使用统一的GUI样式.

警告: Qt样式表不支持自定义QStyle子类, 我们计划在后续版本支持.

参见 style(), QStyle, QApplication::style(), QApplication::setStyle().

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

改变widget的焦点顺序, 将second放在first之后.

注意: 由于second的Tab顺序发生改变, 你应该以如下方式排序焦点链:

  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()可以正确处理代理.

注意: 从Qt5.10开始, 一个具有焦点代理的widget视为一个复合widget. 在一个复合widget设置tab顺序时, 保留每个widget的内部tab顺序. 这意味着, 如果两个widget都是复合widget, 则生成的顺序是从第一个widget的最后一个子widget到第二个widget的第一个子widget

参见 setFocusPolicy(), setFocusProxy(), Keyboard Focus in Widgets.

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

若on是true, 设置窗口标志; 否则, 清除标志.

This function was introduced in Qt 5.9.

参见 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);

调用这个函数将隐藏widget. 你必须调用show()使widget重见.

Note: On some window systems Qt::WindowActive is not immediate, and may be ignored in certain cases.

窗口状态改变时, widget收到changeEvent(), 类型是QEvent::WindowStateChange.

参见 Qt::WindowState, windowState().

void QWidget::setupUi(QWidget *widget)

设置特定的用户界面.

注意: 这个函数用于使用派生自uic创建的用户界面的widget.

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