QWidget 类

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

头：	#include <QWidget>
qmake:	QT += widgets
继承：	QObject and QPaintDevice
继承者：	38 types QAbstractButton , QAbstractSlider , QAbstractSpinBox , QCalendarWidget , QComboBox , QDesignerActionEditorInterface , QDesignerFormWindowInterface , QDesignerObjectInspectorInterface , QDesignerPropertyEditorInterface , QDesignerWidgetBoxInterface , QDesktopWidget , QDialog , QDialogButtonBox , QDockWidget , QFocusFrame , QFrame , QGroupBox , QKeySequenceEdit , QLineEdit , QMacCocoaViewContainer , QMacNativeWidget , QMainWindow , QMdiSubWindow , QMenu , QMenuBar , QOpenGLWidget , QProgressBar , QQuickWidget , QRubberBand , QSizeGrip , QSplashScreen , QSplitterHandle , QStatusBar , QSvgWidget , QTabBar , QTabWidget , QToolBar ，和 QWizardPage

• 所有成员列表，包括继承成员
• 过时成员

公共类型

enum	RenderFlag { DrawWindowBackground, DrawChildren, IgnoreMask }
flags	RenderFlags

特性

acceptDrops : bool accessibleDescription : QString accessibleName : QString autoFillBackground : bool baseSize : QSize childrenRect : const QRect childrenRegion : const QRegion contextMenuPolicy : Qt::ContextMenuPolicy cursor : QCursor enabled : bool focus : const bool focusPolicy : Qt::FocusPolicy font : QFont frameGeometry : const QRect frameSize : const QSize fullScreen : const bool geometry : QRect height : const int inputMethodHints : Qt::InputMethodHints isActiveWindow : const bool layoutDirection : Qt::LayoutDirection locale : QLocale maximized : const bool maximumHeight : int maximumSize : QSize maximumWidth : int minimized : const bool minimumHeight : int minimumSize : QSize minimumSizeHint : const QSize

minimumWidth : int modal : const bool mouseTracking : bool normalGeometry : const QRect palette : QPalette pos : QPoint rect : const QRect size : QSize sizeHint : const QSize sizeIncrement : QSize sizePolicy : QSizePolicy statusTip : QString styleSheet : QString tabletTracking : bool toolTip : QString toolTipDuration : int updatesEnabled : bool visible : bool whatsThis : QString width : const int windowFilePath : QString windowFlags : Qt::WindowFlags windowIcon : QIcon windowModality : Qt::WindowModality windowModified : bool windowOpacity : double windowTitle : QString x : const int y : const int

公共函数

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

重实现保护函数

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

保护槽

void	updateMicroFocus ()

宏

QWIDGETSIZE_MAX

详细描述

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 = { } (若可用) 设置窗口标志；默认适于几乎所有 Widget，但要获得如没有窗口系统框架的窗口，还必须使用特殊标志。

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

顶层和子级 Widget

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

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

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

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

复合 Widget

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

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

自定义 Widget 和描绘

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

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

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

大小提示和大小策略

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

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

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

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

事件

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

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

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

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

• paintEvent () 被调用每当需要重新描绘 Widget 时。每个显示自定义内容的 Widget 都必须实现它。描绘使用 QPainter 只可以发生在 paintEvent () 或函数调用通过 paintEvent ().
• resizeEvent () 被调用当 Widget 被重置大小时。
• mousePressEvent () 被调用当鼠标光标在 Widget 内按下鼠标按钮时，或者当 Widget 有抓取鼠标使用 grabMouse ()。按下鼠标不释放它如同有效调用 grabMouse ().
• mouseReleaseEvent () 被调用当释放鼠标按钮时。Widget 接收鼠标释放事件，当它有收到相应鼠标按下事件时。这意味着若用户按下鼠标在 your 小部件，然后将鼠标拖拽到其它地方在释放鼠标按钮之前， your 小部件接收释放事件。有一例外：若出现弹出菜单当按下鼠标按钮时，此弹出窗口会立即窃取鼠标事件。
• mouseDoubleClickEvent () 被调用当用户在 Widget 中双击时。若用户双击，Widget 将收到鼠标按下事件、鼠标释放事件 (鼠标点击事件)、第 2 次鼠标按下，此事件和最后第 2 次鼠标释放事件 (也可能收到一些鼠标移动事件，若在此操作期间鼠标未保持稳定)。它是 不可能 区分点击从双击直到第 2 次点击到达 (这是大多数 GUI 书籍为什么推荐双击是单击的扩展，而不是触发不同动作)。

