Sobre controles tab

Um controle tab é análogo aos divisores em um notebook ou aos rótulos em um armário de arquivos. Usando um controle tab, um aplicativo pode definir várias páginas para a mesma área de uma janela ou caixa de diálogo. Cada página consiste em um determinado tipo de informação ou um grupo de controles que o aplicativo exibe quando o usuário seleciona a guia correspondente.

A captura de tela a seguir mostra um controle guia simples que contém guias para dias da semana. A guia terça-feira foi selecionada.

screen shot of a property sheet with five tabs, one for each day of the week

Este tópico inclui as seções a seguir.

Criando controles de tabulação

Você pode criar um controle de guia chamando a função CreateWindowEx , especificando a classe de janela WC_TABCONTROL . Essa classe de janela é registrada quando a DLL de controles comuns é carregada. Para garantir que a DLL seja carregada, use a função InitCommonControlsEx .

Em Microsoft Visual Studio, você pode criar um controle tab usando a Caixa de Ferramentas.

Você envia mensagens para um controle tab para adicionar guias e, de outra forma, afeta a aparência e o comportamento do controle. Cada mensagem tem uma macro correspondente que você pode usar em vez de enviar a mensagem explicitamente. Não é possível desabilitar uma guia individual em um controle tab. No entanto, você pode desabilitar um controle de guia em uma folha de propriedades desabilitando a página correspondente.

Estilos de controle de tabulação

Você pode aplicar determinadas características aos controles de tabulação especificando estilos de controle de tabulação quando o controle é criado. Por exemplo, você pode especificar o alinhamento e a aparência geral das guias em um controle tab.

Você pode fazer com que as guias se pareçam com botões especificando o estilo TCS_BUTTONS . As guias nesse tipo de controle de guia devem servir à mesma função que os controles de botão; ou seja, clicar em uma guia deve executar um comando em vez de exibir uma página. Como a área de exibição em um controle de guia de botão normalmente não é usada, nenhuma borda é desenhada ao redor dela.

Você pode fazer com que uma guia receba o foco de entrada quando clicada especificando o estilo TCS_FOCUSONBUTTONDOWN . Normalmente, esse estilo é usado apenas com o estilo TCS_BUTTONS . Você pode especificar que uma guia não recebe o foco de entrada quando clicada usando o estilo TCS_FOCUSNEVER .

Por padrão, um controle tab exibe apenas uma linha de guias. Se nem todas as guias puderem ser mostradas de uma só vez, o controle de tabulação exibirá um controle para cima para que o usuário possa rolar guias adicionais para a exibição. Você pode fazer com que um controle tab exiba várias linhas de guias, se necessário, especificando o estilo TCS_MULTILINE . Com esse estilo, todas as guias podem ser exibidas de uma só vez. As guias são alinhadas à esquerda em cada linha, a menos que você especifique o estilo TCS_RIGHTJUSTIFY . Nesse caso, a largura de cada guia é aumentada para que cada linha de guias preencha toda a largura do controle de tabulação.

Um controle tab dimensiona automaticamente cada guia para ajustar seu ícone, se houver, e seu rótulo. Para dar a todas as guias a mesma largura, você pode especificar o estilo TCS_FIXEDWIDTH . O controle dimensiona todas as guias para se ajustar ao rótulo mais largo ou você pode atribuir uma largura e altura específicas usando a mensagem TCM_SETITEMSIZE . Em cada guia, o controle centraliza o ícone e o rótulo, colocando o ícone à esquerda do rótulo. Você pode forçar o ícone à esquerda, deixando o rótulo centralizado, especificando o estilo TCS_FORCEICONLEFT . Você pode alinhar o ícone e o rótulo à esquerda usando o estilo TCS_FORCELABELLEFT . Você não pode usar o estilo TCS_FIXEDWIDTH com o estilo TCS_RIGHTJUSTIFY .

Você pode especificar que a janela pai desenha as guias no controle usando o estilo TCS_OWNERDRAWFIXED . Para obter mais informações, consulte Guias desenhadas pelo proprietário.

