`CProgressCtrl` 類別

發行項
07/05/2024

提供 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`