接受键盘输入的 Widget 还需要重实现一些事件处理程序：

• keyPressEvent () 被调用每当按下键时，且它会再次自动重复当按下键时间够长时。 Tab and Shift+Tab 键才被传递给 Widget，若它们未用于焦点改变机制。要强制 Widget 处理这些键，必须重实现 QWidget::event ().
• focusInEvent () 被调用当 Widget 获得键盘聚焦时 (假定有调用 setFocusPolicy ())。行为良好的 Widget 以清晰但谨慎的方式指示它们拥有键盘聚焦。
• focusOutEvent () 被调用当 Widget 丢失键盘聚焦。

可能还要求重实现一些不太常见的事件处理程序：

• mouseMoveEvent () 被调用每当鼠标移动时，当按下鼠标按钮时。这在拖放操作期间很有用。若调用 setMouseTracking (true) 获取鼠标移动事件，甚至在未按下按钮时。(另请参阅 拖放 指南)
• keyReleaseEvent () 被调用每当键被释放且当按下它时 (若键自动重复)。在此情况下，每次重复 Widget 都会收到一对键释放和键按下事件。 Tab and Shift+Tab 键才被传递给 Widget，若它们未用于焦点改变机制。要强制 Widget 处理这些键，必须重实现 QWidget::event ().
• wheelEvent () 被调用每当用户转动鼠标滚轮时，当 Widget 拥有聚焦。
• enterEvent () 被调用当鼠标进入 Widget 的屏幕空间 (这排除由 Widget 的任何子级所拥有的屏幕空间)。
• leaveEvent () 被调用当鼠标离开 Widget 的屏幕空间。若鼠标进入子级 Widget，不会导致 leaveEvent ().
• moveEvent () 被调用当 Widget 有相对于其父级移动时。
• closeEvent () 被调用当用户关闭 Widget 时 (或当 close () 被调用)。

还有一些相当费解的事件描述在文档编制 QEvent::Type 。要处理这些事件，需要重实现 event () 直接。

默认实现的 event () 处理 Tab and Shift+Tab (以移动键盘聚焦)，并将大多数其它事件传递给上文更专业的某一处理程序。

事件和用于交付它们的机制涵盖在 事件系统 .

函数和特性组

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

在以上简图中，构造移除区域的半透明矩形子级小部件并将其添加到父级 Widget ( QLabel 展示像素图)。然后，设置不同特性和 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 设置窗口标志为半透明能工作。
• macOS：小部件需要拥有 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 () 被忽略当渲染到目标时。默认情况下，此选项是禁用的。

该枚举在 Qt 4.3 引入或被修改。

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

特性文档编制

acceptDrops : bool

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

把此特性设为 true 向系统宣布此小部件 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 .

该特性在 Qt 4.1 引入。

访问函数：

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

childrenRect : const QRect

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

排除隐藏子级。

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

访问函数：

QRect

childrenRect () const

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

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

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 的字体传播类似于其调色板传播。

当前样式用于渲染所有标准 Qt 小部件的内容，可以自由选择所用 Widget 字体，或在某些情况下，(部分或完全) 忽略它。尤其，某些风格像 GTK 风格、Mac 风格及 Windows Vista 风格，对 Widget 字体应用特殊修改以匹配平台的本机外观和感觉。因为此，将特性赋值给 Widget 字体并不保证会改变 Widget 外观。取而代之，可以选择应用 styleSheet .

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

访问函数：

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

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

frameGeometry : const QRect

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

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

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

访问函数：

QRect

frameGeometry () const

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

frameSize : const QSize

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

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

访问函数：

QSize

frameSize () const

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

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 4.6 引入。

访问函数：

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

另请参阅 inputMethodQuery ().

isActiveWindow : const bool

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

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

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

默认情况下，此特性为 false .

访问函数：

bool	isActiveWindow () const

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

layoutDirection : Qt::LayoutDirection

此特性保持此 Widget 的布局方向。

注意： 从 Qt 4.7 起，此方法不再影响文本布局方向。

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

当布局方向在 Widget 中有设置时，将传播到小部件子级，但不会传播给是窗口的子级，且也不会传播给已明确调用 setLayoutDirection() 的子级。此外，添加的子级小部件 after setLayoutDirection() 已被父级调用，不会继承父级的布局方向。

