Partilhar via

Classe CStatusBar

  • Artigo

Uma barra de controle com uma linha de painéis de saída de texto ou "indicadores".

Sintaxe

class CStatusBar : public CControlBar

Membros

Construtores públicos

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

Métodos públicos

Nome Descrição
CStatusBar::CommandToIndex Obtém índice para uma ID de indicador determinada.
CStatusBar::Create Cria a barra de status, anexa-a ao objeto CStatusBar e define a fonte inicial e a altura da barra.
CStatusBar::CreateEx Cria um objeto CStatusBar com estilos adicionais para o objeto CStatusBarCtrl inserido.
CStatusBar::DrawItem Chamado quando um aspecto visual de um controle de barra de status de desenho de proprietário é alterado.
CStatusBar::GetItemID Obtém ID de indicador para um determinado índice.
CStatusBar::GetItemRect Obtém o retângulo de exibição para um determinado índice.
CStatusBar::GetPaneInfo Obtém a ID do indicador, o estilo e a largura de um determinado índice.
CStatusBar::GetPaneStyle Obtém estilo de indicador para um determinado índice.
CStatusBar::GetPaneText Obtém texto de indicador para um determinado índice.
CStatusBar::GetStatusBarCtrl Permite acesso direto ao controle comum subjacente.
CStatusBar::SetIndicators Define IDs de indicador.
CStatusBar::SetPaneInfo Define a ID do indicador, o estilo e a largura de um determinado índice.
CStatusBar::SetPaneStyle Define estilo de indicador para um determinado índice.
CStatusBar::SetPaneText Define texto de indicador para um determinado índice.

Comentários

Os painéis de saída comumente são usados como linhas de mensagem e como indicadores de status. Exemplos incluem as linhas de mensagem de ajuda do menu que explicam brevemente o comando de menu selecionado e os indicadores que mostram o status do SCROLL LOCK, NUM LOCK e outras chaves.

CStatusBar::GetStatusBarCtrl, uma função de membro nova no MFC 4.0, permite que você aproveite o suporte do controle comum do Windows para personalização da barra de status e funcionalidades adicionais. As funções de membro CStatusBar oferecem a maior parte da funcionalidade dos controles comuns do Windows, no entanto, quando você chama GetStatusBarCtrl, é possível dar às suas barras de status ainda mais as características de uma barra de status do Windows 95/98. Quando você chama GetStatusBarCtrl, ele retorna uma referência a um objeto CStatusBarCtrl. Consulte CStatusBarCtrl para obter mais informações sobre como criar barras de ferramentas usando controles comuns do Windows. Para obter informações mais gerais sobre controles comuns, confira Controles Comuns no SDK do Windows.

A estrutura armazena informações de indicador em uma matriz com o indicador mais à esquerda na posição 0. Ao criar uma barra de status, você usa uma matriz de IDs de cadeia de caracteres que a estrutura associa aos indicadores correspondentes. Em seguida, é possível usar uma ID de cadeia de caracteres ou um índice para acessar um indicador.

Por padrão, o primeiro indicador é "elástico": ele ocupa o comprimento da barra de status não usado pelos outros painéis indicadores, assim os outros painéis ficam alinhados à direita.

Para criar uma barra de status, siga estas etapas:

  1. Construa o objeto CStatusBar.

  2. Chame a função Criar (ou CreateEx) para criar a janela de barra de status e anexá-la ao objeto CStatusBar.

  3. Chame SetIndicators para associar uma ID de cadeia de caracteres a cada indicador.

Há três maneiras de atualizar o texto em um painel de barras de status:

  1. Chame CWnd::SetWindowText para atualizar o texto somente no painel 0.

  2. Chame CCmdUI::SetText no identificador ON_UPDATE_COMMAND_UI da barra de status.

  3. Chame SetPaneText para atualizar o texto de um painel.

Chame SetPaneStyle para atualizar o estilo de um painel de barras de status.

Para obter mais informações sobre como usar CStatusBar, consulte o artigo Implementação da Barra de Status no MFC e Nota Técnica 31: barras de controle.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CControlBar

CStatusBar

Requisitos

Cabeçalho: afxext.h

CStatusBar::CommandToIndex

Obtém o índice indicador de uma determinada ID.

int CommandToIndex(UINT nIDFind) const;

Parâmetros

nIDFind
ID da cadeia de caracteres do indicador cujo índice deve ser recuperado.

Valor de retorno

O índice do indicador, se for bem-sucedido e -1 se não for bem-sucedido.

Comentários

O índice do primeiro indicador é 0.

CStatusBar::Create

Cria uma barra de status (uma janela filho) e a associa ao objeto CStatusBar.

virtual BOOL Create(
    CWnd* pParentWnd,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_BOTTOM,
    UINT nID = AFX_IDW_STATUS_BAR);

