Пошаговое руководство. Создание графического элемента времени разработки

Статья
08/11/2011

В данном пошаговом руководстве описывается создание графического элемента времени разработки для пользовательского элемента управления Windows Presentation Foundation (WPF). Этот графический элемент можно использовать в Конструктор WPF для Visual Studio, чтобы задать значение свойства Opacity для пользовательского элемента управления "кнопка". В данном пошаговом руководстве элемент управления является простой кнопкой, а графический элемент – это ползунок, позволяющий изменить прозрачность кнопки. Полный листинг кода см. в примере "Графический элемент ползунка непрозрачности" на веб-странице WPF and Silverlight Designer ExtensibilitySamples.

В данном пошаговом руководстве выполняются следующие задачи.

Создание проекта библиотеки настраиваемых элементов управления WPF.
Создание отдельной сборки для метаданных времени разработки.
Реализация поставщика графических элементов.
Тестирование элемента управления во время разработки.

В результате будет полностью описан процесс создания поставщика графических элементов для пользовательского элемента управления.

Примечание

Отображаемые диалоговые окна и команды меню могут отличаться от описанных в справке в зависимости от текущих настроек или выпуска.Чтобы изменить параметры, выберите в меню Сервис пункт Импорт и экспорт параметров.Дополнительные сведения см. в разделе Работа с параметрами.

Обязательные компоненты

Ниже приведены компоненты, необходимые для выполнения данного пошагового руководства.

Visual Studio 2010.

Создание пользовательского элемента управления

Первым этапом является создание проекта для пользовательского элемента управления. Этот элемент управления представляет собой простую кнопку, созданную с помощью небольшого количества кода, в котором для реализации поведения во время разработки используется метод GetIsInDesignMode.

Создание пользовательского элемента управления

Создайте новый проект библиотеки пользовательских элементов управления WPF на языке Visual Basic или Visual C# с именем CustomControlLibrary.

В редакторе кода открывается код для элемента управления CustomControl1.
В обозревателе решений измените имя файла с кодом на ButtonWithDesignTime.cs или ButtonWithDesignTime.vb. Если появляется окно сообщения, запрашивающее подтверждение переименования всех ссылок в этом проекте, нажмите кнопку Да.
Откройте файл ButtonWithDesignTime.cs или ButtonWithDesignTime.vb в редакторе кода.

Замените автоматически создаваемый код на следующий код. Пользовательский элемент управления ButtonWithDesignTime наследуется от Button и в нем отображается текст "Design mode active", когда кнопка появляется в конструкторе. Проверка GetIsInDesignMode и следующий код времени разработки являются необязательными и приведены только для демонстрации.

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

Задайте выходной путь проекта как "bin\".
Выполните построение решения.

Создание сборки метаданных времени разработки

Код времени разработки развертывается в особых сборках метаданных. В данном руководстве пользовательский графический элемент поддерживается только Visual Studio и развертывается в сборке с именем CustomControlLibrary.VisualStudio.Design. Дополнительные сведения см. в разделе Предоставление метаданных времени разработки.

Создание сборки метаданных времени разработки

Добавьте к решению новый проект библиотеки классов на языке Visual Basic или Visual C# с именем CustomControlLibrary.VisualStudio.Design.
Задайте выходной путь проекта как ".. \CustomControlLibrary\bin\". В этом случае сборка элемента управления и сборка метаданных будут находиться в одной папке, что обеспечит доступ к метаданным для конструкторов.
Добавьте ссылки на следующие сборки WPF:
- PresentationCore
- PresentationFramework
- System.Xaml
- WindowsBase
Добавьте ссылки на следующие сборки сред. Конструктор WPF.
- Microsoft.Windows.Design.Extensibility
- Microsoft.Windows.Design.Interaction
Добавьте ссылку на проект CustomControlLibrary.
В обозревателе решений измените имя файла с кодом Class1 на Metadata.cs или Metadata.vb.

Замените автоматически создаваемый код на следующий код. Этот код создает таблицу AttributeTable, в которой пользовательская реализация времени разработки присоединяется к классу 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();
            }
        }
    }
}

Сохраните решение.

Реализация поставщика графических элементов

Поставщик графического элемента реализуется в типе с именем OpacitySliderAdornerProvider. Этот графический элемент позволяет пользователю устанавливать свойство элемента управления Opacity во время разработки.

Реализация поставщика графических элементов

Добавьте новый класс с именем OpacitySliderAdornerProvider в проект CustomControlLibrary.VisualStudio.Design.

В редакторе кода для поставщика OpacitySliderAdornerProvider замените автоматически создаваемый код на следующий код. В этом коде реализуется поставщик PrimarySelectionAdornerProvider, который предоставляет графический элемент на базе элемента управления 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;
        }
    }
}

Выполните построение решения.

Тестирование реализации времени разработки

Элемент управления ButtonWithDesignTime можно использовать как любой другой элемент управления WPF. сред. Конструктор WPF управляет созданием всех объектов времени разработки.

Тестирование реализации времени разработки

Добавьте к решению новый проект приложения WPF на языке Visual Basic или Visual C# с именем DemoApplication.

Файл MainWindow.xaml будет открыт в сред. Конструктор WPF.
Добавьте ссылку на проект CustomControlLibrary.
В представлении XAML замените автоматически созданный код XAML на следующий код XAML. Этот код XAML добавляет ссылку на пространство имен CustomControlLibrary и добавляет пользовательский элемент управления ButtonWithDesignTime. Кнопка появляется в представлении конструктора с текстом "Режим разработки активен", обозначающим включение режима разработки. Если кнопка не отображается, щелкните панель информации в верхней части конструктора для перезагрузки представления.
```
<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>
```
В представлении "Конструктор" выберите элемент управления ButtonWithDesignTime.

Над элементом ButtonWithDesignTime появится элемент управления Slider
Ползунок графического элемента используется для изменения прозрачности кнопки.

В представлении XAML свойству Opacity присвоено значение, указанное в элементе управления Slider.
Запустите проект DemoApplication.

Во время выполнения проекта кнопка будет отображаться с прозрачностью, заданной в графическом элементе.

Следующие действия

Для пользовательских элементов управления можно добавить больше специальных компонентов времени разработки.

Добавьте MenuAction к пользовательскому элементу времени разработки. Дополнительные сведения см. в разделе Пошаговое руководство. Создание поставщика меню.
Создайте поставщик графического элемента для редактирования "на месте". Дополнительные сведения см. в разделе Пошаговое руководство. Реализация редактирования по месту.
Создайте пользовательский редактор цвета, который можно использовать в окне "Свойства". Дополнительные сведения см. в разделе Пошаговое руководство. Реализация редактора цвета.