访问函数：

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

另请参阅 QApplication::layoutDirection .

locale : QLocale

此特性保持 Widget 的区域设置

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

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

该特性在 Qt 4.3 引入。

访问函数：

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

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

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 .

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 .

minimumSizeHint : const QSize

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

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

minimumSizeHint() 默认实现返回无效尺寸若此 Widget 没有布局，否则返回布局的最小尺寸。大多数内置 Widget 有重实现 minimumSizeHint()。

QLayout 从不会将 Widget 尺寸重置成小于最小尺寸提示，除非 minimumSize () 有设置或大小策略被设为 QSizePolicy::Ignore。若 minimumSize () 有设置，忽略最小尺寸提示。

访问函数：

virtual QSize

minimumSizeHint () const

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

minimumWidth : int

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

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

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

访问函数：

int	minimumWidth () const
void	setMinimumWidth (int minw )

另请参阅 minimumSize and minimumHeight .

modal : const bool

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

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

默认情况下，此特性为 false .

访问函数：

bool	isModal () const

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

mouseTracking : bool

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

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

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

访问函数：

bool	hasMouseTracking () const
void	setMouseTracking (bool enable )

另请参阅 mouseMoveEvent ().

normalGeometry : const QRect

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

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

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

访问函数：

QRect

normalGeometry () const

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

palette : QPalette

此特性保持 Widget 的调色板

此特性描述 Widget 的调色板。调色板用于 Widget 样式当渲染标准组件时，且可用作确保自定义 Widget 与本机平台外观和感觉可以保持一致的手段。不同平台或不同样式，有不同的调色板很常见。

当将新调色板赋值给 Widget 时，来自此调色板的颜色角色组合 Widget 的默认调色板，以形成 Widget 的最终调色板。Widget 背景角色的调色板条目用于填充小部件的背景 (见 QWidget::autoFillBackground )，和前景角色初始化 QPainter 的钢笔。

默认从属系统环境。 QApplication 维护充当所有 Widget 的默认的系统/主题调色板。对于某些类型的 Widget，还可能默认存在特殊调色板 (如：在 Windows Vista，所有类派生自 QMenuBar 拥有特殊默认调色板)。也可以定义自己的 Widget 默认调色板，通过将自定义调色板和 Widget 名称传递给 QApplication::setPalette ()。最后，样式始终拥有赋值时抛光调色板的选项 (见 QStyle::polish ()).

QWidget 明确将调色板角色从父级传播给子级。若将笔刷 (或颜色) 赋值给调色板中的特定角色，并将该调色板赋值给 Widget，该角色将被传播给 Widget 的所有子级，覆盖该角色的任何系统默认值。注意，默认情况下不会将调色板传播给窗口 (见 isWindow ()) 除非 Qt::WA_WindowPropagation 属性被启用。

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

当前风格用于渲染所有标准 Qt 小部件的内容，可以自由地从 Widget 调色板选择颜色和笔刷，或在某些情况下可以 (部分或完全) 忽略调色板。尤其，某些风格 (像 GTK 风格、Mac 风格及 Windows Vista 风格) 从属第三方 API 来渲染小部件的内容，且这些风格通常不遵循调色板。因为这，把角色赋值给 Widget 调色板不保证 Widget 会改变外观。相反，可以选择应用 styleSheet .

警告： 不要使用此函数结合 Qt 样式表 。当使用样式表时，可以使用 color、background-color、selection-color、selection-background-color 及 alternate-background-color 定制 Widget 调色板。

访问函数：

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

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

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 ，使用此函数的结果。

默认策略为 Preferred/Preferred (首选/首选)，意味着 Widget 可以自由重置大小，但首选大小由 sizeHint () 返回。像按钮 Widget 设置大小策略以指定它们可以水平拉伸，但垂直固定。这同样适用于行编辑控件 (譬如 QLineEdit , QSpinBox 或可编辑 QComboBox ) 及其它水平取向 Widget (譬如 QProgressBar ). QToolButton 通常为正方形，所以，它们允许 2 方向增长。支持不同方向的 Widget (譬如 QSlider , QScrollBar 或 QHeader) 仅指定相应方向的拉伸。可以提供滚动条的 Widget (通常是子类化的 QScrollArea ) 倾向于指定他们可以使用的额外空间，且他们可以使用的空间小于 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 子类。计划在某些未来发行中解决此问题。

