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
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de