In .Net 3.0 we were given a great new printing framework based around XPS documents. This immediately opened up a world of vector based printing where you can print your WPF vector controls and have them appear as sharp as ever, or if printing to an XPS or PDF document, your print out will be preserved in its full vector glory. What makes this even better is that you as a developer don’t have to worry about any of this, you just send your data off to one of the many methods provided and the rest is done for you. There are of course some instances where you can’t print raw vector data out and need to handled rasterised data. This too is very simple and there are a few tricks you can use to make it even easier.

Using the PrintDialog

One of the first things you’ll want to do when it comes to printing is to choose a printer. There are a few different ways of enumerating printers visible to a machine and the method that is best for you will depend on the approach you take to printing in your application. The first method and perhaps the simplest is the good old PrintDialog class defined in the System.Windows.Controls namespace (PresentationFramework.dll).

The PrintDialog object gives us a handy, pre-built dialog for choosing and customising a printer and page setup. The dialog can then be used to send your job to the selected printer with very little coding required (of course you’ll still need to code the generation of the content to be printed). Below is a very simple method that creates a new instance of a PrintDialog and displays it. The OnShowPrintDialogButtonClick method is set as the click event handler in the Window’s XAML. Those of you familiar with dialogs in .Net will be familiar with this. The result of the call to ShowDialog() will give us a Nullable<Boolean> which can be used to determine whether clicked the ‘Ok’ button or not (and the reason using the explicit quality operator).

private void OnShowPrintDialogButtonClick(object sender, EventArgs e)
{
PrintDialog printDialog = new PrintDialog();
if (printDialog.ShowDialog() == false)
return;

// ..
}


Here is the print dialog in all its glory:

PrintDialog

It’s not much to look at but in just a few lines of code you have a complete list of available printers along with access to ceach device’s configuration settings as well as a few other treats. All of the printer and page setup data can be accessed through the dialog’s PrintTicket property which returns a PrintTicket object, defined in the System.Printing namespace (ReachFramework.dll). In a nutshell the print ticket details the settings and configuration for the print job as defined by the user from the print dialog, namely paper size, orientation etc. This print ticket will be used a lot when generating content to be printed.

Finding Available Print Queues

The PrintDialog isn’t always going to be suited to your needs, if for example you’re creating a rich print preview control a la Microsoft Word 2010 etc. For this you’ll need to provide configuration options for all the features you’ll want to support. The first step in this process is to get a list of available printers, which we do so through a PrintServer defined in the System.Printing namespace (System.Printing.dll). The PrintServer object is quite powerful and can be used for myriad print queue related activities, but for now all we need is a list of PrintQueue objects known to the print server. The code snippet below demonstrates the retrieval of a collection of printers (print queues).

private IEnumerable GetPrintQueues()
{
PrintServer printServer = new PrintServer();

PrintQueueCollection printQueues
= printServer.GetPrintQueues(new[]
{
EnumeratedPrintQueueTypes.Local,
EnumeratedPrintQueueTypes.Connections
});

return printQueues;
}

There are several overloads for the GetPrintQueues() method, the one you use will depend entirely on your situation. Here we use a method that allows us to pass in EnumeratedPrintQueueTypes values that ensure we get both local and network printers. You can take the collection of print queues and present them in the UI somehow allowing the user to select their desired printer. Like the PrintDialog, a PrintQueue also exposes a print ticket object, UserPrintTicket and DefaultPrintTicket, allowing you to access and modify printer and page settings, something you will need later when you come to provide configuration options such as selected page size and orientation etc.

Finding the User’s Default Print Queue

A nice little touch we can add here is to discover the user’s default printer and use that as the default in the app. Using the LocalPrintServer class’ static method GetDefaultPrintQueue, it’s easy to find.

private PrintQueue GetDefaultPrintQueue()
{
return LocalPrintServer.GetDefaultPrintQueue();
}

Using a PrintTicket