该特性在 Qt 4.2 引入。

访问函数：

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

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

tabletTracking : bool

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

若数位板追踪被禁用 (默认)，Widget 才接收数位板移动事件当手写笔接触数位板时，或至少按下某一触控笔按钮，当移动手写笔时。

若数位板追踪被启用，Widget 接收数位板移动事件即使在附近徘徊。这对监控位置、辅助特性 (譬如：旋转和倾斜) 及在 UI 中提供反馈很有用。

该特性在 Qt 5.9 引入。

访问函数：

bool	hasTabletTracking () const
void	setTabletTracking (bool enable )

另请参阅 tabletEvent ().

toolTip : QString

此特性保持 Widget 的工具提示

注意，默认情况下，工具提示才展示当 Widget 是活动窗口子级时。可以改变此行为通过设置属性 Qt::WA_AlwaysShowToolTips 在 window ，不在带有工具提示的 Widget 中。

若想要控制工具提示的行为，可以拦截 event () 函数和捕获 QEvent::ToolTip 事件 (如，若想要定制应展示工具提示的区域)。

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

访问函数：

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

另请参阅 QToolTip , statusTip ，和 whatsThis .

toolTipDuration : int

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

指定工具提示将显示多长时间，以毫秒为单位。如果值为 -1 (默认)，将根据工具提示的长度计算持续时间。

该特性在 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 .

width : const int

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

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

注意： 不要使用此函数去查找屏幕的宽度在 多屏桌面 。读取 此注意事项 了解细节。

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

访问函数：

int	width () const

另请参阅 geometry , height ，和 size .

windowFilePath : QString

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

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

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

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

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

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

该特性在 Qt 4.4 引入。

访问函数：

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 图标

此特性仅对窗口有意义。若未设置图标，windowIcon() 返回应用程序图标 ( QApplication::windowIcon ()).

注意： 在 macOS，窗口图标表示活动文档，且不会显示除非还有设置文件路径使用 setWindowFilePath .

访问函数：

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

通知程序信号：

void	windowIconChanged (const QIcon & icon )

另请参阅 windowTitle and setWindowFilePath .

windowModality : Qt::WindowModality

此特性保持哪些窗口被模态 Widget 所阻塞

此特性仅对窗口有意义。模态 Widget 阻止在其它窗口中的 Widget 获得输入。此特性的值控制哪些窗口被阻塞当 Widget 可见时。改变此特性不起作用，当窗口可见时；必须 hide () Widget 首先，然后 show () 它再次。

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

该特性在 Qt 4.1 引入。

访问函数：

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 , 应用程序范例 , SDI 范例 ，和 MDI 范例 .

windowOpacity : double

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

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

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

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

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

警告： 将此特性从不透明更改为透明可能发出描绘事件，需要窗口在被正确显示之前处理。这主要影响使用 QScreen::grabWindow ()。另请注意，半透明窗口的更新和调整大小显著慢于不透明窗口。

访问函数：

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 .

x : const int

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

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

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

访问函数：

int	x () const

另请参阅 frameGeometry , y ，和 pos .

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 添加到已经可见的小部件，必须明确展示子级以使其可见。

注意，X11 版本的 Qt 可能无法在所有系统交付样式标志的所有组合。这是因为在 X11，Qt 只询问窗口管理器，且窗口管理器可以覆盖应用程序的设置。在 Windows，Qt 可以设置您想要的任何标志。

另请参阅 windowFlags .

[slot] bool QWidget:: close ()

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

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

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

The 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 及其子级小部件。

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

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

[slot] void QWidget:: showFullScreen ()

以全屏方式展示 Widget。

调用此函数仅影响 windows .

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

注意： 全屏模式在 Windows 工作得很好，在 X 却有一些问题。这些问题是由于 X11 客户端和窗口管理器之间指定的 ICCCM (国际计算机和通信管理会议) 通信协议的局限性所致。ICCCM 简直不理解非装饰全屏窗口的概念。因此，能做的最好是请求无边框窗口，放置并重置其大小以填充整个屏幕。从属窗口管理器，这可能工作，也可能不工作。使用 MOTIF 提示请求无边框窗口，至少部分支持所有现代窗口管理器。

