Class Reference
Download Latest Version Index History
CapeSoft Logo

CapeSoft DrawClass
Class Reference - Methods and Properties

Installed Version Latest Version

All the Clarion built in drawing functions have equivalent methods of the DrawClass, so you can call them same way you would normally, except as a method of the class. For example, to draw a box simply call the box method, where the name of the DrawClass object is Drawer:

! Draw a box at (10,10), 120 pixels wide and high, with a red fill
Drawer.Box(10, 10, 120, 120, color:red)

Don't forget to call drawer.Display() to display the box in the Draw image control.

The following are DrawClass methods that are the equivalent of the built in Clarion graphics functions, and operate in the same manner.
Basic Methods
Arc Draw an arc of an ellipse
Blank Clear the entire drawing area
Box Draw a box (filled and line only)
Chord Draw a chord (a closed arc)
Ellipse Draw an Ellipse
Line Draw a Line
Polygon Draw a Polygon
Show Write text to the drawing area


As well as providing the same functionality as the Clarion graphics functions, the DrawClass class provides additional methods (The methods that are the same as the Clarion drawing functions are included in this listing for completeness). See the section on Layers for a list of DrawClass methods for handling layers.

Draw also has a number of internal methods that are provided for advanced users who would like to customize or modify the DrawClass class. See the Internal Class Methods section.
Draw Class Methods
Arc Draws an arc
Barcode Draws a PDF417 compatible 2D barcode.
BestFit Calculates the best proportional scaling when passed dimensions.
Blank  Clears the drawing area
Blur Blurs a layer, supports blurring horizontally, vertically, or a standard blur.
Box Draws a rectangle
Captcha Creates a CAPTCHA from a passed string. This is used to create an image that a human can read, but is difficult for a machine to read, for web based forms etc.
Chord Draws a chord (and arc with the ends connected by a straight line)
ClarionToRGB Converts a Clarion color to a standard RGB color .
ColorRange Used to calculate the colors at two points anywhere on a color gradient
Create256 Create a 256 colour bitmap from the 24 bit version.
Curve Draws a smooth curve through the points passed.
Cylinder Draws a variety of cylinders, with multiple shading options
Display Displays the draw control. Display() needs to be called every time control needs to be updated
Ellipse Draws an ellipse
EnumFontFamilies Populates a queue for all available fonts on the system.
ErrorTrap The default error handler, allows error messages to be turned on or off, as well as providing the ability to easily customise the error handling throughout Draw.
FileToString Reads the content of a file into a string, also see StringToFile
FindPixel Travel across the drawing in a specific direction until a pixel of interest is located.
Flood Floodfill an area of the drawing.
FormatMessage Returns the error message for a passed Window API error code.
Fullscreen Uses the built in functions to get the metrics for the current monitor and resizes the window to the full size of the screen (see the Fullscreen example).
GetDeviceCaps Gets information about the current device capabilities (screen size, resolution etc.)
GetDevicePixel Returns the color of a pixel anywhere on the screen
GetDisplay Loads the current image control contents into the Draw buffer, useful for getting an image that Clarion has loaded into the control.
GetIconHandle Gets a handle to an icon on disk or in a resource for passing to LoadIcon
GetImagePixel Returns a pixel on the Draw control, faster than GetDevicePixel, and the coordinates are relative to the origin of the Draw control.
GetPixel Identical to GetImagePixel, simply provides an alternative name.
GetMonitorInfo Retrieve information about the monitor based on the passed handle (including the monitor size and workspace size).
GetWindowsColors Populates the Draw Windows colors variable with the current interface colors stored by Windows.
GrabScreen Grabs the specified area of the screen and loads it into the Draw control
Grayscale Converts an image to grayscale.
HalfEllipse Draws half of an ellipse
Highlight Turns a highlight on and off over the area specified. Gives a "selected" effect.
HsvToRgb Converts an HSV color to a standard Clarion RGB color
Image Displays and image from a file
ImageDimensions Returns the pixel dimensions of a bitmap image file.
imageFromBuffer Writes from a buffer that contains RGB data to a layer as an image.
Init Initializes the Draw control, called automatically
Init256 Initializes 256 colour drawing capabilities
Kill Destroys the Draw control, called automatically
Kill256 Halts 256 colour drawing and cleans up
LengthenLine Calculates the coordinates of a lengthened
Line Draws a line
ListDisplayDevices Lists all display devices on the system and populates a queue with the details
ListMonitors Retrieves information about all of the monitors on the system and fill a queue with the details include the monitor handle, the coordinates and the workarea.
LoadIcon Places an image from an icon file onto the Draw control
Log Log to the OS debug output (see Debugging and Logging)
MetallicCylinder Draws a double shaded cylinder with a metallic look
MonitorFromRect Returns a handle to the monitor that the passed Rect is on
MouseX Return the current x position of the mouse relative to the Draw control
MouseY Return the current y position of the mouse relative to the Draw control
PieSlice Draws a shaded slice of a pie (a segment of a pie chart).
PointInPolygon Returns whether an x and y coordinate are within a polygon.
PointInPieSlice Whether a coordinate is within a specific pie slice (ellipse segment)
Polygon Draw a polygon
Putpixel Puts a pixel on the Draw control
RadLine Draws a line radially (from a point to a length along an angle)
ResetDisplayArea Resets the Display to redraw the entire canvas (see SetDisplayArea)
Resize Changes the size of the Draw buffer
ResizeControl Changes the size of the Clarion control Draw uses
RgbToHsv Convert and RGB color to an HSV color
RoundRect Draw an round cornered rectangle.
SetDisplayArea Limits the display command to a rectangular area, can dramatically increase display performance.
SetFontColor Sets the current Draw font color
SetFill Sets the current fill type to patterned instead of solid
SetPenColor Sets the current Draw pen color
SetPenstyle Sets the current Draw pen style
ShadeBox Draws a rectangular box with multiple shading options
ShadeEllipse Draw an ellipse shaded from one color to another.
ShadeLine Draws a line shaded from one color to another
ShadePolygon Draw a polygon horizontally shaded from one color to another.
StrHeight Returns the height of the current font
StrLen Returns the length of a string in pixels
Sphere Draws a sphere shaded between two colors (the "sphere" can be elliptical).
SetPenWidth Sets the current Draw pen width
SetFill Sets the current fill style, allows patterned fill to be used
SetFont Sets the current font attributes to use.
SetFontColor Set the current font color
SetFontMode Set the font render mode (anti-aliased etc.)
Show Write text to the drawing area
StringToFile Writes a string to a file, see FileToString
SwapBuffers Writes the buffer passed into the image control
ToClipboard Copies the current Draw control contents to the clipboard
WriteBMP Writes the Draw control to a bitmap image file
WriteLayerBMP Writes the current layer to a Windows Bitmap file.
WriteLayerPNG Writes the current layer to a PNG file.
WritePNG Writes the Draw control to a PNG image file
DrawClass provides a number of methods to manage the use of Layers. IT provides the ability to use an unlimited number of independent layers in an image (by default the number of layers is limited to 256, but it can be adjusted up to 2 billion if needed).

Drawing on layers is done in the same manner as simply drawing to the control, in fact DrawClass initializes the first layer automatically and uses it as the default drawing surface. Layers can be any size, although typically they are the same size as the Draw control.

Layers also provide a number of useful features such as transparency - either a specific color can be made transparent, or an alpha channel can be used, which provides 256 levels of transparency. This provides "soft" transparency and can be used for anti-aliasing, soft drop shadows, glow effects etc. You can draw to an alpha layer using all the normal Draw methods, and methods such as Blur() provide a simple way to create soft drop shadows and other effects. This list of the method, along with more information on layers, can be found in the Layers section of the documentation.
LayerMethods
Addalpha Add an alpha channel to a layer
AlphaCopy Handles alpha blending for CopyLayer. Do not call directly.
CopyLayer Copy a block of pixels from one layer to another (handles transparency).
IndexTransparency Set the index transparency of the layer.
HasAlpha Returns whether a layer has an alpha channel
HideLayer Set a layer to hidden.
InitLayer Initialize a new layer
KillLayer Delete a layer.
LayerMode Return whether a layer has a display mode enabled or disabled.
MoveLayer Change a layer's display order.
NumLayers Return the number of initialized layers.
ResizeLayer Resize a specific layer.
SetMode Set the display mode.
Showlayer Set a layer to be shown when Display() is called.
SwapLayers Swap two slayer's display order.
ToAlpha Copy one RGB channel from one layer to another.
WithLayer Activate a layer for drawing to.
See the Layers section for more information on using layers, as well as the layer data type. For convenience this method listing is duplicated at the beginning of the Layers section.
Draw also provides methods that allow 3D calculations using 3D points, vectors and lines (Draw provides these data types). All 3D methods and structures can be used in 2D simply by setting the z-coordinate (depth) to zero.
3D Data Types
Point2D and Point3D A single point in 3D (or 2D) space. Define by an x, y and z coordinate.
Vector3D A 3D vector. This type is essentially interchangeable with the point data type, although it specifies a line through 3D space rather than a single point, the components are the same.
Line3D A 3D Line from one point to another. It consist of a start and an end point.

3D Methods
Add3d Add two points or vectors
CrossProd Calculate the cross product of two vectors (or points).
Dot Calculate the dot product of two vectors
Distance Calculate the distance from a line to a point
Equal3d Determine equality of two vectors or points
Length3d Returns the length of the passed vector
LinesIntersect Determine if two lines intersect, and if so the point of intersection
Normalize Normalizes the passed vector
Perp Calculate the length of the perpendicular
PointOnLine Determine if a point is on a line, and if so where.
ScalarProd Calculate the scalar product of a point or vector multiplied by a real number
Sub3d Subtract two points or vectors

Utility and Internal Methods
Font Handling Methods
EnumFonts Populates a queue with all the fonts installed on the system
EnumFontFamExProc The callback methods for font enumeration. When EnumFonts is called this method will be called for each font found.
AnsiToUnicode Converts an ANSI string to a Unicode string
UnicodeToAnsi Converts a Unicode string to an ANSI string
General File Handling
FileToString Reads a file into memory
StringToFile Writes the passed data to disk
Monitor, Window and Device handling
GetWindowInfo Returns information about the current window
MonitorFromRect Returns the a handle to the monitor when passed a the coordinates of a rectangle
GetMonitorInfo Returns the monitor information when passed a monitor handle
GetDeviceCaps Retrieve information about the display
General Utility methods
GetRegKey Retrieves a key value from the registry
GetLastError Returns the error code for the last API function called. Not a member of the Draw class, so it can be called without a Draw object.
FormatMessage Converts a Windows error code into the associated error message
ToClipboard Copies the contents of the Draw control to the clipboard as a BMP
Min Find the minimum of all passed values (up to 8 reals)
Max Find the maximum of all passed values (up to 8 reals)
EnumProcessModules Find all the modules loaded for the current process.
BigEndian Converts a long to Big Endian bit order

Class Method Reference

Note that Clarion stores RGB colours lowest byte first. This means that 0FF0000h is blue (color:blue), 000FF00h is green (color:lime) and 00000FFh is red (color:red). It is also worth mentioning that color:green is dark green and that pure RGB green is color:lime.

Arc

Arc (long x, long y, long width, long height, long startAngle, long endAngle)

Description

The ARC procedure places an arc of an ellipse on the current target. The ellipse is drawn inside a "bounding box" defined by the x, y, width, and height parameters. The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."

The startangle and endangle parameters specify what sector of the ellipse will be drawn, as an arc.

The border color is the current pen color set by SETPENCOLOR; the default color is the Windows system color for window text. The border width is the current width set by SETPENWIDTH; the default width is one pixel. The border style is the current pen style set by SETPENSTYLE; the default style is a solid line.

Parameters
Parameter Description
long x An integer expression that specifies the x-coordinate of the top left corner of bounding box of the ellipse that the arc is a segment of
long y An integer expression that specifies the x-coordinate of the top left corner of bounding box of the ellipse that the arc is a segment of
long width An integer expression that specifies the width of the ellipse that the arc is a segment of.
long height An integer expression that specifies the height of the ellipse that the arc is a segment of.
long startAngle An integer expression that specifies the angle on the ellipse that the arc starts at, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.
long endAngle An integer expression that specifies the angle on the ellipse that the arc ends at, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.

arc screenshot

Examples
Example
drawer.SetPenColor(color:black)       ! Set the arc line color to black
drawer.Blank(color:white)             ! clear the current layer to white
drawer.Arc(2, 2, 60, 40, 1200, 1800)  ! draw an arc from 120 degrees to 180 degrees
drawer.Display()                      ! write the current layers to the image control

You can also use the arc method to achieve more complex effects. The code below draws a ring of arcs and shades them from red to yellow. The arcs are drawn with a pen width of 2 for effect.

colorComponents     group
red                     byte    ! red component
green                   byte    ! green component
blue                    byte    ! blue component
a                       byte    ! unused high order byte in the long
                    end
curColor            long, over(colorComponents)  ! current color to set the pen color to
colorIncrement      byte        ! increment for the color component

    drawer.Blank(color:white)   ! clear the current layer to white
    
curColor = color:red             
    colorIncrement = 1
    drawer.SetPenWidth(2)       ! set the pen width to 2 pixels

    loop i = 0 to 1800 by 10
        x = cos(i)* 80 + 90
        y = sin(i)* 80 + 90
        drawer.SetPenColor(curColor)                 ! set the current pen color
        drawer.Arc(x, y, 100, 150, i, i + 2700)      ! draw an arc
    
        if colorComponents.green = 255
            colorIncrement = -1
        elsif colorComponents.green = 0
            colorIncrement = 1
        end
        colorComponents.green += colorIncrement
    end

    drawer.Display()            ! display the result in the image control

The result:
multi arcs screenshot

