/dev/mobile

The first time I heard that the .NET Micro Framework’s GUI framework was Windows Presentation Foundation (WPF) I was excited but wanted to know more. How could such a “big” framework be compressed for use on such a small device, with little to no OS for support?

This blog entry discusses the structure of simple WPF applications written for the .NET Micro Framework and outlines some of the differences when compared against the WPF framework found on the desktop.

The WPF implementation found within the .NET Micro Framework shares many of the same underlying structures and concepts as the desktop version of WPF, but the implementation and capabilities are completely different. For example there is no declarative markup language (XAML), no data binding, no visual form designer and the namespaces are slightly different.

Getting Started
To get started create a new .NET Micro Framework Console application from within Visual Studio 2005 and delete the contents of Program.cs. We would typically use the “Windows Application” template, but since we want to learn the purpose of the code generated by that template we will code it all from scratch.

We also need to add a couple of additional references to our Project in order for the compiler to find the WPF related classes:

• Microsoft.SPOT.TinyCore
• Microsoft.SPOT.Graphics

Creating a window
A window is represented by the Microsoft.SPOT.Presentation.Window class. Typically a subclass of this class will be produced to encapsulate as much window specific logic as possible for each type of window within our application. Since we don’t have a Visual Form designer or XAML we must hand code this in C# directly.

Our main window could be represented as follows:

using Microsoft.SPOT.Presentation;
using Microsoft.SPOT.Presentation.Media;
 
public class MainWindow : Window
{
  public MainWindow() 
  { 
    // Make the window the same size as the LCD screen
    this.Width = SystemMetrics.ScreenWidth;
    this.Height = SystemMetrics.ScreenHeight;
 
    // Make the window have a red background
    this.Background = new SolidColorBrush((Color)0x0000FF);
  }
}

The constructor provides an ideal place to configure the look and feel of our window. In this example we configure the initial width and height of our window to be the same size as the LCD screen found on our device. We also give it a solid red background fill.

Creating an Application
A WPF application is represented by the Microsoft.SPOT.Application class. This class manages the display of windows and routes events from the hardware to the active window’s controls etc.

To display our main window on the screen we must create an instance of our application and call it’s Run method, passing in the main window. Like standard desktop .NET applications, the main entry point of an application is its static Main method and this provides an ideal place to perform this initialisation step as shown below:

using System; 
using Microsoft.SPOT; 
 
public class Program : Application 
{
  // This is the method the .NET Micro Framework
  // will call when our application starts running 
  public static void Main() 
  { 
    // Create an instance of the Application
    // and our main Window class
    Application myApplication = new Program(); 
    Window myWindow = new MainWindow(); 
 
    // Ask the application to display the
    // initial window, and don't return until
    // it is closed.
    myApplication.Run(myWindow);
  }
}

When you run this application you should see a solid red window covering the entire screen. It’s pretty boring! Since there is no way (presently) to close this window the call to myApplication.Run will never return.

Adding content
A window can hold a single control, this is because it derives from ContentControl. This class provides a Child property to specify the control which should be displayed within the client area of the window.

Most of the standard controls can be found within the Microsoft.SPOT.Presentation.Controls namespace. The two we will cover in this blog posting are the Text and Image controls.

Displaying Text

To place a string of text on a window we can use the following code snippet at the end of our Window’s constructor:

Font font = Resources.GetFont(Resources.FontResources.small);
this.Child = new Text(font, "Hello World!");

This code refers to a font called “small”. The .NET Micro Framework by default has no fonts, so we must include this font resource as an embedded resource within our application. We do this by following these steps:

1. Open Resources.resx within the designer
2. Open the Files section and select to add an existing file
3. Navigate to the C:\Program Files\Microsoft .Net Micro Framework\v2.0.2036\Fonts\ directory and select “small.tinyfnt”.

By default there are only a couple of fonts to choose from. With Service Pack 1 of the .NET Micro Framework there is also a conversion utility which allows you to convert any TrueType font you may have into the required format.

Displaying an Image

To place an image on a window we make use of the Image control. The easiest way is to simply pass the bitmap we want to display in as a constructor parameter as shown in the below code snippet:

Bitmap bmp = Resources.GetBitmap(Resources.BitmapResources.sample);
Image img = new Image(bmp);
this.Child = img;

