PySide6.QtWidgets.QWidget¶

class QWidget¶

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

Inherited by: QWizardPage, QToolBar, QTabWidget, QTabBar, QStatusBar, QSplitterHandle, QSplashScreen, QSizeGrip, QRubberBand, QRhiWidget, QProgressBar, QMenuBar, QMenu, QMdiSubWindow, QMainWindow, QLineEdit, QKeySequenceEdit, QGroupBox, QFrame, QToolBox, QStackedWidget, QSplitter, QLabel, QLCDNumber, QAbstractScrollArea, QTextEdit, QTextBrowser, QScrollArea, QPlainTextEdit, QMdiArea, QGraphicsView, QAbstractItemView, QTreeView, QTreeWidget, QHelpContentWidget, QTableView, QTableWidget, QListView, QUndoView, QListWidget, QHelpIndexWidget, QHeaderView, QColumnView, QPdfView, QFocusFrame, QDockWidget, QDialogButtonBox, QDialog, QWizard, QProgressDialog, QMessageBox, QInputDialog, QFontDialog, QErrorMessage, QColorDialog, QPrintPreviewDialog, QPageSetupDialog, QAbstractPrintDialog, QPrintDialog, QComboBox, QFontComboBox, QCalendarWidget, QAbstractSpinBox, QSpinBox, QDoubleSpinBox, QDateTimeEdit, QTimeEdit, QDateEdit, QAbstractSlider, QSlider, QScrollBar, QDial, QAbstractButton, QToolButton, QRadioButton, QPushButton, QCommandLinkButton, QCheckBox, QSvgWidget, QQuickWidget, QPrintPreviewWidget, QPdfPageSelector, QOpenGLWidget, QVideoWidget, QHelpSearchResultWidget, QHelpSearchQueryWidget, QHelpFilterSettingsWidget, QDesignerWidgetBoxInterface, QDesignerPropertyEditorInterface, QDesignerObjectInspectorInterface, QDesignerFormWindowInterface, QDesignerActionEditorInterface, QFileDialog, QWebEngineView, QChartView

概要¶

属性¶

• acceptDropsᅟ - 是否为此小部件启用了拖放事件

• accessibleDescriptionᅟ - 辅助技术所看到的小部件描述

• accessibleNameᅟ - 小部件的名称，由辅助技术可见

• autoFillBackgroundᅟ - 是否自动填充小部件背景

• baseSizeᅟ - 小部件的基础大小

• childrenRectᅟ - 小部件子元素的边界矩形

• childrenRegionᅟ - 小部件子元素占用的组合区域

• contextMenuPolicyᅟ - 小部件如何显示上下文菜单

• cursorᅟ - 此小部件的光标形状

• enabledᅟ - 小部件是否启用

• focusᅟ - 此小部件（或其焦点代理）是否具有键盘输入焦点

• focusPolicyᅟ - 小部件接受键盘焦点的方式

• fontᅟ - 当前为小部件设置的字体

• frameGeometryᅟ - 小部件相对于其父部件的几何形状，包括任何窗口框架

• frameSizeᅟ - 小部件的大小，包括任何窗口框架

• fullScreenᅟ - 小部件是否以全屏模式显示

• geometryᅟ - 小部件相对于其父部件的几何形状，不包括窗口框架

• heightᅟ - 小部件的高度，不包括任何窗口框架

• inputMethodHintsᅟ - 该小部件具有的输入法特定提示

• isActiveWindowᅟ - 此小部件的窗口是否为活动窗口

• layoutDirectionᅟ - 此小部件的布局方向

• localeᅟ - 小部件的区域设置

• maximizedᅟ - 此小部件是否最大化

• maximumHeightᅟ - 小部件的最大高度（以像素为单位）

• maximumSizeᅟ - 小部件的最大尺寸（以像素为单位）

• maximumWidthᅟ - 小部件的最大宽度（以像素为单位）

• minimizedᅟ - 此小部件是否最小化（图标化）

• minimumHeightᅟ - 控件的最小高度（以像素为单位）

• minimumSizeᅟ - 控件的最小尺寸

• minimumSizeHintᅟ - 推荐的小部件最小尺寸

• minimumWidthᅟ - 控件的最小宽度（以像素为单位）

• modalᅟ - 该小部件是否为模态小部件

• mouseTrackingᅟ - 是否启用了小部件的鼠标跟踪

• normalGeometryᅟ - 小部件在显示为普通（非最大化或全屏）顶层小部件时的几何形状

• paletteᅟ - 小部件的调色板

• posᅟ - 小部件在其父部件中的位置

• rectᅟ - 小部件的内部几何形状，不包括任何窗口框架

• sizeᅟ - 小部件的大小，不包括任何窗口框架

• sizeHintᅟ - 小部件的推荐大小

• sizeIncrementᅟ - 小部件的大小增量

• sizePolicyᅟ - 小部件的默认布局行为

• statusTipᅟ - 小部件的状态提示

• styleSheetᅟ - 小部件的样式表

• tabletTrackingᅟ - 是否启用了小部件的平板追踪功能

• toolTipᅟ - 小部件的工具提示

• toolTipDurationᅟ - 小部件的工具提示持续时间

• updatesEnabledᅟ - 是否启用更新

• visibleᅟ - 小部件是否可见

• whatsThisᅟ - 小部件的“这是什么”帮助文本

• widthᅟ - 小部件的宽度，不包括任何窗口框架

• windowFilePathᅟ - 与小部件关联的文件路径

• windowIconᅟ - 小部件的图标

• windowIconTextᅟ - 在最小化窗口的图标上显示的文本

• windowModalityᅟ - 哪些窗口被模态小部件阻塞

• windowModifiedᅟ - 窗口中显示的文档是否有未保存的更改

• windowOpacityᅟ - 窗口的透明度级别

• windowTitleᅟ - 窗口标题（标题）

• xᅟ - 小部件相对于其父级的x坐标，包括任何窗口框架

• yᅟ - 小部件相对于其父级的y坐标，包括任何窗口框架

方法¶

• def __init__()

• def acceptDrops()

• def accessibleDescription()

• def accessibleName()

• def actions()

• def activateWindow()

• def addAction()

• def addActions()

• def adjustSize()

• def autoFillBackground()

• def backgroundRole()

• def backingStore()

• def baseSize()

• def childAt()

• def childrenRect()

• def childrenRegion()

• def clearFocus()

• def clearMask()

• def contentsMargins()

• def contentsRect()

• def contextMenuPolicy()

• def create()

• def createWinId()

• def cursor()

• def destroy()

• def effectiveWinId()

• def ensurePolished()

• def focusNextChild()

• def focusPolicy()

• def focusPreviousChild()

• def focusProxy()

• def focusWidget()

• def font()

• def fontInfo()

• def fontMetrics()

• def foregroundRole()

• def frameGeometry()

• def frameSize()

• def geometry()

• def grab()

• def grabGesture()

• def grabKeyboard()

• def grabMouse()

• def grabShortcut()

• def graphicsEffect()

• def graphicsProxyWidget()

• def hasFocus()

• def hasMouseTracking()

• def hasTabletTracking()

• def inputMethodHints()

• def insertAction()

• def insertActions()

• def internalWinId()

• def isActiveWindow()

• def isAncestorOf()

• def isEnabled()

• def isEnabledTo()

• def isFullScreen()

• def isHidden()

• def isLeftToRight()

• def isMaximized()

• def isMinimized()

• def isModal()

• def isRightToLeft()

• def isTopLevel()

• def isVisible()

• def isVisibleTo()

• def isWindow()

• def isWindowModified()

• def layout()

• def layoutDirection()

• def locale()

• def mapFrom()

• def mapFromGlobal()

• def mapFromParent()

• def mapTo()

• def mapToGlobal()

• def mapToParent()

• def mask()

• def maximumHeight()

• def maximumSize()

• def maximumWidth()

• def minimumHeight()

• def minimumSize()

• def minimumWidth()

• def move()

• def nativeParentWidget()

• def nextInFocusChain()

• def normalGeometry()

• def overrideWindowFlags()

• def overrideWindowState()

• def palette()

• def parentWidget()

• def pos()

• def previousInFocusChain()

• def rect()

• def releaseKeyboard()

• def releaseMouse()

• def releaseShortcut()

• def removeAction()

• def render()

• def repaint()

• def resize()

• def restoreGeometry()

• def saveGeometry()

• def screen()

• def scroll()

• def setAcceptDrops()

• def setAccessibleDescription()

• def setAccessibleName()

• def setAttribute()

• def setAutoFillBackground()

• def setBackgroundRole()

• def setBaseSize()

• def setContentsMargins()

• def setContextMenuPolicy()

• def setCursor()

• def setFixedHeight()

• def setFixedSize()

• def setFixedWidth()

• def setFocus()

• def setFocusPolicy()

• def setFocusProxy()

• def setFont()

• def setForegroundRole()

• def setGeometry()

• def setGraphicsEffect()

• def setInputMethodHints()

• def setLayout()

• def setLayoutDirection()

• def setLocale()

• def setMask()

• def setMaximumHeight()

• def setMaximumSize()

• def setMaximumWidth()

• def setMinimumHeight()

• def setMinimumSize()

• def setMinimumWidth()

• def setMouseTracking()

• def setPalette()

• def setParent()

• def setScreen()

• def setShortcutAutoRepeat()

• def setShortcutEnabled()

• def setSizeIncrement()

• def setSizePolicy()

• def setStatusTip()

• def setStyle()

• def setTabletTracking()

• def setToolTip()

• def setToolTipDuration()

• def setUpdatesEnabled()

• def setWhatsThis()

• def setWindowFilePath()

• def setWindowFlag()

• def setWindowFlags()

• def setWindowIcon()

• def setWindowIconText()

• def setWindowModality()

• def setWindowOpacity()

• def setWindowRole()

• def setWindowState()

• def size()

• def sizeIncrement()

• def sizePolicy()

• def stackUnder()

• def statusTip()

• def style()

• def styleSheet()

• def testAttribute()

• def toolTip()

• def toolTipDuration()

• def topLevelWidget()

• def underMouse()

• def ungrabGesture()

• def unsetCursor()

• def unsetLayoutDirection()

• def unsetLocale()

• def update()

• def updateGeometry()

• def updatesEnabled()

• def visibleRegion()

• def whatsThis()

• def winId()

• def window()

• def windowFilePath()

• def windowFlags()

• def windowHandle()

• def windowIcon()

• def windowIconText()

• def windowModality()

• def windowOpacity()

• def windowRole()

• def windowState()

• def windowTitle()

• def windowType()

• def x()

• def y()

虚拟方法¶

• def actionEvent()

• def changeEvent()

• def closeEvent()

• def contextMenuEvent()

• def dragEnterEvent()

• def dragLeaveEvent()

• def dragMoveEvent()

• def dropEvent()

• def enterEvent()

• def focusInEvent()

• def focusNextPrevChild()

• def focusOutEvent()

• def hasHeightForWidth()

• def heightForWidth()

• def hideEvent()

• def inputMethodEvent()

• def inputMethodQuery()

• def keyPressEvent()

• def keyReleaseEvent()

• def leaveEvent()

• def minimumSizeHint()

• def mouseDoubleClickEvent()

• def mouseMoveEvent()

• def mousePressEvent()

• def mouseReleaseEvent()

• def moveEvent()

• def nativeEvent()

• def paintEvent()

• def resizeEvent()

• def setVisible()

• def showEvent()

• def sizeHint()

• def tabletEvent()

• def wheelEvent()

插槽¶

• def close()

• def hide()

• def lower()

• def raise_()

• def repaint()

• def setDisabled()

• def setEnabled()

• def setFocus()

• def setHidden()

• def setStyleSheet()

• def setWindowModified()

• def setWindowTitle()

• def show()

• def showFullScreen()

• def showMaximized()

• def showMinimized()

• def showNormal()

• def update()

• def updateMicroFocus()

信号¶

• def customContextMenuRequested()

• def windowIconChanged()

• def windowIconTextChanged()

• def windowTitleChanged()

静态函数¶

• def createWindowContainer()

• def find()

• def keyboardGrabber()

• def mouseGrabber()

• def setTabOrder()

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

小部件是用户界面的基本单位：它接收来自窗口系统的鼠标、键盘和其他事件，并在屏幕上绘制自身的表示。每个小部件都是矩形的，并且它们按照Z顺序排列。一个小部件会被其父部件和前面的小部件裁剪。

未嵌入父部件中的部件称为窗口。通常，窗口具有框架和标题栏，尽管也可以使用适当的窗口标志创建没有此类装饰的窗口。在Qt中，QMainWindow和QDialog的各种子类是最常见的窗口类型。

每个小部件的构造函数接受一个或两个标准参数：

1. QWidget *parent = nullptr 是新窗口的父窗口。如果它是 None（默认值），新窗口将是一个独立窗口。如果不是，它将是 parent 的子窗口，并受 parent 的几何形状限制（除非你指定 Qt::Window 作为窗口标志）。

2. Qt::WindowFlags f = { }（在可用的情况下）设置窗口标志；默认值适用于大多数小部件，但要获得例如没有窗口系统框架的窗口，必须使用特殊标志。

QWidget 有许多成员函数，但其中一些几乎没有直接功能；例如，QWidget 有一个字体属性，但自己从不使用它。有许多子类提供了实际功能，例如 QLabel、QPushButton、QListWidget 和 QTabWidget。

顶级和小部件¶

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

非窗口小部件是子小部件，显示在其父小部件内。Qt中的大多数小部件主要作为子小部件使用。例如，可以将按钮显示为顶级窗口，但大多数人更喜欢将按钮放在其他小部件内，例如QDialog。

上图展示了一个QGroupBox小部件，用于在QGridLayout提供的布局中容纳各种子部件。QLabel子部件已被勾勒出来，以指示它们的完整大小。

如果你想使用QWidget来容纳子部件，通常你会想要在父QWidget中添加一个布局。更多信息请参见布局管理。

复合小部件¶

当一个小部件被用作容器来分组多个子部件时，它被称为复合小部件。这些可以通过构建具有所需视觉属性的小部件来创建 - 例如，一个QFrame - 并向其添加子部件，通常由布局管理。

复合小部件也可以通过子类化标准小部件来创建，例如QWidget或QFrame，并在子类的构造函数中添加必要的布局和子小部件。许多Qt提供的示例使用这种方法，Qt的小部件教程中也涵盖了这一点。

自定义小部件和绘画¶

由于QWidget是QPaintDevice的子类，子类可以用于显示使用QPainter类实例进行一系列绘制操作组成的自定义内容。这种方法与Graphics View Framework使用的画布风格方法形成对比，后者由应用程序将项目添加到场景中，并由框架本身进行渲染。

每个小部件都在其paintEvent()函数内执行所有绘画操作。每当小部件需要重新绘制时，无论是由于某些外部变化还是应用程序的请求，都会调用此函数。

模拟时钟示例展示了一个简单的小部件如何处理绘制事件。

大小提示和大小策略¶

在实现一个新部件时，几乎总是需要重新实现sizeHint()以为部件提供合理的默认大小，并使用setSizePolicy()设置正确的大小策略。

默认情况下，未提供大小提示的复合小部件将根据其子小部件的空间需求进行大小调整。

尺寸策略允许您为布局管理系统提供良好的默认行为，以便其他小部件可以轻松地包含和管理您的小部件。默认的尺寸策略表明，尺寸提示代表小部件的首选尺寸，这对于许多小部件来说通常已经足够好了。

注意

顶级小部件的大小被限制为桌面高度和宽度的2/3。如果这些限制不够，您可以手动resize()小部件。

事件¶

小部件响应通常由用户操作引起的事件。Qt通过调用特定的事件处理函数来向小部件传递事件，这些函数包含有关每个事件的QEvent子类实例。

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

