Skip to content

cWebDrawing Class

This document describes the cWebDrawing component. For complete help for this class, see the cWebDrawing reference: cWebDrawing.

cWebDrawing

Overview

cWebDrawing allows you to draw on a canvas using only DataFlex code. It provides procedures for creating and manipulating shapes (rectangles, circles, lines, paths, text, images and SVGs), grouping shapes, styling (stroke, fill, shadow), and handling mouse/canvas events.

You can think of the canvas as a piece of paper with a robot hand attached to it. Your code sends drawing instructions to the browser; the browser executes those instructions and renders shapes. After preparing your drawing instructions on the server side, call UpdateDrawing to send them to the browser.

See the WebOrder sample workspace under Demo > Controls > Drawing to see cWebDrawing in action.

Drawing lifecycle

  • The canvas fires the OnLoad event when first loaded. Use OnLoad to issue your initial drawing instructions; drawing commands issued before the canvas has loaded will not render.
  • Put drawing instructions in a procedure and call UpdateDrawing after you finish preparing the instructions to have them rendered on the browser side.
  • To modify shapes after they are drawn, use the drawing events (mouse events). Mouse events work only for shapes that have interaction enabled (EnableInteraction).

Basic shapes

You can create simple shapes with:

  • CreateRectangle
  • CreateCircle
  • CreateEllipse
  • CreateLine

Use styling procedures to adjust appearance:

  • StrokeColor, StrokeWidth, StrokeCap, StrokeJoin, StrokeDash, DashOffset
  • FillColor
  • ShadowBlur, ShadowColor, ShadowOffset

(Refer to the Procedures section below for details.)

Paths

Paths are a special type of shape. Creating a path alone does nothing — you must add points or subpaths:

  • PathAdd — shorthand for MoveTo then repeated LineTo calls.
  • MoveTo — starts a new subpath.
  • LineTo — draws a line from the current point to the given point.
  • QuadraticCurveTo — draws a quadratic curve (with a control/through point and an end point).
  • ClosePath — closes the current path (useful when you want to fill the path).

Style a path with StrokeWidth, StrokeColor and FillColor (filling works when the path is closed).

Text

Create text using CreateText. Text styling uses many of the same properties available to shapes:

  • StrokeColor — outlines the letters.
  • StrokeWidth — thickness of the outline.
  • FillColor — fills the interior of the letters.
  • ShadowColor, ShadowBlur, ShadowOffset — control the shadow.
  • sFontFamily — regular CSS font family (browser-available fonts). See MDN for font CSS: https://developer.mozilla.org/en-US/docs/Web/CSS/font
  • sFontWeight — e.g., "bold", "lighter" or use TextDecoration for decoration options.

Shadows: ShadowColor determines color; ShadowBlur determines blur radius (larger value spreads more but fades visibility); ShadowOffset uses an x/y offset (x shifts right, y shifts down).

Images and SVG

  • CreateImage and CreateSVG import external images/SVGs. sPath accepts any valid URL. For local images used by the browser, the path is relative to the AppHTML folder.
  • Positioning: Both procedures accept one or two position parameters. If only one position is provided, that position is the image center and the original image size is used. If a second position is provided, the image scales to the rectangle defined by the two points.

Groups and Layers

  • Groups let you combine several shapes so they behave like a single shape (apply transforms and styles to the group).
  • Layers determine drawing order. Layers are simpler than groups; layers can generally be made visible/invisible (SetVisibility/ToggleVisibility) and moved/rotated/scaled.
  • CreateGroup / EndCreateGroup and CreateLayer / EndCreateLayer are used to build nested structures.
  • Styling a group affects all child shapes unless individual children are styled afterwards. E.g., setting FillColor on a group changes the fill color of its children unless a child overrides it.

Helper functions

  • XYPoint(fX, fY) — returns a tWebPoint struct.
  • WHSize(fWidth, fHeight) — returns a tWebSize struct.
  • GDIColorToHex(iColor) — converts a GDI color to a CSS HEX string.

Color passing examples:

  • rgba: Send FillColor "id" "rgba(255, 0, 0, 0.5)"
  • name string: Send FillColor "id" "black"
  • hex via helper: Send FillColor "id" (GDIColorToHex(clBlack))

Creating shapes — procedures

The component provides many procedures to create shapes and import images/SVGs. Below are examples and usage.

Example — Smiley face (step by step)

Place the creation code inside a procedure and call it from OnLoad.

1) Base object and setup:

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

2) Create the face circle:

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 UpdateDrawing
    End_Procedure

    Procedure OnLoad
        Send CreateSmiley
    End_Procedure
End_Object

3) Add eyes:

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

4) Create the mouth with a quadratic curve:

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

5) Grouping the face:

// ...
Send CreateGroup "smiley" // Begin of smiley group

// ... create shapes inside the group ...

Send EndCreateGroup "smiley" // End of smiley group
// ...

After grouping, setting styling on "smiley" affects its children (unless children override the style).

Example — Rotate a rectangle on click

Create a rectangle, enable click interaction, and rotate it by 45 degrees every click:

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

