Metadados de propriedade de dependência

O sistema de propriedades da Windows Presentation Foundation (WPF) inclui um sistema de relatórios de metadados para propriedades de dependência. As informações disponíveis por meio do sistema de relatórios de metadados excedem o que está disponível por meio de reflexão ou características gerais do CLR (Common Language Runtime). Ao registrar uma propriedade de dependência, você tem a opção de criar e atribuir metadados a ela. Se você derivar de uma classe que define uma propriedade de dependência, poderá sobrescrever os metadados para a propriedade de dependência herdada. E, se você adicionar sua classe como controlador de uma propriedade de dependência, poderá sobrescrever os metadados da propriedade de dependência herdada.

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.

Como os metadados são usados

Você pode consultar metadados de propriedade de dependência para examinar as características de uma propriedade de dependência. Quando o sistema de propriedades processa uma propriedade de dependência, ele acessa seus metadados. O objeto de metadados de uma propriedade de dependência contém os seguintes tipos de informações:

• O valor padrão da propriedade de dependência, que é definida pelo sistema de propriedades quando nenhum outro valor se aplica, como um valor local, estilo ou herança. Para obter mais informações sobre a precedência de valores durante a atribuição em tempo de execução de valores de propriedade de dependência, consulte Precedência de valor da propriedade de dependência.

• Referências a retornos de chamada de valor de coerção e retornos de chamada de alteração de propriedade no tipo proprietário. Você só pode obter referências a callbacks que tenham um public modificador de acesso ou estejam dentro do seu escopo de acesso permitido. Para obter mais informações sobre retornos de chamada de propriedades de dependência, consulte retornos de chamada e validação de propriedade de dependência.

• Características da propriedade de dependência no nível da estrutura do WPF (se a propriedade de dependência for uma propriedade da estrutura do WPF). Processos do WPF, como o mecanismo de layout da estrutura e a lógica de herança de propriedade, consultam metadados no nível da estrutura do WPF. Para obter mais informações, consulte metadados de propriedade do Framework.

APIs de metadados

A PropertyMetadata classe armazena a maioria dos metadados usados pelo sistema de propriedades. As instâncias de metadados podem ser criadas e atribuídas por:

• Tipos que registram propriedades de dependência no sistema de propriedades.

• Tipos que herdam de uma classe que define uma propriedade de dependência.

• Tipos que se adicionam como proprietário de uma propriedade de dependência.

Se um tipo registrar uma propriedade de dependência sem especificar metadados, o sistema de propriedades atribuirá um PropertyMetadata objeto com valores padrão para esse tipo à propriedade de dependência.

Para recuperar metadados de uma propriedade de dependência, use uma das GetMetadata sobrecargas do identificador DependencyProperty. Os metadados são retornados como um PropertyMetadata objeto.

Classes de metadados mais específicas, derivadas de PropertyMetadata, existem para diferentes áreas de arquitetura. Por exemplo, UIPropertyMetadata dá suporte a relatórios de animação e FrameworkPropertyMetadata dá suporte a propriedades da estrutura do WPF. As propriedades de dependência também podem ser registradas com as PropertyMetadata classes derivadas. Embora GetMetadata retorne um objeto PropertyMetadata, quando aplicável, você pode fazer um casting para um tipo derivado para examinar propriedades específicas do tipo.

As características de propriedade expostas por FrameworkPropertyMetadata às vezes são conhecidas como sinalizadores. Ao criar uma FrameworkPropertyMetadata instância, você tem a opção de passar uma instância do tipo FrameworkPropertyMetadataOptions de enumeração para o FrameworkPropertyMetadata construtor. FrameworkPropertyMetadataOptions permite especificar sinalizadores de metadados em combinação bit a bit. O FrameworkPropertyMetadata usa o FrameworkPropertyMetadataOptions para manter o comprimento de sua assinatura do construtor razoável. No registro da propriedade de dependência, os sinalizadores de metadados que você define são expostos como propriedades FrameworkPropertyMetadataOptions dentro de FrameworkPropertyMetadata, em vez de uma combinação bit a bit de sinalizadores, para tornar as características dos metadados mais intuitivas para consulta.

Substituir ou criar novos metadados?

Quando você herda uma propriedade de dependência, tem a opção de alterar as características da propriedade de dependência substituindo seus metadados. No entanto, talvez você nem sempre consiga realizar seu cenário de propriedade de dependência substituindo metadados e, às vezes, é necessário definir uma propriedade de dependência personalizada em sua classe com novos metadados. As propriedades de dependência personalizadas têm os mesmos recursos que as propriedades de dependência definidas pelos tipos do WPF. Para obter mais informações, consulte Propriedades de dependência personalizadas.

Uma característica de uma propriedade de dependência que você não pode substituir é o tipo de valor. Se uma propriedade de dependência herdada tiver o comportamento aproximado necessário, mas seu cenário exigir um tipo de valor diferente, considere implementar uma propriedade de dependência personalizada. Você pode vincular os valores de propriedade através de conversão de tipo ou alguma outra implementação em sua classe derivada.

Cenários para substituir metadados

Cenários de exemplo para substituir metadados de propriedade de dependência existente são:

• Alterando o valor padrão, que é um cenário comum.

