Vue d’ensemble des ornements

Les ornements sont un type spécial de FrameworkElement, utilisé pour fournir des repères visuels à un utilisateur. Entre autres utilisations, les Adorners peuvent être utilisés pour ajouter des poignées fonctionnelles à des éléments ou de fournir des informations d’état sur un contrôle.

À propos des décorateurs

Un Adorner est un FrameworkElement personnalisé lié à un UIElement. Les ornements sont rendus dans une AdornerLayersurface de rendu qui se trouve toujours en haut de l’élément orné ou d’une collection d’éléments ornés. Le rendu d’un ornement est indépendant du rendu de l’élément UIElement auquel l’ornement est lié. Un ornement est généralement positionné par rapport à l’élément auquel il est lié, à l’aide de l’origine de coordonnées 2D standard située en haut à gauche de l’élément orné.

Les applications courantes pour les ornements sont les suivantes :

• Ajout de poignées fonctionnelles à un UIElement qui permettent à un utilisateur de manipuler l’élément d’une certaine manière (redimensionner, faire pivoter, repositionner, etc.).
• Fournissez des commentaires visuels pour indiquer différents états ou en réponse à différents événements.
• Superposer les décorations visuelles sur un UIElement.
• Masquez visuellement ou remplacez une partie ou l’ensemble d’un UIElement.

Windows Presentation Foundation (WPF) fournit une infrastructure de base pour orner des éléments visuels. Le tableau suivant répertorie les types principaux utilisés lors de l’ornement des objets et leur objectif. Plusieurs exemples d’utilisation suivent :

classe	Descriptif
Adorner	Classe de base abstraite à partir de laquelle toutes les implémentations d’ornements concrètes héritent.
AdornerLayer	Classe représentant une couche de rendu pour le ou les ornements d’un ou plusieurs éléments ornés.
AdornerDecorator	Classe qui permet à une couche d’ornement d’être associée à une collection d’éléments.

Implémentation d'un décorateur personnalisé

L’infrastructure d’ornements fournie par Windows Presentation Foundation (WPF) est destinée principalement à 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 celui AdornerLayer qui restitue le Adorner, et non l’élément orné.

L’exemple suivant montre une classe qui implémente un ornement simple. L'exemple d'adornement orne simplement les coins d'un UIElement avec des cercles.

// 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

L’image suivante montre le SimpleCircleAdorner appliqué à un TextBox:

Comportement d'affichage pour les décorations

Il est important de noter que les ornements n’incluent pas de comportement de rendu inhérent ; s’assurer qu’un ornement rend est la responsabilité de l’implémenteur d’ornement. Un moyen courant d’implémenter le comportement de rendu consiste à remplacer la OnRender méthode et à utiliser un ou plusieurs DrawingContext objets pour afficher les visuels de l’ornement selon les besoins (comme illustré dans l’exemple ci-dessus).

Remarque

Tout ce qui est placé dans la couche d'adorne est rendu au-dessus de tous les autres styles que vous avez définis. En d'autres termes, les adornateurs sont toujours visuellement au premier plan et ne peuvent pas être surpassés, même avec l'utilisation de l'ordre z.

Événements et tests de collision

Les adorneurs reçoivent des événements d'entrée comme tout autre FrameworkElement. Étant donné qu’un ornement a toujours un ordre de z supérieur à l’élément qu’il orne, l’ornement reçoit des événements d’entrée (tels que Drop ou MouseMove) qui peuvent être destinés à l’élément ornementé sous-jacent. Un décorateur peut écouter certains événements d'entrée et les transmettre à l'élément décoré sous-jacent en renvoyant l'événement.

Pour activer le test de pointage direct des éléments sous un ornement, définissez la propriété de test de pointage sur IsHitTestVisible sur l’ornement. Pour plus d’informations sur les tests de détection, consultez Test de détection dans la couche visuelle.

Decoration d’un seul élément d’interface utilisateur

Pour lier un ornement à un particulier UIElement, procédez comme suit :

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

2. Appelez la méthode Add pour lier l'élément de décoration à la cible UIElement.

L’exemple suivant lie un SimpleCircleAdorner (illustré ci-dessus) à un TextBoxmyTextBox nommé :

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

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

Remarque

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

Ornement des enfants d’un panneau

Pour lier un ornement aux enfants d’un Panel, procédez comme suit :

1. Appelez la static méthode GetAdornerLayer pour rechercher une couche d’ornement pour l’élément dont les enfants doivent être orné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 (illustré ci-dessus) aux enfants d'un StackPanel nommé 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

Voir aussi

• AdornerHitTestResult
• Vue d’ensemble des formes et dessins de base dans WPF
• peinture avec des images, des dessins et des visuels
• Vue d’ensemble des objets de dessin
• Sujets de type "comment faire"