Now that you have a list of printers and the local default printer, the next step is to allow the user to change aspects of the active PrintTicket object. A print ticket is a collection of properties defining features of the print job. These include settings such as page orientation, page size etc. Many of the properties won’t be of interest to you and can safely be ignored. We’ll look at two properties here: page orientation (PageOrientation) and page size (PageMediaSize).

To get a print ticket you can either create one or use an existing one. The easiest way to get a print ticket object is through the UserPrintTicket property (or  DefaultPrintTicket property if the former is null) of the active PrintQueue. In some rare instances, reading either of these properties may result in a PrintSystemException (System.Printing namespace, ReachFramework.dll) being thrown when the printer driver doesn’t provide valid values. In this instance just create a new PrintTicket object and use that. Print tickets are used again a bit later on, when it comes to sending data to the printer, something we’ll cover in part 2.

Measuring Capability with PrintCapabilities

When dealing with settings in a print ticket, you first need to know what the target print queue is capable of. There’s no point showing options for duplexing and sending those commands if the target printer doesn’t support duplexing in the first place. To gain a heads-up on the target printer’s capabilities, there exist a PrintCapabilities class in the System.Printing namespace (Reachframework.dll). This is a sealed class with read-only properties defining the features supported by a given print queue. A PrintCapabilities object can now be used to remove features which are not supported.

var pageMediaSizes
= pc.PageMediaSizeCapability.OrderBy(
i => i.PageMediaSizeName).Select(
i => { return i.PageMediaSizeName.ToString(); }).ToList();

Putting it all together

I’ve created a simple demo app that puts these concepts together giving a practical example. The app comprises of a window with a few simple controls with a view model that defines the properties and methods described above. There’s a huge amount going on here, but hopefully it gives a good introduction to some of the common classes you’ll see when dealing with printing. The following class diagram below gives an overview of the app.

Here’s a preview of the app running.

Download the .Net 4, Visual Studio 2010 source for this application.

Next Steps

In the next part I’ll look at actually sending something to a print queue and look at the different approaches you can take to this.

As usual there is a wealth of information on the web on the topic of printing, although I found most of it to be quite disparate and specialised with very few complete examples and gotchas. In this series of posts I intend to cover as many aspects of printing as possible to try and give a better understanding and concrete examples, as a kind of map through the printing underworld. To this end, this series of posts will spare the detail in favour of providing a more general end-to-end look at printing with links to greater detail for those that are interested.

In part 1 I will try to give a brief overview of printing in WPF and get you started with some code for getting hold of a list of local printers and what you can do with that information.

The biggest challenge was the lack of the Media3D namespace. This prompted me to start building up a library of classes that aren’t included in Silverlight. So far I have created a Point3 (Point3D), Vector3 (Vector3D) and Quaternion (Quaternion). They are all basic implementations at the moment and contain just enough functionality to allow me to create the sample.

To overcome the lack of Viewport2DVisual3D, I calculate the scale for each child control based on it’s depth in the scene. This is a bit of a hack rather than a proper perspective correct transformation as I didn’t have the time to spend creating a camera implementation and setting everything up properly. Instead I make do with a camera focal length and combine that with the z value of each object to calculate how big it should appear on the screen, otherwise you wouldn’t be able to tell which controls are further away from the screen. Using a ScaleTransform ensures that the control appears correctly, but with a sense of depth.

Z-ordering is also taken care of, ensuring items deeper in to the scene appear underneath items which are closer to the screen. There are also a few little extras in there such as being able to animate the rotation of the ellipse, which when played around with can create some awesome effects.

The screenshot below shows the app running in full swing. Animation is enabled and a very small focal length is used, making the objects close to the camera appear much larger than those further back. There were around 200 buttons in the control at the time and it coped really well.

The Idea

The idea of this project is to re-create the WPF Elliptical Layout Control in Silverlight 2.0, giving me a chance to get my hands dirty with Silverlight and to discover what really is the difference between Silverlight and WPF.

After copying and pasting my code in to a new Silverlight project I quickly noticed that my XAML would need a bit of attention, which is when I realised the ‘ElementName’ markup extension used in bindings is not included. I also used this as a chance to add a quick example of animating the rotation of the layout ellipse, as a carosuel isn’t much fun if it doesn’t go around by itself!