Você pode especificar que um controle tab criará um controle de dica de ferramenta usando o estilo TCS_TOOLTIPS . Para obter mais informações sobre isso, consulte Dicas de Ferramentas de Controle de Tabulação.

Atributos tabs e tab

Cada guia em um controle de guia consiste em um ícone, um rótulo e dados definidos pelo aplicativo. Essas informações são especificadas por uma estrutura TCITEM . Você pode adicionar guias a um controle tab, recuperar o número de guias, recuperar e definir o conteúdo de uma guia e excluir guias. As guias são identificadas pelo índice baseado em zero.

Para adicionar guias a um controle de guia, use a mensagem TCM_INSERTITEM , especificando a posição do item e o endereço de uma estrutura TCITEM . Você pode recuperar e definir o conteúdo de uma guia existente usando as mensagens TCM_GETITEM e TCM_SETITEM . Para cada guia, você pode especificar um ícone, um rótulo ou ambos. Você também pode especificar dados definidos pelo aplicativo para associar à guia.

Você pode recuperar o número atual de guias usando a mensagem TCM_GETITEMCOUNT , excluir uma guia usando a mensagem TCM_DELETEITEM e excluir todas as guias em um controle de guia usando a mensagem TCM_DELETEALLITEMS .

Você pode associar dados definidos pelo aplicativo a cada guia. Por exemplo, você pode salvar informações sobre cada página com sua guia correspondente. Por padrão, um controle de guia aloca quatro bytes extras por guia para dados definidos pelo aplicativo. Você pode alterar o número de bytes extras por guia usando a mensagem TCM_SETITEMEXTRA . Você só pode usar essa mensagem quando o controle tab estiver vazio.

Os dados definidos pelo aplicativo são especificados pelo membro lParam da estrutura TCITEM . Se você usar mais de 4 bytes de dados definidos pelo aplicativo, precisará definir sua própria estrutura e usá-la em vez de TCITEM. Você pode recuperar e definir dados definidos pelo aplicativo da mesma maneira que recupera e define outras informações sobre uma guia usando as mensagens TCM_GETITEM e TCM_SETITEM .

O primeiro membro da estrutura deve ser uma estrutura TCITEMHEADER e os membros restantes devem especificar dados definidos pelo aplicativo. TCITEMHEADER é idêntico ao TCITEM, exceto que ele não tem o membro lParam . A diferença entre o tamanho da estrutura e o tamanho de TCITEMHEADER deve ser igual ao número de bytes extras por guia.

Área de Exibição

A área de exibição de um controle tab é a área na qual um aplicativo exibe a página atual. Normalmente, um aplicativo cria uma janela filho ou uma caixa de diálogo, definindo o tamanho da janela e a posição para se ajustar à área de exibição. Considerando o retângulo da janela para um controle tab, você pode calcular o retângulo delimitador da área de exibição usando a mensagem TCM_ADJUSTRECT .

Às vezes, a área de exibição deve ter um tamanho específico, por exemplo, o tamanho de uma caixa de diálogo filho modeless. Considerando o retângulo delimitador para a área de exibição, você pode usar TCM_ADJUSTRECT para calcular o retângulo da janela correspondente para o controle tab.

Seleção de Tabulação

Quando o usuário seleciona uma guia, um controle tab envia seus códigos de notificação da janela pai na forma de mensagens de WM_NOTIFY . O código de notificação TCN_SELCHANGING é enviado antes que a seleção seja alterada e o código de notificação TCN_SELCHANGE é enviado após as alterações de seleção.

Você pode processar TCN_SELCHANGING para salvar o estado da página de saída. Você pode retornar TRUE para impedir que a seleção seja alterada. Por exemplo, talvez você não queira se afastar de uma caixa de diálogo filho na qual um controle tem uma configuração inválida.

