Classes TemplateSettingsTemplate settings classes

Pré-requisitosPrerequisites

Presumimos que você saiba adicionar controles à sua interface do usuário, definir as suas propriedades e atribuir manipuladores de eventos.We assume that you can add controls to your UI, set their properties, and attach event handlers. Para obter instruções sobre como adicionar controles ao seu aplicativo, consulte Adicionar controles e manipular eventos.For instructions for adding controls to your app, see Add controls and handle events. Também presumimos que você tem noções básicas sobre como definir um modelo personalizado para um controle, fazendo uma cópia do modelo padrão e editando-a.We also assume that you know the basics of how to define a custom template for a control by making a copy of the default template and editing it. Para saber mais sobre isso, consulte Início rápido: modelos de controle.For more info on this, see Quickstart: Control templates.

O cenário para classes TemplateSettingsThe scenario for TemplateSettings classes

As classes TemplateSettings fornecem um conjunto de propriedades que são usadas quando você define um novo modelo de controle de um controle.TemplateSettings classes provide a set of properties that are used when you define a new control template for a control. As propriedades têm valores como medidas de pixel para o tamanho de determinadas partes do elemento de interface do usuário.The properties have values such as pixel measurements for the size of certain UI element parts. Às vezes, os valores são valores calculados que são provenientes da lógica do controle que normalmente não é fácil de substituir ou até mesmo acessar.The values are sometimes calculated values that come from control logic that isn't typically easy to override or even access. Algumas das propriedades servem como valores From e To que controlam as transições e as animações de partes e, portanto, as propriedades TemplateSettings relevantes vêm em pares.Some of the properties are intended as From and To values that control transitions and animations of parts, and thus the relevant TemplateSettings properties come in pairs.

Há várias classes TemplateSettings.There are several TemplateSettings classes. Todas elas estão no namespace Windows.UI.Xaml.Controls.Primitives.All of them are in the Windows.UI.Xaml.Controls.Primitives namespace. Aqui está uma lista das classes e um link para a propriedade TemplateSettings do controle relevante.Here's a list of the classes, and a link to the TemplateSettings property of the relevant control. Essa propriedade TemplateSettings é como você acessa os valores TemplateSettings para o controle e pode estabelecer associações de modelo às suas propriedades:This TemplateSettings property is how you access the TemplateSettings values for the control, and can establish template bindings to its properties:

As propriedades TemplateSettings sempre devem ser usadas em XAML, não o código.TemplateSettings properties are always intended to be used in XAML, not code. Elas são subpropriedades somente leitura de uma propriedade TemplateSettings somente leitura de um controle pai.They are read-only sub-properties of a read-only TemplateSettings property of a parent control. Em um cenário de controle personalizado avançado, no qual você está criando uma nova classe baseada em Control e portanto pode influenciar a lógica do controle, considere a definição de uma propriedade TemplateSettings personalizada no controle para comunicar informações que podem ser úteis para qualquer um que esteja remodelando o controle.For an advanced custom control scenario, where you're creating a new Control-based class and thus can influence the control logic, consider defining a custom TemplateSettings property on the control in order to communicate info that might be useful for anyone that is re-templating the control. Assim como esse valor somente leitura da propriedade, defina uma nova classe TemplateSettings para o seu controle, que tenha propriedades somente leitura para cada um dos itens de informação, seja relevante para as medidas do modelo, posicionamento da animação, e assim por diante, e forneça aos chamados a instância do tempo de execução dessa classe que é inicializada através da lógica do controle.As that property's read-only value, define a new TemplateSettings class related to your control that has read-only properties for each of the info items that are relevant for template measurements, animation positioning, and so on, and give callers the runtime instance of that class that's initialized using your control logic. As classes TemplateSettings são derivadas de DependencyObject, de forma que as propriedades possam usar o sistema de propriedade de relevância dos retornos de chamada com propriedade alterada.TemplateSettings classes are derived from DependencyObject, so that the properties can use the dependency property system for property-changed callbacks. Mas os identificadores de propriedade de dependência da propriedades não são expostos como API pública, pois as propriedades TemplateSettings não se destinam a ser somente leitura para os chamadores.But the dependency property identifiers for the properties aren't exposed as public API, because the TemplateSettings properties are meant to be read-only to callers.

Como usar TemplateSettings a um modelo de controle.How to use TemplateSettings in a control template

Aqui está um exemplo que vêm dos modelos de controle XAML padrão iniciais.Here's an example that comes from the starting default XAML control templates. Este em especial é do modelo padrão de ProgressRing:This particular one is from the default template of ProgressRing:

