Classe CStatusBarCtrl

Fornece a funcionalidade do controlo da barra de estado comum do Windows.

Sintaxe

class CStatusBarCtrl : public CWnd

Membros

Construtores Públicos

Métodos Públicos

Observações

Um "controlo de barra de estado" é uma janela horizontal, geralmente exibida na parte inferior de uma janela principal, na qual uma aplicação pode apresentar vários tipos de informação de estado. O controlo da barra de estado pode ser dividido em partes para mostrar mais do que um tipo de informação.

Este controlo (e, portanto, a CStatusBarCtrl classe) está disponível apenas para programas a correr sob Windows 95/98 e Windows NT versão 3.51 e posteriores.

Para mais informações sobre a utilização CStatusBarCtrlde , veja Controlos e Utilização do CStatusBarCtrl.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CStatusBarCtrl

Requerimentos

Cabeçalho: afxcmn.h

CStatusBarCtrl::Create

Cria um controlo de barra de estado e anexa-o a um CStatusBarCtrl objeto.

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

Parâmetros

dwStyle
Especifica o estilo do controlo da barra de estado. Aplique qualquer combinação de estilos de controlo de barra de estado listados em Estilos de Controlo Comuns no SDK do Windows. Este parâmetro deve incluir o estilo WS_CHILD. Deve também incluir o estilo WS_VISIBLE.

retângulo
Especifica o tamanho e a posição do controlo da barra de estado. Pode ser um objeto CRect ou uma estrutura RECT .

pParentWnd
Especifica a janela pai do controlo da barra de estado, normalmente um CDialog. Não pode ser NULL.

nID
Especifica o ID do controlo da barra de estado.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero.

Observações

Constróis um A CStatusBarCtrl em dois passos. Primeiro, chama o construtor, e depois chama Create, que cria o controlo da barra de estado e o anexa ao CStatusBarCtrl objeto.

A posição padrão de uma janela de estado está na parte inferior da janela pai, mas podes especificar o estilo CCS_TOP para que apareça no topo da área cliente da janela principal. Pode especificar o estilo SBARS_SIZEGRIP para incluir uma pega de tamanho no extremo direito da janela de estado. Não é recomendado combinar os estilos CCS_TOP e SBARS_SIZEGRIP, porque a pega de dimensionamento resultante não é funcional, mesmo que o sistema a desenhe na janela de estado.

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

Example

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

CStatusBarCtrl::CreateEx

Cria um controlo (uma janela filha) e associa-o ao CStatusBarCtrl objeto.

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

Parâmetros

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

dwStyle
Especifica o estilo do controlo da barra de estado. Aplique qualquer combinação de estilos de controlo de barra de estado listados em Estilos de Controlo Comuns no SDK do Windows. Este parâmetro deve incluir o estilo WS_CHILD. Deve também incluir o estilo WS_VISIBLE.

retângulo
Uma referência a uma estrutura RECT que descreve o tamanho e a posição da janela a criar, em coordenadas cliente de pParentWnd.

pParentWnd
Um apontador para a janela que é o pai do controlo.

nID
O ID da janela criança do controlo.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

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

CStatusBarCtrl::CStatusBarCtrl

Constrói um CStatusBarCtrl objeto.

CStatusBarCtrl();

CStatusBarCtrl::D rawItem

Chamada pelo framework quando um aspeto visual do controlo de barra de estado de saqueio do proprietário muda.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

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

Observações

O itemAction elemento da DRAWITEMSTRUCT estrutura define a ação de desenho que deve ser realizada.

Por defeito, esta função membro não faz nada. Substitua esta função de membro para implementar desenho para um objeto proprietário-desenho CStatusBarCtrl .

A aplicação deve restaurar todos os objetos da interface do dispositivo gráfico (GDI) selecionados para o contexto de visualização fornecido em lpDrawItemStruct antes de esta função membro terminar.

CStatusBarCtrl::GetBorders

Recupera as larguras atuais do controlo da barra de estado das bordas horizontal e vertical 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 um array 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.

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero.

Observações

Estas bordas determinam o espaçamento entre a aresta exterior do controlo e os retângulos dentro do controlo que contêm texto.

Example

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 peça (também conhecida como painel) no controlo atual da barra de estado.

HICON GetIcon(int iPart) const;

