PySide6.QtWidgets.QProgressDialog

class QProgressDialog

QProgressDialog 类提供了关于缓慢操作进度的反馈。更多

PySide6.QtWidgets.QProgressDialog 的继承图

概要

属性

方法

插槽

信号

注意

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

详细描述

警告

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

进度对话框用于向用户指示操作需要多长时间,并证明应用程序没有冻结。它还可以给用户提供中止操作的机会。

进度对话框的一个常见问题是很难知道何时使用它们;操作在不同的硬件上花费的时间不同。QProgressDialog 提供了解决这个问题的方法:它估计操作将花费的时间(基于步骤的时间),并且仅在该估计超过 minimumDuration()(默认为4秒)时显示自己。

使用setMinimum()setMaximum()或构造函数来设置操作中的“步骤”数量,并在操作过程中调用setValue()。步骤数量可以任意选择。它可以是复制的文件数量、接收的字节数量、算法主循环的迭代次数,或其他合适的单位。进度从setMinimum()设置的值开始,当您使用setMaximum()设置的值作为参数调用setValue()时,进度对话框显示操作已完成。

对话框在操作结束时自动重置并隐藏自身。使用setAutoReset()setAutoClose()来更改此行为。请注意,如果您设置了一个新的最大值(使用setMaximum()setRange())并且该值等于当前的value(),则无论怎样对话框都不会关闭。

有两种使用QProgressDialog的方式:模态和非模态。

与无模式的QProgressDialog相比,模态的QProgressDialog对程序员来说使用起来更简单。在循环中执行操作,定期调用setValue(),并使用wasCanceled()检查是否取消。例如:

progress = QProgressDialog("Copying files...", "Abort Copy", 0, numFiles, self)
progress.setWindowModality(Qt.WindowModal)
for i in range(0, numFiles):
    progress.setValue(i)
    if progress.wasCanceled():
        break
    #... copy one file

progress.setValue(numFiles)

无模式进度对话框适用于在后台进行的操作,用户能够与应用程序进行交互。此类操作通常基于计时器类,如QChronoTimer(或更低级别的QObject::timerEvent())或QSocketNotifier;或在单独的线程中执行。在主窗口的状态栏中的QProgressBar通常是无模式进度对话框的替代方案。

你需要有一个正在运行的事件循环,将canceled()信号连接到一个停止操作的槽,并定期调用setValue()。例如:

# Operation constructor
def __init__(self, parent):
    super().__init__(parent)
    self.steps = 0

    pd = QProgressDialog("Operation in progress.", "Cancel", 0, 100)
    pd.canceled.connect(self.cancel)
    t = QTimer(self)
    t.timeout.connect(self.perform)
    t.start(0)

def perform(self):

    pd.setValue(steps)
    #... perform one percent of the operation
    steps += 1
    if steps > pd.maximum():
        t.stop()

def cancel(self):

    t.stop()
    #... cleanup

在这两种模式下,可以通过使用setLabel()setBar()setCancelButton()来替换子部件为自定义部件,从而自定义进度对话框。函数setLabelText()setCancelButtonText()用于设置显示的文本。

../../_images/fusion-progressdialog.png

另请参阅

QDialog QProgressBar

注意

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

property autoCloseᅟ: bool

此属性决定对话框是否会被reset()隐藏。

默认值为 true。

另请参阅

setAutoReset()

Access functions:
property autoResetᅟ: bool

此属性表示进度对话框是否在value()等于maximum()时立即调用reset()

默认值为 true。

另请参阅

setAutoClose()

Access functions:
property labelTextᅟ: str

此属性保存标签的文本。

默认文本是一个空字符串。

Access functions:
property maximumᅟ: int

此属性表示进度条所代表的最高值。

默认值为100。

另请参阅

minimum setRange()

Access functions:
property minimumᅟ: int

此属性表示进度条所代表的最低值。

默认值为0。

另请参阅

maximum setRange()

Access functions:
property minimumDurationᅟ: int

此属性保存对话框出现前必须经过的时间。

如果任务的预期持续时间小于minimumDuration,对话框将不会出现。这可以防止对话框在任务快速完成时弹出。对于预期超过minimumDuration的任务,对话框将在minimumDuration时间后或一旦设置了任何进度时弹出。

如果设置为0,对话框将在任何进度设置时立即显示。默认值为4000毫秒。

Access functions:
property valueᅟ: int

此属性保存当前完成的进度量。

为了使进度对话框按预期工作,您应首先将此属性设置为minimum(),最后将其设置为maximum();在此过程中,您可以多次调用setValue()。

警告

如果进度对话框是模态的(参见QProgressDialog()),setValue()会调用QCoreApplication::processEvents(),因此请注意这不会导致代码中出现不良的重新进入。例如,不要在paintEvent()内部使用QProgressDialog

另请参阅

minimum maximum

Access functions:
property wasCanceledᅟ: bool

此属性表示对话框是否被取消。

Access functions:
__init__([parent=None[, flags=Qt.WindowFlags()]])
Parameters:

构建一个进度对话框。

