How to Use AJAX Vector Objects

Client-server Interaction

In accordance with AJAX technique, this module consists of two parts: server-side - a set of ASP.NET controls and client-side - JavaScript implementation of these controls. The most of user actions, such as manipulations or transformations of layers and objects, are handled via JavaScript API allowing refreshing user-designed collages in a browser without page reloads. In this case client-side objects are affected by these actions only. If, however, a postback is initiated or a remote method is invoked the current state of client-side objects is serialized and sent to the server. Thus, client and server parts are always in synchronized state before any modifications of the server-side objects are performed.

Displaying Multi-layered Images

AJAX Vector Objects module includes two controls allowing you to display multi-layered images, namely CanvasViewer and VObjectsRubberband. The first one is an independent viewport control; however, the second one represents a rubberband which adds multi-layer support functionality to the BitmapViewer control. To familiarize with rubberbands read the Using Navigators and Rubberbands (AJAX Controls) topic.

Both the CanvasViewer and BitmapViewer with VObjectsRubberband implement almost the same functionality. They allow users to put multi-layered content to the viewport, zoom and scroll it. Also they are responsible for converting of control-related coordinates to workspace-related ones and vice versa. See the Displaying Image in BitmapViewer (AJAX Controls) topic for details.

The displayed content is represented with the Canvas accessible through the CanvasViewer.Canvas or VObjectsRubberband.Canvas properties. It is the main logical part of controls which contains a stack of layers. Additionally, it tracks changes of objects made by users as well as undoes and redoes them. The canvas also provides a functionality to save a layered image to a file layer by layer with a possibility to load it later and continue working with it. See the Opening and Saving Files section of this topic for the additional information about this feature.

Using Layers and V-objects

Adding and Removing Layers

The Canvas.Layers property returns a LayerCollection object which represents an array of Layer objects. The order of layers in this array defines the Z-order in which these layers will be displayed. The lesser value of the layer index, the lower is the layer.

To add a layer to the LayerCollection use the Add(Layer) or Insert(Int32, Layer) method.

CanvasViewer.Canvas.Layers.Add(New Aurigma.GraphicsMill.AjaxControls.VectorObjects.Layer())

CanvasViewer.Canvas.Layers.Add(new Aurigma.GraphicsMill.AjaxControls.VectorObjects.Layer());

var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
var layer = new Aurigma.GraphicsMill.AjaxControls.VectorObjects.Layer();
canvasViewer.get_canvas().get_layers().add(layer);

When the Layer is added to the canvas it initializes its Canvas property with the reference to the Canvas object it belongs to.

To remove a layer you need to pass its index or reference to Remove(Layer) or RemoveAt(Int32) method.

Dim currentLayer As Aurigma.GraphicsMill.AjaxControls.VectorObjects.Layer = _
 CanvasViewer.Canvas.CurrentLayer
If Not currentLayer Is Nothing Then
    CanvasViewer.Canvas.Layers.Remove(currentLayer)
End If

Aurigma.GraphicsMill.AjaxControls.VectorObjects.Layer currentLayer = 
    CanvasViewer.Canvas.CurrentLayer;
if (currentLayer != null)
    CanvasViewer.Canvas.Layers.Remove(currentLayer);

var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
var index = canvasViewer.get_canvas().get_currentLayerIndex();
if (index > -1)
    canvasViewer.get_canvas().get_layers().removeAt(index);

You can also reorganize layers using the Move(Int32, Int32) method.

Restricting Layers

By default, dimensions of a layer added to canvas equal to canvas ones. It means that users can put objects to any place of canvas. If, however, you need to bind some portion of canvas to a layer, for example to allow users to place object within the specified boundaries, use the Layer.Region property. This property accepts the RectangleRegion instance which defines a rectangular portion of canvas where objects can be placed.

Adding and Removing V-objects

Within a layer v-objects are organized into an array available through the Layer.VObjects property. This array is represented by the VObjectCollection class and the order of v-objects in this array defines theirs Z-order in the same manner as the order of layers.

V-objects can be added to a layer using the Add(VObject) and Insert(Int32, VObject) methods.

Dim rectangle As New Aurigma.GraphicsMill.AjaxControls.VectorObjects.RectangleVObject(100, 70, 100, 150)
CanvasViewer.Canvas.Layers.Item(0).VObjects.Add(rectangle)

Aurigma.GraphicsMill.AjaxControls.VectorObjects.RectangleVObject rectangle = new
        Aurigma.GraphicsMill.AjaxControls.VectorObjects.RectangleVObject(100, 70, 100, 150);
