`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
指定進度列控制項的識別碼。

傳回值

如果成功建立物件，則為 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 樣式的清單，請參閱 dwExStyle Windows SDK 中的參數 CreateWindowEx 。

dwStyle
指定進度列控制項的樣式。套用 Windows SDK 中所述 CreateWindow 的任何視窗樣式組合。

rect
結構的參考 RECT ，描述要建立之視窗的大小和位置，在的用戶端座標中 pParentWnd 。

pParentWnd
控制項父系之視窗的指標。

nID
控制項的子視窗識別碼。

傳回值

如果成功則為非零；否則為 0。

備註

使用 CreateEx 而不是 Create 套用延伸的 Windows 樣式，由 Windows 擴充樣式前置詞 WS_EX_ 所指定。

`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
接收進度列控制項上限之整數的參考。

備註

此函式會將下限和上限的值分別複製到和 nUpper 所參考的 nLower 整數。

範例

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 進度指標列的色彩是預設色彩，則為。

備註

SetBarColor只有在 Windows Vista 主題沒有作用時，方法才會設定進度列色彩。

這個方法會傳送 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;

下一個程式碼範例會將目前進度列控制項的狀態設定為 Paused 或 In Progress。

// 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`