#1,191 – Custom Element with a Single Child Element

Below is an example of a simple custom element that derives from FrameworkElement and includes a single child element (UIElement), set using the Child dependency property.

Here’s the full code for the custom element.  We do the following:

  • Override both Measure and Layout
  • Override VisualChildrenCount and GetVisualChild to respond indicating that we have a single child
  • Override Render to render the graphical portion of the control
  • Use AddVisualChildAddLogicalChild to indicate that the child element belongs to the parent element
    public class MyElement : FrameworkElement
    {
        private static FrameworkPropertyMetadata childMetadata =
                   new FrameworkPropertyMetadata(null,
                            FrameworkPropertyMetadataOptions.AffectsParentArrange,
                            new PropertyChangedCallback(OnChildChanged));

        public static void OnChildChanged(DependencyObject obj, DependencyPropertyChangedEventArgs e)
        {
            MyElement thisElement = obj as MyElement;
            if (thisElement == null)
                throw new Exception("Child property must be attached to MyElement");

            // Remove old one
            Visual oldChild = e.OldValue as Visual;
            if (oldChild != null)
            {
                thisElement.RemoveVisualChild(oldChild);
                thisElement.RemoveLogicalChild(oldChild);
            }

            // Attach new one
            Visual newChild = e.NewValue as Visual;
            if (newChild != null)
            {
                thisElement.AddVisualChild(newChild);
                thisElement.AddLogicalChild(newChild);
            }
        }

        public static readonly DependencyProperty ChildProperty =
            DependencyProperty.RegisterAttached("Child", typeof(UIElement),
                typeof(MyElement), childMetadata);

        public static void SetChild(DependencyObject depObj, UIElement value)
        {
            depObj.SetValue(ChildProperty, value);
        }

        protected override int VisualChildrenCount
        {
            get
            {
                UIElement childElement = (UIElement)GetValue(ChildProperty);
                return childElement != null ? 1 : 0;
            }
        }

        protected override Visual GetVisualChild(int index)
        {
            // (ignoring index)
            return (UIElement)GetValue(ChildProperty);
        }

        protected override Size MeasureOverride(Size availableSize)
        {
            UIElement childElement = (UIElement)GetValue(ChildProperty);
            if (childElement != null)
                childElement.Measure(availableSize);

            // "X" and child both use all of the available space
            return availableSize;
        }

        protected override Size ArrangeOverride(Size finalSize)
        {
            UIElement childElement = (UIElement)GetValue(ChildProperty);
            if (childElement != null)
                childElement.Arrange(new Rect(new Point(0.0, 0.0), finalSize));

            return finalSize;
        }

        // Render a big "X"
        protected override void OnRender(DrawingContext dc)
        {
            dc.DrawLine(new Pen(Brushes.Blue, 2.0),
                new Point(0.0, 0.0),
                new Point(ActualWidth, ActualHeight));
            dc.DrawLine(new Pen(Brushes.Green, 2.0),
                new Point(ActualWidth, 0.0),
                new Point(0.0, ActualHeight));
        }
    }

We can now use this element as follows:

    <Grid>
        <loc:MyElement>
            <loc:MyElement.Child>
                <Label Content="I'm the child" HorizontalAlignment="Center"/>
            </loc:MyElement.Child>
        </loc:MyElement>
    </Grid>

When rendered, it looks like this:

1191-001

#1,182 – Using RenderSize Properties in Custom Elements

When writing rendering code for a custom element that derives from FrameworkElement, you can use the ActualWidth and ActualHeight properties to know how to render the element.  These properties indicate the desired final size of the element, after all layout calculations have been done.

    public class MyFrameworkElement : FrameworkElement
    {
        protected override void OnRender(DrawingContext dc)
        {
            dc.DrawLine(new Pen(Brushes.Blue, 2.0),
                new Point(0.0, 0.0),
                new Point(ActualWidth, ActualHeight));
            dc.DrawLine(new Pen(Brushes.Green, 2.0),
                new Point(ActualWidth, 0.0),
                new Point(0.0, ActualHeight));
        }
    }

If a custom control derives from UIElement, it won’t have access to the ActualWidth and ActualHeight properties, but can instead use RenderSize.Width and RenderSize.Height.  (You can also use these properties from within an element that derives from FrameworkElement, since FrameworkElement inhertis from UIElement).

    public class MyUIElement : UIElement
    {
        protected override void OnRender(DrawingContext dc)
        {
            dc.DrawLine(new Pen(Brushes.Blue, 2.0),
                new Point(0.0, 0.0),
                new Point(RenderSize.Width, RenderSize.Height));
            dc.DrawLine(new Pen(Brushes.Green, 2.0),
                new Point(RenderSize.Width, 0.0),
                new Point(0.0, RenderSize.Height));
        }
    }

