Class: cWebDrawing
Properties | Events | Methods | Index of Classes
Allows drawing on a canvas in web applications
Hierarchy
cObject > cWebBaseObject > cWebObject > cWebBaseUIObject > cWebBaseDEOServer > cWebBaseControl > cWebDrawing
Show full hierarchy and direct subclasses
Library: Web Application Class Library
Package: cWebDrawing.pkg
Description
Allows drawing on a canvas in web applications.
What is a Canvas?
You can see a canvas as a piece of paper with a robot hand attached to it. Using the component, you send instructions to the browser for the robot to draw. This could be a rectangle, a circle, or a line. When such a shape is drawn, you can style it. You can set things like the fill and outline color, also known as the stroke color, or the outline (stroke) width.
Initializing a Canvas
When the canvas is first loaded, it will fire the OnLoad event. This event can then be used to draw on the canvas. If you draw on the canvas before, the drawing will not render. The best way to draw things on the canvas is to put the instructions into a procedure. After you have written the instructions for the component to draw, you call UpdateDrawing to update the drawing on the browser side.
When changing something on a canvas after clicking, you can use the Drawing Events. With these events, you can manipulate a shape after it has already been drawn on the browser. Events like OnMouseClick will fire when the user clicks on a shape or group of shapes.
Creating Shapes
Simple Shapes
You can create simple shapes using CreateRectangle, CreateCircle, CreateEllipse, and CreateLine. You can use StrokeColor, StrokeWidth, ShadowBlur, ShadowColor, ShadowOffset and/or FillColor to style these shapes.
Advanced Shapes
Paths are a bit of a special type of shape. Creating a path on its own will result in nothing. You must tell the path where to go. Using the procedures PathAdd, MoveTo, LineTo, QuadraticCurveTo and ClosePath, you can tell the drawing how and where the path should be drawn. The path has been designed to use StrokeWidth, StrokeColor and FillColor (On a closed path using ClosePath at the end) to style the path.
When using the MoveTo path instruction, the path will create a new sub path. You can then use LineTo repeatedly to draw a line to one or more points.
The PathAdd procedure is a shorthand for both the MoveTo and LineTo procedures. When starting, it will move the cursor to the first position. After that, it will draw lines between the following points.
Text
You can create text on the canvas by using CreateText. Text on the canvas can be styled the same way as regular shapes. For example, StrokeColor, StrokeWidth, ShadowBlur, ShadowOffset, ShadowColor and FillColor are all applicable for the text on the canvas. StrokeColor in this case determines the color of the outline of the letters. StrokeWidth will determine the thickness of this outline. FillColor will color all the space inside of the outlines.
Shadows can be used to cast a faint shadow behind the text. Multiple styling options are available. ShadowColor will determine the color of the shadow. ShadowBlur will determine the area of the shadow, the higher the value the bigger the shadow will be. However it should be noted that the shadow gets more faint as it spreads a larger area, so a blur with a high value will not be as visible as a blur with a lower value. ShadowOffset will determine the place of the shadow. The x parameter will determine how much more to the right the shadow will be, the y parameter will determine how much lower the shadow will be.
The sFontFamily parameter sets the regular CSS font property of a text object. This means that whichever fonts are available in your browser will also be available within the canvas. More information about what fonts can be used can be found here.
It is possible to style your text by making it bold or lighter. To do this you can pass "bold" or "lighter" in the sFontWeight parameter. Or, alternatively you can use the TextDecoration procedure.
Images and SVGs
Using CreateImage and CreateSVG, you can import an existing image on to the drawing. The path parameter will accept any valid URL. When using a local image from the browser, the image will be relative to the AppHTML folder.
CreateImage and CreateSVG expect one or two parameters for positioning aside from the path variable. One position and one size. If the size parameter is not defined, it will use the original size of the image and use the position as the center position, otherwise it will size the image according to what you have defined.
Groups and Layers
Groups is a way to put together several different shapes and let them behave as a single shape. Layers can determine in which order shapes and groups are drawn. Groups are a more advanced version of a layer. You can move, rotate, and scale a layer using the Rotation, Scaling and Position procedures. Layers can only be made visible or invisible using SetVisibility or ToggleVisibility. Groups are an effective way to style multiple shapes using one line of code. For example, if a group exists with the name "Group", that has 5 circles inside of it called A, B, C, D and E. It is possible to change the FillColor of "Group" to black. Which would also set the fill color of the circles A, B, C, D and E to black.
It is still possible to style individual components that are part of a group. If we expand on the previous example and would set the FillColor of C to red, circles A, B, D and E will remain black, but the circle C will now have a red FillColor.
You can start to create a group using CreateGroup or CreateLayer. After that, you can insert shapes or subgroups into the group. To end a group, you must call EndCreateGroup or EndCreateLayer.
Helper Functions
There are a few helper functions available. These functions are: XYPoint XYPoint is used to set the position of a parameter. The functions accept two float parameters, the x value, and the y value. The function will take these two parameters and put them in to a tWebPoint struct. This struct can then be used with all procedures that require a tWebPoint parameter. WHSize WHSize is used to define the size of a shape. The function accepts two float parameters, the width and the height value. This helper can be used in functions like CreateRectangle, CreateEllipse and ScalingHV. GDIColorToHex GDIColorToHex will convert a GDI color value and convert it into a CSS HEX value. This can be used to set a color of a shape using the StrokeColor, FillColor or ShadowColor procedure. However, it should be noted that passing colors can be done in multiple ways:
Passing color as rgba It is possible to pass a color as a rgba value. This allows you to pick a very specific color along with opacity. Send FillColor "id" "rgba(255, 0, 0, 0.5)"
Passing colors as strings It is also possible to pass colors as a string value. Send FillColor "id" "black"
Passing colors as hex values Send FillColor "id" (GDIColorToHex(clBlack))
Examples
Drawing and Styling Shapes
cWebDrawing has several methods that allow you to create simple shapes and import images. These methods are CreateRectangle, CreateCircle, CreateEllipse, CreatePath, CreateLine, CreateImage, CreateSVG, CreateText, ImportDrawingJsonData.
For the first example, we will create a smiley face consisting of several different shapes. In this case, we are using the Circle and Path shapes.
First, we create the base object to draw on. We set the size of the drawing using piDrawingWidth and piDrawingHeight. After that, we create a procedure that will contain the code to create the face, called CreateSmiley. To make sure the drawing draws correctly when the page loads, we will call the function from the OnLoad event.
Object oWebDrawing is a cWebDrawing
Set piDrawingWidth to 500
Set piDrawingHeight to 500
Procedure CreateSmiley
// The creation of the shape will go here
End_Procedure
Procedure OnLoad
Send CreateSmiley
End_Procedure
End_Object
Second, for the face, we will first create a circle using CreateCircle. The center position of this circle will be x 250 and y 250, starting from the top left of the screen, with a radius of 50. We will make the width of the outline of the circle 5 wide and set the color to the hexadecimal representation of black.
Object oWebDrawing is a cWebDrawing
Set piDrawingWidth to 500
Set piDrawingHeight to 500
Procedure CreateSmiley
// Create the face
Send CreateCircle "face" (XYPoint(250, 250)) 50
Send StrokeColor "face" "#000000"
Send StrokeWidth "face" 5
Send UpdateDrawing
End_Procedure
Procedure OnLoad
Send CreateSmiley
End_Procedure
End_Object
Third, we create two eyes called left-eye and right-eye. The left eye will be located a bit to the left in the face circle and the right slightly to the right. We will make the radius of both circles 5 pixels wide and the fill color black.
Object oWebDrawing is a cWebDrawing
Set piDrawingWidth to 500
Set piDrawingHeight to 500
Procedure CreateSmiley
Send CreateCircle "face" (XYPoint(250, 250)) 50
Send StrokeColor "face" "#000000"
Send StrokeWidth "face" 5
// Create the eyes
Send CreateCircle "left-eye" (XYPoint(230, 230)) 10
Send FillColor "left-eye" "#000000"
Send CreateCircle "right-eye" (XYPoint(270, 230)) 10
Send FillColor "right-eye" "#000000"
Send UpdateDrawing
End_Procedure
Procedure OnLoad
Send CreateSmiley
End_Procedure
End_Object
Lastly, we will create the mouth. This will be a path with a curve. First, we create the path using CreatePath. Then we move the cursor to position 230 270. After that, we create a curved line using QuadraticCurveTo. The first value of this procedure is where the curve should lean towards, the second value is the position of the end of the line. We will make the color black and the width 1.
Object oWebDrawing is a cWebDrawing
Set piDrawingWidth to 500
Set piDrawingHeight to 500
Procedure CreateSmiley
Send CreateCircle "face" (XYPoint(250, 250)) 50
Send StrokeColor "face" "#000000"
Send StrokeWidth "face" 5
Send CreateCircle "left-eye" (XYPoint(230, 230)) 10
Send FillColor "left-eye" "#000000"
Send CreateCircle "right-eye" (XYPoint(270, 230)) 10
Send FillColor "right-eye" "#000000"
// Create the mouth
Send CreatePath "mouth"
Send MoveTo "mouth" (XYPoint(230, 270))
Send QuadraticCurveTo "mouth" (XYPoint(250, 300)) (XYPoint(270, 270))
Send StrokeColor "mouth" "#000000"
Send StrokeWidth "mouth" 1
Send UpdateDrawing
End_Procedure
Procedure OnLoad
Send CreateSmiley
End_Procedure
End_Object
Altering Shapes
We can also manipulate shapes and groups after they have been created. Using Procedures like Position, Rotation, Scaling and ScalingHV, you can reposition, rotate, and resize an item on the canvas.
In this case, we will create a simple red rectangle using the CreateRectangle procedure that starts at position 100 100 with a width of 100 and a height of 50. We will also make the color red. Note that we use the word red here instead of a hex value. This is because the color string will accept CSS color values, you can read more about them here on the MDN developer reference.
After the square has been created, we will rotate the square by 45 degrees clockwise. The result will be a rectangle rotated 45 degrees clockwise.
Object oWebDrawing is a cWebDrawing
Set piDrawingWidth to 500
Set piDrawingHeight to 500
Procedure OnLoad
Send CreateSquare
End_Procedure
Procedure CreateSquare
// Create Square
Send CreateRectangle "square" (XYPoint(100, 100)) (WHSize(100, 50))
Send FillColor "square" "red"
// Rotate square
Send Rotation "square" 45
Send UpdateDrawing
End_Procedure
End_Object
Receiving Events
The Web Canvas has several different events available for handling mouse and canvas interaction. These events are OnMouseDown, OnMouseUp, OnMouseEnter, OnMouseLeave, OnMouseMove, OnMouseClick, OnMouseDoubleClick, OnMouseDrag, OnResize, OnReceiveImage, OnReceiveJsonExport.
All mouse events include two parameters, one for the id of the item being clicked and another for data related to the item being clicked. Mouse events must be enabled per shape first using EnableInteraction. If you want to disable an interaction later, you can use DisableInteraction to do so.
For this example, we will use the square from the previous example. We create an event handler called OnMouseClick within the oWebDrawing object. We will also make sure the OnMouseClick interaction is enabled using EnableInteraction. This event will receive the OnMouseClick event of every shape with the id of the shape being clicked on including extra data like position and fill color. You can read more about it on the tWebDrawingEventData struct.
When you receive the event, you can match the sId with the correct id of your choosing. With this, we rotate the rectangle by 45 degrees clockwise each time we click the rectangle.
Object oWebDrawing is a cWebDrawing
Set piDrawingWidth to 500
Set piDrawingHeight to 500
Procedure OnLoad
Send DrawOnCanvas
End_Procedure
Procedure DrawOnCanvas
Send CreateRectangle "rectangle" (XYPoint(100, 100)) (WHSize(100, 50))
Send EnableInteraction "rectangle" wdInteractionOnMouseClick
Send FillColor "rectangle" "red"
Send UpdateDrawing
End_Procedure
Procedure OnMouseClick String sId tWebDrawingEventData eventData
If (sId = "rectangle") Begin
Float fNewRotation
Move eventData.fRotation to fNewRotation
Move (fNewRotation + 45) to fNewRotation
Send Rotation "rectangle" fNewRotation
Send UpdateDrawing
End
End_Procedure
End_Object