When a user navigates the mouse cursor over a FrameworkElement, the cursor will change to indicate the type of action the user can take. For instance, when you hover around a Canvas, you'll see a basic arrow. Alternatively, if you move your mouse over a HyperLinkButton, you'll see a cursor that looks like a hand. But, you can use whatever cursor you want by setting the Cursor property; for example, using the Stylus cursor with a TextBlock:

<Canvas Cursor="Hand" Background="Green" Height="60" Width="180">
  <TextBox Cursor="Stylus" Height="20" Width="60" />
</Canvas>

This example uses two nondefault cursor options: Stylus and Hand. These options represent Cursor items, each of which is accessible through the System.Windows.Input.Cursors class. This class exposes nine statically visible Cursor properties:

This shows the values you can use in a FrameworkElement's Cursor property. These cursor options provide an excellent way to communicate with your users. Most of these options reflect the cursor options found in Cascading Style Sheets (CSS). But, short of newer advances in the proposed HTML 5 spec, it'd be a challenge to find a W3C CSS equivalent for our next property: Opacity.

The Opacity property represents an element's transparency. By default, this double-precision value is set to 1.0, which means the element is completely visible. You have the flexibility to set this value as low as 0.0, making it completely transparent. To get a feel for how the Opacity property renders content, look at figure 6.1, which shows a TextBlock with varying Opacity values.

Figure 6.1. An example of the Opacity property

The Opacity values ensure that a UIElement is visible. If you set the Opacity value to 0.0, the element wouldn't be visible. But, just because a UIElement can't be seen, it doesn't mean it's not there. Instead, even if a UIElement has an Opacity of 0.0, it'll still behave as though it can be seen. For instance, a transparent element will still respond to mouse events. If you want to completely hide an element, you must change the Visibility property.

The Visibility property gives you the ability to toggle whether a UIElement can be seen and whether it participates in layout. By default, all UIElement objects have a Visibility of Visible. This ensures that a UIElement can be seen and occupies its allotted layout area. If you set the Visibility of a UIElement to Collapsed, no layout area is reserved for the UIElement. Consider the StackPanel in listing 6.1.

Example 6.1. Three visible elements in a StackPanel

Listing 6.1 shows three TextBox elements. By default, each of these elements has a Visibility of Visible. Watch what happens when the Visibility of the middle TextBox is set to Collapsed, as in listing 6.2.

Example 6.2. Two visible elements and one collapsed element in a StackPanel

Listing 6.2 highlights the effects of Collapsed. The TextBox with the name tb2 isn't shown. You could just set the Opacity to 0.0, but the layout space wouldn't be freed. In addition, using the Opacity property to hide an element can be wasteful; an element with an Opacity of 0.0 still participates in the layout and rendering. Elements with a Visibility of Collapsed skip the rendering stem and report no size in the layout steps.

Cursor, Visibility, and Opacity all affect visible portions of the UIElement, but not the layout. The alignment properties typically have a great impact on the layout of an element, depending upon the panel in which the element is hosted.

Every FrameworkElement gives you the opportunity to specify how it should be aligned within its parent. This alignment setting will trickle down through the object tree and affect the alignment of all child elements—well, at least until another FrameworkElement sets its alignment. You have two ways to align visual elements.

Visual elements can be aligned both vertically and horizontally by setting the VerticalAlignment and HorizontalAlignment property values to one of the acceptable values. These values belong to two separate enumerators, aptly called VerticalAlignment and HorizontalAlignment.

Example 6.3. Horizontal and vertical alignment

Listing 6.3 shows the effects of all four HorizontalAlignment options and all four VerticalAlignment options. The HorizontalAlignment property accepts the Left, Center, Right, and Stretch values, whereas the VerticalAlignment property accepts the Top, Center, Bottom, and Stretch values. The alignment properties behave differently depending upon the container in which the UIElement resides. For example, they have no effect when put into a Canvas due to the Canvas panel's lack of layout functionality.

Both properties default to their Stretch values. Because the Stretch options alter the rendered height or width of an element to take up the maximum amount of space available, you may want to consider giving the element some breathing room with the Margin property.

Similar in nature to the Padding property, the Margin property enables you to specify a cushion, but this specific cushion works outside the bounds of a FrameworkElement. This cushion can be set using a single value or a space-delimited or comma-delimited list of four values just like the Padding property, as shown in listing 6.4.

Example 6.4. Margin and padding

Listing 6.4 shows the Margin and Padding properties working together. The Padding property is valid in this code because this property is exposed by the System.Windows.Controls.Control class. This is explained further in the next chapter. For now, it's important to recognize that the Padding property isn't accessible to all FrameworkElement items, but the Margin property is.