Barcode

Barcode (string barcodeText, long sizeFactor=0, long forceRes=0, long binData=0), long

Description

The Barcode method draws a PDF417 compatible 2D barcode using the data passed. As well as creating barcodes, it also provides the option to automatically resize the Draw image to the size of the created barcode (filling the image control with the resultant barcode).

The size of the barcode can be increased by using the sizeFactor parameter, allowing larger barcodes to be created using the same data. This serves two primary purpose:
By default the sizeFactor is set to 5 internally to produce a barcode that is suitable for both screen display, and printing.

The Barcode method supports both text and binary data.

Using the method is as simple as calling it followed by calling Draw.Display() to actually display the image.

The barcode is drawn using the current pen color. If the forceRes parameter is zero then the barcode is drawn over whatever is within the Draw control. If the forceRes parameter is non zero then the barcode is drawn in the current pen color, the background is blanked to white, and the Draw buffer is resized to the size of the resultant barcode.

Parameters
Parameter Description
string barcodeText The text that the barcode should contain (this can be binary data). The text is clipped unless the binData parameter is set to True, which treats the barcodeText as binary, and does not clip it.
long sizeFactor Allows the barcode size to be increased by this factor. For example setting sizeFactor to 2 will double the width and height of the barcode (in pixels). Setting sizeFactor to 3 will triple the width and height etc.

By default Draw uses a sizeFactor of 5, which effective produces a barcode that prints well at 360 DPI (72DPI * 5). We recommend using the default size factor, or increasing it if more resolution is required.
long forceRes If forceRes is non zero, then the Draw buffer is resize to the size of the barcode. This is useful when the barcode should fill the entire image control.
long binData If binData is a non zero value then the barcodeText is treated as binary data and the entire string is converted to a barcode. If binData is zero then the string is treated as plain text and clipped to remove trailing spaces before conversion to a barcode. Setting binData to 1 will work for both text and binary data, however text will not be clipped and the barcode will include any trailing spaces.
Return values

Returns 1 for success and zero is the barcode library fails to render the barcode.

Examples
Example
! Draw and resize the control to the size required for just the barcode
drawer.
Barcode('This is a PDF417, 2D barcode!', , 1)  
drawer.
Display()
Notes

Draw ships with a "Barcode Report" example that demonstrates creating PDF417 barcodes on both windows and reports.

Blank

Blank (long color=color:black)

Description

Blank simply clears the entire image. Like all the Draw methods, Blank does not take effect until Display() is called. Blank can be called without any parameters, in which case the image is cleared to black. If parameters are passed the image is cleared to the color specified by the color parameter.

PieSlice Group Type

Parameter
Parameter Description
long color The color to blank to, this is optional as the default color is black

Examples
Example
Blank() Clears to black
Blank(x)  ! where x <= 0 Clears to black
Blank(1) Clears to white
Blank(COLOR:White) Clears to white
Blank(COLOR:Equate) Clears to the color specified by the Clarion color equate
Blank(0FF3AF1h) Blank to the color specified (this can be either a constant or variable)
Blank can be passed any integer constant or variable to specify the color to clear to.

BestFit

BestFit (ulong srcW, ulong srcH, ulong maxW, ulong maxH, *ulong newW, *ulong newH)

Description

Calculates the best proportional scaling when passed an existing width and height and the dimension that must be fit within. Proportional scaling means that the proportions (the ratio between the initial width and height) are preserved when calculating the new dimensions that will fit within the provided area (the bounding box given by maxW and maxH). This method only performs the calculations, it does not do any drawing or other data modification.

Parameters
Parameter Description
long srcW The original (current) width.
long srcH The original (current)height.
long maxW The maximum width (the bounding box that the new dimensions must fit within).
long maxH The maximum height (the bounding box that the new dimensions must fit within).
long newW A variable that will be set to the new calculated width.
long newH A variable that will be set to the new calculated height.

Blur

Blur (long blurDist, long bType=0) BETA

Description

Blurs the contents of the current layer, either horizontally, vertically, or in both directions. Blur can be be used to create effects like soft drop shadows, or "speed blur". Note that this function is in beta in 2.10 and currently leaves an unblurred section around the very edge of the image that is BlurDist pixels wide. This will be corrected in the next release of Draw.

Parameters
Parameter Description
long blurDist The size of the blur
long bType The default is a standard blur, alternatively Draw:Horizonal or Draw:Vertical can be specified to only blur the image in a single direction.

Examples
Example
    ! 4 pixel blur
drawer.Blur(4)
    drawer.Display()
    ! 4 pixel horizontal blur
drawer.Blur(4, Draw:hBlur)
    drawer.Display()

! 4 pixel vertical blur
drawer.Blur(4, Draw:vBlur)
    drawer.Display()
Blur used to create a soft Drop Shadow for text (see the DrawHeader template for the code to draw this):

Blur / drop shadow example screenshot

Horizontal and Vertical blurs used to create a "motion blur" effect in conjunction with the LoadIcon method used to load a XP style icon, including the alpha channel (soft transparency):

horizontal  blur screenshot vertical blur screenshot

Box

Box (long x, long y, long width, long height, [long fillColor])

Description

This is identical to the Clarion function. Draws a filled or line box.

Parameters
Parameter Description
long x An integer expression that specifies the horizontal position of the starting point.
long y An integer expression that specifies the vertical position of the starting point.
long width An integer expression that specifies the width
long height An integer expression that specifies the height.
long fill (optional) A LONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the
three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value. If omitted then Color:None is used.
Examples
Example
drawer.SetPenColor(color:red)
drawer.Box(2, 2, 50, 80)            ! draw a box with a red line and no fill
drawer.SetPenColor(color:white)     ! set the current pen color to white
drawer.Box(55, 2, 50, 80, 09933FFh) ! box with a white line and pink



drawer.
SetFill(pattern:stars)       ! use a patterned fill
drawer.
SetPenColor(65280)           ! set the pen color to pure RGB green, identical to calling SetPenColor(color:lime)
drawer.
Box(113, 2, 50, 80, color:yellow) ! draw a box with a green line and a yellow patterned fill

drawer.Display()
The result of the above code:
result of the above code screenshot

Information

To set the box outline color call SetPenColor(), to set the box line with call SetPenWidth(). The SetFill() method allows you to specify the current fill pattern, or to turn patterned filling off. Also see the ShadeBox() method for boxes that are shaded between colors. In the above example Blank() is used to clear the buffer and Display() is used to write the buffer into the image control.

Chord

Chord (long x, long y, long width, long height, long startAngle, long endAngle, long fillColor)

Description

Identical to the Clarion function. Draws a closed arc. The parameters are the same as those of the Arc() method, except that you can optionally specify a fill color.

ClarionToRGB

ClarionToRGB (long clarionColor), long

Description

Converts a Clarion BGR (Blue, Green, Red) color to a standard RGB color and returns it. Standard RGB colors, as used by Windows, store the bytes in Red, Green, Blue order. Clarion stores the bytes in the reverse order. This function allows you to convert a color from the Clarion storage format (BGR byte order) to RGB byte order. The color can then be used in Windows API function etc.

Parameters
Parameter Description
long clarionColor A standard Clarion color (which is stored in BGR format internally)
Return Values

The function returns a long containing the color in RGB bytes order.

ColorRange

ColorRange (long startColor, long EndColor, long distance, long p1, long p2, *long color1, *long color2)

Description


Calculates the colors at two points on a color gradient. For instance if a gradient between red and yellow is specified over a distance of 100 pixels, the ColorRange method could be used to determine the color at 20 and 80 pixels along the gradient.

Parameters

Parameter Description
long startColor The color at the start of the gradient
long endColor The color at the end of the gradient
long distance The distance, in pixels, that the color gradient spans
long p1 The position along the gradient to calculate the first color
long p2 The position along the gradient to calculate the second color
*long color1 color1 will be set to the color at the first point (p1)
*long color2 color2 will be set to the color at the second point (2)

Return Values


The method does not return a value, the color1 and color2 parameters are set to the calculated colors.

Information

colour shading between objects screenshot

This method is useful for shading between two colors that spans a number of separate shaded objects. The image on the left uses the ShadeBox() and ShadeEllipse() methods to create a gradient between red and yellow that covers all the objects. ColorRange() is used to calculate the start and end colors at the top and bottom of each of the objects.

An alternative method to achieve this effect would be using two layers. The bottom layer is filled with a shaded box, the top layer is blanked to white and then the shapes are drawn with a color select as the index transparency color for the layer.

Example
Example
bottomColor             long
topColor                long
yTop                    long
yBottom                 long

     yTop = 10
    yBottom = 75
    drawer.ColorRange(color:red, color:yellow, 200, yTop, yBottom, topColor, bottomColor)
    drawer.ShadeEllipse(10, yTop, 78, yBottom - yTop, topColor, bottomColor)
    yTop = 80
    yBottom = 180
    drawer.ColorRange(color:red, color:yellow, 200, yTop, yBottom, topColor, bottomColor)
    drawer.ShadeBox(105, yTop, 100, yBottom - yTop, , , topColor, bottomColor)

Create256

Create256 ()

Create a 256 colour version of the current Draw image and stores it in the Draw.bitmapFileData256 string. Note that calling this method before calling Init256() will simply pass an error to the ErrorTrap() method. Once you have called Init256() and the Draw.colours256 flag has not been set to zero, calling Display() and WriteBMP() will provide this functionality so it is not necessary to call this method normally. This method has simply been provided to allow a 256 colour version to be created at any time, regardless of the state of the Draw.colours256 flag. When you have multiple layers the current active layer set by WithLayer() will be used to create the 256 color image.

Curve

Curve (*long[,] pt, long ptNum)

Draws a smooth curve between the passed points. Automatically calculates the required interpolation between curves in order to draw a curve that is smooth and continuous (C1, C2 and G1 continuity using Hermite curves and interpolation for the blending functions for those who care!).

Parameters
Parameter Description
*longp[,] pt An array of points. The array is 2 dimensional, with each pair of longs specifying and x and y coordinate pair.
long ptNum The number of points to use from the array. If this is set to zero then then it is assumed that all the points in the passed array should be drawn in the curve.
Information

There are two properties of the class that influence the way in which the curves are drawn. Draw .curveSmoothness determines how many points are drawn along the curve, you can leave this as the default (100), or increase the number to increase the potential accuracy for very long curves. Draw.curveTension determines how "curvy" the curve is. A value of 0.5 produces a smooth curve that is fairly moderately curved. A higher value produces a curve that is "pulled" further outwards, as if there was a magnet pulling the curve, 1.0 is very curvy indeed. A value of zero produces a flat line with no curve, and a negative value "pushes" the curve away, reversing it's curve direction Typically you won't need to modify these values.

Examples
Example
aCurve long, dim(1000,2)
aCurvePoints long ! number of used entries
  code
    aCurve[1,1]  = 10
    aCurve[1,2]  = 200
    aCurve[2,1]  = 100
    aCurve[2,2]  = 100
    aCurve[3,1]  = 150
    aCurve[3,2]  = 300
    aCurve[4,1]  = 200
    aCurve[4,2]  = 200
    aCurve[5,1]  = 300
    aCurve[5,2] = 180
    aCurve[6,1] = 390
    aCurve[6,2] = 200
    aCurve[7,1] = 410
    aCurve[7,2] = 300
     
    Drawer.SetPenColor(color:lime)
    Drawer.Curve(aCurve, 7)
    Drawer.Display()

This example shows code that can be added each time the user clicks on the Draw control, in order to Draw a curve through all of the points clicked. In order to trap mouse clicks place a region control over the Draw control, set the Immediate property of the Region on, and then this code to the Event:Accepted embed.

aCurvePoints += 1
if aCurvePoints > 1000
   