Parâmetros

pParentWnd
Ponteiro para o objeto CWnd cuja janela do Windows é o pai da barra de status.

dwStyle
O estilo da barra de status. Além dos estilos padrão do Windows, há suporte para esses estilos.

  • CBRS_TOP Barra de controle está na parte superior da janela de quadros.

  • CBRS_BOTTOM Barra de controle está na parte inferior da janela de quadros.

  • CBRS_NOALIGN A barra de controle não é reposicionada quando o pai é redimensionado.

Nid
A ID da janela filho da barra de ferramentas.

Valor de retorno

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

Comentários

Também define a fonte inicial e define a altura da barra de status como um valor padrão.

CStatusBar::CreateEx

Chame essa função para criar um barra de status (uma janela filho) e associá-la ao objeto CStatusBar.

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwCtrlStyle = 0,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_BOTTOM,
    UINT nID = AFX_IDW_STATUS_BAR);

Parâmetros

pParentWnd
Ponteiro para o objeto CWnd cuja janela do Windows é o pai da barra de status.

dwCtrlStyle
Estilos adicionais para a criação do objeto CStatusBarCtrl inserido. O padrão especifica uma barra de status sem um suporte à alça de dimensionamento ou dica de ferramenta. Os estilos de barra de status com suporte são:

  • SBARS_SIZEGRIP O controle da barra de status inclui uma alça de dimensionamento na extremidade direita da barra de status. Uma alça de dimensionamento é semelhante a uma borda de dimensionamento. Ela é uma área retangular que o usuário pode clicar e arrastar para redimensionar a janela pai.

  • SBT_TOOLTIPS A barra de status dá suporte às dicas de ferramentas.

Para obter detalhes sobre esses estilos, consulte Configurações para CStatusBarCtrl.

dwStyle
O estilo da barra de status. O padrão especifica que uma barra de status visível seja criada na parte inferior da janela de quadros. Aplicar uma combinação de estilos de controle de barra de status listados em Estilos de Janela e CDialogBar::Criar. No entanto, esse parâmetro deve sempre incluir os estilos WS_CHILD e WS_VISIBLE.

Nid
A ID da janela filho da barra de status.

Valor de retorno

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

Comentários

Essa função também define a fonte inicial e define a altura da barra de status como um valor padrão.

Use CreateEx, em vez de Criar, quando determinados estilos precisarem estar presentes durante a criação do controle da barra de status inserida. Por exemplo, defina dwCtrlStyle como SBT_TOOLTIPS para exibir dicas de ferramentas em um objeto de barra de status.

CStatusBar::CStatusBar

Constrói um objeto CStatusBar, cria uma fonte de barra de status padrão, se necessário, e define as características da fonte como valores padrão.

CStatusBar();

CStatusBar::DrawItem

Essa função membro será chamada pela estrutura quando um aspecto visual de uma barra de status desenhada pelo proprietário for alterado.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro 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. Substitua essa função de membro para implementar o desenho para um objeto CStatusBar 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 do encerramento dessa função membro.

CStatusBar::GetItemID

Retorna a ID do indicador especificado por nIndex.

UINT GetItemID(int nIndex) const;

Parâmetros

nIndex
Índice do indicador cuja ID deve ser recuperada.

Valor de retorno

A ID do indicador especificado por nIndex.

CStatusBar::GetItemRect

Copia as coordenadas do indicador especificado por nIndex na estrutura apontada por lpRect.

void GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parâmetros

nIndex
Índice do indicador cujas coordenadas de retângulo devem ser recuperadas.

lpRect
Aponta para uma estrutura RECT ou um objeto CRect que receberá as coordenadas do indicador especificado por nIndex.

Comentários

As coordenadas estão em pixels em relação ao canto superior esquerdo da barra de status.

CStatusBar::GetPaneInfo

Define nID, nStyle e cxWidth como a ID, o estilo e a largura do painel indicador no local especificado por nIndex.

void GetPaneInfo(
    int nIndex,
    UINT& nID,
    UINT& nStyle,
    int& cxWidth) const;

Parâmetros

nIndex
Índice do painel cujas informações devem ser recuperadas.

Nid
Referência a um UINT definido como a ID do painel.

nEstilo
Referência a um UINT definido como o estilo do painel.

cxWidth
Referência a um inteiro que é definido como a largura do painel.

CStatusBar::GetPaneStyle

Chame essa função de membro para recuperar o estilo do painel de uma barra de status.

UINT GetPaneStyle(int nIndex) const;

Parâmetros

nIndex
Índice do painel cujo estilo deve ser recuperado.

Valor de retorno

O estilo do painel de barras de status especificado por nIndex.

Comentários

O estilo de um painel determina como o painel é exibido.

