Sobre controles da barra de ferramentas

Uma barra de ferramentas é um controle que contém um ou mais botões. Cada botão, quando clicado por um usuário, envia uma mensagem de comando para a janela pai. Normalmente, os botões em uma barra de ferramentas correspondem a itens no menu do aplicativo, oferecendo um modo adicional e mais direto para o usuário acessar os comandos de um aplicativo.

A captura de tela a seguir mostra uma janela que contém uma barra de ferramentas simples para operações de arquivo. O aplicativo habilitou estilos visuais. O botão Salvar está "quente" porque o cursor estava pairando sobre ele quando a captura de tela foi tirada. A aparência real do controle varia dependendo do sistema operacional e do tema selecionado pelo usuário.

A captura de tela a seguir mostra o mesmo controle em um aplicativo que foi compilado sem estilos visuais habilitados.

Os tópicos a seguir abordam os recursos a serem considerados ao planejar uma barra de ferramentas. Para obter informações específicas sobre implementação e código de exemplo, consulte Usando controles da barra de ferramentas.

• Especificando o tamanho e a posição da barra de ferramentas
• Barras de ferramentas transparentes
• Barras de ferramentas em estilo de lista
• Definindo imagens de botão
  • Definindo imagens de botão usando bitmaps
  • Definindo imagens de botão usando listas de imagens
• Definindo texto para botões
• Adicionando botões da barra de ferramentas
  • Estilos de botão da barra de ferramentas
  • Estados do botão da barra de ferramentas
  • Identificador de comando
  • Tamanho e posição do botão
• Habilitando a personalização
• Ativando o Hot-tracking

Especificando o tamanho e a posição da barra de ferramentas

Se você criar uma barra de ferramentas usando CreateToolbarEx, a função permitirá especificar em pixels a altura e a largura da barra de ferramentas.

A função CreateWindowEx não tem parâmetros para especificar o tamanho da barra de ferramentas. O procedimento da janela da barra de ferramentas define automaticamente o tamanho e a posição da janela da barra de ferramentas. A altura é baseada na altura dos botões na barra de ferramentas. A largura é a mesma da área de cliente da janela pai. Para alterar as configurações automáticas de tamanho, envie uma mensagem de TB_SETBUTTONSIZE . Os CCS_TOP e CCS_BOTTOM estilos de controle comuns determinam se a barra de ferramentas está posicionada ao longo da parte superior ou inferior da área do cliente. Por padrão, uma barra de ferramentas tem o estilo CCS_TOP.

Além disso, o procedimento da janela da barra de ferramentas ajusta automaticamente o tamanho da barra de ferramentas sempre que ela recebe uma mensagem WM_SIZE ou TB_AUTOSIZE. Um aplicativo deve enviar uma dessas mensagens sempre que o tamanho da janela pai for alterado ou depois de enviar uma mensagem que exija o ajuste do tamanho da barra de ferramentas — por exemplo, uma mensagem TB_SETBUTTONSIZE.

Os comportamentos de dimensionamento e posicionamento padrão da barra de ferramentas podem ser desativados definindo o CCS_NORESIZE e CCS_NOPARENTALIGN estilos de controle comuns. Os controles da barra de ferramentas hospedados por controles de vergalhão devem definir esses estilos porque o controle de vergalhão dimensiona e posiciona a barra de ferramentas.

Barras de ferramentas transparentes

Os controles da barra de ferramentas oferecem suporte a uma aparência transparente que permite que a área do cliente sob a barra de ferramentas seja exibida. Existem dois tipos de barras de ferramentas transparentes, aquelas com botões planos e outras com botões tridimensionais. Se você quiser que seu aplicativo corresponda à interface do Windows, use a barra de ferramentas de estilo transparente simples.

A captura de tela a seguir mostra os dois tipos de barras de ferramentas transparentes, não usando estilos visuais.

A captura de tela a seguir mostra uma barra de ferramentas transparente como ela pode aparecer no Windows Vista, com estilos visuais habilitados. A cor de fundo da caixa de diálogo foi alterada para tornar a transparência mais óbvia.

