Metadados de propriedade da estrutura

Você pode definir opções de metadados de propriedade da estrutura para propriedades de dependência no nível da estrutura do WPF (Windows Presentation Foundation). A designação de nível de estrutura do WPF se aplica quando APIs de apresentação do WPF e executáveis lidam com renderização e associação de dados. APIs de apresentação e executáveis consultam a FrameworkPropertyMetadata propriedade de uma dependência.

Pré-requisitos

O artigo pressupõe um conhecimento básico das propriedades de dependência e que você leu visão geral das propriedades de dependência. Para seguir os exemplos neste artigo, ele ajuda se você estiver familiarizado com XAML (Extensible Application Markup Language) e saber como escrever aplicativos WPF.

Categorias de metadados de propriedades do framework

FrameworkPropertyMetadata se enquadra nessas categorias:

• Metadados que afetam o layout de um elemento, especificamente os sinalizadores de metadados AffectsArrange, AffectsMeasure e AffectsRender. Você poderá definir esses sinalizadores se a implementação da propriedade de dependência afetar um aspecto visual e estiver implementando MeasureOverride ou ArrangeOverride em sua classe. Os métodos MeasureOverride e ArrangeOverride oferecem informações de comportamento específicas da implementação e de renderização para o sistema de layout. Quando AffectsArrange, AffectsMeasure, ou AffectsRender são definidos como true nos metadados de uma propriedade de dependência e seu valor efetivo muda, o sistema de propriedades do WPF iniciará uma solicitação para invalidar os visuais do elemento para disparar um redesenho.

• Metadados que afetam o layout do elemento pai em relação ao elemento filho, especificamente os sinalizadores de metadados AffectsParentArrange e AffectsParentMeasure. Exemplos de propriedades de dependência do WPF que definem esses sinalizadores são FixedPage.Left e Paragraph.KeepWithNext.

• Metadados de herança do valor da propriedade, especificamente os sinalizadores de metadados Inherits e OverridesInheritanceBehavior. Por padrão, as propriedades de dependência não herdam valores. OverridesInheritanceBehavior permite que o caminho da herança também viaje para uma árvore visual, o que é necessário para alguns cenários de composição de controle. Para obter mais informações, consulte Herança do valor da propriedade.

  Observação

  O termo "herda" no contexto de valores de propriedade é específico para propriedades de dependência e não se relaciona diretamente com tipos de código gerenciados e herança de membro por meio de tipos derivados. No contexto das propriedades dependentes, isso significa que os elementos filhos podem herdar valores dessas propriedades de seus elementos pais.

• Metadados de associação de dados, especificamente os sinalizadores de metadados BindsTwoWayByDefault e IsNotDataBindable. Por padrão, as propriedades de dependência na estrutura do WPF dão suporte à associação unidirecional. Considere definir a associação bidirecional como padrão para propriedades que reportam estado e são modificáveis por ação do usuário, por exemplo IsSelected. Além disso, considere definir a associação bidirecional como o padrão quando os usuários de um controle esperam que uma propriedade a implemente, por exemplo , TextBox.Text. BindsTwoWayByDefault afeta apenas o modo de associação padrão. Para editar a direção do fluxo de dados de uma associação, defina Binding.Mode. Você pode usar IsNotDataBindable para desabilitar a associação de dados quando não houver nenhum caso de uso para ela. Para obter mais informações sobre associações de dados, consulte a visão geral da associação de dados.

• Metadados de diário, especificamente o Journal sinalizador de metadados. O valor padrão do Journal sinalizador é apenas true para algumas propriedades de dependência, como SelectedIndex. Os controles de entrada do usuário devem definir o Journal sinalizador para propriedades cujos valores contêm seleções de usuário que precisam ser armazenadas. O Journal indicador é lido por aplicações ou serviços que suportam registros, incluindo serviços de registro do WPF. Para obter informações sobre como armazenar etapas de navegação, confira a visão geral da navegação

FrameworkPropertyMetadata deriva diretamente de UIPropertyMetadata, e implementa os sinalizadores discutidos aqui. A menos que seja definido especificamente, FrameworkPropertyMetadata os sinalizadores têm um valor padrão de false.

Lendo FrameworkPropertyMetadata

