`CProgressCtrl` 类

项目
10/12/2023

提供 Windows 公共进度栏控件的功能。

语法

class CProgressCtrl : public CWnd

成员

公共构造函数

名称	描述
`CProgressCtrl::CProgressCtrl`	构造 `CProgressCtrl` 对象。

公共方法

名称	描述
`CProgressCtrl::Create`	创建进度栏控件并将其附加到 `CProgressCtrl` 对象。
`CProgressCtrl::CreateEx`	创建具有指定 Windows 扩展样式的进度控件，并将其附加到 `CProgressCtrl` 对象。
`CProgressCtrl::GetBarColor`	获取当前进度栏控件的进度指示器栏的颜色。
`CProgressCtrl::GetBkColor`	获取当前进度栏的背景色。
`CProgressCtrl::GetPos`	获取进度栏的当前位置。
`CProgressCtrl::GetRange`	获取进度栏控件范围的下限和上限。
`CProgressCtrl::GetState`	获取当前进度栏控件的状态。
`CProgressCtrl::GetStep`	检索当前进度栏控件的进度栏的步骤增量。
`CProgressCtrl::OffsetPos`	按指定增量推进进度栏控件的当前位置，并重绘进度栏以反映新位置。
`CProgressCtrl::SetBarColor`	设置当前进度栏控件的进度指示器栏的颜色。
`CProgressCtrl::SetBkColor`	设置进度栏的背景色。
`CProgressCtrl::SetMarquee`	打开或关闭当前进度栏控件的字幕模式。
`CProgressCtrl::SetPos`	设置进度栏控件的当前位置，并重绘进度栏以反映新位置。
`CProgressCtrl::SetRange`	设置进度栏控件的最小和最大范围，并重绘进度栏以反映新范围。
`CProgressCtrl::SetState`	设置当前进度栏控件的状态。
`CProgressCtrl::SetStep`	指定进度栏控件的步骤增量。
`CProgressCtrl::StepIt`	按步骤增量（请参阅 `SetStep`）推进进度栏控件的当前位置，并重绘进度栏以反映新位置。

注解

进度栏控件是应用程序可用于指示长时间操作的进度的窗口。该控件包含一个矩形，通过让系统亮色逐渐填充（从左到右）来显示操作进度。

进度栏控件具有范围和当前位置。该范围表示操作的总持续时间，当前位置表示应用程序完成操作的进度。窗口过程使用该范围和当前位置来确定进度栏的百分比，以便用亮色进行填充。由于该范围和当前位置值用带符号整数表示，因此当前位置值的可能范围为 -2,147,483,648 至 2,147,483,647（含）。

有关使用 CProgressCtrl 的详细信息，请参阅控件和使用 CProgressCtrl。

继承层次结构

CObject

CCmdTarget

CWnd

CProgressCtrl

要求

标头：afxcmn.h

`CProgressCtrl::CProgressCtrl`

构造 CProgressCtrl 对象。

CProgressCtrl();

备注

构造 CProgressCtrl 对象后，调用 CProgressCtrl::Create 以创建进度栏控件。

示例

// Create a progress control object on the stack.
CProgressCtrl myCtrl;

// Create a progress control object on the heap.
CProgressCtrl *pmyCtrl = new CProgressCtrl;

`CProgressCtrl::Create`

创建进度栏控件并将其附加到 CProgressCtrl 对象。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwStyle
指定进度栏控件的样式。除了以下进度栏控件样式外，还对控件应用 Windows SDK 中的 CreateWindow 中描述的窗口样式的任意组合：

PBS_VERTICAL 垂直显示进度信息，从上到下。如果没有此标志，进度栏控件将水平显示，从左到右。
PBS_SMOOTH 显示进度栏控件中逐步、平滑的填充。如果没有此标志，控件中将填充块。

rect
指定状态栏控件的大小和位置。它可以是 CRect 对象或 RECT 结构。由于控件必须是子窗口，因此指定的坐标相对于 pParentWnd 的工作区。

pParentWnd
指定进度栏控件的父窗口，通常为 CDialog。不得为 NULL。

nID
指定进度栏控件的 ID。

返回值

如果成功创建 CProgressCtrl 对象，则为 TRUE；否则为 FALSE。

备注

请分两步构造 CProgressCtrl 对象。首先，调用构造函数，这将创建 CProgressCtrl 对象，然后调用 Create这将创建进度栏控件。

示例

CProgressCtrl myCtrl;

// Create a smooth child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE | PBS_SMOOTH, CRect(10, 10, 200, 30),
              pParentWnd, IDC_PROGRESSCTRL);