Margins and padding can alter the location of contained elements, sometimes pushing them to subpixel locations and making them look fuzzy. Luckily, Silverlight has the UseLayoutRounding property to help us avoid that.

Silverlight supports aligning elements on subpixel boundaries. An unfortunate side effect of this is the loss of crisp lines. Sometimes, you really want that 1 px line to be just 1 px thick and not antialiased to 2 px in thickness.

One simple way to avoid this problem is to place your elements on whole pixel locations. But when your element is nested inside a panel, which is inside a control, which is in a stack panel located in another grid—all of which can have margins, padding, and other properties affecting layout—you can't easily calculate exactly where your element will appear.

Silverlight supports a property of the UIElement called UseLayoutRounding. When UseLayoutRounding is set to true, the layout system (see section 6.3) will round the points of your element to the nearest whole pixel. When false, Silverlight will respect the subpixel location of the points and won't attempt to move them. Listing 6.5 shows the impact of layout rounding on two rectangles. The first rectangle has layout rounding turned on; the second has it turned off.

Example 6.5. Layout rounding in action with two rectangles

In listing 6.5, you can see that the rectangle that isn't rounded to the nearest pixel has lines that are two pixels thick and light gray. When viewed in its native resolution, it looks fuzzy. When layout rounding is turned on, the result is a crisp line with sharp corners and no fuzz.

UseLayoutRounding is respected by almost every element in Silverlight. The Polygon class exposes this property but ignores it. Polygons are expected to be complex shapes where layout rounding wouldn't really make sense, so layout rounding is a no-op.

We covered the Margin property as well as the useful HorizontalAlignment and VerticalAlignment properties. In addition, we also highlighted the value of the Visibility, Opacity, and Cursor properties. Finally, we looked at how to scare away the fuzzies with UseLayoutRounding. Collectively, these represent some of the more widely used properties of the FrameworkElement and UIElement classes. But these properties only serve to describe an element. There are times when you need to perform an action on them; in these scenarios, you need to rely on their methods.

Every UIElement is a DependencyObject. A DependencyObject gives you the ability to retrieve and change attached property values. Consider the process of altering the position of an element within a Canvas. Although you might initially think to set the Canvas.Left and Canvas.Top properties, you'll quickly run into a wall. Instead, you must take advantage of the SetValue method as shown in listing 6.6.

Example 6.6. Moving a TextBlock five pixels with GetValue and SetValue

When a TextBlock is clicked and the click event raised, it'll move five pixels down and to the right. This is made possible by retrieving the current Left and Top positions of the TextBlock within the Canvas through the GetValue methods. Then, the TextBlock is moved within the Canvas using the SetValue methods. But where do the TopProperty and LeftProperty values come from?

These properties are DependencyProperty elements—a special type of property designed to depend on information from multiple sources, covered in chapter 2. For instance, as shown in listing 6.6, you use two DependencyProperty (specifically attached properties) attributes—Canvas.Left and Canvas.Top—to position the TextBlock. At the same time, there could be an animation affecting the TextBlock, so the position of the TextBlock would be dependent upon both the layout panel (the Canvas) and the animation. (Animations are discussed in chapter 22.)

Thanks to the DependencyProperty, it's incredibly easy to manage or retrieve the value associated with an attached property. Dependency properties also provide several other advantages discussed in more detail in section 2.1.4. For now, let's look at how to find elements within the element tree.

As described in chapter 2, the Silverlight Object Model is represented as a hierarchical tree of elements. Considering that each element in this visual tree is, at its core, a FrameworkElement, you have the flexibility to navigate this tree. With this element, you have the ability to go either up or down the tree.

To go down the tree, you must call the FindName method. This method takes the name of an element and retrieves it. It doesn't matter if the element is a child, grandchild, or located even further down the tree. The FindName method will retrieve it as long as it's a descendent. If it isn't found, the method will return null.

Alternatively, if you need to find an element up the tree, you use the Parent property to recursively navigate up the tree and search the sibling nodes, as described in chapter 2.

Finding elements is a task that you may need to perform in certain circumstances, such as when you dynamically load XAML. Once these elements are found, you can readily get or set the attached property values of a UIElement using the GetValue and SetValue methods. These methods aren't difficult to understand, but the process of using a DependencyProperty to set the value of an attached property may seem strange at first. As you grow more familiar with it, it's easier to see the power of this approach, which can lead to new ways of delivering a rich and interactive user experience.

