Classe `CProgressCtrl`

Artigo
10/12/2023

Fornece a funcionalidade do controle de barra de progresso comum do Windows.

Sintaxe

class CProgressCtrl : public CWnd

Membros

Construtores públicos

Nome	Descrição
`CProgressCtrl::CProgressCtrl`	Constrói um objeto `CProgressCtrl`.

Métodos públicos

Nome	Descrição
`CProgressCtrl::Create`	Cria um controle de barra de progresso e o anexa a um objeto `CProgressCtrl`.
`CProgressCtrl::CreateEx`	Cria um controle de progresso com os estilos estendidos especificados do Windows e o anexa a um objeto `CProgressCtrl`.
`CProgressCtrl::GetBarColor`	Obtém a cor da barra de indicadores de progresso para o controle da barra de progresso atual.
`CProgressCtrl::GetBkColor`	Obtém a cor da tela de fundo da barra de progresso atual.
`CProgressCtrl::GetPos`	Obtém a posição atual da barra de progresso.
`CProgressCtrl::GetRange`	Obtém os limites inferior e superior do intervalo do controle da barra de progresso.
`CProgressCtrl::GetState`	Obtém o estado do controle da barra de progresso atual.
`CProgressCtrl::GetStep`	Recupera o incremento de etapa da barra de progresso do controle da barra de progresso atual.
`CProgressCtrl::OffsetPos`	Avança a posição atual de um controle de barra de progresso por um incremento especificado e redesenha a barra para refletir a nova posição.
`CProgressCtrl::SetBarColor`	Define a cor da barra de indicadores de progresso no controle da barra de progresso atual.
`CProgressCtrl::SetBkColor`	Define a cor da tela de fundo da barra de progresso.
`CProgressCtrl::SetMarquee`	Ativa ou desativa o modo de letreiro do controle da barra de progresso atual.
`CProgressCtrl::SetPos`	Define a posição atual de um controle de barra de progresso e redesenha a barra para refletir a nova posição.
`CProgressCtrl::SetRange`	Define os intervalos mínimo e máximo para um controle de barra de progresso e redesenha a barra para refletir os novos intervalos.
`CProgressCtrl::SetState`	Define o estado do controle da barra de progresso atual.
`CProgressCtrl::SetStep`	Especifica o incremento de etapa para um controle de barra de progresso.
`CProgressCtrl::StepIt`	Avança a posição atual de um controle de barra de progresso pelo incremento de etapa (consulte `SetStep`) e redesenha a barra para refletir a nova posição.

Comentários

O controle da barra de progresso é uma janela que um aplicativo pode usar para indicar o progresso de uma operação demorada. Ele consiste em um retângulo que é gradualmente preenchido da esquerda para a direita com a cor de realce do sistema à medida que uma operação progride.

Um controle de barra de progresso tem um intervalo e uma posição atual. O intervalo representa a duração total da operação e a posição atual representa o progresso que o aplicativo fez para concluir a operação. O procedimento de janela usa o intervalo e a posição atual para determinar a porcentagem da barra de progresso a ser preenchida com a cor de realce. Como os valores de posição atual e intervalo são expressos como inteiros com sinal, o intervalo possível de valores da posição atual é de -2.147.483.648 a 2.147.483.647, inclusive.

Para obter mais informações sobre como usar CProgressCtrl, consulte Controles e Usar CProgressCtrl.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CProgressCtrl

Requisitos

Cabeçalho: afxcmn.h

`CProgressCtrl::CProgressCtrl`

Constrói um objeto CProgressCtrl.

CProgressCtrl();

Comentários

Depois de construir o objeto CProgressCtrl, chame CProgressCtrl::Create para criar o controle da barra de progresso.

Exemplo

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

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

`CProgressCtrl::Create`

Cria um controle de barra de progresso e o anexa a um objeto CProgressCtrl.

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

Parâmetros