替代是完全绕过窗口管理器和创建窗口采用 Qt::X11BypassWindowManagerHint 标志。虽然，这有其它严重问题，像破坏键盘焦点、当桌面改变 (或用户提升其它窗口) 时效果很奇怪。

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

在 macOS，全屏展示窗口将使整个应用程序在全屏模式下，为它提供专用桌面。当应用程序在全屏模式下运行时，展示另一窗口也可能自动使该窗口全屏。为阻止这，退出全屏模式通过调用 showNormal () 或通过 close () 在全屏窗口，在展示另一窗口之前。

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

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

更新 Widget 的微聚焦。

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

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

注意： 通知程序信号对于特性 windowIcon .

该函数在 Qt 5.2 引入。

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

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

注意： 通知程序信号对于特性 windowTitle .

该函数在 Qt 5.2 引入。

[虚拟] 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 ()，和 QWindowsWindowFunctions::setWindowActivationBehavior ().

void QWidget:: addAction ( QAction * action )

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

所有 QWidget 都拥有列表化的 QAction ，不管怎样，可以按多种不同方式图形表示它们。默认使用 QAction 列表 (作为返回通过 actions ()) 创建上下文 QMenu .

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

所有权对于 action 不会转移给此 QWidget .

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

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

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

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

void QWidget:: adjustSize ()

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

此函数使用 sizeHint () 若它有效 (即：大小提示的宽度和高度 >= 0)。否则，它设置大小为覆盖所有子级 Widget 的子级矩形 (所有子级 Widget 矩形的并集)。

对于窗口，屏幕大小也要考虑在内。若 sizeHint () 小于 (200, 100) 且大小策略为 expanding ，窗口将至少为 (200, 100)。窗口的最大大小是屏幕宽度和高度的 2/3。

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

QPalette::ColorRole QWidget:: backgroundRole () const

返回 Widget 的背景角色。

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

若未明确设置背景角色，Widget 继承其父级小部件的背景角色。

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

QBackingStore *QWidget:: backingStore () const

返回 QBackingStore 将在其中绘制此 Widget。

该函数在 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 ) 在 Widget 坐标系。若指定位置没有可见子级 Widget，函数返回 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 当 Qt 收到来自窗口系统顶层 Widget 的关闭请求时。

默认情况下，接受事件并关闭 Widget。可以重实现此函数以改变 Widget 响应窗口关闭请求的方式。例如，可以阻止窗口关闭通过调用 ignore() 在所有事件中。

主窗口应用程序通常使用此函数的重实现，以校验用户的工作是否已保存并询问权限在关闭前。例如， 应用程序范例 使用帮手函数来确定是否关闭窗口：

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

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

QMargins QWidget:: contentsMargins () const

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

该函数在 Qt 4.6 引入。

另请参阅 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 ().

窗口容器是以本机子级窗口形式被附加到顶层窗口作为其子级。当窗口容器被用作子级对于 QAbstractScrollArea or QMdiArea ，它将创建 本机窗口 为其父级链中的每个 Widget，以允许在此使用案例中正确地堆叠和裁剪。为窗口容器创建本机窗口也允许正确堆叠并裁剪。这必须在窗口容器展示之前完成。具有许多本机子级窗口的应用程序，可能遭遇性能问题。

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

• 堆叠次序；嵌入窗口将以不透明框方式堆叠在 Widget 层次结构顶部。多个重叠窗口容器实例的堆叠次序未定义。
• 渲染集成；窗口容器无法互操作与 QGraphicsProxyWidget , QWidget::render () 或类似功能。
• 聚焦处理；它是可能的让窗口容器实例拥有任何聚焦策略，且它会将聚焦委托给窗口凭借调用 QWindow::requestActivate ()。不管怎样，返回到正常聚焦链从 QWindow 实例将取决于 QWindow 实例实现自身。例如，当进入带 Tab 聚焦基于 Qt Quick 的窗口时，进一步按下 Tab 很可能只会在 QML 应用程序内循环。另外，是否 QWindow::requestActivate () 实际赋予窗口聚焦，从属平台。
• 使用多个窗口容器实例在 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。

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

该函数在 Qt 4.4 引入。