Message('Only 1000 points on the curve supported by this demo, ' |
          & '
this can be changed by increasing the size of the array.')
else
    aCurve[aCurvePoints, 1] = Drawer.
MouseX()
    aCurve[aCurvePoints, 2] = Drawer.
MouseY()
end

! draw a dot at each point that the curve will pass through (optional)
loop i = 1 to aCurvePoints
    Drawer.
Box(aCurve[i, 1]-1, aCurve[i, 2]-1, 4, 4, color:black)
end

if aCurvePoints > 1             ! need at least one point to draw a curve
   
if aCurvePoints > 2         ! draw over the previous curve in a pale color to show where it was
        Drawer.SetPenColor(0DDDDDDh)
        Drawer.Curve(aCurve, aCurvePoints-1)
   
end
    Drawer.
SetPenColor(color:red)
    Drawer.Curve(aCurve, aCurvePoints)
end

curves screenshot

 

Cylinder

Cylinder (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long xp = -1, | long yp=-1, long depth, byte intensity = -1,long eCol=-1)

Deprecated. Replaced by the Cylinder2() method (below).

Description

Draws a shaded cylinder. The type of shading, the colors use, the "depth" of the ellipse on the end of the cylinder etc. can all be determined using the provided parameters. In addition there is now a Cylinder2 method which reduces the complexity of using the Cylinder method and allows the shading direction to be independent on the orientation of the cylinder. This method is now a wrapper than simply calls the new Cylinder2 method. It is recommend that the Cylinder2 method (below) be used. This method is included for backward compatibility only.

Parameters

The first eleven parameters are identical to the ShadeBox method:
Parameter Description
long x The x position to start the bounding box at, in pixels
long y The y position to start the bounding box at, in pixels
long width The bounding box width, in pixels
long height The bounding box height, in pixels
long lcol The color of the left hand side of the cylinder - optional
long rcol The color of the right hand side of the cylinder - optional
long tcol The color of the top of the cylinder - optional
long bcol The color of the bottom of the cylinder - optional
long xp The percentage along the x-axis for the highlight - optional
long yp The percentage along the y-axis for the highlight - optional
byte intensity The percentage intensity of the highlight - optional
However there are also two additional parameters:

Parameter Description
long depth this is the depth of the ellipse on the end of the cylinder
long eCol the color of the ellipse on the end of the cylinder
Depth and eCol are optional, but they should be defined in order for the cylinder to draw correctly. Either lCol and rCol should be specified, or tCol and bCol. If all four color parameters are not passed a solid black cylinder will be drawn.

Calling syntax is identical to Shadebox, with the exception of the two additional parameters that should be defined (depth and eCol).

Single Shaded Cylinder (one color)
Single Shaded Cylinder (one color) screenshot

Single Shaded Cylinder (two color)
Single Shaded Cylinder (two color) screenshot

Double Shaded Cylinder
Single Shaded Cylinder (two color) screenshot
Examples and Using the cylinder method:

Cylinder(x, y, width, height, lcol, rcol, tcol, bcol, XP, yp, depth, intensity, eCol)
Note that in the examples below, the code for a single cylinder is shown, the other cylinders in each image are identical with altered x and y coordinates.

Example
Drawing a single shaded cylinder with one color
Vertical cylinders, shaded from left to right, the highlight position specified by the XP parameter and the highlight intensity specified by the intensity parameter:
drawer.Blank()
col = Random(0, 0FFFFFFh)
drawer.Cylinder(10, 200, 40, -Random(100, 120), col, col, , |
                , 60, , 20, Random(50,100), col)

drawer.Display()
single shaded cylinder with one colour screenshot
Drawing a single shaded cylinder with two colors
Vertical cylinders, shaded from left to right, the highlight position specified by the XP parameter and the highlight intensity specified by the intensity parameter:
drawer.Blank()
leftColor = Random(0, 0FFFFFFh)
rightColor = Random(0, 0FFFFFFh)
drawer.Cylinder(10, 200, 40, -Random(120, 180), leftColor, rightColor, |
                , , 60, , 20, Random(50,100), leftColor)

drawer.Display()
single shaded cylinder with two colours screenshot
Drawing a double shaded cylinder
Vertical cylinders, shaded between colors from top to bottom and from light to dark from left to right, with the highlight position specified by the XP parameter and the highlight intensity specified by the intensity parameter. Note that the color is specified as topColor and bottomColor, rather than left and right:

drawer.Blank()
topColor= Random(0, 0FFFFFFh)
bottomColor =
Random(0, 0FFFFFFh)
drawer.Cylinder(10, 200, 40, -
Random(120, 180), , , bottomColor, |
               
 topColor, 60, , 20, Random(50,100), topColor)

drawer.Display()
double shaded cylinder screenshot
Drawing a single shaded cylinder - horizontal

Horizontal cylinders, shaded between colors from top to bottom. Identical to the vertical cylinder, but with left and right colors swapped with top and bottom colors, and XP and yp swapped.

drawer.Blank()
col = Random(0, 0FFFFFFh)
drawer.Cylinder(20, 10, Random(100, 120), 40, , , col, col, , |
                60, 20, Random(50,100), col)
drawer.Display()
single shaded cylinder - shaded screenshot
Drawing a single shaded cylinder with two colors - horizontal

The same as the single color, except top and bottom colors are different.

drawer.Blank()
topColor = Random(0, 0FFFFFFh)
bottomColor = Random(0,0FFFFFFh)
drawer.Cylinder(20, 10, Random(100, 120), 40, , , topColor, |
                bottomColor, , 60, 20, Random(50,100), topColor)
drawer.Display()
single shaded cylinder with two colors - horizontal screenshot
Drawing a double shaded cylinder - horizontal

Horizontal cylinders, shaded between colors from left to right. Identical to the vertical cylinder, but with left and right colors swapped with top and bottom colors, and xp and yp swapped.

drawer.Blank()
leftColor = Random(0, 0FFFFFFh)
rightColor = Random(0, 0FFFFFFh)
drawer.Cylinder(20, 10, Random(120, 180), 40, leftColor, |
       rightColor, , , , 60, 20, Random(50,100), rightColor)
drawer.Display()
double shaded cylinder - horizontal screenshot
In addition to the Cylinder method, Draw also provides a Cylinder2() method that allows the shading direction to be independent of the direction that the cylinder is drawn in. The Cylinder() method is a wrapper for the Cylinder2() method that provides additional functionality, and does not have any of the drawing errors that the old cylinder method had.

Cylinder2

Cylinder2 (long x, long y, long width, long height, long startColor, long endColor, long orientation, long eDepth, long eColor, |

long eColor2=-1, long angle=-1, long intensity=0, long highlightPos=50, long shadingType=1)


Description

The new cylinder method provides the same functionality as the original Cylinder() method (which is now just a wrapper method which calls Cylinder2()). In addition it allows shading that is independent of the orientation of the cylinder. It also allows a second ellipse color (eColor2) to be optionally specified, which shaded the ellipse on the end of the cylinder between the two colors. The shaded ellipse uses the current pen color as a line color, so calling draw.SetPenColor(color:none) will

Parameters

Parameter Description
x, y, width, height The size of the cylinder bounding box
startColor, endColor The colors to shade from and to.
orientation Whether the cylinder is vertical or horizontal - use either the draw:vertical or draw:horizontal equate.
eDepth The depth of the ellipse on the end of the cylinder
eColor, eColor2 If only eColor is specified, then a solid filled ellipse is drawn, otherwise the ellipse is shaded from eColor to eColor2
angle The direction that the shading is done in, can either be 0 (from top to bottom) or 90 (from left to right).
intensity How bright the highlight is for Single and Double shading
highlightPos The percentage across the cylinder that the highlight is drawn at.
shadingType One of the following equates: draw:linearShade, draw:singleShade, draw:doubleShade.
Examples
Example
drawer.Blank(color:white)
drawer.SetPenColor(color:none)
drawer.Cylinder2(10, 10, 150, 40, color:red, color:yellow, draw:horizontal, 20, |
                 color:red, color:white, 0, 100, 50, draw:singleShade)

drawer.SetPenColor(color:red)
drawer.Cylinder2(10, 60, 150, 40, color:red, color:yellow, draw:horizontal, 20, |
                 color:red, color:white, 90, 100, 50, draw:doubleShade)

drawer.SetPenColor(color:none)
drawer.Cylinder2(10, 110, 133, 41, color:aqua, color:navy, draw:horizontal, 20, |
                 color:aqua, color:navy, 0, 100, 50, draw:doubleShade)

drawer.Cylinder2(10, 160, 193, 21, color:green, color:lime, draw:horizontal, 10, |
                 color:green, color:lime, 0, 100, 50, draw:doubleShade)

drawer.Display()
various cylinder examples screenshot

Display

Display ()

Description

This method updates the image control with the contents of the all the visible Draw layers, this needs to be called each time you wish to update or refresh the Draw control. The Draw buffer is persistent, so even after calling Draw.Display() it retains the same information, allowing you to add to the image and call Draw.Display() again to write the new image to the image control. To blank the buffer call the Blank() method. Once Blank() has been called, you will need to call Draw.Display() to write the cleared buffer to the image control. Important: This is not the same as the Clarion Display() function, it is not necessary to call the Clarion Display() when redrawing the Draw control.

Examples
Example
drawer.SetPenColor(color:blue)            ! Set the current pen color
drawer.Box(1, 20, 100, 120, color:green)  ! Draw a box
drawer.Display()                          ! Update the image control

Ellipse

Ellipse (long x, long y, long width, long height, long fillColor, long pQuad=1111b)

Description

This is identical to the Clarion function. Draws a filled or line ellipse. The ellipse is drawn inside a "bounding box" defined by the x, y, width, and height parameters. The x and y parameters specify the starting point, and the width and height parameters specify the horizontal and vertical size of the "bounding box."

Parameters
Parameter Description
long x An integer expression that specifies the horizontal position of the starting point.
long y An integer expression that specifies the vertical position of the starting point.
long width An integer expression that specifies the width.
long height An integer expression that specifies the height.
long fill A LONG integer constant, constant EQUATE, or variable containing the red, green, and blue components that create the color in the three low-order bytes (bytes 0, 1, and 2) or an EQUATE for a standard Windows color value.
long pQuad A Long consisting of one or more of the following equates (added together);
quad:TopRight, quad:TopLeft, quad:BottomLeft, quad:BottomRight, quad:Top, quad:Bottom, quad:Left, quad:Right, quad:All. If omitted Quad:All is used.
This parameter limits the ellipse to drawing only the quadrants specified.

Examples
Example
    drawer.Blank(color:white)
    drawer.SetPenColor(color:red)
    drawer.Ellipse(2, 2, 50, 80)                 ! draw an ellipse with a red line and no fill
    drawer.SetPenColor(color:black)              ! set the current pen color to black
    drawer.Ellipse(55, 2, 50, 80, color:blue)    ! black line and blue fill
  drawer.
ShadeEllipse(113, 2, 100, 80, color:yellow, color:red ) ! Shade an ellipse from yellow to red

drawer.Display()
ellipses screenshot
Information

In addition to the ellipse method Draw also provides a ShadeEllipse() method which allows you to draw ellipses with shaded fills.

See also: Blank, Display, SetPenColor and ShadeEllipse

EnumFontFamilies

EnumFontFamilies ()

Description

The EnumFonts method fills the gFontDispQ property of the draw class with all the fonts available on the system. In addition to the name to draw.gFontDispQ property also stores the font style, quality, weight etc.

In addition draw provides a FontDispQType that you can for queue to store font information, and to copy information from the Draw property into.

gFontDispQ property:
Field Type Description
name string(64) The name of the font, such as 'Arial' or 'Verdana'
style string(32) The style of the font, 'bold', 'italic' etc.
script string(32) A string specifying the script, that is, the character set, of the font. For example, Cyrillic.
weight long Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used.
quality byte Specifies the output quality. The output quality defines how carefully the graphics device interface (GDI) must attempt to match the logical-font attributes to those of an actual physical font. This specifies whether the font is anti-aliased, non anti-aliased, proof quality, draft quality etc.
pitchandfamily byte Specifies the pitch and family of the font. The two low-order bits specify the pitch of the font and Bits 4 through 7 of the member specify the font family.

Examples
Example
    drawer.EnumFonts()                 ! Fill a the drawer.gFontDispQ property with the font list
    ! This queue can be use to check a font is installed, displayed in a list or dropdown etc.

ErrorTrap

ErrorTrap (string errorStr, string functionName)

Description

Error handling procedure. By default no message is displayed and the function that an error occurred in simply returns. The default implementation of ErrorTrap checks the suppressErrors property of the Draw class, which is set to 1 by default. To enable the display of error messages set Draw.suppressErrors to 0. So in your code simply set:

drawer.suppressErrors = 0

FindPixel

FindPixel(*Long xPos, *Long Ypos, Long xDiff, Long yDiff, Long pIsColor=-1, Long pNotColor=-1), long

Description

From a starting position (xpos,ypos) travel in a specific direction (identified by xDiff and yDiff) until a pixel with the color IsColor is located. Alternatively until a pixel with any color not NotColor is located.) 

See Also


GetPixel

Flood

Flood(long xpos, long ypos, long pcolor)

Description

Floodfill an area of the diagram starting at a specific position (xpos,ypos). Traverses are done horizonatally and vertically until a pixel of a different color to the one under xpos/ypos is located. Note that this method is recursize so should be limited to a small area, or the stack memory for the thread should be set very large.

See Also

GetPixel

FormatMessage

FormatMessage (long errorCode), string

Description

Returns the error message associated with a Windows API error code. The error code is generally returned by the GetLastError() function. The GetLastError function is not a member of the draw class , and can be called without needing a Draw object.

Parameters
Parameter Description
long errorCode The Windows API error code to retrieve the associated error message for.
Return Value

The methods returns a string containing the error message associated with the Windows API error code that was passed.

Example
Example
Message('Windows API error ' & GetLastError() & ': ' & drawer.FormatString(GetLastError()))

FileToString

FileToString (*string fileData, string fileName), long

Description

Loads the entire contents of a file into a string. If the string passed is not large enough the required size is returned.

Parameters
Parameter Description
*string fileData Pointer to a string that the data from the file will be copied into. The string needs to be large enough to contain the entire contents of the file. If the string is not large enough the method returns the required size and leaves the string untouched.
string fileName A string specifying the path and name of the file to be read into the string

Return Values

The method returns 1 to indicate success, or zero to indicate failure. In addition if the passed string to too small to store the entire file, the required size of the string is returned.

Example
Example
dataBuffer &string
fName string(File:MaxFileName)
fileSize long

CODE

    fileSize = drawer.FileToString(dataBuffer, fName)
if fileSize = 0
! handle the error
return 0
    end

    dataBuffer &= New(String(fileSize))
if drawer.FileToString(dataBuffer, fName) = 0
! handle the error
end

Dispose(dataBuffer)    ! the string must be disposed once it is no longer needed.
See Also

StringToFile - write the content of a string to a file on disk.

GetDeviceCaps

GetDeviceCaps ()

Description

Sets a number of properties that describe the current windows and device display settings. Takes no parameters.
Property Description
Draw.hScreenRes The horizontal screen resolution in DPI (dots/pixels per inch)
Draw.vScreenRes The vertical screen resolution in DPI (dots/pixels per inch)
Draw.fontResMult A multiplier that keeps the font size visually the same as the resolution increases. Used internally for the font size calculation.
Draw.hScreenSize The width of the screen in pixels
Draw.vScreenSize The height of the screen in pixels
Draw.bitDepth The current Windows color depth
Example
Example
    myDrawer.GetDeviceCaps()
Message('The current screen dimensions are: ' & myDrawer.hScreenSize & ' x ' & myDrawer.vScreenSize & ' pixels.')

GetIconHandle