Scribble示例实现了更广泛的事件集，用于处理鼠标移动、按钮按下和窗口调整大小。

您需要为您自己的小部件提供行为和内容，但这里简要概述了与QWidget相关的事件，从最常见的事件开始：

• paintEvent() 在小部件需要重新绘制时被调用。每个显示自定义内容的小部件都必须实现它。使用 QPainter 进行绘制只能在 paintEvent() 或由 paintEvent() 调用的函数中进行。

• resizeEvent() 在小部件调整大小时被调用。

• mousePressEvent() 当鼠标光标位于小部件内部时按下鼠标按钮，或者当小部件使用 grabMouse() 捕获鼠标时调用。按下鼠标而不释放它实际上与调用 grabMouse() 相同。

• mouseReleaseEvent() 在鼠标按钮释放时被调用。当小部件接收到相应的鼠标按下事件时，它会接收到鼠标释放事件。这意味着如果用户在你的小部件内按下鼠标，然后在释放鼠标按钮之前将鼠标拖动到其他地方，你的小部件将接收到释放事件。有一个例外：如果在按住鼠标按钮时出现弹出菜单，此弹出菜单会立即窃取鼠标事件。

• mouseDoubleClickEvent() 当用户在小部件中双击时被调用。如果用户双击，小部件会接收到一个鼠标按下事件、一个鼠标释放事件、（一个鼠标点击事件）、第二次鼠标按下、此事件以及最后的第二次鼠标释放事件。（如果在此操作过程中鼠标没有保持稳定，可能还会接收到一些鼠标移动事件。）在第二次点击到来之前，无法区分点击和双击。（这是大多数GUI书籍建议双击应作为单击的扩展，而不是触发不同操作的原因之一。）

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

• keyPressEvent() 在按下键时被调用，并且在键被按住足够长时间以自动重复时再次调用。Tab 和 Shift+Tab 键只有在未被焦点更改机制使用时才会传递给小部件。要强制这些键由您的小部件处理，您必须重新实现 event()。

• focusInEvent() 在小部件获得键盘焦点时被调用（假设你已经调用了 setFocusPolicy()）。行为良好的小部件会以清晰但不显眼的方式表明它们拥有键盘焦点。

• focusOutEvent() 在小部件失去键盘焦点时被调用。

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

• mouseMoveEvent() 在按住鼠标按钮的同时移动鼠标时被调用。这在拖放操作期间非常有用。如果你调用 setMouseTracking (true)，即使没有按住任何按钮，你也会收到鼠标移动事件。（另请参阅拖放指南。）

• keyReleaseEvent() 在每次释放按键时被调用，并且在按键被按住时（如果按键是自动重复的）也会被调用。在这种情况下，小部件将为每次重复接收一对按键释放和按键按下事件。Tab 和 Shift+Tab 键只有在未被焦点更改机制使用时才会传递给小部件。要强制这些键由您的小部件处理，您必须重新实现 event()。

• wheelEvent() 当用户在小部件获得焦点时转动鼠标滚轮时调用。

• enterEvent() 当鼠标进入小部件的屏幕空间时调用。（这不包括由小部件的任何子部件拥有的屏幕空间。）

• leaveEvent() 当鼠标离开小部件的屏幕空间时被调用。如果鼠标进入子小部件，不会触发 leaveEvent()。

• moveEvent() 在小部件相对于其父级移动时被调用。

• closeEvent() 在用户关闭小部件时（或当 close() 被调用时）被调用。

在QEvent::Type的文档中，还描述了一些相当晦涩的事件。要处理这些事件，你需要直接重新实现event()。

event() 的默认实现处理 Tab 和 Shift+Tab（用于移动键盘焦点），并将大多数其他事件传递给上面更专业的处理程序之一。

事件及其传递机制在事件系统中有所涵盖。

函数和属性组¶

上下文	函数和属性
窗口函数	show() , hide() , raise() , lower() , close() .
顶层窗口	windowModified , windowTitle , windowIcon , isActiveWindow , activateWindow() , minimized , showMinimized() , maximized , showMaximized() , fullScreen , showFullScreen() , showNormal() .
窗口内容	update() , repaint() , scroll() .
Geometry	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 handlers	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()

小部件样式表¶

除了每个平台的标准小部件样式外，小部件还可以根据样式表中指定的规则进行样式设置。此功能使您能够自定义特定小部件的外观，以向用户提供有关其用途的视觉提示。例如，可以以特定方式设置按钮的样式，以指示它执行破坏性操作。

小部件样式表的使用在Qt样式表文档中有更详细的描述。

透明度和双缓冲¶

QWidget 自动双缓冲其绘画，因此无需在 paintEvent() 中编写双缓冲代码以避免闪烁。

父窗口部件的内容默认会传播到它们的每个子窗口部件，只要没有设置Qt::WA_PaintOnScreen。自定义窗口部件可以通过更新不规则区域（以创建非矩形的子窗口部件）或使用具有不完全透明度的颜色进行绘制来利用此功能。下图显示了如何微调自定义窗口部件的属性和属性以实现不同的效果。

在上图中，构建了一个半透明的矩形子部件，并移除了一个区域，然后将其添加到父部件（一个显示位图的QLabel）中。接着，设置了不同的属性和部件属性以实现不同的效果：

• 左侧的小部件没有设置额外的属性或小部件属性。这种默认状态适合大多数具有透明度、形状不规则或未使用不透明画笔绘制整个区域的自定义小部件。

• 中心小部件设置了autoFillBackground属性。此属性用于依赖小部件提供默认背景的自定义小部件，并且不会使用不透明的画笔绘制整个区域。

• 右侧的小部件设置了Qt::WA_OpaquePaintEvent小部件属性。这表示小部件将使用不透明的颜色绘制其整个区域。小部件的区域最初将是未初始化的，在图中用红色对角线网格图案表示，该图案透过被覆盖的区域显现出来。

为了快速更新具有简单背景颜色的自定义小部件，例如实时绘图或图表小部件，最好定义一个合适的背景颜色（使用setBackgroundRole()与QPalette::Window角色），设置autoFillBackground属性，并且只在小部件的paintEvent()中实现必要的绘图功能。

为了快速更新自定义小部件，这些部件经常用不透明内容绘制其整个区域，例如视频流小部件，最好设置小部件的Qt::WA_OpaquePaintEvent，避免与重新绘制小部件背景相关的任何不必要开销。

如果一个小部件同时具有Qt::WA_OpaquePaintEvent小部件属性和autoFillBackground属性设置，则Qt::WA_OpaquePaintEvent属性优先。根据您的需求，您应该选择其中之一。

父部件的内容也会传播到标准的Qt部件。如果父部件以非标准方式装饰，这可能会导致一些意想不到的结果，如下图所示。

在不使用子类化的情况下，自定义标准Qt小部件的绘制行为的范围略小于自定义小部件。通常，可以通过设置其autoFillBackground属性来实现标准小部件的所需外观。

创建半透明窗口¶

你可以在支持合成的窗口系统上创建具有半透明区域的窗口。

要在顶级小部件中启用此功能，请使用setAttribute()设置其Qt::WA_TranslucentBackground属性，并确保在您希望部分透明的区域中使用非不透明颜色绘制其背景。

平台说明：

• X11: 此功能依赖于支持ARGB视觉效果的X服务器和合成窗口管理器的使用。

• Windows: 小部件需要设置Qt::FramelessWindowHint窗口标志才能使半透明效果生效。

• macOS：小部件需要设置Qt::FramelessWindowHint窗口标志才能使半透明效果生效。

原生小部件 vs 外来小部件¶

Alien widgets 是窗口系统未知的小部件。它们没有与之关联的原生窗口句柄。这一特性显著加快了小部件的绘制、调整大小，并消除了闪烁。

如果您需要原生窗口的旧行为，请选择以下选项之一：

1. 在你的环境中使用 QT_USE_NATIVE_WINDOWS=1。

2. 在您的应用程序上设置Qt::AA_NativeWindows属性。所有小部件都将是原生小部件。

3. 在部件上设置Qt::WA_NativeWindow属性：部件本身及其所有祖先将变为原生（除非设置了Qt::WA_DontCreateNativeAncestors）。

4. 调用 winId 以强制执行原生窗口（这意味着3）。

5. 设置Qt::WA_PaintOnScreen属性以强制使用原生窗口（这意味着3）。

另请参阅

QGridLayout QBoxLayout

class RenderFlag¶

(继承自 enum.Flag) 此枚举描述了在调用 render() 时如何渲染小部件。

常量	描述
QWidget.DrawWindowBackground	如果启用此选项，即使未设置autoFillBackground，小部件的背景也会渲染到目标中。默认情况下，此选项是启用的。
QWidget.DrawChildren	如果启用此选项，小部件的子部件将递归地渲染到目标中。默认情况下，此选项是启用的。
QWidget.IgnoreMask	如果启用此选项，渲染到目标时，小部件的mask()将被忽略。默认情况下，此选项是禁用的。

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property acceptDropsᅟ: bool¶

此属性保存此小部件是否启用了拖放事件。

将此属性设置为true，向系统宣布此小部件可能能够接受拖放事件。

如果小部件是桌面（windowType() == Qt::Desktop），如果另一个应用程序正在使用桌面，这可能会失败；你可以调用acceptDrops()来测试是否发生这种情况。

警告

不要在拖放事件处理程序中修改此属性。

默认情况下，此属性为 false。

另请参阅

拖拽 和 放置

Access functions:

• acceptDrops()

• setAcceptDrops()

property accessibleDescriptionᅟ: str¶

此属性保存辅助技术所看到的小部件描述。

小部件的可访问描述应传达小部件的功能。虽然accessibleName应该是一个简短且简洁的字符串（例如保存），但描述应提供更多上下文，例如保存当前文档。

此属性需要本地化。

默认情况下，此属性包含一个空字符串，Qt 会回退使用工具提示来提供此信息。

另请参阅

accessibleName text()

Access functions:

• accessibleDescription()

• setAccessibleDescription()

property accessibleNameᅟ: str¶

此属性保存辅助技术所看到的部件名称。

这是辅助技术（如屏幕阅读器）宣布此小部件时使用的主要名称。对于大多数小部件，不需要设置此属性。例如，对于QPushButton，按钮的文本将被使用。

当小部件不提供任何文本时，设置此属性非常重要。例如，仅包含图标的按钮需要设置此属性以与屏幕阅读器配合使用。名称应简短且等同于小部件传达的视觉信息。

此属性需要本地化。

默认情况下，此属性包含一个空字符串。

另请参阅

accessibleDescription text()

Access functions:

• accessibleName()

• setAccessibleName()

property autoFillBackgroundᅟ: bool¶

此属性用于确定是否自动填充小部件的背景。

如果启用，此属性将导致Qt在调用绘制事件之前填充小部件的背景。使用的颜色由小部件调色板中的QPalette::Window颜色角色定义。

此外，除非设置了WA_OpaquePaintEvent或WA_NoSystemBackground属性，否则窗口总是用QPalette::Window填充。

如果小部件的父级背景具有静态渐变，则无法关闭此属性（即设置为false）。

警告

在使用此属性时，请谨慎与Qt样式表结合使用。当小部件具有带有有效背景或边框图像的样式表时，此属性将自动禁用。

默认情况下，此属性为 false。

另请参阅

透明度 和 双缓冲

Access functions:

• autoFillBackground()

• setAutoFillBackground()

property baseSizeᅟ: QSize¶

此属性保存小部件的基本大小。

基础尺寸用于计算适当的小部件尺寸，如果小部件定义了sizeIncrement()。

默认情况下，对于新创建的小部件，此属性包含宽度和高度为零的大小。

另请参阅

setSizeIncrement()

Access functions:

• baseSize()

• setBaseSize()

property childrenRectᅟ: QRect¶

此属性保存小部件子项的边界矩形。

隐藏的子项被排除在外。

默认情况下，对于没有子部件的小部件，此属性包含一个宽度和高度为零的矩形，位于原点。

另请参阅

childrenRegion() geometry()

Access functions:

• childrenRect()

property childrenRegionᅟ: QRegion¶

此属性保存小部件的子项占用的组合区域。

隐藏的子项被排除在外。

默认情况下，对于没有子部件的小部件，此属性包含一个空区域。

另请参阅

childrenRect() geometry() mask()

Access functions:

• childrenRegion()

property contextMenuPolicyᅟ: Qt.ContextMenuPolicy¶

此属性控制小部件如何显示上下文菜单。

此属性的默认值为Qt::DefaultContextMenu，这意味着会调用contextMenuEvent()处理程序。其他值包括Qt::NoContextMenu、Qt::PreventContextMenu、Qt::ActionsContextMenu和Qt::CustomContextMenu。使用Qt::CustomContextMenu时，会发出信号customContextMenuRequested()。

另请参阅

contextMenuEvent() customContextMenuRequested() actions()

Access functions:

• contextMenuPolicy()

• setContextMenuPolicy()

property cursorᅟ: QCursor¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

此属性保存此小部件的光标形状。

当鼠标悬停在此小部件上时，鼠标光标将呈现此形状。请参阅预定义光标对象列表以获取一系列有用的形状。

一个编辑器小部件可能会使用I型光标：

setCursor(Qt.IBeamCursor)

如果没有设置光标，或者在调用unsetCursor()之后，将使用父级的光标。

默认情况下，此属性包含一个具有 Qt::ArrowCursor 形状的光标。

一些底层的窗口实现会在光标离开小部件时重置光标，即使鼠标被捕获。如果你想为所有小部件设置光标，即使是在窗口外部，请考虑使用QGuiApplication::setOverrideCursor()。

另请参阅

setOverrideCursor()

Access functions:

• cursor()

• setCursor()

• unsetCursor()

property enabledᅟ: bool¶

此属性表示小部件是否启用。

通常，启用的部件处理键盘和鼠标事件；禁用的部件则不处理。但QAbstractButton是一个例外。

一些部件在被禁用时会以不同的方式显示自己。例如，按钮可能会将其标签绘制为灰色。如果您的部件需要知道何时启用或禁用，您可以使用类型为QEvent::EnabledChange的changeEvent()。

禁用一个小部件会隐式禁用其所有子部件。启用则会相应地启用所有子部件，除非它们已被显式禁用。如果父部件保持禁用状态，则无法显式启用非窗口的子部件。

默认情况下，此属性为 true。

另请参阅

isEnabledTo() changeEvent()

Access functions:

• isEnabled()

• setEnabled()

property focusᅟ: bool¶

此属性指示此小部件（或其焦点代理）是否具有键盘输入焦点。

默认情况下，此属性为 false。

注意

获取小部件的此属性值实际上等同于检查focusWidget()是否引用该小部件。

另请参阅

setFocus() clearFocus() setFocusPolicy() focusWidget()

Access functions:

• hasFocus()

property focusPolicyᅟ: Qt.FocusPolicy¶

此属性控制小部件接受键盘焦点的方式。

如果小部件通过Tab键接受键盘焦点，则策略为Qt::TabFocus；如果小部件通过点击接受焦点，则策略为Qt::ClickFocus；如果两者都接受，则策略为Qt::StrongFocus；如果完全不接受焦点，则策略为Qt::NoFocus（默认）。

如果一个小部件处理键盘事件，您必须为其启用键盘焦点。这通常是在小部件的构造函数中完成的。例如，QLineEdit 构造函数会调用 setFocusPolicy(Qt::StrongFocus)。

如果小部件有一个焦点代理，那么焦点策略将传播到它。

另请参阅

focusInEvent() focusOutEvent() keyPressEvent() keyReleaseEvent() enabled

Access functions:

• focusPolicy()

• setFocusPolicy()

property fontᅟ: QFont¶

此属性保存当前为小部件设置的字体。

