CapeSoft.Com
Clarion Accessories
Draw
Documentation
DrawPaint
CapeSoft Logo

CapeSoft DrawPaint
Documentation

Installed Version Latest Version
Download Latest Version JumpStart FAQ History

TheDrawPaint Class

The CapeSoft DrawPaint class allows the end user to place objects (such circles and boxes, images, text etc.) onto a Draw control, and then allow the user select and manipulate those object visually. For example a box can be placed on the control by clicking with the mouse, and the box can later be selected, resized, the properties changed etc. It allows the order of objects on the control to be change, and any object to be selected simply by clicking on the control with the mouse.

This provides a tremendous amount of functionality without doing a large mount of coding.

Getting Started - Adding a DrawPaint Control

Adding a DrawPaint control is as simple as populating a Draw control onto the window and setting the based class to DrawPaint.

  1. Add a Draw control normally (place an image control on the window and choose Draw as the control type).
  2. Right click on the control and choose Actions. In the Use a custom base class field enter DrawPaint.
  3. Add a Region control to the window that overlaps the Draw image control and is the same size. Set the region Immediate property on. This allows events to be handled (future versions will remove this requirement). Right click on the Region control and go to Embeds. In the All Events embed add the line of code:

    Drawer.TakeEvent()
    Where Drawer is the name of your DrawPaint object.

Hand coding the class declaration

If you are hand coding the class declaration then simply use the DrawPaint class instead of Draw. Draw is a parent of DrawPaint, so all the existing Draw methods continue to work in exactly the same manner as they do when using Draw:

Drawer            class(DrawPaint)
                  end

Getting Started - The Basic of Using DrawPaint

DrawPaint is as simple as populating a queue with "objects" that you wish to be drawn. These objects can be shapes such as boxes and ellipses, text strings, or images. The type member of the DrawPaint.ItemQueue determines the object type. This should be set to the same type as the Clarion Create would be passed to create that type of control. For example create:box for a rectangular box, create:image for an image, or create:string for a string (text) object.

Once the queue properties have been set the AddItem is called to add the item to the ItemQueue, and once the queue is populate the DrawItems method is used to display the items.

Example

DrawPaint Method Reference

DrawPaint Methods
AddItem Add an item to the queue of items
AlignBottom Align selected items bottom
AlignLeft Align selected items left
AlignRight Align selected items right
AlignTop Align selected items top
CalcStringDims Calculates the width and height of a string
Construct Called when the object comes into scope
CopyItems Copies the selected items so that they can be pasted
DeleteItem Deletes an item
Destruct Called when the object leaves scope
DrawHighlightBox Draws a highlight (selection indicator)
DrawHighlights Draws the highlighting for all selected items
DrawItems Draws all the items in the queue
FindParent Find parent for the item
GetAltPicture Returns a display picture - embed code here to set returnvalue
HideHighlight Hides the highlight (selection) layer
Init Initializes the object and control
InResizeCorner Determines whether the cursor is over the resize area of a selected item
ItemClicked Called when an item was clicked on
Kill Cleans up frees allocated memory
MakeSameHeight Makes all selected items the same height
MakeSameSize Makes all selected items the same size
MakeSameWidth Makes all selected items the same width
MoveItems Moves all selected items by the amount specified
PasteItems Pastes a copy of any items that have been copied by calling CopyItems
PicExample Returns an example text (as seen while editing clarion reports - e.g. $$$$$$$$$$ for a string) for the supplied picture
RedrawHighlightBox Draws the highlight after an object has moved
Reset Reset the layers used for drawing
ResizeItem Resizes and item
SaveHighlightPos Saves a new highlight position for an item
SetCanvasSize Resizes and clears the canvas and all used layers
SetCursor Sets or resets the cursor
SetGrid Redraws or hides the grid layer
SortItems Sorts the items based on the z-order
SpreadHorizontally Spreads out the selected items evenly horizontally
SpreadVertically Spreads out the selected items evenly vertically
TakeClickEvent Called when the user clicks on the control
TakeDragEvent Called when the user clicks and drags
TakeDropEvent Called when the user releases the mouse button after clicking and dragging.
TakeEvent Called when the control receives an event
TakeResizeEvent Called to handle a resize event
WithItem Selects a particular item from the queue

AddItem

AddItem (Long zOrder = 0), long, proc

Description

Adds an item to the internal queue of items (objects) on the canvas. The Itemqueue queue must be populated with the settings for the object before AddItem() is called to add the item. Entries should not be added to the queue manually.

