HOW TO：建立設計階段裝飾項

發行項
08/21/2008

更新：2007 年 11 月

下列程式碼範例會示範如何建立裝飾項，這個裝飾項會在設計階段設定所選自訂控制項的不透明度。

Visual Studio 中對此工作有相當廣泛的支援。如需詳細資訊，請參閱逐步解說：建立設計階段裝飾項。

範例

下列程式碼範例示範如何為 Windows Presentation Foundation (WPF) 自訂控制項建立裝飾項。您可以在 Windows Presentation Foundation (WPF) Designer for Visual Studio 中使用這個裝飾項，設定自訂按鈕控制項上的 Opacity 屬性的值。在這個逐步解說中，控制項是簡單的按鈕，而裝飾項是可讓您變更按鈕不透明度的滑桿。

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

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, ByVal view As DependencyObject)

            ' 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

            AdornerPanel.SetHorizontalStretch(opacitySlider, AdornerStretch.Stretch)
            AdornerPanel.SetVerticalStretch(opacitySlider, AdornerStretch.None)

            Dim placement As New AdornerPlacementCollection()

            ' The adorner's width is relative to the content.
            ' The slider extends the full width of the control it adorns.
            placement.SizeRelativeToContentWidth(1.0, 0)

            ' The adorner's height is the same as the slider's.
            placement.SizeRelativeToAdornerDesiredHeight(1.0, 0)

            ' Position the adorner above the control it adorns.
            placement.PositionRelativeToAdornerHeight(-1.0, 0)

            ' Position the adorner up 5 pixels. This demonstrates 
            ' that these placement calls are additive. These two calls
            ' are equivalent to the following single call:
            ' PositionRelativeToAdornerHeight(-1.0, -5).
            placement.PositionRelativeToAdornerHeight(0, -5)

            AdornerPanel.SetPlacements(opacitySlider, placement)

            ' 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, view)

        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(Control.BackgroundProperty)
                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(Brush.OpacityProperty).SetValue(newOpacityValue)
            End If
        End Sub

        ' This utility method gets the adorned control's
        ' Background brush by using the ModelItem.
        Function GetCurrentOpacity() As Double
            If (True) Then
                Dim backgroundBrushComputedValue As Brush = _
                CType(adornedControlModel.Properties(Control.BackgroundProperty).ComputedValue,  _
                Brush)

                Return backgroundBrushComputedValue.Opacity
            End If

        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, DependencyObject view)
        {
            // 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;

            AdornerPanel.SetHorizontalStretch(opacitySlider, AdornerStretch.Stretch);
            AdornerPanel.SetVerticalStretch(opacitySlider, AdornerStretch.None);

            AdornerPlacementCollection placement = new AdornerPlacementCollection();

            // The adorner's width is relative to the content.
            // The slider extends the full width of the control it adorns.
            placement.SizeRelativeToContentWidth(1.0, 0);

            // The adorner's height is the same as the slider's.
            placement.SizeRelativeToAdornerDesiredHeight(1.0, 0);

            // Position the adorner above the control it adorns.
            placement.PositionRelativeToAdornerHeight(-1.0, 0);

            // Position the adorner up 5 pixels. This demonstrates 
            // that these placement calls are additive. These two calls
            // are equivalent to the following single call:
            // PositionRelativeToAdornerHeight(-1.0, -5).
            placement.PositionRelativeToAdornerHeight(0, -5);

            AdornerPanel.SetPlacements(opacitySlider, placement);

            // 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, view);
        }

        // 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[Control.BackgroundProperty];
            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[Brush.OpacityProperty].SetValue(newOpacityValue);
        }

        // This utility method gets the adorned control's
        // Background brush by using the ModelItem.
        private double GetCurrentOpacity()
        {
            Brush backgroundBrushComputedValue = 
                (Brush)adornedControlModel.Properties[Control.BackgroundProperty].ComputedValue;

            return backgroundBrushComputedValue.Opacity;
        }
    }
}

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

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 IRegisterMetadata. If found, designers instantiate 
    ' this class and call its Register() method automatically.
    Friend Class Metadata
        Implements IRegisterMetadata

        ' Called by the designer to register any design-time metadata.
        Public Sub Register() Implements IRegisterMetadata.Register
            Dim builder As New AttributeTableBuilder()

            ' Add the adorner provider to the design-time metadata.
            builder.AddCustomAttributes(GetType(ButtonWithDesignTime), _
                                        New FeatureAttribute(GetType(OpacitySliderAdornerProvider)))

            MetadataStore.AddAttributeTable(builder.CreateTable())
        End Sub

    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;

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 IRegisterMetadata. If found, designers instantiate 
    // this class and call its Register() method automatically.
    internal class Metadata : IRegisterMetadata
    {
        // Called by the designer to register any design-time metadata.
        public void Register()
        {
            AttributeTableBuilder builder = new AttributeTableBuilder();

            // Add the adorner provider to the design-time metadata.
            builder.AddCustomAttributes(
                typeof(ButtonWithDesignTime), 
                new FeatureAttribute(typeof(OpacitySliderAdornerProvider)));

            MetadataStore.AddAttributeTable(builder.CreateTable());
        }
    }
}

