Procedura dettagliata: creazione di uno strumento decorativo visuale in fase di progettazione

In questa procedura dettagliata viene illustrato come creare uno strumento decorativo Design-Time per un controllo personalizzato WPF (Windows Presentation Foundation). Questo strumento decorativo può essere utilizzato in WPF Designer per Visual Studio per impostare il valore della proprietà Opacity su un controllo pulsante personalizzato. Per questa procedura dettagliata, il controllo è un semplice pulsante e lo strumento decorativo visuale è un dispositivo di scorrimento che consente di modificare l'opacità del pulsante. Per un elenco di codice completo, vedere l'esempio di strumento decorativo visuale del dispositivo di scorrimento per la regolazione dell'opacità nel sito Esempi di estensibilità di WPF Designer.

Questa procedura dettagliata prevede l'esecuzione delle attività seguenti:

  • Creare un progetto di libreria di controlli personalizzati WPF.

  • Creare un assembly distinto per i metadati Design-Time.

  • Implementare il provider di strumenti decorativi visuali.

  • Verificare il controllo in fase di progettazione.

Al termine, si sarà in grado di creare un provider di strumenti decorativi visuali per un controllo personalizzato.

Nota

È possibile che le finestre di dialogo e i comandi di menu visualizzati siano diversi da quelli descritti nella Guida a seconda delle impostazioni attive o dell'edizione del programma. Per modificare le impostazioni, scegliere Importa/Esporta impostazioni dal menu Strumenti. Per ulteriori informazioni, vedere Gestione delle impostazioni.

Prerequisiti

Per completare la procedura dettagliata, è necessario disporre dei componenti seguenti:

  • Visual Studio 2010.

Creazione del controllo personalizzato

Il primo passaggio consiste nella creazione del progetto per il controllo personalizzato. Il controllo è un semplice pulsante con una piccola quantità di codice Design-Time che utilizza il metodo GetIsInDesignMode per implementare un comportamento in fase di progettazione.

Per creare il controllo personalizzato

  1. In Visual Basic o Visual C# creare un nuovo progetto di libreria di controlli personalizzati WPF denominato CustomControlLibrary.

    Il codice per CustomControl1 verrà aperto nell'editor di codice.

  2. In Esplora soluzioni modificare il nome del file di codice in ButtonWithDesignTime.cs o ButtonWithDesignTime.vb. Se viene visualizzata una finestra di messaggio in cui si richiede se eseguire un'operazione di ridenominazione per tutti i riferimenti del progetto, fare clic su .

  3. Aprire ButtonWithDesignTime.cs o ButtonWithDesignTime.vb nell'editor di codice.

  4. Sostituire il codice generato automaticamente con il codice seguente. Il controllo personalizzato ButtonWithDesignTime eredita da Button e visualizza il testo "Design mode active" quando il pulsante viene visualizzato nella finestra di progettazione. Il controllo di GetIsInDesignMode e il seguente codice Design-Time sono facoltativi e sono illustrati solo per scopi dimostrativi.

    Imports System
    Imports System.Collections.Generic
    Imports System.Text
    Imports System.Windows.Controls
    Imports System.Windows.Media
    Imports System.ComponentModel
    
    Public Class ButtonWithDesignTime
        Inherits Button
    
        Public Sub New()
            ' The GetIsInDesignMode check and the following design-time 
            ' code are optional and shown only for demonstration.
            If DesignerProperties.GetIsInDesignMode(Me) Then
                Content = "Design mode active"
            End If
    
        End Sub
    End Class
    
    using System;
    using System.Collections.Generic;
    using System.Text;
    using System.Windows.Controls;
    using System.Windows.Media;
    using System.ComponentModel;
    
    namespace CustomControlLibrary
    {
        public class ButtonWithDesignTime : Button
        {
            public ButtonWithDesignTime()
            {
                // The GetIsInDesignMode check and the following design-time 
                // code are optional and shown only for demonstration.
                if (DesignerProperties.GetIsInDesignMode(this))
                {
                    Content = "Design mode active";
                }
            }
        }
    }
    
  5. Impostare il percorso di output del progetto su "bin\".

  6. Compilare la soluzione.

Creazione dell'assembly di metadati Design-Time

