Sobre controles da barra de controle

  • Artigo

Uma barra de controle deslizante é uma janela que contém um controle deslizante (às vezes chamado de polegar) em um canal e marcas de escala opcionais. Quando o usuário move o controle deslizante, usando o mouse ou as teclas de direção, a barra de rastreamento envia mensagens de notificação para indicar a alteração.

As barras de controle são úteis quando você deseja que o usuário selecione um valor inteiro não assinado discreto ou um conjunto de valores inteiros não assinados consecutivos em um intervalo. Por exemplo, você pode usar uma barra de faixas para permitir que o usuário defina a taxa de repetição do teclado movendo o controle deslizante para uma determinada marca de seleção. A ilustração a seguir mostra uma barra de faixas típica.

screen shot of a trackbar with labels at the ends for slow and fast

O controle deslizante em uma barra de controle se move em incrementos que você especifica ao criá-lo. Os valores nesse intervalo são chamados de unidades lógicas. Por exemplo, se você especificar que a barra de controle deve ter unidades lógicas que variam de 0 a 5, o controle deslizante poderá ocupar apenas seis posições: uma posição no lado esquerdo da barra de controle e uma posição para cada incremento no intervalo. Normalmente, cada uma dessas posições é identificada por uma marca de seleção; no entanto, o número de marcas de escala é arbitrário e pode ser menor do que o número de posições lógicas.

Você cria uma barra de controle usando a função CreateWindowEx, especificando a classe de janela TRACKBAR_CLASS. Depois de criar uma barra de faixa, você pode usar mensagens da barra de controle para definir e recuperar muitas de suas propriedades. As alterações que você pode fazer incluem definir as posições mínimas e máximas para o controle deslizante, desenhar marcas de escala, definir um intervalo de seleção e reposicionar o controle deslizante.

Faixa de seleção

Se você criar uma barra de faixas com o estilo TBS_ENABLESELRANGE, poderá especificar um intervalo de seleção. A barra de faixas realça o intervalo de seleção e exibe marcas de escala triangulares no início e no fim, conforme mostrado na ilustração a seguir.

screen shot of a trackbar with a range highlighted

O intervalo de seleção da barra de faixas não afeta sua funcionalidade de forma alguma. Cabe ao aplicativo implementar o intervalo. Você pode fazer isso de uma das seguintes maneiras:

  • Use um intervalo de seleção para permitir que o usuário defina valores máximos e mínimos para alguns parâmetros. Por exemplo, o usuário pode mover o controle deslizante para uma posição e, em seguida, clicar em um botão rotulado "Max". Em seguida, o aplicativo define o intervalo de seleção para mostrar os valores escolhidos pelo usuário.
  • Limite o movimento do controle deslizante a um subintervalo predeterminado dentro do controle, manipulando a notificação WM_HSCROLL ou WM_VSCROLL e não permitindo qualquer movimento fora do intervalo de seleção. Você pode fazer isso, por exemplo, se o intervalo de valores disponíveis para o usuário puder ser alterado devido a outras escolhas feitas pelo usuário ou de acordo com os recursos disponíveis.

Mensagens da barra de rastreamento

As unidades lógicas de uma barra de controle são o conjunto de valores contíguos que a barra de controle pode representar. Eles geralmente são definidos especificando o intervalo de valores possíveis com uma mensagem TBM_SETRANGE assim que a barra de controle é criada. Os aplicativos podem alterar dinamicamente o intervalo usando TBM_SETRANGE, TBM_SETRANGEMAX ou TBM_SETRANGEMIN.

Para recuperar a posição do controle deslizante (ou seja, o valor que o usuário escolheu), use a mensagem TBM_GETPOS. Para definir a posição do controle deslizante, use a mensagem TBM_SETPOS.

Uma barra de faixas exibe automaticamente marcas de escala no início e no fim, a menos que você especifique o estilo TBS_NOTICKS. (No editor de recursos do Microsoft Visual Studio, isso significa definir a propriedade Tick Marks como False.) Você pode usar o estilo TBS_AUTOTICKS para exibir automaticamente marcas de escala adicionais em intervalos regulares ao longo da barra de faixas. Por padrão, uma barra de trilha TBS_AUTOTICKS exibe uma marca de escala em cada incremento do intervalo da barra de faixa. Para especificar um intervalo diferente para as marcas de escala automáticas, envie a mensagem TBM_SETTICFREQ para a barra de faixa. Por exemplo, você pode usar essa mensagem para exibir apenas 10 marcas de escala em um intervalo de 1 a 100.