Parâmetros

iPart
[dentro] O índice em base zero da parte que contém o ícone a recuperar. Se este parâmetro for -1, assume-se que a barra de estado é uma simples barra de estado de modo.

Valor de retorno

A alça do ícone se o método for bem-sucedido; caso contrário, NULL.

Observações

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

Um controlo de barra de estado consiste numa linha de painéis de saída de texto, também conhecidos como partes. Para mais informações sobre a barra de estado, consulte Implementação da Barra de Estado no MFC e Definir o Modo de um Objeto CStatusBarCtrl.

Example

O primeiro exemplo de código define uma variável, m_statusBar, que é usada para aceder ao controlo atual da barra de estado. Esta variável é usada no exemplo seguinte.

public:
CStatusBarCtrl m_statusBar;

O próximo exemplo de código copia um ícone para dois painéis do controlo atual da barra de estado. Numa secção anterior do exemplo de código, criámos um controlo de barra de estado com três painéis e depois adicionámos um ícone ao primeiro painel. Este exemplo recupera o ícone do primeiro painel e depois adiciona-o ao segundo e terceiro painel.

// 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 a contagem das peças num controlo de barra de estado.

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

Parâmetros

nPartes
Número de peças para recuperar coordenadas. Se este parâmetro for maior do que o número de partes no controlo, a mensagem recupera coordenadas apenas para as partes existentes.

pParts
Endereço de um array inteiro com o mesmo número de elementos que o número de partes especificado por nParts. Cada elemento no array recebe a coordenada cliente da aresta direita da peça correspondente. Se um elemento for definido para -1, a posição da aresta direita dessa parte estende-se até à aresta direita da barra de estado.

Valor de retorno

O número de peças no controlo se for bem-sucedido, ou zero caso contrário.

Observações

Esta função membro também recupera a coordenada da aresta direita do número dado de partes.

Example

int pParts[2];

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

CStatusBarCtrl::GetRect

Recupera o retângulo delimitador de uma peça num controlo de barra de estado.

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

Parâmetros

nPane
Índice de base zero da parte cujo retângulo delimitador deve ser recuperado.

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero.

Example

CRect rectPane1;

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

CStatusBarCtrl::GetText

Recupera o texto da parte dada de um controlo de barra de estado.

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

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

Parâmetros

lpszText
Endereço do buffer que recebe a mensagem. Este parâmetro é uma cadeia terminada por nulo.

nPane
Índice em base zero da parte de onde se deve retirar texto.

pType
Apontar para um inteiro que recebe a informação do tipo. O tipo pode ser um destes valores:

• 0 O texto é desenhado com uma borda para parecer inferior ao plano da barra de estado.

• SBT_NOBORDERS O texto é desenhado sem bordas.

• SBT_POPOUT O texto é desenhado com uma borda para parecer mais alta do que o plano da barra de estado.

• SBT_OWNERDRAW Se o texto tiver o tipo de desenho SBT_OWNERDRAW, o pType recebe esta mensagem e devolve o valor de 32 bits associado ao texto em vez do comprimento e do tipo de operação.

Valor de retorno

O comprimento, em caracteres, do texto ou de um CString contendo o texto atual.

Example

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 a partir da parte dada de um controlo de barra de estado.

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

Parâmetros

nPane
Índice em base zero da parte de onde se deve retirar texto.

pType
Apontar para um inteiro que recebe a informação do tipo. O tipo pode ser um destes valores:

• 0 O texto é desenhado com uma borda para parecer inferior ao plano da barra de estado.

• SBT_NOBORDERS O texto é desenhado sem bordas.

• SBT_OWNERDRAW O texto é desenhado pela janela principal.

• SBT_POPOUT O texto é desenhado com uma borda para parecer mais alta do que o plano da barra de estado.

Valor de retorno

O comprimento, em caracteres, do texto.

Example

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 de um painel numa barra de estado.

CString GetTipText(int nPane) const;

Parâmetros

nPane
O índice em base zero do painel de barra de estado para receber o texto da dica de ferramenta.

Valor de retorno

Um objeto CString contendo o texto a ser usado na dica de ferramenta.

Observações

Esta função membro implementa o comportamento da SB_GETTIPTEXT de mensagens Win32, conforme descrito no SDK do Windows.