We could use the bitmap drawing techniques discussed last time to dynamically create a bitmap to display, or we could embedded an image into our executable. To embedded an image such as the “sample” image in the above example, we follow a similar process to adding a font to our resources.resx file, only this time we select the “Image” section instead of the “Files” section.

By default the image or text will be rendered in the top left corner of the area provided by the window. By changing the HorizontalAlignment and VerticalAlignment properties we can modify this to move the image into the center of the area given to the control. For example to center the image in the previous example we could add the following two lines of code to the Window’s constructor:

img.VerticalAlignment = VerticalAlignment.Center; 
img.HorizontalAlignment = HorizontalAlignment.Center;

Sample Application

[Download wpf-hello-world.zip - 6.7 KB]

A small sample application is available for download. This application demonstrates the techniques outlined within this blog entry and displays the classic “Hello World” message to the user.

The next post on the .NET Micro Framework will discuss how to add more than one control to a window and how to control the size and location of these controls. After that posting we will finally be at the stage where we are ready to discuss how to generate and respond to keyboard or button press events. This will also enable us to discuss how to create multiple windows and close them etc.

This blog entry is a lead in to a new series of articles about developing GUIs with the .NET Micro Framework.

A good place to start when learning a new GUI framework is to learn how to draw simple graphics. This blog entry discusses how to draw simple graphics with the .NET Micro Framework.

Creating a Bitmap
The Microsoft.SPOT namespace contains a Bitmap class which represents a bitmap image. To create a bitmap the same size as your physical screen you could use a code snippet such as the following:

using Microsoft.SPOT;
using Microsoft.SPOT.Presentation;
 
Bitmap bmp = new Bitmap(SystemMetrics.ScreenWidth,
     SystemMetrics.ScreenHeight);

Once you have a bitmap you can draw on it by using the various instance methods of the Bitmap class. When your drawing is completed, you need to copy the bitmap to the LCD screen in order for it to become visible. The framework provides a Flush() method to perform this task. Calling Flush() on your bitmap will copy the bitmap data to the LCD screen.

Bitmap bmp = new Bitmap(SystemMetrics.ScreenWidth,
     SystemMetrics.ScreenHeight);
// ... do drawing stuff here ...
bmp.Flush(); // copy bitmap to LCD

It is important to note that to use the Flush() method your bitmap must be exactly the same size as the LCD display. Otherwise the flush will simply not work, even though no exception or debug diagnostic will indicate a problem while debugging. This is a common trend with many of the .NET Micro Framework Base Class Library methods.

Representing Colours
A colour is represented by the Color enumeration found within the Microsoft.SPOT.Presentation.Media namespace.

This enumeration only has the values Black and White pre-defined. For example to specify the colour White you could use a code snippet such as the following:

using Microsoft.SPOT.Presentation.Media;
Color white = Color.White;

It is possible to specify other colours by specifying the red, green and blue intensity values that make up the desired colour. To do this you use a static method within the ColorUtility class called ColorFromRGB as shown below:

using Microsoft.SPOT.Presentation.Media;
// Specify full intensity red
Color red = ColorUtility.ColorFromRGB(255, 0, 0);

The parameters passed to ColorFromRGB are the Red, Green and Blue components of the desired colour. These values are all bytes which range from 0 to 255 (full brightness).

ColorFromRGB basically encapsulates some simple bit shifts and a typecast. Internally the .NET Micro Framework represents colours as 3 8bit fields packed into a single 32bit unsigned integer. Instead of using the ColorFromRGB method we can perform a manual typecast between a suitable number and the Color enumeration as follows:

using Microsoft.SPOT.Presentation.Media;
//                 0xBBGGRR
Color red = (Color)0x0000FF;

The format when the value is expressed in hexadecimal is 0xBBGGRR, i.e. 8 bits red (R), 8 bits green (G), followed by 8 bits blue (B). So the above example creates a red colour with full intensity.

Drawing Shapes
The bitmap class has numerous methods available for drawing the outlines of basic shapes such as lines, rectangles and ellipses.

Drawing lines:

// Draw a red line 10 pixels thick
// between (x=20, y=30) and (x=40, y=50).
bmp.DrawLine(red, // colour
     10,  // thickness
     20,  // x0
     30,  // y0
     40,  // x1
     50) // y1;

A line is specified by providing the colour, thickness and start and end co-ordinates of the line. The current implementation of the .NET Micro Framework base class library appears to ignore the thickness parameter, all lines are drawn 1 pixel wide.

Drawing rectangles:

// Draw a rectangle which is 40 pixels
// wide and 50 pixels high. The top left
// corner is at (x=20, y=30). The outline is
// 10 pixels wide in red. 
bmp.DrawRectangle(red, // outline colour
     10, // outline thickness
     20, // x
     30, // y
     40, // width
     50, // height
     0,  // xCornerRadius,
     0,  // yCornerRadius,
     0, 0, 0, 0, 0, 0, 0);

Drawing a rectangle involves using the DrawRectangle method which potentially requires setting a number of parameters. We will initially ignore the last 7 parameters and set them to zero (we will discuss them later when we cover gradient fills.).

If the outline thickness is greater than 1 then the co-ordinates specified indicate the center of the outline, i.e. half the outline is drawn on each side.

Rectangles with rounded corners can be specified by setting the xCornerRadius and yCornerRadius parameters to the desired radius. If the radius is larger than zero the outline thickness is ignored by the current version of the BCL and the framework reverts to drawing a 1 pixel thick outline.

Drawing Ellipses:

// Draw an ellipse centred at (x=30, y=60)
// with a radius of 10 on the x axis and
// 20 on the y axis.
bmp.DrawEllipse(red, // colour
     30,  // x
     60,  // y
     10,  // x radius
     20); // y radius

The simplest way to draw an ellipse is to specify the colour, center co-ordinates, and then the radiuses for the x and y axis respectively. This allows drawing not only ellipses, but also circles (which simply have the x and y radiuses the same).

There is a more complex overload of the DrawEllipse method which enables you to specify the thickness of the outline and/or fill the inside of the shape. However both features are not implemented by the current version of the base class library.

Filling Shapes

DrawEllipse and DrawRectangle both have overloads that support specifying a gradient fill to colour in the internal area of the shape (the 7 parameters set to 0 in the above examples).

The specification of a gradient fill consists of a start and end co-ordinate and associated colours at those two points. The framework will then apply a linear gradient between those two points. Any point “before” the start co-ordinate will be the starting colour, while any point “after” the end point will be the end colour. If both the start and end colours are the same a solid fill will be obtained.

The co-ordinates for the gradient start and end points are measured in screen co-ordinates. I.e. they are relative to the top left corner of the LCD and could refer to locations outside the area of the shape being drawn. This fact can be used to produce some interesting rendering and animation effects.

The opacity parameter allows the fill to be semitransparent and show previous content drawn to the same region of the bitmap. The opacity is a byte value with 0 indicating fully transparent, and 255 indicating full opaque (solid fill).

The fill effect shown in the image above was achieved via the following code sample. Notice the direction of the linear fill (as dictated by it’s start and end co-ordinates), and the fact that the bottom right half of the rectangle is a solid white fill due to this region being “after” the gradient’s end point.

bmp.DrawRectangle(Color.White, // outline colour
     0,    // outline thickness (no outline)
     50,    // x
     50,    // y
     100,   // width
     100,   // height
     0,     // x corner radius
     0,     // y corner radius
     red,   // start gradient colour
     50,    // start gradient x
     50,    // start gradient y
     Color.White, // end gradient colour
     100,   // end gradient x
     100,   // end gradient y
     0xFF); // opacity of fill

Sample Applications

[Download drawingexample.zip - 8.6 KB]

The sample application available for download demonstrates a number of basic drawing operations as discussed above. The application cycles through a number of demonstrations. The sample application also demonstrates the use of System.Reflection functionality within the .NET Micro Framework to find the examples. If you would like to experiment with the drawing APIs, this sample application would be an ideal test harness, just add another “Example_XYZ” method that contains your drawing code and your example will be automatically picked up.

[Download randomshapes.zip - 35 KB]

Another sample application is available for download (without explanation as to how it is implemented). This example helps demonstrates the rendering capabilities of the .NET Micro Framework by creating and animating up to 50 random rectangles of different size, colour and alpha transparency over top of the .NET Micro Framework snowflake logo. It also demonstrates the fact that the .NET Micro Framework emulator is really a simulator. You will notice that running this example under the emulator produces very impressive rendering speeds which are not matched when running on actual hardware.

My next blog entry about the .NET Micro Framework will discuss how to create a basic WPF style application. Eventually I will outline an alternative approach for drawing basic shapes that enables the WPF framework to take care of compositing the individual shapes onto the screen, enabling basic shapes to be animated and moved around in a more object orientated manor.