`CProgressCtrl::CreateEx`

创建一个控件（子窗口）并将其与 CProgressCtrl 对象相关联。

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
指定进度栏控件的样式。应用 Windows SDK 中的 CreateWindow 中所述的窗口样式的任意组合。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

使用 CreateEx（而不是 Create）应用由 Windows 扩展样式前缀 WS_EX_ 指定的扩展 Windows 样式。

`CProgressCtrl::GetBarColor`

获取当前进度栏控件的进度指示器栏的颜色。

COLORREF GetBarColor() const;

返回值

当前进度栏的颜色，表示为 COLORREF 值，或者，如果进度指示器栏颜色是默认颜色，则表示为 CLR_DEFAULT。

备注

此方法将发送 PBM_GETBARCOLOR 消息，如 Windows SDK 中所述。

`CProgressCtrl::GetBkColor`

获取当前进度栏的背景色。

COLORREF GetBkColor() const;

返回值

当前进度栏的背景色，表示为 COLORREF 值。

备注

此方法将发送 PBM_GETBKCOLOR 消息，如 Windows SDK 中所述。

`CProgressCtrl::GetPos`

检索进度栏的当前位置。

int GetPos();

返回值

进度栏控件的位置。

注解

进度栏控件的位置不是屏幕上的物理位置，而是位于 SetRange 中指示的上限和下限范围之间。

示例

CProgressCtrl myCtrl;

// Create a child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE, CRect(10, 10, 200, 30), pParentWnd,
              IDC_PROGRESSCTRL);

// Set the new position to half of the current position.
myCtrl.SetPos(myCtrl.GetPos() / 2);

`CProgressCtrl::GetRange`

获取进度栏控件的下限和上限，即范围。

void GetRange(
    int& nLower,
    int& nUpper);

参数

nLower
对接收进度栏控件下限的整数的引用。

nUpper
对接收进度栏控件上限的整数的引用。

备注

此函数将下限和上限的值分别复制到 nLower 和 nUpper 。

示例

CProgressCtrl myCtrl;

// Create a child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE, CRect(10, 10, 200, 30), pParentWnd,
              IDC_PROGRESSCTRL);

// Set the position to be one-fourth of the total range.
int nLower, nUpper;
myCtrl.GetRange(nLower, nUpper);
myCtrl.SetPos((nUpper - nLower) / 4);

`CProgressCtrl::GetState`

获取当前进度栏控件的状态。

int GetState() const;

返回值

当前进度栏控件的状态，该状态是以下值之一：

值	状态
PBST_NORMAL	正在进行
PBST_ERROR	错误
PBST_PAUSED	已暂停

备注

此方法将发送 PBM_GETSTATE 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_progressCtrl，该变量用于以编程方式访问进度栏控件。此变量将在下一个示例中使用。

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

下一个代码示例检索当前进度栏控件的状态。

// Display the current state of the progress control.
CString str = _T("The progress control state is ");
int progState = m_progressCtrl.GetState();
if (progState == PBST_NORMAL)
   str += _T("NORMAL");
else if (progState == PBST_PAUSED)
   str += _T("PAUSED");
else if (progState == PBST_ERROR)
   str += _T("ERROR");
else
   str += _T("unknown");
AfxMessageBox(str, MB_ICONEXCLAMATION);

`CProgressCtrl::GetStep`

检索当前进度栏控件的进度栏的步骤增量。

int GetStep() const;

返回值

进度栏的步骤增量。

备注

步骤增量是对 CProgressCtrl::StepIt 的调用将进度栏的当前位置推进的量。

此方法将发送 PBM_GETSTEP 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_progressCtrl，该变量用于以编程方式访问进度栏控件。此变量将在下一个示例中使用。

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

下一个代码示例检索当前进度栏控件的步骤增量。

// Get the step increment for the progress control.
CString str;
int incr = m_progressCtrl.GetStep();
str.Format(_T("The step increment is %d."), incr);
AfxMessageBox(str, MB_ICONEXCLAMATION);

`CProgressCtrl::OffsetPos`

按 nPos 指定的增量推进进度栏控件的当前位置，并重绘进度栏以反映新位置。

int OffsetPos(int nPos);

参数

nPos
将位置推进的量。

返回值

进度栏控件的上一个位置。

示例

CProgressCtrl myCtrl;

// Create a child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE, CRect(10, 10, 200, 30), pParentWnd,
              IDC_PROGRESSCTRL);

// Offset the position by one-fourth of the total range.
int nLower, nUpper;
myCtrl.GetRange(nLower, nUpper);
myCtrl.OffsetPos((nUpper - nLower) / 4);

