Información general sobre adornos

Actualización: noviembre 2007

Las etiquetas contextuales son un tipo especial de FrameworkElement, que se utiliza para proporcionar indicaciones visuales a un usuario. Entre otros usos se pueden utilizar para agregar controladores funcionales a los elementos o proporcionar información de estado sobre un control.

Este tema contiene las secciones siguientes.

• Etiquetas contextuales
• Implementación de una etiqueta contextual personalizada
• Comportamiento de representación de las etiquetas contextuales
• Eventos y pruebas de posicionamiento
• Agregar una etiqueta contextual a un solo elemento de interfaz de usuario
• Agregar etiquetas contextuales a elementos secundarios de un panel
• Temas relacionados

Etiquetas contextuales

Un Adorner es un elemento de marco (FrameworkElement) personalizado que se enlaza a un elemento de interfaz de usuario (UIElement). Las etiquetas contextuales se representan en una capa de AdornerLayer), que es una superficie de representación que siempre se encuentra encima del elemento con etiqueta o de una colección de elementos con etiqueta. La representación de una etiqueta contextual es independiente de la representación del UIElement al que está enlazado la etiqueta contextual. Una etiqueta contextual se suele colocar con relación al elemento al que se enlaza, utilizando el origen de coordenadas 2D estándar situado en la parte superior izquierda del elemento adornado.

Algunas aplicaciones comunes de las etiquetas contextuales son:

• Agregar controladores funcionales a un UIElement, que permiten al usuario manipular el elemento de alguna manera (cambiar su tamaño o posición, girarlo, etc.).

• Proporcionar comentarios visuales para indicar diversos estados o en respuesta a distintos eventos.

• Superponer etiquetas contextuales visuales en un UIElement.

• Invalidar o enmascarar visualmente la totalidad o parte de un UIElement.

Windows Presentation Foundation (WPF) proporciona un marco de trabajo básico para etiquetar elementos visuales. En la tabla siguiente se muestra una lista de los tipos principales utilizados al etiquetar objetos y su finalidad. A continuación, se presentan varios ejemplos de uso.

Adorner	Una clase base abstracta de la que heredan todas las implementaciones de etiquetas contextuales concretas.
AdornerLayer	Una clase que representa una capa de representación para la o las etiquetas contextuales de uno o más elementos.
AdornerDecorator	Una clase que permite asociar una capa de etiquetas contextuales a una colección de elementos.

Implementación de una etiqueta contextual personalizada

El marco de trabajo de etiquetas contextuales proporcionado por Windows Presentation Foundation (WPF) está diseñado principalmente para admitir la creación de etiquetas contextuales personalizadas. Una etiqueta contextual personalizada se crea implementando una clase que hereda de la clase Adorner abstracta.

Nota

El elemento primario de un objeto Adorner es AdornerLayer, que representa el Adorner, no el elemento etiquetado.

En el ejemplo siguiente se muestra una clase que implementa una etiqueta contextual simple. La etiqueta contextual del ejemplo se limita a etiquetar las esquinas de un UIElement con círculos.

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

// 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);
  }
}

En la ilustración siguiente se muestra la etiqueta contextual SimpleCircleAdorner aplicada a un control TextBox.

Comportamiento de representación de las etiquetas contextuales

Es importante tener en cuenta que las etiquetas contextuales no incluyen ningún comportamiento de representación inherente; asegurarse de que una etiqueta contextual se representa es responsabilidad del implementador de la etiqueta contextual. Una manera común de implementar el comportamiento de representación es invalidar el método OnRenderSizeChanged y utilizar uno o más objetos DrawingContext para representar los elementos visuales de la etiqueta contextual, según sea necesario (como se muestra en el ejemplo anterior).

Nota

Todo aquello que se coloca en la capa de etiquetas contextuales se representa encima del resto de estilos que se han establecido. En otras palabras, las etiquetas contextuales siempre están visualmente encima y no pueden invalidar utilizando el orden z.

Eventos y pruebas de posicionamiento

Las etiquetas contextuales reciben los eventos de entrada exactamente igual que cualquier otro elemento FrameworkElement. Dado que una etiqueta contextual siempre tiene un orden z más alto que el elemento que adorna, la etiqueta contextual recibe los eventos de entrada (como Drop o MouseMove) que podrían estar dirigidos al elemento adornado subyacente. Una etiqueta contextual puede realizar escuchas para ciertos eventos de entrada y pasárselos al elemento etiquetado subyacente volviendo a provocar el evento.

Para habilitar las pruebas de posicionamiento indirectas de los elementos que se encuentran debajo de una etiqueta contextual, establezca la propiedad IsHitTestVisible de la etiqueta contextual en false. Para obtener más información sobre pruebas de posicionamiento, consulte

Realizar pruebas de posicionamiento en la capa visual.

Agregar una etiqueta contextual a un solo elemento de interfaz de usuario

Para enlazar una etiqueta contextual a un elemento UIElement determinado, siga estos pasos:

1. Llame al método estático GetAdornerLayer para obtener un objeto AdornerLayer del elemento UIElement que se va a etiquetar. GetAdornerLayer recorre el árbol visual en sentido ascendente, empezando por el elemento UIElement especificado, y devuelve la primera capa de etiquetas contextuales que encuentra. (Si no se encuentra ninguna capa, el método devuelve null.)

2. Llame al método Add para enlazar la etiqueta contextual al UIElement de destino.

En el ejemplo siguiente se enlaza la etiqueta contextual SimpleCircleAdorner (mostrada anteriormente) a un control TextBox denominado myTextBox.

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

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

Nota

En la actualidad, no se admite el uso de Lenguaje de marcado de aplicaciones extensible (XAML) para enlazar una etiqueta contextual a otro elemento.

Agregar etiquetas contextuales a elementos secundarios de un panel

Para enlazar una etiqueta contextual a los elementos secundarios de un control Panel, siga estos pasos:

 

1. Llame al método staticGetAdornerLayer para buscar una capa de etiquetas contextuales del elemento cuyos elementos secundarios desea etiquetar.

2. Enumere los elementos secundarios del elemento primario y llame al método Add para enlazar una etiqueta contextual a cada elemento secundario.

En el ejemplo siguiente se enlaza la etiqueta contextual SimpleCircleAdorner (mostrada anteriormente) a los elementos secundarios de un control StackPanel denominado myStackPanel.

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

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

Vea también

Conceptos

Información general sobre formas y dibujo básico en WPF

Pintar con imágenes, dibujos y elementos visuales

Información general sobre objetos Drawing

Referencia

AdornerHitTestResult

Otros recursos

Temas "Cómo..." de adornos

Ejemplos de adornos