dwStyle
Especifica o estilo do controle da barra de progresso. Aplique qualquer combinação de estilos de janela descritos em CreateWindow no SDK do Windows, além dos seguintes estilos de controle de barra de progresso, ao controle:

PBS_VERTICAL Exibe informações de progresso verticalmente, de cima para baixo. Sem esse sinalizador, o controle da barra de progresso é exibido horizontalmente, da esquerda para a direita.
PBS_SMOOTH Exibe o preenchimento gradual e suave no controle da barra de progresso. Sem esse sinalizador, o controle será preenchido com blocos.

rect
Especifica o tamanho e a posição do controle da barra de progresso. Pode ser um objeto CRect ou uma estrutura RECT. Como o controle deve ser uma janela filho, as coordenadas especificadas são relativas à área do cliente do pParentWnd.

pParentWnd
Especifica a janela pai do controle da barra de progresso, geralmente um CDialog. Não pode ser NULL.

nID
Especifica a ID do controle da barra de progresso.

Valor de retorno

TRUE se o objeto CProgressCtrl for criado com êxito; caso contrário, FALSE.

Comentários

Um objeto CProgressCtrl é construído em duas etapas. Primeiro, chame o construtor, que criará o objeto CProgressCtrl e, em seguida, chame Create, que criará o controle da barra de progresso.

Exemplo

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`

Cria um controle (uma janela filho) e o associa ao objeto CProgressCtrl.

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

Parâmetros

dwExStyle
Especifica o estilo estendido do controle que está sendo criado. Para obter uma lista de estilos estendidos do Windows, consulte o parâmetro dwExStyle para CreateWindowEx no SDK do Windows.

dwStyle
Especifica o estilo do controle da barra de progresso. Aplique qualquer combinação de estilos de janela descritos em CreateWindow no SDK do Windows.

rect
Uma referência a uma estrutura RECT que descreve o tamanho e a posição da janela a ser criada, nas coordenadas de cliente de pParentWnd.

pParentWnd
Um ponteiro para a janela que é pai do controle.

nID
A ID da janela filho do controle.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Use CreateEx, em vez de Create, para aplicar estilos estendidos do Windows, especificados pelo prefácio WS_EX_ de estilos estendidos do Windows.

`CProgressCtrl::GetBarColor`

Obtém a cor da barra de indicadores de progresso para o controle da barra de progresso atual.

COLORREF GetBarColor() const;

Valor de retorno

A cor da barra de progresso atual, representada como um valor COLORREF, ou CLR_DEFAULT se a cor da barra de indicadores de progresso for a cor padrão.

Comentários

Esse método envia a mensagem PBM_GETBARCOLOR, que é descrita no SDK do Windows.

`CProgressCtrl::GetBkColor`

Obtém a cor da tela de fundo da barra de progresso atual.

COLORREF GetBkColor() const;

Valor de retorno

A cor da tela de fundo da barra de progresso atual, representada como um valor COLORREF.

Comentários

Esse método envia a mensagem PBM_GETBKCOLOR, que é descrita no SDK do Windows.

`CProgressCtrl::GetPos`

Recupera a posição atual da barra de progresso.

int GetPos();

Valor de retorno

A posição do controle da barra de progresso.

Comentários

A posição do controle da barra de progresso não é o local físico na tela, mas sim entre o intervalo superior e inferior indicado em SetRange.

Exemplo

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`

Obtém os limites inferior e superior atuais, ou intervalo, do controle da barra de progresso.

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

Parâmetros

nLower
Uma referência a um inteiro que recebe o limite inferior do controle da barra de progresso.

nUpper
Uma referência a um inteiro que recebe o limite superior do controle da barra de progresso.

Comentários

Essa função copia os valores dos limites inferior e superior para os inteiros referenciados por nLower e nUpper, respectivamente.