Para definir a posição de uma única marca de seleção, envie a mensagem TBM_SETTIC. Uma barra de controle mantém uma matriz de valores DWORD que armazena a posição de cada marca de seleção. A matriz não inclui a primeira e a última marcas de seleção, que a barra de faixas cria automaticamente. Você pode especificar um índice nessa matriz ao enviar a mensagem TBM_GETTIC para recuperar a posição da marca de escala correspondente. Como alternativa, você pode enviar a mensagem TBM_GETPTICS para recuperar um ponteiro para a matriz. O número de elementos na matriz é igual a dois a menos do que a contagem de ticks retornada pela mensagem TBM_GETNUMTICS. Isso ocorre porque a contagem retornada por TBM_GETNUMTICS inclui a primeira e a última marcas de seleção, que não estão incluídas na matriz. Para recuperar a posição física de uma marca de seleção, nas coordenadas do cliente da janela da barra de faixas, envie a mensagem TBM_GETTICPOS. A mensagem TBM_CLEARTICS remove todas, exceto a primeira e a última marcas de escala de uma barra de faixas.

O tamanho da linha de uma barra de trilha determina até onde o controle deslizante se move em resposta à entrada do teclado a partir das teclas de seta, como a tecla SETA PARA A DIREITA ou SETA PARA BAIXO. Para recuperar ou definir o tamanho da linha, envie as mensagens TBM_GETLINESIZE e TBM_SETLINESIZE. A barra de acompanhamento também envia os códigos de notificação TB_LINEUP e TB_LINEDOWN para sua janela pai quando o usuário pressiona as teclas de seta.

O tamanho da página de uma barra de controle deslizante determina até onde o controle deslizante se move em resposta à entrada do teclado, como a tecla PAGE UP ou PAGE DOWN, ou à entrada do mouse, como cliques no canal da barra de faixas. Para recuperar ou definir o tamanho da página, envie as mensagens TBM_GETPAGESIZE e TBM_SETPAGESIZE. A barra de faixas também envia os códigos de notificação TB_PAGEUP e TB_PAGEDOWN para sua janela pai quando recebe entrada de teclado ou mouse que rola a página. Para obter mais informações, consulte Mensagens de notificação da barra de rastreamento.

Um aplicativo pode enviar mensagens para recuperar as dimensões de uma barra de faixa. A mensagem TBM_GETTHUMBRECT recupera o retângulo delimitador do controle deslizante. A mensagem TBM_GETTHUMBLENGTH recupera o comprimento do controle deslizante. A mensagem TBM_GETCHANNELRECT recupera o retângulo delimitador do canal da barra de faixas, que é a área sobre a qual o controle deslizante se move. Ele contém o realce quando um intervalo é selecionado. Se uma barra de faixas tiver o estilo TBS_FIXEDLENGTH, você poderá enviar a mensagem TBM_SETTHUMBLENGTH para alterar o comprimento do controle deslizante.

Você recupera ou define o intervalo de seleção enviando mensagens para a barra de faixas. Use a mensagem TBM_SETSEL para definir as posições inicial e final de uma seleção. Para definir apenas a posição inicial ou apenas a posição final de uma seleção, envie uma mensagem TBM_SETSELSTART ou TBM_SETSELEND. Para recuperar as posições iniciais ou finais de um intervalo de seleção, envie uma mensagem TBM_GETSELSTART ou TBM_GETSELEND. Para limpar um intervalo de seleção e restaurar a barra de faixas para seu intervalo original, envie a mensagem TBM_CLEARSEL.

Observação

É responsabilidade do aplicativo garantir que o usuário não possa selecionar valores fora do intervalo de seleção. O controle em si não impede que o usuário mova o controle deslizante para fora do intervalo.

 

Mensagens de notificação da barra de rastreamento

Uma barra de controle notifica sua janela pai sobre as ações do usuário enviando ao pai uma mensagem WM_HSCROLL ou WM_VSCROLL. Uma barra de faixas com o estilo TBS_HORZ envia mensagens WM_HSCROLL. Uma barra de faixas com o estilo TBS_VERT envia mensagens WM_VSCROLL. A palavra de ordem baixa do parâmetro wParam de WM_HSCROLL ou WM_VSCROLL contém o código de notificação. Para os códigos de notificação TB_THUMBPOSITION e TB_THUMBTRACK, a palavra de ordem alta do parâmetro wParam especifica a posição do controle deslizante. Para todos os outros códigos de notificação, a palavra de ordem alta é zero; envie a mensagem TBM_GETPOS para determinar a posição do controle deslizante. O parâmetro lParam é o identificador da barra de faixas.