<Ellipse
    x:Name="E1"
    Style="{StaticResource ProgressRingEllipseStyle}"
    Width="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Height="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Margin="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseOffset}"
    Fill="{TemplateBinding Foreground}"/>

O XAML completo do modelo ProgressRing tem centenas de linhas, portanto, este é apenas um trecho minúsculo.The full XAML for the ProgressRing template is hundreds of lines, so this is just a tiny excerpt. Este XAML define a parte de um controle que é um dos 6 elementos Ellipse que representam a animação de rotação de progresso indeterminado.This XAML defines a control part that is one of 6 Ellipse elements that portray the spinning animation for indeterminate progress. Como desenvolvedor, talvez você não goste de círculos e talvez use um primitivo de elemento gráfico diferente ou uma forma básica distinta para a progressão da animação.As a developer, you might not like the circles and might use a different graphics primitive or a different basic shape for how the animation progresses. Por exemplo, você pode criar um ProgressRing que use um conjunto de elementos Rectangle organizados em um quadrado.For example, you might compose a ProgressRing that uses a set of Rectangle elements arranged in a square instead. Se for o caso, cada componente Rectangle individual de seu novo modelo pode se parecer com o seguinte:If so, each individual Rectangle component of your new template might look like this:

<Rectangle
    x:Name="R1"
    Width="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Height="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseDiameter}"
    Margin="{Binding RelativeSource={RelativeSource TemplatedParent}, 
        Path=TemplateSettings.EllipseOffset}"
    Fill="{TemplateBinding Foreground}"/>

O motivo pelo qual as propriedades TemplateSettings são úteis aqui é porque elas são valores calculados vindos da lógica de controle básica de ProgressRing.The reason that the TemplateSettings properties are useful here is because they are calculated values coming from the basic control logic of ProgressRing. O cálculo é feito dividindo ActualWidth total e ActualHeight de ProgressRing e distribuindo uma medida calculada de cada um dos elementos de movimento em seu modelo para que as partes do modelo possam acomodar o conteúdo.The calculation is dividing up the overall ActualWidth and ActualHeight of the ProgressRing, and allotting a calculated measurement for each of the motion elements in its templates so that the template parts can size to content.

Este é outro exemplo de uso dos modelos de controle do padrão XAML, desta vez mostrando um dos conjuntos de propriedades que são From e To de uma animação.Here's another example usage from the default XAML control templates, this time showing one of the property sets that are the From and To of an animation. Isso provém do modelo padrão ComboBox:This is from the ComboBox default template:

<VisualStateGroup x:Name="DropDownStates">
    <VisualState x:Name="Opened">
        <Storyboard>
            <SplitOpenThemeAnimation
               OpenedTargetName="PopupBorder"
               ContentTargetName="ScrollViewer"
               ClosedTargetName="ContentPresenter"
               ContentTranslationOffset="0"
               OffsetFromCenter="{Binding RelativeSource={RelativeSource TemplatedParent}, 
                 Path=TemplateSettings.DropDownOffset}"
               OpenedLength="{Binding RelativeSource={RelativeSource TemplatedParent}, 
                 Path=TemplateSettings.DropDownOpenedHeight}"
               ClosedLength="{Binding RelativeSource={RelativeSource TemplatedParent},
                 Path=TemplateSettings.DropDownClosedHeight}" />
        </Storyboard>
   </VisualState>
...
</VisualStateGroup>

Novamente, existem muitos XAML no modelo, portanto, mostramos apenas um trecho.Again there is lots of XAML in the template so we only show an excerpt. E este é apenas um dos vários estados e animações de tema que usam as mesmas propriedades ComboBoxTemplateSettings.And this is only one of several states and theme animations that each use the same ComboBoxTemplateSettings properties. Para ComboBox, o uso dos valores ComboBoxTemplateSettings por meio de associações reforça que as animações relacionadas no modelo pararão e começarão nas posições que são baseadas em valores compartilhados e, portanto, fazem a transição perfeitamente.For ComboBox, use of the ComboBoxTemplateSettings values through bindings enforces that related animations in the template will stop and start at positions that are based on shared values, and thus transition smoothly.

Observação    Quando você usa valores de TemplateSettings como parte de seu modelo de controle, certifique-se de que você está definindo propriedades que correspondem ao tipo do valor.Note   When you do use TemplateSettings values as part of your control template, make sure you're setting properties that match the type of the value. Caso contrário, talvez você precise criar um conversor de valor para a associação de forma que o tipo de destino da associação possa ser convertido de um tipo de origem diferente do valor TemplateSettings.If not, you might need to create a value converter for the binding so that the target type of the binding can be converted from a different source type of the TemplateSettings value. Para saber mais, consulte IValueConverter.For more info, see IValueConverter.