GetIconHandle (string iconName, <ulong hIconModule>, <long iconSize>), ulong

Description

Retrieves a handle to an icon for use with the LoadIcon method. This supports loading icons from disk and resource, as well as allowing the size of the icon to be specified. The method will automatically load the icon from resource if it exists, otherwise it will load it from disk. If no size is specified it uses the default icon in the icon file. If a size is specified the closest icon is selected, and resized to the specified size if necessary.

Parameters
Parameter Description
string iconName The name of the icon to load, if loading from file and the icon is not in the current directory then the path should be specified.
ulong hIconModule A handle to the icon module, as returned by the drwGetModuleHandle() function. The method will get a handle to the current module automatically, this parameter is only provided to allow icons from external modules (DLLs) to be loaded.
Return Values

Returns a handle to the icon if the methods succeeds, or zero if it fails.

See Also

LoadIcon

GetDisplay

GetDisplay ()

Description

Write whatever is in the image control back to the current Draw layer. Note that GetDisplay() will retrieve whatever is in the Clarion image control, regardless of whether Draw understands the format. This method is primarily provided to draw over bitmaps that have already been loaded by Clarion. The Draw does not support formats other than Windows 24 bit bitmaps. GetDisplay will write the contents into the currently active layer, so the layer should be at least as large as the image control. Unless there is a specific reason to allow Clarion to load the BMP into the image control it is advised that you call the Image() method.

Examples
Example
! create a new layer, the same size as the baseLayer:
drawer.InitLayer(2, drawer.baseLayer.width, drawer.baselayer.height, 1, 1, color:none)
drawer.Withlayer(2)     ! make the new layer the current active layer
drawer.GetDisplay()     ! copy the data in the image control onto the current layer
drawer.Display()        ! Display all currently visible layers in the image control
See Also

InitLayer( ), baseLayer, Using Layers, WithLayer( ), Display( ), Image( )

GetDevicePixel

GetDevicePixel (long x, long y), long

Description

Get a pixel from anywhere on the screen and return a long (the color as RGB). This is considerably slower than the GetImagePixel() method, so if you need the color of a pixel within the Draw control, it is strongly advised that you call GetImagePixel() instead of GetDevicePixel().

Examples
Example
    ! capture the top left hand corner of the screen and copy it onto the current draw layer
    loop x = 1 to drawer.width
        loop y = 1 to drawer.height
            drawer.SetPenColor(drawer.GetDevicePixel(x, y))
            drawer.PutPixel(x, y)
        end
    end
    drawer.Display()
See Also

SetPenColor( ), PutPixel( ), GetImagePixel( )

GetImagePixel

GetImagePixel (long x, long y), long

Description

Get a pixel from anywhere within the image control, uses draw coordinates, so (1, 1) is the top left corner and (width, height) is the bottom right. Returns a long which is the color in RGB format.

Notes

Draw 2.11 provides a GetPixel() method that is identical to the GetImagePixel() method.

GetPixel

GetPixel (long x, long y), long

Description

Get a pixel from anywhere within the imagecontrol, uses draw coordinates, so (1, 1) is the top left corner and (width, height) is the bottom right. Returns a long which is the color in RGB format. Identical to the GetImagePixel method (simply provides an alternative name).

See Also

GetImagePixel

GetWindowsColors

GetWindowsColors ()

Description

Retrieves the Windows interface colors from the registry. The colors are stored in the following variables:

dColor:ScrollBar
dColor:Background
dColor:ActiveCaption
dColor:InactiveCaption
dColor:InactiveCaptionText
dColor:Menu
dColor:MenuText
dColor:Window
dColor:WindowText
dColor:WindowFrame
dColor:TitleText
dColor:ActiveBorder
dColor:InactiveBorder
dColor:AppWorkSpace
dColor:Highlight
dColor:HighlightText
dColor:btnFace
dColor:btnShadow
dColor:btnText
dColor:btnHighlight
dColor:GrayText

GrabScreen

GrabScreen (long x, long y, long width, long height, long xdest, long ydest)

Description

Captures the area of the screen defined by the rectangle with the top left corner at (x,y) and with dimensions defined by width and height (in pixels). The captured image gets placed on the imagecontrol with the top left corner at (xdest, ydest). If the captured image is too large it is clipped.

HalfEllipse

HalfEllipse (long x, long y, long width, long height, long innerColor=-1, long outerColor=-1, long orientation=1)

Description

Draws half an ellipse (or half a circle). The half ellipse can be filled with a single color (specify innerColor only), shaded from innerColor to outerColor, or line only (both innerColor and outerColor are set to the default values - color:none).

Parameters
Parameter Description
long x The x coordinate to place the top left hand corner of the bounding box of the ellipse at.
long y The y coordinate to place the top right hand corner of the bounding box of the ellipse at.
long width Width of the ellipse (the full ellipse, not the half section being drawn)
long height Height of the ellipse (the full ellipse, not the half section being drawn)
long innerColor The color to optionally fill the ellipse section with, if outerColor is specified then the half ellipse is shaded from innerColor to outerColor.
long outerColor If specified then the half ellipse is shaded from innerColor to outerColor.
long orientation The section of the ellipse to draw: 1 = top hemisphere, 2 = bottom hemisphere, 3 = left hemisphere, 4 = right hemisphere.
See Also

Ellipse, ShadeEllipse, Sphere

HsvToRgb

HsvToRgb (hsvColorType HSV), long

Description

Converts and HSV color (Hue, Saturation and Value) to a standard Clarion RGB color.

HsvToRgb colour conversion screenshot

Draw defines an hsvColorType as a group of three Reals, representing the Hue, Saturation and Value of the color. The values of each component range from 0 to 1, unlike RGB which ranges from 0 to 255.
hsvColorType 	group, type
h 					real
s 					real
v 					real
				end
Parameters
Parameter Description
*hsvColorType HSV An HSVColor group that will be converted to RGB.
Return Values

None

Example
Example
hsvColorgroup(hsvColorType)
              end
rgbColor       long

hsvColor.h = 0.333    
! Primary Green
hsvColor.s = 1.0      
! Fully saturated
hsvColor.v = 0.7      
! Medium green (1.0 would be bright, primary green)

rgbColor = Drawer.HsvToRgb(hsvColor)
    Drawer.
SetPenColor(color:black)
    Drawer.
Box(1, 1, 120, 120, rgbColor)
    Drawer.Display()
HsvToRgb example screenshot
See Also

RgbToHsv, ClarionToRgb

Highlight

Highlight (long x, long y, long width, long height, long hColor)

Description

Highlights the area specified using the color passed. This created an "inverted" or "negative" effect, very much like a word processor would use to indicate a block of selected text. The method performs an XOR (binary exclusive OR) with hColor over the rectangular region specified by x, y, width and height. Calling Highlight() twice with the same parameters will restore the region to its original state. This is useful for highlighting a section of text or any other object, where the object color and background color contrast.

Image

Image (long x, long y, long width=-1, long height=-1, string filename, long flag=-1, long colorMask=-1),long,proc

Description

Place an image from a file onto the current layer.

Parameters
Parameter Description
long x the x coordinate to place the top left hand corner of the image at. Specifying a negative x value will clip (not draw) the section of the image that falls outside of the layer.
long y the y coordinate to place the top right hand corner of the image at.
long width reserved for future use
long height reserved for future use
string fileName a string specifying the name of the bitmap file to load.
long flag if the value of the flag parameter is draw:tileImage the Image() method will tile the image across the current layer, starting at the coordinates specified by the x and y parameters.
long colorMask colorMask allows a color to be used as an index transparency value, which means that any pixels in the source image that are the same color as colorMask will not be copied onto the destination layer.
Example

The example below checks the color of the top left pixel in the image and then loads a bitmap based on whether the pixel is closer to black or white, then the call to Image() sets the colorMask parameter as the background color color of the bitmap. The image is placed at the current (x,y) coordinates of the mouse, using MouseX() and MouseY().
Example
if drawer.GetImagePixel(1, 1) > 0888888h           ! closer to white than black
    drawer.Image(drawer.
MouseX(), drawer.MouseY(), , , 'fm2_CCCCCCh.bmp', , 0CCCCCCh)
else
    drawer.Image(drawer.
MouseX(), drawer.MouseY(), , , 'fm2_333333h.bmp', , 0333333h)
end
drawer.
Display()
Bitmaps being loaded:

fm2_333333h.bmp fm2_CCCCCCh.bmp
The result of the above code used to place the bitmaps on the Draw image control using a color mask for transparency:



Information

It is often convenient to place an image onto a hidden layer, where it can then be drawn to any other layer without any any disk access. The Draw class provides a ImageDimensions() method to get the pixel width an height of a bitmap file on disk:
Code:
1
2
3
4
5
6
7
8
9
10
11
imgWidth            long
imgHeight           long
curlayer            long
imglayer            long


    drawer.ImageDimensions(imgWidth, imgHeight, 'myBitmap.bmp')
    imgLayer = drawer.numlayers + 1
    drawer.InitLayer(imglayer, imgWidth, imgHeight, 1, 1, color:none, draw:hidden)
    curLayer = drawer.activelayer
    drawer.withlayer(imgLayer)
    drawer.Image(1, 1, , , 'myBitmap.bmp')

Comments:
6
7
8
9
10
11
get the size of the bitmap file and save the width and height in imgWidth and imgHeight
retrieve the current number of initialized layers and increment it by one
create a new layer with the same width and height as the image, create the layer as hidden
save the current active layer number
select the new layer
draw the image from the file onto the new layer

In order to use the image on any other layer simply call CopyLayer() to copy from the image layer to the destination layer. It is also simple to use index transparency by calling SetMode() for the image layer.

ImageDimensions

ImageDimensions (*long width, *long height, string filename)

Description

Sets the width and height parameters to the width and height of the image specified by filename. The file must be a bitmap.

Parameters
Parameter Description
*long width Variable to receive the width of the image
*long height Variable to receive the height of the image
string filename File name and path of image to retrieve the width and height from
Example
Example
iWidth            long
iHeight           long

    drawer.ImageDimensions(iWidth, iHeight, 'c:\images\foo.bmp')


    drawer.ImageDimensions(iWidth,iHeight,'myBitmap.bmp')

ImageFromBuffer

ImageFromBuffer (*string dataBuffer, long x, long y, long width, long height, long tileX=0, long tileY=0, long clipWidth=0, long clipHeight=0), bool, proc

Description

Writes from a buffer that contains RGB data to a layer, allows the position of the image to be specified, along with the ability to clip the image and tile it both horizontally and vertically. Tiling in either direction can be specified independently. The method handles clipping and zero padding automatically. The width and height of the image must be specified so that the length of each scanline can be calculated.

Parameters
Parameter Description
string dataBuffer A string containing the RGB data for the image.
long x The x coordinate on the current layer to place the image at.
long y The y coordinate on the current layer to place the image at.
long width The width of the image that is stored in the buffer.
long height The height of the image that is stored in the buffer.
long tileX [Optional] The number of times the images should be tiled (repeated) horizontally.
long tileY [Optional] The number of times the images should be tiled (repeated) vertically.
long clipWidth [Optional] Allows the maximum width to be specified, anything outside of this width will be clipped (removed). This applies to both a single image being placed and when tiling is used. The clipWidth and clipHeight form a bounding box for drawing the image within.
long clipHeight [Optional] The maximum height, allows a bounding box for drawing the image within to be specified. See clipWidth above.
Return Values

The method returns 1 for success and zero for failure.

Init

Init (ulong control)

Description

Init is called when the control is created, you don't need to call Init explicitly, it is handled for you. If you are drawing to a report you must call SetTarget(report) BEFORE the call to Init( ). See the Clarion documentation for more on SetTarget().

Parameters
Parameter Description
ulong control Handle to the image control to draw to.
Example
Example
Drawer.Init(?Drawer)

Init256

Init256 ( )

Description

When you need to draw a 256 colour image (perhaps you are sending the image across a network, or it needs to be dropped into a report, and the report is bloating excessively) you should call Init256() to create the necessary data structures for storing and creating the 256 colour bitmap. By default when Init256() is called the Draw.colors256 flag is set to TRUE (1), this will result in the Draw image control displaying the 256 colour image. You can flip between 8 bit (256 colours) and 24 bit (around 16.7 million colours) simply by setting the Draw.colors256 flag and then calling Display(). Setting Draw.colours256 = 1 will display the 256 colour image, while setting Draw.colours256 = 0 will display the 24 bit image. Note that when colors256 is set to 1 Draw still works internally in 24 bit colour, the Display() method simply creates a 256 colour image from the 24 bit image and outputs it to the Draw image control. This means that the 24 bit image still exists and can be used at any time, it also means that the Display() method is slower for 256 colour images, so unless there is a good reason to use them, you won't see a speedup. Also note that the WriteBMP() method will write the 256 colour image to a file if the colours256 flag is set to 1. So even if you are drawing a 24 bit image you can still write the 8 bit image to disk. For example you might need to output both 24 bit and 8 bit images, in which case you could do the following:

drawer.Init256()                ! initialise Draws 256 colours features

! --- do your draw commands here --- !

drawer.colours256 = 0           ! disable 256 colour drawing
drawer.Display()                ! you don't have to call Display() unless you want to see the results of your
                                ! drawing in the image control

drawer.WriteBMP('24bit.bmp')    
! write a 24 bit image to a file called "24bit.bmp"

drawer.colors256 = 1
    
drawer.WriteBMP(8bit.bmp)
       ! write a 256 colour image to a file without displaying it

! if you call Drawer.Display() while the Drawer.colors256 flag is set to 1 you will
! display the 256 colour image in the image control.
drawer.Display()                ! Display the 256 colour bitmap

drawer.colors256 = 0            ! use 24 bit image display

...