另请参阅 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 ( QEvent * 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，向后搜索。

有时，会想要重实现此函数。例如，Web 浏览器可以重实现它以向前 (或向后) 移动其 "当前活动链接"，且当它到达 "页面" 中的最后一个 (或第一个) 链接时才调用 focusNextPrevidChild()。

子级 Widget 对其父级小部件调用 focusNextPrevidChild()，但仅包含子级 Widget 的窗口能决定要重定向聚焦到哪里。通过重实现对象的此函数，可以控制所有子级 Widget 的聚焦遍历。

另请参阅 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 ().

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 .

该函数在 Qt 4.6 引入。

另请参阅 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 ，快捷方式适用于整个应用程序。否则，要么本地到此小部件 Qt::WidgetShortcut ，或到窗口自身 Qt::WindowShortcut .

若相同 key 序列有被几个 Widget 所抓取，当 key 序列出现 QEvent::Shortcut 事件以不确定次序发送给应用它的所有 Widget，但将 "ambiguous (歧义)" 标志设为 true。

警告： 通常不需要使用此函数；而是创建 QAction 采用要求的快捷键序列 (若还想要等效菜单选项和工具栏按钮)，或创建 QShortcut 若仅仅需要键序列。 QAction and QShortcut 会为您处理所有事件过滤，并提供当用户触发键序列时触发的信号，所以比此低级函数更易于使用。

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

QGraphicsEffect *QWidget:: graphicsEffect () const

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

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

该函数在 Qt 4.6 引入。

另请参阅 setGraphicsEffect ().

QGraphicsProxyWidget *QWidget:: graphicsProxyWidget () const

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

该函数在 Qt 4.5 引入。

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

bool QWidget:: hasEditFocus () const

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

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

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

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

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

该函数在 Qt 5.0 引入。

[虚拟] int QWidget:: heightForWidth ( int w ) const

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

若此 Widget 拥有布局，默认实现将返回布局的首选高度。若没有布局，默认实现返回 -1，指示首选高度不依赖宽度。

[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 .

[虚拟] 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)。

A QWidget 每动作只应有一个。

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

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

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

A 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 ().

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

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

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

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

翻译全局屏幕坐标 pos 到 Widget 坐标。

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

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

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

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

另请参阅 mapToParent (), mapFrom (), mapFromGlobal ()，和 underMouse ().

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

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

另请参阅 mapFrom (), mapToParent (), mapToGlobal ()，和 underMouse ().

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

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

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

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

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

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

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

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

注意： Widget 还接收鼠标按下和鼠标释放事件，除双击事件外。若和此 Widget 重叠的另一 Widget 在响应按下 (或释放) 事件时消失，那么此 Widget 将只接收双击事件。由开发者来确保应用程序正确地解释这些事件。

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

[static] QWidget *QWidget:: mouseGrabber ()

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

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

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

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

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

若鼠标跟踪被切换为关，当移动鼠标按下鼠标按钮时才发生鼠标移动事件。若鼠标跟踪被切换为开，会发生鼠标移动事件即使鼠标按钮未按下。

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

若想在移动鼠标时立即展示工具提示 (如：获取鼠标坐标采用 QMouseEvent::pos () 并将它们展示成工具提示)，必须首先启用如上所述的鼠标跟踪。然后，为确保能立即更新工具提示，必须调用 QToolTip::showText () 而不是 setToolTip () 在 mouseMoveEvent() 实现中。

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

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

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

若在 mousePressEvent() 中创建新的 Widget，那么 mouseReleaseEvent () 可能不在期望地方结束，从属底层窗口系统 (或 X11 窗口管理器)、Widget 位置、等等。

默认实现是实现关闭弹出 Widget，当在窗口外点击时。对于其它 Widget 类型，什么都不做。

另请参阅 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 , long * 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 若它没有任何本机父级。

该函数在 Qt 4.4 引入。

另请参阅 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 聚焦链中的上一小部件。

该函数在 Qt 4.6 引入。

另请参阅 nextInFocusChain ().

void QWidget:: releaseKeyboard ()

释放键盘抓取。

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

void QWidget:: releaseMouse ()

释放鼠标抓取。

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

void QWidget:: releaseShortcut ( int id )

删除快捷方式采用给定 id 从 Qt 的快捷方式系统。Widget 将不再接收 QEvent::Shortcut 事件对于快捷方式键序列 (除非它有具有相同键序列的其它快捷方式)。

警告： 通常应该不需要使用此函数，因为 Qt 的快捷方式系统会自动移除快捷方式，当它们的父级 Widget 被销毁时。最好使用 QAction or QShortcut 处理快捷方式，因为它们比此低级函数更易于使用。另请注意，此操作很昂贵。

另请参阅 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 () 代替。

注意： To obtain the contents of a QGLWidget (deprecated), use QGLWidget::grabFrameBuffer() or QGLWidget::renderPixmap() instead.

该函数在 Qt 4.3 引入。

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 将被使用当渲染时。

注意： The 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 状态。

该函数在 Qt 4.2 引入。

另请参阅 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 的几何体及状态。

该函数在 Qt 4.2 引入。

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

QScreen *QWidget:: screen () const

返回 Widget 所在的屏幕。

该函数在 Qt 5.14 引入。

另请参阅 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 属性 , bool on = true)

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

