Vue d'ensemble de la création de contrôles

La méthode la plus simple pour créer un contrôle dans WPF consiste à le dériver d'un UserControl. Lorsque vous générez un contrôle qui hérite de UserControl, vous ajoutez des composants existants au UserControl, nommez les composants et référencez les gestionnaires d'événements dans XAML (eXtensible Application Markup Language). Vous pouvez ensuite référencer les éléments nommés et définir les gestionnaires d'événements dans le code. Ce modèle de développement ressemble fortement au modèle utilisé pour le développement d'applications dans WPF.

Si la génération s'est déroulée correctement, un UserControl peut tirer parti des avantages d'un contenu riche, de styles et de déclencheurs. Toutefois, si votre contrôle hérite de UserControl, les personnes qui utilisent votre contrôle ne pourront pas utiliser un DataTemplate ou un ControlTemplate pour personnaliser son apparence. Il est nécessaire de dériver à partir de la classe Control ou d'une de ses classes dérivées (autre que UserControl) pour créer un contrôle personnalisé qui prend en charge des modèles.

Avantages de dériver de UserControl

Dériver de la classe Control est le modèle utilisé par la plupart des contrôles WPF existants. Lorsque vous créez un contrôle qui hérite de la classe Control, vous définissez son apparence à l'aide de modèles. En agissant de la sorte, vous séparez la logique opérationnelle de la représentation visuelle. Vous pouvez également garantir le découplage de l'interface utilisateur et de la logique en utilisant des commandes et des liaisons au lieu des événements et en évitant le plus possible de référencer les éléments dans le ControlTemplate.  Si l'interface utilisateur et la logique de votre contrôle sont correctement découplées, un utilisateur de votre contrôle peut redéfinir son ControlTemplate pour personnaliser son apparence. Bien que la génération d'un Control personnalisé ne soit pas aussi simple que la génération d'un UserControl, un Control personnalisé fournit plus de flexibilité.

Avantages de dériver de Control

Les contrôles qui dérivent de UserControl ou de Control reposent sur la composition d'éléments existants. Cette solution est acceptable dans de nombreux scénarios, car tout objet héritant de FrameworkElement peut appartenir à un ControlTemplate. Dans certains cas, l'apparence d'un contrôle requiert toutefois des fonctionnalités autres que celles de la composition d'éléments simples. Pour ces scénarios, baser un composant sur FrameworkElement est le bon choix.

Il existe deux méthodes standard pour générer des composants basés sur FrameworkElement : le rendu direct et la composition d'éléments personnalisés. Le rendu direct implique de substituer la méthode OnRender de FrameworkElement et de fournir des opérations DrawingContext qui définissent explicitement les visuels du composant. C'est la méthode utilisée par Image et Border. La composition d'éléments personnalisés implique l'utilisation d'objets de type Visual pour composer l'apparence du composant. Pour obtenir un exemple, consultez Utilisation d'objets DrawingVisual. Track est un exemple de contrôle dans WPF qui utilise une composition d'éléments personnalisée. Il est également possible de combiner le rendu direct et la composition d'éléments personnalisés au sein du même contrôle.

Avantages de dériver de FrameworkElement

Dans le cas d'une propriété de dépendance, il est possible d'effectuer les opérations suivantes :

• Définir la propriété dans un style.

• Lier la propriété à une source de données.

• Utiliser une ressource dynamique en tant que valeur de la propriété.

• Animer la propriété.

Si vous voulez qu'une propriété de votre contrôle prenne en charge l'une de ces fonctionnalités, vous devez l'implémenter en tant que propriété de dépendance. L'exemple suivant montre comment définir une propriété de dépendance appelée Value.

• Définissez un identificateur DependencyProperty nommé ValueProperty en tant que champ public static readonly.

• Enregistre le nom de la propriété avec le système de propriétés, en appelant DependencyProperty.Register, afin de spécifier les éléments suivants :

  • le nom de la propriété ;

  • Type de la propriété.

  • le type propriétaire de la propriété ;

  • Les métadonnées de la propriété. Les métadonnées contiennent la valeur par défaut de la propriété, un CoerceValueCallback et un PropertyChangedCallback.