The Theory

The lack of ‘ElementName’ is easy to get around by creating a BindingHelper, a well documented topic. Something which took me by suprise was the lack of FrameworkPropertyMetadata which was being used in almost all of my dependency properties. This allowed me to use the FrameworkPropertyMetadataOptions.AffectsArrange value when registering the dependency property, forcing an update of the control when the value of the property changed. To work around this I defined a PropertyChangedCallback method which then goes on to mark the control as needing an update by calling InvalidateMeasure and InvalidateArrange methods. This is defined for any dependency property that will invalidate the control’s state when its value changes and defined in each property’s PropertyMetaData.

private static void EllipseDefinitionPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
    EllipseLayoutPanel3D ep = d as EllipseLayoutPanel3D;

    if (d != null)
    {
        ep.InvalidateMeasure();
        ep.InvalidateArrange();
    }
}

Another suprise was the lack of a ClipToBounds property, usually found on UIElement. This property is used to determine whether its content can be rendered outside of its bounds (e.g. control with a negative margin in a Canvas), or whether clipping should occur. You can still achieve the same thing in Silverlight, but you have to do a little bit more work. Instead of ClipToBounds we have the UIElement.Clip property of type Geometry. As our control is a plain old rectangle, we just need to create a RectangleGeometry with a Rect which defines the bounds of the control, but because our control can take any size, we need to make sure we update the clip bounds to match.

Getting notified when the width or the height of the control changes is very simple, all we need to do is add a handler to the FrameworkElement.SizeChanged event, in the contrsuctor, and update the Clip property like so:

private void EllipseLayoutPanel3D_SizeChanged(object sender, SizeChangedEventArgs e)
{
    RectangleGeometry rg = new RectangleGeometry();
    rg.Rect = new Rect(0d, 0d, e.NewSize.Width, e.NewSize.Height);
    Clip = rg;
}

The really interesting part of this implementation was getting around the fact that we have no 3D support in Silverlight. In the WPF version of the control I was able to make use of the various 3D controls to do all of the work when it comes to making things appear as if they are sat in a 3-dimensional space. In Silverlight though we do not have this luxury so we have to come up with a way of achieving the same thing. The obvious choice is to setup a 3D pipeline and camera system that we can use to properly calculate the position and scaling of objects as they move toward and away from the screen. The other option is to ignore the camera and take a short-cut for calculating the approximate scale of objects based on their depth.

I decided to take the second option as it’s much quicker and far easier. The problem we are trying to solve is how to determine a scale factor that should be applied to an object such that it appears at a perspectively correct size, i.e. the further in to the scene it is located, the smaller it appears on the screen. Without having a full camera and 3D projection pipeline, I calculate the scale of the object using an approach based on Thales’ Theorem (there’s a great explanation here). This takes in to account the z value (depth) of an object and the focal length for an imaginary camera to calculate the scale of an object. Easy! There is an additonal check in my code which takes a -ve scale and adjusts it so as to avoid any strange rendering behavior. Here’s a look at the code which calculates the scale:

double scale = (-FocalLength / (-FocalLength + rotatedPoint.Z));

if (scale < 0d)
{
    scale = Math.Abs(scale) / 100d;
}

When creating the ScaleTransform, and TranslateTransform, we have to take in to account the position of the layout ellipse to ensure that each child control appears in the correct position and with the correct scale. This is as simple as adding in the position of the layout ellipse’s origin to the control’s position when defining our transforms.

TranslateTransform translate = new TranslateTransform();
translate.X = (rotatedPoint.X) + EllipseCentreX;
translate.Y = (rotatedPoint.Y) + EllipseCentreY;
...
ScaleTransform scaleTransform = new ScaleTransform();
scaleTransform.CenterX = rotatedPoint.X + EllipseCentreX;
scaleTransform.CenterY = rotatedPoint.Y + EllipseCentreY;
scaleTransform.ScaleX = scale;
scaleTransform.ScaleY = scale;