另请参阅 testAttribute ().

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

将 Widget 背景角色设为 role .

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

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

注意，样式能从调色板自由选取任何颜色。可以修改调色板或设置样式表，若采用 setBackgroundRole() 未达到想要的结果。

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

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

这是重载函数。

此相当于 setBaseSize( QSize ( basew , baseh ))。将 Widget 的基尺寸设为宽度 basew 和高度 baseh .

注意： setter 函数对于特性 baseSize .

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

将围绕 Widget 内容的边距设为拥有尺寸 left , top , right ，和 bottom 。边距用于布局系统，且可以用于子类以指定要在其中 (如：不包括框架) 绘制的区域。

更改边距将触发 resizeEvent ().

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

void QWidget:: setContentsMargins (const QMargins & margins )

这是重载函数。

setContentsMargins 函数设置围绕 Widget 内容的边距。

设置围绕 Widget 内容的边距大小，确定通过 margins 。边距用于布局系统，且可以用于子类以指定要在其中 (如：不包括框架) 绘制的区域。

更改边距将触发 resizeEvent ().

该函数在 Qt 4.6 引入。

另请参阅 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 可用于改变焦点。

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

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

void QWidget:: setFixedHeight ( int h )

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

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

void QWidget:: setFixedSize (const QSize & s )

将 Widget 的最小和最大尺寸设为 s ，从而阻止其增长 (或收缩)。

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

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

另外，若想要 Widget 基于其内容拥有固定大小，可以调用 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 自变量会被传入从此函数发送的任何聚焦事件，用于解释为什么导致 Widget 获得聚焦。若窗口不活动，Widget 将获得焦点当窗口变为活动时。

首先，将聚焦即将更改事件发送给聚焦 Widget (若有的话)，告诉它即将失去聚焦。然后改变聚焦，将聚焦出事件发送给先前聚焦项，并将聚焦入事件发送给新的项 (告诉它刚刚收到聚焦；什么都不发生，若聚焦入和聚焦出 Widget 相同)。

注意： 在嵌入式平台，setFocus() 不会导致输入法打开输入面板。若想要这发生，必须发送 QEvent::RequestSoftwareInputPanel 事件给 Widget 自身。

setFocus() 将聚焦赋予 Widget 不管其聚焦策略，但不清零任何键盘抓取 (见 grabKeyboard ()).

注意，若 Widget 被隐藏，不接受聚焦直到它被展示为止。

警告： 若在可以调用自身的函数中调用 setFocus() 从 focusOutEvent () 或 focusInEvent ()，会获得无限递归。

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

void QWidget:: setFocusProxy ( QWidget * w )

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

某些 Widget 可以拥有聚焦，但会创建子级 Widget，譬如 QLineEdit ，以实际处理聚焦。在这种情况下，Widget 可以将行编辑设为其聚焦代理。

setFocusProxy() 设置实际获得聚焦的小部件，当此 Widget 获得聚焦时。若存在聚焦代理， setFocus () 和 hasFocus () 将运转于聚焦代理。若此 Widget 是聚焦小部件，那么 setFocusProxy() 将把聚焦移到新的聚焦代理。

另请参阅 focusProxy ().

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

把 Widget 的前景角色设为 role .

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

若 role is QPalette::NoRole ，Widget 使用对比背景角色的前景角色。

注意，样式能从调色板自由选取任何颜色。可以修改调色板或设置样式表，若采用 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 作为 Widget 的效果。若此 Widget 有安装效果， QWidget 将删除现有效果先于安装新 effect .

若 effect 是在不同 Widget 安装效果，setGraphicsEffect() 将从 Widget 移除效果并将它安装在此小部件中。

