One of the most important areas of thought you should give to your application is how the UIElements that are embedded in various panel-based constructs will react when the page(s), window(s), or parent UIElements are resized, maximized, scaled, or localized. We are talking not only about embedding UIElements inside each other but also embedding UIElements into your page construct.

Have you ever navigated to a website only to find that the menu items don’t line up properly or that an embedded image on the page has caused the text to move to a weird position? Most of the time that isn’t much of a problem, and you can live with it. But imagine if you wanted to read that information or had to interact with that site all day. Your rating of the site would be pretty low, regardless of how good the content is. This is why user experience is so important in a XAML-based application. The same sorts of issues can and do occur with WPF applications.

Why does positioning sometimes get messed up?

It comes down to the flexible layout system that WPF uses to place your controls in the correct position, regardless of the screen size, resolution, Z-order, and so on.

Although layout in WPF is extremely flexible in its approach, as with all things powerful, great responsibility is also present. Your responsibility is to ensure that the settings are correct and accurately reflect the environment that the controls(s) are being used in.

When you create a new Standard Project in Expression Blend, you will note that a Grid UIElement is used and named as the LayoutRoot, a child of a Window base element. Visual Studio also uses a Window as its parent container and provides a standard empty Grid as the base panel container.

Adding controls via drag and drop is simple enough in either environment. How these controls are shown in Blend, however, is not always how they will be interpreted in the Visual Studio design environment, and the resulting layout functionality can be impaired.

You will find this occurs sometimes when you switch between the two environments. Most of the time, you can repair the problem simply by looking at the column and row span requirements of the controls in question (see Figure 5.1).

Figure 5.1. UIElement span differences are apparent.

In Figure 5.1, the same Button element is used twice. Everything (including the properties) is identical in both the top and bottom buttons, with one slight change to the layout property on each. The top button has its Row Span set to 2 and Column Span set to 1, whereas the bottom button has its Row Span set to 1 and its Column Span set to 2. Although this is a simple example, it does demonstrate just how different your UIElements will appear if you are not careful about properties such as the margins and the spans.

You may be wondering why it is necessary to bring up such a simple issue, but you would be surprised by the number of times that you will miss this. This is especially true if you are embedding child UIElements in code only, because you will not get any visual verification until runtime.

You may also be using UIElements that have been built by other developers, XAML architects, or designers; and you may not understand the intended span logic used within the various embedded objects.

As a demonstration of how margins and size can cause you grief with embedded UIElements, use the following steps to create a small application that will display a red grid in the center, with a yellow rectangle embedded in it for visual effect and a block of text centered in the grid.

Even though this scenario may cause you a headache (which may not appear to be a good incentive to actually doing the following steps—you still should), it is very important that you understand how you may find yourself in the following situation so that, in your future design experiences, you can work around the same potential problems.

This example highlights how incorrect settings within the margins of the embedded UIElements can cause some ugly results. (Okay, it was always going to be ugly.) The point is, who knows how your application users will resize and move your application window(s)?

It’s important to be aware of this and not just go slapping controls all over the place, hoping that it will all work correctly when the application is launched, because 99.9% of the time, it won’t work how you wanted it to. Understanding how to set up controls properly will make the difference between a great user experience and a poor one.

So, how do you fix it?

You should define, within your application design specification, the minimum size that the application can run at. You will restrict the application Window from becoming so small that elements disappear, which is what currently happens.

You could modify the properties of the Window in the Properties panel to restrict the minimum Width and Height, so that, regardless of how your user changes the size of the parent Window, the elements will always show. However, in this example, you will fix it by modifying the properties of the Window in the code—after all, you can fix anything in code (you should always tell your boss this if you are a developer).

You should now be able to stretch your application both horizontally and vertically, and the child elements will continue to resize dynamically. You will note that the Window is now restricted to resizing below the initial startup Width and Height of the Window.

These sorts of issues will occur many times during your application development lifecycle, at least until such a time that all the people involved with the design and development are 100% accustomed to sizing controls and UIElements with layout properties instead of straight measurements and anchors. This is a strong claim to make, but I have witnessed it firsthand working with teams of designers (and developers) who are new to Blend.

When using the Grid (which is the most flexible layout panel and, therefore, quite often the most used), there are really three main Layout properties that you need to make sure are correct:

You may have previously added additional controls at runtime to an application by adding a control to the controls collection of the parent control (generally a form- or panel-based construct in .NET). You add XAML elements in much the same way to a parent UIElementCollection property, generically named as Children, for controls that inherit the Panel base class.

The generic Children property has an Add method that accepts a UIElement type. For example, the following code adds a Button UIElement to a Grid UIElement:

this.Grid1.Children.Add(myNewButton);

The Children property also has an Index accessor that returns a UIElement:

Button myButtonReference = (Button) this.Grid1.Children[0];

Those controls that inherit from ContentControl (Button, CheckBox, Frame, Label, and so on) have a Content property that accepts a single object as a child and is assigned like the following:

myNewButton.Content = myNewGrid;