The UIElement and FrameworkElement classes form the base of everything that's rendered in Silverlight. We've seen that they offer a number of useful properties and methods to control everything from their alignment, to visibility, to how opaque they should appear. Now that we understand the capabilities they offer, it's time to take a step back and look at the rendering process as a whole, in which the UIElement and FrameworkElement play a core role.

As you recall from chapter 2, elements in Silverlight are organized into the visual tree. This tree has a single root and it branches off into hundreds or thousands of nodes depending upon the complexity of what's on the screen.

The structure of that tree is key to the rendering process. For any branch of the tree, Silverlight rasterizes elements in the visual tree in the following order:

This is a recursive process; it starts at leaf nodes (the furthest children) and works its way back to the root.

Note that the clipping happens after the opacity calculations. One performance consideration is that a large shape that has opacity other than 1.0 and has only a small portion shown due to clipping (manual or via a panel) can waste a fair number of CPU cycles due to the opacity calculation. Similarly, effects are also calculated prior to the clip and have even more impact on performance.

The intermediate surfaces mentioned are all bitmap caches that are later composited together. Note that the Writeable bitmap is a special case because it essentially is an intermediate surface of its own.

The rendering process involves a recursive traversal of the visual tree, with optimizations to eliminate branches of the tree that have been already cached and haven't changed. Another optimization is the handling of occluded pixels.

I used to play around with 3D rendering. One of the most basic performance optimizations you'd make is the culling of occluded triangles. When 3D objects are rendered in 2D, the surface is typically broken down into many planar triangles. You'd check to see whether the normals (the direction the surface faces) for the triangles are pointing away from you and you are, therefore, looking at the back side of a triangle. If so, you'd remove the triangle from the pipeline. You'd also then check to see if there are any triangles that are completely covered by other triangles.

Though a simplification, consider a complex scene where there's an opaque wall in front of you (the camera) and a bunch of complex shapes on the other side of the wall, as shown in figure 6.3. In such a scene, the shapes would be occluded by the wall; it'd be wasteful to include them in the rendering process.

Occlusion culling in a 3D system can be expensive to calculate. The least performant but most accurate approach would be to shoot an imaginary ray from the camera to each and every point in the geometry making up the shapes, and see if the ray must cross through any other geometry before hitting the target. If it does, then that point is occluded.

Surprisingly, in a 2D system such as Silverlight, where you can have transforms and effects that play into both the size and shape of elements and as varying degrees of opacity, occlusion culling is more complicated.

Figure 6.3. An overhead view of occlusion in a 3D system. The shapes are occluded by the wall; the camera can't see them. It'd be wasteful to include their geometry in the rendering process. Silverlight does occlusion culling at the pixel level rather than the shape level.

Silverlight doesn't handle occlusion culling at the shape level. Instead, it handles it at the brush pixel level. If you consider that performing blends between multiple pixels can be an expensive operation, it makes sense that Silverlight would optimize that process out of the loop for any pixels that wouldn't be visible in a frame.

This optimization does speed up rendering in most cases. But, if you know an element won't be visible on the screen and you either have many elements or that specific element is expensive to render, you'll want to set its Visibility property to Collapsed so that Silverlight doesn't spend any time on its rendering or layout. Similarly, you need to take into consideration the complexity of any alpha blending you perform, especially when there could be several layers of pixels in play.

One way to cut down on the number of layers and also avoid several other rendering and layout steps, is to cache segments of the visual tree into their own bitmaps.

Cached composition enables branches of the visual tree to be stored in bitmap form after the first rendering. (For the web programmers reading this, understand that the cache is a local in-memory cache on the client.) This bitmap is then used on subsequent frames until the elements change. For complex subtrees, cached composition can realize huge performance benefits. Figure 6.4 helps visualize how cached composition works.

Figure 6.4. Cached composition in use. On the first render, or any layout change, the cache is updated with the result of the render. Subsequent frames use the prerendered contents of the cache.

On first render, any elements that have been marked to be cached are rendered as usual and then the output of that render is stored in the bitmap cache. Listing 6.8 shows how to enable caching for a group of elements in a Grid.

Example 6.8. Caching a group of elements in a StackPanel

Listing 6.8 shows some Silverlight artwork (suitable for submission to the Freer and Sackler Galleries, no doubt!) composed of a number of shapes and paths. The paths here are relatively simple, but more complex artwork may be made of hundreds or thousands of points. The process of rasterizing complex artwork has a real CPU cost but, when cached, that cost is one time rather than per frame.

In section 6.4 we discuss render transforms. Render transforms can affect size and orientation of a group of elements. If you apply a render transform to a subtree that has been cached—for example, to increase its size to 200 percent—you may end up losing the benefit of the cache because Silverlight has to render at the larger size. Luckily, there's another form of the CacheMode property that enables you to cache the render at a different size. Listing 6.9 shows how to cache elements at four times their natural size.