此属性描述了小部件请求的字体。该字体在小部件渲染标准组件时由其样式使用，并作为一种手段确保自定义小部件能够与原生平台的外观和感觉保持一致。通常，不同的平台或不同的样式会为应用程序定义不同的字体。

当你为一个小部件分配一个新字体时，该字体的属性会与小部件的默认字体结合，形成小部件的最终字体。你可以调用fontInfo()来获取小部件最终字体的副本。最终字体也用于初始化QPainter的字体。

默认值取决于系统环境。QApplication 维护一个系统/主题字体，作为所有小部件的默认字体。某些类型的小部件可能还有特殊的字体默认值。您还可以通过传递自定义字体和小部件名称到setFont() 来为小部件定义默认字体。最后，字体会与Qt的字体数据库进行匹配，以找到最佳匹配。

QWidget 将显式字体属性从父级传播到子级。如果您更改字体的特定属性并将该字体分配给小部件，则该属性将传播到该小部件的所有子级，覆盖该属性的任何系统默认值。请注意，默认情况下字体不会传播到窗口（参见 isWindow()），除非启用了 Qt::WA_WindowPropagation 属性。

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

当前的样式用于渲染所有标准Qt小部件的内容，可以自由选择使用小部件的字体，或在某些情况下忽略它（部分或完全）。特别是，某些样式如GTK样式、Mac样式和Windows Vista样式，会对小部件字体应用特殊修改，以匹配平台的本地外观和感觉。因此，为小部件的字体分配属性并不能保证会改变小部件的外观。相反，您可以选择应用styleSheet。

注意

如果在同一个部件上使用Qt样式表和setFont()，如果设置冲突，样式表将优先。

另请参阅

fontInfo() fontMetrics()

Access functions:

• font()

• setFont()

property frameGeometryᅟ: QRect¶

此属性保存小部件相对于其父级的几何形状，包括任何窗口框架。

请参阅Window Geometry文档以了解窗口几何问题的概述。

默认情况下，此属性包含的值取决于用户的平台和屏幕几何形状。

另请参阅

geometry() x() y() pos()

Access functions:

• frameGeometry()

property frameSizeᅟ: QSize¶

此属性保存包括任何窗口框架在内的小部件的大小。

默认情况下，此属性包含一个取决于用户平台和屏幕几何形状的值。

Access functions:

• frameSize()

property fullScreenᅟ: bool¶

此属性表示小部件是否以全屏模式显示。

全屏模式下的小部件占据整个屏幕区域，并且不显示窗口装饰，例如标题栏。

默认情况下，此属性为 false。

另请参阅

windowState() 最小化 最大化

Access functions:

• isFullScreen()

property geometryᅟ: QRect¶

此属性保存小部件相对于其父部件的几何形状，不包括窗口框架。

当改变几何形状时，如果小部件可见，它会立即接收到一个移动事件（moveEvent()）和/或一个调整大小事件（resizeEvent()）。如果小部件当前不可见，它保证在显示之前会接收到适当的事件。

如果大小组件超出由minimumSize()和maximumSize()定义的范围，则会进行调整。

警告

在resizeEvent()或moveEvent()内部调用setGeometry()可能导致无限递归。

请参阅Window Geometry文档以了解窗口几何问题的概述。

默认情况下，此属性包含一个取决于用户平台和屏幕几何形状的值。

另请参阅

frameGeometry() rect() move() resize() moveEvent() resizeEvent() minimumSize() maximumSize()

Access functions:

• geometry()

• setGeometry()

property heightᅟ: int¶

此属性保存小部件的高度，不包括任何窗口框架。

请参阅Window Geometry文档以了解窗口几何问题的概述。

默认情况下，此属性包含一个取决于用户平台和屏幕几何形状的值。

另请参阅

geometry width size

访问函数：

property inputMethodHintsᅟ: Combination of Qt.InputMethodHint¶

此属性保存小部件具有的特定输入法提示。

这仅与输入小部件相关。它被输入方法用来获取关于输入方法应如何操作的提示。例如，如果设置了Qt::ImhFormattedNumbersOnly标志，输入方法可能会更改其视觉组件以反映只能输入数字。

警告

某些小部件需要特定的标志才能按预期工作。要设置标志，请执行w->setInputMethodHints(w->inputMethodHints()|f)而不是w->setInputMethodHints(f)。

注意

标志只是提示，因此特定的输入方法实现可以自由忽略它们。如果您想确保输入某种类型的字符，您还应该在部件上设置一个QValidator。

默认值为 Qt::ImhNone。

另请参阅

inputMethodQuery()

Access functions:

• inputMethodHints()

• setInputMethodHints()

property isActiveWindowᅟ: bool¶

此属性指示此小部件的窗口是否为活动窗口。

活动窗口是包含具有键盘焦点的小部件的窗口（如果窗口没有小部件或其小部件不接受键盘焦点，则窗口可能仍然具有焦点）。

当弹出窗口可见时，此属性对于活动窗口和弹出窗口都是true。

默认情况下，此属性为 false。

另请参阅

activateWindow() activeWindow()

Access functions:

• isActiveWindow()

property layoutDirectionᅟ: Qt.LayoutDirection¶

此属性保存此小部件的布局方向。

注意

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

默认情况下，此属性设置为 Qt::LeftToRight。

当在小部件上设置布局方向时，它将传播到小部件的子部件，但不会传播到作为窗口的子部件，也不会传播到已显式调用setLayoutDirection()的子部件。此外，在父部件调用setLayoutDirection()之后添加的子部件不会继承父部件的布局方向。

另请参阅

layoutDirection

Access functions:

• layoutDirection()

• setLayoutDirection()

• unsetLayoutDirection()

property localeᅟ: QLocale¶

此属性保存小部件的区域设置。

只要没有设置特殊的区域设置，这要么是父级的区域设置，要么（如果此小部件是顶级小部件）是默认的区域设置。

如果小部件显示日期或数字，这些应使用小部件的区域设置进行格式化。

另请参阅

setDefault()

Access functions:

• locale()

• setLocale()

• unsetLocale()

property maximizedᅟ: bool¶

此属性表示此小部件是否已最大化。

此属性仅与窗口相关。

注意

由于某些窗口系统的限制，这并不总是报告预期的结果（例如，如果用户在X11上通过窗口管理器最大化窗口，Qt无法将此与其他调整大小操作区分开来）。随着窗口管理器协议的发展，预计这种情况会有所改善。

默认情况下，此属性为 false。

另请参阅

windowState() showMaximized() visible show() hide() showNormal() minimized

Access functions:

• isMaximized()

property maximumHeightᅟ: int¶

此属性保存小部件的最大高度（以像素为单位）。

此属性对应于maximumSize属性所持有的高度。

默认情况下，此属性包含的值为16777215。

注意

QWIDGETSIZE_MAX 宏的定义限制了小部件的最大尺寸。

另请参阅

maximumSize maximumWidth

Access functions:

• maximumHeight()

• setMaximumHeight()

property maximumSizeᅟ: QSize¶

此属性保存小部件的最大大小（以像素为单位）。

小部件无法调整到大于最大小部件尺寸的大小。

默认情况下，此属性包含一个宽度和高度值均为16777215的大小。

注意

QWIDGETSIZE_MAX 宏的定义限制了小部件的最大尺寸。

另请参阅

maximumWidth maximumHeight minimumSize sizeIncrement

Access functions:

• maximumSize()

• setMaximumSize()

property maximumWidthᅟ: int¶

此属性保存小部件的最大宽度（以像素为单位）。

此属性对应于由maximumSize属性持有的宽度。

默认情况下，此属性包含的值为16777215。

注意

QWIDGETSIZE_MAX 宏的定义限制了小部件的最大尺寸。

另请参阅

maximumSize maximumHeight

Access functions:

• maximumWidth()

• setMaximumWidth()

property minimizedᅟ: bool¶

此属性表示此小部件是否已最小化（图标化）。

此属性仅与窗口相关。

默认情况下，此属性为 false。

另请参阅

showMinimized() visible show() hide() showNormal() maximized

Access functions:

• isMinimized()

property minimumHeightᅟ: int¶

此属性保存小部件的最小高度（以像素为单位）。

此属性对应于minimumSize属性所持有的高度。

默认情况下，此属性的值为0。

另请参阅

minimumSize minimumWidth

Access functions:

• minimumHeight()

• setMinimumHeight()

property minimumSizeᅟ: QSize¶

此属性保存小部件的最小尺寸。

小部件无法调整到比最小小部件尺寸更小的尺寸。如果当前尺寸小于最小尺寸，小部件的尺寸将被强制调整为最小尺寸。

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

默认情况下，此属性包含宽度和高度为零的大小。

另请参阅

minimumWidth minimumHeight maximumSize sizeIncrement

Access functions:

• minimumSize()

• setMinimumSize()

property minimumSizeHintᅟ: QSize¶

此属性保存小部件推荐的最小尺寸。

如果此属性的值是无效的大小，则不推荐最小大小。

如果没有为此小部件设置布局，minimumSizeHint() 的默认实现将返回一个无效的大小，否则返回布局的最小大小。大多数内置小部件会重新实现 minimumSizeHint()。

QLayout 永远不会将小部件调整到小于最小尺寸提示的大小，除非设置了 minimumSize() 或者尺寸策略设置为 QSizePolicy::Ignore。如果设置了 minimumSize()，最小尺寸提示将被忽略。

另请参阅

resize() setMinimumSize() sizePolicy()

Access functions:

• minimumSizeHint()

property minimumWidthᅟ: int¶

此属性保存小部件的最小宽度（以像素为单位）。

此属性对应于由minimumSize属性持有的宽度。

默认情况下，此属性的值为0。

另请参阅

minimumSize minimumHeight

Access functions:

• minimumWidth()

• setMinimumWidth()

property modalᅟ: bool¶

此属性表示该小部件是否为模态小部件。

此属性仅对窗口有意义。模态小部件会阻止所有其他窗口中的小部件获取任何输入。

默认情况下，此属性为 false。

另请参阅

isWindow() windowModality QDialog

Access functions:

• isModal()

property mouseTrackingᅟ: bool¶

此属性表示是否为小部件启用了鼠标跟踪。

如果鼠标跟踪被禁用（默认情况下），当移动鼠标时至少有一个鼠标按钮被按下时，小部件才会接收到鼠标移动事件。

如果启用了鼠标跟踪，即使没有按下任何按钮，小部件也会接收到鼠标移动事件。

另请参阅

mouseMoveEvent()

Access functions:

• hasMouseTracking()

• setMouseTracking()

property normalGeometryᅟ: QRect¶

此属性保存小部件在显示为普通（非最大化或全屏）顶层小部件时的几何形状。

如果小部件已经处于此状态，正常几何形状将反映小部件的当前geometry()。

对于子部件，此属性始终持有一个空矩形。

默认情况下，此属性包含一个空矩形。

另请参阅

windowState() geometry

Access functions:

• normalGeometry()

property paletteᅟ: QPalette¶

此属性保存小部件的调色板。

此属性描述了小部件的调色板。调色板由小部件的样式在渲染标准组件时使用，并作为一种手段来确保自定义小部件能够与原生平台的外观和感觉保持一致。通常，不同的平台或不同的样式具有不同的调色板。

当你为一个小部件分配一个新的调色板时，这个调色板的颜色角色会与小部件的默认调色板结合，形成小部件的最终调色板。小部件的背景角色调色板条目用于填充小部件的背景（参见autoFillBackground），而前景角色则初始化QPainter的画笔。

默认值取决于系统环境。QApplication 维护一个系统/主题调色板，作为所有小部件的默认值。某些类型的小部件可能还有特殊的调色板默认值（例如，在Windows Vista上，所有从QMenuBar派生的类都有一个特殊的默认调色板）。您还可以通过传递自定义调色板和小部件的名称到setPalette()来为小部件定义默认调色板。最后，样式在分配调色板时总是可以选择对其进行修饰（参见polish()）。

QWidget 将显式的调色板角色从父级传播到子级。如果你为调色板上的特定角色分配了画笔或颜色，并将该调色板分配给一个小部件，那么该角色将传播到该小部件的所有子级，覆盖该角色的任何系统默认值。请注意，默认情况下，调色板不会传播到窗口（参见 isWindow()），除非启用了 Qt::WA_WindowPropagation 属性。

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

当前的样式用于渲染所有标准Qt小部件的内容，可以自由选择小部件调色板中的颜色和画笔，或者在某些情况下忽略调色板（部分或完全）。特别是，某些样式如GTK样式、Mac样式和Windows Vista样式，依赖于第三方API来渲染小部件的内容，这些样式通常不遵循调色板。因此，为小部件的调色板分配角色并不能保证改变小部件的外观。相反，您可以选择应用styleSheet。

警告

不要将此函数与Qt样式表一起使用。使用样式表时，可以使用“color”、“background-color”、“selection-color”、“selection-background-color”和“alternate-background-color”来自定义小部件的调色板。

另请参阅

font() Qt 样式表

Access functions:

• palette()

• setPalette()

property posᅟ: QPoint¶

此属性保存小部件在其父小部件中的位置。

如果小部件是一个窗口，位置是小部件在桌面上的位置，包括其框架。

当改变位置时，如果小部件可见，它会立即接收到一个移动事件（moveEvent()）。如果小部件当前不可见，它保证在显示之前会接收到一个事件。

默认情况下，此属性包含一个指向原点的位置。

警告

在moveEvent()内部调用move()或setGeometry()可能导致无限递归。

请参阅Window Geometry文档以了解窗口几何问题的概述。

注意

并非所有的窗口系统都支持设置或查询顶层窗口的位置。在这样的系统上，以编程方式移动窗口可能没有任何效果，并且可能会返回当前位置的人工值，例如QPoint(0, 0)。

另请参阅

frameGeometry size x() y()

Access functions:

• pos()

• move()

property rectᅟ: QRect¶

此属性保存小部件的内部几何形状，不包括任何窗口框架。

rect 属性等于 QRect(0, 0, width() , height() ).

请参阅Window Geometry文档以了解窗口几何问题的概述。

默认情况下，此属性包含一个取决于用户平台和屏幕几何形状的值。

另请参阅

size

Access functions:

• rect()

property sizeᅟ: QSize¶

此属性保存小部件的大小，不包括任何窗口框架。

如果小部件在调整大小时可见，它会立即接收到一个调整大小事件（resizeEvent()）。如果小部件当前不可见，它保证在显示之前会接收到一个事件。

如果大小超出由minimumSize()和maximumSize()定义的范围，则会进行调整。

默认情况下，此属性包含一个取决于用户平台和屏幕几何形状的值。

警告

在resizeEvent()内部调用resize()或setGeometry()可能导致无限递归。

注意

将大小设置为QSize(0, 0)将导致小部件不在屏幕上显示。这也适用于窗口。

另请参阅

pos geometry minimumSize maximumSize resizeEvent() adjustSize()

Access functions:

• size()

• resize()

property sizeHintᅟ: QSize¶

此属性保存小部件的推荐大小。

如果此属性的值是无效的大小，则不推荐任何大小。

如果没有为此小部件设置布局，sizeHint() 的默认实现将返回一个无效的大小，否则返回布局的首选大小。

另请参阅

minimumSizeHint() sizePolicy() setMinimumSize() updateGeometry()

Access functions:

• sizeHint()

property sizeIncrementᅟ: QSize¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

此属性保存小部件的大小增量。

当用户调整窗口大小时，大小将以sizeIncrement()的步长移动。width()像素水平移动，sizeIncrement.height()像素垂直移动，以baseSize()为基础。首选小部件大小适用于非负整数i和j：

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

请注意，虽然你可以为所有小部件设置大小增量，但它只影响窗口。

默认情况下，此属性包含宽度和高度为零的大小。

警告

在Windows下，大小增量没有效果，并且在X11上可能会被窗口管理器忽略。

另请参阅