(See Chapter 9, “Using the Blend Asset Library,” for a detailed look at the ContentControl.)

The same traditional rules apply when you want to add elements to subelements of a UIElement. As long as the UIElements are publicly accessible, you can call the Children.Add method and pop an element in there. Some XAML UIElements use an ItemCollection property called Items, although these are generally used for elements that are designed to take multiple child elements as part of the design functionality.

A TreeView is an example UIElement that has an ItemCollection. It takes an object of type object to display as a node in the tree. This object (of type TreeViewItem) can then contain child elements in both the HeaderedItemsControl collection and the ItemsCollection collection, which could be another TreeViewItem, UIElement, or even another TreeView control element.

You may find that some developers add child elements directly to the XAML. Sometimes this occurs automatically when you develop a control element with a visual helper such as Blend and when the developer or designer uses the drag-and-drop method to create the UIElement tree. The benefit to this is always that the controls can be visualized during design time. You also have access to the element properties and events to respond to, as well as manipulate in Timeline animation options.

Adding additional elements to a parent in design time XAML is simple but you will find that a number of controls have larger initialization requirements then others and working in XAML can be cumbersome for some. I advise against this if you suffer from nose bleeds.

The following code shows a button as a child UIElement of a parent grid:

    <Grid Name="ParentGrid">
        <Button Height="23" Margin="233.8,164.8,301.6,0"
         Name="ChildButton" VerticalAlignment="Top">Child Button</Button>
    </Grid>

You probably wouldn’t type this yourself, because you can just drop the control straight onto the grid in the design time editor, but sometimes you may need to “hand crank” the XAML in order to get your UIElements into the parent. (See Chapter 4, “XAML for Beginners,” for more information on XAML structures.)

The TreeView control element was mentioned previously, so the following example runs through using a TreeView control to display various information and UIElements.

First make a simple TreeView display page.

If you are a developer, you are probably thinking that we are going to create a class that inherits from TreeViewItem as we would do normally. In this case, however, we are concentrating on UIElements, so we are going to create two custom controls:

Previously, you may have been limited to the types of information you could show in a node within a TreeView control in .NET. If you had a little time on your hands and you didn’t have a project manager wanting a build every six hours, you could add some other features to your nodes. Unfortunately, I’ve never found an easier way to add other controls, such as a progress bar, another button, or a sub TreeView control, to the node.

You can use a third-party GridView control to show hierarchical data, because it allows you to contain embedded grids within grids. Obviously, however, it will always be primarily determined by the amount and type of information that needs to be shown.

The following steps begin your application by creating a base of functionality within your Window. You will then move on to creating a User Control where the TreeView control functionality will be added.

The XAML in Listing 5.3 allows you to verify your markup created in the previous steps.

    <Grid x:Name="LayoutRoot" Background="{x:Null}">
        <Border HorizontalAlignment="Stretch" VerticalAlignment="Stretch"
Width="Auto" Height="Auto" Padding="5,5,5,5">
            <Grid>
                <Rectangle HorizontalAlignment="Stretch"
VerticalAlignment="Stretch" Width="Auto" Height="30" Fill="{x:Null}"
Stroke="#FF02378E" RadiusX="15" RadiusY="15"/>
               <Viewbox HorizontalAlignment="Stretch" VerticalAlignment="Stretch"
Width="Auto" Height="20" Margin="10,0,10,0">
                    <Label Content="" x:Name="labItemInsertedValue"/>
                </Viewbox>
            </Grid>
        </Border>
    </Grid>

Now you need to add a public method to the control, allowing you to set the Content property of the Label control with a string value, when the TreeHeader control is used.

Open the Project panel and within the Files category, locate the TreeHeader.xaml file. Expand the node to reveal the code behind page for the control as shown in Figure 5.6.

Figure 5.6. The selected TreeHeader code behind file.

In the following steps, you create the next control that will serve as the TreeViewItem Items content.

Figure 5.8 shows the ColumnDefinition Collection Editor with three items added to the collection. You will notice that the items have a Width property set to 1 *. If you quickly look at the XAML for the Grid element, you will see that the Grid Column Definitions are declared but are completely empty of property attributes. This will ensure that the distances are equal between all the Collection Items (representing the Columns).

Figure 5.8. The ColumnDefinition Collection Editor.

You are about to add a Click Event handler for the Button control you added to the UserControl. This is the reason that you just saved and built the application to ensure that you have access to all the controls from the Visual Studio environment.

public void SetLabelValue(String ValueToShow)
        {
            this.labChildName.Content = ValueToShow;
        }

Select to save the project in Visual Studio and then “Build” the solution choosing the Build Solution menu item as you did previously. You can now return to Blend.

Listing 5.8 shows the XAML for the control should you have any issues with the previous steps.

Figure 5.9. The TreeItem control is ready to go.

    <Grid x:Name="LayoutRoot" Background="{x:Null}">
        <Grid HorizontalAlignment="Stretch" VerticalAlignment="Stretch"
