TN031: barras de controle

  • Artigo

Observação

A nota técnica a seguir não foi atualizada desde que foi incluída pela primeira vez na documentação online. Como resultado, alguns procedimentos e tópicos podem estar desatualizados ou incorretos. Para obter as informações mais recentes, é recomendável que você pesquise o tópico de interesse no índice de documentação online.

Esta nota descreve as classes de barra de controle no MFC: a CControlBar, CStatusBar, CToolBar, CDialogBar e CDockBar geral.

CControlBar

Uma ControlBar é uma classe derivada de CWnd que:

  • Está alinhado à parte superior ou inferior de uma janela do quadro.

  • Pode conter itens filho que são controles baseados em HWND (por exemplo, CDialogBar) ou itens não baseados em HWND (por exemplo, CToolBar, CStatusBar).

As barras de controle dão suporte a estilos adicionais:

  • CBRS_TOP (O padrão) fixa a barra de controle no topo.

  • CBRS_BOTTOM Fixa a barra de controle na parte inferior.

  • CBRS_NOALIGN Não reposiciona a barra de controle quando o pai for redimensionado.

As classes derivadas de CControlBar fornecem implementações mais interessantes:

  • CStatusBar Uma barra de status, os itens são painéis da barra de status contendo texto.

  • CToolBar Uma barra de ferramentas, os itens são botões de bitmap alinhados em uma linha.

  • CDialogBar Um quadro semelhante a uma barra de ferramentas contendo controles de janelas padrão (criados a partir de um recurso de modelo de diálogo).

  • CDockBar Uma área de encaixe generalizada para outros objetos derivados de CControlBar. As funções membro e as variáveis específicas disponíveis nessa classe provavelmente serão alteradas em versões futuras.

Todos os objetos/janelas da barra de controle serão janelas filhas de alguma janela do quadro pai. Geralmente, são adicionadas como um irmão à área de cliente do quadro (por exemplo, um cliente MDI ou exibição). A ID da janela filho de uma barra de controle é importante. O layout padrão da barra de controle funciona apenas para barras de controle com IDs no intervalo de AFX_IDW_CONTROLBAR_FIRST a AFX_IDW_CONTROLBAR_LAST. Observe que, embora haja um intervalo de 256 IDs de barra de controle, as primeiras 32 dessas IDs de barra de controle são especiais, pois têm suporte direto pela arquitetura de visualização de impressão.

A classe CControlBar fornece implementação padrão para:

  • Alinhando a barra de controle na parte superior, inferior ou em qualquer um dos lados do quadro.

  • Alocando matrizes de itens de controle.

  • Dando suporte para implementação de classes derivadas.

Os objetos de barra de controle C++ geralmente serão inseridos como membros de uma classe derivada de CFrameWnd, e serão limpos quando o HWND pai e o objeto forem destruídos. Se for necessário alocar um objeto de barra de controle no heap, basta definir o membro m_bAutoDestruct como TRUE para fazer a barra de controle invocar delete this; quando o HWND for destruído.

Observação

Se você criar sua própria classe derivada de CControlBar, em vez de usar uma das classes derivadas do MFC, como CStatusBar, CToolBar ou CDialogBar, será necessário definir o membro de dados m_dwStyle. Isso pode ser feito na substituição de Create:

// CMyControlBar is derived from CControlBar
BOOL CMyControlBar::Create(CWnd* pParentWnd,
    DWORD dwStyle,
    UINT nID)
{
    m_dwStyle = dwStyle;

.
.
.
}

Algoritmo de layout da barra de controle

O algoritmo de layout da barra de controle é muito simples. A janela do quadro envia uma mensagem WM_SIZEPARENT para todos os filhos no intervalo de barra de controle. Junto com essa mensagem, um ponteiro para o retângulo do cliente do pai é passado. Essa mensagem é enviada aos filhos na ordem Z. Os filhos da barra de controle usam essas informações para se posicionarem e reduzir o tamanho da área de cliente do pai. O retângulo final deixado para a área do cliente normal (menos barras de controle) será usado para posicionar a janela principal do cliente (geralmente um cliente MDI, exibição ou janela divisora).

Consulte CWnd::RepositionBars e CFrameWnd::RecalcLayout para obter mais detalhes.

As mensagens privadas do Windows do MFC, incluindo WM_SIZEPARENT, estão documentadas na Nota Técnica 24.

CStatusBar

Uma barra de status é uma barra de controle que possui uma linha de painéis de saída de texto. Há duas maneiras comuns de usar painéis de saída de texto:

  • Como uma linha de mensagem

    (por exemplo, a linha de mensagem de ajuda do menu padrão). Geralmente são acessados por um indexado baseado em 0.

  • Como indicadores de status

    (por exemplo, os indicadores CAP, NUM e SCRL). Geralmente são acessados por ID de comando/cadeia de caracteres.

A fonte da barra de status é MS Sans Serif de 10 pontos (ditada pelo Guia do Design do Aplicativo de Interface do Windows ou a melhor correspondência dos mapeadores de fontes de uma fonte proporcional Swiss de 10 pontos). Em determinadas versões do Windows, como a edição japonesa, as fontes selecionadas são diferentes.