• Définissez une propriété de wrapper CLR nommée Value, qui est le nom utilisé pour enregistrer la propriété de dépendance, en implémentant les accesseurs get et set de la propriété. Notez que les accesseurs get et set appellent uniquement GetValue et SetValue, respectivement. Il est conseillé de ne pas inclure de logique supplémentaire dans les accesseurs de propriétés de dépendance car les clients et WPF peuvent ignorer les accesseurs et appeler directement GetValue et SetValue. Par exemple, lorsqu'une propriété est liée à une source de données, l'accesseur set de la propriété n'est pas appelé. Au lieu d'ajouter une logique supplémentaire aux accesseurs get et set, utilisez les délégués ValidateValueCallback, CoerceValueCallback et PropertyChangedCallback pour répondre ou vérifier la valeur lorsque celle-ci change. Pour plus d'informations sur ces rappels, consultez Validation et rappels de propriétés de dépendance.

• Définissez une méthode pour le CoerceValueCallback, nommée CoerceValue. CoerceValue garantit que Value est supérieur ou égal à MinValue et inférieur ou égal à MaxValue.

• Définissez une méthode pour le PropertyChangedCallback, nommée OnValueChanged. OnValueChanged crée un objet RoutedPropertyChangedEventArgs<T> et se prépare à déclencher l'événement routé ValueChanged. Les événements routés sont examinés dans la section suivante.

/// <summary>
/// Identifies the Value dependency property.
/// </summary>
public static readonly DependencyProperty ValueProperty =
    DependencyProperty.Register(
        "Value", typeof(decimal), typeof(NumericUpDown),
        new FrameworkPropertyMetadata(MinValue, new PropertyChangedCallback(OnValueChanged),
                                      new CoerceValueCallback(CoerceValue)));

/// <summary>
/// Gets or sets the value assigned to the control.
/// </summary>
public decimal Value
{          
    get { return (decimal)GetValue(ValueProperty); }
    set { SetValue(ValueProperty, value); }
}

private static object CoerceValue(DependencyObject element, object value)
{
    decimal newValue = (decimal)value;
    NumericUpDown control = (NumericUpDown)element;

    newValue = Math.Max(MinValue, Math.Min(MaxValue, newValue));

    return newValue;
}

private static void OnValueChanged(DependencyObject obj, DependencyPropertyChangedEventArgs args)
{
    NumericUpDown control = (NumericUpDown)obj;			

    RoutedPropertyChangedEventArgs<decimal> e = new RoutedPropertyChangedEventArgs<decimal>(
        (decimal)args.OldValue, (decimal)args.NewValue, ValueChangedEvent);
    control.OnValueChanged(e);
}

Pour plus d'informations, consultez Propriétés de dépendance personnalisées.

De même que les propriétés de dépendance étendent la notion de propriétés CLR avec des fonctionnalités supplémentaires, les événements routés étendent la notion d'événements CLR standard. Lorsque vous créez un contrôle WPF, il est également conseillé d'implémenter votre événement sous forme d'événement routé car un tel événement prend en charge le comportement suivant :

• Les événements peuvent être gérés sur le parent de plusieurs contrôles. Si un événement est un événement de propagation, un parent unique de l'arborescence d'éléments peut s'abonner à l'événement. Les auteurs d'applications peuvent ensuite utiliser un gestionnaire unique pour répondre à l'événement de plusieurs contrôles. Par exemple, si votre contrôle fait partie de chaque élément d'une ListBox (parce qu'il est inclus dans un DataTemplate), le développeur d'applications peut définir le gestionnaire de l'événement de votre contrôle sur la ListBox. Dans ce cas, chaque fois que l'événement se produit sur un des contrôles, le gestionnaire d'événements est appelé.

• Des événements routés peuvent être utilisés dans un EventSetter, ce qui permet aux développeurs d'applications de spécifier le gestionnaire d'un événement dans un style.

• Il est possible d'utiliser des événements routés dans un EventTrigger, ce qui est utile pour animer des propriétés à l'aide de XAML. Pour plus d'informations, consultez Vue d'ensemble de l'animation.

L'exemple suivant montre comment définir un événement routé :

• Définissez un identificateur RoutedEvent nommé ValueChangedEvent en tant que champ public static readonly.