Para criar uma barra de ferramentas transparente, tudo o que você precisa fazer é adicionar TBSTYLE_FLAT ou TBSTYLE_TRANSPARENT ao parâmetro de estilo de janela de CreateWindowEx. Se você não quiser que uma linha apareça para indicar a parte inferior da barra de ferramentas, não use o estilo de janela WS_BORDER .

Barras de ferramentas em estilo de lista

Os botões da barra de ferramentas permitem que você exiba texto e bitmaps. Os botões em uma barra de ferramentas criada com o estilo TBSTYLE_LIST colocam o texto à direita do bitmap em vez de sob ele.

A captura de tela a seguir mostra uma barra de ferramentas com o estilo de lista.

Você pode usar o estilo de barra de ferramentas TBSTYLE_LIST em combinação com o estilo TBSTYLE_FLAT para criar uma barra de ferramentas com botões planos.

Definindo imagens de botão

Há duas maneiras de especificar as imagens para botões: por bitmaps ou por listas de imagens. Um aplicativo deve escolher qual método usar. Ele não pode usar ambos os métodos com o mesmo controle de barra de ferramentas. Observe que a função CreateToolbarEx usa o método bitmap. Os aplicativos que desejam usar o método de lista de imagens devem usar a função CreateWindowEx para criar o controle da barra de ferramentas.

Definindo imagens de botão usando bitmaps

Cada botão em uma barra de ferramentas pode incluir uma imagem bitmap. Uma barra de ferramentas usa uma lista interna para armazenar as informações necessárias para desenhar as imagens. Ao chamar a função CreateToolbarEx, você especifica um bitmap monocromático ou colorido que contém as imagens iniciais e a barra de ferramentas adiciona as informações à lista interna de imagens. Você pode adicionar imagens adicionais mais tarde usando a mensagem TB_ADDBITMAP.

Cada imagem tem um índice baseado em zero. A primeira imagem adicionada à lista interna tem um índice de 0, a segunda imagem tem um índice de 1 e assim por diante. TB_ADDBITMAP adiciona imagens ao final da lista e retorna o índice da primeira nova imagem adicionada. Para associar a imagem a um botão, você deve enviar uma mensagem de TB_ADDBUTTONS e especificar o índice da imagem depois de adicionar bitmaps à lista de imagens internas.

O Windows pressupõe que todas as imagens bitmap de uma barra de ferramentas são do mesmo tamanho. Você especifica o tamanho ao criar a barra de ferramentas usando CreateToolbarEx. Se você usar a função CreateWindowEx para criar uma barra de ferramentas, o tamanho das imagens será definido como as dimensões padrão de 16 por 15 pixels. Você pode usar a mensagem TB_SETBITMAPSIZE para alterar as dimensões das imagens bitmap, mas deve fazer isso antes de adicionar quaisquer imagens à lista interna.

Definindo imagens de botão usando listas de imagens

Você também pode armazenar imagens de botão em um conjunto de Listas de Imagens. Uma lista de imagens é uma coleção de imagens do mesmo tamanho, cada uma das quais pode ser referida por seu índice. As listas de imagens são usadas para gerenciar grandes conjuntos de ícones ou bitmaps. Você pode usar até três listas de imagens diferentes para exibir botões em vários estados, conforme mostrado na tabela a seguir.

Depois que a barra de ferramentas for destruída, os aplicativos devem liberar todas as listas de imagens que criaram.

Definindo texto para botões

Cada botão pode exibir uma cadeia de caracteres além ou em vez de uma imagem. Uma barra de ferramentas mantém uma lista interna que contém todas as cadeias de caracteres disponíveis para os botões da barra de ferramentas. Você adiciona cadeias de caracteres à lista interna usando a mensagem TB_ADDSTRING, especificando o endereço do buffer que contém as cadeias de caracteres a serem adicionadas. Cada cadeia de caracteres deve ser terminada em nulo e a última cadeia de caracteres deve ser terminada com dois caracteres nulos.