size minimumSize maximumSize

Access functions:

• sizeIncrement()

• setSizeIncrement()

property sizePolicyᅟ: QSizePolicy¶

此属性保存小部件的默认布局行为。

如果有一个QLayout管理此小部件的子部件，则使用该布局指定的大小策略。如果没有这样的QLayout，则使用此函数的结果。

默认策略是Preferred/Preferred，这意味着小部件可以自由调整大小，但更倾向于sizeHint()返回的大小。按钮类小部件设置大小策略以指定它们可以水平拉伸，但垂直方向是固定的。同样适用于行编辑控件（如QLineEdit、QSpinBox或可编辑的QComboBox）和其他水平方向的小部件（如QProgressBar）。QToolButton通常是方形的，因此它们允许在两个方向上增长。支持不同方向的小部件（如QSlider、QScrollBar或QHeader）仅在相应方向上指定拉伸。可以提供滚动条的小部件（通常是QScrollArea的子类）倾向于指定它们可以使用额外的空间，并且它们可以在小于sizeHint()的情况下工作。

另请参阅

sizeHint() QLayout QSizePolicy updateGeometry()

Access functions:

• sizePolicy()

• setSizePolicy()

property statusTipᅟ: str¶

此属性保存小部件的状态提示。

默认情况下，此属性包含一个空字符串。

另请参阅

toolTip whatsThis

Access functions:

• statusTip()

• setStatusTip()

property styleSheetᅟ: str¶

此属性保存小部件的样式表。

样式表包含对部件样式的自定义的文本描述，如Qt样式表文档中所述。

自 Qt 4.5 起，Qt 样式表完全支持 macOS。

警告

目前不支持为自定义的QStyle子类使用Qt样式表。我们计划在未来的某个版本中解决这个问题。

另请参阅

setStyle() styleSheet Qt样式表

Access functions:

• styleSheet()

• setStyleSheet()

property tabletTrackingᅟ: bool¶

此属性表示是否为小部件启用了平板跟踪。

如果平板跟踪被禁用（默认情况下），当触控笔与平板接触时，或者至少有一个触控笔按钮被按下时，小部件仅接收平板移动事件，同时触控笔正在移动。

如果启用了平板跟踪，即使悬停在附近，小部件也会接收到平板移动事件。这对于监控位置以及旋转和倾斜等辅助属性非常有用，并在用户界面中提供反馈。

另请参阅

tabletEvent()

Access functions:

• hasTabletTracking()

• setTabletTracking()

property toolTipᅟ: str¶

此属性保存小部件的工具提示。

请注意，默认情况下，工具提示仅显示为活动窗口的子部件。您可以通过在窗口上设置属性Qt::WA_AlwaysShowToolTips来更改此行为，而不是在带有工具提示的部件上设置。

如果你想控制工具提示的行为，你可以拦截event()函数并捕获QEvent::ToolTip事件（例如，如果你想自定义工具提示应显示的区域）。

默认情况下，此属性包含一个空字符串。

另请参阅

QToolTip statusTip whatsThis

Access functions:

• toolTip()

• setToolTip()

property toolTipDurationᅟ: int¶

此属性保存小部件的工具提示持续时间。

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

另请参阅

toolTip

Access functions:

• toolTipDuration()

• setToolTipDuration()

property updatesEnabledᅟ: bool¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

此属性表示是否启用了更新。

启用了更新的小部件会接收绘制事件并具有系统背景；禁用的小部件则不会。这也意味着如果更新被禁用，调用update()和repaint()将无效。

默认情况下，此属性为 true。

setUpdatesEnabled() 通常用于在短时间内禁用更新，例如为了避免在大规模更改期间出现屏幕闪烁。在 Qt 中，小部件通常不会产生屏幕闪烁，但在 X11 上，当小部件在隐藏之前被其他小部件替换时，服务器可能会擦除屏幕上的区域。禁用更新可以解决这个问题。

示例：

setUpdatesEnabled(False)
bigVisualChanges()
setUpdatesEnabled(True)

禁用一个小部件会隐式禁用其所有子部件。启用一个小部件会启用所有子部件除了顶级部件或那些已被显式禁用的部件。重新启用会隐式调用update()函数来更新小部件。

另请参阅

paintEvent()

Access functions:

• updatesEnabled()

• setUpdatesEnabled()

property visibleᅟ: bool¶

此属性表示小部件是否可见。

调用 setVisible(true) 或 show() 将小部件设置为可见状态，前提是其所有父部件直到窗口都是可见的。如果某个祖先不可见，则小部件在所有祖先都显示之前不会变为可见。如果其大小或位置已更改，Qt 保证小部件在显示之前会收到移动和调整大小事件。如果小部件尚未调整大小，Qt 将使用 adjustSize() 将小部件的大小调整为有用的默认值。

调用 setVisible(false) 或 hide() 会显式隐藏一个小部件。显式隐藏的小部件将永远不会变为可见，即使其所有祖先变为可见，除非你显示它。

当小部件的可见性状态发生变化时，它会接收到显示和隐藏事件。在隐藏和显示事件之间，没有必要浪费CPU周期来准备或向用户显示信息。例如，视频应用程序可能只是停止生成新帧。

一个被屏幕上其他窗口遮挡的小部件仍然被认为是可见的。这同样适用于图标化的窗口和存在于另一个虚拟桌面上的窗口（在支持此概念的平台上）。当窗口系统改变其映射状态时，小部件会接收到自发的显示和隐藏事件，例如，当用户最小化窗口时，会接收到自发的隐藏事件，当窗口再次恢复时，会接收到自发的显示事件。

你很少需要重新实现setVisible()函数。如果你需要在显示小部件之前更改一些设置，请使用showEvent()。如果你需要进行一些延迟初始化，请使用传递给event()函数的Polish事件。

另请参阅

show() hide() isHidden() isVisibleTo() isMinimized() showEvent() hideEvent()

Access functions:

• isVisible()

• setVisible()

property whatsThisᅟ: str¶

此属性保存小部件的“这是什么”帮助文本。

默认情况下，此属性包含一个空字符串。

另请参阅

QWhatsThis toolTip statusTip

Access functions:

• whatsThis()

• setWhatsThis()

property widthᅟ: int¶

此属性保存小部件的宽度，不包括任何窗口框架。

请参阅Window Geometry文档以了解窗口几何问题的概述。

注意

不要使用此函数来查找多屏幕桌面上的屏幕宽度。详情请参见QScreen。

默认情况下，此属性包含一个取决于用户平台和屏幕几何形状的值。

另请参阅

geometry height size

访问函数：

property windowFilePathᅟ: str¶

此属性保存与部件关联的文件路径。

此属性仅对窗口有意义。它将文件路径与窗口关联。如果您设置了文件路径，但未设置窗口标题，Qt 会将窗口标题设置为指定路径的文件名，该文件名通过 QFileInfo::fileName() 获取。

如果在任何时候设置了窗口标题，则窗口标题将优先显示，而不是文件路径字符串。

此外，在macOS上，这还有一个额外的好处，即假设文件路径存在，它会为窗口设置代理图标。

如果没有设置文件路径，此属性包含一个空字符串。

默认情况下，此属性包含一个空字符串。

另请参阅

windowTitle windowIcon

Access functions:

• windowFilePath()

• setWindowFilePath()

property windowIconᅟ: QIcon¶

此属性保存小部件的图标。

此属性仅对窗口有意义。如果未设置图标，windowIcon() 将返回应用程序图标（QApplication::windowIcon()）。

注意

在macOS上，窗口图标代表活动文档，除非还使用setWindowFilePath设置了文件路径，否则不会显示。

另请参阅

windowTitle setWindowFilePath

Access functions:

• windowIcon()

• setWindowIcon()

• 信号 windowIconChanged()

property windowIconTextᅟ: str¶

此属性保存要在最小化窗口图标上显示的文本。

此属性仅对窗口有意义。如果未设置图标文本，此访问器将返回一个空字符串。它仅在X11平台上实现，并且只有某些窗口管理器使用此窗口属性。

此属性已弃用。

另请参阅

windowIcon windowTitle

Access functions:

• windowIconText()

• setWindowIconText()

• 信号 windowIconTextChanged()

property windowModalityᅟ: Qt.WindowModality¶

此属性保存被模态小部件阻止的窗口。

此属性仅对窗口有意义。模态小部件会阻止其他窗口中的小部件获取输入。此属性的值控制当小部件可见时哪些窗口被阻止。在窗口可见时更改此属性无效；您必须先hide()小部件，然后再show()它。

默认情况下，此属性为 Qt::NonModal。

另请参阅

isWindow() modal QDialog

Access functions:

• windowModality()

• setWindowModality()

property windowModifiedᅟ: bool¶

此属性表示窗口中显示的文档是否有未保存的更改。

修改后的窗口是指内容已更改但尚未保存到磁盘的窗口。此标志将根据平台产生不同的效果。在macOS上，关闭按钮将具有修改后的外观；在其他平台上，窗口标题将带有‘*’（星号）。

窗口标题必须包含一个“[＊]”占位符，它指示“＊”应该出现的位置。通常，它应该出现在文件名之后（例如，“document1.txt[＊] - 文本编辑器”）。如果窗口未被修改，占位符将被简单地移除。

请注意，如果一个小部件被设置为已修改，其所有祖先也将被设置为已修改。然而，如果你在一个小部件上调用setWindowModified(false)，这不会传播到其父部件，因为父部件的其他子部件可能已被修改。

另请参阅

windowTitle

Access functions:

• isWindowModified()

• setWindowModified()

property windowOpacityᅟ: float¶

此属性保存窗口的不透明度级别。

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

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

此功能可在支持Composite扩展的嵌入式Linux、macOS、Windows和X11平台上使用。

注意

在X11上，您需要运行一个复合管理器，并且您使用的窗口管理器需要支持X11特定的_NET_WM_WINDOW_OPACITY原子。

警告

将此属性从不透明更改为透明可能会发出一个需要在窗口正确显示之前处理的绘制事件。这主要影响QScreen::grabWindow()的使用。还要注意，半透明窗口的更新和调整大小速度明显比不透明窗口慢。

另请参阅

setMask()

Access functions:

• windowOpacity()

• setWindowOpacity()

property windowTitleᅟ: str¶

此属性保存窗口标题（标题）。

此属性仅对顶级小部件（如窗口和对话框）有意义。如果未设置标题，则标题基于windowFilePath。如果这两者都未设置，则标题为空字符串。

如果您使用windowModified机制，窗口标题必须包含一个“[＊]”占位符，该占位符指示“＊”应出现的位置。通常，它应出现在文件名之后（例如，“document1.txt[＊] - 文本编辑器”）。如果windowModified属性为false（默认值），则占位符将被简单地移除。

在某些桌面平台（包括Windows和Unix），如果设置了应用程序名称（来自QGuiApplication::applicationDisplayName），它会被添加到窗口标题的末尾。这是由QPA插件完成的，因此它会显示给用户，但不是windowTitle字符串的一部分。

另请参阅

windowIcon windowModified windowFilePath

Access functions:

• windowTitle()

• setWindowTitle()

• 信号 windowTitleChanged()

property xᅟ: int¶

此属性保存小部件相对于其父级的x坐标，包括任何窗口框架。

请参阅Window Geometry文档以了解窗口几何问题的概述。

默认情况下，此属性的值为0。

另请参阅

frameGeometry y pos

Access functions:

• x()

property yᅟ: int¶

此属性保存小部件相对于其父级的 y 坐标，包括任何窗口框架。

请参阅Window Geometry文档以了解窗口几何问题的概述。

默认情况下，此属性的值为0。

另请参阅

frameGeometry x pos

Access functions:

• y()

__init__([parent=None[, f=Qt.WindowFlags()]])¶

Parameters:

• parent – QWidget

• f – WindowType 的组合

构造一个作为parent子部件的小部件，小部件标志设置为f。

如果 parent 是 None，新部件将成为一个窗口。如果 parent 是另一个部件，这个部件将成为 parent 内的子窗口。当 parent 被删除时，新部件也会被删除。

小部件的标志参数，f，通常为0，但可以设置为自定义窗口的框架（即parent必须为None）。要自定义框架，请使用由任何窗口标志的按位或组成的值。

如果您将一个子部件添加到一个已经可见的部件中，您必须明确显示该子部件以使其可见。

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

另请参阅

windowFlags

acceptDrops()¶

Return type:

布尔

另请参阅

setAcceptDrops()

属性 acceptDropsᅟ 的获取器。

accessibleDescription()¶

Return type:

字符串

另请参阅

setAccessibleDescription()

属性 accessibleDescriptionᅟ 的获取器。

accessibleName()¶

Return type:

字符串

另请参阅

setAccessibleName()

属性 accessibleNameᅟ 的获取器。

actionEvent(event)¶

Parameters:

事件 – QActionEvent

每当小部件的操作发生变化时，都会使用给定的event调用此事件处理程序。

另请参阅

addAction() insertAction() removeAction() actions() QActionEvent

actions()¶

Return type:

QAction的列表

返回此小部件的（可能为空的）操作列表。

另请参阅

contextMenuPolicy insertAction() removeAction()

activateWindow()¶

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

活动窗口是一个可见的顶层窗口，具有键盘输入焦点。

此函数执行与在顶层窗口的标题栏上点击鼠标相同的操作。在X11上，结果取决于窗口管理器。如果您希望确保窗口也堆叠在顶部，您还应调用raise()。请注意，窗口必须是可见的，否则activateWindow()将无效。

在Windows上，如果应用程序当前不是活动窗口时调用此函数，它不会使该窗口成为活动窗口。它会改变任务栏条目的颜色，以指示窗口以某种方式发生了变化。这是因为微软不允许应用程序中断用户当前在另一个应用程序中的操作。

另请参阅

isActiveWindow() window() show()

addAction(action)¶

Parameters:

动作 – QAction

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

所有QWidget都有一个QActions列表。然而，它们可以通过许多不同的方式以图形方式表示。QAction列表的默认用途（由actions()返回）是创建一个上下文QMenu。

一个 QWidget 应该只拥有每个动作的一个实例，添加一个已经存在的动作不会导致该动作在部件中出现两次。

action 的所有权不会转移给这个 QWidget。

另请参阅

removeAction() insertAction() actions() QMenu

addAction(text)

Parameters:

文本 – str

Return type:

QAction

addAction(text, callable)

Parameters:

• 文本 – str

• callable – 对象

Return type:

QAction

addAction(icon, text)

Parameters:

• 图标 – QIcon

• 文本 – str

Return type:

QAction

addAction(text, shortcut)

Parameters:

• 文本 – str

• 快捷键 – QKeySequence

Return type:

QAction

addAction(icon, text, callable)

Parameters:

• 图标 – QIcon

• 文本 – str

• callable – 对象

Return type:

QAction

addAction(text, shortcut, callable)

Parameters:

• 文本 – str

• 快捷键 – QKeySequence

• callable – 对象

Return type:

QAction

addAction(icon, text, shortcut)

Parameters:

• 图标 – QIcon

• 文本 – str

• 快捷键 – QKeySequence

Return type:

QAction

addAction(icon, text, shortcut, callable)

Parameters:

• 图标 – QIcon

• 文本 – str

• 快捷键 – QKeySequence

• callable – 对象

Return type:

QAction

addAction(text, receiver, member[, type=Qt.AutoConnection])

Parameters:

• 文本 – str

• receiver – QObject

• member – str

• type – ConnectionType

Return type:

QAction

addAction(icon, text, receiver, member[, type=Qt.AutoConnection])

Parameters:

• 图标 – QIcon

• 文本 – str

• receiver – QObject

• member – str

• type – ConnectionType

Return type:

QAction

addAction(text, shortcut, receiver, member[, type=Qt.AutoConnection])

Parameters:

• 文本 – str