Events (mouse and canvas)

The Web Canvas supports these events:

  • OnMouseDown
  • OnMouseUp
  • OnMouseEnter
  • OnMouseLeave
  • OnMouseMove
  • OnMouseClick
  • OnMouseDoubleClick
  • OnMouseDrag
  • OnResize
  • OnReceiveImage
  • OnReceiveJsonExport

All mouse events receive two parameters: the item ID and event data (tWebDrawingEventData). Mouse events must be enabled per-shape using EnableInteraction (and can be disabled via DisableInteraction).

Component properties

Name Description Default
peDrawingJustification Set the justification of the drawing. wdDrawingJustificationLeft
piDrawingWidth The width of the canvas (drawing coordinate width). 0
piDrawingHeight The height of the canvas (drawing coordinate height). 0
peResizeMode Mode to handle resize changes. See wdResizeMode. When wdResizeModeScale is selected, the developer must define piDrawingWidth and piDrawingHeight. When wdResizeModeCrop is selected, piDrawingWidth/piDrawingHeight are ignored. wdResizeModeDisabled
pbNoContextMenu Disable the right-click context menu. False
pbZoomable Enable zooming and panning. False
pfMinZoom Minimum zoom (cannot go below zero). 0.125
pfMaxZoom Maximum zoom. 4
pfDefaultZoom Default zoom. 1
pbClientOnResize Enable the client OnResize event. False
pbDebugOutline Enable the debug outline for the canvas component. False
piDebugOutlineWidth Size of the debug outline. 1
psDebugOutlineColor Color of the debug outline. (not specified)
psCanvasBackgroundColor Background color of the canvas. (not specified)

Global functions

XYPoint

Type: Global Function
Description: Put two floats in a tWebPoint struct

Parameters: - fX (Float) — The x value - fY (Float) — The y value

Returns: tWebPoint

WHSize

Type: Global Function
Description: Put two floats in a tWebSize struct

Parameters: - fWidth (Float) — Width - fHeight (Float) — Height

Returns: tWebSize

GDIColorToHex

Type: Global Function
Description: Convert a clColor (GDI color) to a CSS HEX string

Parameters: - iColor (Integer) — The cl color value

Returns: String (CSS HEX)

Procedures (summary)

Below is a list of key procedures. Each procedure's parameters are described where applicable.

  • UpdateDrawing

  • Description: Send new instructions for the client to draw.

  • CreateRectangle(sId, position, size, fCornerRadius)

  • sId (String) — ID of the item
  • position (tWebPoint) — Top-left position
  • size (tWebSize) — Size of the rectangle

  • fCornerRadius (Float) — Corner radius

  • CreateCircle(sId, centerPosition, fRadius)

  • centerPosition (tWebPoint), fRadius (Float)

  • CreateEllipse(sId, centerPosition, size)

  • size (tWebSize)

  • CreatePath(sId)

  • Starts a path with ID sId.

  • CreateLine(sId, firstPosition, secondPosition)

  • Draws a straight line between two points.

  • CreateImage(sId, sPath, firstPosition, secondPosition?)

  • sPath (String) — Path to image file (relative to AppHTML for local files)
  • firstPosition (tWebPoint) — Center point if secondPosition not provided

  • secondPosition (tWebPoint, optional) — If provided, scales the image between the two points

  • CreateSVG(sId, sPath, firstPosition, secondPosition?)

  • Same positioning behavior as CreateImage.

  • CreateText(sId, position, sContent, sFontFamily, fFontSize, eJustification?, sFontWeight?, sTextDecoration?)

  • eJustification (Integer) — See wdFontJustification

  • CreateLayer(sId) / EndCreateLayer(sId)

  • Create and end a layer.

  • CreateGroup(sId) / EndCreateGroup(sId)

  • Create and end a group.

  • Delete(sId)

  • Delete an item or group from the canvas.

  • PathAdd(sId, position)

  • Add a point to a path (shorthand behavior: MoveTo first then LineTo for subsequent points).

  • MoveTo(sId, position)

  • Start a new subpath at position.

  • LineTo(sId, position)

  • Draw a line from previous point to position.

  • QuadraticCurveTo(sId, troughPoint, toPoint)

  • Draw a quadratic curve with trough/control point and endpoint.

  • ClosePath(sId)

  • Close the current path.

  • StrokeWidth(sId, fWidth)

  • Set stroke width.

  • StrokeColor(sId, sColor)

  • Set stroke color (CSS color string).

  • StrokeCap(sId, eStrokeCap)

  • Set stroke cap type (wdStrokeCap*).

  • StrokeJoin(sId, eStrokeJoin)

  • Set stroke join type (wdStrokeJoin*).

  • DashOffset(sId, fOffset)

  • Set dash offset.

  • StrokeDash(sId, iLineDistance, iWhitespaceDistance?)

  • Create dashed stroke (line length and optional whitespace length).

  • Tooltip(sId, sTooltip)

  • Create tooltip content.

  • FillColor(sId, sColor)

  • Set fill color.

  • ShadowColor(sId, sColor)

  • Set shadow color.

  • ShadowBlur(sId, fBlurAmount)

  • Set shadow blur amount.

  • ShadowOffset(sId, Offset)

  • Set shadow offset (tWebPoint).

  • TextContent(sId, sContent)

  • Set text content.

  • TextFontFamily(sId, sFontFamily)

  • Set font family.

  • TextFontSize(sId, fSize)

  • Set font size.

  • TextFontWeight(sId, sFontWeight)

  • Set font weight (e.g., normal, bold, bolder, lighter).

  • TextDecoration(sId, sTextDecoration)

  • e.g., underline, overline, line-through.

  • TextJustification(sId, eJustification)

  • See wdFontJustification.

  • Position(sId, position)

  • Set item position.

  • Rotation(sId, fAngle, bRotateInPlace?)

  • fAngle in degrees clockwise (negative = counterclockwise).

  • bRotateInPlace (Boolean) — optional: rotate in place vs around canvas/group.

  • Scaling(sId, fScale)

  • Uniform scale (1 = 100%).

  • ScalingHV(sId, scale)

  • Non-uniform horizontal/vertical scaling via tWebSize.

  • SetVisibility(sId, bVisible)

  • Set visibility.

  • ToggleVisibility(sId)

  • Toggle visibility.

  • EnableInteraction(sId, eInteraction)

  • Enable an interaction (see wdInteraction constants).

  • DisableInteraction(sId, eInteraction)

  • Disable an interaction.

  • ExportImage

  • Export canvas to PNG; result received in OnReceiveImage event as Base64.

  • ExportJson

  • Export canvas data as JSON; result received in OnReceiveJsonExport event.

