Compartilhar via

Visão geral de adornos

  • Artigo

Adoradores são um tipo especial de FrameworkElement, usado para fornecer pistas visuais para um usuário. Entre outros usos, adornos podem ser usados para adicionar alças funcionais a elementos ou para fornecer informações de estado sobre um controle.

Sobre adornos

Um Adorner é um costume FrameworkElement que está vinculado a um UIElementarquivo . Os adornos são renderizados em um AdornerLayer, que é uma superfície de renderização que está sempre em cima do elemento adornado ou de uma coleção de elementos adornados. A renderização de um adorno é independente da renderização do UIElement adorno a que o adorno está vinculado. Um adorno é tipicamente posicionado em relação ao elemento ao qual está ligado, usando a origem de coordenada 2D padrão localizada no canto superior esquerdo do elemento adornado.

Aplicações comuns de adornos incluem:

  • Adicionar alças funcionais a um que permitem que um UIElement usuário manipule o elemento de alguma forma (redimensionar, girar, reposicionar, etc.).
  • Fornecer comentários visuais para indicar vários estados ou em resposta a vários eventos.
  • Sobreponha decorações visuais em um UIElementarquivo .
  • Mascarar visualmente ou substituir parte ou todo um UIElementarquivo .

O Windows Presentation Foundation (WPF) fornece uma estrutura básica para adornar elementos visuais. A tabela a seguir lista os tipos primários usados ao adornar objetos e sua finalidade. Seguem-se vários exemplos de utilização:

Classe Descrição
Adorner Uma classe base abstrata da qual todas as implementações concretas de adornos herdam.
AdornerLayer Uma classe representando uma camada de renderização para os adornos de um ou mais elementos adornados.
AdornerDecorator Uma classe que habilita a associação da camada do adorno a uma coleção de elementos.

Implementando um adorno personalizado

A estrutura de adoradores fornecida pelo Windows Presentation Foundation (WPF) destina-se principalmente a dar suporte à criação de adornos personalizados. Um adorador personalizado é criado implementando uma classe que herda da classe abstrata Adorner .

Observação

O pai de um Adorner é o que renderiza o , não o AdornerLayerAdornerelemento que está sendo adornado.

O exemplo a seguir mostra uma classe que implementa um adorno simples. O adorno de exemplo simplesmente adorna os cantos de um UIElement com círculos.

// Adorners must subclass the abstract base class Adorner.
public class SimpleCircleAdorner : Adorner
{
  // Be sure to call the base class constructor.
  public SimpleCircleAdorner(UIElement adornedElement)
    : base(adornedElement)
  {
  }

  // A common way to implement an adorner's rendering behavior is to override the OnRender
  // method, which is called by the layout system as part of a rendering pass.
  protected override void OnRender(DrawingContext drawingContext)
  {
    Rect adornedElementRect = new Rect(this.AdornedElement.DesiredSize);

    // Some arbitrary drawing implements.
    SolidColorBrush renderBrush = new SolidColorBrush(Colors.Green);
    renderBrush.Opacity = 0.2;
    Pen renderPen = new Pen(new SolidColorBrush(Colors.Navy), 1.5);
    double renderRadius = 5.0;

    // Draw a circle at each corner.
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopLeft, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopRight, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomLeft, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomRight, renderRadius, renderRadius);
  }
}

Public Class SimpleCircleAdorner
    Inherits Adorner
    Sub New(ByVal adornedElement As UIElement)
        MyBase.New(adornedElement)
    End Sub

    Protected Overrides Sub OnRender(ByVal drawingContext As System.Windows.Media.DrawingContext)
        MyBase.OnRender(drawingContext)
        Dim adornedElementRect As New Rect(AdornedElement.DesiredSize)
        Dim renderBrush As New SolidColorBrush(Colors.Green)
        renderBrush.Opacity = 0.2
        Dim renderPen As New Pen(New SolidColorBrush(Colors.Navy), 1.5)
        Dim renderRadius As Double
        renderRadius = 5.0

        'Draw a circle at each corner.
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopLeft, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopRight, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomLeft, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomRight, renderRadius, renderRadius)
    End Sub
End Class

A imagem a seguir mostra o SimpleCircleAdorner aplicado a um TextBox:

Screenshot that shows an adorned text box.

Comportamento de renderização para adornos

É importante observar que adornos não incluem nenhum comportamento de renderização inerente; garantir que um adorno seja renderizado é responsabilidade do implementador do adorno. Uma maneira comum de implementar o comportamento de renderização é substituir o OnRender método e usar um ou mais DrawingContext objetos para renderizar os visuais do adorador conforme necessário (como mostrado no exemplo acima).

Observação

Qualquer elemento colocado na camada de adorno é renderizado sobre os demais estilos definidos. Em outras palavras, adornos estão sempre visualmente acima e não podem ser substituídos usando a ordem z.

Eventos e teste de clique

Os adoradores recebem eventos de entrada como qualquer outro FrameworkElement. Como um adorno sempre tem uma ordem z mais alta do que o elemento que ele adorna, o adorno recebe eventos de entrada (como Drop ou MouseMove) que podem ser destinados ao elemento adornado subjacente. Um adorno pode escutar determinados eventos de entrada e passá-los ao elemento adornado subjacente, gerando novamente o evento.

Para habilitar o teste de acerto de passagem de elementos sob um adorador, defina a propriedade de teste IsHitTestVisible de acerto como false no adorador. Para obter mais informações sobre o teste de ocorrências, consulte Teste de ocorrências na camada visual.

Adornado um único UIElement

Para ligar um adorno a um determinado UIElement, siga estes passos:

  1. Chame o método GetAdornerLayer estático para obter um AdornerLayer objeto para o UIElement a ser adornado. GetAdornerLayer sobe a árvore visual, começando pelo especificado UIElement, e retorna a primeira camada de adorno encontrada. (Se nenhuma camada de adorno for encontrada, o método retornará nulo.)

  2. Chame o método para vincular o Add adorno ao destino UIElement.

O exemplo a seguir vincula um SimpleCircleAdorner (mostrado acima) a um TextBox myTextBox nomeado:

myAdornerLayer = AdornerLayer.GetAdornerLayer(myTextBox);
myAdornerLayer.Add(new SimpleCircleAdorner(myTextBox));

myAdornerLayer = AdornerLayer.GetAdornerLayer(myTextBox)
myAdornerLayer.Add(New SimpleCircleAdorner(myTextBox))

Observação

No momento, não há suporte para o uso de XAML (Extensible Application Markup Language) para vincular um adorno a outro elemento.

Adornando os filhos de um painel

Para ligar um adorno aos filhos de um Panel, siga estes passos:

  1. Chame o método GetAdornerLayer para encontrar uma camada adornada para o static elemento cujos filhos devem ser adornados.

  2. Enumere por meio dos filhos do elemento pai e chame o Add método para vincular um adorno a cada elemento filho.

O exemplo a seguir vincula um SimpleCircleAdorner (mostrado acima) aos filhos de um StackPanel myStackPanel nomeado:

foreach (UIElement toAdorn in myStackPanel.Children)
  myAdornerLayer.Add(new SimpleCircleAdorner(toAdorn));

For Each toAdorn As UIElement In myStackPanel.Children
    myAdornerLayer.Add(New SimpleCircleAdorner(toAdorn))
Next

Confira também