Compartilhar via


Classe CStatusBarCtrl

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 Devolução

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.

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
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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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 Devolução

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