Classe CStatusBarCtrl

Artigo
08/04/2024

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

Sintaxe

class CStatusBarCtrl : public CWnd

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
CStatusBarCtrl::Create	Cria um controle de barra de status e o anexa a um objeto `CStatusBarCtrl`.
CStatusBarCtrl::CreateEx	Cria um controle de barra de status com os estilos estendidos do Windows especificados e o anexa a um objeto `CStatusBarCtrl`.
CStatusBarCtrl::DrawItem	Chamado quando um aspecto visual de um controle de barra de status de desenho de proprietário é alterado.
CStatusBarCtrl::GetBorders	Recupera as larguras atuais das bordas horizontal e vertical de um controle de barra de status.
CStatusBarCtrl::GetIcon	Recupera o ícone de uma parte (também conhecida como painel) no controle de barra de status atual.
CStatusBarCtrl::GetParts	Recupera uma contagem das partes em um controle de barra de status.
CStatusBarCtrl::GetRect	Recupera o retângulo delimitador de uma parte em um controle de barra de status.
CStatusBarCtrl::GetText	Recupera o texto da parte fornecida de um controle de barra de status.
CStatusBarCtrl::GetTextLength	Recupere o comprimento, em caracteres, do texto da parte fornecida de um controle de barra de status.
CStatusBarCtrl::GetTipText	Recupera o texto da dica de ferramenta para um painel em uma barra de status.
CStatusBarCtrl::IsSimple	Verifica um controle de janela de status para determinar se ele está no modo simples.
CStatusBarCtrl::SetBkColor	Define a cor da tela de fundo em uma barra de status.
CStatusBarCtrl::SetIcon	Define o ícone de um painel em uma barra de status.
CStatusBarCtrl::SetMinHeight	Define a altura mínima da área de desenho de um controle de barra de status.
CStatusBarCtrl::SetParts	Define o número de partes em um controle de barra de status e a coordenada da borda direita de cada parte.
CStatusBarCtrl::SetSimple	Especifica se um controle de barra de status exibe texto simples ou exibe todas as partes de controle definidas por uma chamada anterior para `SetParts`.
CStatusBarCtrl::SetText	Define o texto na parte determinada de um controle de barra de status.
CStatusBarCtrl::SetTipText	Define o texto da dica de ferramenta para um painel em uma barra de status.

Comentários

Um "controle de barra de status" é uma janela horizontal, geralmente exibida na parte inferior de uma janela pai, na qual um aplicativo pode exibir vários tipos de informações de status. O controle de barra de status pode ser dividido em partes para exibir mais de um tipo de informação.

Esse controle (e, portanto, a classe CStatusBarCtrl) está disponível apenas para programas em execução no Windows 95/98 e Windows NT versão 3.51 e posteriores.

Para mais informações sobre como usar CStatusBarCtrl, confira Controles e Uso de CStatusBarCtrl.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CStatusBarCtrl

Requisitos

Cabeçalho: afxcmn.h

CStatusBarCtrl::Create

Cria um controle de barra de status e o anexa a um objeto CStatusBarCtrl.

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

Parâmetros

dwStyle
Especifica o estilo do controle de barra de status. Aplique qualquer combinação de estilos de controle de barra de status listados em Estilos de Controle Comuns no SDK do Windows. Esse parâmetro deve incluir o estilo WS_CHILD. Ele também deve incluir o estilo WS_VISIBLE.

rect
Especifica o tamanho e a posição do controle de barra de status. Pode ser um objeto CRect ou uma estrutura RECT.

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

Nid
Especifica a ID do controle de barra de status.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O CStatusBarCtrl é construído em duas etapas. Primeiro, chame o construtor, então chame Create, o que cria o controle de barra de status e o anexa ao objeto CStatusBarCtrl.

A posição padrão de uma janela de status é na parte inferior da janela pai, mas você pode especificar o estilo CCS_TOP para que ele apareça na parte superior da área de cliente da janela pai. Você pode especificar o estilo SBARS_SIZEGRIP para incluir uma garra de dimensionamento na extremidade direita da janela de status . Não é recomendável combinar os estilos CCS_TOP e SBARS_SIZEGRIP, pois a garra de dimensionamento resultante não é funcional, embora o sistema a desenhe na janela de status.

Para criar uma barra de status com estilos de janela estendidos, chame CStatusBarCtrl::CreateEx em vez de Create.

Exemplo

VERIFY(m_wndSBC.Create(WS_CHILD | WS_VISIBLE | CCS_BOTTOM | SBARS_SIZEGRIP,
                       CRect(0, 0, 0, 0), this, IDC_STATUSBARCTRL));