On the topic of transformations, I created a method for asserting a Transform for a UIElement, just like the AssertTransform3D method in the WPF version of the control. The method looks at the RenderTransform property of the given UIElement and if the value is a Transform it is added in to a new TransformGroup which is then set as the value of the RenderTransform property. This TransformGroup is then inspected to see if it contains a Transform matching the type of the generic parameter T. If a match is found, the existing value is replaced with the new value (with the exception of when the new value is a null reference), otherwise the new transform is added to the TransformGroup.

The last thing we have to take care of is the z ordering of each item. Because we are manipulating 2D objects in a 2D space to appear 3D, they are all painted on the same surface. This is important because the order in which the controls are rendered will have an effect on their perceived depth. If one object appears to obscure another object, that object must be closer to the viewer than the object it is obscuring. If in your scene a control that is meant to be deep in to the scene is rendered on top of a control which is meant to be much closer to the screen, the perception of depth will be lost. This was taken care of for us in the Viewport3D control, but not this time. Luckily we can use the Canvas.ZIndexProperty attached property to set the z-index of a particular control. The lower the value, the higher the control appears in the rendering order, i.e. it will be rendered earlier.

The ZIndex property is an int, so we round the z value of the control’s position and use that as the z-index of the control.

Canvas.SetZIndex(child, (int)Math.Round(rotatedPoint.Z));

Animating the layout ellipse’s orientation was easily achieved using a Timer in the main Page hosting the ellipse control, with a period equivalent to 60 frames per second. In the example this value is hard-coded but easy enough to make variable. Each time the timer callback is fired, it updates the value of the rotation sliders by an amount goverened by the speed slider, slidSpeed. Plain and simple.

private Timer animationTimer;

private void tbtnAnimate_Click(object sender, RoutedEventArgs e)
{
    if (tbtnAnimate.IsChecked == true)
    {
        //Start up an animation, running @ 16fps
        animationTimer = new Timer(AnimationTimer_Callback, null, 0, 16);
    }
    else if (animationTimer != null)
    {
        //We're done with animation for now.
        animationTimer.Dispose();
    }
}

private void AnimationTimer_Callback(object state)
{
    Dispatcher.BeginInvoke(Update);
}

private void Update()
{
    double speed = slidSpeed.Value / 100d;

    //For each slider, if the value is off the scale, wrap it back around to 0.
    slidEllipseRotationX.Value = slidEllipseRotationX.Value + 1d > slidEllipseRotationX.Maximum ? 0d : slidEllipseRotationX.Value + speed;
    slidEllipseRotationY.Value = slidEllipseRotationY.Value + 1d > slidEllipseRotationY.Maximum ? 0d : slidEllipseRotationY.Value + speed;
    slidEllipseRotationZ.Value = slidEllipseRotationZ.Value + 1d > slidEllipseRotationZ.Maximum ? 0d : slidEllipseRotationZ.Value + speed;
}

The Solution

Here I present a simple demonstration of the above in the attached solution. The solution contains a simple Page which hosts the custom 3D ellipse layout control. The ellipse layout control is included in the EllipiseLayoutPanel3D class and adds several dependency properties and a few methods to the Panel class. The Missing3D library is included as a dll at the moment, until I get a chance to fix it up. By all means check it out in Reflector, although there’s not much to see there yet.

EllipseLayoutPanel3D Class Diagram

The main Page also contains a few controls which allow you to interact with the layout control, allowing you to specify the size, location and pose of the layout control as well as add or remove items to the control. 

With the default orientation of the ellipse when the demo app first runs, changes made to the z-rotation slider will have the effect of spinning the controls around, in the fashion of a carousel.

The control also has a button which toggles animation of the layout ellipse’s orientation by adding a value to each rotation slider every 16 milliseconds, wrapping back around when the end of the slider is reached. Staggering the rotation sliders will give the best effect. The slider underneath the animation button is used to control how much each slider moves on each time period. The further right the slider is the faster the control spins.

To the right is a class diagram, showing the structure of the layout control. You can see it’s pretty simple and doesn’t need to add much to its FrameworkElement ancestor. 