QWidget 拥有所有权对于 effect .

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

注意： 图形效果不支持基于 OpenGL 的 Widget，譬如 QGLWidget， QOpenGLWidget and QQuickWidget .

该函数在 Qt 4.6 引入。

另请参阅 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 传递给布局构造函数。

The 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)）。设置最小宽度到 minw 和最小高度到 minh .

注意： setter 函数对于特性 minimumSize .

void QWidget:: setParent ( QWidget * parent )

将 Widget 父级设为 parent ，并重置窗口标志。把 Widget 移到其新父级的 (0, 0) 位置。

若新的父级 Widget 在不同窗口中，重设父级的小部件及其子级会被追加到末尾对于 Tab 链 的新父级 Widget，以与之前相同的内部次序。若被移动 Widget 之一拥有键盘聚焦，则 setParent() 会调用 clearFocus () 为该 Widget。

若新父级 Widget 和旧父级在同一窗口中，设置父级不改变选项卡次序 (或键盘聚焦)。

若新父级 Widget 是旧父级小部件，此函数什么都不做。

注意： 作为改变其父级的一部分 Widget 变为不可见，即使它先前可见。必须调用 show () 以使 Widget 再次可见。

警告： 您不太可能需要此函数。若有动态改变其内容的 Widget，容易得多的是使用 QStackedWidget .

另请参阅 setWindowFlags ().

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

这是重载函数。

此函数还接受 Widget 标志， f 作为自变量。

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

若 enable 为 true，快捷方式的自动重复采用给定 id 被启用；否则被禁用。

该函数在 Qt 4.2 引入。

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

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

若 enable 为 True，快捷方式采用给定 id 被启用；否则快捷方式被禁用。

警告： 应该通常不需要使用此函数，因为 Qt 的快捷方式系统会自动启用/禁用快捷方式当 Widget 变为隐藏/可见并获得 (或失去) 聚焦时。最好使用 QAction or QShortcut 处理快捷方式，因为它们比此低级函数更易于使用。

另请参阅 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 。样式对象的所有权不转移。

若未设置样式，Widget 使用应用程序的样式， QApplication::style () 代替。

设置 Widget 的样式不影响现有 (或未来) 子级小部件。

警告： 此函数对于想要展示 Qt 的样式化能力的演示目的特别有用。真实应用程序应避免并使用一种一致的 GUI 样式代替。

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

另请参阅 style (), QStyle , QApplication::style ()，和 QApplication::setStyle ().

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

放置 second 小部件后于 first 小部件按聚焦次序。

它有效移除 second 小部件从其聚焦链并将它插入后于 first 小部件。

注意，由于选项卡次序对于 second 小部件已改变，应排序链像这样：

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

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 拥有聚焦代理，setTabOrder(） 会正确代入代理。

注意： 从 Qt 5.10 起：会将拥有子级作为聚焦代理的 Widget，理解成复合小部件。当在 1 个或 2 个复合小部件之间设置选项卡次序时，将保留每个复合小部件内的本地选项卡次序。这意味着若 2 个 Widget 都是复合小部件，产生的选项卡次序将从最后一个子级 first ，到第一子级 second .

另请参阅 setFocusPolicy (), setFocusProxy ()，和 Widget 中的键盘焦点 .

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 .

另请参阅 在 C++ 应用程序使用 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 属性 ) const

返回 true 若属性 属性 在此 Widget 被设置；否则返回 false .

另请参阅 setAttribute ().

bool QWidget:: underMouse () const

返回 true 若 Widget 在鼠标光标下方；否则返回 false .

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

另请参阅 enterEvent () 和 leaveEvent ().

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

取消 Widget 订阅从给定 gesture type

该函数在 Qt 4.6 引入。

另请参阅 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 未涵盖的近似区域；否则，这是空区域。

The 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 ().

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

内容

• 公共类型

• 特性

• 公共函数

• 重实现公共函数

• 公共槽

• 信号

• 静态公共成员

• 保护函数

• 重实现保护函数

• 保护槽

• 宏

• 详细描述

• 顶层和子级 Widget

• 复合 Widget

• 自定义 Widget 和描绘

• 大小提示和大小策略

• 事件

• 函数和特性组

• Widget 样式表

• 透明度和双缓冲

• 创建半透明窗口

• 本机小部件 vs 外来小部件