Você deve processar TCN_SELCHANGE para exibir a página de entrada na área de exibição. Isso pode simplesmente implicar a alteração das informações exibidas em uma janela filho. Com mais frequência, cada página consiste em uma janela ou caixa de diálogo filho. Nesse caso, um aplicativo pode processar essa notificação destruindo ou ocultando a janela ou a caixa de diálogo filho de saída e criando ou mostrando a janela ou a caixa de diálogo filho de entrada.

Você pode recuperar e definir a seleção atual usando as mensagens TCM_GETCURSEL e TCM_SETCURSEL .

Listas de imagens de controle de tabulação

Cada guia pode ter um ícone associado a ela, que é especificado por um índice na lista de imagens para o controle tab. Quando um controle tab é criado, ele não tem nenhuma lista de imagens associada a ele. Um aplicativo pode criar uma lista de imagens usando a função ImageList_Create e atribuí-la a um controle tab usando a mensagem TCM_SETIMAGELIST .

Você pode adicionar imagens à lista de imagens de um controle de tabulação da mesma forma que faria com qualquer outra lista de imagens. No entanto, um aplicativo deve remover imagens usando a mensagem TCM_REMOVEIMAGE em vez da função ImageList_Remove . Essa mensagem garante que cada guia permaneça associada à mesma imagem de antes.

Destruir um controle de tabulação não destrói uma lista de imagens associada a ele. Você deve destruir a lista de imagens separadamente. Isso será útil se você quiser atribuir a mesma lista de imagens a vários controles de guia.

Para recuperar o identificador para a lista de imagens atualmente associada a um controle tab, você pode usar a mensagem TCM_GETIMAGELIST .

Tamanho e posição da guia

Cada guia em um controle de guia tem um tamanho e uma posição. Você pode definir o tamanho das guias, recuperar o retângulo delimitador de uma guia ou determinar qual guia está em uma posição especificada.

Para controles de guia desenhados por proprietário e largura fixa, você pode definir a largura exata e a altura das guias usando a mensagem TCM_SETITEMSIZE . Em outros controles de guia, o tamanho de cada guia é calculado com base no ícone e no rótulo da guia. O controle tab inclui espaço para uma borda e uma margem adicional. Você pode definir a espessura da margem usando a mensagem TCM_SETPADDING .

Você pode determinar o retângulo delimitador atual para uma guia usando a mensagem TCM_GETITEMRECT . Você pode determinar qual guia, se houver, está em um local especificado usando a mensagem TCM_HITTEST .

Em um controle tab com o estilo TCS_MULTILINE , você pode determinar o número atual de linhas de guias usando a mensagem TCM_GETROWCOUNT .

Guias Owner-Drawn

Se um controle tab tiver o estilo TCS_OWNERDRAWFIXED , a janela pai deverá pintar guias processando a mensagem WM_DRAWITEM . O controle tab envia essa mensagem sempre que uma guia precisa ser pintada. O parâmetro lParam especifica o endereço de uma estrutura DRAWITEMSTRUCT , que contém o índice da guia, seu retângulo delimitador e o contexto do dispositivo (DC) no qual desenhar.

Por padrão, o membro itemData de DRAWITEMSTRUCT contém o valor do membro lParam da estrutura TCITEM . No entanto, se você alterar a quantidade de dados definidos pelo aplicativo por guia, itemData conterá o endereço dos dados. Você pode alterar a quantidade de dados definidos pelo aplicativo por guia usando a mensagem TCM_SETITEMEXTRA .

Para especificar o tamanho dos itens em um controle tab, a janela pai deve processar a mensagem de WM_MEASUREITEM . Como todas as guias em um controle de guia desenhado pelo proprietário têm o mesmo tamanho, essa mensagem é enviada apenas uma vez. Não há nenhum estilo de controle de guia para guias desenhadas pelo proprietário de tamanhos variados. Você também pode definir a largura e a altura das guias usando a mensagem TCM_SETITEMSIZE .

Dicas de ferramenta de controle de tabulação

Você pode usar um controle de dica de ferramenta para fornecer uma breve descrição de cada guia em um controle tab. Um controle tab que tem o estilo TCS_TOOLTIPS cria um controle de dica de ferramenta quando é criado e destrói o controle de dica de ferramenta quando ele é destruído. Você também pode criar um controle de dica de ferramenta e atribuí-lo a um controle tab.