Cada cadeia de caracteres tem um índice baseado em zero. A primeira cadeia de caracteres adicionada à lista interna de cadeias de caracteres tem um índice de 0, a segunda cadeia de caracteres tem um índice de 1 e assim por diante. TB_ADDSTRING adiciona cadeias de caracteres ao final da lista e retorna o índice da primeira nova cadeia de caracteres. Use o índice de uma cadeia de caracteres para associá-la a um botão.

Usar TB_ADDSTRING não é a única maneira de adicionar cadeias de caracteres a uma barra de ferramentas. Você pode exibir uma cadeia de caracteres em um botão passando um ponteiro de cadeia de caracteres no membro iString da estrutura TBBUTTON que é passada para TB_ADDBUTTONS. Além disso, você pode usar TB_SETBUTTONINFO para atribuir texto a um botão da barra de ferramentas.

Adicionando botões da barra de ferramentas

Se você usar a função CreateToolbarEx para criar uma barra de ferramentas, poderá adicionar botões à barra de ferramentas preenchendo uma matriz de estruturas TBBUTTON e especificando o endereço da matriz na chamada de função. No entanto, a função CreateWindowEx não tem um parâmetro para passar uma estrutura TBBUTTON. CreateWindowEx cria uma barra de ferramentas vazia que você preenche enviando uma mensagem TB_ADDBUTTONS, especificando o endereço de uma estrutura TBBUTTON.

Depois que uma barra de ferramentas é criada, você pode adicionar botões enviando uma mensagem TB_INSERTBUTTON ou TB_ADDBUTTONS. Cada botão é descrito por uma estrutura TBBUTTON , que define os atributos do botão, incluindo os índices de sua cadeia de caracteres e bitmap, bem como seu estilo, estado, identificador de comando e valor de 32 bits definido pelo aplicativo.

Estilos de botão da barra de ferramentas

O estilo de um botão determina como o botão será exibido e como ele responderá à entrada do usuário. Por exemplo, o estilo BTNS_BUTTON cria um botão da barra de ferramentas que se comporta como um botão padrão. Um botão que tem o estilo BTNS_CHECK é semelhante a um botão de pressão padrão, exceto que alterna entre os estados pressionado e não pressionado cada vez que o usuário clica nele.

Você pode criar grupos de botões da barra de ferramentas que funcionam como botões de opção usando o estilo BTNS_GROUP ou BTNS_CHECKGROUP. Isso faz com que um botão permaneça pressionado até que o usuário escolha outro botão no grupo. Um grupo é definido como uma coleção contígua de botões, todos com o estilo BTNS_GROUP ou BTNS_CHECKGROUP .

O estilo BTNS_SEP cria uma pequena lacuna entre os botões ou desenha uma gravação entre os botões em barras de ferramentas planas. Um botão com o estilo BTNS_SEP não recebe entrada do usuário.

A versão 5.80 dos controles comuns introduziu alguns novos estilos de botão da barra de ferramentas e renomeou alguns dos estilos mais antigos. Todos os sinalizadores de estilo de botão agora começam com BTNS_XXX em vez de TBSTYLE_XXX. Para obter uma lista e discussão dos estilos de botão, consulte Controle da barra de ferramentas e estilos de botão.

Estados de botão da barra de ferramentas

Cada botão em uma barra de ferramentas tem um estado. A barra de ferramentas atualiza o estado de um botão para refletir as ações do usuário, como clicar no botão. O estado indica se o botão está pressionado ou não pressionado, habilitado ou desabilitado, oculto ou visível. Embora um aplicativo defina o estado inicial de um botão ao adicionar o botão à barra de ferramentas, ele pode alterar e recuperar o estado enviando mensagens TB_GETSTATE e TB_SETSTATE para a barra de ferramentas. Para obter uma lista de estados de botões da barra de ferramentas, consulte Estados da barra de ferramentas.

Identificador de comando

Cada botão tem um identificador de comando definido pelo aplicativo associado a ele. Os identificadores de botão geralmente são definidos em um arquivo de cabeçalho de aplicativo. Por exemplo, um botão Colar pode ser definido como:

#define ID_PASTE 100