CanvasViewer.Canvas.Layers[0].VObjects.Add(rectangle);

var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
var layers = canvasViewer.get_canvas().get_layers();
var rectangle = new Aurigma.GraphicsMill.AjaxControls.VectorObjects.RectangleVObject(100, 70, 100, 150);
layers.get_item(0).get_vObjects().add(rectangle);

When creating a new v-object, for example a rectangle, the coordinates of its left-top corner and size are set in workspace-related coordinates. By analogy with layers, each v-object implements the Layer and Canvas properties which contain references to the Layer and Canvas objects this v-object is added to.

If you need to remove v-objects from the VObjectCollection use the Remove(VObject) or RemoveAt(Int32) method. Additionally, you can use the deleteCurrentVObject() client-side method to remove the currently selected v-object.

Dim currentObject As Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObject = _
 CanvasViewer.Canvas.CurrentVObject
If Not currentObject Is Nothing Then
    CanvasViewer.Canvas.CurrentLayer.VObjects.Remove(currentObject)
End If

Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObject currentObject = 
    CanvasViewer.Canvas.CurrentVObject;
if (currentObject != null)
    CanvasViewer.Canvas.CurrentLayer.VObjects.Remove(currentObject);

var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
canvasViewer.get_canvas().deleteCurrentVObject();

Accessing Layers and V-objects

When layers and v-objects are added to the LayerCollection and VObjectCollection respectively, they are accessible by their indices within these collections. These indices are additionally stored in the Layer.Index and VObject.Index properties.

Another way to access layers and v-objects is to use names specified with the Layer.Name and VObject.Name properties. You can set any strings for names of layers and objects using these properties. To access layers and v-objects by names use the following methods:

• LayerCollection.GetLayersByName(String) - scans this collection and returns an array of layers which match the specified name.
• LayerCollection.GetVObjectsByName(String) - scans all the layers within this collection and returns an array of v-objects which match the specified name.
• VObjectCollection.GetVObjectsByName(String) - scans this collection and returns an array of v-objects which match the specified name.

Additionally, the Canvas exposes the CurrentLayer and CurrentLayerIndex properties which return the currently selected layer and its index. By analogy, the CurrentVObject and CurrentVObjectIndex return the currently selected v-object and its index.

Modifying Layers and V-objects

Each layer and v-object can be locked or made invisible using the Layer.Locked/VObject.Locked and Layer.Visible/VObject.Visible properties respectively.

V-objects can be transformed using special control points displayed over an object when it is selected. The user just drags one of the control points and the selected object is resized or rotated depending on its type and state. In terms of AJAX Vector Objects these transformations are called actions and defined by the VObjectAction enumeration. To turn some actions on and off pass the corresponded fields to the VObject.SupportedActions property. The following actions are supported in AJAX Vector Objects:

• Drag (Drag);
• Rotate (Rotate);
• Resize (Resize, ProportionalResize, and ArbitraryResize).

Also you can enable or disable all actions using the All or None fields.

Protected Sub EnableActions_Click(ByVal sender As Object, ByVal e As EventArgs) Handles EnableActions.Click
    CanvasViewer.Canvas.CurrentVObject.SupportedActions = _
     Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObjectAction.All
End Sub

Protected Sub DisableActions_Click(ByVal sender As Object, ByVal e As EventArgs) Handles DisableActions.Click
    CanvasViewer.Canvas.CurrentVObject.SupportedActions = _
     Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObjectAction.None
End Sub

protected void EnableActions_Click(object sender, EventArgs e)
{
    CanvasViewer.Canvas.CurrentVObject.SupportedActions = 
        Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObjectAction.All;
}

protected void DisableActions_Click(object sender, EventArgs e)
{
    CanvasViewer.Canvas.CurrentVObject.SupportedActions = 
        Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObjectAction.None;
}

function enableActions_onclick() {
    var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
    var currentVObject = canvasViewer.get_canvas().get_currentVObject();
    currentVObject.set_supportedActions(Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObjectAction.all);
}

function disableActions_onclick() {
    var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
    var currentVObject = canvasViewer.get_canvas().get_currentVObject();
    currentVObject.set_supportedActions(Aurigma.GraphicsMill.AjaxControls.VectorObjects.VObjectAction.none);
}

Using History

The History is associated with the canvas through the Canvas.History property and allows tracking changes of its content. To turn this feature on set the History.Enable property to true value.

CanvasViewer.Canvas.History.Enable = True

