Using DrawingVisual Objects
Using DrawingVisual Objects
This topic provides an overview of how to use xref:System.Windows.Media.DrawingVisual objects in the [!INCLUDETLA2#tla_winclient] visual layer.
The xref:System.Windows.Media.DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. This class is considered lightweight because it does not provide layout or event handling, which improves its performance. For this reason, drawings are ideal for backgrounds and clip art.
DrawingVisual Host Container
In order to use xref:System.Windows.Media.DrawingVisual objects, you need to create a host container for the objects. The host container object must derive from the xref:System.Windows.FrameworkElement class, which provides the layout and event handling support that the xref:System.Windows.Media.DrawingVisual class lacks. The host container object does not display any visible properties, since its main purpose is to contain child objects. However, the xref:System.Windows.UIElement.Visibility%2A property of the host container must be set to xref:System.Windows.Visibility.Visible; otherwise, none of its child elements will be visible.
When you create a host container object for visual objects, you need to store the visual object references in a xref:System.Windows.Media.VisualCollection. Use the xref:System.Windows.Media.VisualCollection.Add%2A method to add a visual object to the host container. In the following example, a host container object is created, and three visual objects are added to its xref:System.Windows.Media.VisualCollection.
[!NOTE] For the complete code sample from which the preceding code example was extracted, see Hit Test Using DrawingVisuals Sample.
Creating DrawingVisual Objects
When you create a xref:System.Windows.Media.DrawingVisual object, it has no drawing content. You can add text, graphics, or image content by retrieving the object's xref:System.Windows.Media.DrawingContext and drawing into it. A xref:System.Windows.Media.DrawingContext is returned by calling the xref:System.Windows.Media.DrawingVisual.RenderOpen%2A method of a xref:System.Windows.Media.DrawingVisual object.
To draw a rectangle into the xref:System.Windows.Media.DrawingContext, use the xref:System.Windows.Media.DrawingContext.DrawRectangle%2A method of the xref:System.Windows.Media.DrawingContext object. Similar methods exist for drawing other types of content. When you are finished drawing content into the xref:System.Windows.Media.DrawingContext, call the xref:System.Windows.Media.DrawingContext.Close%2A method to close the xref:System.Windows.Media.DrawingContext and persist the content.
In the following example, a xref:System.Windows.Media.DrawingVisual object is created, and a rectangle is drawn into its xref:System.Windows.Media.DrawingContext.
Creating Overrides for FrameworkElement Members
The host container object is responsible for managing its collection of visual objects. This requires that the host container implement member overrides for the derived xref:System.Windows.FrameworkElement class.
The following list describes the two members you must override:
xref:System.Windows.FrameworkElement.GetVisualChild%2A: Returns a child at the specified index from the collection of child elements.
xref:System.Windows.FrameworkElement.VisualChildrenCount%2A: Gets the number of visual child elements within this element.
In the following example, overrides for the two xref:System.Windows.FrameworkElement members are implemented.
Providing Hit Testing Support
The host container object can provide event handling even if it does not display any visible properties—however, its xref:System.Windows.UIElement.Visibility%2A property must be set to xref:System.Windows.Visibility.Visible. This allows you to create an event handling routine for the host container that can trap mouse events, such as the release of the left mouse button. The event handling routine can then implement hit testing by invoking the xref:System.Windows.Media.VisualTreeHelper.HitTest%2A method. The method's xref:System.Windows.Media.HitTestResultCallback parameter refers to a user-defined procedure that you can use to determine the resulting action of a hit test.
In the following example, hit testing support is implemented for the host container object and its children.