Example 6.9. Caching at a size larger than the default (XAML)

Note that the bitmap cache is set to a 4× render whereas I'm only using a 2× transform. That's a bit wasteful but certainly is allowed and useful, and you can always scale down without losing quality. If the RenderAtScale option hadn't been used, caching wouldn't have worked for this subtree of elements.

Caching the elements as bitmaps allows Silverlight to use hardware acceleration by keeping those surfaces as textures cached on the video card—assuming sufficient texture memory and assuming hardware acceleration has been enabled at the plugin level.

Once a tree of visual elements has been cached, you can take advantage of hardware acceleration for composting those elements with other layers in the application. In addition, hardware acceleration can benefit transforms, such as stretching and rotation.

In order to use hardware acceleration, you must set the EnableGPUAcceleration plug-in parameter to true. In chapter 4, we covered how to build up the object tag. Here's the line for enabling acceleration:

<param name="EnableGPUAcceleration" value="true" />

If your application is an out-of-browser application (chapter 5), you can set this via the OutOfBrowserSettings.EnableGPUAccelerationProperty, typically handled through the out-of-browser settings dialog.

Hardware (GPU) acceleration can help you realize real performance gains. But there can also be times when it's a net performance drain in your application. The main reason for this is the number of surfaces that must be created when hardware caching is used.

For each bitmap of cached content, Silverlight must then create two additional surfaces in video RAM: a surface to hold all content above the cached bitmap and one to hold the content below it. In an application with a large height/width on a machine with relatively low video memory (especially all those integrated graphics chips), you can quickly run out of memory should you try to cache too many separate subtrees.

When caching, especially when using hardware acceleration, you should endeavor to create as few bitmap caches as possible. When using acceleration, you may want to debug how the process is working. For that, you can use the cache visualization debug settings.

When performance is important, one thing that can really help is visualizing the bitmap caches in use in your application. Silverlight provides a setting that draws colored overlays on different regions in your UI, indicating which content is or isn't cached. Cached content shows up normally; uncached content shows up with a colored overlay.

Cache visualization is another parameter on the plug-in object described in chapter 4. The parameter is named enableCacheVisualization:

<param name="enableCacheVisualization" value="true"/>

You can also set this value via code, which is essential for debugging out-of-browser applications. The setting is the EnableCacheVisualization property of the Settings object:

Application.Current.Host.Settings.EnableCacheVisualization = true;

In both cases, this is a debug setting, so be sure to turn it off when you move your application to testing or production environments. The in-code approach allows you to turn the property on and off via a menu setting or similar approach.

Similarly, you can visualize redraw regions to see exactly what content Silverlight must redraw for each frame. Like cache visualization, this is an object tag setting:

<param name="enableRedrawRegions" value="true" />

When you enable this visualization, Silverlight will display redraw regions in a different color for each frame, making it obvious what elements are causing which parts of the interface to be redrawn at runtime. Just as with the other setting, this isn't something you want to leave enabled in production. Also with the other settings, this has a runtime-settable version especially useful for out-of-browser applications:

Application.Current.Host.Settings.EnableRedrawRegions = true;

Between the redraw visualization and the cache visualization, you should have a good start on debugging any rendering performance issues in your application.

Rasterization is an important process to understand in Silverlight, especially if you're creating an application, such as a game or media player, which is performance sensitive. Consider using cached composition and hardware acceleration to help you out but understand the limitations and where the point of diminishing returns lies for your application.

The rendering process as a whole has a number of important steps. Of those, the key steps to understand are the clock tick, which increments all the animation and media counters; the per-frame rendering callback, which is useful for game loops and similar operations; and the rasterization process.

One other important step we haven't yet covered is layout. Layout is important enough to require a more in-depth look than some of the other steps. In fact, of all of them, I'd consider layout the most important step for the majority of Silverlight developers.

Whenever elements need to be rendered to screen due to having just been added, made visible, or changed in size, the layout system is invoked for an asynchronous layout pass. The first step in layout is to measure the elements. On a FrameworkElement, the measure pass is implemented inside the virtual MeasureOverride function, called recursively on the visual tree:

protected virtual Size MeasureOverride(Size availableSize)

The availableSize parameter contains the amount of space available for this object to give to itself and child objects. If the FrameworkElement is to size to whatever content it has, the availableSize will be double.PositiveInfinity.

The function returns the size the element requires based on any constraints or sizes of child objects.