• 快捷键 – QKeySequence

• receiver – QObject

• member – str

• type – ConnectionType

Return type:

QAction

addAction(icon, text, shortcut, receiver, member[, type=Qt.AutoConnection])

Parameters:

• 图标 – QIcon

• 文本 – str

• 快捷键 – QKeySequence

• receiver – QObject

• member – str

• type – ConnectionType

Return type:

QAction

addActions(actions)¶

Parameters:

actions – QAction 的列表

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

另请参阅

removeAction() QMenu addAction()

adjustSize()¶

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

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

对于Windows，屏幕尺寸也会被考虑在内。如果sizeHint()小于(200, 100)并且大小策略是expanding，窗口将至少为(200, 100)。窗口的最大尺寸为屏幕宽度和高度的2/3。

另请参阅

sizeHint() childrenRect()

autoFillBackground()¶

Return type:

布尔

另请参阅

setAutoFillBackground()

属性 autoFillBackgroundᅟ 的获取器。

backgroundRole()¶

Return type:

ColorRole

返回小部件的背景角色。

背景角色定义了用于渲染背景的小部件的调色板中的画笔。

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

另请参阅

setBackgroundRole() foregroundRole()

backingStore()¶

Return type:

QBackingStore

返回此小部件将被绘制到的QBackingStore。

baseSize()¶

Return type:

QSize

另请参阅

setBaseSize()

属性 baseSizeᅟ 的获取器。

changeEvent(event)¶

Parameters:

事件 – QEvent

可以重新实现此事件处理程序以处理状态更改。

在此事件中更改的状态可以通过提供的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。

childAt(p)¶

Parameters:

p – QPoint

Return type:

QWidget

这是一个重载函数。

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

childAt(p)

Parameters:

p – QPointF

Return type:

QWidget

这是一个重载函数。

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

childAt(x, y)

Parameters:

• x – 整数

• y – 整数

Return type:

QWidget

返回在部件坐标系中位置 (x, y) 处的可见子部件。如果在指定位置没有可见的子部件，函数将返回 None。

childrenRect()¶

Return type:

QRect

属性 childrenRectᅟ 的获取器。

childrenRegion()¶

Return type:

QRegion

属性 childrenRegionᅟ 的获取器。

clearFocus()¶

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

如果小部件具有活动焦点，则会向该小部件发送一个focus out event，以告知它已失去焦点。

此小部件必须启用焦点设置以获取键盘输入焦点；也就是说，它必须调用setFocusPolicy()。

另请参阅

hasFocus() setFocus() focusInEvent() focusOutEvent() setFocusPolicy() focusWidget()

clearMask()¶

移除由setMask()设置的任何掩码。

另请参阅

setMask()

close()¶

Return type:

布尔

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

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

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

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

closeEvent(event)¶

Parameters:

事件 – QCloseEvent

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

默认情况下，事件被接受并且小部件被关闭。您可以重新实现此函数以更改小部件响应窗口关闭请求的方式。例如，您可以通过在所有事件上调用ignore()来防止窗口关闭。

主窗口应用程序通常使用此函数的重新实现来检查用户的工作是否已保存，并在关闭前请求许可。

另请参阅

event() hide() close() QCloseEvent

contentsMargins()¶

Return type:

QMargins

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

另请参阅

setContentsMargins() contentsRect()

contentsRect()¶

Return type:

QRect

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

另请参阅

setContentsMargins() contentsMargins()

contextMenuEvent(event)¶

Parameters:

事件 – QContextMenuEvent

此事件处理程序，用于事件 event，可以在子类中重新实现以接收小部件上下文菜单事件。

当小部件的contextMenuPolicy为Qt::DefaultContextMenu时，将调用此处理程序。

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

另请参阅

event() customContextMenuRequested()

contextMenuPolicy()¶

Return type:

ContextMenuPolicy

另请参阅

setContextMenuPolicy()

属性 contextMenuPolicyᅟ 的获取器。

create([window=0[, initializeWindow=true[, destroyOldWindow=true]]])¶

Parameters:

• window – WId

• initializeWindow – 布尔值

• destroyOldWindow – 布尔值

创建一个新的小部件窗口。

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

另请参阅

createWindowContainer() fromWinId()

createWinId()¶

static createWindowContainer(window[, parent=None[, flags=Qt.WindowFlags()]])¶

Parameters:

• 窗口 – QWindow

• parent – QWidget

• flags – WindowType 的组合

Return type:

QWidget

创建一个QWidget，使得可以将window嵌入到基于QWidget的应用程序中。

窗口容器被创建为parent的子元素，并使用窗口标志flags。

一旦窗口被嵌入到容器中，容器将控制窗口的几何形状和可见性。不建议在嵌入的窗口上显式调用QWindow::setGeometry()、QWindow::show()或QWindow::hide()。

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

窗口容器作为本地子窗口附加到其所属的顶级窗口。当窗口容器用作QAbstractScrollArea或QMdiArea的子窗口时，它将为其父链中的每个小部件创建一个本地 窗口，以便在此使用情况下实现正确的堆叠和裁剪。为窗口容器创建本地窗口也允许实现正确的堆叠和裁剪。这必须在显示窗口容器之前完成。具有许多本地子窗口的应用程序可能会遇到性能问题。

窗口容器有一些已知的限制：

• 堆叠顺序；嵌入的窗口将作为一个不透明的盒子堆叠在小部件层次结构的顶部。多个重叠的窗口容器实例的堆叠顺序是未定义的。

• 渲染集成；窗口容器不与QGraphicsProxyWidget、render()或类似功能互操作。

• 焦点处理；可以让窗口容器实例拥有任何焦点策略，并且它会通过调用QWindow::requestActivate()将焦点委托给窗口。然而，从QWindow实例返回到正常焦点链将由QWindow实例实现本身决定。例如，当使用Tab键进入基于Qt Quick的窗口时，很可能进一步的Tab键按下只会在QML应用程序内部循环。此外，QWindow::requestActivate()是否实际给予窗口焦点，取决于平台。

• 在基于QWidget的应用程序中使用多个窗口容器实例可能会大大降低应用程序的整体性能。

• 自6.7版本起，如果window属于一个小部件（即window是通过调用windowHandle()获得的），则不会创建容器。相反，此函数将在将小部件重新父级化到父级后返回小部件本身。由于不会创建容器，flags将被忽略。换句话说，如果window属于一个小部件，考虑将该小部件重新父级化到parent，而不是使用此函数。

cursor()¶

Return type:

QCursor

另请参阅

setCursor()

属性 cursorᅟ 的获取器。

customContextMenuRequested(pos)¶

Parameters:

pos – QPoint

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

另请参阅

mapToGlobal() QMenu contextMenuPolicy

destroy([destroyWindow=true[, destroySubWindows=true]])¶

Parameters:

• destroyWindow – 布尔值

• destroySubWindows – 布尔值

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

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

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

dragEnterEvent(event)¶

Parameters:

事件 – QDragEnterEvent

当拖动正在进行且鼠标进入此小部件时，将调用此事件处理程序。事件通过event参数传递。

如果事件被忽略，小部件将不会接收到任何drag move events。

请参阅拖放文档，了解如何在您的应用程序中提供拖放功能的概述。

另请参阅

QDragQDragEnterEvent

dragLeaveEvent(event)¶

Parameters:

事件 – QDragLeaveEvent

当拖动正在进行且鼠标离开此小部件时，将调用此事件处理程序。事件通过event参数传递。

请参阅拖放文档，了解如何在您的应用程序中提供拖放功能的概述。

另请参阅

QDragQDragLeaveEvent

dragMoveEvent(event)¶

Parameters:

事件 – QDragMoveEvent

如果正在进行拖动操作，并且发生以下任一条件时，将调用此事件处理程序：光标进入此小部件、光标在此小部件内移动，或在此小部件具有焦点时按下键盘上的修饰键。事件通过event参数传递。

请参阅拖放文档，了解如何在您的应用程序中提供拖放功能的概述。

另请参阅

QDragQDragMoveEvent

dropEvent(event)¶

Parameters:

事件 – QDropEvent

当拖动操作在此小部件上释放时，将调用此事件处理程序。事件通过event参数传递。

请参阅拖放文档，了解如何在您的应用程序中提供拖放功能的概述。

另请参阅

QDragQDropEvent

effectiveWinId()¶

Return type:

WId

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

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

注意

我们建议您不要存储此值，因为它可能在运行时发生变化。

另请参阅

nativeParentWidget()

ensurePolished()¶

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

QWidget 在完全构建之后但在首次显示之前调用此函数。如果您想确保在执行操作之前小部件已经完善，可以调用此函数，例如，在小部件的 sizeHint() 重新实现中可能需要正确的字体大小。请注意，此函数 是 从 sizeHint() 的默认实现中调用的。

抛光对于必须在所有构造函数（来自基类以及子类）被调用后发生的最终初始化非常有用。

如果您需要在部件被修饰时更改一些设置，请重新实现 event() 并处理 QEvent::Polish 事件类型。

注意

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

另请参阅

event()

enterEvent(event)¶

Parameters:

事件 – QEnterEvent

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

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

另请参阅

leaveEvent() mouseMoveEvent() event()

static find(id)¶

Parameters:

id – WId

Return type:

QWidget

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

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

focusInEvent(event)¶

Parameters:

事件 – QFocusEvent

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

一个部件通常必须setFocusPolicy()设置为除了Qt::NoFocus以外的值，才能接收焦点事件。（注意，应用程序程序员可以在任何部件上调用setFocus()，即使是那些通常不接受焦点的部件。）

默认实现会更新小部件（除了那些没有指定focusPolicy()的窗口）。

另请参阅

focusOutEvent() setFocusPolicy() keyPressEvent() keyReleaseEvent() event() QFocusEvent

focusNextChild()¶

Return type:

布尔

找到一个适合Tab键的新小部件来给予键盘焦点，如果可以找到新小部件，则返回true，否则返回false。

另请参阅

focusPreviousChild()

focusNextPrevChild(next)¶

Parameters:

next – 布尔值

Return type:

布尔

找到一个新部件以给予键盘焦点，适用于Tab和Shift+Tab，如果可以找到新部件则返回true，否则返回false。

如果 next 为真，此函数向前搜索，如果 next 为假，则向后搜索。

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

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

另请参阅

focusNextChild() focusPreviousChild()

focusOutEvent(event)¶

Parameters:

事件 – QFocusEvent

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

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

默认实现会更新小部件（除了那些没有指定focusPolicy()的窗口）。

另请参阅

focusInEvent() setFocusPolicy() keyPressEvent() keyReleaseEvent() event() QFocusEvent

focusPolicy()¶

Return type:

FocusPolicy

另请参阅

setFocusPolicy()

属性 focusPolicyᅟ 的获取器。

focusPreviousChild()¶

Return type:

布尔

找到一个适合Shift+Tab的新小部件来给予键盘焦点，如果可以找到新小部件，则返回true，否则返回false。

另请参阅

focusNextChild()

focusProxy()¶

Return type:

QWidget

返回焦点代理，如果没有焦点代理则返回None。

另请参阅

setFocusProxy()

focusWidget()¶

Return type:

QWidget

返回此小部件的最后一个子部件，该子部件已被调用setFocus。对于顶级小部件，这是在此窗口被激活时将获得焦点的小部件。

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

font()¶

Return type:

QFont

另请参阅

setFont()

属性 fontᅟ 的获取器。

fontInfo()¶

Return type:

QFontInfo

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

另请参阅

font() fontMetrics() setFont()

fontMetrics()¶

Return type:

QFontMetrics

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

另请参阅

font() fontInfo() setFont()

foregroundRole()¶

Return type:

ColorRole

返回前景角色。

前景角色定义了用于绘制前景的小部件的调色板中的颜色。

如果没有设置明确的前景角色，函数将返回一个与背景角色形成对比的角色。

另请参阅

setForegroundRole() backgroundRole()

frameGeometry()¶

Return type:

QRect

属性 frameGeometryᅟ 的获取器。

frameSize()¶

Return type:

QSize

属性 frameSizeᅟ 的获取器。

geometry()¶

Return type:

QRect

另请参阅

setGeometry()

属性 geometryᅟ 的获取器。

grab([rectangle=QRect(QPoint(0, 0), QSize(-1, -1))])¶

Parameters:

矩形 – QRect

Return type:

QPixmap

将小部件渲染到由给定的rectangle限制的像素图中。如果小部件有任何子部件，则它们也会在适当的位置绘制。

如果指定了无效大小的矩形（默认值），则绘制整个小部件。

另请参阅

render() QPixmap

grabGesture(type[, flags=Qt.GestureFlags()])¶

Parameters:

• type – GestureType

• flags – GestureFlag 的组合

将小部件订阅到具有特定gesture的给定flags。

另请参阅

ungrabGesture() QGestureEvent

grabKeyboard()¶

获取键盘输入。

此小部件接收所有键盘事件，直到调用releaseKeyboard()；其他小部件完全不会收到键盘事件。鼠标事件不受影响。如果你想捕获鼠标事件，请使用grabMouse()。

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

如果当前有另一个小部件正在捕获键盘输入，则该小部件的捕获将首先被释放。

另请参阅

releaseKeyboard() grabMouse() releaseMouse() focusWidget()

grabMouse()¶

获取鼠标输入。

此小部件接收所有鼠标事件，直到调用releaseMouse()；其他小部件完全不会收到鼠标事件。键盘事件不受影响。如果你想捕获键盘事件，请使用grabKeyboard()。

警告

鼠标抓取应用程序中的错误经常会锁定终端。请极其谨慎地使用此函数，并考虑在调试时使用-nograb命令行选项。

在使用Qt时，很少需要手动捕获鼠标，因为Qt会智能地捕获和释放鼠标。特别是，当按下鼠标按钮时，Qt会捕获鼠标，并在最后一个按钮释放之前保持捕获状态。

注意

只有可见的小部件才能捕获鼠标输入。如果isVisible()返回false，则该小部件无法调用grabMouse()。

注意

在Windows上，grabMouse()仅在鼠标位于进程拥有的窗口内时有效。在macOS上，grabMouse()仅在鼠标位于该小部件的框架内时有效。

另请参阅

releaseMouse() grabKeyboard() releaseKeyboard()

grabMouse(cursor)

Parameters:

光标 – QCursor

此函数重载了 grabMouse() 。

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

光标将呈现形状 cursor（只要鼠标焦点被捕获），并且此小部件将是唯一接收鼠标事件的，直到调用 releaseMouse()。

警告

抓取鼠标可能会锁定终端。

注意

请参阅grabMouse()中的注释。

另请参阅

releaseMouse() grabKeyboard() releaseKeyboard() setCursor()

grabShortcut(key[, context=Qt.WindowShortcut])¶

Parameters:

• key – QKeySequence

• 上下文 – ShortcutContext

Return type:

整数

向Qt的快捷方式系统添加快捷方式，该系统监视给定key序列在给定context中的情况。如果context是Qt::ApplicationShortcut，则该快捷方式适用于整个应用程序。否则，它要么是本地于该小部件的，即Qt::WidgetShortcut，要么是本地于窗口本身的，即Qt::WindowShortcut。

如果相同的key序列被多个小部件捕获，当key序列发生时，QEvent::Shortcut事件将以非确定性的顺序发送到所有适用的小部件，但“ambiguous”标志设置为true。

警告

通常你不需要使用这个函数；相反，创建带有你需要的快捷键序列的QAction（如果你还想要等效的菜单选项和工具栏按钮），或者如果你只需要键序列，创建QShortcut。QAction和QShortcut都为你处理所有的事件过滤，并提供在用户触发键序列时触发的信号，因此比这个低级函数更容易使用。

另请参阅

releaseShortcut() setShortcutEnabled()

graphicsEffect()¶

Return type:

QGraphicsEffect

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

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

