Modelos de controle

Você pode personalizar a estrutura visual e o comportamento visual de um controle criando um modelo de controle na estrutura XAML. Os controles possuem muitas propriedades, como Background, Foreground e FontFamily, que você pode definir para especificar diferentes aspectos da aparência do controle. Mas as alterações que você pode fazer definindo essas propriedades são limitadas. Você pode especificar personalizações adicionais criando um modelo usando a classe ControlTemplate. Aqui, mostramos como criar uma ControlTemplate para personalizar a aparência de um controle CheckBox.

APIs importantes: Classe ControlTemplate, Propriedade Control.Template

Exemplo de modelo de controle personalizado

Por padrão, um controle CheckBox coloca seu conteúdo (a cadeia de caracteres ou objeto ao lado do CheckBox) à direita da caixa de seleção e uma marca de seleção indica que um usuário selecionou o CheckBox. Essas características representam a estrutura visual e o comportamento visual do CheckBox .

Aqui está um CheckBox usando o ControlTemplate padrão mostrado nos estados Unchecked, Checked e Indeterminate.

Você pode alterar essas características criando um ControlTemplate para o CheckBox . Por exemplo, se você quiser que o conteúdo da caixa de seleção esteja abaixo da caixa de seleção e quiser usar um X para indicar que um usuário selecionou a caixa de seleção. Você especifica essas características no ControlTemplate do CheckBox.

Para usar um modelo personalizado com um controle, atribua o ControlTemplate à propriedade Template do controle. Aqui está um CheckBox usando um ControlTemplate chamado CheckBoxTemplate1. Mostramos a Linguagem de Marcação de Aplicações Extensível (XAML) para o ControlTemplate na próxima seção.

<CheckBox Content="CheckBox" Template="{StaticResource CheckBoxTemplate1}" IsThreeState="True" Margin="20"/>

Veja como este CheckBox fica nos estados Unchecked, Checkede Indeterminate depois de aplicarmos nosso modelo.

Especificar a estrutura visual de um controle

Ao criar umControlTemplate, você combina objetos FrameworkElement para criar um único controle. Um ControlTemplate deve ter apenas um FrameworkElement como seu elemento raiz. O elemento raiz geralmente contém outros objetos FrameworkElement. A combinação de objetos compõe a estrutura visual do controle.

Este XAML cria um ControlTemplate para um CheckBox que especifica que o conteúdo do controle está abaixo da caixa de seleção. O elemento raiz é um Border. O exemplo especifica um Path para criar um X que indica que um usuário selecionou o CheckBoxe uma Ellipse que indica um estado indeterminado. Observe que a Opacidade está definida como 0 no Caminho e na Elipse para que, por padrão, nenhum dos dois apareça.

Um TemplateBinding é uma associação especial que vincula o valor de uma propriedade em um modelo de controle ao valor de alguma outra propriedade exposta no controle modelado. TemplateBinding só pode ser usado dentro de uma definição ControlTemplate em XAML. Confira Extensão de marcação TemplateBinding para obter mais informações.

<ControlTemplate x:Key="CheckBoxTemplate1" TargetType="CheckBox">
    <Border BorderBrush="{TemplateBinding BorderBrush}"
            BorderThickness="{TemplateBinding BorderThickness}"
            Background="{TemplateBinding Background}">
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="*"/>
                <RowDefinition Height="25"/>
            </Grid.RowDefinitions>
            <Rectangle x:Name="NormalRectangle" Fill="Transparent" Height="20" Width="20"
                       Stroke="{ThemeResource SystemControlForegroundBaseMediumHighBrush}"
                       StrokeThickness="{ThemeResource CheckBoxBorderThemeThickness}"
                       UseLayoutRounding="False"/>
            <!-- Create an X to indicate that the CheckBox is selected. -->
            <Path x:Name="CheckGlyph"
                  Data="M103,240 L111,240 119,248 127,240 135,240 123,252 135,264 127,264 119,257 111,264 103,264 114,252 z"
                  Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                  FlowDirection="LeftToRight"
                  Height="14" Width="16" Opacity="0" Stretch="Fill"/>
            <Ellipse x:Name="IndeterminateGlyph"
                     Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                     Height="8" Width="8" Opacity="0" UseLayoutRounding="False" />
            <ContentPresenter x:Name="ContentPresenter"
                              ContentTemplate="{TemplateBinding ContentTemplate}"
                              Content="{TemplateBinding Content}"
                              Margin="{TemplateBinding Padding}" Grid.Row="1"
                              HorizontalAlignment="Center"
                              VerticalAlignment="{TemplateBinding VerticalContentAlignment}"/>
        </Grid>
    </Border>
