QWidget 类

QWidget 类是所有用户界面对象的基类。 更多...

公共类型

enum RenderFlag { DrawWindowBackground, DrawChildren, IgnoreMask }
flags RenderFlags

特性

公共函数

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

重实现公共函数

virtual QPaintEngine * paintEngine () const override

公共槽

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

信号

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

静态公共成员

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

保护函数

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

重实现保护函数

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

保护槽

void updateMicroFocus (Qt::InputMethodQuery query = Qt::ImQueryAll)

详细描述

Widget 是用户界面原子:它从窗口系统接收鼠标、键盘及其它事件,并在屏幕上描绘自身表示。每个 Widget 为矩形,且按 Z 次序排序。Widget 被父级及其前面的小部件裁剪。

未嵌入父级小部件的 Widget 称为窗口。通常,窗口拥有框架和标题栏,尽管还可以创建不带这种装饰的窗口使用适合 窗口标志 。在 Qt 中, QMainWindow 和各种子类化 QDialog 是最常见的窗口类型。

每个 Widget 的构造函数接受 1 个或 2 个标准自变量:

  1. QWidget *parent = nullptr 是新 Widget 的父级。若它为 nullptr (默认),新的小部件将是窗口。若不是,它将是子级对于 parent ,并被约束由 parent 的几何体 (除非指定 Qt::Window 作为窗口标志)。
  2. Qt::WindowFlags f = { } (若可用的话) 设置窗口标志;默认适于几乎所有小部件,但要获得如没有窗口系统框架的窗口,就必须使用特殊标志。

QWidget 有很多成员函数,但其中一些拥有很少的直接功能; QLabel , QPushButton , QListWidget ,和 QTabWidget .

顶层和子级 Widget

没有父级小部件的 Widget 始终是独立窗口 (顶层小部件)。对于这些小部件, setWindowTitle () 和 setWindowIcon () 分别设置标题栏和图标。

非窗口 Widget 是子级小部件,显示在其父级小部件内。Qt 中的大多数 Widget 主要用作子级小部件。例如,将按钮显示成顶层窗口是可能的,但大多数人更喜欢将按钮放在其它小部件内,譬如 QDialog .

A parent widget containing various child widgets.

以上简图展示 QGroupBox 小部件用于将各种子级 Widget 保持在布局中,提供通过 QGridLayout QLabel 子级小部件已提纲以指示其完整大小。

若想要使用 QWidget 来保持子级小部件,通常需要向父 QWidget 添加布局。见 布局管理 了解更多信息。

复合 Widget

当 Widget 被用作分组多个子级 Widget 的容器时,它被称为复合 Widget。这些可以被创建,通过构造 Widget 采用所需视觉特性 QFrame ,例如:把子级 Widget 添加给它,通常由布局进行管理。上图展示使用 Qt Designer 创建这种复合小部件。

复合 Widget 还可以被创建,通过子类化标准 Widget,如 QWidget 或 QFrame ,并在子类的构造函数中添加必要布局和子级 Widget。许多 随 Qt 提供的范例 使用这种途径,且它还涵盖于 Qt 教程 .

自定义 Widget 和描绘

由于 QWidget 是子类化的 QPaintDevice ,子类可以被用于显示由一系列描绘操作组成的自定义内容,采用实例化的 QPainter 类。此途径对比画布样式途径使用 图形视图框架 ,其中的项由应用程序添加到场景,并由框架本身渲染。

每个 Widget 履行所有描绘操作均在其 paintEvent () 函数。这被调用,每当 Widget 需要被重新绘制时,作为某些外部改变的结果或当应用程序请求时。

指针式时钟范例 展示简单 Widget 如何处理描绘事件。

大小提示和大小策略

当实现新的 Widget 时,它始终很有用去重实现 sizeHint () 以为 Widget 提供合理默认大小和设置校正大小策略采用 setSizePolicy ().

默认情况下,不提供大小提示的复合 Widget 将根据其子小部件的空间要求调整大小。

大小策略让您为布局管理系统提供良好的默认行为,以便其它 Widget 可以轻松包含和管理您的小部件。默认大小策略指示表示首选 Widget 大小的大小提示,且这对许多 Widget 来说经常已足够。

注意: 顶层 Widget 尺寸被约束到桌面高度和宽度的 2/3。可以 resize () Widget 手动若这些界限不够。

事件

Widget 通常响应由用户动作导致的事件。Qt 向 Widget 交付事件是通过调用特定事件处理函数,采用实例化的 QEvent 子类包含每个事件的有关信息。

若小部件只包含子级 Widget,可能不需要实现任何事件处理程序。若想要检测子级 Widget 中的鼠标点击,调用子级的 underMouse () 函数在 Widget 的 mousePressEvent ().

涂鸦范例 实现一组更广泛事件来处理鼠标移动、按钮按下及重置窗口大小。

需要为自己的 Widget 提供行为和内容,这里是 QWidget 相关事件的简要概述,从最常见的开始:

  • paintEvent () 被调用每当需要重新描绘 Widget 时。每个显示自定义内容的 Widget 都必须实现它。描绘使用 QPainter 只可以发生在 paintEvent () 或函数调用通过 paintEvent ().
  • resizeEvent () 被调用当 Widget 被重置大小时。
  • mousePressEvent () 被调用当鼠标光标在 Widget 内按下鼠标按钮时,或者当 Widget 有抓取鼠标使用 grabMouse ()。按下鼠标不释放它如同有效调用 grabMouse ().
  • mouseReleaseEvent () is called when a mouse button is released. A widget receives mouse release events when it has received the corresponding mouse press event. This means that if the user presses the mouse inside your widget, then drags the mouse somewhere else before releasing the mouse button, your widget receives the release event. There is one exception: if a popup menu appears while the mouse button is held down, this popup immediately steals the mouse events.
  • mouseDoubleClickEvent () is called when the user double-clicks in the widget. If the user double-clicks, the widget receives a mouse press event, a mouse release event, (a mouse click event,) a second mouse press, this event and finally a second mouse release event. (Some mouse move events may also be received if the mouse is not held steady during this operation.) It is not possible to distinguish a click from a double-click until the second click arrives. (This is one reason why most GUI books recommend that double-clicks be an extension of single-clicks, rather than trigger a different action.)

Widgets that accept keyboard input need to reimplement a few more event handlers:

  • keyPressEvent () is called whenever a key is pressed, and again when a key has been held down long enough for it to auto-repeat. The Tab and Shift+Tab keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement QWidget::event ().
  • focusInEvent () is called when the widget gains keyboard focus (assuming you have called setFocusPolicy ()). Well-behaved widgets indicate that they own the keyboard focus in a clear but discreet way.
  • focusOutEvent () is called when the widget loses keyboard focus.

You may be required to also reimplement some of the less common event handlers:

  • mouseMoveEvent () is called whenever the mouse moves while a mouse button is held down. This can be useful during drag and drop operations. If you call setMouseTracking (true), you get mouse move events even when no buttons are held down. (See also the 拖放 指南。)
  • keyReleaseEvent () is called whenever a key is released and while it is held down (if the key is auto-repeating). In that case, the widget will receive a pair of key release and key press event for every repeat. The Tab and Shift+Tab keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement QWidget::event ().
  • wheelEvent () is called whenever the user turns the mouse wheel while the widget has the focus.
  • enterEvent () is called when the mouse enters the widget's screen space. (This excludes screen space owned by any of the widget's children.)
  • leaveEvent () is called when the mouse leaves the widget's screen space. If the mouse enters a child widget it will not cause a leaveEvent ().
  • moveEvent () is called when the widget has been moved relative to its parent.
  • closeEvent () is called when the user closes the widget (or when close () 被调用)。

There are also some rather obscure events described in the documentation for QEvent::Type . To handle these events, you need to reimplement event () directly.

The default implementation of event () 处理 Tab and Shift+Tab (to move the keyboard focus), and passes on most of the other events to one of the more specialized handlers above.

Events and the mechanism used to deliver them are covered in 事件系统 .

函数和特性组

上下文 函数和特性
窗口函数 show (), hide (), raise (), lower (), close ().
顶层窗口 windowModified , windowTitle , windowIcon , isActiveWindow , activateWindow (), minimized , showMinimized (), maximized , showMaximized (), fullScreen , showFullScreen (), showNormal ().
窗口内容 update (), repaint (), scroll ().
几何体 pos , x (), y (), rect , size , width (), height (), move (), resize (), sizePolicy , sizeHint (), minimumSizeHint (), updateGeometry (), layout (), frameGeometry , geometry , childrenRect , childrenRegion , adjustSize (), mapFromGlobal (), mapToGlobal (), mapFromParent (), mapToParent (), maximumSize , minimumSize , sizeIncrement , baseSize , setFixedSize ()
模式 visible , isVisibleTo (), enabled , isEnabledTo (), modal , isWindow (), mouseTracking , updatesEnabled , visibleRegion ().
外观和感觉 style (), setStyle (), styleSheet , cursor , font , palette , backgroundRole (), setBackgroundRole (), fontInfo (), fontMetrics ().
键盘聚焦函数 focus , focusPolicy , setFocus (), clearFocus (), setTabOrder (), setFocusProxy (), focusNextChild (), focusPreviousChild ().
鼠标和键盘抓取 grabMouse (), releaseMouse (), grabKeyboard (), releaseKeyboard (), mouseGrabber (), keyboardGrabber ().
事件处理程序 event (), mousePressEvent (), mouseReleaseEvent (), mouseDoubleClickEvent (), mouseMoveEvent (), keyPressEvent (), keyReleaseEvent (), focusInEvent (), focusOutEvent (), wheelEvent (), enterEvent (), leaveEvent (), paintEvent (), moveEvent (), resizeEvent (), closeEvent (), dragEnterEvent (), dragMoveEvent (), dragLeaveEvent (), dropEvent (), childEvent (), showEvent (), hideEvent (), customEvent (). changeEvent (),
系统函数 parentWidget (), window (), setParent (), winId (), find (), metric ().
上下文菜单 contextMenuPolicy , contextMenuEvent (), customContextMenuRequested (), actions ()
交互式帮助 setToolTip (), setWhatsThis ()

Widget 样式表

除各平台的标准小部件样式外,Widget 还可以根据指定规则被样式化在 样式表 。此特征使您能够定制特定 Widget 外观,以向用户提供有关其目的的视觉暗示。例如,可以按特定方式样式化按钮,以指示它履行破坏性动作。

Widget 样式表用法的更详细描述在 Qt 样式表 文档。

透明度和双缓冲

从 Qt 4.0 起,QWidget 自动对其绘制双缓冲,因此不需要编写双缓冲代码在 paintEvent () 以避免闪烁。

从 Qt 4.1 起,默认情况下,父级小部件的内容会被传播给其每一子级只要 Qt::WA_PaintOnScreen 未设置。可以通过更新不规则区域 (以创建非矩形子级小部件) 或采用小于完整 Alpha 分量的颜色描绘来编写自定义 Widget 以利用此特征。以下简图展示如何微调自定义 Widget 的属性和特性来达成不同效果。

在以上简图中,构造移除区域的半透明矩形子级小部件并将其添加到父级 Widget ( QLabel 展示像素图)。然后,设置不同特性和 Widget 属性以达成不同效果:

  • 左侧 Widget 没有设置额外特性或小部件属性。此默认状态适合大多数使用透明度的自定义 Widget,形状不规则 Widget 或采用透明笔刷描绘其整个区域的 Widget。
  • 居中 Widget 拥有 autoFillBackground 设置特性。此特性用于依赖小部件提供默认背景的自定义 Widget,且采用透明笔刷在其整个区域进行描绘。
  • 右侧 Widget 拥有 Qt::WA_OpaquePaintEvent Widget 设置属性。这指示 Widget 将采用不透明颜色描绘其整个区域。小部件区域最初为 uninitialized ,在简图中采用红色对角栅格图案表示 (透过重绘区域闪耀)。Qt::WA_OpaquePaintArea 属性对于需要快速描绘其自己的特定内容且不需要默认填充背景的 Widget 很有用。

要采用简单背景颜色快速更新自定义 Widget (譬如:实时绘图或图形化 Widget),最好定义合适的背景颜色 (使用 setBackgroundRole () 采用 QPalette::Window 角色),设置 autoFillBackground 特性,且仅实现必要绘图功能在小部件的 paintEvent ().

要快速更新不断采用不透明内容描绘其整个区域的自定义 Widget (如:视频流小部件),最好设置小部件的 Qt::WA_OpaquePaintEvent ,避免关联重新描绘 Widget 背景的任何不必要开销。

若 Widget 拥有 Qt::WA_OpaquePaintEvent Widget 属性 and the autoFillBackground 设置特性, Qt::WA_OpaquePaintEvent 属性优先。根据要求,应选择它们之一。

从 Qt 4.1 起,父级 Widget 的内容还被传播给标准 Qt 小部件。若父级小部件以非标准方式装饰,这可能导致一些意外结果,如以下简图所示。

在不诉诸子类化的情况下,定制标准 Qt 小部件的描绘行为的作用域,可能略小于自定义 Widget 的作用域。通常,可以达成标准 Widget 期望的外观通过设置其 autoFillBackground 特性。

创建半透明窗口

从 Qt 4.5 起,在支持合成的窗口系统创建具有半透明区域的窗口是可能的。

要在顶层 Widget 启用此特征,设置其 Qt::WA_TranslucentBackground 属性采用 setAttribute () 并确保在想要部分透明的区域中采用透明颜色绘制其背景。

平台注意事项:

  • X11:此特征依赖于支持 ARGB 视觉和合成窗口管理器的 X 服务器使用。
  • Windows:小部件需要拥有 Qt::FramelessWindowHint 设置窗口标志为半透明能工作。

本机小部件 vs 外来小部件

在 Qt 4.4 引入的外来 Widget 是窗口系统的未知小部件。它们没有关联它们的本机窗口句柄。此特征可显著提高小部件描绘、重置尺寸及移除闪烁的速度。

