CanvasControl Class

CanvasControl Class

XAML control providing immediate mode 2D rendering. Start here if you are new to the Win2D API.

Inheritance Hierarchy

SystemObject
Windows.UI.Xaml.ControlsUserControl
Microsoft.Graphics.Canvas.UI.XamlCanvasControl

Namespace: Microsoft.Graphics.Canvas.UI.Xaml
Assembly: Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0

Syntax

Copy

public sealed class CanvasControl : UserControl, 
	IAnimationObject, IVisualElement, ICanvasResourceCreatorWithDpi, ICanvasResourceCreator

The CanvasControl type exposes the following members.

Constructors

	Name	Description
	CanvasControl	Initializes a new instance of the CanvasControl class.

Top

Properties

	Name	Description
	ClearColor	The color that the control is cleared to before the Draw event is raised.
	CustomDevice	Gets or sets an application-chosen device for this control.
	Device	Gets the underlying device used by this control.
	Dpi	Gets the current dots-per-inch (DPI) of this control.
	DpiScale	Gets or sets a scaling factor applied to this control's Dpi.
	ForceSoftwareRenderer	Gets or sets the whether the devices that this control creates will be forced to software rendering.
	ReadyToDraw	Gets whether the control is in a state where it is ready to draw.
	Size	Gets the current size of the control, in device independent pixels (DIPs).
	UseSharedDevice	Gets or sets whether this control should create a new device each time, or use a device which may common between other controls.

Top

Methods

	Name	Description
	ConvertDipsToPixels	Converts units from device independent pixels (DIPs) to physical pixels based on the current DPI of this control.
	ConvertPixelsToDips	Converts units from physical pixels to device independent pixels (DIPs) based on the current DPI of this control.
	Invalidate	Indicates that the contents of the CanvasControl need to be redrawn. Calling Invalidate results in the Draw event being raised shortly afterward.
	RemoveFromVisualTree	Removes the control from the last FrameworkElement it was parented to.

Top

Events

	Name	Description
	CreateResources	Hook this event to create any resources needed for your drawing.
	Draw	This is where the magic happens! Hook this event to issue your immediate mode 2D drawing calls.

Top

Remarks

To get started using Win2D, simply add a CanvasControl to your XAML tree, subscribe to its CanvasControl.Draw event, and use the methods of CanvasDrawEventArgs.DrawingSession to draw your immediate mode 2D graphics.

When using CanvasControl from managed code, care must be taken to avoid memory leaks due to reference count cycles. See Avoiding memory leaks for more information.

Examples

Starting with the "Blank App" XAML project template, edit MainPage.xaml and add the namespace and unloaded handler:

Copy

xmlns:canvas="using:Microsoft.Graphics.Canvas.UI.Xaml"
Unloaded="Page_Unloaded"

Add a CanvasControl to the page:

Copy

<Grid>
  <canvas:CanvasControl x:Name="myWidget" CreateResources="myWidget_CreateResources" Draw="myWidget_Draw" ClearColor="CornFlowerBlue"/>
</Grid>

Edit MainPage.xaml.cs, and add some drawing code:

Copy

public sealed partial class MainPage : Page
{
    CanvasSolidColorBrush redBrush;

    public MainPage()
    {
        this.InitializeComponent();
    }

    void myWidget_CreateResources(CanvasControl sender, CanvasCreateResourcesEventArgs args)
    {
        // Create any resources needed by the Draw event handler.

        // Asynchronous work can be tracked with TrackAsyncAction:
        args.TrackAsyncAction(myWidget_CreateResourcesAsync(sender).AsAsyncAction());
    }

    async Task myWidget_CreateResourcesAsync(CanvasControl sender)
    {
         // Load bitmaps, create brushes, etc.
         bitmapTiger = await CanvasBitmap.LoadAsync(sender, "imageTiger.jpg");
    }

    void myWidget_Draw(CanvasControl sender, CanvasDrawEventArgs args)
    {
        args.DrawingSession.DrawEllipse(155, 115, 80, 30, Colors.Black, 3);
        args.DrawingSession.DrawText("Hello, world!", 100, 100, Colors.Yellow);
    }

    void Page_Unloaded(object sender, RoutedEventArgs e)
    {
        this.myWidget.RemoveFromVisualTree();
        this.myWidget = null;
    }
}

Reference

Microsoft.Graphics.Canvas.UI.Xaml Namespace