Events (detailed)

Each event procedure typically has the signature:

Procedure OnEventName String sId tWebDrawingEventData eventData

Where: - sId (String) — ID of the item - eventData (tWebDrawingEventData) — event-related data

Event list: - OnMouseDown(sId, eventData) - OnMouseUp(sId, eventData) - OnMouseEnter(sId, eventData) - OnMouseLeave(sId, eventData) - OnMouseMove(sId, eventData) - OnMouseClick(sId, eventData) - OnMouseDoubleClick(sId, eventData) - OnMouseDrag(sId, eventData) - OnReceiveImage(sDataBase64) — PNG data as Base64 string - OnReceiveJsonExport(sJsonData) — JSON string of canvas data - OnResize(sId, resizeEventData) — resize event data (tWebDrawingResizetData)

Structs

tWebDrawingEventData

Type: Struct — Event data passed to mouse events

Members: - tMousePosition (tWebPoint) — position of the mouse - eMouseButtons (Integer) — mouse button being pressed (wdMouseButton*) - tPosition (tWebPoint) — position of the item - fRotation (Float) — rotation of the item - sStrokeColor (String) - fStrokeWidth (Float) - iStrokeCap (Integer) - iStrokeJoin (Integer) - fDashOffset (Float) - sTextContent (String) - sFontFamily (String) - fFontSize (Float) - eJustification (Integer) - sFontWeight (String) - sTextDecoration (String)

tWebDrawingResizetData

Type: Struct — Resize event data

Members: - fViewWidth (Float) — current width of the canvas view - fViewHeight (Float) — current height of the canvas view

tWebPoint

Type: Struct — A point on the canvas

Members: - fX (Float) — X coordinate - fY (Float) — Y coordinate

tWebSize

Type: Struct — Size of a shape

Members: - fWidth (Float) - fHeight (Float)

Enums / Constants

wdDrawingJustification

  • wdDrawingJustificationLeft — left justify drawing
  • wdDrawingJustificationCenter — center justify drawing
  • wdDrawingJustificationRight — right justify drawing

wdResizeMode

  • wdResizeModeDisabled — keep original canvas size
  • wdResizeModeScale — scale the canvas to fit available space (requires piDrawingWidth & piDrawingHeight)
  • wdResizeModeCrop — resize drawing area to fit available space

Mouse buttons

  • wdMouseButtonNone
  • wdMouseLeftButton
  • wdMouseMiddleButton
  • wdMouseRightButton

wdStrokeCap

  • wdStrokeCapRound
  • wdStrokeCapSquare
  • wdStrokeCapButt

wdStrokeJoin

  • wdStrokeJoinMiter
  • wdStrokeJoinRound
  • wdStrokeJoinBevel

wdFontJustification

  • wdFontJustificationLeft
  • wdFontJustificationCenter
  • wdFontJustificationRight

wdInteraction

  • wdInteractionOnMouseDown
  • wdInteractionOnMouseUp
  • wdInteractionOnMouseEnter
  • wdInteractionOnMouseLeave
  • wdInteractionOnMouseMove
  • wdInteractionOnMouseClick
  • wdInteractionOnMouseDoubleClick
  • wdInteractionOnMouseDrag

References: - MDN: CSS font — https://developer.mozilla.org/en-US/docs/Web/CSS/font - MDN: CSS color values — https://developer.mozilla.org/en-US/docs/Web/CSS/color_value