若要求采用本机窗口的旧行为,可以选择以下选项之一:

  1. 使用 QT_USE_NATIVE_WINDOWS=1 在环境中。
  2. 设置 Qt::AA_NativeWindows 应用程序属性。所有 Widget 将是本机小部件。
  3. 设置 Qt::WA_NativeWindow 小部件属性:小部件本身及其所有祖先将变为本机的 (除非 Qt::WA_DontCreateNativeAncestors 有设置)。
  4. 调用 QWidget::winId 以强制本机窗口 (这隐含 3)。
  5. 设置 Qt::WA_PaintOnScreen 属性以强制本机窗口 (这隐含 3)。

另请参阅 QEvent , QPainter , QGridLayout ,和 QBoxLayout .

成员类型文档编制

enum QWidget:: RenderFlag
flags QWidget:: RenderFlags

此枚举描述如何渲染 Widget 当调用 QWidget::render ().

常量 描述
QWidget::DrawWindowBackground 0x1 若启用此选项,Widget 背景被渲染到目标即使 autoFillBackground 未设置。默认情况下,此选项是启用的。
QWidget::DrawChildren 0x2 若启用此选项,Widget 的子级被递归渲染到目标。默认情况下,此选项是启用的。
QWidget::IgnoreMask 0x4 若启用此选项,Widget 的 QWidget::mask () 被忽略当渲染到目标时。默认情况下,此选项是禁用的。

RenderFlags 类型是 typedef 对于 QFlags <RenderFlag>。它存储 RenderFlag 值的 OR 组合。

特性文档编制

acceptDrops : bool

此特性保持是否为此 Widget 启用下落事件

把此特性设为 true 向系统宣布此 Widget may 能够接受掉落事件。

若 Widget 是桌面 ( windowType () == Qt::Desktop ),这可能失败,若另一应用程序正在使用桌面;可以调用 acceptDrops() 去测试,若这发生。

警告: 不要在拖放事件处理程序中修改此特性。

默认情况下此特性为 false .

访问函数:

bool acceptDrops () const
void setAcceptDrops (bool on )

另请参阅 拖放 .

accessibleDescription : QString

此特性按通过辅助技术可见保持 Widget 的描述

Widget 的可访问描述应该传达小部件能做什么。而 accessibleName 应该是简短且简洁的字符串 (如 Save ),描述应该给出更多上下文,譬如 保存当前文档 .

此特性必须为 localized .

默认情况下,此特性包含空字符串,且 Qt 会回退到使用工具提示以提供此信息。

访问函数:

QString accessibleDescription () const
void setAccessibleDescription (const QString & description )

另请参阅 QWidget::accessibleName and QAccessibleInterface::text ().

accessibleName : QString

此特性保持通过辅助技术可见的 Widget 名称

这是通过辅助技术 (譬如:屏幕阅读器) 宣布此 Widget 的首要名称。对于大多数 Widget,不要求设置此特性。例如对于 QPushButton 将使用按钮文本。

设置此特性很重要,当 Widget 不提供任何文本时。例如,仅包含图标的按钮需要设置此特性以工作于屏幕阅读器。名称应简短且等效于由 Widget 传达的视觉信息。

此特性必须为 localized .

默认情况下,此特性包含空字符串。

访问函数:

QString accessibleName () const
void setAccessibleName (const QString & name )

另请参阅 QWidget::accessibleDescription and QAccessibleInterface::text ().

autoFillBackground : bool

此特性保持是否自动填充 Widget 背景

若启用,此特性将导致 Qt 填充 Widget 背景在援引描绘事件之前。使用颜色的定义通过 QPalette::Window 颜色角色来自 Widget 的 palette .

此外,填充窗口总是采用 QPalette::Window ,除非有设置 WA_OpaquePaintEvent 或 WA_NoSystemBackground 属性。

此特性无法被关闭 (即设为 false),若 Widget 父级拥有用于其背景的静态渐变。

警告: 使用此特性要谨慎当结合 Qt 样式表 。当 Widget 拥有带有效背景或边框图像的样式表时,此特性被自动禁用。

默认情况下此特性为 false .

访问函数:

bool autoFillBackground () const
void setAutoFillBackground (bool enabled )

另请参阅 Qt::WA_OpaquePaintEvent , Qt::WA_NoSystemBackground ,和 透明度和双缓冲 .

baseSize : QSize

此特性保持 Widget 的基尺寸

基尺寸用于计算适当 Widget 尺寸,若小部件有定义 sizeIncrement ().

默认情况下,对于新近创建的 Widget,此特性包含 0 宽高尺寸。

访问函数:

QSize baseSize () const
void setBaseSize (const QSize &)
void setBaseSize (int basew , int baseh )

另请参阅 setSizeIncrement ().

[read-only] childrenRect : const QRect

此特性保持 Widget 子级的边界矩形

排除隐藏子级。

默认情况下,对于没有子级的 Widget,此特性包含位于原点的 0 宽高矩形。

访问函数:

QRect childrenRect () const

另请参阅 childrenRegion () 和 geometry ().

[read-only] childrenRegion : const QRegion

此特性保持由 Widget 子级占据的组合区域

排除隐藏子级。

默认情况下,对于没有子级的 Widget,此特性包含空区域。

访问函数:

QRegion childrenRegion () const

另请参阅 childrenRect (), geometry (),和 mask ().

contextMenuPolicy : Qt::ContextMenuPolicy

Widget 如何展示上下文菜单

此特性的默认值为 Qt::DefaultContextMenu ,这意味着 contextMenuEvent () 处理程序被调用。其它值 Qt::NoContextMenu , Qt::PreventContextMenu , Qt::ActionsContextMenu ,和 Qt::CustomContextMenu 。采用 Qt::CustomContextMenu ,信号 customContextMenuRequested () 被发射。

访问函数:

Qt::ContextMenuPolicy contextMenuPolicy () const
void setContextMenuPolicy (Qt::ContextMenuPolicy policy )

另请参阅 contextMenuEvent (), customContextMenuRequested (),和 actions ().

cursor : QCursor

此特性保持此 Widget 的光标形状

鼠标光标将假定此形状,当它越过此 Widget 时。见 预定义光标对象列表 了解有用形状范围。

编辑器 Widget 可能使用 I-beam 光标:

setCursor(Qt::IBeamCursor);
							

若未设置光标,或在调用 unsetCursor() 之后,则使用父级的光标。

默认情况下,此特性包含的光标具有 Qt::ArrowCursor 形状。

一些底层窗口实现将重置光标若它离开 Widget,即使鼠标被抓取。若想要为所有 Widget 设置光标,即使在窗口外,请考虑 QGuiApplication::setOverrideCursor ().

访问函数:

QCursor cursor () const
void setCursor (const QCursor &)
void unsetCursor ()

另请参阅 QGuiApplication::setOverrideCursor ().

enabled : bool

此特性保持 Widget 是否被启用

通常,启用 Widget 处理键盘和鼠标事件;禁用小部件不会。例外是 QAbstractButton .

某些 Widget 按不同方式显示自身,当它们被禁用时。例如,按钮可能将其标签绘制为灰色。若 Widget 需要知道它何时变为启用或禁用,可以使用 changeEvent () 采用类型 QEvent::EnabledChange .

禁用 Widget 隐式禁用其所有子级。启用会分别启用所有子级 Widget,除非它们被明确禁用。明确启用不是窗口的子级 Widget (而其父级 Widget 仍被禁用) 是不可能的。

默认情况下此特性为 true .

访问函数:

bool isEnabled () const
void setEnabled (bool)

另请参阅 isEnabledTo (), QKeyEvent , QMouseEvent ,和 changeEvent ().

[read-only] focus : const bool

此特性保持此 Widget (或其聚焦代理) 是否拥有键盘输入聚焦

默认情况下此特性为 false .

注意: 获取 Widget 此特性值有效相当于校验是否 QApplication::focusWidget () 引用 Widget。

访问函数:

bool hasFocus () const

另请参阅 setFocus (), clearFocus (), setFocusPolicy (),和 QApplication::focusWidget ().

focusPolicy : Qt::FocusPolicy

此特性保持 Widget 接受键盘聚焦的方式

策略为 Qt::TabFocus 若 Widget 通过 Tab 键接受键盘聚焦, Qt::ClickFocus 若 Widget 通过点击接受聚焦, Qt::StrongFocus 若它接受两者,而 Qt::NoFocus (默认) 若它根本不接受聚焦。

必须为 Widget 启用键盘聚焦,若它处理键盘事件。通常这是由 Widget 构造函数完成的。例如, QLineEdit 构造函数调用 setFocusPolicy( Qt::StrongFocus ).

若 Widget 有聚焦代理,聚焦策略就会传播给它。

访问函数:

Qt::FocusPolicy focusPolicy () const
void setFocusPolicy (Qt::FocusPolicy policy )

另请参阅 focusInEvent (), focusOutEvent (), keyPressEvent (), keyReleaseEvent (),和 enabled .

font : QFont

此特性保持 Widget 目前设置的字体

此特性描述 Widget 的请求字体。字体用于 Widget 的样式当渲染标准组件时,且可用作确保自定义 Widget 与本机平台外观和感觉可以保持一致的手段。不同平台或不同样式,为应用程序定义不同字体是很常见的。

当将新字体赋值给 Widget 时,此字体特性组合小部件默认字体以形成小部件最终字体。可以调用 fontInfo () 获取 Widget 的最终字体副本。最终字体还用于初始化 QPainter 的字体。

默认从属系统环境。 QApplication 维护系统/主题字体 (充当所有 Widget 的默认)。某些类型的 Widget 还可能有特殊默认字体。也可以为 Widget 自己定义默认字体,通过将自定义字体和小部件名称传递给 QApplication::setFont ()。最后,字体匹配 Qt 字体数据库以找到最佳匹配。

QWidget 明确从父级传播字体特性到子级。若改变字体具体特性并将该字体赋值给 Widget,该特性将传播给小部件的所有子级,覆盖该特性的任何系统默认值。注意,默认情况下,字体不会被传播给窗口 (见 isWindow ()) 除非 Qt::WA_WindowPropagation 属性被启用。

QWidget 的字体传播类似于其调色板传播。

The current style, which is used to render the content of all standard Qt widgets, is free to choose to use the widget font, or in some cases, to ignore it (partially, or completely). In particular, certain styles like GTK style, Mac style, and Windows Vista style, apply special modifications to the widget font to match the platform's native look and feel. Because of this, assigning properties to a widget's font is not guaranteed to change the appearance of the widget. Instead, you may choose to apply a styleSheet .

注意: Qt 样式表 用于如 setFont() 的相同 Widget,样式表优先若设置冲突。

访问函数:

const QFont & font () const
void setFont (const QFont &)

另请参阅 fontInfo () 和 fontMetrics ().

[read-only] frameGeometry : const QRect

相对于其父级包括任何窗口框架的 Widget 几何体

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

默认情况下,此特性包含从属用户平台和屏幕几何体的值。

访问函数:

QRect frameGeometry () const

另请参阅 geometry (), x (), y (),和 pos ().

[read-only] frameSize : const QSize

此特性保持包括任何窗口框架的 Widget 尺寸

默认情况下,此特性包含从属用户平台和屏幕几何体的值。

访问函数:

QSize frameSize () const

[read-only] fullScreen : const bool

此特性保持 Widget 是否以全屏模式展示

全屏模式下 Widget 占据整个屏幕区域且不显示窗口装饰 (譬如:标题栏)。

默认情况下此特性为 false .

访问函数:

bool isFullScreen () const

另请参阅 windowState (), minimized ,和 maximized .

geometry : QRect

此特性保持 Widget 相对于其父级的几何体,但不包括窗口框架

当改变几何体时,Widget (若可见) 接收移动事件 ( moveEvent ()) 和/或重置尺寸事件 ( resizeEvent ()) 立即。若小部件目前不可见,保证收到适当事件在展示它之前。

调节其组件大小,若它超出范围定义通过 minimumSize () 和 maximumSize ().

警告: 调用 setGeometry() 在 resizeEvent () 或 moveEvent () 可能导致无限递归。

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

默认情况下,此特性包含从属用户平台和屏幕几何体的值。

访问函数:

const QRect & geometry () const
void setGeometry (int x , int y , int w , int h )
void setGeometry (const QRect &)

另请参阅 frameGeometry (), rect (), move (), resize (), moveEvent (), resizeEvent (), minimumSize (),和 maximumSize ().

[read-only] height : const int

此特性排除任何窗口框架保持 Widget 高度

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

默认情况下,此特性包含的值从属用户平台和 屏幕几何体 .

访问函数:

int height () const

另请参阅 geometry , width ,和 size .

inputMethodHints : Qt::InputMethodHints

Widget 有什么输入法特定提示。

这仅与输入 Widget 相关。输入法使用它来检索输入法应该如何操作的有关提示。例如,若 Qt::ImhFormattedNumbersOnly 标志被设置,输入法可以改变其视觉组件以反射只可以录入数字。

警告: 一些 Widget 要求某些标志才如打算般工作。要设置标志,执行 w->setInputMethodHints(w->inputMethodHints()|f) 而不是 w->setInputMethodHints(f) .

注意: 标志只是提示,因此,特定输入法实现可自由忽略它们。若希望确保录入某种类型的字符,还应该设置 QValidator 在 Widget。

默认值为 Qt::ImhNone .

访问函数:

Qt::InputMethodHints inputMethodHints () const
void setInputMethodHints (Qt::InputMethodHints hints )

另请参阅 inputMethodQuery ().

[read-only] isActiveWindow : const bool

此特性保持此 Widget 的窗口,是否为活动窗口

活动窗口是包含拥有键盘聚焦的 Widget 的窗口 (窗口可能仍然拥有聚焦,若它没有 Widget 或其 Widget 不接受键盘聚焦)。

当弹出窗口可见时,此特性为 true 对于活动窗口 and 对于弹出窗口。

默认情况下此特性为 false .