As cores usadas na barra de status também são consistentes com a recomendação do Guia do Design do Aplicativo de Interface do Windows. Essas cores não são codificadas e são alteradas dinamicamente em resposta à personalização do usuário no Painel de Controle.

Item Valor de COR do Windows RGB padrão
Plano de fundo da barra de status COLOR_BTNFACE RGB(192, 192, 192)
Texto da barra de status COLOR_BTNTEXT RGB(000, 000, 000)
Bordas esquerda/superior da barra de status COLOR_BTNHIGHLIGHT RGB(255, 255, 255)
Bordas direita/inferior da barra de status COLOR_BTNSHADOW RGB(128, 128, 128)

Suporte CCmdUI para CStatusBar

A maneira como os indicadores geralmente são atualizados é por meio do mecanismo ON_UPDATE_COMMAND_UI. Em tempo ocioso, a barra de status chamará o manipulador ON_UPDATE_COMMAND_UI com a ID da cadeia de caracteres do painel do indicador.

O manipulador ON_UPDATE_COMMAND_UI poderá chamar:

  • Enable: para habilitar ou desabilitar o painel. Um painel desabilitado se parece exatamente com um painel habilitado, mas o texto é invisível (ou seja, desativa o indicador de texto).

  • SetText: para alterar o texto. Tenha cuidado se usar isso porque o painel não será redimensionado automaticamente.

Consulte a classe CStatusBar na Referência da Biblioteca de Classes para obter detalhes sobre as APIs de criação e personalização de CStatusBar. A maior parte da personalização das barras de status deverá ser feita antes que a barra de status fique inicialmente visível.

A barra de status dá suporte apenas a um painel alongado, geralmente o primeiro painel. O tamanho desse painel é realmente um tamanho mínimo. Se a barra de status for maior que o tamanho mínimo de todos os painéis, qualquer largura adicional será dada ao painel alongado. O aplicativo padrão com uma barra de status possui indicadores alinhados à direita para CAP, NUM e SCRL, pois o primeiro painel é alongado.

CToolBar

Uma barra de ferramentas é uma barra de controle com uma linha de botões de bitmap que podem incluir separadores. Há suporte para dois estilos de botões: botões de ação e botões de caixa de seleção. A funcionalidade do grupo de opção pode ser construída com botões de caixa de seleção e ON_UPDATE_COMMAND_UI.

Todos os botões de bitmap na barra de ferramentas são obtidos de um bitmap. Esse bitmap deve conter uma imagem ou glifo para cada botão. Normalmente, a ordem das imagens/glifos no bitmap é a mesma ordem em que serão desenhadas na tela. (Isso pode ser alterado usando as APIs de personalização.)

Cada botão deve ser do mesmo tamanho. O padrão é 24x22 pixels. Cada imagem/glifo deve ter o mesmo tamanho e estar lado a lado no bitmap. O tamanho padrão da imagem/glifo é 16x15 pixels. Portanto, para uma barra de ferramentas com 10 botões (usando tamanhos padrão), é necessário um bitmap de 160 pixels de largura e 15 pixels de altura.

Cada botão tem uma e apenas uma imagem/glifo. Os diferentes estados e estilos de botão (por exemplo, pressionado, para cima, para baixo, desabilitado, desabilitado para baixo, indeterminado) são gerados algoritmicamente a partir dessa imagem/glifo. Em teoria, é possível usar qualquer bitmap de cor ou DIB. O algoritmo para gerar os diferentes estados dos botões funcionará melhor se a imagem original estiver em tonalidades de cinza. Observe os botões da barra de ferramentas padrão e o clipart do botão da barra de ferramentas fornecido no exemplo CLIPART geral do MFC para obter exemplos.

As cores usadas na barra de ferramentas também são consistentes com a recomendação do Guia do Design do Aplicativo de Interface do Windows. Essas cores não são codificadas e são alteradas dinamicamente em resposta à personalização do usuário no Painel de Controle.

Item Valor de COR do Windows RGB padrão
Plano de fundo da barra de ferramentas COLOR_BTNFACE RGB(192,192,192)
Bordas esquerda/superior dos botões da barra de ferramentas COLOR_BTNHIGHLIGHT RGB(255,255,255)
Bordas direita/inferior dos botões da barra de ferramentas COLOR_BTNSHADOW RGB(128,128,128)

Além disso, os botões de bitmap da barra de ferramentas são recoloridos como se fossem controles de botão padrão do Windows. Essa recoloração ocorre quando o bitmap é carregado do recurso e em resposta a uma alteração nas cores do sistema em resposta à personalização do usuário no Painel de Controle. As cores a seguir em um bitmap da barra de ferramentas serão recoloridas automaticamente, portanto, é necessário usar com cuidado. Se você não quiser que uma parte do bitmap seja recolorida, use uma cor que se aproxime de um dos valores RGB mapeados. O mapeamento é feito com base em valores RGB exatos.