Example

CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl::IsSimple

Verifica um controlo de janela de estado para determinar se está em modo simples.

BOOL IsSimple() const;

Valor de retorno

Não nulo se o controlo da janela de estado estiver em modo simples; caso contrário, zero.

Observações

Esta função membro implementa o comportamento da SB_ISSIMPLE de mensagens Win32, conforme descrito no SDK do Windows.

CStatusBarCtrl::SetBkColor

Define a cor de fundo numa barra de estado.

COLORREF SetBkColor(COLORREF cr);

Parâmetros

cr
COLORREF que especifica a nova cor de fundo. Especifique o valor CLR_DEFAULT para fazer com que a barra de estado use a cor de fundo predefinida.

Valor de retorno

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

Observações

Esta função membro implementa o comportamento da SB_SETBKCOLOR de mensagens Win32, conforme descrito no SDK do Windows.

Example

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 numa barra de estado.

BOOL SetIcon(
    int nPane,
    HICON hIcon);

Parâmetros

nPane
O índice em base zero do painel que receberá o ícone. Se este parâmetro for -1, assume-se que a barra de estado é uma barra de estado simples.

hIcon
Handle para o ícone a definir. Se este valor for NULL, o ícone é removido da peça.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero.

Observações

Esta função membro implementa o comportamento da SB_SETICON de mensagens Win32, conforme descrito no SDK do Windows.

Example

Veja o exemplo de CStatusBarCtrl::SetBkColor.

CStatusBarCtrl::SetMinHeight

Define a altura mínima da área de desenho de um controlo de barra de estado.

void SetMinHeight(int nMin);

Parâmetros

nMin
Altura mínima, em pixels, do controlo.

Observações

A altura mínima é a soma de nMin e o dobro da largura, em píxeis, da borda vertical do controlo da barra de estado.

Example

m_wndSBC.SetMinHeight(40);

CStatusBarCtrl::SetParts

Define o número de partes num controlo de barra de estado e a coordenada da aresta direita de cada peça.

BOOL SetParts(
    int nParts,
    int* pWidths);

Parâmetros

nPartes
Número de peças para montar. O número de peças não pode ser superior a 255.

PLarguras
Endereço de um array inteiro com o mesmo número de elementos que as partes especificadas por nParts. Cada elemento do array especifica a posição, em coordenadas do cliente, da aresta direita da peça correspondente. Se um elemento for - 1, a posição da aresta direita dessa parte estende-se até à aresta direita do controlo.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero.

Example

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 controlo de barra de estado apresenta texto simples ou se mostra todas as partes de controlo definidas por uma chamada anterior ao SetParts.

BOOL SetSimple(BOOL bSimple = TRUE);

Parâmetros

bSimple
[dentro] Bandeira do tipo ecrã. Se este parâmetro for VERDADEIRO, o controlo mostra texto simples; se for FALSO, mostra várias partes.

Valor de retorno

Sempre devolve 0.

Observações

Se a sua aplicação alterar o controlo da barra de estado de não simples para simples, ou vice-versa, o sistema redesenha imediatamente o controlo.

CStatusBarCtrl::SetText

Define o texto na parte dada de um controlo de barra de estado.

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

Parâmetros

lpszText
Endereço de uma cadeia terminada nula que especifica o texto a definir. Se o nType for SBT_OWNERDRAW, o lpszText representa 32 bits de dados.

nPane
Índice base zero da peça a definir. Se este valor for 255, assume-se que o controlo da barra de estado é um controlo simples com apenas uma parte.

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero.

Observações

A mensagem invalida a parte do controlo que foi alterada, fazendo com que o novo texto seja exibido quando o controlo recebe novamente a mensagem WM_PAINT.

Example

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

CStatusBarCtrl::SetTipText

Define o texto da dica de ferramenta para um painel numa barra de estado.

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

Parâmetros

nPane
O índice em base zero do painel de barra de estado para receber o texto da dica de ferramenta.

pszTipText
Um apontador para uma string que contém o texto da tooltip.

Observações

Esta função membro implementa o comportamento da SB_SETTIPTEXT de mensagens Win32, conforme descrito no SDK do Windows.

Example

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

Consulte também

Classe CWnd
Gráfico de Hierarquia
Classe CToolBarCtrl