CStatusBarCtrl::CreateEx

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

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, confira o parâmetro dwExStyle para CreateWindowEx 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, em coordenadas do 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 Criar para aplicar estilos estendidos do Windows, especificados pelo prefácio WS_EX_ de estilos estendidos do Windows.

CStatusBarCtrl::CStatusBarCtrl

Constrói um objeto CStatusBarCtrl.

CStatusBarCtrl();

CStatusBarCtrl::DrawItem

Chamado pela estrutura quando um aspecto visual de um controle de barra de status de desenho do proprietário é alterado.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro longo para uma estrutura DRAWITEMSTRUCT que contém informações sobre o tipo de desenho necessário.

Comentários

O membro itemAction da estrutura DRAWITEMSTRUCT define a ação de desenho a ser executada.

Por padrão, essa função membro não faz nada. Substitua essa função de membro para implementar o desenho para um objeto CStatusBarCtrl desenhado pelo proprietário.

O aplicativo deve restaurar todos os objetos GDI (Graphics Device Interface) selecionados para o contexto de exibição fornecido no lpDrawItemStruct antes que a função membro seja encerrada.

CStatusBarCtrl::GetBorders

Recupera as larguras atuais do controle de barra de status das bordas horizontais e verticais e do espaço entre retângulos.

BOOL GetBorders(int* pBorders) const;

BOOL GetBorders(
    int& nHorz,
    int& nVert,
    int& nSpacing) const;

Parâmetros

pBorders
Endereço de uma matriz inteiro com três elementos. O primeiro elemento recebe a largura da borda horizontal, o segundo recebe a largura da borda vertical e o terceiro recebe a largura da borda entre retângulos.

nHorz
Referência a um inteiro que recebe a largura da borda horizontal.

nVert
Referência a um inteiro que recebe a largura da borda vertical.

nSpacing
Referência a um inteiro que recebe a largura da borda entre retângulos.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essas bordas determinam o espaçamento entre a borda externa do controle e os retângulos dentro do controle que contêm texto.

Exemplo

RECT rectPane1;
VERIFY(m_wndSBC.GetRect(1, &rectPane1));

int borderArray[3];
VERIFY(m_wndSBC.GetBorders(borderArray));

int nHorz, nVert, nSpacing;
VERIFY(m_wndSBC.GetBorders(nHorz, nVert, nSpacing));

CStatusBarCtrl::GetIcon

Recupera o ícone de uma parte (também conhecida como painel) no controle de barra de status atual.

HICON GetIcon(int iPart) const;

Parâmetros

iPart
[in] O índice baseado em zero da parte que contém o ícone a ser recuperado. Se esse parâmetro for -1, a barra de status será considerada uma barra de status de modo simples.

Valor de retorno

O identificador para o ícone se o método tiver êxito; caso contrário, NULL.

Comentários

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

Um controle de barra de status consiste em uma linha de painéis de saída de texto, que também são conhecidos como partes. Para mais informações sobre a barra de status, confira Implementação da barra de status no MFC e Como definir o modo de um objeto CStatusBarCtrl.

Exemplo

O primeiro exemplo de código define uma variável m_statusBar, que é usada para acessar o controle de barra de status atual. Essa variável será usada no próximo exemplo.

public:
CStatusBarCtrl m_statusBar;

O próximo exemplo de código copia um ícone para dois painéis do controle de barra de status atual. Em uma seção anterior do exemplo de código, criamos um controle de barra de status com três painéis e adicionamos um ícone ao primeiro painel. Este exemplo recupera o ícone do primeiro painel e o adiciona ao segundo e ao terceiro painéis.

// Get the icon from pane 1 and set it in panes 2 and 3.
HICON hIcon = m_statusBar.GetIcon(0);
m_statusBar.SetIcon(1, hIcon);
m_statusBar.SetIcon(2, hIcon);

CStatusBarCtrl::GetParts

Recupera uma contagem das partes em um controle de barra de status.

int GetParts(
    int nParts,
    int* pParts) const;

Parâmetros

nParts
Número de partes para as quais recuperar coordenadas. Se esse parâmetro for maior que o número de partes no controle, a mensagem recuperará coordenadas somente para partes existentes.

pParts
Endereço de uma matriz de inteiro com o mesmo número de elementos que o número de partes especificadas por nParts. Cada elemento na matriz recebe a coordenada do cliente da borda direita da parte correspondente. Se um elemento for definido como -1, a posição da borda direita para essa parte se estenderá até a borda direita da barra de status.

Valor de retorno

O número de partes no controle, se bem-sucedido ou zero, caso contrário.

Comentários

Essa função membro também recupera a coordenada da borda direita do número determinado de partes.

Exemplo

int pParts[2];

int nParts = m_wndSBC.GetParts(2, pParts);

CStatusBarCtrl::GetRect