drawer.Kill256()                ! clean up by destroying the data structures that were used by 256 colour drawing

! Note that once Kill256() has been called the Draw.colors256 flag has no effect whatsoever,
! and Kill256() will set it to zero.


When Draw.Kill() is called, either manually or automatically when the window the image control was on is closed, Draw.Kill256() is automatically called. You can call it manually if you no longer need 256 colour drawing, but if you don't call it Draw will clean up after itself.

Parameters

none

Example
Example
Drawer.Init256()                         ! see above for a full example of how to use Init256(), Draw.colours256 and Kill256()
See also

Kill256( ), Display( ), WriteBMP( ), Init(), Kill() and colors256

Kill

Kill ( )

Description

Like the Init() method, Kill() is called automatically by the template. If you create the Draw object your self you should call Kill() when you are finished using the object.

Kill256

Kill256 ( )

Description

Destroys data structures used to 256 colour drawing and disables 256 colour drawing. Once Kill256() as been called the Draw.colours256 flag has no effect. See Init256() for more details and examples of how to use Kill256() and 256 colour drawing.

Line

Line (long x, long y, long width, long height)

Description

This is identical to the Clarion function. Draws a line starting at (x,y) with a width and height specified by the width and height parameters. To set the line width call Draw.SetPenWidth() and to draw lines using a patterned style call Draw.SetPenStyle(). You can also draw lines shaded from one color to another using the ShadeLine() method.

LoadIcon

LoadIcon (long x, long y, string iconFileName, long width=-1, long height=-1, long bpp=-1, long index=-1, byte alphaChannel=-1, ulong hIcon=0),long,proc

Description

This Method allows you to load an image out of a Windows Icon file and place it on the Draw control. The icon can be loaded from disk, or from a resource included in the project.

When loading an icon from a resource a handle to the icon needs to be passed instead of the icon file name. GetIconHandle can be used to get a handle to an icon resource:

! Get a handle to the icon resource
hIcon = ds_GetHIcon(Clip(self.Icons[y].IconName), , 32);
! Use Draw to display the icon
Drawer.LoadIcon(1, 1, '', 32, 32, 32, , , hIcon)

Note: Draw currently supports all icon sizes and color depths, except for 4 bit and 24 bit icons loaded from disk (they are supported when loading from resources).

The method supports 1, 4, 8, and 24 bit color icons with transparency (a single color is treated as fully transparent, this is known as "index transparency"), as well as 32 bit color icons, which includes an alpha channel. The alpha channel allows areas of the icon to be partially transparent, which gives a "soft" transparency look. This can be seen with the soft drop shadows that some icons use. An icon using 32 bit color uses 24 bits per pixel for the RGB color information, and the remaining 8 bits to store a level of opacity (0-255).

If the bit depth is not specified then the highest bit depth available is used. If the width and bit depth are specified and no icon that matches the required format is found then the method returns 0.

The method returns 1 if successful, otherwise it calls ErrorTrap and returns 0.

Parameters
Parameter Description
long x The x coordinate to place the top left hand corner of the image
long y The y coordinate to place the top left hand corner of the image
string fileName The name of the icon to load. If the icon is a resource the name should be an empty string and the hIcon parameter should contain a handle to the icon resource.
long width [Optional] The width of the icon to load
long height [Optional] The height of the icon to load (generally equal to the width)
long bpp [Optional] The color depth of the icon to load (4, 8, 16, 24 or 32 bits per pixel). Not supported in loading icons from resource, the highest bit depth available is used.
long index [Optional] If this is specified all other parameters are ignored at the icon at this position is loaded
byte alphaChannel Not Currently Supported. Specifies the layer alpha channel to copy the icon's alpha channel into. Only valid if the layer the icon is being drawn onto has an alpha channel. Leaving out this parameter will still use the alpha channel of the icon when copying the pixels onto the layer, this just allows you to preserve the transparent area of the icon by copying the alpha values of the icon pixels into the alpha channel.
ulong hIcon When loading from an icon resource the hIcon parameter should contain a handle to the icon resource.

Examples
Example
Load and icon using variables for the required size (reqWidth) and color depth (reqColors):

    if Drawer.LoadIcon(xpos, ypos, 'myIcon.ico', reqWidth, , reqColors)
        
! icon loaded
    else
        
! handle errors here, ErrorTrap() will display
        ! information if Drawer.suppressErrors = 0
 
    end


Load a 48x48 icon with 32 bit color, within an icon file containing many icons:

    Drawer.LoadIcon(10, 10, 'smile.ico', 48, 48, 32)

Load the first icon in the file, or there is only one icon:

    Drawer.LoadIcon(10, 10, 'smile.ico')