<Window x:Class="DemoApplication.Window1"
    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>

<Window x:Class="DemoApplication.Window1"
    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 類別。
加入下列組件的參考。
- PresentationCore
- PresentationFramework
- WindowsBase

在名稱為 CustomControlLibrary 的組件中編譯 ButtonWithDesignTime 類別。

vbc /r:PresentationCore.dll /r:PresentationFramework.dll /r:WindowsBase.dll /t:library /out:CustomControlLibrary.dll ButtonWithDesignTime.vb

csc /r:PresentationCore.dll /r:PresentationFramework.dll /r:WindowsBase.dll /t:library /out:CustomControlLibrary.dll ButtonWithDesignTime.cs

編譯自訂裝飾項

建立 OpacitySliderAdornerProvider 及 Metadata 類別。
加入下列組件的參考：
- PresentationCore
- PresentationFramework
- WindowsBase
- Microsoft.Windows.Design
- Microsoft.Windows.Design.Extensibility
- Microsoft.Windows.Design.Interaction
加入 CustomControlLibrary 組件或專案的參考。

在名稱為 CustomControlLibrary.VisualStudio.Design 的不同組件中，編譯 OpacitySliderAdornerProvider 和 Metadata 類別。將編譯過的組件導向至 CustomControlLibrary 組件的相同資料夾。

vbc /r:PresentationCore.dll /r:PresentationFramework.dll /r:WindowsBase.dll /r:Microsoft.Windows.Design.dll /r:Microsoft.Windows.Design.Extensibility.dll /r:Microsoft.Windows.Design.Interaction.dll /r:CustomControlLibrary.dll /t:library /out:CustomControlLibrary.VisualStudio.Design.dll OpacitySliderAdornerProvider.vb Metadata.vb

csc /r:PresentationCore.dll /r:PresentationFramework.dll /r:WindowsBase.dll /r:Microsoft.Windows.Design.dll /r:Microsoft.Windows.Design.Extensibility.dll /r:Microsoft.Windows.Design.Interaction.dll /r:CustomControlLibrary.dll /t:library /out:CustomControlLibrary.VisualStudio.Design.dll OpacitySliderAdornerProvider.cs Metadata.cs

編譯測試應用程式

在 Visual Studio 中，建立新的 WPF 應用程式專案。
加入 CustomControlLibrary 組件或專案的參考。
將 Window1.xaml 中的現有 XAML 替換成前面所列的 XAML。

在 [設計] 檢視中，Slider 控制項會出現在 ButtonWithDesignTime 控制項的上方。

請參閱

共用方式為