Il codice Design-Time viene distribuito in speciali assembly di metadati. Per questa procedura dettagliata, lo strumento decorativo visuale personalizzato è supportato solo da Visual Studio ed è distribuito in un assembly denominato CustomControlLibrary.VisualStudio.Design. Per ulteriori informazioni, vedere Aggiunta di metadati della fase di progettazione.

Per creare l'assembly di metadati Design-Time

  1. In Visual Basic o Visual C# aggiungere un nuovo progetto Libreria di classi denominato CustomControlLibrary.VisualStudio.Design alla soluzione.

  2. Impostare il percorso di output del progetto su ".. \CustomControlLibrary\bin\". In questo modo l'assembly del controllo e l'assembly dei metadati verranno mantenuti nella stessa cartella, consentendo l'individuazione di metadati per le finestre di progettazione.

  3. Aggiungere riferimenti agli assembly WPF riportati di seguito.

    • PresentationCore

    • PresentationFramework

    • System.Xaml

    • WindowsBase

  4. Aggiungere riferimenti agli assembly WPF Designer riportati di seguito.

    • Microsoft.Windows.Design.Extensibility

    • Microsoft.Windows.Design.Interaction

  5. Aggiungere un riferimento al progetto CustomControlLibrary.

  6. In Esplora soluzioni modificare il nome del file di codice Class1 in Metadata.cs o Metadata.vb.

  7. Sostituire il codice generato automaticamente con il codice seguente. Con questo codice viene creato un oggetto AttributeTable che connette l'implementazione in fase di progettazione personalizzata alla classe ButtonWithDesignTime.

    Imports System
    Imports System.Collections.Generic
    Imports System.Text
    Imports System.ComponentModel
    Imports System.Windows.Media
    Imports System.Windows.Controls
    Imports System.Windows
    Imports CustomControlLibrary
    Imports Microsoft.Windows.Design.Features
    Imports Microsoft.Windows.Design.Metadata
    
    ' The ProvideMetadata assembly-level attribute indicates to designers
    ' that this assembly contains a class that provides an attribute table. 
    <Assembly: ProvideMetadata(GetType(CustomControlLibrary.VisualStudio.Design.Metadata))> 
    
    Namespace CustomControlLibrary.VisualStudio.Design
    
        ' Container for any general design-time metadata to initialize.
        ' Designers look for a type in the design-time assembly that 
        ' implements IProvideAttributeTable. If found, designers instantiate
        ' this class and access its AttributeTable property automatically.
        Friend Class Metadata
            Implements IProvideAttributeTable
    
            ' Accessed by the designer to register any design-time metadata.
            Public ReadOnly Property AttributeTable() As AttributeTable _
                Implements IProvideAttributeTable.AttributeTable
                Get
                    Dim builder As New AttributeTableBuilder()
    
                    ' Add the adorner provider to the design-time metadata.
                    builder.AddCustomAttributes(GetType(ButtonWithDesignTime), _
                                                New FeatureAttribute(GetType(OpacitySliderAdornerProvider)))
    
                    Return builder.CreateTable()
                End Get
            End Property
    
    
        End Class
    
    End Namespace
    
    using System;
    using System.Collections.Generic;
    using System.Text;
    using System.ComponentModel;
    using System.Windows.Media;
    using System.Windows.Controls;
    using System.Windows;
    
    using CustomControlLibrary;
    using Microsoft.Windows.Design.Features;
    using Microsoft.Windows.Design.Metadata;
    
    // The ProvideMetadata assembly-level attribute indicates to designers
    // that this assembly contains a class that provides an attribute table. 
    [assembly: ProvideMetadata(typeof(CustomControlLibrary.VisualStudio.Design.Metadata))]
    namespace CustomControlLibrary.VisualStudio.Design
    {
        // Container for any general design-time metadata to initialize.
        // Designers look for a type in the design-time assembly that 
        // implements IProvideAttributeTable. If found, designers instantiate 
        // this class and access its AttributeTable property automatically.
        internal class Metadata : IProvideAttributeTable
        {
            // Accessed by the designer to register any design-time metadata.
            public AttributeTable AttributeTable
            {
                get 
                {
                    AttributeTableBuilder builder = new AttributeTableBuilder();
    
                    // Add the adorner provider to the design-time metadata.
                    builder.AddCustomAttributes(
                        typeof(ButtonWithDesignTime),
                        new FeatureAttribute(typeof(OpacitySliderAdornerProvider)));
    
                    return builder.CreateTable();
                }
            }
        }
    }
    
  8. Salvare la soluzione.

