IXRCanvas (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

This class represents an area upon which you can explicitly position child objects by using coordinates that are in relation to the area.

Syntax

class IXRCanvas : public IXRPanel

Remarks

IXRCanvas is a container object that contains child objects, which are rendered inside the graphical area covered by the canvas. Child objects are explicitly positioned by using coordinates. Because absolute positioning does not consider the size of the window, it is often a better choice to use IXRGrid or IXRStackPanel as a container.

If you would like to access or modify the size of the window, you can call IXRVisualHost::GetSize or IXRVisualHost::SetSize. To specify x-coordinates and y-coordinates for the window, you can populate the XRWindowCreateParams structure and supply a pointer to it when you create an instance of the visual host.

You can access an existing IXRCanvas object in the visual tree by obtaining a pointer to a visual host, retrieving the host's root element, traversing the element tree, and then calling IUnknown::QueryInterface on a named object in the visual tree. Or, you can create a new IXRCanvas object yourself and insert it into a generated visual tree, as an alternative to declaring it in the source XAML for your application.

A canvas object can also be defined in Microsoft Silverlight 2 XAML. For information about the differences between XAML in Silverlight for Windows Embedded and Silverlight 2, see Differences Between Silverlight for the Web and Silverlight for Windows Embedded. For more information about how to define this element in the source XAML for your application, see this Microsoft Web site.

Notice that when you load the source XAML for your application, the canvas object is added to Silverlight element tree.

Each child object of a canvas must be an IXRUIElement. In XAML, you declare child objects as object elements that are the inner XML of a canvas object. In code, you can manipulate the collection of child objects that belongs to the canvas object, in order to add new objects or modify existing objects. To access this collection, you can call the inherited method IXRPanel::GetChildren and retrieve the collection in an IXRUIElementCollection object.

To control the positioning of objects inside the canvas, you must specify x and y coordinates for each object. These coordinates are in pixels. The x and y coordinates are often specified by using attached properties, specifically Canvas.Left and Canvas.Top. Canvas.Left specifies the object's distance from the left side of the canvas that contains it (x-coordinate), and Canvas.Top specifies the object's distance from the top of the canvas that contains it (y-coordinate). To set these properties on a child object, you can call IXRDependencyObject::SetAttachedProperty.

You can also nest canvas objects and position them by using Canvas.Left and Canvas.Top attached properties. When you nest objects, the coordinates used by each object are in relation to its immediate canvas container object. To set these properties on a nested canvas object, you can call the inherited method IXRDependencyObject::SetAttachedProperty.

Frequently, IXRCanvas is used only as a container for other objects and has no visible settings. A canvas object is not visible if one of the following conditions is true:

The value retrieved by the inherited method IXRFrameworkElement::GetHeight is equal to 0.
The value retrieved by the inherited method IXRFrameworkElement::GetWidth is equal to 0.
The value retrieved by the inherited method IXRPanel::GetBackground is equal to a null reference.
The value retrieved by the inherited method IXRUIElement::GetOpacity is equal to 0.
The value retrieved by the inherited method IXRUIElement::GetVisibility is equal to AX_Visibility_Collapsed.
One of the ancestor objects of the canvas object is not visible.