另请参阅

setGraphicsEffect()

graphicsProxyWidget()¶

Return type:

QGraphicsProxyWidget

返回图形视图中对应嵌入小部件的代理小部件；否则返回None。

另请参阅

createProxyForChildWidget() addWidget()

hasFocus()¶

Return type:

布尔

属性 focusᅟ 的获取器。

hasHeightForWidth()¶

Return type:

布尔

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

hasMouseTracking()¶

Return type:

布尔

属性 mouseTrackingᅟ 的获取器。

hasTabletTracking()¶

Return type:

布尔

属性 tabletTrackingᅟ 的获取器。

heightForWidth(w)¶

Parameters:

w – 整数

Return type:

整数

返回此小部件的首选高度，给定宽度 w。

如果此小部件有布局，默认实现返回布局的首选高度。如果没有布局，默认实现返回-1，表示首选高度不依赖于宽度。

hide()¶

隐藏小部件。此函数等同于 setVisible (false)。

注意

如果您正在使用QDialog或其子类，并且在此函数之后调用show()函数，对话框将显示在其原始位置。

另请参阅

hideEvent() isHidden() show() setVisible() isVisible() close()

hideEvent(event)¶

Parameters:

事件 – QHideEvent

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

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

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

另请参阅

visible event() QHideEvent

inputMethodEvent(event)¶

Parameters:

事件 – QInputMethodEvent

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

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

默认实现调用 event->ignore()，这会拒绝输入法事件。有关更多详细信息，请参阅 QInputMethodEvent 文档。

另请参阅

event() QInputMethodEvent

inputMethodHints()¶

Return type:

InputMethodHint 的组合

另请参阅

setInputMethodHints()

属性 inputMethodHintsᅟ 的获取器。

inputMethodQuery(query)¶

Parameters:

查询 – InputMethodQuery

Return type:

对象

此方法仅与输入小部件相关。输入方法使用它来查询小部件的一组属性，以便能够支持复杂的输入方法操作，如对周围文本的支持和重新转换。

query 指定要查询的属性。

另请参阅

inputMethodEvent() inputMethodHints

insertAction(before, action)¶

Parameters:

• 之前 – QAction

• action – QAction

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

一个 QWidget 应该只拥有每个动作的一个实例。

另请参阅

removeAction() addAction() QMenu contextMenuPolicy actions()

insertActions(before, actions)¶

Parameters:

• 之前 – QAction

• actions – QAction 的列表

将操作 actions 插入到此小部件的操作列表中，位于操作 before 之前。如果 before 是 None 或 before 不是此小部件的有效操作，则追加该操作。

一个 QWidget 最多可以拥有每个动作中的一个。

另请参阅

removeAction() QMenu insertAction() contextMenuPolicy

internalWinId()¶

Return type:

WId

isActiveWindow()¶

Return type:

布尔

属性 isActiveWindowᅟ 的获取器。

isAncestorOf(child)¶

Parameters:

子控件 – QWidget

Return type:

布尔

如果此小部件是给定child的父级（或祖父级，依此类推到任何级别），并且两个小部件都在同一个窗口内，则返回true；否则返回false。

isEnabled()¶

Return type:

布尔

属性 enabledᅟ 的获取器。

isEnabledTo(ancestor)¶

Parameters:

祖先 – QWidget

Return type:

布尔

如果启用ancestor后此小部件将变为启用状态，则返回true；否则返回false。

如果小部件本身及其每个父级（不包括ancestor）都没有被显式禁用，则属于这种情况。

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

这里的“祖先”一词指的是同一窗口内的父部件。

因此，isEnabledTo(0) 在这个小部件的窗口处停止，与 isEnabled() 不同，后者还会考虑父窗口。

另请参阅

setEnabled() enabled

isFullScreen()¶

Return type:

布尔

属性 fullScreenᅟ 的获取器。

isHidden()¶

Return type:

布尔

如果小部件被隐藏，则返回 true，否则返回 false。

隐藏的小部件只有在调用show()时才会变得可见。当父部件显示时，它不会自动显示。

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

isHidden() 意味着 ! isVisible()，但一个小部件可以同时不可见且不隐藏。这种情况适用于那些作为不可见小部件的子部件的小部件。

小部件在以下情况下隐藏：

• 它们被创建为独立的窗口，

• 它们被创建为可见小部件的子部件，

• hide() 或 setVisible (false) 被调用。

isLeftToRight()¶

Return type:

布尔

isMaximized()¶

Return type:

布尔

属性 maximizedᅟ 的获取器。

isMinimized()¶

Return type:

布尔

属性 minimizedᅟ 的获取器。

isModal()¶

Return type:

布尔

属性 modalᅟ 的获取器。

isRightToLeft()¶

Return type:

布尔

isTopLevel()¶

Return type:

布尔

注意

此函数已弃用。

请使用isWindow()代替。

isVisible()¶

Return type:

布尔

属性 visibleᅟ 的获取器。

isVisibleTo(ancestor)¶

Parameters:

祖先 – QWidget

Return type:

布尔

如果显示ancestor时此小部件将变为可见，则返回true；否则返回false。

如果小部件本身或其任何父级（直到但不包括ancestor）未被明确隐藏，则真实情况发生。

如果小部件被屏幕上的其他窗口遮挡，此函数仍将返回 true，但如果它或它们被移动，则可能物理上可见。

isVisibleTo(0) 与 isVisible() 相同。

另请参阅

show() hide() isVisible()

isWindow()¶

Return type:

布尔

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

窗口是一个在视觉上不属于任何其他小部件的小部件，通常具有框架和window title。

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

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

另请参阅

window() isModal() parentWidget()

isWindowModified()¶

Return type:

布尔

属性 windowModifiedᅟ 的获取器。

keyPressEvent(event)¶

Parameters:

事件 – QKeyEvent

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

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

如果你重新实现这个处理程序，如果你不对键进行操作，调用基类实现是非常重要的。

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

请注意，QKeyEvent 开始时 isAccepted() == true，因此您不需要调用 QKeyEvent::accept() - 如果您对按键进行操作，只需不调用基类实现即可。

另请参阅

keyReleaseEvent() setFocusPolicy() focusInEvent() focusOutEvent() event() QKeyEvent

keyReleaseEvent(event)¶

Parameters:

事件 – QKeyEvent

此事件处理程序，用于事件 event，可以在子类中重新实现以接收小部件的按键释放事件。

一个部件必须accept focus初始并且have focus才能接收一个键释放事件。

如果你重新实现这个处理程序，如果你不对键进行操作，调用基类实现是非常重要的。

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

请注意，QKeyEvent 开始时 isAccepted() == true，因此您不需要调用 QKeyEvent::accept() - 如果您对按键进行操作，只需不调用基类实现即可。

另请参阅

keyPressEvent() setFocusPolicy() focusInEvent() focusOutEvent() event() QKeyEvent

static keyboardGrabber()¶

Return type:

QWidget

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

如果当前应用程序中没有小部件正在抓取键盘，则返回None。

另请参阅

grabMouse() mouseGrabber()

layout()¶

Return type:

QLayout

返回安装在此小部件上的布局管理器，如果未安装布局管理器，则返回None。

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

另请参阅

setLayout() sizePolicy() 布局管理

layoutDirection()¶

Return type:

LayoutDirection

另请参阅

setLayoutDirection()

属性 layoutDirectionᅟ 的获取器。

leaveEvent(event)¶

Parameters:

事件 – QEvent

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

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

另请参阅

enterEvent() mouseMoveEvent() event()

locale()¶

Return type:

QLocale

另请参阅

setLocale()

属性 localeᅟ 的获取器。

lower()¶

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

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

另请参阅

raise() stackUnder()

mapFrom(parent, pos)¶

Parameters:

• parent – QWidget

• pos – QPoint

Return type:

QPoint

这是一个重载函数。

mapFrom(parent, pos)

Parameters:

• parent – QWidget

• pos – QPointF

Return type:

QPointF

将小部件的坐标 pos 从 parent 的坐标系转换到此小部件的坐标系。parent 不能为 None，并且必须是调用小部件的父级。

另请参阅

mapTo() mapFromParent() mapFromGlobal() underMouse()

mapFromGlobal(pos)¶

Parameters:

pos – QPoint

Return type:

QPoint

这是一个重载函数。

mapFromGlobal(pos)

Parameters:

pos – QPointF

Return type:

QPointF

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

另请参阅

mapToGlobal() mapFrom() mapFromParent()

mapFromParent(pos)¶

Parameters:

pos – QPoint

Return type:

QPoint

这是一个重载函数。

mapFromParent(pos)

Parameters:

pos – QPointF

Return type:

QPointF

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

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

另请参阅

mapToParent() mapFrom() mapFromGlobal() underMouse()

mapTo(parent, pos)¶

Parameters:

• parent – QWidget

• pos – QPoint

Return type:

QPoint

这是一个重载函数。

mapTo(parent, pos)

Parameters:

• parent – QWidget

• pos – QPointF

Return type:

QPointF

将小部件的坐标 pos 转换为 parent 的坐标系。parent 不能为 None，并且必须是调用小部件的父级。

另请参阅

mapFrom() mapToParent() mapToGlobal() underMouse()

mapToGlobal(pos)¶

Parameters:

pos – QPoint

Return type:

QPoint

这是一个重载函数。

mapToGlobal(pos)

Parameters:

pos – QPointF

Return type:

QPointF

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

另请参阅

mapFromGlobal() mapTo() mapToParent()

mapToParent(pos)¶

Parameters:

pos – QPoint

Return type:

QPoint

这是一个重载函数。

mapToParent(pos)

Parameters:

pos – QPointF

Return type:

QPointF

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

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

另请参阅

mapFromParent() mapTo() mapToGlobal() underMouse()

mask()¶

Return type:

QRegion

返回当前在小部件上设置的遮罩。如果没有设置遮罩，返回值将是一个空区域。

另请参阅

setMask() clearMask() isEmpty()

maximumHeight()¶

Return type:

整数

另请参阅

setMaximumHeight()

属性 maximumHeightᅟ 的获取器。

maximumSize()¶

Return type:

QSize

另请参阅

setMaximumSize()

属性 maximumSizeᅟ 的获取器。

maximumWidth()¶

Return type:

整数

另请参阅

setMaximumWidth()

属性 maximumWidthᅟ 的获取器。

minimumHeight()¶

Return type:

整数

另请参阅

setMinimumHeight()

属性 minimumHeightᅟ 的获取器。

minimumSize()¶

Return type:

QSize

另请参阅

setMinimumSize()

属性 minimumSizeᅟ 的获取器。

minimumSizeHint()¶

Return type:

QSize

属性 minimumSizeHintᅟ 的获取器。

minimumWidth()¶

Return type:

整数

另请参阅

setMinimumWidth()

属性 minimumWidthᅟ 的获取器。

mouseDoubleClickEvent(event)¶

Parameters:

事件 – QMouseEvent

此事件处理程序，用于事件 event，可以在子类中重新实现以接收小部件的鼠标双击事件。

默认实现调用 mousePressEvent() 。

注意

小部件除了双击事件外，还将接收鼠标按下和鼠标释放事件。如果另一个重叠此小部件的小部件在响应按下或释放事件时消失，则此小部件将仅接收双击事件。开发人员需要确保应用程序正确解释这些事件。

另请参阅

mousePressEvent() mouseReleaseEvent() mouseMoveEvent() event() QMouseEvent

static mouseGrabber()¶

Return type:

QWidget

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

如果当前应用程序中没有小部件正在抓取鼠标，则返回None。

另请参阅

grabMouse() keyboardGrabber()

mouseMoveEvent(event)¶

Parameters:

事件 – QMouseEvent

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

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

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

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

另请参阅

setMouseTracking() mousePressEvent() mouseReleaseEvent() mouseDoubleClickEvent() event() 涂鸦示例

mousePressEvent(event)¶

Parameters:

事件 – QMouseEvent

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

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

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

另请参阅

mouseReleaseEvent() mouseDoubleClickEvent() mouseMoveEvent() event() 涂鸦示例

mouseReleaseEvent(event)¶

Parameters:

事件 – QMouseEvent

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

另请参阅

mousePressEvent() mouseDoubleClickEvent() mouseMoveEvent() event() 涂鸦示例

move(arg__1)¶

Parameters:

arg__1 – QPoint

属性 posᅟ 的设置器。

move(x, y)

Parameters:

• x – 整数

• y – 整数

这是一个重载函数。

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

moveEvent(event)¶

Parameters:

事件 – QMoveEvent

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

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

另请参阅

resizeEvent() event() move() QMoveEvent

nativeEvent(eventType, message)¶

Parameters:

• eventType – QByteArray

• message – void

Return type:

PyObject

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

在重新实现此函数时，如果您希望阻止Qt处理该事件，请返回true并设置result。result参数仅在Windows上有意义。如果返回false，此本机事件将传递回Qt，Qt将事件转换为Qt事件并发送到小部件。

注意

只有当小部件具有本机窗口句柄时，事件才会传递到此事件处理程序。

注意

此函数取代了Qt 4中的事件过滤函数x11Event()、winEvent()和macEvent()。

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

另请参阅

QAbstractNativeEventFilter

nativeParentWidget()¶

Return type:

QWidget

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

另请参阅

effectiveWinId()

nextInFocusChain()¶

Return type:

QWidget

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

另请参阅

previousInFocusChain()

normalGeometry()¶

Return type:

QRect

属性 normalGeometryᅟ 的获取器。

overrideWindowFlags(type)¶

Parameters:

type – WindowType 的组合

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

警告

除非你真的知道自己在做什么，否则不要调用这个函数。

另请参阅

setWindowFlags()

overrideWindowState(state)¶

Parameters:

state – WindowState 的组合

paintEvent(event)¶

Parameters:

事件 – QPaintEvent

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

绘制事件是对重新绘制小部件全部或部分的请求。它可能由于以下原因之一发生：

• repaint() 或 update() 被调用，

• 小部件被遮挡，现在已被揭开，或者

• 许多其他原因。

许多小部件在被要求时可以简单地重新绘制它们的整个表面，但一些较慢的小部件需要通过仅绘制请求的区域来优化：QPaintEvent::region()。这种速度优化不会改变结果，因为在事件处理期间，绘制被裁剪到该区域。QListView 和 QTableView 就是这样做的，例如。

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

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

背景可以使用setBackgroundRole()和setPalette()来设置。

自 Qt 4.0 起，QWidget 自动双缓冲其绘制，因此无需在 paintEvent() 中编写双缓冲代码以避免闪烁。

注意

通常，你应该避免在paintEvent()内部调用update()或repaint()。例如，在paintEvent()内部对子元素调用update()或repaint()会导致未定义的行为；子元素可能会也可能不会收到绘制事件。

警告

如果您使用的是没有Qt的backingstore的自定义绘图引擎，则必须设置Qt::WA_PaintOnScreen。否则，paintEngine()将永远不会被调用；将使用backingstore代替。

另请参阅

event() repaint() update() 模拟时钟

palette()¶

Return type:

QPalette

另请参阅

setPalette()

属性 paletteᅟ 的获取器。

parentWidget()¶

Return type:

QWidget

返回此小部件的父级，如果没有父级小部件，则返回None。

pos()¶

Return type:

QPoint

属性 posᅟ 的获取器。

previousInFocusChain()¶

Return type:

QWidget

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

另请参阅

nextInFocusChain()

raise_()¶

rect()¶

Return type:

QRect

属性 rectᅟ 的获取器。

releaseKeyboard()¶

释放键盘抓取。

另请参阅

grabKeyboard() grabMouse() releaseMouse()

releaseMouse()¶

释放鼠标抓取。

另请参阅

grabMouse() grabKeyboard() releaseKeyboard()

releaseShortcut(id)¶

Parameters:

id – int