Below is a screen-shot of the demo application in action. The values of the sliders are bound to the ellipse control’s dependency properties via the binding helper. There is a small amount of code behind to handle the locking of the height and width sliders, the add and remove buttons and the animation toggle button.

The code is available for download as a Visual Studio 2008 (SP1) solution (+Silverlight Tools), built against Silverlight 2.0, .Net 3.5 SP1.

Going Forwards

At present the level of user interaction with the control itself is fairly minimal, sure you can interact with items in the control, but there is little in terms of controlling the position of items in the list using the position of the mouse, or any concept of focusing on a particular item etc.

There are many optimizations to be made in the 3D aspects of the demo. The transformation of points and scale calculations could be performed in a pipeline, use of lookup tables for the outputs of the sin and cos functions etc.

I also decided to put a mention in for the book which I, along with two former colleagues, spent the last year writing, WPF Recipes in C# 2008: not for the money as we see very little out of it, but more so that people can get in touch with me in relation to its content.

We wrote the book in our evenings and weekends as an attempt to provide a collection of worked examples of various everyday problems, something we yearned for during our early days of using .Net 3.0. We hope it can help you avoid many of headaches we encountered on our WPF journey!

So be it questions, comments or corrections relating to the following chapters, get in touch.

• 1 – Building and Debugging WPF Applications
• 7 – Working with Text, Documents, and Printing
• 10 – Working with 3D Graphics
• 11 – Creating Animation

This example creates a new control which derives from FrameworkElement and is very similar to the implementation of the Viewport3D control. The new control overrides the measure and layout methods of FrameworkElement and positions the child controls (supplied as a collection of UIElements) according to the orientation of an imaginary 2D ellipse in 3D space.

It is assumed that the reader has some knowledge of custom controls, LINQ and 3D in WPF. The code provided is by no means an ideal implementation of the theory, it should be thought of more as a quick demonstration of the concept. And remember, in WPF there is almost always more than one way of doing the same thing, mine is just my take on the problem :0)

3D Elliptical Layout Panel Demo

The Idea

In the last example, we worked out how to lay out controls as if they were positioned at equal intervals around the edge of an imaginary ellipse. We now want to take that ellipse from a 2D space in to 3D, giving a sense of depth in the control.

Taking the existing layout logic in to the third dimension is fairly trivial if we remember that the positions we calculate for child controls in the 2D version could be thought of as being 3D points, all at the same distance away from the screen, i.e. z = 0. So by treating the points that are generated as 3D points, each with a value of zero for z (their depth), we can then rotate them to match the orientation of the layout ellipse (defined by an x, y and z axis rotation).

In short, we calculate the position of each child element as before, then rotate that point in 3D to match the rotation of a virtual layout ellipse. The layout ellipse will be configured as before, although this time we need to allow a way to configure its orientation. This is as simple as adding three new properties to allow an angle of rotation to be specified for each axis.

When it comes to the control, we need to look to 3D controls in WPF. We could create our own control which lays out its content, then projects it in to 3D and renders the control scaled such that they appear to be 3D, but that’s no fun and way too much effort! It would somehow be great if we could take advantage of the relatively new Viewport2DVisual3D control, effictively a 3D wrapper for a UIElement. It would also be great if the control exposed just a collection of UIElements, which internally it could wrap in a Viewport2DVisual3D control. 

Now we know what our items are doing, we need to think of a suitable container. If we look at the Viewport3D control, we can see that it wraps a Viewport3DVisual, exposing a collection of UIElement objects which it implicitly converts to Visual3D objects and adds to the inner Viewport3DVisual, as well as one or two other things. This is very similar to what we want to do, with the difference that we want to also define the layout mechanism too.

The Theory

I guess the first thing to tackle here is how to take the generated 2D position for each child control and turn that in to a 3D point, which we can use to create a TranslateTransform3D. For each point we generate on the ellipse, create a Point3D object using the x and y values of the 2D point and supply a z value of 0d (or whatever you want for the ellipse’s distance from the image plane).