Width="Auto" Height="Auto">
            <Grid.ColumnDefinitions>
                <ColumnDefinition/>
                <ColumnDefinition/>
                <ColumnDefinition/>
            </Grid.ColumnDefinitions>
            <Label HorizontalAlignment="Stretch" x:Name="labChildName" Verti-
calAlignment="Stretch" Content=""/>
            <ProgressBar HorizontalAlignment="Stretch" Margin="10,0,10,0"
x:Name="pbRunner" VerticalAlignment="Center" Width="Auto" Height="10" Grid.Col-
umn="1" IsIndeterminate="False"/>
            <Button HorizontalAlignment="Stretch" Margin="10,0,10,0" x:Name="cmdIn-
determinate" VerticalAlignment="Center" Content="Not Determinate" Grid.Column="2"
Click="cmdIndeterminate_Click"/>
        </Grid>
    </Grid>

You should be ready to continue on with the TreeView sample application that you first started with, using the two controls you just built to display the required information. You added the Button control and ProgressBar controls to the TreeItem control to show that the control can and will maintain its own functionality, independent of its parent.

The majority of the work remaining is carried out in Visual Studio, so as per good working practices, save the project in Blend, and then Build it from the Project menu before continuing.

Listing 5.9 shows that you are looking at the Number of Child Items to add value, which is located in txtItemCount, and basing your additions on it.

private void btnAddChild_Click(object sender, RoutedEventArgs e)
        {

            int LoopCount = Convert.ToInt32(this.txtItemCount.Text);

            //Make sure we have at least 1 to add
            if(LoopCount == 0)
            {
                this.txtItemCount.Text = "1";
                LoopCount = 1;
            }

            //Create a new TreeItem to add to the control
            TreeViewItem TempItem = new TreeViewItem();

            //Create a single Header that will show the time it was created
            TreeHeader MyHeader = new TreeHeader();
            MyHeader.SetLabelContent("Item added: " + DateTime.Now.ToLongDateString
() + " " + DateTime.Now.ToLongTimeString());
            MyHeader.MinWidth = 300;

            //Add the header to the control before we start to add child items
            TempItem.Header = MyHeader;

            //Add child elements
            for (int LoopValue = 0; LoopValue < LoopCount ; LoopValue++)
            {
                //Create and add an item to our TreeViewItem
                TreeItem TempTreeItem = new TreeItem();
                TempTreeItem.SetLabelValue(Convert.ToString(LoopValue + 1) + " of "
+ LoopCount.ToString() + " children");
                TempTreeItem.MinWidth = 500;
                TempItem.Items.Add(TempTreeItem);

                TempTreeItem = null;
            }

            //Add our item to the TreeView control. If an item or header is selected,
            //add our item as a child of it
            if (this.tvMain.SelectedItem  != null)
            {
                if (this.tvMain.SelectedItem is TreeItem)
                {
                    TreeViewItem SelectedItem = (this.tvMain.SelectedItem as
TreeItem).Parent as TreeViewItem ;
                    this.tvMain.BeginInit();
                    SelectedItem.Items.Add(TempItem);
                    this.tvMain.EndInit();
                }
                else if (this.tvMain.SelectedItem is TreeHeader )
                {
                    TreeViewItem SelectedItem = (this.tvMain.SelectedItem as Tree-
Header).Parent as TreeViewItem;
                    this.tvMain.BeginInit();
                    SelectedItem.Items.Add(TempItem);
                    this.tvMain.EndInit();
                }
                else if (this.tvMain.SelectedItem is TreeViewItem )
                {
                    TreeViewItem SelectedItem = this.tvMain.SelectedItem as Tree-
ViewItem;
                    this.tvMain.BeginInit();
                    SelectedItem.Items.Add(TempItem);
                    this.tvMain.EndInit();
                }

            }
            else
            {
                this.tvMain.BeginInit();
                this.tvMain.Items.Add(TempItem);
                this.tvMain.EndInit();
            }
        }

If you study the previous Add methods, you will see how you must now manage child objects and their header and child items compared with just child items in .NET TreeView controls.

Before you send emails telling me that I should have broken the code in Listing 5.9 into multiple methods, know that I was thinking that some of you reading this book may not have used any code previously. The concept of methods (functions) is covered in Chapter 10, “Visual Studio: C# Primer.” By all means, refactor away if it makes you feel better!

Now add the code to your .NET code behind page, return to Blend, and build and test your application. Your results should be similar to Figure 5.10.

Figure 5.10. The finished product.

This is a simple sample, but you are probably already thinking about the possibilities this dimensional embedding provides developers. It also lets designers get away with some pretty amazing concepts.

Before you finish with embedding controls, you may be wondering why you had to add a Grid in places where you would normally just add multiple control elements as children. Cast your mind back, and you will remember that you had to do this when building the TreeHeader control when you added a Border control. The only Child element of the Border is a Grid. Everything else under it is a child of the Grid.

The explanation for this pertains to a special control that handles content, aptly called a ContentControl.