访问函数:

bool isActiveWindow () const

另请参阅 activateWindow () 和 QApplication::activeWindow ().

layoutDirection : Qt::LayoutDirection

此特性保持用于该 Widget 的布局方向

默认情况下,此特性被设为 Qt::LeftToRight .

When the layout direction is set on a widget, it will propagate to the widget's children, but not to a child that is a window and not to a child for which setLayoutDirection() has been explicitly called. Also, child widgets added after setLayoutDirection() has been called for the parent do not inherit the parent's layout direction.

从 Qt 4.7 起,此方法不再影响文本布局方向。

访问函数:

Qt::LayoutDirection layoutDirection () const
void setLayoutDirection (Qt::LayoutDirection direction )
void unsetLayoutDirection ()

另请参阅 QApplication::layoutDirection .

locale : QLocale

此特性保持 Widget 的区域设置

只要没有设置特殊区域设置,这要么是父级的区域设置,要么 (若此 Widget 是顶层小部件) 是默认区域设置。

若 Widget 显示日期或数字,则应使用小部件区域设置对其进行格式化。

访问函数:

QLocale locale () const
void setLocale (const QLocale & locale )
void unsetLocale ()

另请参阅 QLocale and QLocale::setDefault ().

[read-only] maximized : const bool

此特性保持此 Widget 是否为最大化

此特性仅相关窗口。

注意: 由于某些窗口系统的局限性,这并不总是报告期望结果 (如:若 X11 用户凭借窗口管理器最大化窗口,Qt 将没有办法区分这与任何其它重置大小)。随着窗口管理器协议的进化,期望这有改进。

默认情况下此特性为 false .

访问函数:

bool isMaximized () const

另请参阅 windowState (), showMaximized (), visible , show (), hide (), showNormal (),和 minimized .

maximumHeight : int

此特性保持 Widget 的最大高度 (以像素为单位)

此特性对应高度的保持通过 maximumSize 特性。

默认情况下,此特性包含 16777215 值。

注意: 定义的 QWIDGETSIZE_MAX 宏限制 Widget 最大尺寸。

访问函数:

int maximumHeight () const
void setMaximumHeight (int maxh )

另请参阅 maximumSize and maximumWidth .

maximumSize : QSize

此特性保持 Widget 的最大尺寸 (以像素为单位)

Widget 尺寸无法被重置为比最大小部件尺寸更大的尺寸。

默认情况下,此特性包含宽度和高度值为 16777215 的尺寸。

注意: 定义的 QWIDGETSIZE_MAX 宏限制 Widget 最大尺寸。

访问函数:

QSize maximumSize () const
void setMaximumSize (const QSize &)
void setMaximumSize (int maxw , int maxh )

另请参阅 maximumWidth , maximumHeight , minimumSize ,和 sizeIncrement .

maximumWidth : int

此特性保持 Widget 最大宽度 (以像素为单位)

此特性对应的宽度保持通过 maximumSize 特性。

默认情况下,此特性包含 16777215 值。

注意: 定义的 QWIDGETSIZE_MAX 宏限制 Widget 最大尺寸。

访问函数:

int maximumWidth () const
void setMaximumWidth (int maxw )

另请参阅 maximumSize and maximumHeight .

[read-only] minimized : const bool

此特性保持此 Widget 是否最小化 (图标化)

此特性仅相关窗口。

默认情况下此特性为 false .

访问函数:

bool isMinimized () const

另请参阅 showMinimized (), visible , show (), hide (), showNormal (),和 maximized .

minimumHeight : int

此特性保持 Widget 最小高度 (以像素为单位)

此特性对应高度的保持通过 minimumSize 特性。

默认情况下,此特性拥有 0 值。

访问函数:

int minimumHeight () const
void setMinimumHeight (int minh )

另请参阅 minimumSize and minimumWidth .

minimumSize : QSize

此特性保持 Widget 的最小尺寸

Widget 无法被重置为比最小小部件尺寸更小的尺寸。Widget 的尺寸被强制为最小尺寸若当前尺寸较小。

由此函数设置的最小尺寸将覆盖的最小尺寸定义通过 QLayout 。要取消最小尺寸设置,使用值 QSize(0, 0) .

默认情况下,此特性包含 0 大小宽度和高度。

访问函数:

QSize minimumSize () const
void setMinimumSize (const QSize &)
void setMinimumSize (int minw , int minh )

另请参阅 minimumWidth , minimumHeight , maximumSize ,和 sizeIncrement .

[read-only] minimumSizeHint : const QSize

此特性保持 Widget 的最小推荐尺寸

若此特性的值是无效尺寸,不推荐使用最小尺寸。

The default implementation of minimumSizeHint() returns an invalid size if there is no layout for this widget, and returns the layout's minimum size otherwise. Most built-in widgets reimplement minimumSizeHint().

QLayout will never resize a widget to a size smaller than the minimum size hint unless minimumSize () is set or the size policy is set to QSizePolicy::Ignore. If minimumSize () is set, the minimum size hint will be ignored.

访问函数:

virtual QSize minimumSizeHint () const

另请参阅 QSize::isValid (), resize (), setMinimumSize (),和 sizePolicy ().

minimumWidth : int

此特性保持 Widget 的最小宽度 (以像素为单位)

此特性对应的宽度保持通过 minimumSize 特性。

默认情况下,此特性拥有 0 值。

访问函数:

int minimumWidth () const
void setMinimumWidth (int minw )

另请参阅 minimumSize and minimumHeight .

此特性保持 Widget 是否为模态小部件

此特性仅对窗口有意义。模态 Widget 阻止所有其它窗口中的小部件获得任何输入。

默认情况下此特性为 false .

访问函数:

bool isModal () const

另请参阅 isWindow (), windowModality ,和 QDialog .

mouseTracking : bool

此特性保持是否为 Widget 启用鼠标跟踪

若鼠标跟踪被禁用 (默认),当至少按下一鼠标按钮移动鼠标时,Widget 才接收鼠标移动事件。

若鼠标跟踪被启用,Widget 接收鼠标移动事件,即使没有按钮被按下。

访问函数:

bool hasMouseTracking () const
void setMouseTracking (bool enable )

另请参阅 mouseMoveEvent ().

[read-only] normalGeometry : const QRect

此特性保持 Widget 几何体,因为它会出现当展示作为正常 (非最大化或全屏) 顶层小部件时

对于子级 Widget,此特性始终保持空矩形。

默认情况下,此特性包含空矩形。

访问函数:

QRect normalGeometry () const

另请参阅 QWidget::windowState () 和 QWidget::geometry .

palette : QPalette

此特性保持 Widget 的调色板

This property describes the widget's palette. The palette is used by the widget's style when rendering standard components, and is available as a means to ensure that custom widgets can maintain consistency with the native platform's look and feel. It's common that different platforms, or different styles, have different palettes.

When you assign a new palette to a widget, the color roles from this palette are combined with the widget's default palette to form the widget's final palette. The palette entry for the widget's background role is used to fill the widget's background (see QWidget::autoFillBackground ), and the foreground role initializes QPainter 's pen.

默认从属系统环境。 QApplication maintains a system/theme palette which serves as a default for all widgets. There may also be special palette defaults for certain types of widgets (e.g., on Windows Vista, all classes that derive from QMenuBar have a special default palette). You can also define default palettes for widgets yourself by passing a custom palette and the name of a widget to QApplication::setPalette (). Finally, the style always has the option of polishing the palette as it's assigned (see QStyle::polish ()).

QWidget propagates explicit palette roles from parent to child. If you assign a brush or color to a specific role on a palette and assign that palette to a widget, that role will propagate to all the widget's children, overriding any system defaults for that role. Note that palettes by default don't propagate to windows (see isWindow ()) 除非 Qt::WA_WindowPropagation 属性被启用。

QWidget 's palette propagation is similar to its font propagation.

The current style, which is used to render the content of all standard Qt widgets, is free to choose colors and brushes from the widget palette, or in some cases, to ignore the palette (partially, or completely). In particular, certain styles like GTK style, Mac style, and Windows Vista style, depend on third party APIs to render the content of widgets, and these styles typically do not follow the palette. Because of this, assigning roles to a widget's palette is not guaranteed to change the appearance of the widget. Instead, you may choose to apply a styleSheet .

警告: 不要将使用此函数结合 Qt 样式表 . When using style sheets, the palette of a widget can be customized using the "color", "background-color", "selection-color", "selection-background-color" and "alternate-background-color".

访问函数:

const QPalette & palette () const
void setPalette (const QPalette &)

另请参阅 QGuiApplication::palette (), QWidget::font (),和 Qt 样式表 .

pos : QPoint

此特性保持 Widget 在其父级小部件中的位置

若 Widget 是窗口,则位置是小部件在桌面上的位置,包括其框架。

当改变位置时,Widget (若可见) 接收移动事件 ( moveEvent ()) 立即。若小部件目前不可见,保证收到事件在展示它之前。

默认情况下,此特性包含原点引用位置。

警告: 调用 move() 或 setGeometry () 在 moveEvent () 可能导致无限递归。

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

访问函数:

QPoint pos () const
void move (int x , int y )
void move (const QPoint &)

另请参阅 frameGeometry , size , x (),和 y ().

[read-only] rect : const QRect

此特性保持 Widget 的内部几何体,排除任何窗口框架

矩形特性等于 QRect (0, 0, width (), height ()).

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

默认情况下,此特性包含从属用户平台和屏幕几何体的值。

访问函数:

QRect rect () const

另请参阅 size .

size : QSize

此特性保持 Widget 的大小,排除任何窗口框架

若在重置尺寸时可见,Widget 接收重置尺寸事件 ( resizeEvent ()) 立即。若小部件目前不可见,保证收到事件在展示它之前。

调节其大小,若它超出范围定义通过 minimumSize () 和 maximumSize ().

默认情况下,此特性包含从属用户平台和屏幕几何体的值。

警告: 调用 resize() 或 setGeometry () 在 resizeEvent () 可能导致无限递归。

注意: 将尺寸设为 QSize(0, 0) 将导致 Widget 不出现在屏幕上。这也适用于窗口。

访问函数:

QSize size () const
void resize (int w , int h )
void resize (const QSize &)

另请参阅 pos , geometry , minimumSize , maximumSize , resizeEvent (),和 adjustSize ().

[read-only] sizeHint : const QSize

此特性保持 Widget 的推荐尺寸

若此特性的值是无效尺寸,则没有尺寸被推荐。

默认 sizeHint() 实现返回无效尺寸,若此 Widget 没有布局;否则,返回布局的首选尺寸。

访问函数:

virtual QSize sizeHint () const

另请参阅 QSize::isValid (), minimumSizeHint (), sizePolicy (), setMinimumSize (),和 updateGeometry ().

sizeIncrement : QSize

此特性保持 Widget 的大小增量

当用户重置窗口大小时,大小将按 sizeIncrement() 步幅移动。 width () 像素水平和 sizeIncrement。 height () 像素垂直,采用 baseSize () 作为基础。首选 Widget 大小是非负整数 i and j :

width = baseSize().width() + i * sizeIncrement().width();
height = baseSize().height() + j * sizeIncrement().height();
							

注意,虽然可以为所有 Widget 设置大小增量,但它仅影响窗口。

默认情况下,此特性包含 0 大小宽度和高度。

警告: 大小增量在 Windows 不起作用,而在 X11 可能会被窗口管理器忽视。

访问函数:

QSize sizeIncrement () const
void setSizeIncrement (const QSize &)
void setSizeIncrement (int w , int h )

另请参阅 size , minimumSize ,和 maximumSize .

sizePolicy : QSizePolicy

此特性保持 Widget 的默认布局行为

若有 QLayout 管理此 Widget 的子级,将使用由该布局指定的大小策略。若没有这种 QLayout ,使用此函数的结果。

The default policy is Preferred/Preferred, which means that the widget can be freely resized, but prefers to be the size sizeHint () returns. Button-like widgets set the size policy to specify that they may stretch horizontally, but are fixed vertically. The same applies to lineedit controls (such as QLineEdit , QSpinBox or an editable QComboBox ) and other horizontally orientated widgets (such as QProgressBar ). QToolButton 's are normally square, so they allow growth in both directions. Widgets that support different directions (such as QSlider , QScrollBar or QHeader) specify stretching in the respective direction only. Widgets that can provide scroll bars (usually subclasses of QScrollArea ) tend to specify that they can use additional space, and that they can make do with less than sizeHint ().

访问函数:

QSizePolicy sizePolicy () const
void setSizePolicy (QSizePolicy)
void setSizePolicy (QSizePolicy::Policy horizontal , QSizePolicy::Policy vertical )

另请参阅 sizeHint (), QLayout , QSizePolicy ,和 updateGeometry ().

statusTip : QString

此特性保持 Widget 的状态提示

默认情况下,此特性包含空字符串。

访问函数:

QString statusTip () const
void setStatusTip (const QString &)

另请参阅 toolTip and whatsThis .

styleSheet : QString

此特性保持 Widget 的样式表

样式表包含定制 Widget 样式的的正文描述,作为描述在 Qt 样式表 文档。

从 Qt 4.5 起,Qt 样式表完全支持 macOS。

警告: Qt 样式表目前不支持自定义 QStyle 子类。计划在某些未来发行中解决这。

访问函数:

QString styleSheet () const
void setStyleSheet (const QString & styleSheet )

另请参阅 setStyle (), QApplication::styleSheet ,和 Qt 样式表 .

[since 5.9] tabletTracking : bool

此特性保持是否为 Widget 启用数位板跟踪

If tablet tracking is disabled (the default), the widget only receives tablet move events when the stylus is in contact with the tablet, or at least one stylus button is pressed, while the stylus is being moved.

If tablet tracking is enabled, the widget receives tablet move events even while hovering in proximity. This is useful for monitoring position as well as the auxiliary properties such as rotation and tilt, and providing feedback in the UI.

该特性在 Qt 5.9 引入。

访问函数:

bool hasTabletTracking () const
void setTabletTracking (bool enable )

另请参阅 tabletEvent ().

toolTip : QString

此特性保持 Widget 的工具提示

Note that by default tooltips are only shown for widgets that are children of the active window. You can change this behavior by setting the attribute Qt::WA_AlwaysShowToolTips window , not on the widget with the tooltip.

若想要控制工具提示的行为,可以拦截 event () 函数和捕获 QEvent::ToolTip event (e.g., if you want to customize the area for which the tooltip should be shown).

默认情况下,此特性包含空字符串。

访问函数:

QString toolTip () const
void setToolTip (const QString &)

另请参阅 QToolTip , statusTip ,和 whatsThis .

[since 5.2] toolTipDuration : int

此特性保持 Widget 的工具提示持续时间

Specifies how long time the tooltip will be displayed, in milliseconds. If the value is -1 (default) the duration is calculated depending on the length of the tooltip.

该特性在 Qt 5.2 引入。

访问函数:

int toolTipDuration () const
void setToolTipDuration (int msec )

另请参阅 toolTip .

updatesEnabled : bool

此特性保持是否启用更新

启用更新的 Widget 接收描绘事件并拥有系统背景;禁用的 Widget 不会。这还隐含调用 update () 和 repaint () 无效,若更新被禁用。

默认情况下此特性为 true .

setUpdatesEnabled()通常用于在短时间内禁用更新 (例如:避免在较大变化期间屏幕闪烁)。在 Qt,Widget 通常不生成屏幕闪烁,但在 X11,服务器可能擦除屏幕区域当 Widget 被隐藏时,在以其它 Widget 替换它们之前。禁用更新可解决此。

范例:

setUpdatesEnabled(false);
bigVisualChanges();
setUpdatesEnabled(true);
							

禁用 Widget 隐式禁用其所有子级。启用 Widget 启用所有子级小部件 except 顶层 Widget 或已被明确禁用的那些。重新启用更新隐式调用 update () 在 Widget。

访问函数:

bool updatesEnabled () const
void setUpdatesEnabled (bool enable )

另请参阅 paintEvent ().

visible : bool

此特性保持 Widget 是否可见

调用 setVisible(true) 或 show () 将 Widget 设为可见状态,若窗口前的所有父级小部件可见。若祖先不可见,Widget 不会变为可见,直到展示其所有祖先为止。若其大小或位置有改变,Qt 保证 Widget 在展示之前获得移动和重置尺寸事件。若 Widget 尚未重置尺寸,Qt 将小部件大小调节到有用默认值使用 adjustSize ().

调用 setVisible(false) 或 hide () 明确隐藏 Widget。被明确隐藏的 Widget 从不会变为可见,即使其所有祖先变为可见,除非展示它。

Widget 接收展示和隐藏事件,当其可见性状态改变时。在隐藏和展示事件之间,无需浪费 CPU 周期准备或向用户显示信息。例如:视频应用程序可能只需停止生成新帧。

恰巧被屏幕上其它窗口遮盖的 Widget 被认为是可见的。同样适用于图标化窗口和存在于另一虚拟桌面的窗口 (在支持此概念的平台)。Widget 接收自发展示和隐藏事件,当窗口系统改变其映射状态时,如:自发隐藏事件当用户最小化窗口时,和自发展示事件当窗口再次还原时。

几乎从不需要重新实现 setVisible() 函数。若需要在 Widget 被展示之前更改某些设置,请使用 showEvent () 代替。若需要做一些延迟初始化,请使用 Polish (抛光) 事件,被交付给 event () 函数。

访问函数:

bool isVisible () const
virtual void setVisible (bool visible )

另请参阅 show (), hide (), isHidden (), isVisibleTo (), isMinimized (), showEvent (),和 hideEvent ().

whatsThis : QString

此特性保持 Widget 的 What's This 帮助文本。

默认情况下,此特性包含空字符串。

访问函数:

QString whatsThis () const
void setWhatsThis (const QString &)

另请参阅 QWhatsThis , QWidget::toolTip ,和 QWidget::statusTip .

[read-only] width : const int

此特性保持 Widget 的宽度 (排除任何窗口框架)

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

注意: Do not use this function to find the width of a screen on a multi-screen desktop. See QScreen 了解细节。

默认情况下,此特性包含从属用户平台和屏幕几何体的值。

访问函数:

int width () const

另请参阅 geometry , height ,和 size .

windowFilePath : QString

此特性保持与 Widget 关联的文件路径

此特性仅对窗口有意义。它把文件路径与窗口关联。若设置文件路径,但未设置窗口标题,则 Qt 会把窗口标题设为指定路径的文件名,获得使用 QFileInfo::fileName ().

若在任何时候设置了窗口标题,则窗口标题优先,且将被展示而非文件路径字符串。

此外,在 macOS 这还有额外好处,设置 代理图标 为窗口,假定文件路径存在。

此特性包含空字符串,若未设置文件路径。

默认情况下,此特性包含空字符串。

访问函数:

QString windowFilePath () const
void setWindowFilePath (const QString & filePath )

另请参阅 windowTitle and windowIcon .

windowFlags : Qt::WindowFlags

窗口标志是组合,构成由类型 (如 Qt::Dialog ) 和零个或多个窗口系统提示 (如 Qt::FramelessWindowHint ).

若 Widget 有类型 Qt::Widget or Qt::SubWindow 并变为窗口 ( Qt::Window , Qt::Dialog ,等),它被放在桌面 (0, 0) 位置。若 Widget 是窗口并变成 Qt::Widget or Qt::SubWindow ,它被放在相对于其父级 Widget 的 (0, 0) 位置。

注意: 此函数调用 setParent () 当改变窗口标志时,导致 Widget 被隐藏。必须调用 show () 以使 Widget 再次变为可见。

访问函数:

Qt::WindowFlags windowFlags () const
void setWindowFlags (Qt::WindowFlags type )

另请参阅 windowType (), setWindowFlag (),和 窗口标志范例 .

windowIcon : QIcon

此特性保持 Widget 图标

This property only makes sense for windows. If no icon has been set, windowIcon() returns the application icon ( QApplication::windowIcon ()).

注意: On macOS, window icons represent the active document, and will not be displayed unless a file path has also been set using setWindowFilePath .

访问函数:

QIcon windowIcon () const
void setWindowIcon (const QIcon & icon )

通知程序信号:

void windowIconChanged (const QIcon & icon )

另请参阅 windowTitle and setWindowFilePath .

windowModality : Qt::WindowModality

This property holds which windows are blocked by the modal widget

This property only makes sense for windows. A modal widget prevents widgets in other windows from getting input. The value of this property controls which windows are blocked when the widget is visible. Changing this property while the window is visible has no effect; you must hide () the widget first, then show () it again.

默认情况下此特性为 Qt::NonModal .

访问函数:

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

另请参阅 isWindow (), QWidget::modal ,和 QDialog .

windowModified : bool

此特性保持在窗口中展示的文档是否有未保存的更改

修改窗口是其内容有改变但尚未保存到磁盘的窗口。此标志对于各种平台有不同效果。在 macOS,关闭按钮将拥有修改外观;在其它平台,窗口标题将拥有 * 星号。

窗口标题必须包含 [*] 占位符,指示 * 应用出现在何处。通常,它应出现在文件名后右侧 (如 document1.txt[*] - Text Editor)。若尚未修改窗口,会简单移除占位符。

注意,若将 Widget 设为被修改,则其所有祖先也被设为被修改。不管怎样,若调用 setWindowModified(false) 在 Widget,这不会传播给其父级,因为父级的其它子级可能已被修改。

访问函数:

bool isWindowModified () const
void setWindowModified (bool)

另请参阅 windowTitle , Qt Widgets - 应用程序范例 , SDI 范例 ,和 MDI 范例 .

windowOpacity : double

此特性保持窗口的不透明度级别。

不透明度的有效范围是从 1.0 (完全不透明) 到 0.0 (完全透明)。

默认情况下,此特性的值为 1.0。

此特征可用于支持复合扩展的嵌入式 Linux、macOS、Windows 和 X11 平台。

注意: 在 X11,需要运行复合管理器,且 X11 的特定 _NET_WM_WINDOW_OPACITY 原子需要所用窗口管理器的支持。

警告: Changing this property from opaque to transparent might issue a paint event that needs to be processed before the window is displayed correctly. This affects mainly the use of QScreen::grabWindow (). Also note that semi-transparent windows update and resize significantly slower than opaque windows.

访问函数:

qreal windowOpacity () const
void setWindowOpacity (qreal level )

另请参阅 setMask ().

windowTitle : QString

此特性保持窗口标题 (Caption 题注)

此特性仅对顶层 Widget (譬如:窗口和对话框) 有意义。若未设置 Caption (题注),则标题基于 windowFilePath 。若都未设置,则标题为空字符串。

若使用 windowModified 机制,窗口标题必须包含 [*] 占位符,指示 * 应出现在何处。通常,它应出现在文件名后右侧 (如 document1.txt[*] - Text Editor)。若 windowModified 特性为 false (默认),简单移除占位符。

在某些桌面平台 (包括 Windows 和 Unix),应用程序名称 (来自 QGuiApplication::applicationDisplayName ) 会被添加到窗口标题末尾,若有设置的话。这是由 QPA 插件来完成的,因此会向用户展示,但不属于 windowTitle 字符串。

访问函数:

QString windowTitle () const
void setWindowTitle (const QString &)

通知程序信号:

void windowTitleChanged (const QString & title )

另请参阅 windowIcon , windowModified ,和 windowFilePath .

[read-only] x : const int

此特性保持 Widget 相对于其父级 (包括任何窗框) 的 X 坐标

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

默认情况下,此特性拥有 0 值。

访问函数:

int x () const

另请参阅 frameGeometry , y ,和 pos .

[read-only] y : const int

此特性保持 Widget 相对于其父级和包括任何窗框的 y 坐标

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

默认情况下,此特性拥有 0 值。

访问函数:

int y () const

另请参阅 frameGeometry , x ,和 pos .

成员函数文档编制

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

构造子级 Widget 为 parent ,采用 Widget 设置标志 f .

parent is nullptr ,新的 Widget 变为窗口。若 parent 是另一 Widget,此小部件变成子级窗口在 parent 。新的小部件被删除当其 parent 被删除。

Widget 标志自变量 f ,通常为 0,但可以将它设为定制窗口框架 (即 parent 必须是 nullptr )。要定制框架,使用组成值来自按位 OR 的任何 窗口标志 .

若将子级 Widget 添加到已经可见的小部件,必须明确展示子级以使其可见。

Note that the X11 version of Qt may not be able to deliver all combinations of style flags on all systems. This is because on X11, Qt can only ask the window manager, and the window manager can override the application's settings. On Windows, Qt can set whatever flags you want.

另请参阅 windowFlags .

[slot] bool QWidget:: close ()

关闭此 Widget。返回 true 若 Widget 被关闭;否则返回 false .

首先,它向 Widget 发送 QCloseEvent 。小部件 hidden 若它 accepts 关闭事件。若它 ignores 事件,什么都不发生。默认实现的 QWidget::closeEvent () 接受关闭事件。

若 Widget 拥有 Qt::WA_DeleteOnClose 标志,小部件还被删除。关闭事件会被交付给 Widget 无论小部件是否可见。

QApplication::lastWindowClosed () 信号被发射当最后可见首要窗口 (即:窗口没有父级) 具有 Qt::WA_QuitOnClose 属性设置被关闭。默认情况下,除瞬时窗口 (譬如:闪屏、工具窗口及弹出菜单) 外,所有 Widget 都有设置此属性。

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

此信号被发射当 Widget 的 contextMenuPolicy is Qt::CustomContextMenu ,且用户已请求 Widget 的上下文菜单。位置 pos 是 Widget 接收上下文菜单事件的位置。通常,这在 Widget 坐标中。此规则的例外是 QAbstractScrollArea 且其子类把上下文菜单事件映射到坐标为 viewport() .

另请参阅 mapToGlobal (), QMenu ,和 contextMenuPolicy .

[slot] void QWidget:: hide ()

隐藏 Widget。此函数相当于 setVisible (false).

注意: 若正操控 QDialog 或其子类和援引 show () 函数在此函数之后,对话框将显示在其原始位置。

另请参阅 hideEvent (), isHidden (), show (), setVisible (), isVisible (),和 close ().

[slot] void QWidget:: lower ()

把 Widget 降低到父级 Widget 的堆栈底部。

在此调用之后,Widget 将在视觉上位于 (且因此被遮盖由) 任何重叠同级小部件后面。

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

[slot] void QWidget:: raise ()

把此 Widget 提升到父级 Widget 的堆栈顶部。

在此调用之后,Widget 会在任何重叠同级 Widget 之前可见。

注意: 当使用 activateWindow (),可以调用此函数以确保窗口堆叠在顶部。

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

[slot] void QWidget:: repaint ()

直接重新绘制 Widget 通过调用 paintEvent () 立即,除非更新被禁用或 Widget 被隐藏。

我们建议仅在需要立即重新绘制 (如:在动画期间) 时才使用 repaint()。在几乎所有情况下 update () 更好,因为它准许 Qt 优化速度并最小化闪烁。

警告: 若在可以调用本身的函数中调用 repaint() 从 paintEvent (),可能获得无限递归。 update () 函数从不导致递归。

另请参阅 update (), paintEvent (),和 setUpdatesEnabled ().

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

禁用 Widget 输入事件若 disable 为 true;否则启用输入事件。

enabled 文档编制,了解更多信息。

另请参阅 isEnabledTo (), QKeyEvent , QMouseEvent ,和 changeEvent ().

[slot] void QWidget:: setFocus ()

这是重载函数。

把键盘输入聚焦给予此 Widget (或其聚焦代理),若此 Widget 或其父级之一是 活动窗口 .

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

方便函数,相当于 setVisible (! hidden ).

另请参阅 isHidden ().

[slot] void QWidget:: show ()

展示 Widget 及其子级 Widget。

