Walkthrough: Implementing In-Place Editing

Article
05/09/2012

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

This walkthrough shows how to implement in-place editing for a Windows Presentation Foundation (WPF) custom control. You can use this design-time feature in the WPF Designer for Visual Studio to set the value of the Content property on a custom button control. For this walkthrough, the control is a simple button and the adorner is a text box that allows you to change the content of the button.

In this walkthrough, you perform the following tasks:

Create a WPF custom control library project.
Create a separate assembly for design-time metadata.
Implement the adorner provider for in-place editing.
Test the control at design time.

When you are finished, you will know how create an adorner provider for a custom control.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

Visual Studio 2012 RC.

Creating the Custom Control

The first step is to create the project for the custom control. The control is a simple button with small amount of design-time code, which uses the GetIsInDesignMode method to implement a design-time behavior.

To create the custom control

Create a new WPF Custom Control Library project in Visual C# named CustomControlLibrary.

The code for CustomControl1 opens in the Code Editor.
In Solution Explorer, change the name of the code file to DemoControl.cs. If a message box appears that asks if you want to perform a rename for all references in this project, click Yes.
Open DemoControl.cs in the Code Editor.

Replace the automatically generated code with the following code. The DemoControl custom control inherits from Button

using System;
using System.Windows;
using System.Windows.Controls;

namespace CustomControlLibrary
{
    public class DemoControl : Button
    {   
    }
}

Set the project's output path to "bin\".
Build the solution.

Creating the Design-time Metadata Assembly

Design-time code is deployed in special metadata assemblies. For this walkthrough, the custom adorner is supported by Visual Studio only and is deployed in an assembly named CustomControlLibrary.VisualStudio.Design. For more information, see Providing Design-time Metadata.

To create the design-time metadata assembly

Add a new Class Library project in Visual C# named CustomControlLibrary.VisualStudio.Design to the solution.
Set the project's output path to "..\CustomControlLibrary\bin\". This keeps the control's assembly and the metadata assembly in the same folder, which enables metadata discovery for designers.
Add references to the following WPF assemblies.
- PresentationCore
- PresentationFramework
- System.Xaml
- WindowsBase
Add references to the following WPF Designer assemblies.
- Microsoft.Windows.Design.Extensibility
- Microsoft.Windows.Design.Interaction
Add a reference to the CustomControlLibrary project.
In Solution Explorer, change the name of the Class1 code file to Metadata.cs.

Replace the automatically generated code with the following code. This code creates an AttributeTable which attaches the custom design-time implementation to the DemoControl class.

using System;
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(DemoControl),
                    new FeatureAttribute(typeof(InplaceButtonAdorners)));

                return builder.CreateTable();
            }
        }
    }
}

Save the solution.

Implementing the Adorner Provider

The adorner provider is implemented in a type named InplaceButtonAdorners. This adorner provider enables the user to set the control's Content property at design time.

To implement the adorner provider

Add a new class named InplaceButtonAdorners to the CustomControlLibrary.VisualStudio.Design project.

In the Code Editor for InplaceButtonAdorners, replace the automatically generated code with the following code. This code implements a PrimarySelectionAdornerProvider which provides an adorner based on a TextBox control.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Shapes;
using Microsoft.Windows.Design.Interaction;
using System.Windows.Data;
using System.Windows.Input;
using System.ComponentModel;
using Microsoft.Windows.Design.Model;
//using SampleControls.Designer;
using System.Windows.Media;
using Microsoft.Windows.Design.Metadata;
using System.Globalization;


namespace CustomControlLibrary.VisualStudio.Design
{

    // The InplaceButtonAdorners class provides two adorners:  
    // an activate glyph that, when clicked, activates in-place 
    // editing, and an in-place edit control, which is a text box.
    internal class InplaceButtonAdorners : PrimarySelectionAdornerProvider
    {
        private Rectangle activateGlyph;
        private TextBox editGlyph;
        private AdornerPanel adornersPanel;
        private ModelItem _editedItem;

        public InplaceButtonAdorners()
        {
            adornersPanel = new AdornerPanel();
            adornersPanel.IsContentFocusable = true;
            adornersPanel.Children.Add(ActivateGlyph);

            Adorners.Add(adornersPanel);
        }

        protected override void Activate(ModelItem item)
        {
            _editedItem = item;
            _editedItem.PropertyChanged += new PropertyChangedEventHandler(OnEditedItemPropertyChanged);
            base.Activate(item);
        }