If you know the position of the icon you would like to load in the icon file:

    ! load the image that is at position 3 in the icon file    
    Drawer.LoadIcon(10, 10, 'smile.ico', , , , 3

Load an icon, either from a resource or a file, specify the size and color depth, but if they don't exist then load whichever icon exists:

if Instring('~', IconName, 1, 1)       ! Icon is a resource, not from disk
  hIcon = ds_GetHIcon(IconName, , 32)  ! Attempt to fetch the 32x32 icon
  if
hIcon = 0                         ! If no 32x32 then fetch the first icon in the resource
    hIcon = ds_GetHIcon(IconName)
  end
  if
hIcon = 0
   
! Report error: Could not load the icon. The icon resource could not be located.
  else

    Drawer.Loadicon(1, 1, '', 32, 32, 32, , , hIcon) ! Load the icon from a resource
  end

else
! Load the icon from disk
  if not Drawer.Loadicon(1, 1, IconName, 32, 32, 32)
! Try load the 32 bit icon (32x32 pixels)
    if not
Drawer.Loadicon(1, 1, IconName, 32, 32)   ! Any bit depth (32x32 pixels)
      Drawer.Loadicon(1, 1, IconName)                ! Any icon
    end

  end

end
If you would like to edit or create your own icons it is recommended that you use a tool such as the excellent Axialis IconWorkshop Pro (see www.axialis.com)

Some background on the icon file format:

A Windows icon file (.ICO) stores one or more images within a single file. Generally each image within the file is the same image at different sizes and color depths. Standard icon sizes are 16x16 pixels (small icons), 32x32 pixels (standard icons) and 48x48 icons (large icons). Versions of Windows prior to WindowsXP used 256 color (8 bit) icons as well as 16 color (4 bit) icons. WindowsXP introduced a new icon format that supports larger icon sizes, as well as 32 bit color. A typical WindowsXP icon contains 4, 8, and 32 bit color icons in a variety of sizes, normally 16x16, 24x24, 32x32 and 48x48 pixels. Although the icon format allows icons with any width and height, only square icons are supported in use (the width and height should be equal).

See Also

GetIconHandle

Log

Log (string messageStr)

Description

The Log method takes a sting parameter and writes it to the windows debug output. This output can be viewed using a free tool such as DebugView from www.sysinternals.com.
This allows you to view debug output whether the program is compiled in Debug or Release modes, and it has a negligible performance impact, as well as having no affect on your code execution (unlike the Message() and Stop() functions). In order to use the Log function you should set the Draw.logging property to 1. This also means that any errors that Draw encounters will be logged. Logging is in dependent of whether the suppressErrors property is set, so you can set Draw.suppressErrors to 1 to allow error to be handled by your program and not displayed to the user, but still have output using the Log method.

Parameters
Parameter Description
string messageStr A string to print to the debug output. There is no Draw limit on the length of the string.
Examples
Example
    Drawer.logging = 1   ! enable logging
Drawer.suppressErrors = 1        ! hide any error messages from the end user (only send errors to the debug output)
Drawer.Log('Draw  box at: ' & xpos & ', ' & ypos)
    Drawer.Log('Current layer width: ' & Drawer.width & ', current layer height: ' & Drawer.height)

MetallicCylinder

MetallicCylinder (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long XP = -1, long yp=-1, long depth, byte intensity=-1, long eCol=-1)

Description

Double shaded cylinder functionality as provided by the Cylinder( ) method, with an alternative shading algorithm.

Metallic Shaded Cylinders
metallic shaded cylinders screenshot

MouseX

MouseX ()

Description

Returns the x coordinate (in pixels) of the current mouse position with respect to the origin of the image control (the top left hand corner).

MouseY

MouseY ()

Description

Returns the y coordinate (in pixels) of the current mouse position with respect to the origin of the image control (the top left hand corner).

PieSlice

PieSlice (long x, long y, long width, long height, PieSliceType pSlice) (BETA)

Description

Draws a "Pie Slice" - a section of an ellipse (or a circle) form by an arc and two radii. The Pie slice is drawn counter clockwise from startAngle to endAngle.

pieslice screenshot

Parameters
Parameter Description
long x The x coordinate of the top left hand corner of the bounding box of the ellipse
long y The y coordinate of the top left hand corner of the bounding box of the ellipse
long width Width of the ellipse
long height Height of the ellipse
long pSlice The data structure that defines how the pie slice will be drawn (see below)
Note that other than startAngle, endAngle and OuterColor, all other fields are optional. See the example below for how you can use the same PieSlice data structure to draw multiple pie slices by modifying the groups variables between each call.

arc screenshot

PieSlice Group Type
Name Type Default Description
startAngle long 0 The angle that the slice starts at, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.
endAngle long 0 The angle that the slice ends at, in tenths of degrees (10 = 1 degree) measured counter-clockwise from three o'clock.
outerColor long color:none The color at the outer edge of the pie slice
innerColor long color:none The color at the inner edge of the pie slice
borderColor long color:none An optional parameter that specifies the color of a line around the pie slice (by default no border is drawn)
highlightPos long 0 Specifies that a highlight should be be created (the shading shades from outerColor to the highlight and then to innerColor). This value is the percentage across the slice that the highlight should be drawn at.
highlightIntensity long 0 The intensity of the highlight, from 0 to 100 (where zero is no highlight and 100 is pure white).
startRadius long 0 The radius to start the slice at (allows the slice to be smaller than the full ellipse). Percentage value from 0 to 100.
endRadius long 100 The radius to end the start at (this creates a "donut" slice, where the slice ends before the center of the ellipse). Percentage from 0 to 100.
dropHeight long 0 Optional parameter to specify the 3D drop section of the pie slice. Note in version 2.10 only the curved section of the drop is drawn, future versions will also draw the polygonal "edges" of the pie slice.
dropType long 0 Specifies the type of shading to use for the 3D drop section of the pie slice. This can be set to Draw:Horizontal, Draw:Vertical or Draw:Solid, which do horizontal, vertical or no shading respectively.
dropColor1 long color:none The color to use for the drop section of the slice. If dropType is not set to Draw:Solid then this is the color to start shading from.
dropColor2 long color:none The color to shade the drop to.
dropHighlightPos long 0 Specifies a highlight position in the shading for the drop section of the slice, values range from 0 to 100.
dropHighlightIntensity long 0 The intensity of the highlight, from zero (which does not draw any highlight at all) to 100 (pure white).
Examples

See the example application in Clarion\3rdParty\examples\draw\Demo for the source code that creates the image below. The example code listed below is a simplified version that draws the pie slices without drop shadows or text. The Demo example also includes the code to draw the drop shadowed text.

pie slice with drop shadow and 3D "Donut" slice with highlight screenshot
Example
sAng long(200)
eAng long(2200)
width long(250)
height long(160)


CODE

    drawer.Blank(color:white)
    curSlice.startAngle = sAng
    curSlice.endAngle = eAng

    ! ------------- The first pie slice ----------- !
curSlice.outerColor = Random(color:white, color:black)
    curSlice.innerColor = Random(color:white, color:black)
    curSlice.startRadius = 0
    curSlice.endRadius = 100
    curSlice.dropHeight = 0
    curSlice.highlightPos = 0
    curSlice.highlightIntensity = 0
    drawer.PieSlice(30, 40 , width, height, curSlice)

! ----------- The Second Pie Slice ------------ !
curSlice.outerColor = Random(color:white, color:black)
    curSlice.innerColor = Random(color:white, color:black)
    curSlice.highlightPos = Random(30, 70)
    curSlice.highlightIntensity = Random(40, 80)
    curSlice.startRadius = 20
    curSlice.endRadius = 100
    curSlice.dropHeight = 25
    curSlice.dropColor1 = curSlice.outerColor
    curslice.dropColor2 = curSlice.innerColor
    drawer.PieSlice(20, 200 , width, height, curSlice)

    drawer.Display()

Polygon

Polygon (*long[] vertices, long fill=-1, long numVertices)

Description

This is identical to the Clarion function. Draws a polygon, the array contains x and y coordinate pairs for each point on the polygon. Polygons are always closed, the last point will automatically be joined to the first. It is recommended that polygons vertices are defined in the array in clockwise order.

Parameter Description
*long[] vertices An array that defines the vertices for the polygon. Each pair of entries in the array define the x and y coordinates of a vertex. For example to draw a quadrilateral you would need an array with 8 entries to specify the four vertices.
long fill=-1 The fill color to be used for the polygon. The default value is no fill (color:none), which draws a line only polygon.
long numVertices=0 Allows the number of vertices to be specified if there are more entries in the the array than there are vertices required. For example the first 8 entries in an array of 256 elements could be set to the coordinates for the four vertices of a quadrilateral, this parameter would then be set to 4 to ensure that only the first 4 vertices (8 array entries) are used. If this number is set to great than half the size of the array, then there are not sufficient entries in the array for the number of vertices required and the function will return and call ErrorTrap with the error description.
Example
Example
   drawer.Blank(color:white) 				! Clear the Draw control
    !---- Create the quad ----!
pVertices[1] = Random(5, 60)
    pVertices[2] = Random(105, 160)
    pVertices[3] = Random(120, 200)
    pVertices[4] = Random(105, 160)
    pVertices[5] = Random(120, 200)
    pVertices[6] = Random(220, 300)
    pVertices[7] = Random(5, 60)
    pVertices[8] = Random(220,300)
    drawer.SetPenColor(color:none)             ! Draw the polygon without a line around it
drawer.Polygon(pVertices, color:red)       ! Draw a polygon with a red fill
drawer.Display()

PointInPolygon

PointInPolygon (*long[] vertices, long numVertices, long x, long y), long

Description

Returns whether a coordinate passed is inside a defined polygon or not. This can be used to determine whether a user clicked in any area in the image control that can be defined by a polygon, or whether a user clicked on a particular polygon in the Draw control.

Parameters
Parameter Description
 *long[] vertices An array that defines the vertices for the polygon. Each pair of entries in the array define the x and y coordinates of a vertex. For example to draw a quadrilateral you would need an array with 8 entries to specify the four vertices.
long numVertices Allows the number of vertices to be specified if there are more entries in the the array than there are vertices required. For example the first 8 entries in an array of 256 elements could be set to the coordinates for the four vertices of a quadrilateral, this parameter would then be set to 4 to ensure that only the first 4 vertices (8 array entries) are used. If this number is set to great than half the size of the array, then there are not sufficient entries in the array for the number of vertices required and the function will return and call ErrorTrap with the error description.
long x The x-coordinate of the point to check.
long y The y-coordinate of the pint to check.
Return Values

If the point given by the x and y parameters is within the polygon then then the method returns 1, otherwise it returns zero.

Example
Example
    !---- Create the quad ----!
    pVertices[1] = Random(5, 60)
    pVertices[2] = Random(105, 160)
    pVertices[3] = Random(120, 200)
    pVertices[4] = Random(105, 160)
    pVertices[5] = Random(120, 200)
    pVertices[6] = Random(220, 300)
    pVertices[7] = Random(5, 60)
    pVertices[8] = Random(220,300)

if drawer.PointInPolygon(pVertices, 4, drawer.MouseX(), drawer.MouseY())
    Message('The mouse is currently in the polygon')
end

PutPixel

PutPixel (long x, long y, <Long Layer>)

Description

Put a pixel of the current pen color (see SetPenColor) at the coordinates given by x and y on the layer specified. If the layer parameter is omitted then the current active layer is used.

ResetDisplayArea

ResetDisplayArea Procedure()

Description

Resets the display are to display the entire Draw canvas. The SetDisplayArea method is used to limit displaying to a rectangular region when calling Display, which is used to improve performance when a small area has been changed and the entire control (canvas) doesn't need to be redrawn. This can dramatically improve display performance, particularly with large canvases, many layer, or when calling Display frequently such as when creating animations

Parameters

None

Return Value

None

Resize

Resize (long width=-1, long height=-1, copyData=0)

Description

Allows the image buffer to be resized. Default is to resize to the current control size. Or you can specify the width and height to resize the buffer to.

Note:
that this does not resize any layers other than the baseLayer, so when using multiple layers the ResizeLayer() methods must be called to perform any layer resizing needed.

Parameters
Parameter Description
width [Optional] The width to resize to. If not specified, or less than 1, the width is set to the current width of the Image control
height [Optional] The height to resize to. If not specified, or less than 1, the height is set to the current height of the Image control
copyData [Optional]. If this is passed as non zero then the image data is copied into the new buffer, otherwise the image is cleared to black.
Returns

True (1) for success and False (0) for failure. ErrorTrap is called in the event of failure with additional information.

Example
Example
!--- Resize the buffer to the current image control size
Drawer.Resize() 
!--- Resize the buffer to 180 by 400 pixels, note that the control size is not changed
Drawer.Resize(180, 400) 
!--- Resize all layers
Drawer.Resize()              ! Resize the base layer
loop i = 2 to DRAW:NUMLAYERS ! Resize any other layers that have been initialized
    if Drawer.layers[i].init ! Layer is in use
        Drawer.ResizeLayer(i, Drawer.baseLayer.width, Drawer.baseLayer.height)
    end
end

ResizeControl

ResizeControl ()

Sets the control size to the current buffer size. Does not take parameters or return a value.

RgbToHsv

RgbToHsv (long rgbColor, *hsvColorType HSV)

Description

Convert a standard RGB color to and HSV color (Hue, Saturation and Value) . HSV colors allow easier manipulation of the color than RGB. For example to darken or lighten an HSV color the Value component can be lowered or raised. To increase saturation (color intensity) the Saturation value can be increased.

RgbToHsv screenshot

Draw defines an hsvColorType as a group of three Reals, representing the Hue, Saturation and Value of the color. The values of each component range from 0 to 1, unlike RGB which ranges from 0 to 255.

hsvColorType 	group, type
h 					real
s 					real
v 					real
				end
Parameter
Parameter Description
long rgbColor A standard clarion RGB color, such as 0FF66FFh, color:red etc.
*hsvColorType HSV An HSVColor group that the converted color will be placed into.
Return Values

None

Example
Example
hsvColor       group(hsvColorType)
              end

Drawer.RgbToHsv(
color:red, hsvColor)
See Also

HsvToRGB

RoundRect

RoundRect (long x, long y, long width, long height, long eWidth, long eHeight, long lineColor=color:none, fill=color:none)

Description

Draws a round cornered rectangle that is the width and height passed, and where the corner rounding is determined by the eWidth and eHeight parameters. If no line color is passed, then the current pen color is used.



Parameters
Parameter Description
long x The x (horizontal) position to place the object at.
long y The x (vertical) position to place the object at.
long width The width (in pixels) of the rectangle.
long height The height (in pixels) of the rectangle.
long eWidth The width of the bounding box that would encompass the ellipse that the round corner is formed from. For a corner that is 10 pixels wide, this should be set to 20 pixels.
long eHeight The height of the bounding box that would encompass the ellipse that the round corner is formed from. For a corner that is 10 pixels high, this should be set to 20 pixels.
long lineColor The color of the rectangle's line. If this is omitted, then the current pen color is used.
long fill The color to fill the rectangle. If this is omitted then the rectangle is not filled.

SetPenstyle

SetPenstyle (long style)

Description

Sets the pen style to one on the predefined Clarion styles:

SetPenWidth

SetPenWidth (long width)

Description

Sets the penwidth member data to the value given by width. You can also set penwidth directly by assigning a value to the penWidth property of the Draw object.

SetPenColor

SetPenColor (ulong color)

Description

Sets the current pen color, this is the color lines, curves, boxes etc. are drawn in. This has no effect on the current fill color or the current font color. The fill color is set in each method (passed as a parameter) and the font color is set by calling SetFontColor(color). The default pen color is black. Once you set the pen color it will remain that color until SetPenColor is called with a new color.

Parameters
Parameter Description
ulong Color The color to set the pen to, range from 0 (black) to 0FFFFFFh (white). Hex colors are stored as BGR.
Examples
Example
Drawer.SetPenColor(color:red)           ! set pen color to red
Drawer.SetPenColor(0FFFF00h)            ! set pen color to yellow
Drawer.SetPenColor(65280)               ! set pen color to green

SetFill

SetFill (String Pattern)

Description

Sets the fill type to a pattern instead of a solid, you can use any of the pattern equates, or create your own pattern. To make it easier to create patterned fills Draw Beta 7 and above ships with the Draw Pattern Maker, which allows you to easily create a pattern in realtime with a graphical user interface.

CapeSoft Draw Pattern Fill Maker

Once you have a pattern that you like you can simply copy and paste the string of ones and zeros into Clarion to use with the SetFill method.
To set the fill back to a solid color call SetFill() with an empty string or call SetFill(pattern:None)

Parameters
Parameter Description
String pattern A string of ones and zeros which represent and 8 x 8 pixel pattern.
Examples
Example
     drawer.SetFill(pattern:stars)           ! set the fill pattern to a Draw pattern equate
          drawer.SetPenColor(color:red)           ! set pen color to red
          drawer.Box(10, 10, 120, 120, color:red)     ! draw a red box with a patterned fill

Built in Equates:
pattern:None
pattern:FineDiagonal
pattern:CoarseDiagonal
pattern:CoarseVertical
pattern:FineChecked
pattern:CoarseChecked
pattern:CoarseZigZag
pattern:Cross
pattern:Tiles
pattern:CoarseHorizontal
pattern:Kite
pattern:CrossHatch
pattern:Squares
pattern:Ducks
pattern:Smilies
pattern:Stars
pattern:Grey
pattern:Waves
pattern:Zigzag
pattern:VeryThickZigZag
pattern:Chainmail
pattern:SmallVerticalZigZag
pattern:Pebbles
pattern:CoarsePebbles
pattern:LargePebbles
pattern:Mosiac
pattern:LargeDots
pattern:SmallDots
pattern:InversedSmilies
pattern:Circuits


These equates can be found in the Draw.inc file in your 3rdparty\libsrc directory off your Clarion root directory.

SetFont

SetFont (<String pName>,Long pSize=-1,Long pColor=-1,Long pStyle=-1,Long pCharset=-1)

Description

Allows the programmer to specify the font to use for the Show, and other, methods, that make use of a font.

Parameters
Parameter Description
String pName the name of the typeface to use. Like Arial, or Tahoma etc. If omitted or blank it defaults to the font of the current window.
Long pSize The size of the font to use. If omitted it defaults to the font size of the current window.
Long pColor The color of the font to use. If you are only changing the color then use the SetFontColor method instead. If omitted the color of the font of the current window is used.
Long pStyle The style of the font. Equates like Font:Regular, Font:Bold and Font:Italic can be used. If omitted the style of the window font is used.
Long pCharset The Charset of the font to use. If omitted the charset of the window is used.

SetFontColor

SetFontColor (ulong color)

Description

The color to draw text in, used by the Show method. The default color is the current window text color. Syntax is the same as the SetPenColor() method.

Parameters
Parameter Description
ulong color The color to set the font to, range from 0 (black) to 0FFFFFFh (white). Hex colors are stored as
 BGR.

SetFontMode

SetFontMode (ulong mode)

Description

Sets the current font rendering mode. This is used to control how text is render, and whether it is anti aliased or not (anti-aliasing smooth's the edges of font, although smaller fonts are not anti-aliased in order to preserve legibility, in general fonts smaller than 13 point are not anti-aliased, although it is dependent on the particular font).

Parameters
Parameter Description
ulong mode The text rending mode. It can be one of the following values:

These three modes use the current user anti-aliasing settings (the windows font smoothing settings):
Draw:DEFAULT_QUALITY
Draw:DRAFT_QUALITY
Draw:PROOF_QUALITY

To draw non anti-aliased text set mode to:
Draw:NONANTIALIASED_QUALITY

To draw anti-aliased text set the mode to:
Draw:ANTIALIASED_QUALITY

Not that smooth (anti-aliased) font are supported in Windows 95 Plus! and later.
Examples
Example
Drawer.SetFontMode(Draw:NONANTIALIASED_QUALITY)     ! turn off font smoothing
Drawer.SetFontMode(Draw:ANTIALIASED_QUALITY)        ! turn on font smoothing
Drawer.SetFontMode(Draw:DEFAULT_QUALITY)            ! use the current Windows font smoothing setting

ShadeBox

ShadeBox (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long XP = -1, long yp=-1, byte intensity=-1)

Description

Draw a shaded box.

There are three basic types of shaded box:
  1. Linear shading - simply shade from one color to another
  2. Single Shading - shading from one color to a highlight to a second color (which may or may not be the same as the first color)
  3. Double Shading - shading from one color to another, whilst shading toward the highlight perpendicularly
Parameters
Parameter Description
long x The x position to start the box at, in pixels
long y The y position to start the box at, in pixels
long width The box width, in pixels
long height The box height, in pixels
long lcol The color of the left hand side of the box - optional
long rcol The color of the right hand side of the box - optional
long tcol The color of the top of the box - optional
long bcol The color of the bottom of the box - optional
long XP The percentage along the x-axis for the highlight - optional
long yp The percentage along the y-axis for the highlight - optional
byte intensity The percentage intensity of the highlight - optional
The type of box drawn, and the direction of shading is dependent on the parameters passed. All box types require a x and y starting point as well as a width and height.

  1. Linear Shaded Boxes
    linear shaded boxes screenshot
  2. Single Shaded Boxes
    single shaded boxes screenshot
  3. Double Shaded Boxes
    double shaded boxes screenshot
Examples
  1. Linear Shaded Box - shaded left to right from red to green
    Draw.ShadeBox(10, 15, 180, 180, color:red, color:green)
  2. Single Shaded Box - left to right from red to blue, the highlight at 66% across and 100% intensity
    Draw.ShadeBox(10, 15, 180, 180, color:red, color:blue, , , 66, , 100)
  3. Double shaded box - red at top and yellow at the bottom, with the highlight 66% across and 100% intensity
    Drawer.ShadeBox(10, 15, 180, 180, color:none, color:none, color:red, color:yellow, 66, , 100)
linear, single and double horizontal shaded boxes screenshot

Boxes can also be shaded from top to bottom:

  1. Linear Shaded Box - shaded top to bottom, blue to white
    Draw.ShadeBox(10, 15, 180, 180, color:none, color:none, 00000FFh, 0FFFFFFh)
  2. Single Shaded Box - top to bottom from red to blue, the highlight at 50% down and 80% intensity
    Draw.ShadeBox(10, 15, 180, 180, color:none, color:none, color:red, color:blue, , 50, 80)
  3. Double shaded box - blue at left and cyan at right, with the highlight 40% across and 100% intensity
    Drawer.ShadeBox(10, 15, 180, 180, color:blue, 000FFFFh, color:none, color:none, , 40, 100)
linear, single and double vertical shaded boxes screenshot

ShadeEllipse

ShadeEllipse (long x, long y, long width, long height, long startColor, long endColor, long direction=0, byte xp = -1,byte yp=-1, long intensity=-1)

Description

Draws a shaded ellipse. Support shading from left to right, or top to bottom. Currently only linear shading is supported. Future version may add additional shading types. Also see the Sphere function for shading circles and ellipses from an outercolor to an innercolor, as well as specifying the the highlight position on the "sphere".

Parameters
Parameter Description
 long x x coordinate of the top left hand corner of the ellipse's bounding box
 long y y coordinate of the top left hand corner of the ellipse's bounding box
 long width The height of the ellipse, in pixels
 long height The width of the ellipse, in pixels
 long startColor The color to start shading from
 long endColor The color to shade to
 long direction The shading direction. Currently Draw:Horizontal (the default) and Draw:Vertical are supported.
All other parameters are unsupported at this time are are for future functionality.

Example
Example
    drawer.Blank()
    drawer.
SetPenColor(color:red)
    drawer.ShadeEllipse(10, 10, 180, 100,
color:red, color:green)
    drawer.
Display()

    shaded ellipse screenshot
See Also

Sphere - Draws an ellipses shaded from the outside to the inside.

ShadeLine

ShadeLine (long x, long y, long width, long height, long startColor, long endColor)

Description

This draws a line shaded from startColor to endColor, it only draws horizontal or vertical lines, and can be used to shade any shape.

Parameters
Parameter Description
long startColor The color to start shading from
long endClor The color to end shading at
Identical to the Line( ) method, with two additional parameters:

ShadePolygon

ShadePolygon (*long[] array, long startColor=-1, long endColor=-1, long numVertices=0)

Description

Identical to the normal Polygon method, except that it allows the polygon to be shaded from left to right, from startColor to endColor.

Parameters
Parameter Description
*long[] vertices An array that defines the vertices for the polygon. Each pair of entries in the array define the x and y coordinates of a vertex. For example to draw a quadrilateral you would need an array with 8 entries to specify the four vertices.
long startColor=-1 The fill color to be used for the polygon. The default value is no fill (color:none), which draws a line only polygon. If endColor is specified the the polygon is shaded from startColor to endColor. Currently only linear horizontal shading is supported.
long endColor=-1 Specifies the color to shade to. The parameter is optional, if not color is specified then the polygon is either dran with a solid fill (if startColor is specified) or with no fill (if both startColor and endColor are not specified).
long numVertices=0 Allows the number of vertices to be specified if there are more entries in the the array than there are vertices required. For example the first 8 entries in an array of 256 elements could be set to the coordinates for the four vertices of a quadrilateral, this parameter would then be set to 4 to ensure that only the first 4 vertices (8 array entries) are used. If this number is set to great than half the size of the array, then there are not sufficient entries in the array for the number of vertices required and the function will return and call ErrorTrap with the error description.
Identical to the Polygon( ) method, with two additional parameters:

Example
Example
 ! DATA
pVertices   long, dim(8)

! CODE
drawer.Blank(color:white)                ! Clear the Draw control
    !---- Create the quad ----!
pVertices[1] = Random(5, 60)
    pVertices[2] = Random(105, 160)
    pVertices[3] = Random(120, 200)
    pVertices[4] = Random(105, 160)
    pVertices[5] = Random(120, 200)
    pVertices[6] = Random(220, 300)
    pVertices[7] = Random(5, 60)
    pVertices[8] = Random(220,300)
drawer.SetPenColor(color:none) ! Draw the polygon without a line around it drawer.ShadePolygon(pVertices, color:red, color:green) drawer.Display() shaded polygon screenshot
See Also

ShadeLine, ShadeEllipse, ShadeBox, Sphere, Polygon

Show

Show (long x, long y, string text, long rotation=0)

Description

This is identical to the Clarion function. Displays a line of text in the current font color, set by SetFontColor. The only difference is the optional rotation parameter. This allows the text to be rotated from 0 to 360 degrees. Currently Version 1 of Draw only supports 0 or 90 degree rotations.

The font typeface and style are initially set to those of the parent windows, however the face and style can be set directly through the Draw.fontName and Draw.fontStyle member data.

The font size is initially set to that of the window on which the Draw control is place. You can set the font size using the Draw.fontSize member data.

Example
Example
    drawer.Blank(color:white)
    drawer.fontName = '
Arial'
    drawer.fontStyle =
font:bold + font:italic
    drawer.fontSize = 12
    drawer.
SetFontColor(color:red)
    drawer.Show(10, 10, '
CapeSoft Draw TrueType Text')
    drawer.
Display()
This would draw the text "CapeSoft Draw TrueType Text" in red, Arial 12pt, bold and italic at (10,10) on the image control, after blanking the control to white. Like all Draw properties the font properties are persistent, so all text will be drawn with the same settings until the properties are changed. For example after calling the above code:

    drawer.SetFontColor(color:green)
    drawer.Show(100, 120, '
Rotated text', 90)
    drawer.
Display()


This would draw in the same font face, style and size, but in green and rotated 90 degrees.

The equates to set the style can be any of the standard Clarion font style equates:

Font Weight:
FONT:thin
FONT:regular
FONT:bold


Font Style:
FONT:italic
FONT:underline
FONT:strikeout


As in the example above the font style equates can be combined simply by adding them. Note: the font weights are exclusive. So FONT:thin, FONT:regular and FONT:Bold may not be specified in combination.

The fontName can be set to the name of any of the fonts on the system, such as 'Arial', 'Helvetica', 'Courier', 'Times New Roman' etc.

Information

Character Sets and Complex Script Language Support

The Draw.FontCharSet property can be set to any of the following values as required in order to change the:
  Draw:ANSI_CHARSET
Draw:DEFAULT_CHARSET
Draw:SYMBOL_CHARSET
Draw:SHIFTJIS_CHARSET
(Complex Script)
Draw:HANGEUL_CHARSET
(Complex Script)
Draw:HANGUL_CHARSET
(Complex Script)
Draw:GB2312_CHARSET
(Complex Script)
Draw:CHINESEBIG5_CHARSET
(Complex Script)
Draw:OEM_CHARSET
Draw:JOHAB_CHARSET
(Complex Script)
Draw:HEBREW_CHARSET
(Complex Script)
Draw:ARABIC_CHARSET
(Complex Script)
Draw:GREEK_CHARSET
Draw:TURKISH_CHARSET
Draw:VIETNAMESE_CHARSET
(Complex Script)
Draw:THAI_CHARSET
(Complex Script)
Draw:EASTEUROPE_CHARSET
Draw:RUSSIAN_CHARSET
Draw:MAC_CHARSET
Draw:BALTIC_CHARSET
Draw supports complex script languages such as Arabic and Japanese, where multiple character can combine and form single character and space can be modifed depending on content etc. Draw automatically calls Draw.ShowFull() for complex script languages based on the value of the Draw.FontCharSet property (all those marked above as Complex Script languages). You can also force this behaviour by setting Draw.renderWholeStrings = 1.

Unicode support and automatic Unicode conversion (coming soon!)

Draw also supports unicode strings (in all versions of Clarion) as well as allowing single and multi byte strings to be converted to unicode automatically for you. This feature is a work in progress and will be available in the next release.

Text Reading Direction

You can modify the direction that the text is read in by setting the Draw.textAlignRTL property to 1. This will display the text from right to left. This is useful for languages such as Hebrew which are read from right to left rather than left to right.

Important: When using Complex Script Languages, Unicode strings, Right-To-Left rendering and the Draw.renderWholeStrings property you must pass the Draw.StrLen() and Draw.StrHeight() methods the string that is to be rendered. This is because for these cases the literal characters in the string and the rendered characters may be markedly different.

See Also

StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()

StrHeight

StrHeight (<string textString>), long

Description

Returns the height (in pixels) from the top of an uppercase 'W' to the bottom of a lower case 'p'. This is the total possible height of a string with the current font settings.

Important: When using Complex Script Languages, Unicode strings (Draw.useUnicode), Right-To-Left rendering (set when the charset is Hebrew or Arabic or Draw.textAlignRTL is set to 1) or the Draw.renderWholeStrings property you must pass the Draw.StrHeight() method the string that is to be rendered. This is because for these cases the literal characters in the string and the rendered characters may be markedly different.

Parameters
Parameter Description
 string textStringThe string that you want the height calculated for (optional, see note above).
See Also

StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()

Strlen

Strlen (string text), long

Description

Takes a string and returns the width of the string in pixels using the current font settings, it also buffers the characters for future use.

Parameter
Parameter Description
string textThe string that you want the width calculated for.
See Also

StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()

Sphere

Sphere (long x, long y, long width, long height, long outerColor, long innerColor, real xOffset=0, real yOffset=0)

Description

Draws an ellipse shaded from an inner point to the outer edges of the ellipse, creating a spherical effect. The position of the "highlight" can be specified either horizontally or vertically.

Parameters
Parameter Description
long xx coordinate of the top left hand corner of the ellipse's bounding box
long yy coordinate of the top left hand corner of the ellipse's bounding box
long widthThe height of the ellipse, in pixels
long heightThe width of the ellipse, in pixels
long outerColorThe color at the outer edge of the ellipse
long endColorthe color at the highlight point
real yOffsetThe vertical offset from center to draw the highlight at. 0 is the top, 0.5 is the center and 1.0 is the bottom.
real xOffsetthe horizontal offset from the center to draw the highlight at. 0 is the far left, 0.5 is the center and 1.0 is the far right.
Example
Example
drawer.Blank(color:white)
drawer.SetPenColor(color:none)
drawer.Sphere(10, 10, 120, 200, color:red, color:white, 0.5, 1)
drawer.Sphere(130, 10, 120, 120, color:red, color:yellow, 0, 0)

drawer.Display()

spheres screenshot
See Also

Ellipse, ShadeEllipse

RadLine

RadLine (long x, long y, long angle, long length, long startPos=0, long endPos=100, long startColor=-1, long endColor = -1)

Description

Draws a line, where the parameters passed as used to draw the radially - from a start point the line is draw at an angle to the length specified. The startPos and endPos parameters are reserved for future use.

Parameters
Parameter Description
long xx coordinate of the start point of the line
long yy coordinate of the start point of the line
long angleThe angle to draw the line at, in degrees, with zero at 3 O'Clock
long lengthThe length of the line, in pixels
long startPosReserved for future use
long endPosReserved for future use
long startColorThe color at the start of the line at if a shaded line is being drawn
long endColorThe color at the end of the line if a shaded line is being drawn.
Example
Example
curAngle			long

CODE

	drawer.Blank(color:white)
	drawer.SetPenColor(color:red)
	drawer.SetPenWidth(1)
loop curAngle = 0 to 360 by 10
   	drawer.radLine(150,150, curAngle, 120, , , color:red, color:yellow)
end
	drawer.Display()

shaded radline screenshot
See Also

Line, ShadeLine

SetDisplayArea

SetDisplayArea (long x, long x, long w, long h)

Description

The SetDisplayArea method is used to limit displaying to a rectangular region when calling Display, which is used to improve performance when a small area has been changed and the entire control (canvas) doesn't need to be redrawn. This can dramatically improve display performance, particularly with large canvases, many layer, or when calling Display frequently such as when creating animations. Call ResetDisplayArea to reset to drawing the entire canvas.

Note that SetDisplayArea applies to all layers - when displaying just that section of each layer is composited into the final image.

Parameters
Parameter Description
xThe x coordinate of the rectangular region that display is limited to.
yThe y coordinate of the rectangular region that display is limited to.
wThe width of the rectangular region that display is limited to.
hThe height of the rectangular region that display is limited to.
Return Value

None

StringToFile

StringToFile (string source, string fileName, long newFile=0, long clipData=0), long, proc

Description

Write the contents of a string to disk. The data passed in the source string is written to a file with the name specified by the fileName parameter. The remaining two parameters modify the behavior of the function. If newFile is non zero a new file is always created (if the file already exists it is replaced), the default is for newFile to be zero, in which case if the file already exists it is appended to. If the clipData parameter is non zero then the data is clipped before being written to file (any trailing spaces are not written to disk). This is useful for a string that contains text, but should not be used for binary data such as images. If an error occurs the method calls draw.ErrorTrap() with details of the error that occurred. The function handles strings up to 2GB in size, strings larger than 2GB will be truncated (only the first 2GB will be written to disk).

Return Values

The method returns zero for failure and non zero for success. Checking of the return value is optional, as any errors are handled by ErrorTrap().

Example
Example
binaryString			string(4096)
textString				string(1024)

  CODE
    ! assume that binaryString has been filled with 4K of binary data...
    ! write to a file, always create a new file, and write the entire string to disk with no clipping
drawer.StringToFile(binaryString, 'myData.bin', 1, 0)

    textString = '<<html><13,10><<head><13,10>' |
& '<<title>Test HTML Page<</title><13,10>' |
& '<</head><13,10><<body><13,10>' |
& '<<h1>This is an HTML page<</h1><13,10>' |
& '<</body><13,10><</html>'

! write some plain text to an html file, always create a new file, and write the clipped data to disk (no trailing spaces)
drawer.StringToFile(textString, 'test.html', 1, 1)
See Also

FileToString - Read the contents of a file into a string in memory.

Notes

WinEvent provides improved version of these functions, see ds_File2String and ds_String2File in the WinEvent docs

SwapBuffers

SwapBuffers (string* buffer)

Description

Writes the buffer pointed to the the string* into the image control. Note that the buffer must be a standard windows BMP.

ToClipboard

ToClipboard ()

Description

Copies the current contents of the Draw control to the Clipboard as a standard Windows bitmap. The image can then be pasted into an image manipulation program such as Photoshop or Paintshop Pro, or even MS Paint. It can also be pasted into any other program that support bitmaps, such as Word and Excel.

Parameters

None

Return Value

None

WriteBMP

WriteBMP (string path)

Description

Write the buffer to a bitmap file. Simply pass the destination filename and path. Image is written as a 24 Bit Windows Bitmap. The WritePNG() method allows the current image control contents to be written to a PNG rather than a BMP.

Examples
Example
Drawer.WriteBMP('c:\my documents\my pictures\test.bmp')
! Or you can pass just the filename, and the path is assumed to be the current directory:
Drawer.WriteBMP('test.bmp'

WriteLayerBMP

WriteLayerBMP (string path)

Description

Write the current layer to a bitmap file. Simply pass the destination filename and path. Image is written as a 24 Bit Windows Bitmap. See the WriteBMP() method for writing the current display buffer to a file.

Examples
Example
drawer.WithLayer(2)       ! select the second layer
drawer.WriteLayerBMP(
'c:\my documents\my pictures\layer2.bmp')
! Or you can pass just the filename, and current directory will be used as the path (See SetPath() in the Clarion docs)
drawer.WritelayerBMP('layer2.bmp'

WriteLayerPNG

WriteLayerPNG (string path)

Description

Write the current layer to a PNG file. Simply pass the destination file name and path. This method is identical to the WritePNG() method, except that it only writes the currently selected layer to a PNG. See WritePNG() for more information on PNG files.

Examples
Example
drawer.WithLayer(2)       ! select the second layer
drawer.WriteLayerPNG('c:\my documents\my pictures\layer2.png'/span)
! Or you can pass just the filename, and the
path is assumed to be the current directory:
drawer.WriteLayerPNG('layer2.png'/span) 

WritePNG

WritePNG (string path)

Description

Identical to the WriteBMP method, except that it writes to a PNG file. A PNG (Portable Network Graphic, pronounced "ping") file is a losslessly compressed image format.

3D Draw Data Types

Point2D
A point in 2D space (a point on a flat plane), each point has an x, y
Components:
x         real
y         real

Point3D
A point in 3D space, each point has an x, y and z coordinate.
Components:
x         real
y         real
z         real

Example
Example
p1         like(Point3D)

    p1.x = 1.25
    p1.y = 2.117
    p1.z = 0        ! Use a zero z coord for 2D



Vector3D
A 3D vector, defined by an x, y and z component. Vectors are unchanged by translation, so it is often convenient to consider each vector to start at the origin and end at the point defined by its components.
vector 3D screenshot

Components:
x         real
y         real
z         real

The vector components can be assigned in the same way as those of a point, all the Draw methods that accept vectors as arguments will accept points. If you pass a point to a method that takes a vector, the point will be treated as a vector.

Line3D

A line3D is the line between two point (p0 and p1) in 3D space. You can specify two dimensional lines simply by setting the z component of each point to zero.

Components:
p0         like(Point3D)
p1         like(Point3D)

Example
Example
line1            like(Line3D)
    line1.p0.x = 1.5        ! a line3D is defined as two points: P0 and P1, each of which have and x, y and z coordinate
    line1.p0.y = 2.5
    line1.p0.z = 0
    line1.p1.x = 5.0
    line1.p1.y = 12.25
    line1.p1.z = 0

3D Methods

Draw.Add3DAdd two points or vectors
Draw.CrossProdCalculate the cross product of two vectors (or points)
Draw.DotCalculate the dot product of two vectors
Draw.DistanceCalculate the distance from a line to a point
Draw.Equal3DDetermine equality of two vectors or points
Draw.LinesIntersectDetermine if two lines intersect, and if so the point of intersection
Draw.PerpCalculate the length of the perpendicular
Draw.PointOnLineDetermine if a point is on a line, and if so where.
Draw.ScalarProdCalculate the scalar product of a point or vector multiplied by a real number
Draw.Sub3DSubtract two points or vectors

Add3D

Add3D (vector v1, vector v2, *vector r)

Description

Adds vector v1 and v2 and places the result in the vector r, you can call this method with both points and vectors. Also see Sub3D().

Example
Example
v1         like(vector)
v2         like(vector)
v3         like(vector)

     Drawer.Add3D(v1, v2, v3)               ! v3 = v1 + v2

CrossProd

CrossProd (vector v1, vector v2, *vector r)

Description

Calculates the cross product of two vectors. The resultant vector is perpendicular to the two original vectors and is oriented according to the right hand rule.

CrossProd screenshot

Given a pair of vectors U and V, the cross product is defined as:

U x V equals cross product
             cross product two

Dot

Dot (vector v1, vector v2), long

Description

Returns the dot product of two vectors. The dot product can be defined as the length of the projection of X onto the unit vector (a vector with a length of one) of Y.

dot product of two vectors screenshotThe dot product of X and Y is show in red. y unit screenshotis the unit vector of Y.

The dot product is given by dot screenshot where theta screenshot is the angle between the vectors. If the dot product is zero, the vectors are perpendicular. Which is a lot less complicated than it sounds, as the dot product of two vectors is simply the sum of the products of the components. For instance, given a pair of vectors A and B:

A dot B screenshot dot simple screenshot

Which in Clarion code would be written as:

Dot(vector1, vector2) = (vector1.x * vector2.x) + (vector1.y *vector2.y)

The Dot product behaves very similarly to multiplication with real numbers:

It is commutative:        dot cummutative screenshot         where X and Y are vectors
It is associative:          dot associative screenshot        where X and Y are vectors and r is a real number
It is distributive:           dot distributive screenshot        where X, Y and Z are vectors

Distance

Distance (point p, line3D line), long

Description

Returns the distance from a point to a line. The distance returned is the shortest possible distance between a line and a point.

Example
Example
line1            like(line3D)
point1           like(point)
dist             long

    line1.p0.x = 1.5        ! a line3D is defined as two point: P0 and P1, each of which have and x, y and z coordinate
    line1.p0.y = 2.5
    line1.p0.z = 0
    line1.p1.x = 5.0
    line1.p1.y = 12.25
    line1.p1.z = 0

    point1.x = 0            ! check the distance from the origin to the line we have specified
    point1.y = 0
    point1.z = 0

    dist = Distance(point1, line1)

Equal3D

Equal3D (vector v1, vector v2), long

Description

If the two vectors or points passed are equal the method returns 1, otherwise it returns 0.

LinesIntersect

LinesIntersect (line3D line1, line3D line2, *point i0, *point i1), long

Description

Determine if two lines intersect. If the lines are completely disjoint (no intersection) the method returns zero, if they intersect it returns 1 and if they overlap it returns 2. If they intersect the point at which they intersect is stored in i0. If they overlap the start and end points of the overlapping segment are stored in i0 and i1 respectively.

Perp

Perp (vector v1, vector v2), long

Description

Perp() returns the length of the perpendicular to two vectors in 2D (the z component is ignored).

PointOnLine

PointOnLine (point p, line line1), long

Description

Returns 1 if the point lies one the line, and zero otherwise.

ScalarProd

ScalarProd (real s, vector v, *vector r)

Description

The vector r is set to the product if the vector v and the scalar (real number) s. Essentially r = v*s. Each component of the vector v is multiplied by the real number s.

Sub3D

Sub3D (vector v1, vector v2, *vector r)

Description

Subtracts v2 from v1 ans stores the result in r. Essentially r = v1 - v2. Usage is identical to Add3D.

Internal Methods

These are some of internal methods of the Draw class, they have been included for completeness, and are not meant to be called under normal circumstances. You can modify any of these methods to change the functionality of the Draw class without effecting the external interface to the class methods. It is strongly advised that you fully understand what the method is doing before modifying it, and that you back up your Draw files before modifying them.

ReadBMP (string filename)
Reads in a bitmap in any format, currently not used, but provided for convenience and later expansion.

_Plot (long x, long y, long flag)
This is an internal draw method.

_Absolute (long i, long j, *long k)
This is an internal draw method. It is not the same as the Clarion Abs() function.

_Swap (*long a, *long b)
This is an internal draw method.

EllipsePlotPoints (long xCenter, long yCenter, long x, long y)
This is an internal draw method.

_SingleShadeBox (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long XP = -1, long yp=-1, byte intensity=-1)
Normally you should call ShadeBox, which will handle which type of box to draw for you, however you can call _singleShadeBox directly

_DoubleShadeBox (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long XP = -1, long yp=-1, byte intensity=-1)
Normally you should call ShadeBox, which will handle which type of box to draw for you, however you can call _doubleShadeBox directly

_SingleShadeCylinder (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long XP = -1, long yp=-1, long depth, byte intensity = -1, long eCol=-1)
Normally you should call Cylinder, which handles which type of cylinder to draw for you, however you can call _SingleShadeCylinder directly

_DoubleShadeCylinder (long x, long y, long width, long height, long lcol=-1, long rcol=-1, long tcol=-1, long bcol=-1, long XP = -1, long yp=-1, long depth, byte intensity = -1, long eCol=-1)
Normally you should call Cylinder, which handles which type of cylinder to draw for you, however you can call _SingleShadeBox directly

BigEndian()
Convert a long from little endian to big endian (previously used for encoding PNGs).

Class Property Reference

These are some of the properties of the Draw class that you might find useful to set directly.

antiAlias
Enables or disabled anti-aliased drawing of basic primitives. Set to True (1) to enable anti-aliasing, and False (0) to disable it.

When objects are drawn on the screen they are drawn using pixels, which are square. This means that objects drawn are approximations, and can result in "jagged" or "stepped" edges. Anti-aliasing provides smoothing by blending the edge pixels slightly with the background that the object is being drawn onto.

The image below demonstrates the effects of anti-aliasing on objects and text (the right hand side is anti-aliased, the left is not).


Note that anti-aliasing will improve the visual quality, however there is a speed impact, as it takes significantly more processing to render anti-aliased objects.
bitmapFileData&stringA handle to the Bitmap buffer of the current layer. You can change the buffer directly to implement per pixel, or even per channel effects. The buffer is stored as a Bitmap, with three bytes per pixel (BGR), a 54 byte header and each scanline is zero padded so that it ends on a word boundary.
colors256longFlag to enable or disable 256 colour drawing once Init256() has been called. See the Init256() documentation for drawing in 256 colours and how to use the colors256 flag.
fontColorlong We advise that you do not set this property directly, call the .SetFontColor() method.
The font color. You can set the font color by calling SetFontColor(). If you do set this manually make sure you set the .fontred, .fontgreen, .fontblue properties. See the SetFontColor or SetPenColor methods for how to get the relevant bytes.

Draw.fontRed                     byte
Draw.fontGreen                   byte
Draw.fontBlue                    byte
TThe individual font colour components
fontName

A string for the name of the font drawn by the Show() method.

Examples
           drawer.fontName = 'Arial'
         drawer.fontName = 'Times New Roman'

See the Show() method for more details.
fontCharset

The character set used for rendering the fonts. The Draw.FontCharSet property can be set to any of the following values as required in order to change the:

Draw:ANSI_CHARSET
Draw:DEFAULT_CHARSET
Draw:SYMBOL_CHARSET
Draw:SHIFTJIS_CHARSET (Complex Script)
Draw:HANGEUL_CHARSET (Complex Script)
Draw:HANGUL_CHARSET  (Complex Script)
Draw:GB2312_CHARSET  (Complex Script)
Draw:CHINESEBIG5_CHARSET (Complex Script)
Draw:OEM_CHARSET
Draw:JOHAB_CHARSET  (Complex Script)
Draw:HEBREW_CHARSET  (Complex Script)
Draw:ARABIC_CHARSET (Complex Script)
Draw:GREEK_CHARSET
Draw:TURKISH_CHARSET 
Draw:VIETNAMESE_CHARSET  (Complex Script)
Draw:THAI_CHARSET  (Complex Script)
Draw:EASTEUROPE_CHARSET
Draw:RUSSIAN_CHARSET
Draw:MAC_CHARSET
Draw:BALTIC_CHARSET

See Also
StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()
fontStyle

A combination of the font weight and style equates.

Example
Drawer.fontStyle = FONT:Bold + FONT:Italic + FONT:Underline.
See the a href="#Show">Show() method for more details.

See Also
StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()
fontSize

The point size of the font used by the Show() method.

Example

    drawer.fontSize = 12            ! draw 12 point text/span>

See Also
StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()
fontZoom

Setting the fontZoom factor allows you to adjust for increased resolution. This is particularly useful on reports with high resolution Draw controls. See the section on Drawing on Reports for more details on using the fontZoom property. The default value for fontZoom is 1, increasing fontZoom will increase the size that fonts are drawn at any particular point size. This allows you to use a 12 point font on a high resolution report, simply by increasing the fontZoom factor to adjust for the resolution.
height
longThe height of the current layer, in pixels. The height of the actual Draw image is Draw.baseLayer.height.
penColorlongSetting this property directly is not recommended, use the .SetPenColor() method.

The pen color. You can set the pen color by calling the SetPenColor() method. If you set this manually make sure you set penred, pengreen and penblue properties. See the SetPenColor() method for how to get the relevant bytes.

penRed                           string(1)
penGreen                         string(1)
penBlue                          string(1)
Individual pen colour components.
penStyle                       longThe pen style, uses the same equates as Clarion pen styles.
penWidth                       longThe pen width in pixels.
suppressErrors                 byte(1) Whether the ErrorTrap() method displays a message, default suppressErrors is 1, and no messages are displayed. 

Example
Drawer.suppressErrors = 1        ! suppress all error messages
Drawer.suppressErrors = 0        ! display all error messages
textAlignRTL
Sets the text to display in Right-To-Left reading order for languages such as Hebrew. See the Show() method.

Example

drawer.textAlignRTL = true            ! Use RTL text order.

See Also

StrLen(), Show(), fontSize, fontName, SetFontColor(), fontCharset, fontStyle, SetFontMode(), SetFontColor()
width                          longThe width of the current layer in pixels. The width of the Draw image is Draw.baseLayer.width.