这相当于调用 showFullScreen (), showMaximized (),或 setVisible (true),取决于平台窗口标记的默认行为。

另请参阅 raise (), showEvent (), hide (), setVisible (), showMinimized (), showMaximized (), showNormal (), isVisible (),和 windowFlags ().

[slot] void QWidget:: showFullScreen ()

以全屏模式展示 Widget。

调用此函数仅影响 windows .

要从全屏模式返回,调用 showNormal ().

Full-screen mode works fine under Windows, but has certain problems under X. These problems are due to limitations of the ICCCM protocol that specifies the communication between X11 clients and the window manager. ICCCM simply does not understand the concept of non-decorated full-screen windows. Therefore, the best we can do is to request a borderless window and place and resize it to fill the entire screen. Depending on the window manager, this may or may not work. The borderless window is requested using MOTIF hints, which are at least partially supported by virtually all modern window managers.

An alternative would be to bypass the window manager entirely and create a window with the Qt::X11BypassWindowManagerHint flag. This has other severe problems though, like totally broken keyboard focus and very strange effects on desktop changes or when the user raises other windows.

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

另请参阅 showNormal (), showMaximized (), show (), hide (),和 isVisible ().

[slot] void QWidget:: showMaximized ()

最大化展示 Widget。

调用此函数仅影响 windows .

在 X11,此函数可能不正确工作于某些窗口管理器。见 窗口几何体 文档编制了解解释。

另请参阅 setWindowState (), showNormal (), showMinimized (), show (), hide (),和 isVisible ().

[slot] void QWidget:: showMinimized ()

以图标形式最小化展示 Widget。

调用此函数仅影响 windows .

另请参阅 showNormal (), showMaximized (), show (), hide (), isVisible (),和 isMinimized ().

[slot] void QWidget:: showNormal ()

还原 Widget 在它被最大化或最小化之后。

调用此函数仅影响 windows .

另请参阅 setWindowState (), showMinimized (), showMaximized (), show (), hide (),和 isVisible ().

[slot] void QWidget:: update ()

更新 Widget 除非更新被禁用或 Widget 被隐藏。

此函数不会导致立即重新绘制;相反,它在 Qt 返回到主事件循环时调度描绘处理事件。这准许 Qt 去优化以提高速度并减少闪烁相比调用 repaint () 做。

多次调用 update() 通常仅仅导致一次 paintEvent () 调用。

Qt 通常先擦除 Widget 区域再 paintEvent () 调用。若 Qt::WA_OpaquePaintEvent Widget 属性被设置,Widget 负责采用不透明颜色描绘其所有像素。

另请参阅 repaint (), paintEvent (), setUpdatesEnabled (),和 指针式时钟范例 .

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

Updates the widget's micro focus and informs input methods that the state specified by query 已改变。

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

此信号被发射当窗口图标已改变,采用新的 icon 作为自变量。

注意: 通知程序信号为特性 windowIcon .

该函数在 Qt 5.2 引入。

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

此信号被发射当窗口标题已改变,采用新的 title 作为自变量。

注意: 通知程序信号为特性 windowTitle .

该函数在 Qt 5.2 引入。

[virtual] QWidget:: ~QWidget ()

销毁 Widget。

此 Widget 的所有子级被首先删除。退出应用程序若此 Widget 是主小部件。

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

此事件处理程序被调用采用给定 event 每当 Widget 的操作发生更改时。

另请参阅 addAction (), insertAction (), removeAction (), actions (),和 QActionEvent .

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

返回此 Widget 的动作列表 (可能为空)。

另请参阅 contextMenuPolicy , insertAction (),和 removeAction ().

void QWidget:: activateWindow ()

把包含此 Widget 的顶层 Widget,设为活动窗口。

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

此函数履行如在顶层窗口的标题栏上,点击鼠标的相同操作。在 X11,结果取决于窗口管理器。若想要确保窗口堆叠在顶部,同样,还应调用 raise ()。注意:窗口必须可见,否则 activateWindow() 无效。

在 Windows,若在应用程序目前不是活动窗口时调用这,则不会使其成为活动窗口。它会改变任务栏条目的颜色,以指示窗口在某些方面有变化。这是因为 Microsoft 不允许应用程序,去中断用户在另一应用程序中目前正做的。

另请参阅 isActiveWindow (), window (),和 show ().

void QWidget:: addAction ( QAction * action )

追加动作 action 到此 Widget 的动作列表。

所有 QWidget 都有列表,针对 QAction ,无论如何,可以按多种不同方式图形表示它们。默认使用 QAction 列表 (作为返回通过 actions ()) 创建上下文 QMenu .

QWidget 只应每动作有一个,且已添加动作不会导致同一动作在 Widget 中出现两次。

所有权对于 action 不会传输给此 QWidget .

另请参阅 removeAction (), insertAction (), actions (),和 QMenu .

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

追加动作 actions 到此 Widget 的动作列表。

另请参阅 removeAction (), QMenu ,和 addAction ().

void QWidget:: adjustSize ()

调节 Widget 大小以拟合其内容。

此函数使用 sizeHint () if it is valid, i.e., the size hint's width and height are >= 0. Otherwise, it sets the size to the children rectangle that covers all child widgets (the union of all child widget rectangles).

For windows, the screen size is also taken into account. If the sizeHint () is less than (200, 100) and the size policy is expanding , the window will be at least (200, 100). The maximum size of a window is 2/3 of the screen's width and height.

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

QPalette::ColorRole QWidget:: backgroundRole () const

返回 Widget 的背景角色。

背景角色定义笔刷来自 Widget 的 palette 用于渲染背景。

If no explicit background role is set, the widget inherts its parent widget's background role.

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

[since 5.0] QBackingStore *QWidget:: backingStore () const

返回 QBackingStore this widget will be drawn into.

该函数在 Qt 5.0 引入。