Implementazione del provider di strumenti decorativi visuali

Il provider di strumenti decorativi visuali viene implementato in un tipo denominato OpacitySliderAdornerProvider. Questo strumento decorativo visuale consente all'utente di impostare in fase di progettazione la proprietà Opacity del controllo.

Per implementare il provider di strumenti decorativi visuali

  1. Aggiungere una nuova classe denominata OpacitySliderAdornerProvider al progetto CustomControlLibrary.VisualStudio.Design.

  2. Nell'editor del codice per OpacitySliderAdornerProvider sostituire il codice generato automaticamente con il codice seguente. Questo codice implementa un PrimarySelectionAdornerProvider che fornisce uno strumento decorativo visuale basato su un controllo Slider.

    Imports System
    Imports System.Collections.Generic
    Imports System.Text
    Imports System.Windows.Input
    Imports System.Windows
    Imports System.Windows.Automation
    Imports System.Windows.Controls
    Imports System.Windows.Media
    Imports System.Windows.Shapes
    Imports Microsoft.Windows.Design.Interaction
    Imports Microsoft.Windows.Design.Model
    
    Namespace CustomControlLibrary.VisualStudio.Design
    
        ' The following class implements an adorner provider for the 
        ' adorned control. The adorner is a slider control, which 
        ' changes the Background opacity of the adorned control.
        Class OpacitySliderAdornerProvider
            Inherits PrimarySelectionAdornerProvider
            Private adornedControlModel As ModelItem
            Private batchedChange As ModelEditingScope
            Private opacitySlider As Slider
            Private opacitySliderAdornerPanel As AdornerPanel
    
            Public Sub New()
                opacitySlider = New Slider()
            End Sub
    
            ' The following method is called when the adorner is activated.
            ' It creates the adorner control, sets up the adorner panel,
            ' and attaches a ModelItem to the adorned control.
            Protected Overrides Sub Activate(ByVal item As ModelItem)
    
                ' Save the ModelItem and hook into when it changes.
                ' This enables updating the slider position when 
                ' a new Background value is set.
                adornedControlModel = item
                AddHandler adornedControlModel.PropertyChanged, AddressOf AdornedControlModel_PropertyChanged
    
                ' Setup the slider's min and max values.
                opacitySlider.Minimum = 0
                opacitySlider.Maximum = 1
    
                ' Setup the adorner panel.
                ' All adorners are placed in an AdornerPanel
                ' for sizing and layout support.
                Dim myPanel = Me.Panel
    
                ' The slider extends the full width of the control it adorns.
                AdornerPanel.SetAdornerHorizontalAlignment( _
                    opacitySlider, _
                    AdornerHorizontalAlignment.Stretch)
    
                ' Position the adorner above the control it adorns.
                AdornerPanel.SetAdornerVerticalAlignment( _
                    opacitySlider, _
                    AdornerVerticalAlignment.OutsideTop)
    
                ' Position the adorner 5 pixels above the control. 
                AdornerPanel.SetAdornerMargin( _
                    opacitySlider, _
                    New Thickness(0, 0, 0, 5))
    
                ' Initialize the slider when it is loaded.
                AddHandler opacitySlider.Loaded, AddressOf slider_Loaded
    
                ' Handle the value changes of the slider control.
                AddHandler opacitySlider.ValueChanged, AddressOf slider_ValueChanged
    
                AddHandler opacitySlider.PreviewMouseLeftButtonUp, _
                    AddressOf slider_MouseLeftButtonUp
    
                AddHandler opacitySlider.PreviewMouseLeftButtonDown, _
                    AddressOf slider_MouseLeftButtonDown
    
                MyBase.Activate(item)
    
            End Sub
    
            ' The Panel utility property demand-creates the 
            ' adorner panel and adds it to the provider's 
            ' Adorners collection.
            Public ReadOnly Property Panel() As AdornerPanel
                Get
                    If Me.opacitySliderAdornerPanel Is Nothing Then
                        Me.opacitySliderAdornerPanel = New AdornerPanel()
    
                        ' Add the adorner to the adorner panel.
                        Me.opacitySliderAdornerPanel.Children.Add(opacitySlider)
    
                        ' Add the panel to the Adorners collection.
                        Adorners.Add(opacitySliderAdornerPanel)
                    End If
    
                    Return Me.opacitySliderAdornerPanel
                End Get
            End Property
    
    
            ' The following method deactivates the adorner.
            Protected Overrides Sub Deactivate()
                RemoveHandler adornedControlModel.PropertyChanged, _
                    AddressOf AdornedControlModel_PropertyChanged
                MyBase.Deactivate()
    
            End Sub
    
            ' The following method handles the PropertyChanged event.
            ' It updates the slider control's value if the adorned control's 
            ' Background property changed,
            Sub AdornedControlModel_PropertyChanged( _
                ByVal sender As Object, _
                ByVal e As System.ComponentModel.PropertyChangedEventArgs)
    
                If e.PropertyName = "Background" Then
                    opacitySlider.Value = GetCurrentOpacity()
                End If
    
            End Sub
    
            ' The following method handles the Loaded event.
            ' It assigns the slider control's initial value.
            Sub slider_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    
                opacitySlider.Value = GetCurrentOpacity()
    
            End Sub
    
            ' The following method handles the MouseLeftButtonDown event.
            ' It calls the BeginEdit method on the ModelItem which represents 
            ' the adorned control.
            Sub slider_MouseLeftButtonDown( _
                ByVal sender As Object, _
                ByVal e As System.Windows.Input.MouseButtonEventArgs)
    
                batchedChange = adornedControlModel.BeginEdit()
    
            End Sub
    
            ' The following method handles the MouseLeftButtonUp event.
            ' It commits any changes made to the ModelItem which represents the
            ' the adorned control.
            Sub slider_MouseLeftButtonUp( _
                ByVal sender As Object, _
                ByVal e As System.Windows.Input.MouseButtonEventArgs)
    
                If Not (batchedChange Is Nothing) Then
                    batchedChange.Complete()
                    batchedChange.Dispose()
                    batchedChange = Nothing
                End If
    
            End Sub
    
            ' The following method handles the slider control's 
            ' ValueChanged event. It sets the value of the 
            ' Background opacity by using the ModelProperty type.
            Sub slider_ValueChanged( _
                ByVal sender As Object, _
                ByVal e As RoutedPropertyChangedEventArgs(Of Double))
    
                If (True) Then
                    Dim newOpacityValue As Double = e.NewValue
    
                    ' During setup, don't make a value local and set the opacity.
                    If newOpacityValue = GetCurrentOpacity() Then
                        Return
                    End If
    
                    ' Access the adorned control's Background property
                    ' by using the ModelProperty type.
                    Dim backgroundProperty As ModelProperty = _
                        adornedControlModel.Properties("Background")
                    If Not backgroundProperty.IsSet Then
                        ' If the value isn't local, make it local 
                        ' before setting a sub-property value.
                        backgroundProperty.SetValue(backgroundProperty.ComputedValue)
                    End If
    
                    ' Set the Opacity property on the Background Brush.
                    backgroundProperty.Value.Properties("Opacity").SetValue(newOpacityValue)
                End If
            End Sub
    
            ' This utility method gets the adorned control's
            ' Background brush by using the ModelItem.
            Function GetCurrentOpacity() As Double
    
                Dim backgroundBrushComputedValue As Brush = _
                CType(adornedControlModel.Properties("Background").ComputedValue,  _
                Brush)
    
                Return backgroundBrushComputedValue.Opacity
    
            End Function
        End Class
    End Namespace
    
    using System;
    using System.Collections.Generic;
    using System.Text;
    using System.Windows.Input;
    using System.Windows;
    using System.Windows.Automation;
    using System.Windows.Controls;
    using System.Windows.Media;
    using System.Windows.Shapes;
    using Microsoft.Windows.Design.Interaction;
    using Microsoft.Windows.Design.Model;
    
    namespace CustomControlLibrary.VisualStudio.Design
    {
        // The following class implements an adorner provider for the 
        // adorned control. The adorner is a slider control, which 
        // changes the Background opacity of the adorned control.
        class OpacitySliderAdornerProvider : PrimarySelectionAdornerProvider
        {
            private ModelItem adornedControlModel;
            private ModelEditingScope batchedChange;
            private Slider opacitySlider;
            private AdornerPanel opacitySliderAdornerPanel;
    
            public OpacitySliderAdornerProvider()
            {
                opacitySlider = new Slider();
            }
    
            // The following method is called when the adorner is activated.
            // It creates the adorner control, sets up the adorner panel,
            // and attaches a ModelItem to the adorned control.
            protected override void Activate(ModelItem item)
            {
                // Save the ModelItem and hook into when it changes.
                // This enables updating the slider position when 
                // a new Background value is set.
                adornedControlModel = item;
                adornedControlModel.PropertyChanged += 
                    new System.ComponentModel.PropertyChangedEventHandler(
                        AdornedControlModel_PropertyChanged);
    
                // Setup the slider's min and max values.
                opacitySlider.Minimum = 0;
                opacitySlider.Maximum = 1;
    
                // Setup the adorner panel.
                // All adorners are placed in an AdornerPanel
                // for sizing and layout support.
                AdornerPanel myPanel = this.Panel;
    
                // The slider extends the full width of the control it adorns.
                AdornerPanel.SetAdornerHorizontalAlignment( 
                    opacitySlider, 
                    AdornerHorizontalAlignment.Stretch);
    
                // Position the adorner above the control it adorns.
                AdornerPanel.SetAdornerVerticalAlignment(
                    opacitySlider, 
                    AdornerVerticalAlignment.OutsideTop);
    
                // Position the adorner 5 pixels above the control. 
                AdornerPanel.SetAdornerMargin(
                    opacitySlider, 
                    new Thickness(0, 0, 0, 5));
    
                // Initialize the slider when it is loaded.
                opacitySlider.Loaded += new RoutedEventHandler(slider_Loaded);
    
                // Handle the value changes of the slider control.
                opacitySlider.ValueChanged += 
                    new RoutedPropertyChangedEventHandler<double>(
                        slider_ValueChanged);
    
                opacitySlider.PreviewMouseLeftButtonUp += 
                    new System.Windows.Input.MouseButtonEventHandler(
                        slider_MouseLeftButtonUp);
    
                opacitySlider.PreviewMouseLeftButtonDown += 
                    new System.Windows.Input.MouseButtonEventHandler(
                        slider_MouseLeftButtonDown);
    
                base.Activate(item);
            }
    
            // The Panel utility property demand-creates the 
            // adorner panel and adds it to the provider's 
            // Adorners collection.
            public AdornerPanel Panel 
            { 
                get
                {
                    if (this.opacitySliderAdornerPanel == null)
                    {
                        opacitySliderAdornerPanel = new AdornerPanel();
    
                        opacitySliderAdornerPanel.Children.Add(opacitySlider);
    
                        // Add the panel to the Adorners collection.
                        Adorners.Add(opacitySliderAdornerPanel);
                    }
    
                    return this.opacitySliderAdornerPanel;
                } 
            }
    
    
            // The following method deactivates the adorner.
            protected override void Deactivate()
            {
                adornedControlModel.PropertyChanged -= 
                    new System.ComponentModel.PropertyChangedEventHandler(
                        AdornedControlModel_PropertyChanged);
                base.Deactivate();
            }
    
            // The following method handles the PropertyChanged event.
            // It updates the slider control's value if the adorned control's 
            // Background property changed,
            void AdornedControlModel_PropertyChanged(
                object sender, 
                System.ComponentModel.PropertyChangedEventArgs e)
            {
                if (e.PropertyName == "Background")
                {   
                    opacitySlider.Value = GetCurrentOpacity();
                }
            }
    
            // The following method handles the Loaded event.
            // It assigns the slider control's initial value.
            void slider_Loaded(object sender, RoutedEventArgs e)
            {   
                opacitySlider.Value = GetCurrentOpacity();
            }
    
            // The following method handles the MouseLeftButtonDown event.
            // It calls the BeginEdit method on the ModelItem which represents 
            // the adorned control.
            void slider_MouseLeftButtonDown(
                object sender, 
                System.Windows.Input.MouseButtonEventArgs e)
            {
                batchedChange = adornedControlModel.BeginEdit();
            }
    
            // The following method handles the MouseLeftButtonUp event.
            // It commits any changes made to the ModelItem which represents the
            // the adorned control.
            void slider_MouseLeftButtonUp(
                object sender, 
                System.Windows.Input.MouseButtonEventArgs e)
            {
                if (batchedChange != null)
                {
                    batchedChange.Complete();
                    batchedChange.Dispose();
                    batchedChange = null;
                }
            }
    
            // The following method handles the slider control's 
            // ValueChanged event. It sets the value of the 
            // Background opacity by using the ModelProperty type.
            void slider_ValueChanged(
                object sender, 
                RoutedPropertyChangedEventArgs<double> e)
            {
                double newOpacityValue = e.NewValue;
    
                // During setup, don't make a value local and set the opacity.
                if (newOpacityValue == GetCurrentOpacity())
                {
                    return;
                }
    
                // Access the adorned control's Background property
                // by using the ModelProperty type.
                ModelProperty backgroundProperty = 
                    adornedControlModel.Properties["Background"];
                if (!backgroundProperty.IsSet)
                {
                    // If the value isn't local, make it local 
                    // before setting a sub-property value.
                    backgroundProperty.SetValue(backgroundProperty.ComputedValue);
                }
    
                // Set the Opacity property on the Background Brush.
                backgroundProperty.Value.Properties["Opacity"].SetValue(newOpacityValue);
            }
    
            // This utility method gets the adorned control's
            // Background brush by using the ModelItem.
            private double GetCurrentOpacity()
            {
                Brush backgroundBrushComputedValue =
                    (Brush)adornedControlModel.Properties["Background"].ComputedValue;
    
                return backgroundBrushComputedValue.Opacity;
            }
        }
    }
    
  3. Compilare la soluzione.