从Qt的快捷方式系统中移除具有给定id的快捷方式。该小部件将不再接收该快捷方式键序列的QEvent::Shortcut事件（除非它有其他具有相同键序列的快捷方式）。

警告

通常不需要使用此函数，因为Qt的快捷方式系统会在其父部件被销毁时自动移除快捷方式。最好使用QAction或QShortcut来处理快捷方式，因为它们比这个低级函数更易于使用。还要注意，这是一个昂贵的操作。

另请参阅

grabShortcut() setShortcutEnabled()

removeAction(action)¶

Parameters:

动作 – QAction

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

另请参阅

insertAction() actions() insertAction()

render(target[, targetOffset=QPoint()[, sourceRegion=QRegion()[, renderFlags=QWidget.RenderFlags(QWidget.RenderFlag.DrawWindowBackground | QWidget.RenderFlag.DrawChildren)]]])¶

Parameters:

• target – QPaintDevice

• targetOffset – QPoint

• sourceRegion – QRegion

• renderFlags – RenderFlag 的组合

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

使用renderFlags确定如何渲染，将此小部件的sourceRegion渲染到target中。渲染从target中的targetOffset开始。例如：

pixmap = QPixmap(widget.size())
widget.render(pixmap)

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

在渲染之前，请确保为target设备的当前活动画家（如果有的话）调用QPainter::end()。例如：

painter = QPainter(self)
...
painter.end()
myWidget.render(self)

注意

要获取QOpenGLWidget的内容，请使用QOpenGLWidget::grabFramebuffer()代替。

render(painter, targetOffset[, sourceRegion=QRegion()[, renderFlags=QWidget.RenderFlags(QWidget.RenderFlag.DrawWindowBackground | QWidget.RenderFlag.DrawChildren)]])

Parameters:

• 画家 – QPainter

• targetOffset – QPoint

• sourceRegion – QRegion

• renderFlags – RenderFlag 的组合

这是一个重载函数。

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

应用于painter的转换和设置将在渲染时使用。

注意

painter 必须处于活动状态。在 macOS 上，小部件将被渲染到 QPixmap 中，然后由 painter 绘制。

另请参阅

device()

repaint()¶

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

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

警告

如果你在一个可能从paintEvent()调用的函数中调用repaint()，你可能会得到无限递归。函数update()永远不会导致递归。

另请参阅

update() paintEvent() setUpdatesEnabled()

repaint(rect)

Parameters:

rect – QRect

这是一个重载函数。

此版本在小部件内重新绘制了一个矩形 rect。

repaint(rgn)

Parameters:

rgn – QRegion

这是一个重载函数。

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

repaint(x, y, w, h)

Parameters:

• x – 整数

• y – 整数

• w – 整数

• h – 整数

这是一个重载函数。

此版本重新绘制了小部件内的一个矩形（x, y, w, h）。

如果 w 是负数，它将被替换为 width() - x，如果 h 是负数，它将被替换为 height() - y。

resize(arg__1)¶

Parameters:

arg__1 – QSize

属性 sizeᅟ 的设置器。

resize(w, h)

Parameters:

• w – 整数

• h – 整数

这是一个重载函数。

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

resizeEvent(event)¶

Parameters:

事件 – QResizeEvent

此事件处理程序可以在子类中重新实现，以接收传递在event参数中的小部件调整大小事件。当调用resizeEvent()时，小部件已经具有其新的几何形状。旧的大小可以通过QResizeEvent::oldSize()访问。

小部件将被擦除，并在处理调整大小事件后立即接收绘制事件。在此处理程序中不需要（也不应该）进行任何绘制。

另请参阅

moveEvent() event() resize() paintEvent() 涂鸦示例

restoreGeometry(geometry)¶

Parameters:

几何 – QByteArray

Return type:

布尔

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

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

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

settings = QSettings("MyCompany", "MyApp")
myWidget.restoreGeometry(settings.value("myWidget/geometry").toByteArray())

请参阅Window Geometry文档以了解窗口几何问题的概述。

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

另请参阅

saveGeometry() saveState() restoreState()

saveGeometry()¶

Return type:

QByteArray

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

保存顶层小部件的当前几何形状和状态。

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

def closeEvent(self, event):

    settings = QSettings("MyCompany", "MyApp")
    settings.setValue("geometry", saveGeometry())
    QWidget.closeEvent(event)

请参阅Window Geometry文档以了解窗口几何问题的概述。

使用saveState()来保存几何形状以及工具栏和停靠小部件的状态。

另请参阅

restoreGeometry() saveState() restoreState()

screen()¶

Return type:

QScreen

返回小部件所在的屏幕。

另请参阅

setScreen() windowHandle()

scroll(dx, dy)¶

Parameters:

• dx – 整数

• dy – 整数

将小部件及其子部件向右滚动dx像素，向下滚动dy像素。dx和dy都可以是负数。

滚动后，小部件将接收到需要重新绘制的区域的绘制事件。对于Qt知道是不透明的小部件，这只是新暴露的部分。例如，如果一个不透明的小部件向左滚动8像素，只有右侧边缘的8像素宽的条纹需要更新。

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

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

另请参阅

透明度 和 双缓冲

scroll(dx, dy, r)

Parameters:

• dx – 整数

• dy – 整数

• r – QRect

这是一个重载函数。

此版本仅滚动 r 并且不会移动小部件的子元素。

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

另请参阅

QScrollArea

setAcceptDrops(on)¶

Parameters:

on – 布尔值

另请参阅

acceptDrops()

属性 acceptDropsᅟ 的设置器。

setAccessibleDescription(description)¶

Parameters:

描述 – str

另请参阅

accessibleDescription()

属性 accessibleDescriptionᅟ 的设置器。

setAccessibleName(name)¶

Parameters:

name – str

另请参阅

accessibleName()

属性 accessibleNameᅟ 的设置器。

setAttribute(attribute[, on=true])¶

Parameters:

• 属性 – WidgetAttribute

• on – 布尔值

如果 on 为真，则在此小部件上设置属性 attribute；否则清除该属性。

另请参阅

testAttribute()

setAutoFillBackground(enabled)¶

Parameters:

enabled – 布尔值

另请参阅

autoFillBackground()

属性 autoFillBackgroundᅟ 的设置器。

setBackgroundRole(role)¶

Parameters:

角色 – ColorRole

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

背景角色定义了用于渲染背景的小部件的调色板中的画笔。

如果 role 是 QPalette::NoRole，那么该小部件将继承其父部件的背景角色。

请注意，样式可以从调色板中选择任何颜色。如果您无法通过setBackgroundRole()实现所需的结果，您可以修改调色板或设置样式表。

另请参阅

backgroundRole() foregroundRole()

setBaseSize(arg__1)¶

Parameters:

arg__1 – QSize

另请参阅

baseSize()

属性 baseSizeᅟ 的设置器。

setBaseSize(basew, baseh)

Parameters:

• basew – int

• baseh – int

这是一个重载函数。

这对应于setBaseSize (QSize(basew, baseh))。将小部件的基本大小设置为宽度basew和高度baseh。

setContentsMargins(margins)¶

Parameters:

边距 – QMargins

这是一个重载函数。

setContentsMargins 函数设置小部件内容周围的边距。

设置小部件内容周围的边距，使其大小由margins确定。边距由布局系统使用，并且可能由子类用于指定绘制的区域（例如，不包括框架）。

更改边距将触发 resizeEvent() 。

另请参阅

contentsRect() contentsMargins()

setContentsMargins(left, top, right, bottom)

Parameters:

• left – int

• top – int

• right – int

• bottom – int

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

更改边距将触发resizeEvent()。

另请参阅

contentsRect() contentsMargins()

setContextMenuPolicy(policy)¶

Parameters:

policy – ContextMenuPolicy

另请参阅

contextMenuPolicy()

属性 contextMenuPolicyᅟ 的设置器。

setCursor(arg__1)¶

Parameters:

arg__1 – QCursor

另请参阅

cursor()

属性 cursorᅟ 的设置器。

setDisabled(disable)¶

Parameters:

disable – 布尔值

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

查看enabled文档以获取更多信息。

另请参阅

isEnabledTo() changeEvent()

setEnabled(arg__1)¶

Parameters:

arg__1 – 布尔值

另请参阅

isEnabled()

属性 enabledᅟ 的设置器。

setFixedHeight(h)¶

Parameters:

h – 整数

将小部件的最小和最大高度设置为h，而不改变宽度。为方便起见提供。

另请参阅

sizeHint() minimumSize() maximumSize() setFixedSize()

setFixedSize(s)¶

Parameters:

s – QSize

将小部件的最小和最大尺寸设置为s，从而防止其增长或缩小。

这将覆盖由QLayout设置的默认大小约束。

要移除约束，请将大小设置为 QWIDGETSIZE_MAX 。

或者，如果您希望小部件根据其内容具有固定大小，您可以调用 setSizeConstraint ( SetFixedSize );

另请参阅

maximumSize minimumSize

setFixedSize(w, h)

Parameters:

• w – 整数

• h – 整数

这是一个重载函数。

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

setFixedWidth(w)¶

Parameters:

w – 整数

将小部件的最小和最大宽度设置为w，而不改变高度。为方便起见提供。

另请参阅

sizeHint() minimumSize() maximumSize() setFixedSize()

setFocus()¶

这是一个重载函数。

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

setFocus(reason)

Parameters:

原因 – FocusReason

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

首先，一个关于即将改变焦点的事件被发送到焦点小部件（如果有的话），以告诉它即将失去焦点。然后焦点被改变，一个焦点离开事件被发送到之前的焦点项目，一个焦点进入事件被发送到新项目，以告诉它刚刚获得了焦点。（如果焦点进入和焦点离开的小部件是相同的，则不会发生任何事情。）

注意

在嵌入式平台上，setFocus() 不会导致输入法打开输入面板。如果你希望这种情况发生，你必须自己向小部件发送一个 QEvent::RequestSoftwareInputPanel 事件。

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

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

警告

如果你在一个可能从focusOutEvent()或focusInEvent()调用的函数中调用setFocus()，你可能会得到一个无限递归。

另请参阅

hasFocus() clearFocus() focusInEvent() focusOutEvent() setFocusPolicy() focusWidget() focusWidget() grabKeyboard() grabMouse() 小部件中的键盘焦点 RequestSoftwareInputPanel

setFocusPolicy(policy)¶

Parameters:

策略 – FocusPolicy

另请参阅

focusPolicy()

属性 focusPolicyᅟ 的设置器。

setFocusProxy(w)¶

Parameters:

w – QWidget

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

一些小部件可以“拥有焦点”，但会创建一个子部件，例如QLineEdit，来实际处理焦点。在这种情况下，小部件可以将行编辑设置为其焦点代理。

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

另请参阅

focusProxy()

setFont(arg__1)¶

Parameters:

arg__1 – QFont

另请参阅

font()

属性 fontᅟ 的设置器。

setForegroundRole(role)¶

Parameters:

角色 – ColorRole

将小部件的前景角色设置为 role。

前景角色定义了用于绘制前景的小部件的调色板中的颜色。

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

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

另请参阅

foregroundRole() backgroundRole()

setGeometry(arg__1)¶

Parameters:

arg__1 – QRect

另请参阅

geometry()

属性 geometryᅟ 的设置器。

setGeometry(x, y, w, h)

Parameters:

• x – 整数

• y – 整数

• w – 整数

• h – 整数

这是一个重载函数。

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

setGraphicsEffect(effect)¶

Parameters:

效果 – QGraphicsEffect

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

将effect设置为小部件的效果。如果此小部件上已经安装了一个效果，QWidget将在安装新的effect之前删除现有的效果。

如果 effect 是安装在不同小部件上的效果，setGraphicsEffect() 将从该小部件中移除效果并将其安装在此小部件上。

QWidget 拥有 effect 的所有权。

注意

此函数将效果应用于自身及其所有子元素。

注意

基于OpenGL的小部件（如QGLWidget、QOpenGLWidget和QQuickWidget）不支持图形效果。

另请参阅

graphicsEffect()

setHidden(hidden)¶

Parameters:

hidden – 布尔值

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

另请参阅

isHidden()

setInputMethodHints(hints)¶

Parameters:

提示 – InputMethodHint 的组合

另请参阅

inputMethodHints()

属性 inputMethodHintsᅟ 的设置器。

setLayout(layout)¶

Parameters:

布局 – QLayout

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

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

如果 layout 是另一个小部件的布局管理器，setLayout() 将重新设置布局的父级，并使其成为此小部件的布局管理器。

示例：

layout = QVBoxLayout()
layout.addWidget(formWidget)
setLayout(layout)

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

QWidget 将拥有 layout 的所有权。

另请参阅

layout() 布局管理

setLayoutDirection(direction)¶

Parameters:

方向 – LayoutDirection

另请参阅

layoutDirection()

属性 layoutDirectionᅟ 的设置器。

setLocale(locale)¶

Parameters:

locale – QLocale

另请参阅

locale()

属性 localeᅟ 的设置器。

setMask(bitmap)¶

Parameters:

位图 – QBitmap

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

仅使小部件中bitmap对应的1位像素可见。如果区域包括小部件rect()之外的像素，该区域的窗口系统控件是否可见取决于平台。

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

以下代码展示了如何使用带有alpha通道的图像为小部件生成遮罩：

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

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

遮罩小部件仅在其可见部分接收鼠标事件。

另请参阅

mask() clearMask() windowOpacity()

setMask(region)

Parameters:

区域 – QRegion

这是一个重载函数。

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

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

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

另请参阅

windowOpacity

setMaximumHeight(maxh)¶

Parameters:

maxh – 整数

另请参阅

maximumHeight()

属性 maximumHeightᅟ 的设置器。

setMaximumSize(arg__1)¶

Parameters:

arg__1 – QSize

另请参阅

maximumSize()

属性 maximumSizeᅟ 的设置器。

setMaximumSize(maxw, maxh)

Parameters:

• maxw – int

• maxh – int

这是一个重载函数。

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

setMaximumWidth(maxw)¶

Parameters:

maxw – 整数

另请参阅

maximumWidth()

属性 maximumWidthᅟ 的设置器。

setMinimumHeight(minh)¶

Parameters:

minh – 整数

另请参阅

minimumHeight()

属性 minimumHeightᅟ 的设置器。

setMinimumSize(arg__1)¶

Parameters:

arg__1 – QSize

另请参阅

minimumSize()

属性 minimumSizeᅟ 的设置器。

setMinimumSize(minw, minh)

Parameters:

• minw – 整数

• minh – int

这是一个重载函数。

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

setMinimumWidth(minw)¶

Parameters:

minw – 整数

另请参阅

minimumWidth()

属性 minimumWidthᅟ 的设置器。

setMouseTracking(enable)¶

Parameters:

enable – 布尔值

另请参阅

hasMouseTracking()

属性 mouseTrackingᅟ 的设置器。

setPalette(arg__1)¶

Parameters:

arg__1 – QPalette

另请参阅

palette()

属性 paletteᅟ 的设置器。

setParent(parent)¶

Parameters:

父级 – QWidget

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

如果新的父部件位于不同的窗口中，重新父化的部件及其子部件将按照之前的内部顺序附加到新父部件的标签链的末尾。如果其中一个移动的部件具有键盘焦点，setParent() 将对该部件调用clearFocus()。

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

如果“新”的父部件是旧的父部件，此函数不执行任何操作。

注意

小部件在更改其父级时会变为不可见，即使它之前是可见的。您必须调用show()来使小部件再次可见。

警告

你很可能永远不需要这个函数。如果你有一个动态改变内容的小部件，使用QStackedWidget会容易得多。

另请参阅

setWindowFlags()

setParent(parent, f)

Parameters:

• parent – QWidget

• f – WindowType 的组合

这是一个重载函数。