        protected override void Deactivate()
        {
            if (_editedItem != null)
            {
                _editedItem.PropertyChanged -= new PropertyChangedEventHandler(OnEditedItemPropertyChanged);
                _editedItem = null;
            }
            base.Deactivate();
        }

        private ModelItem EditedItem
        {
            get
            {
                return _editedItem;
            }
        }
        private UIElement ActivateGlyph
        {
            get
            {
                if (activateGlyph == null)
                {
                    // The following code specifies the shape of the activate 
                    // glyph. This can also be implemented by using a XAML template.
                    Rectangle glyph = new Rectangle();
                    glyph.Fill = AdornerColors.HandleFillBrush;
                    glyph.Stroke = AdornerColors.HandleBorderBrush;
                    glyph.RadiusX = glyph.RadiusY = 2;
                    glyph.Width = 20;
                    glyph.Height = 15;
                    glyph.Cursor = Cursors.Hand;

                    ToolTipService.SetToolTip(
                        glyph,
                        "Click to edit the text of the button.  " +
                        "Enter to commit, ESC to cancel.");

                    // Position the glyph to the upper left of the DemoControl, 
                    // and slightly inside.
                    AdornerPanel.SetAdornerHorizontalAlignment(glyph, AdornerHorizontalAlignment.Left);
                    AdornerPanel.SetAdornerVerticalAlignment(glyph, AdornerVerticalAlignment.Top);
                    AdornerPanel.SetAdornerMargin(glyph, new Thickness(5, 5, 0, 0));

                    // Add interaction to the glyph.  A click starts in-place editing.
                    ToolCommand command = new ToolCommand("ActivateEdit");
                    Task task = new Task();
                    task.InputBindings.Add(new InputBinding(command, new ToolGesture(ToolAction.Click)));
                    task.ToolCommandBindings.Add(new ToolCommandBinding(command, OnActivateEdit));
                    AdornerProperties.SetTask(glyph, task);
                    activateGlyph = glyph;
                }

                return activateGlyph;
            }
        }
        // When in-place editing is activated, a text box is placed 
        // over the control and focus is set to its input task. 
        // Its task commits itself when the user presses enter or clicks 
        // outside the control.
        private void OnActivateEdit(object sender, ExecutedToolEventArgs args)
        {
            adornersPanel.Children.Remove(ActivateGlyph);
            adornersPanel.Children.Add(EditGlyph);

            // Once added, the databindings activate. 
            // All the text can now be selected.
            EditGlyph.SelectAll();
            EditGlyph.Focus();

            GestureData data = GestureData.FromEventArgs(args);
            Task task = AdornerProperties.GetTask(EditGlyph);
            task.Description = "Edit text";
            task.BeginFocus(data);
        }

        // The EditGlyph utility property creates a TextBox to use as 
        // the in-place editing control. This property centers the TextBox
        // inside the target control and sets up data bindings between 
        // the TextBox and the target control.
        private TextBox EditGlyph
        {
            get
            {
                if (editGlyph == null && EditedItem != null)
                {
                    TextBox glyph = new TextBox();
                    glyph.Padding = new Thickness(0);
                    glyph.BorderThickness = new Thickness(0);

                    UpdateTextBlockLocation(glyph);

                    // Make the background white to draw over the existing text.
                    glyph.Background = SystemColors.WindowBrush;


                    // Two-way data bind the text box's text property to content.
                    Binding binding = new Binding();
                    binding.Source = EditedItem;
                    binding.Path = new PropertyPath("Content");
                    binding.Mode = BindingMode.TwoWay;
                    binding.UpdateSourceTrigger = UpdateSourceTrigger.PropertyChanged;
                    binding.Converter = new ContentConverter();
                    glyph.SetBinding(TextBox.TextProperty, binding);


                    // Create a task that describes the UI interaction.
                    ToolCommand commitCommand = new ToolCommand("Commit Edit");
                    Task task = new Task();
                    task.InputBindings.Add(
                        new InputBinding(
                            commitCommand,
                            new KeyGesture(Key.Enter)));

                    task.ToolCommandBindings.Add(
                        new ToolCommandBinding(commitCommand, delegate
                        {
                            task.Complete();
                        }));

                    task.FocusDeactivated += delegate
                    {
                        adornersPanel.Children.Remove(EditGlyph);
                        adornersPanel.Children.Add(ActivateGlyph);
                    };

                    AdornerProperties.SetTask(glyph, task);

                    editGlyph = glyph;
                }

                return editGlyph;
            }
        }