CanvasViewer.Canvas.History.Enable = true;

After that if you need to undo or redo some action just call the Undo() or Redo() method.

Protected Sub UndoButton_Click(ByVal sender As Object, ByVal e As EventArgs) Handles UndoButton.Click
    CanvasViewer.Canvas.History.Undo()
End Sub

Protected Sub RedoButton_Click(ByVal sender As Object, ByVal e As EventArgs) Handles RedoButton.Click
    CanvasViewer.Canvas.History.Redo()
End Sub

protected void UndoButton_Click(object sender, EventArgs e)
{
    CanvasViewer.Canvas.History.Undo();
}

protected void RedoButton_Click(object sender, EventArgs e)
{
    CanvasViewer.Canvas.History.Redo();
}

function undoButton_onclick() {
    var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
    canvasViewer.get_canvas().get_history().undo();
}

function redoButton_onclick() {
    var canvasViewer = $find("<%= CanvasViewer.ClientID %>");
    canvasViewer.get_canvas().get_history().redo();
}

Opening and Saving Files

Saving and Opening Layered Images

AJAX Vector Objects allows you to save layered images layer by layer to files and then restore and continue working with them. This feature is implemented in the Canvas class with Serialize() and Deserialize(String) methods.

When you call the Serialize() method it returns the content of the Canvas serialized into JSON formatted string. Thus, to store this data you can simply save this string into a file.

Dim serializedString As String = CanvasViewer.Canvas.Serialize()
Dim serializedData As Byte() = System.Text.Encoding.ASCII.GetBytes(serializedString)
Dim fs As New System.IO.FileStream(Server.MapPath("tmp.vobj"), System.IO.FileMode.Create, _
 System.IO.FileAccess.Write)
fs.Write(serializedData, 0, serializedData.Length)
fs.Close()

string serializedString = CanvasViewer.Canvas.Serialize();
byte[] serializedData = System.Text.Encoding.ASCII.GetBytes(serializedString);
System.IO.FileStream fs = new System.IO.FileStream(Server.MapPath("tmp.vobj"), 
    System.IO.FileMode.Create, System.IO.FileAccess.Write);
fs.Write(serializedData, 0, serializedData.Length);
fs.Close();

Then if you need to restore your layered image just open this file and pass its content to the Deserialize(String) method.

Dim fs As New System.IO.FileStream(Server.MapPath("tmp.vobj"), System.IO.FileMode.Open, _
 System.IO.FileAccess.Read)
Dim serializedData(fs.Length - 1) As Byte
fs.Read(serializedData, 0, serializedData.Length)
Dim serializedString As String = System.Text.Encoding.ASCII.GetString(serializedData)
CanvasViewer.Canvas.Deserialize(serializedString)
fs.Close()

System.IO.FileStream fs = new System.IO.FileStream(Server.MapPath("tmp.vobj"), 
    System.IO.FileMode.Open, System.IO.FileAccess.Read);
byte[] serializedData = new byte[fs.Length];
fs.Read(serializedData, 0, serializedData.Length);
string serializedString = System.Text.Encoding.ASCII.GetString(serializedData);
CanvasViewer.Canvas.Deserialize(serializedString);
fs.Close();

Rendering Bitmap

The Canvas also provides the RenderWorkspace(Single, ColorSpace) method which returns its content as a Bitmap object. It means that you can save the layered image as a bitmap in one of the graphic formats supported by Graphics Mill for .NET.

Dim bitmap As Aurigma.GraphicsMill.Bitmap = CanvasViewer.Canvas.RenderWorkspace(72, _
 Aurigma.GraphicsMill.ColorSpace.Rgb)
bitmap.Save(Server.MapPath("tmp.jpg"))
bitmap.Dispose()

Aurigma.GraphicsMill.Bitmap bitmap = CanvasViewer.Canvas.RenderWorkspace(72, 
    Aurigma.GraphicsMill.ColorSpace.Rgb);
bitmap.Save(Server.MapPath("tmp.jpg"));
bitmap.Dispose();

See Also

Reference

• CanvasViewer Class
• VObjectsRubberband Class
• Canvas Class
• Layer Class
• ImageVObject Class
• RectangleVObject Class
• EllipseVObject Class
• TextVObject Class

Manual

• Quick Start in AJAX Vector Objects
• Basic Concepts of AJAX Vector Objects
• Gift Editor Demo Overview
• Displaying Image in BitmapViewer (AJAX Controls)
• Using Navigators and Rubberbands (AJAX Controls)