Test dell'implementazione in fase di progettazione

È possibile utilizzare il controllo ButtonWithDesignTime come qualsiasi altro controllo. In WPF Designer viene gestita la creazione di tutti gli oggetti in fase di progettazione.

Per eseguire il test dell'implementazione in fase di progettazione

  1. In Visual Basic o Visual C# aggiungere un nuovo progetto di applicazione WPF denominato DemoApplication.

    MainWindow.xaml viene aperto in WPF Designer.

  2. Aggiungere un riferimento al progetto CustomControlLibrary.

  3. In visualizzazione XAML sostituire il codice XAML generato automaticamente con il seguente codice XAML. Con questo codice XAML viene aggiunto un riferimento allo spazio dei nomi CustomControlLibrary e viene aggiunto il controllo personalizzato ButtonWithDesignTime. Il pulsante viene visualizzato in visualizzazione Progettazione con il testo "Design mode active", per indicare che si trova in modalità progettazione. Se il pulsante non viene visualizzato, può essere necessario fare clic sulla barra informazioni nella parte superiore della finestra di progettazione per ricaricare la visualizzazione.

    <Window x:Class="DemoApplication.MainWindow"
        xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:cc="clr-namespace:CustomControlLibrary;assembly=CustomControlLibrary"
        Title="Window1" Height="300" Width="300">
        <Grid>
            <cc:ButtonWithDesignTime Margin="30,30,30,30" Background="#FFD4D0C8"></cc:ButtonWithDesignTime>
        </Grid>
    </Window>
    
  4. In visualizzazione Progettazione fare clic sul controllo ButtonWithDesignTime per selezionarlo.

    Verrà visualizzato un controllo Slider sopra il controllo ButtonWithDesignTime.

  5. Utilizzare lo strumento decorativo visuale del dispositivo di scorrimento per modificare l'opacità del pulsante.

    In visualizzazione XAML, la proprietà Opacity viene impostata sul valore specificato dal controllo Slider.

  6. Eseguire il progetto DemoApplication.

    In fase di esecuzione il pulsante presenta l'opacità che è stata impostata con lo strumento decorativo visuale.

Passaggi successivi

È possibile aggiungere altre funzionalità in fase di progettazione ai controlli personalizzati.

Vedere anche

Riferimenti

PrimarySelectionAdornerProvider

Altre risorse

Esempi di estensibilità di WPF Designer

Concetti avanzati sulla estensibilità

Estensibilità di Progettazione WPF

Aggiunta di metadati della fase di progettazione