O sistema envia os códigos de notificação TB_BOTTOM, TB_LINEDOWN, TB_LINEUP e TB_TOP somente quando o usuário interage com uma barra de faixas usando o teclado. Os códigos de notificação TB_THUMBPOSITION e TB_THUMBTRACK só são enviados quando o usuário está usando o mouse. Os códigos de notificação TB_ENDTRACK, TB_PAGEDOWN e TB_PAGEUP são enviados em ambos os casos. A tabela a seguir lista os códigos de notificação da barra de controle e os eventos (códigos de chave virtual ou eventos de mouse) que fazem com que as notificações de Códigos de Chave Virtualsejam enviadas.

Código de notificação Motivo enviado
TB_BOTTOM VK_END
TB_ENDTRACK WM_KEYUP (o usuário liberou uma chave que enviou um código de chave virtual relevante)
TB_LINEDOWN VK_RIGHT ou VK_DOWN
TB_LINEUP VK_LEFT ou VK_UP
TB_PAGEDOWN VK_NEXT (o usuário clicou no canal abaixo ou à direita do controle deslizante)
TB_PAGEUP VK_PRIOR (o usuário clicou no canal acima ou à esquerda do controle deslizante)
TB_THUMBPOSITION WM_LBUTTONUP seguir um código de notificação TB_THUMBTRACK
TB_THUMBTRACK Movimento do controle deslizante (o usuário arrastou o controle deslizante)
TB_TOP VK_HOME

 

Processamento de mensagens padrão da barra de controle

Esta seção descreve o processamento de mensagens de janela executado por uma barra de faixa.

Mensagem Processamento realizado
WM_CAPTURECHANGED Mata o temporizador se um foi definido durante o processamento WM_LBUTTONDOWN e envia o código de notificação TB_THUMBPOSITION, se necessário. Ele sempre envia o código de notificação TB_ENDTRACK.
WM_CREATE Executa inicialização adicional, como definir o tamanho da linha, o tamanho da página e a frequência da marca de escala para valores padrão.
WM_DESTROY Libera recursos.
WM_ENABLE Repinta a janela da barra de faixas.
WM_ERASEBKGND Apaga o plano de fundo da janela, usando a cor de plano de fundo atual para a barra de faixas.
WM_GETDLGCODE Retorna o valor DLGC_WANTARROWS.
WM_KEYDOWN Processa as teclas de direção e envia os códigos de notificação TB_TOP, TB_BOTTOM, TB_PAGEUP, TB_PAGEDOWN, TB_LINEUP e TB_LINEDOWN, conforme apropriado.
WM_KEYUP Envia o código de notificação TB_ENDTRACK se a chave for uma das teclas de direção.
WM_KILLFOCUS Repinta a janela da barra de faixas.
WM_LBUTTONDOWN Define o foco e a captura do mouse para a barra de faixas. Quando necessário, ele define um temporizador que determina a rapidez com que o controle deslizante se move em direção ao cursor do mouse quando o usuário mantém pressionado o botão do mouse na janela.
WM_LBUTTONUP Libera a captura do mouse e encerra o temporizador se um foi definido durante WM_LBUTTONDOWN processamento. Ele envia o código de notificação TB_THUMBPOSITION, se necessário. Ele sempre envia o código de notificação TB_ENDTRACK.
WM_MOUSEMOVE Move o controle deslizante e envia o código de notificação TB_THUMBTRACK ao rastrear o mouse (consulte WM_TIMER).
WM_PAINT Pinta a barra de faixas. Se o parâmetro wParam for não-NULL, o controle assume que o valor é um HDC e pinta usando esse contexto de dispositivo.
WM_SETFOCUS Repinta a janela da barra de faixas.
WM_SIZE Define as dimensões da barra de faixas, removendo o controle deslizante se não houver espaço suficiente para exibi-lo.
WM_TIMER Recupera a posição do mouse e atualiza a posição do controle deslizante. (Ele é recebido somente quando o usuário está arrastando o controle deslizante.)
WM_WININICHANGE Inicializa as dimensões do controle deslizante.

 

Dicas de ferramentas da barra de rastreamento

Uma barra de controle criada com o estilo TBS_TOOLTIPS tem um controle de dica de ferramenta padrão. A dica de ferramenta permanece visível e exibe o valor atual à medida que o usuário arrasta o controle deslizante usando o mouse.

Você pode atribuir um novo controle de dica de ferramenta a uma barra de controle enviando a mensagem TBM_SETTOOLTIPS. Para recuperar o identificador para um controle de dica de ferramenta atribuído, use a mensagem TBM_GETTOOLTIPS.