Wednesday, July 13, 2011

GridLayout for WPF: Escape the Margin hell

Working with WPF, you surely have come across the System.Windows.Controls.Grid class. It is a derivation of System.Windows.Controls.Panel, which in turn is a base class for layouters. You can use a Grid to create windows that have their child elements arranged in a uniform manner.

When you have worked with the Grid class, you probably know about this issue: Adding elements to the Grid will make them be strung together without any spacing between them. When you want to add spacing, you have to set each element's Margin property accordingly. This wouldn't be half as bad - it's just that, depending on where in the Grid your element is, you have to set the left, top, right and bottom margins differently. This can become quite a tedious task and makes your XAML look far more complicated than it needed to be. And that's not all - imagine you putting together a prototype of a very complex UI. Just think about one of those equalizer/sound processor programs that have dozens of controls arranged in a grid. You finally finished your prototype - you think it looks awesome - and show it to your boss. His face turns to a disgusted visage and he says "Why is it all so clung together? You can barely tell the buttons apart since they are too near to each other. Can't you add more space between them?". With the standard Grid class, you would gasp, look a bit depressed and tell your boss to come again in an hour or two. And when he comes around and wants to look at your updated prototype, you are still not finished changing all the margins correctly.

Forget that scenario. Use the GridLayout class from the download below and change all margins at once. It automatically sets a uniform margin to all child elements of this specialized Grid class. And even better - it is smart enough to set the Margin.Left of elements in the first column to 0. The same goes with the Margin.Right in the rightmost column, Margin.Top in the first row and Margin.Bottom in the last row. With this class, you simply change the newly introduced ChildMargin property and be done - you will see the effect of the changes immediately, live in the WPF designer and at runtime.

Here is a screenshot of a simple form done with the default System.Windows.Controls.Grid class - without setting any special margins. You can see how narrow the space between the elements is and that it does not look very appealing.

Default Grid form example

And here is the same form done with the GridLayout. Note that only the class of the Grid has been changed - the child elements are exactly the same.

GridLayout form example

The best of all is that this has been done in very few lines of code. It just took two steps: The first was to introduce a new property in a class that derives from System.Windows.Controls.Grid that would define the margin that the cild elements of the new Grid would use. The second set was overriding

protected void MeasureOverride(Size)
that has been introduced in FrameworkElement. The overwritten version of MeasureOverride enumerates all children and changes their Margin accordingly. After that, the base version of MeasureOverride is called. This makes sure that, before each arrangement, the margins are updated correctly.

Here is the complete source-code of the GridLayout:


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

namespace GridLayoutTest
{
    // The GridLayout is a special Panel that can be used exactly like the Grid Panel, except that it
    // defines a new property ChildMargin. ChildMargin's left, top, right and bottom margins will be applied
    // to all children in a way that the children will have a vertical space of ChildMargin.Top+ChildMargin.Bottom
    // and a horizontal space of ChildMargin.Left+ChildMargin.Right between them.
    // However, there is no margin for the borders of the internal widget, so that the GridLayout itself can be
    // aligned to another element without a margin.
    // It's best to have a look at TestWindow, which effectively tests all possible alignments of children.

    public class GridLayout : Grid
    {
        public static readonly DependencyProperty ChildMarginProperty = DependencyProperty.Register(
            "ChildMargin",
            typeof(Thickness),
            typeof(GridLayout),
            new FrameworkPropertyMetadata(new Thickness (5))
            {
                AffectsArrange = true,
                AffectsMeasure = true
            });
        // The child margin defines a margin that will be automatically applied to all children of this Grid.
        // However, the children at the edges will have the respective margins remove. E.g. the leftmost children will have
        // a Margin.Left of 0 and the children in the first row will have a Margin.Top of 0.
        // The margins that are not set to 0 are set to half the ChildMargin's value, since it's neighbour will also apply it,
        // effectively doubling it.

        public Thickness ChildMargin
        {
            get { return (Thickness)GetValue(ChildMarginProperty); }
            set 
            {
                SetValue(ChildMarginProperty, value);
                UpdateChildMargins();
            }
        }

        // UpdateChildMargin first finds out what's the rightmost column and bottom row and then applies
        // the correct margins to all children.

        public void UpdateChildMargins()
        {
            int maxColumn = 0;
            int maxRow = 0;
            foreach (UIElement element in InternalChildren)
            {
                int row = GetRow(element);
                int column = GetColumn(element);
                if (row > maxRow)
                    maxRow = row;
                if (column > maxColumn)
                    maxColumn = column;
            }
            foreach (UIElement element in InternalChildren)
            {
                FrameworkElement fe = element as FrameworkElement;
                if (null != fe)
                {
                    int row = GetRow(fe);
                    int column = GetColumn(fe);
                    double factorLeft   = 0.5;
                    double factorTop    = 0.5;
                    double factorRight  = 0.5;
                    double factorBottom = 0.5;
                    // Top row - no top margin
                    if (row == 0)
                        factorTop = 0;
                    // Bottom row - no bottom margin
                    if (row == maxRow)
                        factorBottom = 0;
                    // Leftmost column = no left margin
                    if (column == 0)
                        factorLeft = 0;
                    // Rightmost column - no right margin
                    if (column == maxColumn)
                        factorRight = 0;
                    fe.Margin = new Thickness (ChildMargin.Left   * factorLeft,
                                               ChildMargin.Top    * factorTop,
                                               ChildMargin.Right  * factorRight,
                                               ChildMargin.Bottom * factorBottom);
                }
            }
        }

        // We change all children's margins in MeasureOverride, since this is called right before
        // the layouting takes place. I was first skeptical to do this here, because I thought changing
        // the margin will trigger a LayoutUpdate, which in turn would lead to an endless recursion,
        // but apparantly WPF takes care of this.

        protected override Size MeasureOverride(Size availableSize)
        {
            UpdateChildMargins();
            return base.MeasureOverride(availableSize);
        }


    }
}

You can download a complete project with an exhaustive test scenario here:

GridLayout test window

Download

Edit: I forgot to take the ColumnSpan and RowSpan into account in the first version. This lead to margins being too large when an element with a Column- or RowSpan was spanning to the rightmost or bottommost row or column. This has been fixed in version 1.1. Download link has been updated.

6 comments:

  1. Works easily enough, but the resulting grid cells are actually different sizes. (the edge cells expand to use the margin area.

    ReplyDelete
  2. Is it possible to reimplement this as some kind of a attached property? I don't see how, but it would be nice to be able to keep styles from Grid to work also on GridLayout.

    ReplyDelete
  3. What kind of styles are you referring to? Should not be much of a problem, since GridLayout derives from Grid.
    Thanks for the feedback!

    ReplyDelete
  4. You should move the UpdateChildMargins() call from property setter to the property changed event handler in property metadata. (the setter is not guaranteed to be called)

    ReplyDelete
    Replies
    1. You are totally right. Back then I didn't realize that those properties are merely a convention. Thanks for the feedback

      Delete