Exemplo

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`

Obtém o estado do controle da barra de progresso atual.

int GetState() const;

Valor de retorno

O estado do controle da barra de progresso atual, que é um dos seguintes valores:

Valor	Estado
PBST_NORMAL	Em andamento
PBST_ERROR	Erro
PBST_PAUSED	Pausada

Comentários

Esse método envia a mensagem PBM_GETSTATE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável m_progressCtrl, que é usada para acessar programaticamente o controle da barra de progresso. Essa variável será usada no próximo exemplo.

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

O próximo exemplo de código recupera o estado do controle da barra de progresso atual.

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

Recupera o incremento de etapa da barra de progresso do controle da barra de progresso atual.

int GetStep() const;

Valor de retorno

O incremento de etapa da barra de progresso.

Comentários

O incremento de etapa é o quanto uma chamada a CProgressCtrl::StepIt aumenta a posição atual da barra de progresso.

Esse método envia a mensagem PBM_GETSTEP, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável m_progressCtrl, que é usada para acessar programaticamente o controle da barra de progresso. Essa variável será usada no próximo exemplo.

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

O próximo exemplo de código recupera o incremento de etapa do controle da barra de progresso atual.

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

Avança a posição atual do controle da barra de progresso pelo incremento especificado por nPos e redesenha a barra para refletir a nova posição.

int OffsetPos(int nPos);

Parâmetros

nPos
Valor para avançar a posição.

Valor de retorno

A posição anterior do controle da barra de progresso.

Exemplo

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`

Define a cor da barra de indicadores de progresso no controle da barra de progresso atual.

COLORREF SetBarColor(COLORREF clrBar);

Parâmetros

clrBar
[in] Um valor COLORREF que especifica a nova cor da barra de indicadores de progresso. Especifique CLR_DEFAULT para fazer com que a barra de progresso use sua cor padrão.

Valor de retorno

A cor anterior da barra de indicadores de progresso, representada como um valor COLORREF, ou CLR_DEFAULT se a cor da barra de indicadores de progresso for a cor padrão.

Comentários

O método SetBarColor define a cor da barra de progresso somente se um tema do Windows Vista não estiver em vigor.

Esse método envia a mensagem PBM_SETBARCOLOR, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável m_progressCtrl, que é usada para acessar programaticamente o controle da barra de progresso. Essa variável será usada no próximo exemplo.

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

O exemplo de código a seguir altera a cor da barra de progresso para vermelho, verde, azul ou o padrão.

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

Define a cor da tela de fundo da barra de progresso.

COLORREF SetBkColor(COLORREF clrNew);

Parâmetros

clrNew
Um valor COLORREF que especifica a nova cor do plano de fundo. Especifique o valor CLR_DEFAULT para usar a cor da tela de fundo padrão para a barra de progresso.

Valor de retorno

O valor COLORREF que indica a cor anterior da tela de fundo ou CLR_DEFAULT se a cor da tela de fundo é a cor padrão.

Exemplo

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`

Ativa ou desativa o modo de letreiro do controle da barra de progresso atual.

BOOL SetMarquee(
    BOOL fMarqueeMode,
    int nInterval);

Parâmetros

fMarqueeMode
[in] TRUE para ativar o modo de letreiro ou FALSE para desativá-lo.

nInterval
[in] Tempo em milissegundos entre atualizações da animação de letreiro.

Valor de retorno

Esse método sempre retorna TRUE.

Comentários

Quando o modo de letreiro está ativado, a barra de progresso é animada e rola como uma placa de letreiro de teatro.

Esse método envia a mensagem PBM_SETMARQUEE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável m_progressCtrl, que é usada para acessar programaticamente o controle da barra de progresso. Essa variável será usada no próximo exemplo.

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

O próximo exemplo de código é iniciado e interrompe a animação de rolagem do letreiro.

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

Define a posição atual do controle da barra de progresso conforme especificado por nPos e redesenha a barra para refletir a nova posição.

int SetPos(int nPos);

Parâmetros

nPos
Nova posição do controle da barra de progresso.

Valor de retorno

A posição anterior do controle da barra de progresso.

Comentários

A posição do controle da barra de progresso não é o local físico na tela, mas sim entre o intervalo superior e inferior indicado em SetRange.

Exemplo

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`

