Partager via

Vue d’ensemble des ornements

  • Article

Les ornements sont un type spécial de FrameworkElement, utilisé pour fournir des repères visuels à un utilisateur. Les ornements permettent notamment d’ajouter des descripteurs fonctionnels à des éléments ou de fournir des informations d’état sur un contrôle.

À propos des ornements

Un Adorner est un personnalisé FrameworkElement 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 du UIElement ornement 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é.

Parmi les applications courantes des ornements, citons les suivantes :

  • Ajout de handles fonctionnels à un utilisateur qui permet à un utilisateur de manipuler l’élément d’une UIElement certaine manière (redimensionner, faire pivoter, repositionner, etc.).
  • Retour visuel pour indiquer différents états, ou en réponse à différents événements
  • Superposition de 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 principaux types utilisés pour orner des objets et leur but. Plusieurs exemples d’utilisation suivent :

Classe Description
Adorner Classe de base abstraite à partir de laquelle toutes les implémentations d’ornement concrètes sont héritées.
AdornerLayer Classe représentant une couche de rendu pour le ou les ornements d’un ou plusieurs éléments ornés.
AdornerDecorator Classe permettant d’associer une couche d’ornement à une collection d’éléments.

Implémentation d’un ornement 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’ornement orne simplement les coins d’un UIElement cercle.

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

Screenshot that shows an adorned text box.

Comportement de rendu des ornements

Il est important de noter que les ornements n’incluent aucun comportement de rendu inhérent ; il appartient donc à l’implémenteur d’un ornement de vérifier son rendu. 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 que vous placez dans la couche d’ornement s’affiche 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. É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 ornement peut écouter certains événements d’entrée et les passer à l’élément orné sous-jacent en déclenchant à nouveau l’événement.

Pour activer le test d’accès directe des éléments sous un ornement, définissez la propriété de test IsHitTestVisible de positionnement sur false sur l’ornement. Pour plus d’informations sur les tests de positionnement, consultez Test d’accès dans la couche visuelle.

Ornementation d’un UIElement unique

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

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

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

L’exemple suivant lie un SimpleCircleAdorner (illustré ci-dessus) à un TextBox myTextBox 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.

Ornementation 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 Add méthode pour lier un ornement à chaque élément enfant.

L’exemple suivant lie un SimpleCircleAdorner (illustré ci-dessus) aux enfants d’un StackPanel myStackPanel nommé :

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