Click or drag to resize
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
C#
public sealed class CanvasControl : UserControl, 
	ICanvasResourceCreatorWithDpi, ICanvasResourceCreator

The CanvasControl type exposes the following members.

Constructors
  NameDescription
Public methodCanvasControl
Initializes a new instance of the CanvasControl class.
Top
Properties
  NameDescription
Public propertyClearColor
The color that the control is cleared to before the Draw event is raised.
Public propertyCustomDevice
Gets or sets an application-chosen device for this control.
Public propertyDevice
Gets the underlying device used by this control.
Public propertyDpi
Gets the current dots-per-inch (DPI) of this control.
Public propertyDpiScale
Gets or sets a scaling factor applied to this control's Dpi.
Public propertyForceSoftwareRenderer
Gets or sets the whether the devices that this control creates will be forced to software rendering.
Public propertyReadyToDraw
Gets whether the control is in a state where it is ready to draw.
Public propertySize
Gets the current size of the control, in device independent pixels (DIPs).
Public propertyUseSharedDevice
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
  NameDescription
Public methodConvertDipsToPixels
Converts units from device independent pixels (DIPs) to physical pixels based on the current DPI of this control.
Public methodConvertPixelsToDips
Converts units from physical pixels to device independent pixels (DIPs) based on the current DPI of this control.
Public methodInvalidate
Indicates that the contents of the CanvasControl need to be redrawn. Calling Invalidate results in the Draw event being raised shortly afterward.
Public methodRemoveFromVisualTree
Removes the control from the last FrameworkElement it was parented to.
Top
Events
  NameDescription
Public eventCreateResources
Hook this event to create any resources needed for your drawing.
Public eventDraw
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:

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

Add a CanvasControl to the page:

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

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

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;
    }
}
See Also