Parameters
Parameter Description
zOrder Determines the order in which the object is drawn, object with a low z-order are drawn first, and object with a higher z-order are draw on top of them. The higher the z-order the higher up the "stack" the object is.
Return Values

Returns 1 for success and zero for failure. If the method fails it calls ErrorTrap() with an error description.

Remarks

Use the zOrder to specify an order other than the creation order for displaying the item. The zOrder determines which item is topmost and which is bottommost. All other settings should be done using the ItemQueue properties.

Examples
Add a String
Drawer.ItemQueue.type = create:string
Drawer.ItemQueue.TextValue = 'Hello World!'
Drawer.ItemQueue.FontName = 'Tahoma'
Drawer.ItemQueue.xpos = 20
Drawer.ItemQueue.FontColor = color:black
Drawer.ItemQueue.FontSize = Random(12, 32)
Drawer.ItemQueue.ypos = 10 + Drawer.ItemQueue.FontSize * 2
Drawer.ItemQueue.FontStyle = Choose(Random(1,3), font:regular, font:bold, font:italic)
Drawer.AddItem()
Add an Image
Drawer.Logging = 1
Drawer.ItemQueue.type = create:image
Drawer.ItemQueue.xpos = 120
Drawer.ItemQueue.ypos = 120
Drawer.ItemQueue.TextValue = 'capesoft.bmp'
Drawer.AddItem()
Add a Box
Drawer.ItemQueue.type = create:box
Drawer.ItemQueue.xpos = 50
Drawer.ItemQueue.ypos = 250
Drawer.ItemQueue.width = 300
Drawer.ItemQueue.height = 200
Drawer.ItemQueue.BoxBorderColor = Random(0F00F0Fh, 0FFFFFFh)
Drawer.ItemQueue.BoxFillColor = Random(00F0F0Fh, 0FFFFFFh)
Drawer.AddItem()
Add a Line
Drawer.ItemQueue.type = create:line
Drawer.ItemQueue.xpos = 100
Drawer.ItemQueue.ypos = 15
Drawer.ItemQueue.width = 100
Drawer.ItemQueue.height = 100
Drawer.ItemQueue.LineColor = Random(0F0F0Fh, 0FFFFFFh)
Drawer.ItemQueue.LineStyle = Choose(Random(1, 3), pen:solid, pen:dash, pen:dot)
Drawer.AddItem()
Add an Ellipse
Drawer.ItemQueue.type = create:ellipse
Drawer.ItemQueue.xpos = 305
Drawer.ItemQueue.ypos = 35
Drawer.ItemQueue.width = 400
Drawer.ItemQueue.height = 250
Drawer.ItemQueue.BoxBorderColor = Random(0F0F0Fh, 0FFFFFFh)
Drawer.ItemQueue.BoxFillColor = Random(0F0F0Fh, 0FFFFFFh)
Drawer.AddItem()
Add an Arc
Drawer.ItemQueue.type = create:arc
Drawer.ItemQueue.xpos = 20
Drawer.ItemQueue.ypos = 20
Drawer.ItemQueue.width = 100
Drawer.ItemQueue.height = 100
Drawer.ItemQueue.LineWidth = 5
Drawer.ItemQueue.StartAngle = 450
Drawer.ItemQueue.EndAngle = 1200
Drawer.ItemQueue.BoxBorderColor = Random(0F0F0Fh, 0FFFFFFh)
Drawer.AddItem()
See Also

DrawItems, DeleteItem, ItemQueue properties

AlignBottom

AlignBottom ()

Description

Aligns the bottoms of all selected objects with one another on a common baseline.

AlignLeft

AlignLeft ()

Description

Aligns all selected (highlighted) objects using the left hand side of each object to align it with the leftmost coordinate.

AlignRight

AlignRight ()

Description

Aligns all selected (highlighted) objects using the right hand side of each object to align it with the rightmost coordinate.

AlignTop

AlignTop ()

Description

Aligns all selected (highlighted) objects using the top of each object to align it with the topmost coordinate.

CalcStringDims

CalcStringDims (long pItem = 0)

Construct

Construct ()

Description

Called when the object enters scope.

CopyItems

CopyItems ()

Description

Copies all selected items to a queue. Duplicates of the items can then be created by calling PasteItems().

DeleteItem

DeleteItem (long p_Item), long

Description

Removes the item indicated by the p_Item parameter from te queue. Does not redraw the control.

Destruct

Destruct ()

Description