`CProgressCtrl::SetBarColor`

设置当前进度栏控件的进度指示器栏的颜色。

COLORREF SetBarColor(COLORREF clrBar);

参数

clrBar
[in] 一个 COLORREF 值，该值指定进度指示器栏的新颜色。指定 CLR_DEFAULT 以使进度栏使用其默认颜色。

返回值

进度指示器栏的上一个颜色，表示为 COLORREF 值，或者，如果进度指示器栏的颜色是默认颜色，则表示为 CLR_DEFAULT。

备注

仅当 Windows Vista 主题无效时，SetBarColor 方法才会设置进度栏颜色。

此方法将发送 PBM_SETBARCOLOR 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_progressCtrl，该变量用于以编程方式访问进度栏控件。此变量将在下一个示例中使用。

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

下一个代码示例将进度栏的颜色更改为红色、绿色、蓝色或默认颜色。

// Set the progress bar color to red, green, blue, or
// the system default. The SetBarColor method has an
// effect only if the Windows system theme is Classic.
void CCProgressCtrl_s1Dlg::OnSetbarcolorRed()
{
   m_progressCtrl.SetBarColor(RGB(255, 0, 0));
}

void CCProgressCtrl_s1Dlg::OnSetbarcolorGreen()
{
   m_progressCtrl.SetBarColor(RGB(0, 255, 0));
}

void CCProgressCtrl_s1Dlg::OnSetbarcolorBlue()
{
   m_progressCtrl.SetBarColor(RGB(0, 0, 255));
}

void CCProgressCtrl_s1Dlg::OnSetbarcolorOri()
{
   m_progressCtrl.SetBarColor(CLR_DEFAULT);
}

`CProgressCtrl::SetBkColor`

设置进度栏的背景色。

COLORREF SetBkColor(COLORREF clrNew);

参数

clrNew
一个指定新背景色的 COLORREF 值。指定 CLR_DEFAULT 值以使用进度栏的默认背景色。

返回值

指示上一个背景色的 COLORREF 值，或者，如果背景色是默认颜色，则为 CLR_DEFAULT。

示例

CProgressCtrl myCtrl;

// Create a smooth child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE | PBS_SMOOTH, CRect(10, 10, 200, 30),
              pParentWnd, IDC_PROGRESSCTRL);

// Set the background color to red.
myCtrl.SetBkColor(RGB(255, 0, 0));

`CProgressCtrl::SetMarquee`

打开或关闭当前进度栏控件的字幕模式。

BOOL SetMarquee(
    BOOL fMarqueeMode,
    int nInterval);

参数

fMarqueeMode
[in] 若要打开字幕模式，则为 TRUE若要关闭字幕模式，则为 FALSE。

nInterval
[in] 更新字幕动画之间的时间（以毫秒为单位）。

返回值

此方法始终返回 TRUE。

注解

打开字幕模式后，进度栏会进行动画处理，并像剧院字幕上的标志一样滚动。

此方法将发送 PBM_SETMARQUEE 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_progressCtrl，该变量用于以编程方式访问进度栏控件。此变量将在下一个示例中使用。

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

下一个代码示例将启动并停止字幕滚动动画。

// Turn the marquee animation on or off.
void CCProgressCtrl_s1Dlg::OnSetmarqueeOn()
{
   m_progressCtrl.SetMarquee(TRUE, nMarqueeInterval);
}

void CCProgressCtrl_s1Dlg::OnSetmarqueeOff()
{
   m_progressCtrl.SetMarquee(FALSE, nMarqueeInterval);
}

`CProgressCtrl::SetPos`

按 nPos 的指定来设置进度栏控件的当前位置，并重绘控制栏以体现新位置。

int SetPos(int nPos);

参数

nPos
进度栏控件的新位置。

返回值

进度栏控件的上一个位置。

注解

进度栏控件的位置不是屏幕上的物理位置，而是位于 SetRange 中指示的上限和下限范围之间。

示例

CProgressCtrl myCtrl;

// Create a child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE, CRect(10, 10, 200, 30), pParentWnd,
              IDC_PROGRESSCTRL);

// Set the range to be 0 to 100.
myCtrl.SetRange(0, 100);

// Set the position to be half, 50.
myCtrl.SetPos(50);

`CProgressCtrl::SetRange`

设置进度栏控件范围的上限和下限，并重绘进度栏以反映新范围。

void SetRange(
    short nLower,
    short nUpper);

void SetRange32(
    int nLower,
    int nUpper);

参数

nLower
指定范围的下限（默认值为零）。

nUpper
指定范围的上限（默认值为 100）。

备注