Next, rotate the point around each axis using the rotations used to describe the layout ellipse’s orientation.  If you’re familiar with 3D graphics you may well be aware of Gimbal lock, something we want to avoid when we’re rotating the child control positions. To combat this, the rotation method will use quaternions. If you’ve not come across quaternions before, I recommend a quick look on Google as there are far better explanations out there than I can give. Also look at this site which gives the theory behind the math used to rotate a point.

private readonly static Vector3D UnitXAxis3D = new Vector3D(1d, 0d, 0d);
private readonly static Vector3D UnitYAxis3D = new Vector3D(0d, 1d, 0d);
private readonly static Vector3D UnitZAxis3D = new Vector3D(0d, 0d, 1d);

private static Point3D RotatePoint3D(Point3D point, double xRotation, double yRotation, double zRotation)
{
    Quaternion xQ = new Quaternion(UnitXAxis3D, xRotation);
    Quaternion yQ = new Quaternion(UnitYAxis3D, yRotation);
    Quaternion zQ = new Quaternion(UnitZAxis3D, zRotation);

    Quaternion xyzQ = xQ * yQ * zQ;
    Quaternion xyzQc = xyzQ;
    xyzQc.Conjugate();

    Quaternion pQ = new Quaternion(point.X, point.Y, point.Z, 0d);
    Quaternion q = xyzQ * pQ * xyzQc;
    Point3D rotatedPoint = new Point3D(q.X, q.Y, q.Z);

    return rotatedPoint;
 }

With the Point3D in hand, a TranslateTransform3D object can be created and applied to the child Viewport2DVisual3D control. This leads to the next question of how we are going to handle the wrapping of UIElements. With the addition of the Viewport2DVisual3D control, it is now possible to easily use a UIElement in a 3D scene, maintaining all the usual input handling, so no more messing around with visual brushes and models! You don’t get off too lightly though as you still need to provide the Viewport2DVisual3D with some information. This includes a Geometry3D object detailing a mesh that defines the surface which the inner Visual is to be rendered on; the material which should be used when rendering the Visual on the mesh and finally the Visual object itself.

To keep things simple, we can define a basic mesh containing a unit square. This mesh is going to be used as the geometry for each control surface, so we need a way of sizing it according to the dimensions of the control being rendered. This is again a trivial problem and is solved by creating a ScaleTransform3D object which scales the Viewport2DVisual3D control so that it is scaled by the dimensions of the inner Visual object, ignoring z. Nice!

The scale transform is created for each Viewport2DVisual3D control each time the MeasureOverride method is called. There is no particular reason to place this code here, other than it keeps the sizing logic separate from the layout logic, keeping things a bit better organised. The next code snippet is included to highlight the use of the OfType<T>() LINQ extension method, used on the Children property of the control’s inner Viewport3DVisual. This method returns an IEnumerable<T> object containing all the items in the collection with a type specified by T. Because we know that our Children collection contains a light somewhere within it, we want to skip over that when scaling the child objects.

protected override Size MeasureOverride(Size availableSize)
{
    //Iterate all the children of the inner viewport.
    foreach (Viewport2DVisual3D visualChild 
        in viewport3DVisual.Children.OfType<Viewport2DVisual3D>())
    {
        //Get the inner UIElement
        UIElement element = visualChild.Visual as UIElement;
        //Create a scale transform so that the control appears the right size
        ScaleTransform3D scaleTransform
            = new ScaleTransform3D(element.DesiredSize.Width, element.DesiredSize.Height, 0d);

        //Add the scale transform in to the Viewport2DVisual3D's transform group.
        AssertTransform3D<ScaleTransform3D>(scaleTransform, visualChild);
    }

    return availableSize;
}

The container that will hold all of these Viewport2DVisual3D controls will need to be a Viewport3DVisual. Again because we are dealing with 3D we need to define a few extra things for the Viewport3DVisual. The first is a Camera object which defines how controls displayed in the Viewport3DVisual appear to the viewer. The second is a Light object which defines an AmbientLight object used to provide a uniform white light in the 3D scene (otherwise everything would be dark and you’d see nothing more than a black screen).