Quando o usuário seleciona um botão, a barra de ferramentas envia à janela pai uma mensagem de WM_COMMAND ou WM_NOTIFY que inclui o identificador de comando do botão. A janela pai examina o identificador de comando e executa o comando associado ao botão. Para obter informações sobre quando os controles enviam mensagens WM_COMMAND e quando eles enviam WM_NOTIFY, consulte a seção Comentários da documentação WM_NOTIFY.

Tamanho e posição do botão

Uma barra de ferramentas controla seus botões atribuindo a cada botão um índice de posição. O índice é baseado em zero; ou seja, o botão mais à esquerda tem um índice de 0, o botão seguinte à direita tem um índice de 1, e assim por diante. Um aplicativo deve especificar o índice de um botão ao enviar mensagens para recuperar informações sobre o botão ou para definir os atributos do botão.

Uma barra de ferramentas atualiza os índices de posição à medida que os botões são inseridos e removidos. Um aplicativo pode recuperar o índice de posição atual de um botão usando a mensagem TB_COMMANDTOINDEX. A mensagem especifica o identificador de comando de um botão e a janela da barra de ferramentas usa o identificador para localizar o botão e retornar seu índice de posição.

Todos os botões em uma barra de ferramentas têm o mesmo tamanho. A função CreateToolbarEx requer que você defina o tamanho inicial dos botões ao criar a barra de ferramentas. Quando você usa a função CreateWindowEx , o tamanho inicial é definido para as dimensões padrão de 24 por 22 pixels. Você pode usar a mensagem TB_SETBUTTONSIZE para alterar o tamanho do botão, mas deve fazê-lo antes de adicionar qualquer botão à barra de ferramentas. A mensagem TB_GETITEMRECT recupera as dimensões atuais dos botões.

Quando você adiciona uma cadeia de caracteres que é maior do que qualquer cadeia de caracteres atualmente na barra de ferramentas, a barra de ferramentas redefine automaticamente a largura de seus botões. A largura é definida para acomodar a cadeia de caracteres mais longa na barra de ferramentas.

Habilitando a personalização

Uma barra de ferramentas tem recursos internos de personalização que você pode disponibilizar para o usuário dando à barra de ferramentas o CCS_ADJUSTABLE estilo de controle comum. Os recursos de personalização permitem que o usuário arraste um botão para uma nova posição ou remova um botão arrastando-o para fora da barra de ferramentas. Além disso, o usuário pode clicar duas vezes na barra de ferramentas para exibir a caixa de diálogo Personalizar Barra de Ferramentas, que permite ao usuário adicionar, excluir e reorganizar os botões da barra de ferramentas. Para exibir a caixa de diálogo, use a mensagem TB_CUSTOMIZE. Um aplicativo determina se os recursos de personalização estão disponíveis para o usuário e controla até que ponto o usuário pode personalizar a barra de ferramentas.

Como parte do processo de personalização, os aplicativos geralmente precisam salvar e restaurar o estado de uma barra de ferramentas. Por exemplo, muitos aplicativos armazenam o estado da barra de ferramentas antes que o usuário comece a personalizá-la, caso o usuário queira posteriormente restaurar a barra de ferramentas ao seu estado original. O controle da barra de ferramentas não mantém automaticamente um registro de seu estado de pré-personalização. Seu aplicativo deve salvar o estado da barra de ferramentas para restaurá-lo. Para obter mais informações, consulte Usando controles da barra de ferramentas.

Ativando o Hot-tracking

Hot-tracking significa que, quando o ponteiro se move sobre um item, a aparência do botão muda. Quando os estilos visuais estão habilitados, as barras de ferramentas oferecem suporte ao rastreamento a quente por padrão. Caso contrário, somente os controles da barra de ferramentas criados com o estilo TBSTYLE_FLAT oferecem suporte ao rastreamento a quente. Você pode usar outros estilos de janela em combinação com TBSTYLE_FLAT para produzir barras de ferramentas que permitem o rastreamento a quente, mas têm uma aparência diferente de uma barra de ferramentas simples. Para obter mais informações, consulte Usando controles da barra de ferramentas.