成员函数 SetRange32 设置进度控件的 32 位范围。

示例

CProgressCtrl myCtrl;

// Create a smooth child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE | PBS_SMOOTH, CRect(10, 10, 200, 30),
              pParentWnd, IDC_PROGRESSCTRL);

// Set the range to be 0 to 100.
myCtrl.SetRange(0, 100);

`CProgressCtrl::SetState`

设置当前进度栏控件的状态。

int SetState(int iState);

参数

iState
[in] 要将进度栏设置到的状态。使用以下值之一：

PBST_NORMAL - 正在进行
PBST_ERROR - 错误
PBST_PAUSED - 已暂停

返回值

当前进度栏控件的前一个状态。

备注

此方法将发送 PBM_SETSTATE 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义变量 m_progressCtrl，该变量用于以编程方式访问进度栏控件。此变量将在下一个示例中使用。

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

下一个代码示例将当前进度栏控件的状态设置为“已暂停”或“正在进行”。

// Set the progrees control to normal or paused state.
void CCProgressCtrl_s1Dlg::OnSetstateNormal()
{
   m_progressCtrl.SetState(PBST_NORMAL);
}

void CCProgressCtrl_s1Dlg::OnSetstatePaused()
{
   m_progressCtrl.SetState(PBST_PAUSED);
}

`CProgressCtrl::SetStep`

指定进度栏控件的步骤增量。

int SetStep(int nStep);

参数

nStep
新步骤增量。

返回值

上一个步骤增量。

注解

步骤增量是对 CProgressCtrl::StepIt 的调用将进度栏的当前位置推进的量。

默认步骤增量为 10。

示例

CProgressCtrl myCtrl;

// Create a child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE, CRect(10, 10, 200, 30), pParentWnd,
              IDC_PROGRESSCTRL);

// Set the size to be 1/10 of the total range.
int nLower, nUpper;
myCtrl.GetRange(nLower, nUpper);
myCtrl.SetStep((nUpper - nLower) / 10);

`CProgressCtrl::StepIt`

按步骤增量推进进度栏控件的当前位置，并重绘进度栏以反映新位置。

int StepIt();

返回值

进度栏控件的上一个位置。

备注

步骤增量由 CProgressCtrl::SetStep 成员函数设置。

示例

CProgressCtrl myCtrl;

// Create a child progress control.
myCtrl.Create(WS_CHILD | WS_VISIBLE, CRect(10, 10, 200, 30), pParentWnd,
              IDC_PROGRESSCTRL);

// Advance the position to the next step.
myCtrl.StepIt();

另请参阅

MFC 示例 CMNCTRL2
CWnd 类
 层次结构图

通过

CProgressCtrl 类

语法

成员

公共构造函数

公共方法

注解

继承层次结构

要求

CProgressCtrl::CProgressCtrl

备注

示例

CProgressCtrl::Create

参数

返回值

备注

示例

CProgressCtrl::CreateEx

参数

返回值

备注

CProgressCtrl::GetBarColor

返回值

备注

CProgressCtrl::GetBkColor

返回值

备注

CProgressCtrl::GetPos

返回值

注解

示例

CProgressCtrl::GetRange

参数

备注

示例

CProgressCtrl::GetState

返回值

备注

示例

CProgressCtrl::GetStep

返回值

备注

示例

CProgressCtrl::OffsetPos

参数

返回值

示例

CProgressCtrl::SetBarColor

参数

返回值

备注

示例

CProgressCtrl::SetBkColor

参数

返回值

示例

CProgressCtrl::SetMarquee

参数

返回值

注解

示例

CProgressCtrl::SetPos

参数

返回值

注解

示例

CProgressCtrl::SetRange

参数

备注

示例

CProgressCtrl::SetState

参数

返回值

备注

示例

CProgressCtrl::SetStep

参数

返回值

注解

示例

`CProgressCtrl` 类

`CProgressCtrl::CProgressCtrl`

`CProgressCtrl::Create`

`CProgressCtrl::CreateEx`

`CProgressCtrl::GetBarColor`

`CProgressCtrl::GetBkColor`

`CProgressCtrl::GetPos`

`CProgressCtrl::GetRange`

`CProgressCtrl::GetState`

`CProgressCtrl::GetStep`

`CProgressCtrl::OffsetPos`

`CProgressCtrl::SetBarColor`

`CProgressCtrl::SetBkColor`

`CProgressCtrl::SetMarquee`

`CProgressCtrl::SetPos`

`CProgressCtrl::SetRange`

`CProgressCtrl::SetState`

`CProgressCtrl::SetStep`

`CProgressCtrl::StepIt`