Nevron .NET Vision
Diagram for .NET / User's Guide / Extensions / Canvas

In This Topic
    Canvas
    In This Topic
    The canvas extension can help you render a drawing to a virtual drawing surface (any device which can provide a valid Graphics object). It is represented by the NCanvas class and is internally used in printing and image export. By design NCanvas behaves very similar to a NDrawingView. 

    A NCanvas instance can be created on demand. The reference to the drawing passed in the canvas constructor is mandatory. The following code creates a canvas with the size of the drawing, which also uses the drawing resolution.
    C#
    Copy Code 
    // create a new canvas
NCanvas canvas = new NCanvas(drawingDocument);
    Visual Basic
    Copy Code 
    ' create a new canvas
Dim canvas As New NCanvas(drawingDocument)
     Canvas size and resolution

    The size of the canvas is measured in pixels and is controlled by the Size property. The canvas resolution is controlled by the Resolution property and is originally initialized with the document resolution. Initially the canvas is resized to the fit the entire document. The canvas can automatically be resized in two ways:

    • Size to Document - this operation is performed by the SizeToDocument method. The result of the operation is a canvas size in pixels large enough to contain the entire document. This operation resets the canvas X and Y scaling factors to 1.
    • Size to Viewport - this operation is performed by the SizeToViewport method. The result of the operation is a canvas size in pixels large enough to contain the specified viewport. This operation resets the canvas X and Y scaling factors to 1 and updates the viewport origin.

    For example:

    C#
    Copy Code 
    // set canvas resolution to 300x300 dpi
canvas.Resolution = 300;

// size the canvas to display the specified rect in scene coordinates
canvas.SizeToViewport(new NRectangleF(100, 100, 200, 200));

// create a bitmap large enough to contain the entire canvas
Bitmap bmp = new Bitmap(canvas.Size.Width, canvas.Size.Height, PixelFormat.Format24bppRgb);

// paint the canvas in the graphics constructed on top of this bitmap
Graphics grx = Graphics.FromImage(bmp);
canvas.Paint(grx, PaintReason.ImageExport, new NGraphicsSettings());
grx.Dispose();
    Visual Basic
    Copy Code 
    ' set canvas resolution to 300x300 dpi
canvas.Resolution = 300

' size the canvas to display the specified rect in scene coordinates
canvas.SizeToViewport(New NRectangleF(100, 100, 200, 200))

' create a bitmap large enough to contain the entire canvas
Dim bmp As New Bitmap(canvas.Size.Width, canvas.Size.Height, PixelFormat.Format24bppRgb)

' paint the canvas in the graphics constructed on top of this bitmap
Dim grx As Graphics = Graphics.FromImage(bmp)
canvas.Paint(grx, PaintReason.ImageExport, New NGraphicsSettings)
grx.Dispose()
     Canvas window

    The window is the rectangular area of the canvas in which the viewport must be painted. The WindowMargins property controls the margins of the window relative to the canvas. The window margins are measured in pixels and are by default set to 0.

    C#
    Copy Code 
    // modify the canvas window margins to be offset by 10 pixels
canvas.WindowMargins = new NMarginsL(10);
    Visual Basic
    Copy Code 
    ' modify the canvas window margins to be offset by 10 pixels
canvas.WindowMargins = New NMarginsL(10)

    The WindowOrigin is the point in canvas coordinates to which the ViewportOrigin is mapped. The Window property can help you obtain the entire window (in canvas device coordinates - i.e. pixels).

     Canvas viewport

    The viewport is the part of the document scene space, which is displayed in the window. The ViewportOrigin property is used to control the point in scene coordinates which is mapped to the WindowOrigin. By default the viewport origin is initialized with the document bounds left - top corner. The following code modifies the viewport origin:

    C#
    Copy Code 
    // modify the viewport origin 
canvas.ViewportOrigin = new NPointF(100, 100);
    Visual Basic
    Copy Code 
    ' modify the viewport origin 
canvas.ViewportOrigin = New NPointF(100, 100)
     Canvas layout

    The positioning of the document relative to the canvas is called canvas layout. You can perform a canvas layout with the help of the DoLayout method. Currently supported are the following layouts:

    • Normal - the document is displayed with the canvas specified scaling factors (controlled by the ScaleX and ScaleY properties).
    • Fit - the document is fit inside the canvas window (preserves the aspect ratio).
    • Stretch - the document is stretched to the canvas window (breaks the aspect ratio)
    • StretchToWidth - the document is stretched to the canvas window width (preserves the aspect ratio)
    • StretchToHeight - the document is stretched to the canvas window height (preserves the aspect ratio)

    The following code fits the document inside the canvas: 

    C#
    Copy Code 
    // fit the document in the canvas
canvas.DoLayout(CanvasLayout.Fit);
    Visual Basic
    Copy Code 
    ' fit the document in the canvas
canvas.DoLayout(CanvasLayout.Fit)
     Document padding
    Layouts as well the SizeToDocument method take into account the DocumentPadding property in order to compute the padded document bounds. The document padding are by default set to 0 and are measured in the document measurement unit.
    See Also
    NCanvas Class