• Enregistrez l'événement routé en appelant la méthode EventManager.RegisterRoutedEvent. L'exemple spécifie les informations suivantes lorsqu'il appelle RegisterRoutedEvent :

  • Le nom de l'événement est ValueChanged.

  • La stratégie de routage est Bubble, ce qui signifie qu'un gestionnaire d'événements sur la source (l'objet qui déclenche l'événement) est appelé en premier, puis que les gestionnaires d'événements sur les éléments parents de la source sont appelés dans l'ordre, en commençant par le gestionnaire d'événements sur l'élément parent le plus proche.

  • Le type du gestionnaire d'événements est RoutedPropertyChangedEventHandler<T>, qui est construit avec un type Decimal.

  • Le type propriétaire de l'événement est NumericUpDown.

• Déclarez un événement public nommé ValueChanged et incluez des déclarations d'accesseurs d'événement. L'exemple appelle AddHandler dans la déclaration d'accesseur add et RemoveHandler dans la déclaration d'accesseur remove afin d'utiliser les services d'événement WPF.

• Créez une méthode virtuelle protégée nommée OnValueChanged, qui déclenche l'événement ValueChanged.

/// <summary>
/// Identifies the ValueChanged routed event.
/// </summary>
public static readonly RoutedEvent ValueChangedEvent = EventManager.RegisterRoutedEvent(
    "ValueChanged", RoutingStrategy.Bubble, 
    typeof(RoutedPropertyChangedEventHandler<decimal>), typeof(NumericUpDown));

/// <summary>
/// Occurs when the Value property changes.
/// </summary>
public event RoutedPropertyChangedEventHandler<decimal> ValueChanged
{
    add { AddHandler(ValueChangedEvent, value); }
    remove { RemoveHandler(ValueChangedEvent, value); }
}

/// <summary>
/// Raises the ValueChanged event.
/// </summary>
/// <param name="args">Arguments associated with the ValueChanged event.</param>
protected virtual void OnValueChanged(RoutedPropertyChangedEventArgs<decimal> args)
{
    RaiseEvent(args);
}

Pour plus d'informations, consultez Vue d'ensemble des événements routés et Comment : créer un événement routé personnalisé.

Pour découpler l'interface utilisateur de votre contrôle de sa logique, pensez à utiliser la liaison de données. C'est particulièrement important si vous définissez l'apparence de votre contrôle à l'aide d'un ControlTemplate. L'utilisation de la liaison de données permet d'éviter de référencer des parties spécifiques de l'interface utilisateur au départ du code. Il est préférable d'éviter de référencer des éléments qui se trouvent dans le ControlTemplate parce que lorsque le code référence des éléments présents dans le ControlTemplate et que le ControlTemplate est modifié, l'élément référencé doit être inclus dans le nouveau ControlTemplate.

L'exemple suivant met à jour le TextBlock du contrôle NumericUpDown, en lui assignant un nom et référençant la zone de texte dans le code par son nom.

<Border BorderThickness="1" BorderBrush="Gray" Margin="2" 
        Grid.RowSpan="2" VerticalAlignment="Center" HorizontalAlignment="Stretch">
  <TextBlock Name="valueText" Width="60" TextAlignment="Right" Padding="5"/>
</Border>

		Private Sub UpdateTextBlock()
			valueText.Text = Value.ToString()
		End Sub

private void UpdateTextBlock()
{
    valueText.Text = Value.ToString();
}

L'exemple suivant utilise la liaison pour faire la même chose.

<Border BorderThickness="1" BorderBrush="Gray" Margin="2" 
        Grid.RowSpan="2" VerticalAlignment="Center" HorizontalAlignment="Stretch">

    <!--Bind the TextBlock to the Value property-->
    <TextBlock 
        Width="60" TextAlignment="Right" Padding="5"
        Text="{Binding RelativeSource={RelativeSource FindAncestor, 
                       AncestorType={x:Type local:NumericUpDown}}, 
                       Path=Value}"/>

</Border>

Pour plus d'informations sur la liaison de données, consultez Vue d'ensemble de la liaison de données.

Pour obtenir de l'aide pour les contrôles WPF personnalisés dans Concepteur WPF pour Visual Studio (par exemple, pour modifier des propriétés avec la fenêtre Propriétés), suivez les indications ci-après. Pour plus d'informations sur le développement pour Concepteur WPF, consultez Concepteur WPF.

Propriétés de dépendance

Propriétés jointes