Valor RGB Valor de COR mapeado dinamicamente.
RGB(000, 000, 000) COLOR_BTNTEXT
RGB(128, 128, 128) COLOR_BTNSHADOW
RGB(192, 192, 192) COLOR_BTNFACE
RGB(255, 255, 255) COLOR_BTNHIGHLIGHT

Consulte a classe CToolBar na Referência da Biblioteca de Classes para obter detalhes sobre as APIs de criação e personalização de CToolBar. A maior parte da personalização das barras de ferramentas deverá ser feita antes que a barra de ferramentas fique inicialmente visível.

As APIs de personalização poderão ser usadas para ajustar as IDs dos botões, estilos, largura do espaçador e qual imagem/glifo é usado para qual botão. Por padrão, não será necessário usar essas APIs.

Suporte CCmdUI para CToolBar

A maneira como os botões da barra de ferramentas são sempre atualizados é por meio do mecanismo ON_UPDATE_COMMAND_UI. Em tempo ocioso, a barra de ferramentas chamará o manipulador ON_UPDATE_COMMAND_UI com a ID de comando desse botão. ON_UPDATE_COMMAND_UI não é chamado para separadores, mas é chamado para botões de ação e botões de caixa de seleção.

O manipulador ON_UPDATE_COMMAND_UI poderá chamar:

  • Enable: para habilitar ou desabilitar o botão. Isso funciona igualmente para botões de ação e botões de caixa de seleção.

  • SetCheck: para definir o estado de verificação de um botão. Chamar isso para um botão da barra de ferramentas transformará em um botão de caixa de seleção. SetCheck recebe um parâmetro que poderá ser 0 (não verificado), 1 (marcado) ou 2 (indeterminado).

  • SetRadio: Shorthand para SetCheck.

Os botões de caixa de seleção são botões de caixa de seleção "AUTOMÁTICOS", ou seja, quando o usuário pressiona os botões eles mudam de estado imediatamente. Verificado é o estado inativo ou rebaixado. Não há uma interface de usuário integrada para alterar um botão para o estado "indeterminado", que deverá ser feito por meio de código.

As APIs de personalização permitirão alterar o estado de um determinado botão da barra de ferramentas, preferencialmente, altere esses estados no manipulador ON_UPDATE_COMMAND_UI do comando que o botão da barra de ferramentas representa. Lembre-se, o processamento ocioso alterará o estado dos botões da barra de ferramentas com o manipulador ON_UPDATE_COMMAND_UI, portanto, alterações nesses estados feitas por meio de SetButtonStyle poderão ser perdidas após a próxima ociosidade.

Os botões da barra de ferramentas enviarão mensagens WM_COMMAND como botões normais ou itens de menu e, normalmente, serão manipulados por um manipulador ON_COMMAND na mesma classe que fornecerá o manipulador ON_UPDATE_COMMAND_UI.

Há quatro estilos de botão da barra de ferramentas (valores TBBS_) usados para estados de exibição:

  • TBBS_CHECKED: a caixa de seleção está marcada (para baixo).

  • TBBS_INDETERMINATE: a caixa de seleção está atualmente indeterminada.

  • TBBS_DISABLED: o botão está desabilitado no momento.

  • TBBS_PRESSED: o botão está pressionado no momento.

Os seis estilos de botão do Guia do Design do Aplicativo de Interface do Windows oficiais são representados pelos seguintes valores TBBS:

  • Liberação do botão do mouse = 0

  • Pressionamento do botão do mouse = TBBS_PRESSED (| qualquer outro estilo)

  • Desabilitado = TBBS_DISABLED

  • Pressionamento = TBBS_CHECKED

  • Pressionamento desabilitado = TBBS_CHECKED | TBBS_DISABLED

  • Indeterminado = TBBS_INDETERMINATE

CDialogBar

Uma barra de diálogo é uma barra de controle contendo os controles padrão do Windows. Ela atua como uma caixa de diálogo contendo os controles e dá suporte a tabulações entre eles. Também funciona como uma caixa de diálogo porque usa um modelo de caixa de diálogo para representar a barra.

Um CDialogBar é usado para a barra de ferramentas de visualização de impressão, que contém os controles de botão de ação padrão.

Usar um CDialogBar é como usar um CFormView. É necessário definir um modelo de diálogo para a barra de diálogo e remover todos os estilos, exceto WS_CHILD. Observe que a caixa de diálogo não deve estar visível.

As notificações de controle para um CDialogBar serão enviadas para o pai da barra de controle (assim como os botões da barra de ferramentas).

Suporte CCmdUI para CDialogBar

Os botões da barra de diálogo deverão ser atualizados por meio do mecanismo do manipulador ON_UPDATE_COMMAND_UI. Em tempo ocioso, a barra de diálogo chamará o manipulador ON_UPDATE_COMMAND_UI com a ID de comando de todos os botões que tenham uma ID >= 0x8000 (ou seja, no intervalo de IDs de comando).

O manipulador ON_UPDATE_COMMAND_UI poderá chamar:

  • Habilitar: para habilitar ou desabilitar o botão.

  • SetText: para alterar o texto do botão.

A personalização poderá ser feita por meio de APIs do gerenciador de janelas padrão.

Confira também

Observações técnicas por número
Observações técnicas por categoria