#1,181 – Custom Element Indicates Desired Size in MeasureOverride

By default, a custom element deriving from FrameworkElement has no desired size.  Most elements should override MeasureOverride as a way of indicating what their desired size should be.  This would typically be based on the control’s content, but also might be some minimum size.

Below, we have a custom element that indicates that it has a minimum size of 20 x 20.

    public class MyFrameworkElement : FrameworkElement
    {
        protected override Size MeasureOverride(Size availableSize)
        {
            return new Size(20.0, 20.0);
        }

        protected override void OnRender(DrawingContext dc)
        {
            dc.DrawLine(new Pen(Brushes.Blue, 2.0),
                new Point(0.0, 0.0),
                new Point(ActualWidth, ActualHeight));
            dc.DrawLine(new Pen(Brushes.Green, 2.0),
                new Point(ActualWidth, 0.0),
                new Point(0.0, ActualHeight));
        }
    }

We can still specify a desired size when consuming the element, overriding the default size.

    <Grid ShowGridLines="True">
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>

        <loc:MyFrameworkElement HorizontalAlignment="Center"
                                VerticalAlignment="Top"/>
        <loc:MyFrameworkElement Grid.Row="1" Margin="20,10"/>
    </Grid>

1181-001

#1,180 – By Default, FrameworkElement Doesn’t Have Desired Size

If you create a custom control that derives from FrameworkElement, the control won’t by default have any particular desired size.  You can see this by setting alignment properties on a simple custom control without also setting explicit Width and Height.

    <Grid ShowGridLines="True">
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>

        <loc:MyFrameworkElement HorizontalAlignment="Center"
                                VerticalAlignment="Top"/>
        <loc:MyFrameworkElement Grid.Row="1" Margin="20,10"/>
    </Grid>

You can see in the designer that the first instance of MyFrameworkElement is not visible, because it has no size.

1180-001

A custom control will typically define its desired size based on its content.  In the example above, the custom control hasn’t specified any desired size, size the control has a size of (0,0) and disappears.

 

#1,178 – Custom Element Based on FrameworkElement

You can create custom user interface elements that derive from FrameworkElement.  Below is a simple example that renders itself as a graphical “X”.  We override the OnRender method (inherited from UIElement) and use the DrawingContext object to create visual content.

    public class MyElement : FrameworkElement
    {
        protected override void OnRender(DrawingContext dc)
        {
            dc.DrawLine(new Pen(Brushes.Blue, 2.0),
                new Point(0.0, 0.0),
                new Point(ActualWidth, ActualHeight));
            dc.DrawLine(new Pen(Brushes.Green, 2.0),
                new Point(ActualWidth, 0.0),
                new Point(0.0, ActualHeight));
        }
    }

Using the new element looks like this:

    <Grid>
        <loc:MyElement/>
    </Grid>

Here’s what it looks like at run-time:
1178-001

If we host the Grid as a top-level element in a Window, our element is sized to fit the Grid, which sizes to fit the Window.  Because we render the element using ActualWidth and ActualHeight, it changes size as we resize the window.

1178-002

 

#1,177 – UIElement vs. FrameworkElement vs. Control

If you want to implement a custom element in WPF, either to display something in a user interface or to get input from a user, you’ll typically derive your custom element from one of the following classes: UIElementFrameworkElement, or Control.

The inheritance chain for these three classes is:

1177-001

When creating a custom control, you’ll want to choose as a base class whichever one of these classes has only the features that you want.  The core functionality for these three classes is:

  • UIElement  (Layout + Input + Focus + Events)
    • Layout behavior (parent/child relationship, measure/arrange passes)
    • Responding to user input (input events, command bindings)
    • Managing focus
    • Raising and responding to routed events
  • FrameworkElement adds
    • Alignment-related and Margin properties
    • Animation support
    • Data binding
    • Data templates
    • Styles
    • Defaults Focusable to false
  • Control adds
    • Control templates
    • Background, Foreground
    • Font-related properties
    • Border-related properties
    • Defaults Focusable to true

#616 – FrameworkElement.Initialized and Loaded Event Order

All elements that inherit (directly or indirectly) from FrameworkElement will fire both Initialized and Loaded events when the control is being loaded.  For example, both an Initialized and Loaded event will for each control in your application when the application is starting up.

The Initialized events for all controls fire starting with the elements at the bottom of the logical tree.  When handling the Initialize event for a particular element, you can assume that any elements below the element in question have already been initialized.

The Loaded event, on the other hand, fires from the top of the logical tree and then continues down the tree.  The Loaded events begin firing only after the layout system has figured out the position and size of every element in the tree.  So in a handler for a Loaded event, you can assume that all elements in the logical tree are fully configured.