To make the controls appear to be positioned within 3-dimensional space, we will use a PerspectiveCamera, meaning objects which are placed deeper in to the control (further from the screen) will appear smaller than those which are closer to the screen. All we need to do to configure the camera is tell it where it is and the direction it is looking. Because we are keeping things simple here, we’ll position our camera somewhere along the positive z-axis, and have it looking down the z-axis (towards the origin). This means our camera will be looking straight on at the objects placed within the control, with the layout ellipse’s origin at the origin of the scene.

The Solution

Here I present a simple demonstration of the above in the attached solution. The solution contains a simple Window which hosts the custom 3D ellipse layout control. The ellipse layout control is included in the ElliptiseLayout3DPanel class and adds several dependency properties and a few methods to the FrameworkElement class.

EllipticalLayoutPanel3D Class Diagram

The main window also contains a few controls which allow you to interact with the layout control, allowing you to specify the size, location and pose of the layout control as well as add or remove items to the control. There are also two buttons will moves the controls around the ellipse, one at a time. This is a bit of a jig and is as simple as removing an item from the top of the collection held in the control’s Children property and adding it to the end of the collection. The reverse is true for moving back through the items. The light sometimes gets caught up in this, so you may not see anything happen for a click or two when switching direction.

With the default orientation of the ellipse when the demo app first runs, changes made to the z-rotation slider will have the effect of spinning the controls around, in the fashion of a carousel. This could be used to animate the rotation items in the control.

To the right is a class diagram, showing the structure of the layout control. You can see it’s pretty simple and doesn’t need to add much to its FrameworkElement ancestor. 

Below is a screen-shot of the demo application in action. The values of the sliders are directly bound to the panel’s dependency properties, meaning the only code-behind is for the four button event handlers.

3D Elliptical Layout Panel Demo

The code is available for download as a Visual Studio 2008 (SP1) solution, built against .Net 3.5 SP1.

Going Forwards

The light source and other properties of the control are not configurable. You may want to expose the lights as a separate collection, or at least allow the colour to be altered.

The control will need some more work to enable it to be used in an ItemsPanelTemplate, so it won’t work out of the box.

You may want to add proper methods for controlling the order of items in the control, possibly animating this.

All and any comments / bugs / suggestions are welcomed!

This is a fully working, but a little rough, demonstration of creating your own control and performing custom layout logic.

The Idea

The problem we are trying to solve requires working out the location that a control should be positioned at within its containing panel, such that all of the controls are positioned as if they are placed along the edge of an invisible ellipse.

We can simpify the problem by modelling the edge of the ellipse as a long piece of string that we can straighten out in to a straight line and also assume that each point on the ellipse’s edge is at an angle one unit (degree or radian) greater than the last. This means that the angle to the location of the control around the edge of the ellipse is directly proportional to the distance that the control needs to be from the start of a straight line.

For the control itself I chose to create a new control that inherits System.Windows.Controls.Canvas. The reasoning for this is that Canvas provides everything that we need, meaning we only have to override how items are laid out and a few additional properties to configure the layout.

The Theory

Here we will approach the solution in two steps. The first of which will give us the spacing of the controls, which will allow us to go on and calculate the location of the control.

To calculate how far around the ellipse each control should be placed, we need to know the number of items we want to display and the length of the line we have to display them on. Simple! First, the amount of spacing (space) between each item (where count is the number of items, length is the length of the line) is calculated using:

There is one unknown in the above formula: the legth of the line; or more accurately, the circumference of the ellipse. It may come as a suprise to learn that there is no finite equation which will give the circumference of an ellipse. Don’t worry though, we don’t have to get our hands dirty with second degree integrals as some clever chaps have devised equations which will approximate the circumference. 

Several methods exist, each with varying degrees of accuracy. The most accurate of which is the second form of Ramanujan’s approximation (although the accuracy degrades for ellipses where the width is much greater than the height and vice versa) and is given by:

Where:

In code it looks like this:

private double CalculateEllipseCircumferenceRamanujan2(double a, double b)
{
    double h = Math.Pow(a - b, 2) / Math.Pow(a + b, 2);
    //pi (a + b) [ 1 + 3 h / (10 + (4 - 3 h)^1/2 ) ]            
    double result = Math.PI * (a + b) * (1 + 3 * h / (10 + Math.Pow((4 - 3 * h), 0.5)));
    return result;
}

Now each control’s distance from the start of the line can be calculated as:

Where ‘index’ is the 0-based index of the control in its parent collection, or some other value which indicates the ordering of elements. It is important to note that by using a 0-based index, our spacing allows space for one extra item which doesn’t actually exist. If we didn’t do this, the last item in the control would be placed on top of the first as they’d both occupy the same position when wrapped around the ellipse.

Given the offset of the control from the start of the line, we need to convert this in to an angle of rotation from the start point of the ellipse’s edge. As stated before, we can assume that each point on the ellipse’s edge directly relates to the distance from the start of the ellipse. So all we need to do is map our value on to a radian number range.

In code:

double theta = (Math.PI * 2) * ((i * itemSpacing) / layoutCirfumference);

We’re almost there! The last step is to now take that angle along with the characterisitcs of the ellipse and calculate a point for a given angle. Thankfully the parametric equations for a point on the edge of an ellipse are nice and simple:

In code:

private Point GetPointOnEllipse(double width, double height, Point origin, double theta)
{
    double x = origin.X + (width * Math.Cos(theta));
    double y = origin.Y + (height * Math.Sin(theta));
    return new Point(x, y);
}

Now if we use the above method for each child control, we will have a collection of evenly spaced points plotting the edge of the ellipse! Woo hoo. Note that when setting the location of a control, you will need to offset these values slightly such that the control is centred on the point, rather than having its top left corner at the point.

The last point of interest in the control’s code is the metadata used to define the characteristics of its dependency properties. Each dependency property registration specifies a FrameworkPropertyMetadata class which makes use of the value FrameworkPropertyMetadataOptions.AffectsArrange. In a nutshell, each time the the value of the property changes, the control’s ArrangeOverride is invoked, updating the layout of any child controls.

public static readonly DependencyProperty EllipseHeightProperty
            = DependencyProperty.Register("EllipseHeight", typeof(double), typeof(EllipticalLayoutPanel),
                                          new FrameworkPropertyMetadata(75d, FrameworkPropertyMetadataOptions.AffectsArrange));

So what’s so great about that? Well it means we don’t have to bother specifying PropertyChangedCallbacks and  then some internal update method, WPF does it for us! If you’re interested in learning more about dependency properties, check out MSDN or for some worked examples, look at my chapter on application development (chapter 1) in ‘WPF Recipes in C# 2008′.

The Solution

EllipticalLayoutPanel Class Diagram

Here I present a simple demonstration of the above in the attached solution. The solution contains a simple Window which hosts the custom ellipse layout control. The ellipse layout control is included in the EllipticalLayoutPanel class and adds several dependency properties and a few methods to the Canvas class.

The main window also contains a few controls which allow you to interact with the layout control, allowing you to specify the size and location of the control as well as add or remove items to the control.

To the right is a class diagram, showing the structure of the layout control. You can see it’s pretty simple and doesn’t need to add much to its Canvas ancestor. The dependency properties are there only for testing as really the dimensions of the ellipse should be automatically calculated using the available size of the control. If there is any desire for this, I could easily extend the solution to perform this, just give me a shout.

Below is a screenshot of the demo application in action. The values of the sliders are directly bound to the panel’s dependency properties, meaning the only code-behind is for the two button event handlers.

The demo in action

The code is available for download as a Visual Studio 2008 (SP1) solution, built against .Net 3.5 SP1.

All and any comments / bugs / suggestions are welcomed!

So a little about me. Well as the blog’s title suggests, I love to code! Presently I am working exclusively in .Net 3.5 and am an avid fan of WPF. I am currently working for SmithBayes where I have been working with .Net 3 (especially WPF) since the early CTP releases building a large decision making platform application.

The purpose of this blog is to be a place where I can share the knowledge in WPF I have gained over the years and get to know fellow .Net 3x fans.