Partilhar via

Visão geral dos adornos

  • Artigo

Os adornos são um tipo especial de FrameworkElement, usados para fornecer pistas visuais para um utilizador. Entre outros usos, os "Adorners" podem ser utilizados para adicionar ferramentas funcionais aos elementos ou fornecer informações de estado sobre um controlo.

Sobre os adornos

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

As aplicações comuns para decoradores incluem:

  • Adicionar identificadores funcionais a um UIElement que permitem que um usuário manipule o elemento de alguma forma (redimensionar, girar, reposicionar, etc.).
  • Fornecer feedback visual para indicar vários estados ou em resposta a vários eventos.
  • Sobreponha decorações visuais num UIElement.
  • Oculte visualmente ou substitua parte ou a totalidade de um/uma UIElement.

Windows Presentation Foundation (WPF) fornece uma estrutura básica para adornar elementos visuais. A tabela a seguir lista os principais tipos 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 adorners herdam.
AdornerLayer Uma classe que representa uma camada de renderização para o(s) adorno(s) de um ou mais elementos adornados.
AdornerDecorator Uma classe que permite que uma camada de decoração seja associada a uma coleção de elementos.

Implementando um adorno personalizado

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

Observação

O pai de um Adorner é o AdornerLayer que renderiza o Adorner, não o elemento que está a ser adornado.

O exemplo a seguir mostra uma classe que implementa um adorno simples. O exemplo de adorno 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:

Captura de tela que mostra uma caixa de texto adornada.

Comportamento de renderização para adornadores

É importante notar que os adornos não incluem qualquer comportamento de renderização inerente; garantir que um adorno renderiza é responsabilidade do implementador de 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 elementos visuais do adorno conforme necessário (como mostrado no exemplo acima).

Observação

Qualquer coisa colocada na camada de adorno é renderizada em cima do resto de todos os estilos que você definiu. Em outras palavras, os adornadores estão sempre visualmente no topo e não podem ser sobrepostos usando z-order.

Eventos e deteção de colisões

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 passá-los para o elemento adornado subjacente, reemitindo o evento.

Para habilitar o teste de acerto de passagem de elementos sob um adorner, defina a propriedade IsHitTestVisible teste de acerto para falso no adorner. Para obter mais informações sobre teste de colisão, consulte Teste de colisão na camada visual.

Adornando um UIElement

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

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

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

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

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 adorner a outro elemento.

Adornando as crianças de um painel

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

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

  2. Enumere os filhos do elemento pai e chame o método Add para associar um adorno a cada elemento filho.

O exemplo a seguir vincula um SimpleCircleAdorner (mostrado acima) aos filhos de um StackPanel chamado 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

Ver também