Vue d'ensemble des ornements

Les ornements sont un type spécial de FrameworkElement, utilisés pour fournir des signaux visuels à un utilisateur. Parmi les autres utilisations, les ornements peuvent être utilisés pour ajouter des handles fonctionnels aux éléments ou fournir des informations d'état à propos d'un contrôle.

Cette rubrique comprend les sections suivantes.

• À propos des ornements
• Implémentation d'un ornement personnalisé
• Rendu du comportement pour les ornements
• Événements et test de positionnement
• Ornementer un UIElement unique
• Ornementer les enfants d'un volet
• Rubriques connexes

À propos des ornements

Un Adorner est un FrameworkElement personnalisé lié à un UIElement. Les ornements sont restitués dans un AdornerLayer, qui est une surface de rendu toujours située au dessus de l'élément ornementé ou une collection d'éléments ornementés. Le rendu d'un ornement est indépendant du rendu de l'UIElement auquel est lié l'ornement. Un ornement est positionné en général par rapport à l'élément auquel il est lié, à l'aide des coordonnées 2D standard d'origine situées au coin supérieur gauche de l'élément ornementé.

Les applications courantes pour les ornements incluent :

• L'ajout de handles fonctionnels à un UIElement qui permet à un utilisateur de manipuler l'élément d'une certaine façon (redimensionner, faire pivoter, repositionner, etc.).

• La fourniture d'une rétroaction visuelle pour indiquer différents états, ou en réponse à divers événements.

• La superposition de décorations visuelles sur un UIElement.

• La masquage visuel ou le remplacement partiel ou complet d'un UIElement.

Windows Presentation Foundation (WPF) fournit une infrastructure de base pour ornementer des éléments visuels. La table suivante répertorie les types principaux utilisés lors de l'ornementation d'objets, et leur but. Plusieurs exemples d'utilisation suivent.

Adorner	Une classe de base abstraite à partir de laquelle toutes les implémentations d'ornement concrètes héritent.
AdornerLayer	Une classe qui représente une couche de rendu pour le(s) ornements d'un ou plusieurs éléments ornementés.
AdornerDecorator	Une classe qui permet d'associer une couche d'ornement à une collection d'éléments.

Implémentation d'un ornement personnalisé

L'infrastructure des ornements fournie par Windows Presentation Foundation (WPF) est prévue à l'origine pour prendre en charge la création d'ornements personnalisés. Un ornement personnalisé est créé en implémentant une classe qui hérite de la classe abstraite Adorner.

Remarque
Le parent d'un Adorner est la AdornerLayer qui restitue l'Adorner, pas l'élément qui est ornementé.

L'exemple suivant montre une classe qui implémente un ornement simple. L'ornement d'exemple ornemente simplement les angles d'un UIElement avec des cercles.

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

L'image suivante montre le SimpleCircleAdorner appliqué à une TextBox.

Rendu du comportement pour les ornements

Il est important de noter que les ornements n'incluent aucun comportement de rendu inhérent; garantissant que le rendu d'un ornement est la responsabilité de l'implémenteur d'ornement. Un moyen courant d'implémentation du comportement de rendu est de remplacer la méthode OnRender et d'utiliser un ou plusieurs objets DrawingContext pour restituer les visuels de l'ornement en fonction des besoins (comme illustré dans l'exemple ci-dessous).

Remarque
Tout ce qui est placé dans la couche d'ornement est restitué au dessus de tous les styles que vous avez définis.En d'autres termes, les ornements sont toujours visuellement en haut et ne peuvent pas être substitués à l'aide de l'ordre de plan.

Événements et test de positionnement

Les ornements reçoivent des événements d'entrée comme n'importe quel autre FrameworkElement. Un ornement ayant toujours un ordre de plan plus élevé que l'élément qu'il ornemente, l'ornement reçoit des événements d'entrée (tel qu'un Drop ou MouseMove) qui peuvent être prévus pour l'élément ornementé sous-jacent. Un ornement peut écouter certains événements d'entrée et les passer sur l'élément ornementé sous-jacent en déclenchant à nouveau l'événement.

Pour permettre le test de positionnement direct d'éléments sous un ornement, définissez la propriété de test de positionnement IsHitTestVisible à false sur l'ornement. Pour plus d'informations sur les tests de positionnement, consultez

Test de positionnement dans la couche visuelle.

Ornementer un UIElement unique

Pour lier un ornement à un UIElement particulier, suivez ces étapes :

1. Appelez la méthode statique GetAdornerLayer pour obtenir un objet AdornerLayer pour le UIElement à orner. GetAdornerLayer parcourt l'arborescence d'éléments visuels en commençant par le UIElement spécifié et retourne la première couche d'ornement qu'il trouve. (Si aucune couche d'ornement n'est trouvée, la méthode retourne la valeur null.)

2. Appelez la méthode Add pour lier l'ornement à la cible UIElement.

L'exemple suivant lie un SimpleCircleAdorner (montré ci-dessus) à une TextBox nommée myTextBox.

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

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

Remarque
L'utilisation de Extensible Application Markup Language (XAML) pour lier un ornement à un autre élément n'est pas prise en charge actuellement.

Ornementer les enfants d'un volet

Pour lier un ornement aux enfants d'un Panel, suivez ces étapes :

 

1. Appelez la méthode staticGetAdornerLayer pour rechercher une couche d'ornement pour l'élément dont les enfants doivent être ornementés.

2. Énumérez les enfants de l'élément parent et appelez la méthode Add pour lier un ornement à chaque élément enfant.

L'exemple suivant lie un SimpleCircleAdorner (montré ci-dessus) aux enfants d'un StackPanel nommé 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));

Voir aussi

Référence

AdornerHitTestResult

Concepts

Vue d'ensemble des formes et dessins de base dans WPF

Peinture avec des objets d'image, de dessin et visuels

Vue d'ensemble des objets Drawing

Autres ressources

Rubriques "Comment" relatives aux ornements