Note that MeasureOverride isn't called directly from the layout system: it's a protected function. Instead, this function is called from the UIElement's Measure function, which, in turn, is called by the layout system.

The second pass of layout is to arrange the elements given their final sizes. On a FrameworkElement, the Arrange is implemented inside the virtual ArrangeOverride function, also called recursively:

protected virtual Size ArrangeOverride(Size finalSize)

The finalSize parameter contains the size (the area within the parent) this object should use to arrange itself and child objects. The returned size must be the size actually used by the element and smaller than the finalSize passed in; larger sizes typically result in clipping by the parent.

Similar to the relationship between the measure pass and MeasureOverride, ArrangeOverride isn't called directly by the layout system. Instead, the Arrange method on UIElement is called, which then calls the protected ArrangeOverride function.

At the end of the arrange pass, Silverlight has everything it needs to properly position and size each element in the tree. But it doesn't have everything it needs to actually display the element because its render position or size could be affected by a render transform, as covered in the previous section.

Despite the name, the LayoutCompleted event isn't technically part of the layout pass. Instead, it's fired as the last event before an element is ready to accept input. LayoutCompleted is the safe location for inspecting the actual size and position of the element or otherwise responding to changes in same.

Don't do anything in LayoutCompleted that would cause another layout pass. For example, don't change the size or position of an element, modify its contents, change its layout rounding, or otherwise manipulate properties that could change the size of the element's bounding box. If you have multiple nested layout passes and they take longer than the time allowed for that frame, the Silverlight runtime may skip frames or throw a layout exception.

Regardless of its actual shape, each visual element in Silverlight can be represented by a bounding box or layout slot. This is a rectangular shape that takes into account the element's size and any margins, padding, or constraints in effect. Figure 6.5 shows the relationship between a layout slot and the child element hosted in a panel.

Figure 6.5. The relationship between the layout slot and the child element for an element smaller than the slot

The layout slot is the maximum size to be used when displaying an element. Portions of the element that fall outside the slot will be clipped. To see the layout slot for an element, you can call the static function GetLayoutSlot:

public static Rect GetlayoutSlot(FrameworkElement element)

The returned Rect will contain the bounding box or layout slot for that element. This return value can be useful when creating a custom panel or when debugging layout issues.

Sometimes elements may be larger than their layout slots, even after measuring and arranging have attempted to fit them. When that happens, you have a layout clip that represents the intersection of the child element's size and the layout slot.

Figure 6.6 shows the relationship between the layout slot, the child element, and the layout clip for that child element in an instance where the child element is too large for its slot.

The function GetLayoutClip returns the intersection that represents the layout clip. In this case, the function returns an actual geometry object, useful for setting the clip geometry for an element should you need to:

public static Geometry GetLayoutClip(FrameworkElement element)

Figure 6.6. The relationship between the layout clip and the layout slot for a child element too large for its slot

The returned Geometry contains the intersection or null, if the element wasn't clipped. It should be noted that, in WPF, the GetLayoutClip method has a counterpart by the same name that actually resides on the UIElement and takes in the slot size and returns clip geometry.

An example of this has to do with large collections of children in controls such as lists and grids. Drawing the elements takes a certain amount of time but that only happens for elements that are onscreen. Creation of the CLR objects representing the items also takes a certain amount of time. Most importantly for us, the measure and layout passes happen for all children, regardless of their potential position on screen or off. Therefore, if you have a thousand elements in a ListBox, MeasureOverride and ArrangeOverride will be called for each of them. More importantly, if those elements contain children (as often is the case with item templates), you'll have even more calls in the layout passes.

One solution to this is virtualization. A subset of the built-in controls (such as the DataGrid) support UI virtualization. For those, precreated elements are reused with new data. The end result is a reduction in the number of in-memory elements, as well as a reduction of MeasureOverride and ArrangeOverride calls.

Another performance consideration has to do with sizing and positioning elements. For example, if you change the margin of an element or modify its width or height, you'll trigger a layout pass. But, if you instead call a render transform to either move or resize that element, you won't trigger a pass. We'll cover render transforms in the next section.

Understanding the layout system helps take some of the mystery out of what happens when you size elements in Silverlight, and they don't quite do what you might've expected them to do. It's also a key concept to understand if you plan to implement your own panels/container controls.

WPF has the concept of a layout transform. This type of transform is parallel to a render transform but triggers a layout pass. As we've seen here, triggering a layout pass can be an expensive operation, especially if done inside an animation. For performance considerations and due to their relatively low adoption, layout transforms were omitted from Silverlight.

The render transforms provided by Silverlight are almost always adequate to solve problems we used to solve with layout transforms—and often superior. Let's look at them next.