Класс `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
Задает стиль элемента управления индикатора выполнения. Примените любое сочетание стилей окон, указанных в CreateWindow пакете SDK для Windows, помимо следующих стилей элементов управления индикатора выполнения, к элементу управления:

PBS_VERTICAL Отображает сведения о ходе выполнения по вертикали, сверху вниз. Без этого флага элемент управления индикатора хода выполнения отображается горизонтально слева направо.
PBS_SMOOTH Отображает постепенное, плавное заполнение элемента управления индикатора выполнения. Без этого флага элемент управления заполняется блоками.

rect
Задает размер и позицию элемента управления индикатора выполнения. Это может быть CRect объект или RECT структура. Поскольку элемент управления должен быть дочерним окном, указанные координаты относятся к клиентской pParentWndобласти.

pParentWnd
Указывает родительское окно элемента управления индикатора хода выполнения, как правило, значение CDialog. Он не должен иметь значение NULL.

nID
Указывает идентификатор элемента управления индикатора выполнения.

Возвращаемое значение

ЗНАЧЕНИЕ TRUE, если CProgressCtrl объект успешно создан; в противном случае — ЗНАЧЕНИЕ 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 . в параметре CreateWindowEx пакета SDK для Windows.

dwStyle
Задает стиль элемента управления индикатора выполнения. Примените любое сочетание стилей окон, описанных в CreateWindow пакете SDK для Windows.

rect
Ссылка на RECT структуру, описывающую размер и положение создаваемого окна в координатах pParentWndклиента.

pParentWnd
Указатель на окно, которое является родительским элементом элемента управления.

nID
Идентификатор дочернего окна элемента управления.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Используйте CreateEx вместо Create применения расширенных стилей Windows, указанных предисловием WS_EX_расширенного стиля Windows.

`CProgressCtrl::GetBarColor`

Возвращает цвет индикатора хода выполнения для текущего элемента управления индикатора хода выполнения.

COLORREF GetBarColor() const;

Возвращаемое значение

Цвет текущей панели хода выполнения, представленной в виде COLORREF значения, или CLR_DEFAULT если цвет индикатора хода выполнения является цветом по умолчанию.

Замечания

Этот метод отправляет PBM_GETBARCOLOR сообщение, описанное в пакете SDK для Windows.

`CProgressCtrl::GetBkColor`

Возвращает цвет фона текущей панели хода выполнения.

COLORREF GetBkColor() const;

Возвращаемое значение

Цвет фона текущей панели хода выполнения, представленный COLORREF в виде значения.

Замечания

Этот метод отправляет PBM_GETBKCOLOR сообщение, описанное в пакете SDK для Windows.

`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 сообщение, описанное в пакете SDK для Windows.

Пример

Первый пример кода определяет переменную, 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 сообщение, описанное в пакете SDK для Windows.

Пример

// 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 сообщение, описанное в пакете SDK для Windows.

Пример

// 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] Время в миллисекундах между обновлениями анимации marquee.

Возвращаемое значение

Этот метод всегда возвращает значение TRUE.

Замечания

При включении режима marquee индикатор хода выполнения анимируется и прокручивается, как знак в театре.

Этот метод отправляет PBM_SETMARQUEE сообщение, описанное в пакете SDK для Windows.

Пример

// 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
Новая позиция элемента управления индикатора хода выполнения.

Возвращаемое значение

Предыдущая позиция элемента управления индикатора выполнения.

Замечания

Пример

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 сообщение, описанное в пакете SDK для Windows.

Пример

// 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::StepIt

Класс `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`