Called when the object goes out of scope. The Kill() method must have been called by the time that Destruct is called.

DrawHighlightBox

DrawHighlightBox (long pItem = 0)

Description

Selects the item in the queue and highlights it.

DrawHighlights

DrawHighlights ()

Description

Draws the highlight (selection indication) on all currently selected objects and displays the control.

DrawItem

DrawItem (long pTransColor = COLOR:None)

Description

Draws the item to the buffer (does not actually display the item). This is used to actually draw each item in the queue before the control is displayed.

DrawItems

DrawItems ()

Description

Loop through the queue and draws each item by calling DrawItem.

FindParent

FindParent (long pItem=0),long

Description

Returns the ParentID for the item, if it has a parent set.

GetAltPicture

GetAltPicture (String pTextValue)

Description

Returns a display picture for the passed text - embed code here to set returnvalue.

HideHighLight

HideHighLight ()

Description

Hides the HighLight layer, so no selections will be visible.

HighlightBoxesMoved

HighlightBoxesMoved (long pDeltaX=0, long pDeltaY=0)

Description

Redraws the highlighting of all selected items based on the the current movement indicated by the deltaX and deltaY parameters.

HighLightItem

HighLightItem (long pItem=0, long pMulti=0)

Description

Highlights (selects) a particular item. If pMulti is set then the item is added to the currently selected items, otherwise the current selection is cleared and the item becomes the only selected item. Typically the user will hold down the Shift or Control key to select multiple items.

Init

Init (ulong controlHandle)

Description

Called to initialize the control, takes the handle to a particular image control to use for the display.

InResizeCorner

InResizeCorner (), long

Description

Determines whether the user has moused over the corner of a selected object, which allows the user to them click and drag to resize the object.

ItemClicked

ItemClicked ()

Description

Called when an item was clicked on. In graphics this is usually referred to as picking.

Kill

Kill ()

Description

Called to dispose allocated memory can clean up when the control is no longer needed.

MakeSameHeight

MakeSameHeight ()

Description

Makes all selected objects the same height.

MakeSameSize

MakeSameSize ()

Description

Makes all selected objects the same size (width and height)

MakeSameWidth

MakeSameWidth ()

Description

Makes all selected objects the same width.

MoveItems

MoveItems ()

Description

Handles moving selected items as the user drags the items, and redraws the controls as the items are moved.

PasteItems

PasteItems (long pTopLeftX = -1, long pTopLeftY = -1)

Description

Called after calling CopyItems() to create duplicates of the copied items at the position specified.

PicExample

PicExample (string pPicture), string

Description

Returns an example text (as seen while editing clarion reports - e.g. $$$$$$$$$$ for a string) for the supplied picture.

RedrawHighlightBox

RedrawHighlightBox (long pItem=0, long dx=0, long dy=0, long dw=0, long dh=0)

Description

Redraws the highlight (selection indication) when an item has been moved (dragged by the user for example).

Reset

Reset ()

Description

Clears all layers of the rendered image data. This does not remove any items from the queue, and does not call Display or change what appears in the control.

ResizeItem

ResizeItem ()

Description

Called when the user clicks and drags to resize an item, it sets the new size on the item and updates the queue.

SaveHighlightPos

SaveHighlightPos (long pItem=0, long pXPos, long pYPos, long pWidth, long pHeight)

Description

Updates the highlight position for the item using the passed parameters.

SetCanvasSize

SetCanvasSize (long canvasWidth=0, long canvasHeight=0)
Description

Resizes the canvas (drawing area) to the width and height specified, and resizes all the layers used. The grid layers are redrawn, but not displayed until Display is called, everything else is cleared.

SetCursor

SetCursor (<string pCursor>)

Description

Sets the cursor based on the passed string, or reset it to the standard cursor if no parameter is pased

SetGrid

SetGrid (bool showGrid)

Description

If the grid is enabled (DrawPaint.gridEnabled = 1) the the grid layer is redrawn and unhidden. If the grid is disabled then the grid layer is hidden.

SortItems

SortItems ()

Description

Sorts the items in the queue based on their z-order, with the lowest z-order being the bottom-most item.

SpreadHorizontally

SpreadHorizontally ()

Description

Spreads out all selected objects evenly based on their widths and positions.

SpreadVertically

SpreadVertically ()

Description

Spreads out all selected objects evenly based on their heights and positions.

TakeClickEvent

TakeClickEvent ()

Description

The user clicked on the control, handles object selection and highlighting.