• Alterando ou adicionando callbacks de alteração de propriedade, o que pode ser necessário caso uma propriedade de dependência herdada interaja com outras propriedades de dependência de maneira diferente de sua implementação original. Uma das características de um modelo de programação que dá suporte a código e marcação é que os valores de propriedade podem ser definidos em qualquer ordem. Esse fator pode afetar a forma como você implementa funções de retorno de alteração de propriedade. Para obter mais informações, consulte funções de retorno e validação da propriedade de dependência.

• Alterando as opções de metadados de propriedade do framework WPF. Normalmente, as opções de metadados são definidas durante o registro de uma nova propriedade de dependência, mas você pode respecificá-las em chamadas OverrideMetadata ou AddOwner. Para mais informações sobre como substituir os metadados de propriedade do framework, consulte Especificando FrameworkPropertyMetadata. Para saber como definir opções de metadados de propriedade da estrutura ao registrar uma propriedade de dependência, consulte as propriedades de dependência personalizadas.

Substituindo metadados

Ao implementar uma nova propriedade de dependência, você pode definir seus metadados usando sobrecargas do Register método. Se sua classe herdar uma propriedade de dependência, você poderá substituir valores de metadados herdados usando o OverrideMetadata método. Por exemplo, você pode usar OverrideMetadata para definir valores específicos do tipo. Para obter mais informações e exemplos de código, consulte Sobrescrever metadados de uma propriedade de dependência.

Um exemplo de uma propriedade de dependência do WPF é Focusable. A FrameworkElement classe registra Focusable. A Control classe deriva de FrameworkElement, herda a Focusable propriedade de dependência e substitui os metadados da propriedade herdada. A substituição altera o valor da propriedade padrão de false para true, mas preserva outros valores de metadados herdados.

Como a maioria das propriedades de dependência existentes não são propriedades virtuais, sua implementação herdada sombreia o membro existente. Quando você substitui uma característica de metadados, o novo valor de metadados substitui o valor original ou eles são mesclados:

• Para um DefaultValue, o novo valor substituirá o valor padrão existente. Se você não especificar um DefaultValue nos metadados de substituição, o valor será proveniente do ancestral mais próximo especificado DefaultValue nos metadados.

• Para um PropertyChangedCallback, a lógica de mesclagem padrão armazena todos os PropertyChangedCallback valores em uma tabela e todos são invocados em 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.

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

Adicionar uma classe como proprietário

Para "herdar" uma propriedade de dependência registrada em uma hierarquia de classe diferente, use o AddOwner método. Esse método normalmente é usado quando a classe de adição não é derivada do tipo que registrou a propriedade de dependência. Na chamada AddOwner, a classe de inclusão pode criar e atribuir metadados específicos do tipo para a propriedade de dependência herdada. Para ser um participante completo no sistema de propriedades, por meio de código e marcação, a classe de adição deve implementar esses membros públicos:

• Um campo identificador de propriedade de dependência. O valor do identificador da propriedade de dependência é o valor retornado da AddOwner chamada. Esse campo deve ser um public static readonly campo do tipo DependencyProperty.

• Um wrapper CLR que implementa os acessadores get e set. Usando um wrapper de propriedade, consumidores podem obter ou definir valores de propriedades de dependência da mesma forma que fariam com qualquer outra propriedade CLR. Os acessadores get e set interagem com o sistema de propriedades subjacente por meio de chamadas DependencyObject.GetValue e DependencyObject.SetValue, passando o identificador de propriedade de dependência como um parâmetro. Implemente o wrapper da mesma maneira que faria ao registrar uma propriedade de dependência personalizada. Para obter mais informações, consulte Propriedades de dependência personalizadas

Uma classe que chama AddOwner tem os mesmos requisitos para expor o modelo de objeto da propriedade de dependência herdada como uma classe que define uma nova propriedade de dependência personalizada. Para obter mais informações, consulte Adicionar um tipo de proprietário para uma propriedade de dependência

Metadados de propriedade anexados

No WPF, a maioria das propriedades anexadas relacionadas à interface do usuário em tipos WPF são implementadas como propriedades de dependência. As propriedades anexadas implementadas como propriedades de dependência dão suporte a conceitos de propriedade de dependência, como metadados que classes derivadas podem substituir. Os metadados de uma propriedade anexada geralmente não são diferentes de uma propriedade de dependência. Você pode substituir o valor padrão, os retornos de chamada de alteração de propriedade, e as propriedades do framework WPF para a propriedade anexada herdada, em instâncias da classe que a substitui. Para obter mais informações, consulte Metadados de propriedade anexados

Adicionar uma classe como proprietário de uma propriedade anexada

Para herdar uma propriedade anexada de outra classe, mas expô-la como uma propriedade de dependência não anexada em sua classe:

• Chame AddOwner para adicionar sua classe como proprietário da propriedade de dependência anexada.

• Atribua o valor retornado da AddOwner chamada a um public static readonly campo, para uso como o identificador da propriedade de dependência.

• Defina um wrapper CLR, que adiciona a propriedade como membro de uma classe e dá suporte ao uso de propriedade não anexada.

Consulte também

• PropertyMetadata
• DependencyObject
• DependencyProperty
• GetMetadata
• AddOwner
• Visão geral das propriedades de dependência
• Metadados de propriedade da estrutura