</ControlTemplate>

Especificar o comportamento visual de um controle

Um comportamento visual especifica a aparência de um controle quando ele está em um determinado estado. O controle CheckBox tem três estados de verificação: , e . O valor da propriedade IsChecked determina o estado do CheckBox, e seu estado determina o que aparece na caixa.

Esta tabela lista os valores possíveis de IsChecked, os estados correspondentes do CheckBox e a aparência do CheckBox .

Você especifica a aparência de um controle quando ele está em um determinado estado usando objetos VisualState. Um VisualState contém um Setter ou Storyboard que altera a aparência dos elementos no ControlTemplate. Quando o controle entra no estado especificado pela propriedade VisualState.Name, as alterações de propriedade no Setter ou Storyboard são aplicadas. Quando o controle sai do estado, as alterações são removidas. Você adiciona objetos VisualState a objetos VisualStateGroup. Você adiciona objetos VisualStateGroup à propriedade anexada VisualStateManager.VisualStateGroups , que você define no FrameworkElement raiz do ControlTemplate.

Este XAML mostra os objetos VisualState para os estados , e . O exemplo define a propriedade anexada VisualStateManager.VisualStateGroups no Border, que é o elemento raiz do ControlTemplate. O VisualState Checked especifica que a Opacidade do Caminho denominado CheckGlyph (que mostramos no exemplo anterior) é 1. O IndeterminateVisualState especifica que o Opacity do Ellipse nomeado IndeterminateGlyph é 1. O UncheckedVisualState não tem nenhum Setter ou Storyboard, assim, a CheckBox volta a sua aparência padrão.

<ControlTemplate x:Key="CheckBoxTemplate1" TargetType="CheckBox">
    <Border BorderBrush="{TemplateBinding BorderBrush}"
            BorderThickness="{TemplateBinding BorderThickness}"
            Background="{TemplateBinding Background}">

        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup x:Name="CheckStates">
                <VisualState x:Name="Checked">
                    <VisualState.Setters>
                        <Setter Target="CheckGlyph.Opacity" Value="1"/>
                    </VisualState.Setters>
                    <!-- This Storyboard is equivalent to the Setter. -->
                    <!--<Storyboard>
                        <DoubleAnimation Duration="0" To="1"
                         Storyboard.TargetName="CheckGlyph" Storyboard.TargetProperty="Opacity"/>
                    </Storyboard>-->
                </VisualState>
                <VisualState x:Name="Unchecked"/>
                <VisualState x:Name="Indeterminate">
                    <VisualState.Setters>
                        <Setter Target="IndeterminateGlyph.Opacity" Value="1"/>
                    </VisualState.Setters>
                    <!-- This Storyboard is equivalent to the Setter. -->
                    <!--<Storyboard>
                        <DoubleAnimation Duration="0" To="1"
                         Storyboard.TargetName="IndeterminateGlyph" Storyboard.TargetProperty="Opacity"/>
                    </Storyboard>-->
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>

        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="*"/>
                <RowDefinition Height="25"/>
            </Grid.RowDefinitions>
            <Rectangle x:Name="NormalRectangle" Fill="Transparent" Height="20" Width="20"
                       Stroke="{ThemeResource SystemControlForegroundBaseMediumHighBrush}"
                       StrokeThickness="{ThemeResource CheckBoxBorderThemeThickness}"
                       UseLayoutRounding="False"/>
            <!-- Create an X to indicate that the CheckBox is selected. -->
            <Path x:Name="CheckGlyph"
                  Data="M103,240 L111,240 119,248 127,240 135,240 123,252 135,264 127,264 119,257 111,264 103,264 114,252 z"
                  Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                  FlowDirection="LeftToRight"
                  Height="14" Width="16" Opacity="0" Stretch="Fill"/>
            <Ellipse x:Name="IndeterminateGlyph"
                     Fill="{ThemeResource CheckBoxForegroundThemeBrush}"
                     Height="8" Width="8" Opacity="0" UseLayoutRounding="False" />
            <ContentPresenter x:Name="ContentPresenter"
                              ContentTemplate="{TemplateBinding ContentTemplate}"
                              Content="{TemplateBinding Content}"
                              Margin="{TemplateBinding Padding}" Grid.Row="1"
                              HorizontalAlignment="Center"
                              VerticalAlignment="{TemplateBinding VerticalContentAlignment}"/>
        </Grid>
    </Border>