此函数还接受小部件标志 f 作为参数。

setScreen(screen)¶

Parameters:

屏幕 – QScreen

设置小部件应显示在哪个屏幕上为screen。

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

注意

如果屏幕是多个屏幕的虚拟桌面的一部分，窗口将不会自动移动到screen。要将窗口相对于屏幕放置，请使用屏幕的topLeft()位置。

另请参阅

screen() setScreen()

setShortcutAutoRepeat(id[, enable=true])¶

Parameters:

• id – int

• enable – 布尔值

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

另请参阅

grabShortcut() releaseShortcut()

setShortcutEnabled(id[, enable=true])¶

Parameters:

• id – int

• enable – 布尔值

如果 enable 为 true，则启用具有给定 id 的快捷方式；否则禁用该快捷方式。

警告

通常不需要使用此函数，因为Qt的快捷键系统会在小部件隐藏/显示以及获得或失去焦点时自动启用/禁用快捷键。最好使用QAction或QShortcut来处理快捷键，因为它们比这个低级函数更容易使用。

另请参阅

grabShortcut() releaseShortcut()

setSizeIncrement(arg__1)¶

Parameters:

arg__1 – QSize

另请参阅

sizeIncrement()

属性 sizeIncrementᅟ 的设置器。

setSizeIncrement(w, h)

Parameters:

• w – 整数

• h – 整数

这是一个重载函数。

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

setSizePolicy(arg__1)¶

Parameters:

arg__1 – QSizePolicy

另请参阅

sizePolicy()

属性 sizePolicyᅟ 的设置器。

setSizePolicy(horizontal, vertical)

Parameters:

• horizontal – Policy

• 垂直 – Policy

这是一个重载函数。

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

另请参阅

QSizePolicy()

setStatusTip(arg__1)¶

Parameters:

arg__1 – str

另请参阅

statusTip()

属性 statusTipᅟ 的设置器。

setStyle(style)¶

Parameters:

样式 – QStyle

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

如果没有设置样式，小部件将使用应用程序的样式，style() 代替。

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

警告

此函数特别适用于演示目的，您希望展示Qt的样式功能。实际应用程序应避免使用它，而应使用一致的GUI样式。

警告

目前不支持为自定义的QStyle子类使用Qt样式表。我们计划在未来的某个版本中解决这个问题。

另请参阅

style() QStyle style() setStyle()

setStyleSheet(styleSheet)¶

Parameters:

styleSheet – str

另请参阅

styleSheet()

属性 styleSheetᅟ 的设置器。

static setTabOrder(first, second)¶

Parameters:

• 第一个 – QWidget

• second – QWidget

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

将second小部件放在first小部件之后，以调整焦点顺序。

它有效地从焦点链中移除了second小部件，并将其插入到first小部件之后。

请注意，由于second小部件的标签顺序已更改，您应该按以下顺序排列链：

setTabOrder(a, b) # a to b
setTabOrder(b, c) # a to b to c
setTabOrder(c, d) # a to b to c to d

不是这样的：

# WRONG
setTabOrder(c, d) # c to d
setTabOrder(a, b) # a to b AND c to d
setTabOrder(b, c) # a to b to c, but not c to d

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

注意

自 Qt 5.10 起：一个拥有子控件作为焦点代理的控件被视为复合控件。当在一个或两个复合控件之间设置标签顺序时，每个控件内部的本地标签顺序将被保留。这意味着如果两个控件都是复合控件，最终的标签顺序将从 first 中的最后一个子控件，到 second 中的第一个子控件。

另请参阅

setFocusPolicy() setFocusProxy() 小部件中的键盘焦点

setTabletTracking(enable)¶

Parameters:

enable – 布尔值

另请参阅

hasTabletTracking()

属性 tabletTrackingᅟ 的设置器。

setToolTip(arg__1)¶

Parameters:

arg__1 – str

另请参阅

toolTip()

属性 toolTipᅟ 的设置器。

setToolTipDuration(msec)¶

Parameters:

毫秒 – 整数

另请参阅

toolTipDuration()

属性 toolTipDurationᅟ 的设置器。

setUpdatesEnabled(enable)¶

Parameters:

enable – 布尔值

另请参阅

updatesEnabled()

属性 updatesEnabledᅟ 的设置器。

setVisible(visible)¶

Parameters:

visible – 布尔值

另请参阅

isVisible()

属性 visibleᅟ 的设置器。

setWhatsThis(arg__1)¶

Parameters:

arg__1 – str

另请参阅

whatsThis()

属性 whatsThisᅟ 的设置器。

setWindowFilePath(filePath)¶

Parameters:

filePath – str

另请参阅

windowFilePath()

属性 windowFilePathᅟ 的设置器。

setWindowFlag(flag[, on=true])¶

Parameters:

• flag – WindowType

• on – 布尔值

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

另请参阅

setWindowFlags() windowFlags() windowType()

setWindowFlags(type)¶

Parameters:

type – WindowType 的组合

另请参阅

windowFlags()

setWindowIcon(icon)¶

Parameters:

图标 – QIcon

另请参阅

windowIcon()

属性 windowIconᅟ 的设置器。

setWindowIconText(arg__1)¶

Parameters:

arg__1 – str

另请参阅

windowIconText()

属性 windowIconTextᅟ 的设置器。

setWindowModality(windowModality)¶

Parameters:

windowModality – WindowModality

另请参阅

windowModality()

属性 windowModalityᅟ 的设置器。

setWindowModified(arg__1)¶

Parameters:

arg__1 – 布尔值

另请参阅

isWindowModified()

属性 windowModifiedᅟ 的设置器。

setWindowOpacity(level)¶

Parameters:

level – 浮点数

另请参阅

windowOpacity()

setWindowRole(role)¶

Parameters:

role – str

将窗口的角色设置为role。这仅对X11上的窗口有意义。

另请参阅

windowRole()

setWindowState(state)¶

Parameters:

state – WindowState 的组合

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

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

w.setWindowState(w.windowState() ^ Qt.WindowFullScreen)

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

w.setWindowState((w.windowState()  ~Qt.WindowMinimized) | Qt.WindowActive)

调用此函数将隐藏小部件。你必须调用show()才能使小部件再次可见。

注意

在某些窗口系统中，Qt::WindowActive 不是立即生效的，在某些情况下可能会被忽略。

当窗口状态改变时，小部件会接收到一个类型为 QEvent::WindowStateChange 的 changeEvent()。

另请参阅

windowState()

setWindowTitle(arg__1)¶

Parameters:

arg__1 – str

另请参阅

windowTitle()

属性 windowTitleᅟ 的设置器。

show()¶

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

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

另请参阅

raise() showEvent() hide() setVisible() showMinimized() showMaximized() showNormal() isVisible() windowFlags()

showEvent(event)¶

Parameters:

事件 – QShowEvent

此事件处理程序可以在子类中重新实现，以接收传递在event参数中的小部件显示事件。

非自发的显示事件在部件显示之前立即发送。窗口的自发显示事件随后传递。

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

另请参阅

visible event() QShowEvent

showFullScreen()¶

以小部件全屏模式显示。

调用此函数仅影响windows。

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

注意

全屏模式在Windows下工作良好，但在X下存在一些问题。这些问题是由于ICCCM协议的限制，该协议规定了X11客户端与窗口管理器之间的通信。ICCCM根本不理解无装饰全屏窗口的概念。因此，您能做的最好的事情就是请求一个无边框窗口，并将其放置和调整大小以填满整个屏幕。根据窗口管理器的不同，这可能有效也可能无效。无边框窗口是使用MOTIF提示请求的，几乎所有现代窗口管理器至少部分支持这些提示。

另一种方法是完全绕过窗口管理器，并使用Qt::X11BypassWindowManagerHint标志创建一个窗口。然而，这也会带来其他严重问题，比如键盘焦点失效，以及在桌面切换或用户提升其他窗口时出现非常奇怪的效果。

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

在macOS上，将窗口显示为全屏会将整个应用程序置于全屏模式，为其提供一个专用的桌面。在应用程序以全屏模式运行时显示另一个窗口可能会自动使该窗口也变为全屏。为了防止这种情况，可以通过调用showNormal()或通过close()在全屏窗口上退出全屏模式，然后再显示另一个窗口。

另请参阅

showNormal() showMaximized() show() isVisible() close()

showMaximized()¶

显示最大化的小部件。

调用此函数仅影响windows。

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

另请参阅

setWindowState() showNormal() showMinimized() show() hide() isVisible()

showMinimized()¶

将小部件最小化显示为图标。

调用此函数仅影响windows。

另请参阅

showNormal() showMaximized() show() hide() isVisible() isMinimized()

showNormal()¶

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

调用此函数仅影响windows。

另请参阅

setWindowState() showMinimized() showMaximized() show() hide() isVisible()

size()¶

Return type:

QSize

属性 sizeᅟ 的获取器。

sizeHint()¶

Return type:

QSize

属性 sizeHintᅟ 的获取器。

sizeIncrement()¶

Return type:

QSize

另请参阅

setSizeIncrement()

属性 sizeIncrementᅟ 的获取器。

sizePolicy()¶

Return type:

QSizePolicy

另请参阅

setSizePolicy()

属性 sizePolicyᅟ 的获取器。

stackUnder(w)¶

Parameters:

w – QWidget

将小部件放置在父小部件的堆栈中的w下方。

为了使这个工作，小部件本身和w必须是兄弟节点。

另请参阅

raise() lower()

statusTip()¶

Return type:

字符串

另请参阅

setStatusTip()

属性 statusTipᅟ 的获取器。

style()¶

Return type:

QStyle

另请参阅

setStyle() setStyle() style()

styleSheet()¶

Return type:

字符串

另请参阅

setStyleSheet()

属性 styleSheetᅟ 的获取器。

tabletEvent(event)¶

Parameters:

事件 – QTabletEvent

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

如果你重新实现这个处理程序，非常重要的一点是，如果你不处理该事件，你应该忽略()它，以便小部件的父级可以解释它。

默认实现忽略该事件。

如果平板跟踪关闭，平板移动事件仅在触控笔与平板接触或至少按下一个触控笔按钮时发生，同时触控笔正在移动。如果平板跟踪开启，平板移动事件即使在触控笔悬停在平板附近且没有按下任何按钮时也会发生。

另请参阅

event() setTabletTracking() QTabletEvent

testAttribute(attribute)¶

Parameters:

属性 – WidgetAttribute

Return type:

布尔

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

另请参阅

setAttribute()

toolTip()¶

Return type:

字符串

另请参阅

setToolTip()

属性 toolTipᅟ 的获取器。

toolTipDuration()¶

Return type:

整数

另请参阅

setToolTipDuration()

属性 toolTipDurationᅟ 的获取器。

topLevelWidget()¶

Return type:

QWidget

请使用window()代替。

underMouse()¶

Return type:

布尔

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

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

另请参阅

enterEvent() leaveEvent()

ungrabGesture(type)¶

Parameters:

类型 – GestureType

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

另请参阅

grabGesture() QGestureEvent

unsetCursor()¶

属性 cursorᅟ 的重置功能。

unsetLayoutDirection()¶

属性 layoutDirectionᅟ 的重置功能。

unsetLocale()¶

属性 localeᅟ 的重置功能。

update()¶

除非更新被禁用或小部件被隐藏，否则更新小部件。

此函数不会立即触发重绘；相反，它会在Qt返回到主事件循环时安排一个绘制事件进行处理。这使得Qt能够优化速度并减少闪烁，相比于直接调用repaint()。

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

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

另请参阅

repaint() paintEvent() setUpdatesEnabled() 模拟时钟

update(rect)

Parameters:

rect – QRect

这是一个重载函数。

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

update(rgn)

Parameters:

rgn – QRegion

这是一个重载函数。

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

update(x, y, w, h)

Parameters:

• x – 整数

• y – 整数

• w – 整数

• h – 整数

这是一个重载函数。

此版本更新了小部件内的一个矩形（x, y, w, h）。

updateGeometry()¶

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

如果sizeHint()或sizePolicy()发生了变化，请调用此函数。

对于明确隐藏的小部件，updateGeometry() 是一个无操作。一旦小部件显示出来，布局系统将立即收到通知。

updateMicroFocus([query=Qt.ImQueryAll])¶

Parameters:

查询 – InputMethodQuery

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

updatesEnabled()¶

Return type:

布尔

另请参阅

setUpdatesEnabled()

属性 updatesEnabledᅟ 的获取器。

visibleRegion()¶

Return type:

QRegion

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

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

如果必要，repaint() 函数会调用此函数，因此通常你不需要调用它。

whatsThis()¶

Return type:

字符串

另请参阅

setWhatsThis()

属性 whatsThisᅟ 的获取器。

wheelEvent(event)¶

Parameters:

事件 – QWheelEvent

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

如果你重新实现这个处理程序，非常重要的一点是，如果你不处理该事件，你应该忽略()它，以便小部件的父级可以解释它。

默认实现忽略该事件。

另请参阅

event() QWheelEvent

winId()¶

Return type:

WId

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

原则上可移植，但如果你使用它，你可能即将做一些不可移植的事情。请小心。

如果一个小部件是非原生的（外来的）并且在其上调用了winId()，那么该小部件将被提供一个原生句柄。

这个值可能在运行时发生变化。在窗口系统标识符发生变化后，将向小部件发送一个类型为QEvent::WinIdChange的事件。

另请参阅

find()

window()¶

Return type:

QWidget

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

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

典型用法是更改窗口标题：

aWidget.window().setWindowTitle("New Window Title")

另请参阅

isWindow()

windowFilePath()¶

Return type:

字符串

另请参阅

setWindowFilePath()

属性 windowFilePathᅟ 的获取器。

windowFlags()¶

Return type:

WindowType的组合

另请参阅

setWindowFlags()

windowHandle()¶

Return type:

QWindow

如果这是一个原生小部件，返回关联的QWindow。否则返回null。

原生小部件包括顶层小部件、QGLWidget 以及调用了 winId() 的子小部件。

另请参阅

winId() screen()

windowIcon()¶

Return type:

QIcon

另请参阅

setWindowIcon()

属性 windowIconᅟ 的获取器。

windowIconChanged(icon)¶

Parameters:

图标 – QIcon

当窗口的图标发生变化时，会发出此信号，新的icon作为参数。

属性 windowIconᅟ 的通知信号。

windowIconText()¶

Return type:

字符串

另请参阅

setWindowIconText()

属性 windowIconTextᅟ 的获取器。

windowIconTextChanged(iconText)¶

Parameters:

iconText – str

当窗口的图标文本发生变化时，会发出此信号，新的iconText作为参数。

此信号已弃用。

属性 windowIconTextᅟ 的通知信号。

windowModality()¶

Return type:

WindowModality

另请参阅

setWindowModality()

属性 windowModalityᅟ 的获取器。

windowOpacity()¶

Return type:

浮点数

另请参阅

setWindowOpacity()

windowRole()¶

Return type:

字符串

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

另请参阅

setWindowRole() windowIcon windowTitle

windowState()¶

Return type:

WindowState的组合

返回当前窗口状态。窗口状态是 Qt::WindowState 的按位或组合：Qt::WindowMinimized、Qt::WindowMaximized、Qt::WindowFullScreen 和 Qt::WindowActive。

另请参阅

setWindowState()

windowTitle()¶

Return type:

字符串

另请参阅

setWindowTitle()

属性 windowTitleᅟ 的获取器。

windowTitleChanged(title)¶

Parameters:

标题 – str

当窗口的标题发生变化时，会发出此信号，新的title作为参数。

属性 windowTitleᅟ 的通知信号。

windowType()¶

Return type:

WindowType

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

另请参阅

windowFlags

x()¶

Return type:

整数

属性 xᅟ 的获取器。

y()¶

Return type:

整数

属性 yᅟ 的获取器。