[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

返回可见子级 Widget 在位置 ( x , y ) in the widget's coordinate system. If there is no visible child widget at the specified position, the function returns nullptr .

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

这是重载函数。

返回可见子级 Widget 在点 p 在小部件自己的坐标系统中。

void QWidget:: clearFocus ()

从 Widget 获取键盘输入聚焦。

若 Widget 有活动聚焦, 聚焦出事件 被发送给此 Widget 以告诉它已丢失聚焦。

此 Widget 必须启用聚焦设置以获取键盘输入聚焦,即:它必须调用 setFocusPolicy ().

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

void QWidget:: clearMask ()

移除任何遮罩设置通过 setMask ().

另请参阅 setMask ().

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

此事件处理程序被调用采用给定 event when Qt receives a window close request for a top-level widget from the window system.

By default, the event is accepted and the widget is closed. You can reimplement this function to change the way the widget responds to window close requests. For example, you can prevent the window from closing by calling ignore() on all events.

Main window applications typically use reimplementations of this function to check whether the user's work has been saved and ask for permission before closing. For example, the Qt Widgets - 应用程序范例 uses a helper function to determine whether or not to close the window:

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

另请参阅 event (), hide (), close (), QCloseEvent ,和 Qt Widgets - 应用程序范例 .

QMargins QWidget:: contentsMargins () const

contentsMargins 函数返回 Widget 的内容边距。

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

QRect QWidget:: contentsRect () const

返回 Widget 边距内的区域。

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

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

此事件处理程序,用于事件 event ,可以在子类中被重实现以接收 Widget 上下文菜单事件。

处理程序被调用,当 Widget 的 contextMenuPolicy is Qt::DefaultContextMenu .

默认实现忽略上下文事件。见 QContextMenuEvent 文档编制了解更多细节。

另请参阅 event (), QContextMenuEvent ,和 customContextMenuRequested ().

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

创建新 Widget 窗口。

参数 window , initializeWindow ,和 destroyOldWindow 被忽略,在 Qt 5。请使用 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 ().

The window container is attached as a native child window to the toplevel window it is a child of. When a window container is used as a child of a QAbstractScrollArea or QMdiArea , it will create a native window for every widget in its parent chain to allow for proper stacking and clipping in this use case. Creating a native window for the window container also allows for proper stacking and clipping. This must be done before showing the window container. Applications with many native child windows may suffer from performance issues.

窗口容器有许多已知局限性:

  • Stacking order; The embedded window will stack on top of the widget hierarchy as an opaque box. The stacking order of multiple overlapping window container instances is undefined.
  • 渲染集成;窗口容器无法互操作与 QGraphicsProxyWidget , QWidget::render () 或类似功能。
  • Focus Handling; It is possible to let the window container instance have any focus policy and it will delegate focus to the window via a call to QWindow::requestActivate (). However, returning to the normal focus chain from the QWindow instance will be up to the QWindow instance implementation itself. For instance, when entering a Qt Quick based window with tab focus, it is quite likely that further tab presses will only cycle inside the QML application. Also, whether QWindow::requestActivate () actually gives the window focus, is platform dependent.
  • 使用多个窗口容器实例在 QWidget 基应用程序会大大损害应用程序的整体性能。

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

释放窗口系统资源。销毁 Widget 窗口,若 destroyWindow 为 true。

destroy() 会为所有子级 Widget 递归调用本身,传递 destroySubWindows destroyWindow 参数。要更好地控制 Subwidget 的销毁,请先选择性地销毁 Subwidget。

此函数通常被调用从 QWidget 析构函数。

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

此事件处理程序被调用当拖拽正在进行中且鼠标进入此 Widget 时。事件被传入 event 参数。

若事件被忽略,Widget 不会接收任何 拖曳移动事件 .

拖放文档编制 了解如何为应用程序提供拖放的概述。

另请参阅 QDrag and QDragEnterEvent .

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

此事件处理程序被调用当拖拽正在进行中且鼠标离开此 Widget 时。事件被传入 event 参数。

拖放文档编制 了解如何为应用程序提供拖放的概述。

另请参阅 QDrag and QDragLeaveEvent .

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

此事件处理程序被调用若拖拽正在进行中且发生以下任一条件:光标进入此 Widget、光标在此 Widget 内移动、若按下键盘修饰键当此 Widget 获得聚焦时。事件被传入 event 参数。

拖放文档编制 了解如何为应用程序提供拖放的概述。

另请参阅 QDrag and QDragMoveEvent .

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

此事件处理程序被调用当拖拽掉落在此 Widget 上时。事件被传入 event 参数。

拖放文档编制 了解如何为应用程序提供拖放的概述。

另请参阅 QDrag and QDropEvent .

WId QWidget:: effectiveWinId () const

返回 Widget 的有效窗口系统标识符,即:本机父级的窗口系统标识符。

若 Widget 是本机的,此函数返回本机小部件 ID。否则,返回首个本机父级 Widget (即:包含此 Widget 的顶层小部件) 的窗口 ID。

注意: 推荐不要存储此值,因为运行时它可能改变。

另请参阅 nativeParentWidget ().

void QWidget:: ensurePolished () const

确保 Widget 及其子级已被抛光,通过 QStyle (即:拥有适当字体和调色板)。

QWidget 调用此函数在完全构造之后,但在首次展示之前。可以调用此函数,若想要确保在执行操作之前抛光 Widget,如:可能需要正确字体大小在 Widget 的 sizeHint () 重实现。注意:此函数 is 调用自默认实现的 sizeHint ().

抛光对必须在调用所有构造函数 (来自基类及子类) 之后的最终初始化很有用。

若需要改变某些设置当抛光 Widget 时,重实现 event () 和处理 QEvent::Polish 事件类型。

注意: 函数被声明为 const 以便可以从其它 const 函数中调用它 (如 sizeHint ()).

另请参阅 event ().

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

此事件处理程序可以在子类中被重实现以接收 Widget 进入事件,当传入 event 参数。

事件被发送给 Widget,当鼠标光标进入 Widget 时。

另请参阅 leaveEvent (), mouseMoveEvent (),和 event ().

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

重实现: QObject::event (QEvent *e).

这是主事件处理程序;它处理事件 event 。可以在子类中重实现此函数,但推荐使用某一专用事件处理程序代替。

按键和释放事件的处理不同于其它事件。event() 检查 Tab 和 Shift+Tab 并试着适当移动聚焦。若没有能移动聚焦的 Widget (或按键不是 Tab 或 Shift+Tab),event() 调用 keyPressEvent ().

鼠标和数位板事件的处理还有点特殊:仅当 Widget enabled ,event() 会调用专用处理程序如 mousePressEvent ();否则它会丢弃事件。

此函数返回 true 若事件被识别,否则它返回 false 。若识别事件被接受 (见 QEvent::accepted ),任何进一步的处理 (譬如:把事件传播给父级 Widget) 都会停止。

另请参阅 closeEvent (), focusInEvent (), focusOutEvent (), enterEvent (), keyPressEvent (), keyReleaseEvent (), leaveEvent (), mouseDoubleClickEvent (), mouseMoveEvent (), mousePressEvent (), mouseReleaseEvent (), moveEvent (), paintEvent (), resizeEvent (), QObject::event (),和 QObject::timerEvent ().

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

返回指向 Widget 的指针,采用窗口标识符/句柄 id .

窗口标识符类型取决于底层窗口系统,见 qwindowdefs.h 实际定义。若没有带此标识符的 Widget, nullptr 被返回。

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

此事件处理程序可以在子类中被重实现,以接收 Widget 的键盘聚焦事件 (聚焦接收)。事件被传入 event 参数

Widget 通常必须 setFocusPolicy () 到某事除了 Qt::NoFocus 为接收聚焦事件 (注意:应用程序程序员可以调用 setFocus () 在任何 Widget,即使其通常不接受聚焦。)

默认实现更新 Widget (除了窗口未指定 focusPolicy ()).

另请参阅 focusOutEvent (), setFocusPolicy (), keyPressEvent (), keyReleaseEvent (), event (),和 QFocusEvent .

[protected] bool QWidget:: focusNextChild ()

查找新的 Widget 以给予键盘聚焦,如适合 Tab ,并返回 true 若能找到新的 Widget,或 false 若找不到。

另请参阅 focusPreviousChild ().

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

查找新的 Widget 以赋予键盘聚焦,如适合 Tab 和 Shift+Tab,并返回 true 若能找到新的 Widget,或 false 若找不到。

next 为 true,此函数向前搜索,若 next 为 False,向后搜索。

Sometimes, you will want to reimplement this function. For example, a web browser might reimplement it to move its "current active link" forward or backward, and call focusNextPrevChild() only when it reaches the last or first link on the "page".

Child widgets call focusNextPrevChild() on their parent widgets, but only the window that contains the child widgets decides where to redirect focus. By reimplementing this function for an object, you thus gain control of focus traversal for all child widgets.

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

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

此事件处理程序可以在子类中被重实现,以接收 Widget 的键盘聚焦事件 (聚焦丢失)。事件被传入 event 参数。

Widget 通常必须 setFocusPolicy () 到某事除了 Qt::NoFocus 为接收聚焦事件 (注意:应用程序程序员可以调用 setFocus () 在任何 Widget,即使其通常不接受聚焦。)

默认实现更新 Widget (除了窗口未指定 focusPolicy ()).

另请参阅 focusInEvent (), setFocusPolicy (), keyPressEvent (), keyReleaseEvent (), event (),和 QFocusEvent .

[protected] bool QWidget:: focusPreviousChild ()

查找新的 Widget 以给予键盘聚焦,如适合 Shift+Tab ,并返回 true 若能找到新的 Widget,或 false 若找不到。

另请参阅 focusNextChild ().

QWidget *QWidget:: focusProxy () const

返回聚焦代理,或 nullptr 若没有聚焦代理。

另请参阅 setFocusProxy ().

QWidget *QWidget:: focusWidget () const

返回最后子级当此小部件 setFocus 被调用。对于顶层 Widget,这是窗口被激活的情况下获得聚焦的小部件

这不同于 QApplication::focusWidget (),其返回在目前活动窗口中的聚焦 Widget。

QFontInfo QWidget:: fontInfo () const

返回 Widget 当前字体的字体信息。相当于 QFontInfo(widget->font()) .

另请参阅 font (), fontMetrics (),和 setFont ().

QFontMetrics QWidget:: fontMetrics () const

返回 Widget 当前字体的字体规格。相当于 QFontMetrics(widget->font()) .

另请参阅 font (), fontInfo (),和 setFont ().

QPalette::ColorRole QWidget:: foregroundRole () const

返回前景角色。

前景角色定义颜色来自 Widget 的 palette 用于绘制前景。

若未明确设置前景角色,函数返回对比后台角色的角色。

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

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

把 Widget 渲染成像素图,限定通过给定 rectangle 。若 Widget 有任何子级,它们也会被描绘在适当位置。

若矩形具有无效指定尺寸 (默认),整个 Widget 被描绘。

注意: 此函数可以被援引,通过元对象系统和从 QML。见 Q_INVOKABLE .

该函数在 Qt 5.0 引入。

另请参阅 render () 和 QPixmap .

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

将 Widget 订阅到给定 gesture 采有特定 flags .

另请参阅 ungrabGesture () 和 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 () 若想要抓取这。

警告: 以鼠标抓取应用程序的 Bug 会经常锁定终端。使用此函数要极其谨慎,并考虑使用 -nograb 命令行选项当调试时。

抓取鼠标几乎从不是必要的当使用 Qt 时,因为 Qt 会明智地抓取和释放鼠标。特别是,当鼠标按钮被按下时,Qt 抓住鼠标并保持它直到最后一个按钮被释放。

注意: 仅可见 Widget 可以抓取鼠标输入。若 isVisible () 返回 false 对于 Widget,小部件无法调用 grabMouse()。

注意: 在 Windows,grabMouse() 仅当鼠标位于进程所拥有的窗口内时才工作。在 macOS,grabMouse() 仅当鼠标位于该 Widget 框架内时才工作。

另请参阅 releaseMouse (), grabKeyboard (),和 releaseKeyboard ().

void QWidget:: grabMouse (const QCursor & cursor )

此函数重载 grabMouse()。

抓取鼠标输入和改变光标形状。

光标会假定形状 cursor (对于只要鼠标聚焦被抓住) 且此 Widget 将是接收鼠标事件的唯一小部件直到 releaseMouse () 被 called()。

警告: 抓取鼠标可能锁定终端。

注意: 见注意事项在 QWidget::grabMouse ().

另请参阅 releaseMouse (), grabKeyboard (), releaseKeyboard (),和 setCursor ().

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

将快捷方式添加到 Qt 快捷方式看守系统为给定 key 序列在给定 context 。若 context is Qt::ApplicationShortcut ,快捷方式适用于整个应用程序。否则,要么本地到此 Widget, Qt::WidgetShortcut ,或到窗口本身, Qt::WindowShortcut .

若相同 key 序列有被几个 Widget 所抓取,当 key 序列发生 QEvent::Shortcut event is sent to all the widgets to which it applies in a non-deterministic order, but with the ``ambiguous'' flag set to true.

警告: 通常不需要使用此函数;而是创建 QAction s with the shortcut key sequences you require (if you also want equivalent menu options and toolbar buttons), or create QShortcut s if you just need key sequences. Both QAction and QShortcut handle all the event filtering for you, and provide signals which are triggered when the user triggers the key sequence, so are much easier to use than this low-level function.

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

QGraphicsEffect *QWidget:: graphicsEffect () const

graphicsEffect 函数返回指向 Widget 图形效果的指针。

若 Widget 没有图形效果, nullptr 被返回。

另请参阅 setGraphicsEffect ().

QGraphicsProxyWidget *QWidget:: graphicsProxyWidget () const

返回在图形视图中相应嵌入 Widget 的代理小部件;否则返回 nullptr .

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

bool QWidget:: hasEditFocus () const

返回 true 若此 Widget 目前拥有编辑焦点;否则 false。

此特征只可用于 Qt for Embedded Linux。

另请参阅 setEditFocus () 和 QApplication::navigationMode ().

[virtual, since 5.0] bool QWidget:: hasHeightForWidth () const

返回 true 若 Widget 的首选高度取决于其宽度;否则返回 false .

该函数在 Qt 5.0 引入。

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

返回此 Widget 的首选高度,给定宽度 w .

If this widget has a layout, the default implementation returns the layout's preferred height. if there is no layout, the default implementation returns -1 indicating that the preferred height does not depend on the width.

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

此事件处理程序可以在子类中被重实现以接收 Widget 隐藏事件。事件被传入 event 参数。

隐藏事件被立即发送给 Widget 在它们被隐藏后。

注意:Widget 接收自发展示和隐藏事件当通过窗口系统改变其映射状态时,如:自发隐藏事件当用户最小化窗口时,和自发展示事件当窗口被再次还原时。在接收自发隐藏事件之后仍然认为 Widget 是可见的,在意识到 isVisible ().

另请参阅 visible , event (),和 QHideEvent .

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

初始化 painter 钢笔,背景和字体与给定 Widget 的相同。自动调用此函数,当描绘器被打开在 QWidget .

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

此事件处理程序,用于事件 event ,可以在子类中重实现以接收输入法合成事件。处理程序被调用,当输入法状态改变时。

注意:当创建自定义文本编辑 Widget 时, Qt::WA_InputMethodEnabled 窗口属性必须被明确设置 (使用 setAttribute () 函数) 为接收输入法事件。

默认实现调用 event->ignore(),拒绝输入法事件。见 QInputMethodEvent 文档编制了解更多细节。

另请参阅 event () 和 QInputMethodEvent .

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

此方法仅与输入 Widget 相关。输入法使用它查询 Widget 的一组属性,以便能够支持为支持围绕文本和再转换的复杂输入法操作。

query 指定查询特性。

另请参阅 inputMethodEvent (), QInputMethodEvent , QInputMethodQueryEvent ,和 inputMethodHints .

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

插入动作 action 到此 Widget 的动作列表,前置于动作 before 。它追加动作,若 before is nullptr or before 不是有效动作 (对于此 Widget)。

QWidget 每动作只应有一个。

另请参阅 removeAction (), addAction (), QMenu , contextMenuPolicy ,和 actions ().

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

插入动作 actions 到此 Widget 的动作列表,前置于动作 before 。它追加动作,若 before is nullptr or before 不是有效动作 (对于此 Widget)。

QWidget 每动作最多能有一个。

另请参阅 removeAction (), QMenu , insertAction (),和 contextMenuPolicy .

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

返回 true 若此 Widget 是父级 (或祖父级等任何级别),针对给定 child ,且两 Widget 在同一窗口;否则返回 false .

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

返回 true 若此 Widget 将变为被启用,若 ancestor 被启用;否则返回 false .

就是这种情况若不是 Widget 本身或每个父级直到,但排除 ancestor 已被明确禁用。

isEnabledTo(0) 返回 false 若此 Widget 或其任何祖先被明确禁用。

这里的祖先一词是指在相同窗口中的父级 Widget。

因此 isEnabledTo(0) 停止在此 Widget 窗口,不像 isEnabled () 还会考虑父级窗口。

另请参阅 setEnabled () 和 enabled .

bool QWidget:: isHidden () const

返回 true 若 Widget 被隐藏,否则返回 false .

隐藏 Widget 才变为可见当 show () 被它调用时。它不会自动展示当展示父级时。

要校验可见性,使用 ! isVisible () 代替 (注意感叹号)。

isHidden() 隐含 ! isVisible (),但 Widget 可以为不可见且同时不被隐藏。对于是不可见 Widget 子级的小部件就是这种情况。

Widget 被隐藏若:

  • 它们被创建作为独立窗口,
  • 它们是作为可见 Widget 子级创建的,
  • hide () 或 setVisible (false) 被调用。

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

返回 true 当此 Widget 变为可见若 ancestor 被展示;否则返回 false .

true 情况发生若 Widget 本身或任何父级直到但排除 ancestor 已被明确隐藏。

此函数仍将返回 true,若 Widget 被其它屏幕窗口遮挡,但可以是物理可见的,若它或它们要被移动。

isVisibleTo(0) 等同于 isVisible ().

另请参阅 show (), hide (),和 isVisible ().

bool QWidget:: isWindow () const

返回 true 若 Widget 是独立窗口,否则返回 false .

窗口不是任何其它可见小部件的子级 Widget,通常拥有框架和 窗口标题 .

窗口可以拥有 父级 Widget 。那么,它将与其父级被分组在一起和被删除当父级被删除时,它将最小化当父级被最小化时,等。若窗口管理器支持,它还拥有如其父级的常见任务栏条目。

QDialog and QMainWindow Widget 默认是窗口,即使在构造函数中有指定父级 Widget。此行为的指定通过 Qt::Window 标志。

另请参阅 window (), isModal (),和 parentWidget ().

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

此事件处理程序,用于事件 event ,可以在子类中被重实现以接收 Widget 按键事件。

Widget 必须调用 setFocusPolicy () 以接受初始聚焦并拥有焦点为接收键按下事件。

若重实现此处理程序,则调用基类实现很重要若按键不行动。

默认实现关闭弹出 Widget 若用户按下键序列 QKeySequence::Cancel (通常指 Escape 键)。否则,事件被忽略,以便 Widget 父级可以解释它。

注意, QKeyEvent 开始采用 isAccepted() == true,因此不需要调用 QKeyEvent::accept () - 仅仅不调用基类实现若按键有行动。

另请参阅 keyReleaseEvent (), setFocusPolicy (), focusInEvent (), focusOutEvent (), event (), QKeyEvent ,和 俄罗斯方块范例 .

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

此事件处理程序,用于事件 event ,可以在子类中被重实现以接收 Widget 按键释放事件。

Widget 必须 接受聚焦 初始和 拥有焦点 为接收键释放事件。

若重实现此处理程序,则调用基类实现很重要若按键不行动。

默认实现忽略事件,以便 Widget 父级可以解释它。

注意, QKeyEvent 开始采用 isAccepted() == true,因此不需要调用 QKeyEvent::accept () - 仅仅不调用基类实现若按键有行动。

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

[static] QWidget *QWidget:: keyboardGrabber ()

返回目前正抓取键盘输入的 Widget。

若在此应用程序中目前没有 Widget 正抓取键盘, nullptr 被返回。

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

QLayout *QWidget:: layout () const

返回安装在此 Widget 上的布局管理器,或 nullptr 若未安装布局管理器。

布局管理器设置已被添加到布局的 Widget 子级的几何体。

另请参阅 setLayout (), sizePolicy (),和 布局管理 .

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

此事件处理程序可以在子类中被重实现以接收 Widget 离开事件,当传入 event 参数。

离开事件被发送给 Widget 当鼠标光标离开 Widget 时。

另请参阅 enterEvent (), mouseMoveEvent (),和 event ().

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

翻译 Widget 坐标 pos 从坐标系统为 parent 到此 Widget 的坐标系统。 parent 必须不是 nullptr 且必须是调用 Widget 的父级。

该函数在 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 到 Widget 坐标。

该函数在 Qt 6.0 引入。

另请参阅 mapToGlobal (), mapFrom (),和 mapFromParent ().

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

这是重载函数。

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

翻译父级 Widget 坐标 pos 到 Widget 坐标。

如同 mapFromGlobal () 若 Widget 没有父级。

该函数在 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

翻译 Widget 坐标 pos 到坐标系统为 parent parent 必须不是 nullptr 且必须是调用 Widget 的父级。

该函数在 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

翻译 Widget 坐标 pos 到全局屏幕坐标。例如: mapToGlobal(QPointF(0,0)) 将给出 Widget 左上像素的全局坐标。

该函数在 Qt 6.0 引入。

另请参阅 mapFromGlobal (), mapTo (),和 mapToParent ().

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

这是重载函数。

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

翻译 Widget 坐标 pos 到父级 Widget 坐标。

如同 mapToGlobal () 若 Widget 没有父级。

该函数在 Qt 6.0 引入。

另请参阅 mapFromParent (), mapTo (), mapToGlobal (),和 underMouse ().

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

这是重载函数。

QRegion QWidget:: mask () const

返回在 Widget 上目前设置的遮罩。若未设置遮罩,返回值会是空区域。

另请参阅 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 ,可以在子类中重实现以接收 Widget 的鼠标双击事件。

默认实现调用 mousePressEvent ().

注意: The widget will also receive mouse press and mouse release events in addition to the double click event. And if another widget that overlaps this widget disappears in response to press or release events, then this widget will only receive the double click event. It is up to the developer to ensure that the application interprets these events correctly.

另请参阅 mousePressEvent (), mouseReleaseEvent (), mouseMoveEvent (), event (),和 QMouseEvent .

[static] QWidget *QWidget:: mouseGrabber ()

返回目前正抓取鼠标输入的 Widget。

若在此应用程序中目前没有 Widget 正抓取鼠标, nullptr 被返回。

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

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

此事件处理程序,用于事件 event ,可以在子类中重实现以接收 Widget 的鼠标移动事件。

If mouse tracking is switched off, mouse move events only occur if a mouse button is pressed while the mouse is being moved. If mouse tracking is switched on, mouse move events occur even if no mouse button is pressed.

QMouseEvent::pos () reports the position of the mouse cursor, relative to this widget. For press and release events, the position is usually the same as the position of the last mouse move event, but it might be different if the user's hand shakes. This is a feature of the underlying window system, not Qt.

If you want to show a tooltip immediately, while the mouse is moving (e.g., to get the mouse coordinates with QMouseEvent::pos () and show them as a tooltip), you must first enable mouse tracking as described above. Then, to ensure that the tooltip is updated immediately, you must call QToolTip::showText () 而不是 setToolTip () in your implementation of mouseMoveEvent().

另请参阅 setMouseTracking (), mousePressEvent (), mouseReleaseEvent (), mouseDoubleClickEvent (), event (), QMouseEvent ,和 涂鸦范例 .

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

此事件处理程序,用于事件 event ,可以在子类中被重实现以接收 Widget 鼠标按下事件。

If you create new widgets in the mousePressEvent() the mouseReleaseEvent () may not end up where you expect, depending on the underlying window system (or X11 window manager), the widgets' location and maybe more.

The default implementation implements the closing of popup widgets when you click outside the window. For other widget types it does nothing.

另请参阅 mouseReleaseEvent (), mouseDoubleClickEvent (), mouseMoveEvent (), event (), QMouseEvent ,和 涂鸦范例 .

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

此事件处理程序,用于事件 event ,可以在子类中被重实现以接收 Widget 鼠标释放事件。

另请参阅 mousePressEvent (), mouseDoubleClickEvent (), mouseMoveEvent (), event (), QMouseEvent ,和 涂鸦范例 .

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

这是重载函数。

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

注意: Setter 函数为特性 pos .

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

此事件处理程序可以在子类中重实现,以接收的 Widget 移动事件被传入 event 参数。当 Widget 收到此事件时,它已在新位置。

可访问旧位置透过 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 事件并将它发送给 Widget。

注意: 事件才被交付给此事件处理程序,若 Widget 具有本机窗口句柄。

注意: 此函数取代 Qt 4 的事件过滤器函数 x11Event() winEvent() 及 macEvent()。

平台 事件类型标识符 消息类型 结果类型
Windows "windows_generic_MSG" MSG * LRESULT
macOS "NSEvent" NSEvent *
XCB "xcb_generic_event_t" xcb_generic_event_t *

另请参阅 QAbstractNativeEventFilter .

QWidget *QWidget:: nativeParentWidget () const

返回此 Widget 的本机父级 (即:具有系统标识符的下一祖先小部件) 或 nullptr 若它没有任何本机父级。

另请参阅 effectiveWinId ().

QWidget *QWidget:: nextInFocusChain () const

返回在此 Widget 聚焦链中的下一小部件。

另请参阅 previousInFocusChain ().

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

将 Widget 窗口标志设为 flags , without 告诉窗口系统。

警告: 不要调用此函数,除非真的知道要做什么。

另请参阅 setWindowFlags ().

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

重实现: QPaintDevice::paintEngine () const.

返回 Widget 的描绘引擎。

注意:此函数不应该由用户明确调用,因为它仅意味着重实现目的。函数由 Qt 内部调用,且默认实现可能并不总是返回有效指针。

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

此事件处理程序可在子类中重实现以接收传入描绘事件 event .

描绘事件是重新描绘 Widget 全部或局部的请求。它能发生是因为下列原因之一:

  • repaint () 或 update () 被援引,
  • Widget 被遮盖且现被发现,或
  • 许多其它原因。

许多 Widget 可以在被要求时仅重新描绘其整个表面,但一些缓慢 Widget 需要通过只描绘请求区域进行优化: QPaintEvent::region ()。此速度优化不改变结果,因为描绘会被裁剪到该区域 (在事件处理期间)。 QListView and QTableView 会这样做,例如。

Qt 还试着通过把多个描绘事件合并成一个以加速描绘。当 update () 被多次调用或窗口系统发送多个描绘事件,Qt 把这些事件合并成具有更大区域的一个事件 (见 QRegion::united ())。 repaint () 函数不准许进行此种优化,因此建议使用 update () 每当可能时。

当描绘事件发生时,更新区域通常已被擦除,因此您正在 Widget 的背景上描绘。

背景可以被设置使用 setBackgroundRole () 和 setPalette ().

从 Qt 4.0 起, QWidget 自动双缓冲其描绘,因此不需要在 paintEvent() 中编写双缓冲代码以避免闪烁。

注意: 一般来说,应克制调用 update () 或 repaint () inside paintEvent()。例如,调用 update () 或 repaint () 在 paintEvent() 内子级会导致未定义行为;子级可能 (或不可能) 获得描绘事件。

警告: 若正在使用没有 Qt 的 Backingstore (后备存储) 的自定义描绘引擎, Qt::WA_PaintOnScreen 必须被设置。否则, QWidget::paintEngine () 将从不被调用;代之,将使用 Backingstore (后备存储)。

另请参阅 event (), repaint (), update (), QPainter , QPixmap , QPaintEvent ,和 指针式时钟范例 .

QWidget *QWidget:: parentWidget () const

返回此 Widget 的父级,或 nullptr 若它没有任何父级 Widget。

QWidget *QWidget:: previousInFocusChain () const

previousInFocusChain 函数返回此 Widget 聚焦链中的上一小部件。

另请参阅 nextInFocusChain ().

void QWidget:: releaseKeyboard ()

释放键盘抓取。

另请参阅 grabKeyboard (), grabMouse (),和 releaseMouse ().

void QWidget:: releaseMouse ()

释放鼠标抓取。

另请参阅 grabMouse (), grabKeyboard (),和 releaseKeyboard ().

void QWidget:: releaseShortcut ( int id )

删除快捷方式采用给定 id 从 Qt 的快捷方式系统。Widget 将不再接收 QEvent::Shortcut events for the shortcut's key sequence (unless it has other shortcuts with the same key sequence).

警告: You should not normally need to use this function since Qt's shortcut system removes shortcuts automatically when their parent widget is destroyed. It is best to use QAction or QShortcut to handle shortcuts, since they are easier to use than this low-level function. Note also that this is an expensive operation.

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

void QWidget:: removeAction ( QAction * action )

移除动作 action 从此 Widget 的动作列表。

另请参阅 insertAction (), actions (),和 insertAction ().

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

渲染 sourceRegion 的此 Widget 到 target 使用 renderFlags 以确定如何渲染。渲染始于 targetOffset target 。例如:

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

sourceRegion 是 null 区域,此函数将使用 QWidget::rect () 作为区域,即:整个 Widget。

确保调用 QPainter::end () 为 target 设备的活动描绘器 (若有的话) 在渲染之前。例如:

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

注意: 要获取 QOpenGLWidget 的内容,使用 QOpenGLWidget::grabFramebuffer() 代替。

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

这是重载函数。

将 Widget 渲染到 painter 's QPainter::device ().

变换和设置应用于 painter 将被使用当渲染时。

注意: painter 必须是活动的。在 macOS 将把 Widget 渲染到 QPixmap 然后绘制通过 painter .

另请参阅 QPainter::device ().

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

这是重载函数。

此版本重新描绘矩形 ( x , y , w , h ) 在 Widget 内。

w 是负的,它会被替换采用 width() - x ,且若 h 是负的,它会被替换采用 height() - y .

void QWidget:: repaint (const QRect & rect )

这是重载函数。

此版本重新描绘矩形 rect 在 Widget 内。

void QWidget:: repaint (const QRegion & rgn )

这是重载函数。

此版本重新描绘区域 rgn 在 Widget 内。

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

这是重载函数。

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

注意: Setter 函数为特性 size .

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

此事件处理程序可以在子类中被重实现以接收 Widget 重置尺寸事件,当传入 event 参数。当 resizeEvent() 被调用时,Widget 已经有新的几何体。旧尺寸是可访问的透过 QResizeEvent::oldSize ().

Widget 将被擦除并立即接收描绘事件,在处理重置尺寸事件后。无需 (或应该) 在此处理程序内完成绘制。

另请参阅 moveEvent (), event (), resize (), QResizeEvent , paintEvent (),和 涂鸦范例 .

bool QWidget:: restoreGeometry (const QByteArray & geometry )

还原顶层 Widget 的几何体和状态,存储在字节数组 geometry 。返回 true 当成功时;否则返回 false .

若还原几何体离屏,它将被修改为在可用屏幕几何体内。

要还原保存几何体使用 QSettings ,可以使用的代码像这样:

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

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

使用 QMainWindow::restoreState () 以还原几何体、工具栏和停放 Widget 状态。

另请参阅 saveGeometry (), QSettings , QMainWindow::saveState (),和 QMainWindow::restoreState ().

QByteArray QWidget:: saveGeometry () const

保存顶层 Widget 的当前几何体及状态。

要在窗口关闭时保存几何体,可以实现像这样的关闭事件:

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

窗口几何体 文档编制,了解有关窗口几何体问题的概述。

使用 QMainWindow::saveState () 以保存工具栏和停放 Widget 的几何体及状态。

另请参阅 restoreGeometry (), QMainWindow::saveState (),和 QMainWindow::restoreState ().

[since 5.14] QScreen *QWidget:: screen () const

返回 Widget 所在的屏幕。

该函数在 Qt 5.14 引入。

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

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

卷动 Widget 包括其子级 dx 像素到右侧和 dy 向下。两者 dx and dy 可能为负值。

在卷动之后,Widget 将接收需要重新描绘区域的描绘事件。对于 Qt 知道是不透明的 Widget,这只是新近暴露部分。例如,若不透明 Widget 向左滚动 8 像素,则只有右边缘 8 像素宽条纹需要更新。

由于 Widget 默认传播其父级内容,因此需要设置 autoFillBackground 特性,或使用 setAttribute () 去设置 Qt::WA_OpaquePaintEvent 属性,以使 Widget 变得不透明。

对于使用内容传播的 Widget,卷动将导致整个卷动区域的更新。

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

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

这是重载函数。

此版本仅卷动 r 且不会移动 Widget 子级。

r 为空或无效,结果不确定。

另请参阅 QScrollArea .

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

设置属性 attribute 在此 Widget 若 on 为 true;否则清零属性。

另请参阅 testAttribute ().

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

将 Widget 背景角色设为 role .

背景角色定义笔刷来自 Widget 的 palette 用于渲染背景。

role is QPalette::NoRole ,则 Widget 继承其父级的背景角色。

Note that styles are free to choose any color from the palette. You can modify the palette or set a style sheet if you don't achieve the result you want with setBackgroundRole().

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

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

这是重载函数。

此相当于 setBaseSize( QSize ( basew , baseh )). Sets the widgets base size to width basew and height baseh .

注意: Setter 函数为特性 baseSize .

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

Sets the margins around the contents of the widget to have the sizes left , top , right ,和 bottom . The margins are used by the layout system, and may be used by subclasses to specify the area to draw in (e.g. excluding the frame).

更改边距将触发 resizeEvent ().

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

void QWidget:: setContentsMargins (const QMargins & margins )

这是重载函数。

The setContentsMargins function sets the margins around the widget's contents.

Sets the margins around the contents of the widget to have the sizes determined by margins . The margins are used by the layout system, and may be used by subclasses to specify the area to draw in (e.g. excluding the frame).

更改边距将触发 resizeEvent ().

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

void QWidget:: setEditFocus ( bool enable )

enable 为 true,使此 Widget 拥有编辑聚焦,在这种情况下 Qt::Key_Up and Qt::Key_Down 通常将被交付给 Widget;否则, Qt::Key_Up and Qt::Key_Down are used to change focus.

此特征只可用于 Qt for Embedded Linux。

另请参阅 hasEditFocus () 和 QApplication::navigationMode ().

void QWidget:: setFixedHeight ( int h )

Sets both the minimum and maximum heights of the widget to h without changing the widths. Provided for convenience.

另请参阅 sizeHint (), minimumSize (), maximumSize (),和 setFixedSize ().

void QWidget:: setFixedSize (const QSize & s )

Sets both the minimum and maximum sizes of the widget to s , thereby preventing it from ever growing or shrinking.

这将覆盖默认尺寸约束设置通过 QLayout .

要移除约束,将尺寸设为 QWIDGETSIZE_MAX .

Alternatively, if you want the widget to have a fixed size based on its contents, you can call QLayout::setSizeConstraint ( QLayout::SetFixedSize );

另请参阅 maximumSize and minimumSize .

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

这是重载函数。

把 Widget 的宽度设置为 w 且高度为 h .

void QWidget:: setFixedWidth ( int w )

把 Widget 的最小 最大宽度设为 w 不改变高度。为方便起见提供。

另请参阅 sizeHint (), minimumSize (), maximumSize (),和 setFixedSize ().

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

把键盘输入聚焦给予此 Widget (或其聚焦代理),若此 Widget 或其父级之一是 活动窗口 reason argument will be passed into any focus event sent from this function, it is used to give an explanation of what caused the widget to get focus. If the window is not active, the widget will be given the focus when the window becomes active.

First, a focus about to change event is sent to the focus widget (if any) to tell it that it is about to lose the focus. Then focus is changed, a focus out event is sent to the previous focus item and a focus in event is sent to the new item to tell it that it just received the focus. (Nothing happens if the focus in and focus out widgets are the same.)

注意: On embedded platforms, setFocus() will not cause an input panel to be opened by the input method. If you want this to happen, you have to send a QEvent::RequestSoftwareInputPanel event to the widget yourself.

setFocus() gives focus to a widget regardless of its focus policy, but does not clear any keyboard grab (see grabKeyboard ()).

Be aware that if the widget is hidden, it will not accept focus until it is shown.

警告: If you call setFocus() in a function which may itself be called from focusOutEvent () 或 focusInEvent (), you may get an infinite recursion.

另请参阅 hasFocus (), clearFocus (), focusInEvent (), focusOutEvent (), setFocusPolicy (), focusWidget (), QApplication::focusWidget (), grabKeyboard (), grabMouse (), Widget 中的键盘焦点 ,和 QEvent::RequestSoftwareInputPanel .

void QWidget:: setFocusProxy ( QWidget * w )

把 Widget 的聚焦代理设为小部件 w 。若 w is nullptr ,函数把此 Widget 重置为没有聚焦代理。

Some widgets can "have focus", but create a child widget, such as QLineEdit , to actually handle the focus. In this case, the widget can set the line edit to be its focus proxy.

setFocusProxy() sets the widget which will actually get focus when "this widget" gets it. If there is a focus proxy, setFocus () 和 hasFocus () operate on the focus proxy. If "this widget" is the focus widget, then setFocusProxy() moves focus to the new focus proxy.

另请参阅 focusProxy ().

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

把 Widget 的前景角色设为 role .

前景角色定义颜色来自 Widget 的 palette 用于绘制前景。

role is QPalette::NoRole , the widget uses a foreground role that contrasts with the background role.

Note that styles are free to choose any color from the palette. You can modify the palette or set a style sheet if you don't achieve the result you want with setForegroundRole().

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

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

这是重载函数。

这相当于 setGeometry( QRect ( x , y , w , h )).

注意: Setter 函数为特性 geometry .

void QWidget:: setGraphicsEffect ( QGraphicsEffect * effect )

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

设置 effect as the widget's effect. If there already is an effect installed on this widget, QWidget will delete the existing effect before installing the new effect .

effect is the installed effect on a different widget, setGraphicsEffect() will remove the effect from the widget and install it on this widget.

QWidget takes ownership of effect .

注意: 此函数将效果应用到自身及其所有子级。

注意: Graphics effects are not supported for OpenGL-based widgets, such as QGLWidget, QOpenGLWidget and QQuickWidget .

另请参阅 graphicsEffect ().

void QWidget:: setLayout ( QLayout * layout )

将此 Widget 的布局管理器设为 layout .

如果此 Widget 已安装了布局管理器, QWidget 是不会允许安装另一个的。必须首先删除现有的布局管理器 (返回通过 layout ()),在可以采用新的布局调用 setLayout() 之前。

layout 是不同 Widget 的布局管理器,setLayout() 将重设父级布局,并使其成为此 Widget 的布局管理器。

范例:

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

调用此函数的备选方案,是把此 Widget 传递给布局构造函数。

QWidget 将拥有所有权对于 layout .

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

void QWidget:: setMask (const QBitmap & bitmap )

促使 Widget 像素仅与 bitmap 具有相应 1 位才可见。若区域包括像素超出 rect 为 Widget,在该区域中的窗口系统控件可能是可见的,也可能是不可见的,这取决于平台。

注意:此效果可能很慢,若区域特别复杂。

以下代码展示如何使用具有 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 才可见。若区域包括像素超出 rect 为 Widget,在该区域中的窗口系统控件可能是可见的,也可能是不可见的,这取决于平台。

注意:此效果可能很慢,若区域特别复杂。

另请参阅 windowOpacity .

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

这是重载函数。

此函数相当于 setMaximumSize( QSize ( maxw , maxh ))。设置最大宽度到 maxw 和最大高度到 maxh .

注意: Setter 函数为特性 maximumSize .

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

这是重载函数。

此函数相当于 setMinimumSize( QSize (minw, minh)). Sets the minimum width to minw and the minimum height to minh .

注意: Setter 函数为特性 minimumSize .

void QWidget:: setParent ( QWidget * parent )

将 Widget 父级设为 parent , and resets the window flags. The widget is moved to position (0, 0) in its new parent.

If the new parent widget is in a different window, the reparented widget and its children are appended to the end of the tab chain of the new parent widget, in the same internal order as before. If one of the moved widgets had keyboard focus, setParent() calls clearFocus () for that widget.

If the new parent widget is in the same window as the old parent, setting the parent doesn't change the tab order or keyboard focus.

If the "new" parent widget is the old parent widget, this function does nothing.

注意: The widget becomes invisible as part of changing its parent, even if it was previously visible. You must call show () 以使 Widget 再次可见。

警告: It is very unlikely that you will ever need this function. If you have a widget that changes its content dynamically, it is far easier to use QStackedWidget .

另请参阅 setWindowFlags ().

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

这是重载函数。

此函数还接受 Widget 标志, f 作为自变量。

void QWidget:: setScreen ( QScreen * screen )

将 Widget 应展示屏幕设为 screen .

设置屏幕仅对 Windows 有意义。若有必要,将重新创建 Widget 窗口在 screen .

注意: 若屏幕是多屏幕虚拟桌面的一部分,窗口不会自动移至 screen 。要相对屏幕放置窗口,使用屏幕的 topLeft() 位置。

另请参阅 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 被启用;否则快捷方式被禁用。

警告: You should not normally need to use this function since Qt's shortcut system enables/disables shortcuts automatically as widgets become hidden/visible and gain or lose focus. It is best to use QAction or QShortcut to handle shortcuts, since they are easier to use than this low-level function.

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

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

这是重载函数。

将 x (宽度) 尺寸增量设为 w 和 y (高度) 尺寸增量到 h .

注意: Setter 函数为特性 sizeIncrement .

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

这是重载函数。

将 Widget 的大小策略设为 horizontal and vertical ,采用标准拉伸和高度不为宽度。

注意: Setter 函数为特性 sizePolicy .

另请参阅 QSizePolicy::QSizePolicy ().

void QWidget:: setStyle ( QStyle * style )

将小部件 GUI 样式设为 style 。样式对象的所有权不转移。

If no style is set, the widget uses the application's style, QApplication::style () 代替。

Setting a widget's style has no effect on existing or future child widgets.

警告: This function is particularly useful for demonstration purposes, where you want to show Qt's styling capabilities. Real applications should avoid it and use one consistent GUI style instead.

警告: Qt 样式表目前不支持自定义 QStyle 子类。计划在某些未来发行中解决这。

另请参阅 style (), QStyle , QApplication::style (),和 QApplication::setStyle ().

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

放置 second 小部件后于 first 小部件按聚焦次序。

It effectively removes the second widget from its focus chain and inserts it after the first 小部件。

Note that since the tab order of the second widget is changed, you should order a chain like this:

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

not 像这样:

// 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 or second has a focus proxy, setTabOrder() correctly substitutes the proxy.

注意: Since Qt 5.10: A widget that has a child as focus proxy is understood as a compound widget. When setting a tab order between one or two compound widgets, the local tab order inside each will be preserved. This means that if both widgets are compound widgets, the resulting tab order will be from the last child inside first , to the first child inside second .

另请参阅 setFocusPolicy (), setFocusProxy (),和 Widget 中的键盘焦点 .

[since 5.9] void QWidget:: setWindowFlag ( Qt::WindowType flag , bool on = true)

设置窗口标志 flag 在此 Widget 若 on 为 true;否则清零标志。

该函数在 Qt 5.9 引入。

另请参阅 setWindowFlags (), windowFlags (),和 windowType ().

void QWidget:: setWindowRole (const QString & role )

把窗口角色设为 role 。这仅对 X11 中的窗口有意义。

另请参阅 windowRole ().

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

把窗口状态设为 windowState 。窗口状态是 OR (或) 组合的 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 再次可见。

注意: 在某些窗口系统中 Qt::WindowActive 不是立即的,且在某些情况下可能被忽略。

当窗口状态改变时,Widget 接收 changeEvent () 的类型 QEvent::WindowStateChange .

另请参阅 Qt::WindowState and windowState ().

void QWidget:: setupUi ( QWidget * widget )

把用户界面设为指定 widget .

注意: 此函数可用于派生自用户界面描述的 Widget,创建使用 uic .

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

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

此事件处理程序可以在子类中被重实现以接收 Widget 展示事件,当传入 event 参数。

非自发展示事件会被立即发送给 Widget 在展示它们之前。窗口的自发展示事件是之后交付的。

注意:Widget 接收自发展示和隐藏事件当通过窗口系统改变其映射状态时,如:自发隐藏事件当用户最小化窗口时,和自发展示事件当窗口被再次还原时。在接收自发隐藏事件之后仍然认为 Widget 是可见的,在意识到 isVisible ().

另请参阅 visible , event (),和 QShowEvent .

void QWidget:: stackUnder ( QWidget * w )

下置小部件 w 在父级 Widget 堆栈。

要使这工作,Widget 本身和 w 必须同级。

另请参阅 raise () 和 lower ().

QStyle *QWidget:: style () const

另请参阅 QWidget::setStyle (), QApplication::setStyle (),和 QApplication::style ().

[virtual protected] void QWidget:: tabletEvent ( QTabletEvent * event )

此事件处理程序,用于事件 event ,可在子类中重实现以接收 Widget 数位板事件。

若重实现此处理程序,非常重要的是 ignore() 事件若不处理它,以便 Widget 父级可以解释它。

默认实现忽略事件。

若数位板跟踪被切换为关,数位板移动事件才发生若手写笔接触数位板,或至少按下一手写笔按钮,当移动手写笔时。若数位板跟踪被切换为开,数位板移动事件发生,即使手写笔悬停在数位板附近,没有按下按钮。

另请参阅 QEvent::ignore (), QEvent::accept (), event (), setTabletTracking (),和 QTabletEvent .

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

返回 true 若属性 attribute 在此 Widget 被设置;否则返回 false .

另请参阅 setAttribute ().

bool QWidget:: underMouse () const

返回 true 若 Widget 在鼠标光标下方;否则返回 false .

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

另请参阅 enterEvent () 和 leaveEvent ().

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

取消订阅 Widget 从给定 gesture type

另请参阅 grabGesture () 和 QGestureEvent .

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

这是重载函数。

此版本更新矩形 ( x , y , w , h ) 在 Widget 内。

void QWidget:: update (const QRect & rect )

这是重载函数。

此版本更新矩形 rect 在 Widget 内。

void QWidget:: update (const QRegion & rgn )

这是重载函数。

此版本重新描绘区域 rgn 在 Widget 内。

void QWidget:: updateGeometry ()

通知布局系统此 Widget 已改变,且可能需要更改几何体。

调用此函数,若 sizeHint () 或 sizePolicy () 已改变。

对于明确隐藏 Widget,updateGeometry() 是空操作。会尽快通知布局系统,Widget 一展示。

QRegion QWidget:: visibleRegion () const

返回可以发生描绘事件的未遮盖区域。

对于可见 Widget,这是其它 Widget 未覆盖的近似区域;否则,这是空区域。

repaint () 函数会调用此函数若有必要,因此通常不需要调用它。

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

此事件处理程序,用于事件 event ,可以在子类中被重实现以接收 Widget 滚轮事件。

若重实现此处理程序,非常重要的是 ignore() 事件若不处理它,以便 Widget 父级可以解释它。

默认实现忽略事件。

另请参阅 QEvent::ignore (), QEvent::accept (), event (),和 QWheelEvent .

WId QWidget:: winId () const

返回 Widget 的窗口系统标识符。

原则上是可移植的,但若使用它,可能会做一些不可移植的事情。小心。

若 Widget 非本机 (外来) 且在其上援引了 winId(),则该 Widget 会提供本机句柄。

此值可能在运行时改变。事件带有类型 QEvent::WinIdChange 会被发送给 Widget 在窗口系统标识符改变后。

另请参阅 find ().

QWidget *QWidget:: window () const

返回用于此 Widget 的窗口,即具有 (或可能具有) 窗口系统框架的下一祖先 Widget。

若 Widget 是窗口,Widget 本身被返回。

典型用法是更改窗口标题:

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

另请参阅 isWindow ().

[since 5.0] QWindow *QWidget:: windowHandle () const

若这是本机 Widget,返回关联 QWindow 。否则返回 null。

本机 Widget 包括顶层小部件、QGLWidget 及子级小部件,在其中 winId () 被调用。

该函数在 Qt 5.0 引入。

另请参阅 winId () 和 screen ().

QString QWidget:: windowRole () const

返回窗口的角色 (或空字符串)。

另请参阅 setWindowRole (), windowIcon ,和 windowTitle .

Qt::WindowStates QWidget:: windowState () const

返回当前窗口状态。窗口状态是 OR (或) 组合的 Qt::WindowState : Qt::WindowMinimized , Qt::WindowMaximized , Qt::WindowFullScreen ,和 Qt::WindowActive .

另请参阅 Qt::WindowState and setWindowState ().

Qt::WindowType QWidget:: windowType () const

返回此 Widget 的窗口类型。这等同于 windowFlags () & Qt::WindowType_Mask .

另请参阅 windowFlags .

宏文档编制

QWIDGETSIZE_MAX

定义最大尺寸,为 QWidget 对象。

Widget 的最大允许尺寸为 QSize (QWIDGETSIZE_MAX, QWIDGETSIZE_MAX),即 QSize (16777215,16777215).

另请参阅 QWidget::setMaximumSize ().