        private void UpdateTextBlockLocation(TextBox glyph)
        {
            Point textBlockLocation = FindTextBlock();
            AdornerPanel.SetAdornerMargin(glyph, new Thickness(textBlockLocation.X, textBlockLocation.Y, 0, 0));
        }


        /// <summary>
        /// iterate through the visual tree and look for TextBlocks to position the glyph
        /// </summary>
        /// <returns></returns>
        private Point FindTextBlock()
        {
            // use ModelFactory to figure out what the type of text block is - works for SL and WPF.
            Type textBlockType = ModelFactory.ResolveType(Context, new TypeIdentifier(typeof(TextBlock).FullName));

            ViewItem textBlock = FindTextBlock(textBlockType, EditedItem.View);
            if (textBlock != null)
            {
                // transform the top left of the textblock to the view coordinate system.
                return textBlock.TransformToView(EditedItem.View).Transform(new Point(0, 0));
            }

            // couldn't find a text block in the visual tree.  Return a default position.
            return new Point();
        }
        private ViewItem FindTextBlock(Type textBlockType, ViewItem view)
        {
            if (view == null)
            {
                return null;
            }

            if (textBlockType.IsAssignableFrom(view.ItemType))
            {
                return view;
            }
            else
            {
                // walk through the child tree recursively looking for it.
                foreach (ViewItem child in view.VisualChildren)
                {
                    return FindTextBlock(textBlockType, child);
                }
            }
            return null;
        }
        void OnEditedItemPropertyChanged(object sender, PropertyChangedEventArgs e)
        {
            if (e.PropertyName == "Content")
            {
                if (EditGlyph != null)
                {
                    UpdateTextBlockLocation(EditGlyph);
                }
            }
        }


        // The ContentConverter class ensures that only strings
        // are assigned to the Text property of EditGlyph.
        private class ContentConverter : IValueConverter
        {
            public object Convert(
                object value,
                Type targetType,
                object parameter,
                System.Globalization.CultureInfo culture)
            {
                if (value is ModelItem)
                {
                    return ((ModelItem)value).GetCurrentValue();
                }
                else if (value != null)
                {
                    return value.ToString();
                }

                return string.Empty;
            }

            public object ConvertBack(
                object value,
                Type targetType,
                object parameter,
                System.Globalization.CultureInfo culture)
            {
                return value;
            }
        }
    }

}

Build the solution.

Testing the Design-time Implementation

You can use the DemoControl class as you would use any other WPF control. The WPF Designer handles the creation of all design-time objects.

To test the design-time implementation

Add a new WPF Application project in Visual C# named DemoApplication to the solution.

MainWindow.xaml opens in the WPF Designer.
Add a reference to the CustomControlLibrary project.

In XAML view, replace the automatically generated XAML with the following XAML. This XAML adds a reference to the CustomControlLibrary namespace and adds the DemoControl custom control. If the control does not appear, you might have to click the Information bar at the top of the designer to reload the view.

<Window x:Class="DemoApplication.MainWindow"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:ccl="clr-namespace:CustomControlLibrary;assembly=CustomControlLibrary"
    Title="Window1" Height="300" Width="300">
    <Grid>
        <ccl:DemoControl></ccl:DemoControl>
    </Grid>
</Window>

Rebuild the solution.
In Design view, click the DemoControl control to select it.

A small Rectangle glyph appears in the upper-left corner of the DemoControl control.
Click the Rectangle glyph to activate in-place editing.

A text box appears showing the Content of DemoControl. Since the content is currently empty, you just see a cursor in the center of the button.
Type in a new value for the text content, and then press the ENTER key.

In XAML view, the Content property is set to the text value that you typed in Design view.
Set the DemoApplication project as the startup project and run the solution.

At run time, the button has the text value that you set with the adorner.

Next Steps

You can add more custom design-time features to your custom controls.

Add a MenuAction to your custom design time. For more information, see Walkthrough: Creating a Menu Provider.
Create a custom color editor, which you can use in the Properties window. For more information, see Walkthrough: Implementing a Color Editor.
Create a custom adorner for setting the opacity of a control. For more information, see Walkthrough: Creating a Design-time Adorner.