Canvas and CanvasViewer Control

Adding Control to Page

CanvasViewer is embedded into ASP.NET web applications as a regular Web Forms control and does not require installing any additional plug-ins or players like Flash player or Silverlight on the client side. It comes in Aurigma.GraphicsMill.AjaxControls.VectorObjects.dll assembly located in the Graphics Mill Web Controls installation folder.

The code snippet below represents embedded CanvasViewer with the size specified by the Width and Height properties:

<asp:ScriptManager ID="ScriptManager1" runat="server" />
<aur:CanvasViewer ID="CanvasViewer1" runat="server" Width="324px" Height="204px">
</aur:CanvasViewer>

This snippet produces the following view:

As you can see, CanvasViewer displays the worksheet. This worksheet is a default instance of the Canvas class created by the CanvasViewer. After you read the Canvas paragraph, you will learn how to set canvas size and populate it with graphics data.

Workspace, Content, Viewport

Before going further with Canvas and CanvasViewer details, we should review three basic concepts:

• Workspace is a coordinate system for Canvas. Coordinates are specified in points (72 points = 1 inch) and they are device independent.
• Content is a coordinate system for Canvas adapted for displaying in the web browser with a specified zoom level. Coordinates are in pixels.
• Viewport is a coordinate system for the content visible in the CanvasViewer control at a specific time. Coordinates are in pixels.

The following picture illustrates the workspace, content, viewport, and how they are related:

CanvasViewer control displays the viewport at every moment of time. When scrolling the design inside CanvasViewer, the viewport changes its position on the content. Viewport does not include CanvasViewer frame and scrollbars.

Canvas

As we discussed before, Canvas is the graphics document represented in device independent coordinates. Its content is defined by layers and objects. To learn about layers and objects in more detail, read the Layers and Objects article. There are three types of objects, namely, raster, vector, and text. All your designs loaded in AJAX Vector Objects are formed using them. Layers, in their turn, are invisible as they exist to organize objects in groups. All manipulations are made on objects and can be performed in two ways: interactively using a touch screen/mouse device or programmatically via an API. The client and server APIs provide very similar features. Thus, if you create an object using the server API, you can easily manipulate it on the client side.

When you set up a Canvas instance, you can specify a workspace size which is set in points. Unlike pixels, points always have the same size. If you measure an object on the different outputs with the ruler, its size will be the same, equal to the value in points. Therefore, the workspace coordinate system is device independent. For example, when you set the Canvas size in points and create a design on it and the design is displayed on your screen (usually 96 DPI), the number of pixels will be different from the same design printed on a 300 DPI printer. However, if you measure both displayed and printed designs with a ruler, the values will be the same.

Let us see how the coordinate systems of the workspace, content, and image rendered to print-ready output are related. The following snippet shows how to specify Canvas with 243 x 153 pt workspace:

<aur:CanvasViewer ID="CanvasViewer1" runat="server" Width="350px" 
    Height="220px" Zoom="3">
    <Canvas ID="Canvas" WorkspaceWidth="243" WorkspaceHeight="153" />
</aur:CanvasViewer>

After launching, the application AJAX Vector Objects translates the workspace to the content depending on the screen resolution (96 DPI in our case) and a current zoom. As we specify 100% zoom, the content size is equal to the workspace (3.375 x 2.125 inches or 324 x 204 pixels). When you prepare the Canvas content for printing on a 300 DPI printer, you will get 3.375 x 2.125 inches too, but it will have 1012 x 637 pixel size. To learn more about rendering read the Saving and Rendering Canvas article. The following picture illustrates this:

CanvasViewer

As we discussed before, CanvasViewer is a control designed for displaying Canvas on the webpage. When you set CanvasViewer size, you specify width/height of the ASP.NET control as well as indirectly specify viewport size, which is a part of the control.

The viewport size never changes while a user is editing the Canvas content in the browser, whereas the content size can change along with the zoom level: zoom-in makes the content larger, zoom-out - smaller. You can get the current content size via the ContentHeight and ContentWidth properties.

The Zoom property allows you to change the zoom level, which should be between MinZoom and MaxZoom values. For example, let us set 500% zoom in CanvasViewer:

CanvasViewer1.Zoom = Math.Min(5.0f, CanvasViewer1.MaxZoom);

var canvasViewer = $find("<%= CanvasViewer1.ClientID %>");
canvasViewer.set_zoom(Math.min(5.0, canvasViewer.get_maxZoom()));

If you do not want to calculate the optimal zoom value for displaying Canvas in CanvasViewer, you can use the ZoomMode enumeration:

Here is how to specify ZoomMode to BestFit. The following picture shows how BestFit mode works:

Another way to change a visible area of the content is to scroll the viewport. If the content is larger than the viewport, a user can scroll the content to see more of Canvas using the scroll bars that appear on CanvasViewer. When you scroll Canvas, this means that you move the viewport on the content. The current position of the viewport is specified by the ScrollingPosition property which defines the slider's position. The vertical slider can be moved in the range from 0 to (ContentHeight - Height + ScrollBarWidth), horizontal - from 0 to (ContentWidth - Width + ScrollBarWidth). The following code moves the viewport to the right bottom corner of the content:

CanvasViewer1.ScrollingPosition = new System.Drawing.Point(
    CanvasViewer1.ContentWidth - (int)CanvasViewer1.Width.Value + CanvasViewer1.ScrollBarWidth,
    CanvasViewer1.ContentHeight - (int)CanvasViewer1.Height.Value + CanvasViewer1.ScrollBarWidth);

var canvasViewer = $find("<%= CanvasViewer1.ClientID %>");
canvasViewer.set_scrollingPosition(new Sys.UI.Point(
    canvasViewer.get_contentWidth() - canvasViewer.get_width() + canvasViewer.get_scrollBarWidth(),
    canvasViewer.get_contentHeight() - canvasViewer.get_height() + canvasViewer.get_scrollBarWidth()));

As a result, after launching the application, you will see the right bottom corner of the design instead of the upper left displayed by default.

The CanvasViewer always displays the scroll bars by default regardless of the content size but you can change this behavior. The following code snippet hides scroll bars if the content fits the viewport:

CanvasViewer1.ScrollBarsStyle = Aurigma.GraphicsMill.AjaxControls.ScrollBarsStyle.Auto;

Notice, that you can specify the scroll bar style only in the server API.

On mobile devices, zooming and scrolling can be performed using gestures: the pinch and spread gestures zoom the content in/out, the two fingers scroll gesture scrolls the content:

These gestures work by default for all platforms supported by Graphics Mill Web Controls, namely: Android, iOS, and Windows RT.

See Also

Reference

• Canvas Class
• CanvasViewer Class
• ContentHeight Property
• ContentWidth Property
• Zoom Property
• ZoomMode Property
• ScrollingPosition Property
• ScrollBarWidth Property

Manual

• Layers and Objects

Other

• ScriptManager Class
• Saving and Rendering Canvas