Para recuperar metadados de uma propriedade de dependência, chame o identificador GetMetadata no DependencyProperty. A GetMetadata chamada retorna um PropertyMetadata objeto. Se você precisar consultar os valores de metadados da estrutura, converta PropertyMetadata para FrameworkPropertyMetadata.

Especificando FrameworkPropertyMetadata

Ao registrar uma propriedade de dependência, você tem a opção de criar e atribuir metadados a ela. O objeto de metadados que você atribui pode ser PropertyMetadata ou uma de suas classes derivadas, como FrameworkPropertyMetadata. Escolha FrameworkPropertyMetadata para propriedades de dependência que utilizam APIs de apresentação do WPF e executáveis para renderização e vinculação de dados. Uma opção mais avançada é derivar de FrameworkPropertyMetadata para criar uma classe de relatório de metadados personalizada com mais sinalizadores. Ou você pode usar UIPropertyMetadata para propriedades não estruturais que afetam a renderização da interface do usuário.

Embora as opções de metadados normalmente sejam definidas durante o registro de uma nova propriedade de dependência, você pode resspecificá-las em chamadas OverrideMetadata ou AddOwner. Ao substituir metadados, sempre substitua com o mesmo tipo de metadados usado durante o registro de propriedade.

As características de propriedade expostas por FrameworkPropertyMetadata às vezes são conhecidas como sinalizadores. Se você estiver criando uma FrameworkPropertyMetadata instância, haverá duas maneiras de preencher valores de sinalizador:

1. Defina os sinalizadores em uma instância do tipo de enumeração FrameworkPropertyMetadataOptions. FrameworkPropertyMetadataOptions permite especificar sinalizadores de metadados na combinação OR bit a bit. Em seguida, crie uma instância FrameworkPropertyMetadata usando um construtor que tenha um FrameworkPropertyMetadataOptions parâmetro e passe sua FrameworkPropertyMetadataOptions instância. Para alterar os sinalizadores de metadados depois de passar FrameworkPropertyMetadataOptions ao construtor FrameworkPropertyMetadata, altere a propriedade correspondente na nova instância FrameworkPropertyMetadata. Por exemplo, se você definir o sinalizador FrameworkPropertyMetadataOptions.NotDataBindable, poderá desfazer isso definindo FrameworkPropertyMetadata.IsNotDataBindable para false.

2. Crie uma instância FrameworkPropertyMetadata usando um construtor que não tenha um FrameworkPropertyMetadataOptions parâmetro e, em seguida, defina os sinalizadores aplicáveis Boolean em FrameworkPropertyMetadata. Defina valores de sinalizador antes de associar sua FrameworkPropertyMetadata instância a uma propriedade de dependência, caso contrário, você receberá um InvalidOperationException.

Comportamento de substituição de metadados

Quando você substitui os metadados de propriedade da estrutura, os valores de metadados alterados substituem ou são mesclados com os valores originais:

• Para um PropertyChangedCallback, a lógica padrão de mesclagem mantém os valores anteriores de PropertyChangedCallback em uma tabela, e todos são acionados quando há uma alteração de propriedade. A ordem de retorno de chamada é determinada pela profundidade da classe, em que um retorno de chamada registrado pela classe base na hierarquia seria executado primeiro. Os retornos de chamada herdados são executados apenas uma vez e pertencem à classe que os adicionou aos metadados.

• Para um DefaultValue, o novo valor substituirá o valor padrão existente. Se você não especificar um DefaultValue nos metadados de substituição e se o FrameworkPropertyMetadata existente tiver o sinalizador Inherits definido, o valor padrão vem do ancestral mais próximo que especificou DefaultValue nos metadados.

• Para um CoerceValueCallback, o novo valor substituirá um valor existente CoerceValueCallback . Se você não especificar um CoerceValueCallback nos metadados de substituição, o valor será proveniente do ancestral mais próximo na cadeia de herança que especificou um CoerceValueCallback.

• Para FrameworkPropertyMetadata sinalizadores não herdados, você pode substituir o valor padrão false com o valor true. No entanto, você só pode sobrescrever um valor de true por um valor de false para Inherits, Journal, OverridesInheritanceBehavior, e SubPropertiesDoNotAffectRender.

Consulte também

• PropertyMetadata
• GetMetadata
• OverrideMetadata
• AddOwner
• Metadados de propriedade da dependência
• Visão geral das propriedades de dependência
• Propriedades de dependência personalizada