Recupera o retângulo delimitador de uma parte em um controle de barra de status.

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

Parâmetros

nPane
Índice baseado em zero da parte cujo retângulo delimitador deve ser recuperado.

lpRect
Endereço de uma estrutura RECT que recebe o retângulo delimitador.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

CRect rectPane1;

VERIFY(m_wndSBC.GetRect(1, &rectPane1));

CStatusBarCtrl::GetText

Recupera o texto da parte fornecida de um controle de barra de status.

CString GetText(
    int nPane,
    int* pType = NULL) const;

int GetText(
    LPCTSTR lpszText,
    int nPane,
    int* pType = NULL) const;

Parâmetros

lpszTexto
Endereço do buffer que recebe o texto. Esse parâmetro é uma cadeia de caracteres terminada em nulo.

nPane
Índice baseado em zero da parte da qual recuperar texto.

pType
Ponteiro para um inteiro que recebe as informações de tipo. O tipo pode ser um destes valores:

0 O texto é desenhado com uma borda a ser exibida abaixo do plano da barra de status.
SBT_NOBORDERS O texto é desenhado sem bordas.
SBT_POPOUT O texto é desenhado com uma borda a ser exibida acima do plano da barra de status.
SBT_OWNERDRAW Se o texto tiver o tipo de desenho SBT_OWNERDRAW, pType receberá essa mensagem e retornará o valor de 32 bits associado ao texto, em vez do tamanho e do tipo de operação.

Valor de retorno

O comprimento, em caracteres, do texto ou de um CString que contém o texto atual.

Exemplo

int nType;
TCHAR *pszPaneOneText;