TakeDragEvent

TakeDragEvent ()

Description

Handles when the user clicks and drags. If an object was dragged them it is moved (or resized if the corner of a selection object was clicked and dragged). If multiple objects are selected they are moved as the user moves the mouse.

TakeDropEvent

TakeDropEvent ()

Description

Handles ending a Drag event. Unlike a normal "drop" even this handles ending a drag by updating the positions of the selected items that were dragged, auto finding the parents as needed.

TakeEvent

TakeEvent ()

Description

Called when event occurs, such as an object on the canvas being clicked on

TakeResizeEvent

TakeResizeEvent ()

Description

Called when a resize occurs so that an action can be taken (resizing and redrawing the control).

WithItem

WithItem (long p_Item), long , proc

Description

Selects a particular item from the queue so that the settings can be modified.

DrawPaint Properties

These are the DrawPaint class properties that are useful when working with DrawPaint. You can access all these properties directly (they are not private and so you don't need accessor methods, and they can be inherited if you base classes on DrawPaint). Properties that should be used with caution are indicated by an underscore preceding the name. Typically these properties should not be accessed directly.

DrawPaint Properties
CanMoveNow long
canvasColor long
CopyItemQueue &CopyItemQueueType
gridColor long
gridEnabled long
gridStyle long
gridWidth long
hDrawFactor decimal(20, 10)
HighLight group
ItemQueue &DrawPaintItemQueueType
LockParents long
Moving long
Resizing long
vDrawFactor decimal(20, 10)
ZoomFactor long
_control long
_DeltaX long
_DeltaY long
_highlighted long
_HighlightItems long
_HighlightQueue &HighlightQueueType
_items long
_MultiClickCount long
_nextId long
_StartMouseX long
_StartMouseY long
 canvasColor long The canvas (background) color for the control.
CanMoveNow long Indicates that a select has been made and can be moved if the user drags the mouse.
CopyItemQueue &CopyItemQueueType The queue used to store the item details when the CopyItems method is used to copy one of more items. The PasteItems() methods then uses this queue to created copies of the items at the chosen position.
gridColor long The colour used for the grid lines drawn over the canvas (if the grid is enabled)
gridEnabled long Enables or disables (hide) the grid layer.
gridStyle long The style of the grid lines being drawn onto the grid layer, uses a standard Clarion line style.
gridWidth long The width of the grid lines drawn onto the grid layer, by default this is one pixel.
hDrawFactor decimal(20, 10)
HighLight group,pre()
ItemQueue &DrawPaintItemQueueType The queue that contains the items on the canvas. This stores each items that is created and drawn on the control. This is the fundamental storage for the DrawPaint class.
ItemQueue members (properties)
ID long Description
type long The type of object. the following types are supported;
create:string, create:image, create:line, create:box, create:ellipse, create:arc
Common (generic) properties
xpos long the x position of the object
ypos long the y position of the object
width long the width (in pixels) of the object
height long the height (in pixels) of the object
zorder long
hidden long
transparent long
Line Properties
lineColor long
lineStyle long
lineWidth long
Box Properties
boxBorderColor long
boxFillColor long
boxRounded long
Font Properties
fontColor long
fontSize long
fontStyle long
fontCharset long
fontName string
textValue string
Image Properties
imageName string
imageStretch long
imageCentered long
imageTiled long
imageBitdepth long
imageFileType long
Parent Properties
isParent long
parentID long
File Properties
recNum long
Guid string
String Properties
justify long
picture long
clipped long
fitWidth long
fitHeight long
textBox long
RTF long
Arc Properties
StartAngle long Tenths of a degree, anti-clockwise, from 3 o'clock. eg 1800 is 9 O'clock
EndAngle long Tenths of a degree, anti-clockwise, from 3 o'clock


LockParents long
Moving long Indicates that items are being moved in a drag operation.
Resizing long Indicates that an item us being resized as the user drags the mouse.
vDrawFactor decimal(20, 10)
ZoomFactor long
_control long Handle to the Image control that Draw is using to display the image
_DeltaX long Internal store for calculating differences when objects are moved or resized.
 _DeltaY long Internal store for calculating differences when objects are moved or resized.
_highlighted long  
_HighlightItems long  
_HighlightQueue &HighlightQueueType Stores all highlights (selected areas)
_items long
_MultiClickCount long
_nextId long
_StartMouseX long Internal store for the mouse coordinate at the start of an action.
_StartMouseY long Internal store for the mouse coordinate at the start of an action.