Quickstart: Shapes for Windows Phone

Article
05/20/2016

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

In Windows Phone, there are several options for creating shapes and drawing them on the screen. This Quickstart introduces shapes, such as ellipses, rectangles, polygons, and paths. This Quickstart focuses on creating shapes by using XAML.

Tip

If you do a lot of work with shapes, you probably will want to use a WYSIWYG tool like Blend for Visual Studio, which you can use to develop apps for Windows Phone. A WYSIWYG tool simply generates XAML, so understanding the underlying XAML is worthwhile.

This topic contains the following sections.

Introduction to Shapes

There are two sets of classes that define a region of space: Shape and Geometry. The main difference between these classes is that a Shape has a brush associated with it and can be rendered to the screen, while a Geometry simply defines a region of space and is not rendered. You can think of a Shape as a UIElement with its boundary defined by a Geometry. This Quickstart just covers Shape classes.

The different Shape classes are Line, Ellipse, Rectangle, Polygon, Polyline, and Path. Path is interesting in that it allows you to define an arbitrary geometry for its boundary.

In order for a Shape to be rendered to the screen, a Brush must be associated with it. The Fill property of the Shape is set to the desired Brush. The different types of brushes in Windows Phone are: SolidColorBrush, LinearGradientBrush, RadialGradientBrush, and ImageBrush. For more information about Brushes, see the Quickstart: Brushes for Windows Phone.

Ellipses

To create a basic Ellipse, simply specify a Width, Height, and a Brush for the Fill.

The following example creates an Ellipse with a Width of 300, a Height of 300, and uses an SBlueSolidColorBrush as its Fill.

<Ellipse Fill="Blue" 
    Height="300" 
    Width="300"/>

Rectangles and Strokes

A Rectangle is a four-sided shape with opposite sides being equal. To create a basic Rectangle, simply specify a Width, a Height, and a Fill.

Windows Phone enables you to round the corners of a Rectangle. To create rounded corners, specify a value for the RadiusX and RadiusY properties. These properties specify the x and y axes of an ellipse that defines the curve of the corners. The maximum value of RadiusX is the Width divided by two and the maximum value of RadiusY is the Height divided by two.

All Shape classes have Stroke and StrokeThickness properties. Stroke specifies the Brush that's used to paint the border of the Shape. If a Brush for Stroke isn't specified, then the border around the shape isn't drawn. StrokeThickness specifies the width of the border.

Note

A Line only renders a Stroke, not the Fill, since it has no interior space. To render a Line, make sure the Stroke and StrokeThickness properties are specified.

The following example creates a Rectangle with a Width of 100 and Height of 50. It uses a SteelBlue SolidColorBrush for its Fill and a Black SolidColorBrush for its Stroke. The StrokeThickness is set to 3 and the RadiusX and RadiusY properties are set to 10, which gives the Rectangle rounded corners. Use the sliders in this example to experiment with different property values.

<Rectangle Fill="SteelBlue" 
    Height="275" 
    Width="350" 
    Stroke="AliceBlue" 
    StrokeThickness="15" 
    RadiusX="40" 
    RadiusY="30"/>

The following image shows a Rectangle with rounded corners displayed on a Windows Phone.

Polygons

A Polygon is a shape with a boundary defined by an arbitrary number a points. The boundary is created by connecting a line from one point to the next, with the last point connected to the first point. The Points property defines the collection of points that make up the boundary. In XAML, you define the points with a comma-separated list. In code, you use a PointCollection to define the points and you add each individual point as a Points structure to the collection.

The following example creates a Polygon with four points set to (10,200), (60,140), (130,140), and (180,200). It uses a Blue SolidColorBrush for its Fill. No Stroke is defined, so it's possible to arrange the points so that nothing is rendered. If a Stroke is defined, at least a line or a point as thick as the Stroke is drawn. Use the sliders in this example to experiment with the coordinates of the different points. Also, note that if you select the Stroke check box, the last point is connected to the first point.

Polylines

A Polyline is similar to a Polygon in that the boundary of the shape is defined by a set of points. The main difference between a Polyline and a Polygon is that the last point in a Polyline isn't connected to the first point. The Fill of a Polyline still paints the interior space of the shape, even if the ends of the boundary (or Stroke) don't meet.

As with a Polygon, the Points property defines the collection of points that make up the boundary. In XAML, you define the points with a comma-separated list. In code, you use a PointCollection to define the points and you add each individual point as a Points structure to the collection.

The following example creates a Polyline with four points set to (10,200), (60,140), (130,140), and (180,200). A Fill isn't defined, but a Stroke is defined. Notice that the last and first points aren't connected as they are in a Polygon. Use the sliders in this example to experiment with the coordinates of the different points. Compare the differences between a Polyline and a Polygon when the Fill and Stroke check boxes are changed.

Paths

A Path is the most versatile Shape because it allows you do define an arbitrary geometry. However, with this versatility comes complexity. This section shows how to create a basic Path in XAML.

The geometry of a path is defined with the Data property. The Data property can be set to a Geometry object or in XAML. To define a path in XAML, you use the path markup syntax.

The following example creates a Path that's comprised of a Bezier curve segment and a line segment. The Data attribute string begins with the move command, indicated by M, which establishes a start point for the path. The capital M indicates an absolute location for the new current point. A lowercase m indicates a relative location. The first segment is a cubic Bezier curve that begins at (100,200) and ends at (400,175), which is drawn by using the two control points (100,25) and (400,350). This segment is indicated by the C command in the Data attribute string. Again, the capital C indicates an absolute path; the lowercase c indicates a relative path.

The second segment begins with an absolute horizontal line command H, which specifies a line drawn from the preceding subpath's endpoint (400,175) to a new endpoint (280,175). Because it is a horizontal line command, the value specified is an x-coordinate.

Note

Path data parameters are case-sensitive.

<Path Stroke="DarkGoldenRod" 
    StrokeThickness="3" 
    Data="M 100,200 C 100,25 400,350 400,175 H 280" />

The following image show the Path displayed on a Windows Phone.

Graphics Thread

On Windows Phone graphics (and some animations) run on a separate thread. For most scenarios, you won't have to worry about this since the system takes care of managing all of this for you. But if your app is going to have a lot of graphics and animations, there are performance and design considerations you'll want to consider.

For more information about performance, see App performance considerations for Windows Phone 8.