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();

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()

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.