Se você usar um controle de dica de ferramenta com um controle tab, a janela pai deverá processar o código de notificação TTN_GETDISPINFO para fornecer uma descrição de cada guia na solicitação.

Para usar o mesmo controle de dica de ferramenta com mais de um controle de guia, crie o controle de dica de ferramenta por conta própria e atribua-o ao controle tab usando a mensagem TCM_SETTOOLTIPS . Você pode recuperar o identificador para o controle de dica de ferramenta atual de um controle de tabulação usando a mensagem TCM_GETTOOLTIPS . Se você criar seu próprio controle de dica de ferramenta, não deverá usar o estilo TCS_TOOLTIPS .

Processamento padrão de mensagens de controle de tabulação

Esta seção descreve o processamento de mensagens executado por um controle tab. As mensagens específicas aos controles de guia são discutidas em outras seções desta documentação.

Mensagem Processamento executado
WM_CAPTURECHANGED Não fará nada se o controle tab liberou a captura do mouse em si. Se outra janela capturou o mouse e um botão é mantido pressionado, o comando libera o botão.
WM_CREATE Aloca e inicializa uma estrutura de dados interna. O controle criará um controle de dica de ferramenta se o estilo TCS_TOOLTIPS for especificado.
WM_DESTROY Libera recursos alocados durante WM_CREATE processamento.
WM_GETDLGCODE Retorna uma combinação dos valores DLGC_WANTARROWS e DLGC_WANTCHARS.
WM_GETFONT Retorna o identificador para a fonte usada para rótulos.
WM_KEYDOWN Processa chaves de direção e altera a seleção, se apropriado.
WM_KILLFOCUS Invalida a guia que tem o foco para que ela seja repintada para refletir um estado desfocado.
WM_LBUTTONDOWN Encaminha a mensagem para o controle de dica de ferramenta, se houver, e altera a seleção se o usuário estiver clicando em uma guia. Se o usuário estiver clicando em um botão, o controle redesenhará o botão para dar uma aparência submersa e capturará o mouse. Se o usuário estiver clicando em uma guia ou botão e o estilo TCS_FOCUSONBUTTONDOWN for especificado, o controle definirá o foco para si mesmo.
WM_LBUTTONUP Libera o mouse se um botão foi pressionado. Se o cursor estiver sobre o botão e estiver sendo retido, o controle alterará a seleção adequadamente e redesenhará o botão.
WM_MOUSEMOVE Encaminha a mensagem para o controle de dica de ferramenta, se houver. Se o estilo de TCS_BUTTONS for especificado e o botão do mouse estiver sendo pressionado após clicar, o controle também poderá redesenhar o botão afetado para dar a ele uma aparência elevada ou submersa.
WM_NOTIFY Encaminha códigos de notificação enviados pelo controle de dica de ferramenta.
WM_PAINT Desenha uma borda ao redor da área de exibição (a menos que o estilo de TCS_BUTTONS seja especificado) e pinta todas as guias que cruzam o retângulo inválido. Para cada guia, ela desenha o corpo da guia (ou envia uma mensagem de WM_DRAWITEM para a janela pai) e desenha uma borda ao redor da guia. Se o parâmetro wParam não for NULL, o controle pressupõe que o valor seja um HDC e pintará usando esse contexto de dispositivo.
WM_RBUTTONDOWN Envia um código de notificação NM_RCLICK para a janela pai.
WM_SETFOCUS Invalida a guia que tem o foco para que ela seja repintada para refletir um estado focado.
WM_SETFONT Define a fonte usada para rótulos.
WM_SETREDRAW Define o estado de um sinalizador interno que determina se o controle é repintado quando os itens são inseridos e excluídos, quando a fonte é alterada e assim por diante.
WM_SIZE Recalcula as posições das guias e pode invalidar parte do controle tab para forçar a repintação de algumas ou todas as guias.