pszPaneOneText = new TCHAR[m_wndSBC.GetTextLength(1, &nType) + 1];
int nTextLength = m_wndSBC.GetText(pszPaneOneText, 1, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

delete pszPaneOneText;

CStatusBarCtrl::GetTextLength

Recupera o comprimento, em caracteres, do texto da parte fornecida de um controle de barra de status.

int GetTextLength(
    int nPane,
    int* pType = NULL) const;

Parâmetros

nPane
Índice baseado em zero da parte da qual recuperar texto.

pType
Ponteiro para um inteiro que recebe as informações de tipo. O tipo pode ser um destes valores:

0 O texto é desenhado com uma borda a ser exibida abaixo do plano da barra de status.
SBT_NOBORDERS O texto é desenhado sem bordas.
SBT_OWNERDRAW O texto é desenhado pela janela pai.
SBT_POPOUT O texto é desenhado com uma borda a ser exibida acima do plano da barra de status.

Valor de retorno

O comprimento nos caracteres do texto.

Exemplo

int nType;
int nLength = m_wndSBC.GetTextLength(0, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

CStatusBarCtrl::GetTipText

Recupera o texto da dica de ferramenta para um painel em uma barra de status.

CString GetTipText(int nPane) const;

Parâmetros

nPane
O índice baseado em zero do painel de barras de status para receber o texto da dica de ferramenta.

Valor de retorno

Um objeto CString que contém o texto a ser usado na dica de ferramenta.

Comentários

Essa função membro implementa o comportamento do SB_GETTIPTEXT de mensagem Win32, conforme descrito no SDK do Windows.

Exemplo

CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl::IsSimple

Verifica um controle de janela de status para determinar se ele está no modo simples.

BOOL IsSimple() const;

Valor de retorno

Não zero se o controle da janela de status estiver no modo simples; caso contrário, zero.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 SB_ISSIMPLE, conforme descrito no SDK do Windows.

CStatusBarCtrl::SetBkColor

Define a cor da tela de fundo em uma barra de status.

COLORREF SetBkColor(COLORREF cr);

Parâmetros

cr
Um valor COLORREF que especifica a nova cor da tela de fundo. Especifique o valor CLR_DEFAULT para fazer com que a barra de status use sua cor da tela de fundo padrão.

Valor de retorno

Um valor COLORREF que representa a cor da tela de fundo padrão anterior.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 SB_SETBKCOLOR, conforme descrito no SDK do Windows.

Exemplo

m_wndSBC.SetBkColor(RGB(0, 0, 250));

HICON hIcon = AfxGetApp()->LoadIcon(IDI_PANE_0_ICON);
VERIFY(hIcon);
VERIFY(m_wndSBC.SetIcon(0, hIcon));

CStatusBarCtrl::SetIcon

Define o ícone de um painel em uma barra de status.

BOOL SetIcon(
    int nPane,
    HICON hIcon);

Parâmetros

nPane
O índice baseado em zero do painel que receberá o ícone. Se esse parâmetro for -1, a barra de status será considerada uma barra de status simples.

hIcon
Identificador para o ícone a ser definido. Se esse valor for NULL, o ícone será removido da parte.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 SB_SETICON, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CStatusBarCtrl::SetBkColor.

CStatusBarCtrl::SetMinHeight

Define a altura mínima da área de desenho de um controle de barra de status.

void SetMinHeight(int nMin);

Parâmetros

nMin
A altura mínima, em pixels, do controle.

Comentários

A altura mínima é a soma de nMin e o dobro da largura, em pixels, da borda vertical do controle de barra de status.

Exemplo

m_wndSBC.SetMinHeight(40);

CStatusBarCtrl::SetParts

Define o número de partes em um controle de barra de status e a coordenada da borda direita de cada parte.

BOOL SetParts(
    int nParts,
    int* pWidths);

Parâmetros

nParts
Número de partes a serem definidas. O número de partes não pode ser maior que 255.

pWidths
Endereço de uma matriz de inteiros com o mesmo número de elementos que as partes especificadas por nParts. Cada elemento na matriz especifica a posição, nas coordenadas do cliente, da borda direita da parte correspondente. Se um elemento for -1, a posição da borda direita para essa parte se estenderá até a borda direita do controle.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

const int c_nParts = 4;
CRect rect;

m_wndSBC.GetClientRect(&rect);
int aWidths[c_nParts] = {rect.right - 300, rect.right - 200, rect.right - 100,
                         -1};

VERIFY(m_wndSBC.SetParts(c_nParts, aWidths));

CStatusBarCtrl::SetSimple

Especifica se um controle de barra de status exibe texto simples ou exibe todas as partes de controle definidas por uma chamada anterior para SetParts.

BOOL SetSimple(BOOL bSimple = TRUE);

Parâmetros

bSimple
[in] Sinalizador de tipo de exibição. Se esse parâmetro for TRUE, o controle exibirá texto simples; se for FALSE, exibirá várias partes.

Valor de retorno

Sempre retorna 0.

Comentários

Se o aplicativo alterar o controle de barra de status de não simples para simples, ou vice-versa, o sistema redesenhará imediatamente o controle.

CStatusBarCtrl::SetText

Define o texto na parte determinada de um controle de barra de status.

BOOL SetText(
    LPCTSTR lpszText,
    int nPane,
    int nType);

Parâmetros

lpszTexto
Endereço de uma cadeia de caracteres terminada em nulo especificando o texto a ser definido. Se nType for SBT_OWNERDRAW, lpszText representará 32 bits de dados.

nPane
Índice baseado em zero da parte a ser definida. Se esse valor for 255, o controle de barra de status será considerado um controle simples com apenas uma parte.

nType
Tipo de operação de desenho. Confira a mensagem SB_SETTEXT para uma lista de valores possíveis.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

A mensagem invalida a parte do controle que foi alterada, fazendo com que ela exiba o novo texto quando o controle recebe a mensagem WM_PAINT.

Exemplo

VERIFY(m_wndSBC.SetText(_T("Text For Pane 1"), 1, 0));

CStatusBarCtrl::SetTipText

Define o texto da dica de ferramenta para um painel em uma barra de status.

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

Parâmetros

nPane
O índice baseado em zero do painel de barras de status para receber o texto da dica de ferramenta.

pszTipText
Um ponteiro para uma cadeia de caracteres que contém o texto da dica de ferramenta.

Comentários

Essa função membro implementa o comportamento da mensagem Win32 SB_SETTIPTEXT, conforme descrito no SDK do Windows.

Exemplo

m_wndSBC.SetTipText(0, _T("This is Pane 0"));

Confira também

Classe CWnd
Gráfico da hierarquia
Classe CToolBarCtrl

Compartilhar via

Classe CStatusBarCtrl

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CStatusBarCtrl::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::CreateEx

Parâmetros

Valor de retorno

Comentários

CStatusBarCtrl::CStatusBarCtrl

CStatusBarCtrl::DrawItem

Parâmetros

Comentários

CStatusBarCtrl::GetBorders

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::GetIcon

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::GetParts

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::GetRect

Parâmetros

Valor de retorno

Exemplo

CStatusBarCtrl::GetText

Parâmetros

Valor de retorno

Exemplo

CStatusBarCtrl::GetTextLength

Parâmetros

Valor de retorno

Exemplo

CStatusBarCtrl::GetTipText

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::IsSimple

Valor de retorno

Comentários

CStatusBarCtrl::SetBkColor

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::SetIcon

Parâmetros

Valor de retorno

Comentários

Exemplo

CStatusBarCtrl::SetMinHeight

Parâmetros

Comentários

Exemplo

CStatusBarCtrl::SetParts

Parâmetros

Valor de retorno

Exemplo

CStatusBarCtrl::SetSimple

Parâmetros

Valor de retorno

Comentários

CStatusBarCtrl::SetText