</ControlTemplate>

Para entender melhor como objetos de VisualState funcionam, considere o que acontece quando o CheckBox vai do estado Unchecked para o estado Checked, depois para o estado Indeterminate e então retorna para o estado Unchecked. Aqui estão as transições.

 Para obter mais informações sobre como criar estados visuais para controles e, em particular, como usar a classe Storyboard e os tipos de animação, consulte Animações em storyboard para estados visuais.

Usar ferramentas para trabalhar com temas facilmente

Uma maneira rápida de aplicar temas aos seus controles é clicar com o botão direito do mouse em um controle no Microsoft Visual Studio Document Outline e selecionar Edit ou Edit Style (dependendo do controle no qual você está clicando com o botão direito do mouse). Em seguida, você pode aplicar um tema existente selecionando Aplicar Recurso ou definir um novo selecionando Criar Vazio.

Controles e acessibilidade

Ao criar um novo modelo para um controle, além de possivelmente alterar o comportamento do controle e a aparência visual, você também pode estar alterando a forma como o controle se representa para estruturas de acessibilidade. O Windows app dá suporte à estrutura do Microsoft Automação da Interface do Usuário para acessibilidade. Todos os controles padrão e seus modelos têm suporte para tipos e padrões comuns de controle de Automação da Interface do Usuário apropriados para a finalidade e a função do controle. Esses tipos de controle e padrões são interpretados por clientes de Automação da Interface do Usuário, como tecnologias assistivas, e isso permite que um controle seja acessível como parte de uma interface de usuário de aplicativo acessível maior.

Para separar a lógica de controle básica e também para atender a alguns dos requisitos arquitetônicos da Automação de IU, as classes de controle incluem seu suporte de acessibilidade em uma classe separada, um par de automação. Os pares de automação às vezes interagem com os modelos de controle porque esperam que certas partes nomeadas existam nos modelos, para que funcionalidades como habilitar tecnologias assistivas para invocar ações de botões sejam possíveis.

Ao criar um controle personalizado completamente novo, você também pode querer criar um novo par de automação para acompanhá-lo. Para obter mais informações, consulte Pares de automação personalizados.

Saiba mais sobre o modelo padrão de um controle

Os tópicos que documentam os estilos e modelos para controles XAML mostram trechos do mesmo XAML inicial que você veria se usou as técnicas Editar Tema ou Editar Estilo explicadas anteriormente. Cada tópico lista os nomes dos estados visuais, os recursos de tema usados e o XAML completo para o estilo que contém o modelo. Os tópicos podem ser orientações úteis se você já tiver começado a modificar um modelo e quiser ver a aparência do modelo original ou verificar se o novo modelo tem todos os estados visuais nomeados necessários.

Recursos de tema em modelos de controle

Para alguns dos atributos nos exemplos XAML, talvez você tenha notado referências de recurso que usam a extensão de marcação {ThemeResource}. Essa é uma técnica que permite que um único modelo de controle use recursos que podem ser valores diferentes, dependendo de qual tema está ativo no momento. Isso é particularmente importante para pincéis e cores, pois a principal finalidade dos temas é permitir que os usuários escolham se querem um tema escuro, claro ou de alto contraste aplicado ao sistema em geral. Os aplicativos que usam o sistema de recursos XAML podem usar um conjunto de recursos apropriado para esse tema, de modo que as opções de tema na interface do usuário de um aplicativo reflitam a opção de tema em todo o sistema do usuário.

Obter o código de exemplo

• exemplo da Galeria WinUI 3
• Exemplo de controle de edição de texto personalizado