Visão geral dos adornos

Adornos são uma categoria especial de FrameworkElement, usada para fornecer pistas visuais a um usuário. Entre outros usos, adornadores podem ser usados para adicionar manipuladores funcionais a um elemento ou fornecer informações de estado sobre um componente.

Sobre adornos

Um Adorner é um FrameworkElement personalizado associado a um UIElement. Adornos são renderizados em uma AdornerLayer, que é uma superfície de renderização que está sempre sobre o elemento adornado ou uma coleção de elementos adornados. A renderização de um adorno é independente da renderização do UIElement ao qual o adorno está ligado. Normalmente, um adorno é posicionado em relação ao elemento ao qual está associado, usando a origem das coordenadas 2D padrão localizada no canto superior esquerdo do elemento adornado.

As aplicações comuns para adornos incluem:

• Adicionando alças funcionais a um UIElement que permite ao usuário manipular o elemento de alguma forma (redimensionar, girar, reposicionar etc.).
• Forneça comentários visuais para indicar vários estados ou em resposta a vários eventos.
• Sobrepor decorações visuais em um UIElement.
• Mascarar visualmente ou substituir parte ou todo de um UIElement.

O WPF (Windows Presentation Foundation) 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. Vários exemplos de uso seguem:

Implementando um adorno personalizado

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

O exemplo a seguir mostra uma classe que implementa um decorador 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:

Comportamento de renderização para decoradores

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

Eventos e teste de clique

Os adornos recebem eventos de entrada como qualquer outro FrameworkElement. Como um adorno sempre tem uma ordem z maior do que o elemento que adorna, o adorno recebe eventos de entrada (como Drop ou MouseMove) que podem ser destinados ao elemento adornado subjacente. Um decorador pode escutar certos eventos de entrada e retransmiti-los para o elemento decorado subjacente.

Para habilitar o teste de clique de passagem de elementos em um adorno, defina a propriedade de teste IsHitTestVisible de clique como false no adorno. Para obter mais informações sobre o teste de clique, consulte Teste de Clique na Camada Visual.

Adornando um único UIElement

Para associar um adorno a um UIElementespecífico, siga estas etapas:

1. Chame o método GetAdornerLayer estático para obter um AdornerLayer objeto para que ele UIElement seja adornado. GetAdornerLayer percorre a árvore visual, começando na camada especificada UIElemente retorna a primeira camada de adorno encontrada. (Se nenhuma camada de adorno for encontrada, o método retornará nulo.)

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

O exemplo a seguir associa um SimpleCircleAdorner (mostrado acima) a um TextBoxnome myTextBox:

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

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

Embelezando os elementos de um painel

Para associar um adorno aos filhos de um Panel, siga estas etapas:

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

2. Enumerar por meio dos filhos do elemento pai e chamar o método Add para associar um adorno a cada elemento filho.

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

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

Consulte também

• AdornerHitTestResult
• Visão geral de formas e desenho básico no WPF
• Pintura com Imagens, Desenhos e Elementos Visuais
• Visão geral dos objetos de desenho
• Tópicos "Como Fazer"