Vous pouvez inclure votre contrôle dans le même assembly que votre application, ou l'intégrer dans un assembly séparé qui peut être utilisé dans plusieurs applications. Pour la plupart, les informations abordées dans cette rubrique sont valables, quelle que soit la méthode que vous utilisez. Toutefois, il existe une différence notable. Lorsque vous placez un contrôle dans le même assembly qu'une application, vous êtes libre d'ajouter des ressources globales au fichier App.xaml. Cependant, un assembly qui ne contient que des contrôles n'est associé à aucun objet Application et aucun fichier App.xaml n'est donc disponible.

Lorsqu'une application recherche une ressource, elle examine trois niveaux dans l'ordre suivant :

1. Niveau de l'élément.

   Le système commence par l'élément qui référence la ressource, puis il passe en revue les ressources du parent logique, et ainsi de suite, jusqu'à atteindre l'élément racine ;

2. Niveau de l'application.

   Ressources définies par l'objet Application ;

3. Niveau du thème.

   Les dictionnaires au niveau du thème sont enregistrés dans un sous-dossier nommé Themes. Les fichiers contenus dans ce dossier correspondent aux thèmes. Par exemple, vous pouvez avoir Aero.NormalColor.xaml, Luna.NormalColor.xaml, Royale.NormalColor.xaml, etc. Vous pouvez également avoir un fichier nommé generic.xaml. Lorsque le système recherche une ressource au niveau des thèmes, il la cherche en premier lieu dans le fichier spécifique au thème puis dans generic.xaml.

Lorsque votre contrôle se trouve dans un assembly distinct de l'application, vous devez placer vos ressources globales au niveau de l'élément ou du thème. Les deux méthodes ont leurs avantages.

Définition de ressources au niveau de l'élément

<ResourceDictionary 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <LinearGradientBrush 
    x:Key="myBrush"  
    StartPoint="0,0" EndPoint="1,1">
    <GradientStop Color="Red" Offset="0.25" />
    <GradientStop Color="Blue" Offset="0.75" />
  </LinearGradientBrush>

</ResourceDictionary>

<UserControl.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="Dictionary1.xaml"/>
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</UserControl.Resources>

internal static class SharedDictionaryManager
{
    internal static ResourceDictionary SharedDictionary
    {
        get
        {
            if (_sharedDictionary == null)
            {
                System.Uri resourceLocater =
                    new System.Uri("/ElementResourcesCustomControlLibrary;component/Dictionary1.xaml", 
                                    System.UriKind.Relative);

                _sharedDictionary = 
                    (ResourceDictionary)Application.LoadComponent(resourceLocater);
            }

            return _sharedDictionary;
        }
    }

    private static ResourceDictionary _sharedDictionary;
}

public NumericUpDown()
{
    this.Resources.MergedDictionaries.Add(SharedDictionaryManager.SharedDictionary);
    InitializeComponent();

}

Définition de ressources au niveau du thème

static NumericUpDown()
{
    DefaultStyleKeyProperty.OverrideMetadata(typeof(NumericUpDown),
               new FrameworkPropertyMetadata(typeof(NumericUpDown)));
}

<LinearGradientBrush 
     x:Key="{ComponentResourceKey TypeInTargetAssembly={x:Type local:Painter}, 
                                  ResourceId=MyEllipseBrush}"  
                                  StartPoint="0,0" EndPoint="1,0">
    <GradientStop Color="Blue" Offset="0" />
    <GradientStop Color="Red" Offset="0.5" />
    <GradientStop Color="Green" Offset="1"/>
</LinearGradientBrush>

<RepeatButton 
    Grid.Column="1" Grid.Row="0"
    Background="{StaticResource {ComponentResourceKey 
                        TypeInTargetAssembly={x:Type local:NumericUpDown}, 
                        ResourceId=ButtonBrush}}">
    Up
</RepeatButton>
<RepeatButton 
    Grid.Column="1" Grid.Row="1"
    Background="{StaticResource {ComponentResourceKey 
                    TypeInTargetAssembly={x:Type local:NumericUpDown}, 
                    ResourceId=ButtonBrush}}">
    Down
 </RepeatButton>

[assembly: ThemeInfo(ResourceDictionaryLocation.SourceAssembly, 
           ResourceDictionaryLocation.SourceAssembly)]