Para obter uma lista de estilos disponíveis para barras de status, consulte Criar.

CStatusBar::GetPaneText

Chame essa função de membro para recuperar o texto que aparece em um painel de barras de status.

CString GetPaneText(int nIndex) const;  void GetPaneText(int nIndex, CString& rString) const;

Parâmetros

nIndex
Índice do painel cujo texto deve ser recuperado.

rString
Uma referência a um objeto CString que contém o texto a ser recuperado.

Valor de retorno

Um objeto CString que contém o texto do painel.

Comentários

A segunda forma dessa função de membro preenche um objeto CString com o texto da cadeia de caracteres.

CStatusBar::GetStatusBarCtrl

Essa função de membro permite acesso direto ao controle comum subjacente.

CStatusBarCtrl& GetStatusBarCtrl() const;

Valor de retorno

Contém uma referência a um objeto CStatusBarCtrl.

Comentários

Use GetStatusBarCtrl para aproveitar a funcionalidade do controle comum da barra de status do Windows e aproveitar o suporte que o CStatusBarCtrl fornece para personalização da barra de status. Por exemplo, usando o controle comum, é possível especificar um estilo que inclui uma alça de dimensionamento na barra de status ou especificar um estilo para que a barra de status apareça na parte superior da área do cliente da janela pai.

Para obter informações mais gerais sobre controles comuns, consulte Controles Comuns no SDK do Windows.

CStatusBar::SetIndicators

Define a ID de cada indicador como o valor especificado pelo elemento correspondente da matriz lpIDArray, carrega o recurso de cadeia de caracteres especificado por cada ID e define o texto do indicador como a cadeia de caracteres.

BOOL SetIndicators(
    const UINT* lpIDArray,
    int nIDCount);

Parâmetros

lpIDArray
Ponteiro para uma matriz de IDs.

nIDCount
Número de elementos na matriz apontados por lpIDArray.

Valor de retorno

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

CStatusBar::SetPaneInfo

Define o painel de indicadores especificado como uma nova ID, estilo e largura.

void SetPaneInfo(
    int nIndex,
    UINT nID,
    UINT nStyle,
    int cxWidth);

Parâmetros

nIndex
Índice do painel indicador cujo estilo deve ser definido.

Nid
Nova ID para o painel de indicadores.

nEstilo
Novo estilo para o painel de indicadores.

cxWidth
Nova largura para o painel de indicadores.

Comentários

Há suporte para os seguintes estilos de indicadores:

  • SBPS_NOBORDERS Sem borda em 3D ao redor do painel.

  • SBPS_POPOUT Borda inversa para que o texto "se destaque".

  • SBPS_DISABLED Não desenhar texto.

  • SBPS_STRETCH Alongar painel para preencher espaço não utilizado. Somente um painel por barra de status pode ter esse estilo.

  • SBPS_NORMAL Sem alongamento, bordas ou destaques.

CStatusBar::SetPaneStyle

Chame essa função de membro para recuperar o estilo de um painel da barra de status.

void SetPaneStyle(
    int nIndex,
    UINT nStyle);

Parâmetros

nIndex
Índice do painel cujo estilo deve ser definido.

nEstilo
Estilo do painel cujo estilo deve ser definido.

Comentários

O estilo de um painel determina como o painel é exibido.

Para obter uma lista de estilos disponíveis para barras de status, consulte SetPaneInfo.

CStatusBar::SetPaneText

Chame essa função de membro para definir o texto do painel para a cadeia de caracteres apontada por lpszNewText.

BOOL SetPaneText(
    int nIndex,
    LPCTSTR lpszNewText,
    BOOL bUpdate = TRUE);

Parâmetros

nIndex
Índice do painel cujo texto deve ser definido.

lpszNewText
Ponteiro para o novo texto do painel.

bUpdate
Se for TRUE, o painel será invalidado depois que o texto for definido.

Valor de retorno

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

Comentários

Depois de chamar SetPaneText, você deve adicionar um identificador de atualização de interface do usuário para exibir o novo texto na barra de status.

Exemplo

//Sets and displays text for pane index 3 and id ID_INDICATOR_SCRL
m_wndStatusBar.SetPaneText(3, _T("My New Status Bar Text"), TRUE);

 

//UI handler in the message map updates the status bar text:
ON_UPDATE_COMMAND_UI(ID_INDICATOR_SCRL, &CMainFrame::OnUpdatePane)

 

void CMainFrame::OnUpdatePane(CCmdUI* pCmdUI)
{
   pCmdUI->Enable();
}

Confira também

CTRLBARS de exemplo do MFC
Exemplo de MFC DLGCBR32
Classe CControlBar
Gráfico da hierarquia
Classe CStatusBarCtrl
Classe CControlBar