CapeSoft DrawPaint
Documentation

• Introduction to DrawPaint
• Getting Started - Adding a DrawPaint control
• DrawPaint Template
• DrawPaint Methods
• DrawPaint Properties

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.

Please note that this documentation is under construction and is being expanded.

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

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.

Note: In Clarion 5.5 the ItemQueue is not cleared by default, so it is strongly recommended that you Clear(Drawer.ItemQueue) either directly before or directly after the call to Drawer.Init(). This is not necessary in Clarion 6 or 7.

Example

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

AlignBottom

AlignLeft

AlignRight

AlignTop

CalcStringDims

Construct

CopyItems

DeleteItem

Destruct

DrawHighlightBox

DrawHighlights

DrawItem

DrawItems

FindParent

GetAltPicture

HideHighLight

HighlightBoxesMoved

HighLightItem

Init

InResizeCorner

ItemClicked

Kill

MakeSameHeight

MakeSameSize

MakeSameWidth

MoveItems

PasteItems

PicExample

RedrawHighlightBox

Reset

ResizeItem

SaveHighlightPos

SetCanvasSize

SetCursor

SetGrid

SortItems

SpreadHorizontally

SpreadVertically

TakeClickEvent

TakeDragEvent

TakeDropEvent

TakeEvent

TakeResizeEvent

WithItem

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.