Compartir a través de


Tutorial: Crear un adorno en tiempo de diseño

En este tutorial se muestra cómo crear un adorno en tiempo de diseño para un control personalizado de Windows Presentation Foundation (WPF). Puede utilizar este adorno en tiempo de diseño en WPF Designer for Visual Studio para establecer el valor de la propiedad Opacity en un control de botón personalizado. En este tutorial, el control es un botón simple y el adorno es un control deslizante que le permite cambiar la opacidad del botón. Para obtener el código completo, vea el ejemplo Opacity Slider Adorner en el sitio WPF Designer Extensibility Samples.

En este tutorial realizará las siguientes tareas:

  • Crear un proyecto de biblioteca de controles personalizados de WPF.

  • Crear un ensamblado independiente para los metadatos de tiempo de diseño.

  • Implementar el proveedor de adornos.

  • Probar el control en tiempo de diseño.

Cuando haya finalizado, sabrá crear un proveedor de adornos para un control personalizado.

Nota

Los cuadros de diálogo y comandos de menú que se ven pueden diferir de los descritos en la Ayuda, en función de los valores de configuración o de edición activos. Para cambiar la configuración, elija la opción Importar y exportar configuraciones del menú Herramientas. Para obtener más información, vea Trabajar con valores de configuración.

Requisitos previos

Necesita los componentes siguientes para completar este tutorial:

  • Visual Studio 2010.

Crear el control personalizado

El primer paso consiste en crear el proyecto para el control personalizado. El control es un botón simple con poco código en tiempo de diseño, que utiliza el método GetIsInDesignMode para implementar un comportamiento en tiempo de diseño.

Para crear el control personalizado

  1. Cree un nuevo proyecto de biblioteca de controles personalizados de WPF en Visual Basic o Visual C# denominado CustomControlLibrary.

    El código de CustomControl1 se abre en el Editor de código.

  2. En el Explorador de soluciones, cambie el nombre del archivo de código a ButtonWithDesignTime.cs o ButtonWithDesignTime.vb. Si se muestra un cuadro de mensaje que le pregunta si desea cambiar el nombre de todas las referencias de este proyecto, haga clic en .

  3. Abra ButtonWithDesignTime.cs o ButtonWithDesignTime.vb en el Editor de código.

  4. Reemplace el código generado automáticamente por el código siguiente. El control personalizado ButtonWithDesignTime hereda de Button y muestra el texto "Design mode active" cuando el botón aparece en el diseñador. GetIsInDesignMode realiza comprobaciones y el siguiente código en tiempo de diseño es opcional y se muestra sólo con fines de demostración.

    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. Establezca la ruta de acceso de los resultados del proyecto en "bin\".

  6. Genere la solución.

Crear el ensamblado de metadatos en tiempo de diseño

El código en tiempo de diseño se implementa en ensamblados de metadatos especiales. En este tutorial, el adorno personalizado sólo lo admite Visual Studio y se implementa en un ensamblado denominado CustomControlLibrary.VisualStudio.Design. Para obtener más información, vea Proporcionar metadatos en tiempo de diseño.

Para crear el ensamblado de metadatos en tiempo de diseño

  1. Agregue un nuevo proyecto de biblioteca de clases en Visual Basic o Visual C# denominado CustomControlLibrary.VisualStudio.Design a la solución.

  2. Establezca la ruta de acceso de salida del proyecto en ".. \CustomControlLibrary\bin\". De este modo, el ensamblado del control y el ensamblado de metadatos permanecen en la misma carpeta, lo que permite que los diseñadores detecten los metadatos.

  3. Agregue referencias a los siguientes ensamblados de WPF.

    • PresentationCore

    • PresentationFramework

    • System.Xaml

    • WindowsBase

  4. Agregue referencias a los siguientes ensamblados de WPF Designer.

    • Microsoft.Windows.Design.Extensibility

    • Microsoft.Windows.Design.Interaction

  5. Agregue una referencia al proyecto CustomControlLibrary.

  6. En el Explorador de soluciones, cambie el nombre del archivo de código Class1 a Metadata.cs o Metadata.vb.

  7. Reemplace el código generado automáticamente por el código siguiente. Este código crea un objeto AttributeTable que asocia la implementación en tiempo de diseño personalizada a la clase 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. Guarde la solución.

Implementar el proveedor de adornos

El proveedor de adornos se implementa en un tipo denominado OpacitySliderAdornerProvider. Este adorno permite al usuario establecer la propiedad Opacity del control en tiempo de diseño.

Para implementar el proveedor de adornos

  1. Agregue una nueva clase denominada OpacitySliderAdornerProvider al proyecto CustomControlLibrary.VisualStudio.Design.

  2. En el editor de código de OpacitySliderAdornerProvider, reemplace el código generado automáticamente por el código siguiente. Este código implementa un objeto PrimarySelectionAdornerProvider que proporciona un adorno basado en un control 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. Genere la solución.

Probar la implementación en tiempo de diseño

Puede utilizar el control ButtonWithDesignTime como cualquier otro control de WPF. WPF Designer administra la creación de todos los objetos en tiempo de diseño.

Para probar la implementación en tiempo de diseño

  1. Agregue un nuevo proyecto de aplicación de WPF en Visual Basic o Visual C# denominado DemoApplication a la solución.

    MainWindow.xaml se abrirá en WPF Designer.

  2. Agregue una referencia al proyecto CustomControlLibrary.

  3. En la vista XAML, reemplace el XAML generado automáticamente por el XAML siguiente. Este XAML agrega una referencia al espacio de nombres CustomControlLibrary y agrega el control personalizado ButtonWithDesignTime. El botón aparece en la Vista de diseño con el texto "Design mode active", que indica que se encuentra en modo de diseño. Si el botón no aparece, es posible que tenga que hacer clic en la barra de información situada en la parte superior del diseñador para volver a cargar la vista.

    <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. En la Vista de diseño, haga clic en el control ButtonWithDesignTime para seleccionarlo.

    Aparecerá un control Slider sobre el control ButtonWithDesignTime.

  5. Utilice el adorno del control deslizante para cambiar la opacidad del botón.

    En la vista XAML, la propiedad Opacity se establece en el valor que especifica el control Slider.

  6. Ejecute el proyecto DemoApplication.

    En tiempo de ejecución, el botón tiene la opacidad que establece con el adorno.

Pasos siguientes

Puede agregar más características personalizadas en tiempo de diseño a los controles personalizados.

Vea también

Referencia

PrimarySelectionAdornerProvider

Otros recursos

WPF Designer Extensibility Samples

Conceptos de extensibilidad avanzada

Extensibilidad de WPF Designer

Proporcionar metadatos en tiempo de diseño