Define os limites superior e inferior do intervalo do controle da barra de progresso e redesenha a barra para refletir os novos intervalos.

void SetRange(
    short nLower,
    short nUpper);

void SetRange32(
    int nLower,
    int nUpper);

Parâmetros

nLower
Especifica o limite inferior do intervalo (o padrão é zero).

nUpper
Especifica o limite superior do intervalo (o padrão é 100).

Comentários

A função membro SetRange32 define o intervalo de 32 bits para o controle de progresso.

Exemplo

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`

Define o estado do controle da barra de progresso atual.

int SetState(int iState);

Parâmetros

iState
[in] O estado para definir a barra de progresso. Use um dos seguintes valores:

PBST_NORMAL – Em andamento
PBST_ERROR – Erro
PBST_PAUSED – Em pausa

Valor de retorno

O estado anterior do controle da barra de progresso atual.

Comentários

Esse método envia a mensagem PBM_SETSTATE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável m_progressCtrl, que é usada para acessar programaticamente o controle da barra de progresso. Essa variável será usada no próximo exemplo.

// Variable to access the progress control
CProgressCtrl m_progressCtrl;

O exemplo de código a seguir define o estado do controle da barra de progresso atual como Em pausa ou Em andamento.

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

Especifica o incremento de etapa para um controle de barra de progresso.

int SetStep(int nStep);

Parâmetros

nStep
Incremento de nova etapa.

Valor de retorno

O incremento de etapa anterior.

Comentários

O incremento de etapa é o quanto uma chamada a CProgressCtrl::StepIt aumenta a posição atual da barra de progresso.

O incremento de etapa padrão é 10.

Exemplo

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`

Avança a posição atual de um controle de barra de progresso pelo incremento de etapa e redesenha a barra para refletir a nova posição.

int StepIt();

Valor de retorno

A posição anterior do controle da barra de progresso.

Comentários

O incremento de etapa é definido pela função membro CProgressCtrl::SetStep.

Exemplo

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();

Confira também

Exemplo de MFC CMNCTRL2
Classe CWnd
Gráfico da hierarquia

Compartilhar via

Classe CProgressCtrl

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CProgressCtrl::CProgressCtrl

Comentários

Exemplo

CProgressCtrl::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CProgressCtrl::CreateEx

Parâmetros

Valor de retorno

Comentários

CProgressCtrl::GetBarColor

Valor de retorno

Comentários

CProgressCtrl::GetBkColor

Valor de retorno

Comentários

CProgressCtrl::GetPos

Valor de retorno

Comentários

Exemplo

CProgressCtrl::GetRange

Parâmetros

Comentários

Exemplo

CProgressCtrl::GetState

Valor de retorno

Comentários

Exemplo

CProgressCtrl::GetStep

Valor de retorno

Comentários

Exemplo

CProgressCtrl::OffsetPos

Parâmetros

Valor de retorno

Exemplo

CProgressCtrl::SetBarColor

Parâmetros

Valor de retorno

Comentários

Exemplo

CProgressCtrl::SetBkColor

Parâmetros

Valor de retorno

Exemplo

CProgressCtrl::SetMarquee

Parâmetros

Valor de retorno

Comentários

Exemplo

CProgressCtrl::SetPos

Parâmetros

Valor de retorno

Comentários

Exemplo

CProgressCtrl::SetRange

Parâmetros

Comentários

Exemplo

CProgressCtrl::SetState

Parâmetros

Valor de retorno

Comentários

Exemplo

CProgressCtrl::SetStep

Parâmetros

Valor de retorno

Comentários

Exemplo

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