默认设置:

  • 标签文本为空。

  • 取消按钮的文本是(翻译)“取消”。

  • 最小值为0;

  • 最大值为100

parent 参数是对话框的父部件。部件标志 f 被传递给 QDialog() 构造函数。

__init__(labelText, cancelButtonText, minimum, maximum[, parent=None[, flags=Qt.WindowFlags()]])
Parameters:
  • labelText – str

  • cancelButtonText – str

  • minimum – int

  • maximum – 整数

  • parentQWidget

  • flagsWindowType 的组合

构建一个进度对话框。

labelText 是用于提醒用户当前进度的文本。

cancelButtonText 是显示在取消按钮上的文本。如果传递了 QString(),则不会显示取消按钮。

minimummaximum 是操作中此进度对话框显示进度的步骤数。例如,如果操作是检查50个文件,此最小值将为0,最大值将为50。在检查第一个文件之前,调用 setValue (0)。当每个文件被处理时,调用 setValue (1), setValue (2), 等等,最后在检查完最后一个文件后调用 setValue (50)。

parent 参数是对话框的父部件。父部件 parent 和部件标志 f 被传递给 QDialog() 构造函数。

autoClose()
Return type:

布尔

另请参阅

setAutoClose()

属性 autoCloseᅟ 的获取器。

autoReset()
Return type:

布尔

另请参阅

setAutoReset()

属性 autoResetᅟ 的获取器。

cancel()

重置进度对话框。wasCanceled() 变为 true,直到进度对话框被重置。进度对话框变为隐藏。

canceled()

当点击取消按钮时,会发出此信号。默认情况下,它连接到cancel()槽。

另请参阅

wasCanceled()

forceShow()

如果算法启动后对话框仍然隐藏,并且已经过了minimumDuration毫秒,则显示对话框。

另请参阅

setMinimumDuration()

labelText()
Return type:

字符串

另请参阅

setLabelText()

属性 labelTextᅟ 的获取器。

maximum()
Return type:

整数

另请参阅

setMaximum()

属性 maximumᅟ 的获取器。

minimum()
Return type:

整数

另请参阅

setMinimum()

属性 minimumᅟ 的获取器。

minimumDuration()
Return type:

整数

另请参阅

setMinimumDuration()

属性 minimumDurationᅟ 的获取器。

open(receiver, member)
Parameters:
  • receiverQObject

  • member – str

打开对话框并将其canceled()信号连接到由receivermember指定的槽。

当对话框关闭时,信号将从插槽断开。

reset()

重置进度对话框。如果autoClose()为true,进度对话框将变为隐藏。

setAutoClose(close)
Parameters:

close – 布尔值

另请参阅

autoClose()

属性 autoCloseᅟ 的设置器。

setAutoReset(reset)
Parameters:

reset – 布尔值

另请参阅

autoReset()

属性 autoResetᅟ 的设置器。

setBar(bar)
Parameters:

barQProgressBar

将进度条小部件设置为bar。进度对话框会调整大小以适应。进度对话框会取得进度条bar的所有权,必要时会删除它,因此不要使用在栈上分配的进度条。

setCancelButton(button)
Parameters:

按钮QPushButton

将取消按钮设置为按钮,cancelButton。进度对话框将拥有此按钮的所有权,必要时会删除它,因此不要传递栈上对象的地址,即使用new()创建按钮。如果传递None,则不会显示取消按钮。

另请参阅

setCancelButtonText()

setCancelButtonText(text)
Parameters:

文本 – str

将取消按钮的文本设置为cancelButtonText。如果文本设置为QString(),则会导致取消按钮被隐藏并删除。

另请参阅

setCancelButton()

setLabel(label)
Parameters:

标签QLabel

将标签设置为label。进度对话框会调整大小以适应。标签将由进度对话框拥有,并在必要时删除,因此不要传递堆栈上对象的地址。

另请参阅

setLabelText()

setLabelText(text)
Parameters:

文本 – str

另请参阅

labelText()

属性 labelTextᅟ 的设置器。

setMaximum(maximum)
Parameters:

最大值 – int

另请参阅

maximum()

属性 maximumᅟ 的设置器。

setMinimum(minimum)
Parameters:

最小值 – int

另请参阅

minimum()

属性 minimumᅟ 的设置器。

setMinimumDuration(ms)
Parameters:

ms – 整数

另请参阅

minimumDuration()

属性 minimumDurationᅟ 的设置器。

setRange(minimum, maximum)
Parameters:
  • minimum – int

  • maximum – 整数

将进度对话框的最小值和最大值分别设置为 minimummaximum

如果 maximum 小于 minimumminimum 将成为唯一合法的值。

如果当前值超出新范围,进度对话框将使用reset()重置。

另请参阅

minimum maximum

setValue(progress)
Parameters:

progress – 整数

另请参阅

value()

属性 valueᅟ 的设置器。

value()
Return type:

整数

另请参阅

setValue()

属性 valueᅟ 的获取器。

wasCanceled()
Return type:

布尔

属性 wasCanceledᅟ 的获取器。