Class Reference - Methods and Properties
		Version

• Main
• DrawPaint
  • Sub 1
  • Sub 2
    • Sub Sub
• DrawImage
• How To Guides
• Examples
• FAQ
• History

Contents
	Basic Methods Draw Class Methods Layer Methods 3D Data Types 3D Methods Utility and Internal Methods Draw Class Properties DrawHeader Class Methods and Properties   "How To" Guides Using the Multiple Monitor and system functions This guide shows you how to get the dimensions of the current monitor and total screen size, as well as many other useful system metrics

All the Clarion built in drawing functions have equivalent methods of the Draw class, 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 Draw 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 Draw methods that are the equivalent of the built in Clarion graphics functions, and operate in the same manner.

As well as providing the same functionality as the Clarion graphics functions, the Draw 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 Draw methods for handling layers.

Draw also has a number of internal methods that are provided for advanced users who would like to customise or modify the Draw class. See the Internal Class Methods section.

Draw provides a number of methods to manage the use of Layers. Draw provides the ability to use an unlimited number of independant 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 Draw initialises 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.

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.

 
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.

Click on the (up) icon to go back to the Class Method Index.

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

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 (see diagram below)

Examples

    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:

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

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:
1. Barcodes should be large enough to scan quickly and accurately.
2. It allows the resolution to be increased for printing. Printing typically uses a resolution that is at least four times higher than screen resolution.

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

Return values

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

Examples

    ! 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 (ulong color)
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

Examples

Blank can be passed any integer constant or variable to specify the color to clear to.

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

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

Blur (long blurDist, long bType=0) BETA
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

Examples

    ! 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):

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):

Box (long x, long y, long width, long height, long fillColor)
This is identical to the Clarion function. Draws a filled or line box.

Parameters

Examples

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:

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

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 (long clarionColor), long

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

Return Values

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

ColorRange (long startColor, long EndColor, long distance, long p1, long p2, *long color1, *long color2)
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.

I

Return Values

Information

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

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 ()
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 (*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 (C¹, C² and G¹ continuity using Hermite curves and interpolation for the blending functions for those who care!).

Parameters:

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

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

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).

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 independant 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 compatiblility only.

Parameters

The first eleven parameters are identical to the ShadeBox method:

However there are also two additional parameters:

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 (two color)	Double Shaded Cylinder

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.

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()

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()

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()

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()

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()

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()

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 (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)

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

Examples

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()

Examples

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 (long x, long y, long width, long height, long fillColor)
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

Examples

    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()

Information

See also: Blank, Display, SetPenColor and ShadeEllipse

EnumFonts ()
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:

Examples

    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 (string errorStr, string functionName) 
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

FormatMessage (long errorCode), string
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

Return Value

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

Example

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

FileToString (*string fileData, string fileName), long
Loads the entire contents of a file into a string. If the string passed is not large enough the required size is returned.

Parameters

Return Values

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 ()
Sets a number of properties that describe the current windows and device display settings. Takes no parameters.

Example

    myDrawer.GetDeviceCaps()
Message('The current screen dimensions are: ' & myDrawer.hScreenSize & ' x ' & myDrawer.vScreenSize & ' pixels.')

  

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

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

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.

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

See Also

LoadIcon

GetDisplay()
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

    ! 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(long x, long y), long
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

    ! 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(long x, long y), long
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(long x, long y), long
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()
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 (long x, long y, long width, long height, long xdest, long ydest) 
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(long x, long y, long width, long height, long innerColor=-1, long outerColor=-1, long orientation=1)
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

See Also

Ellipse, ShadeEllipse, LinearEllipse, Sphere

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

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

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()

Highlight (long x, long y, long width, long height, long hColor) 
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(long x, long y, long width=-1, long height=-1, string filename, long flag=-1, long colorMask=-1),long,proc
Place an image from a file onto the current layer.

Parameters

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

ImageDimensions (*long width, *long height, string filename)
Sets the width and height parameters to the width and height of the image specified by filename. The file must be a bitmap.

Parameters

Example

iWidth            long
iHeight           long

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

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

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

Return Values

The method returns 1 for success and zero for failure.

Init (ulong control)
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

Example

Init256 ( )
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

Example

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

Information

Kill ( )
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 ( )
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 (long x, long y, long width, long height)
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.

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. WinEvent 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 the new WindowsXP 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 WindowsXP 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

Examples

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 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).

Log (string messageStr)
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 dependant 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

Examples

    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)

See Also

Debugging and Logging

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)
Double shaded cylinder functionality as provided by the Cylinder( ) method, with an alternative shading algorithm.

Metallic Shaded Cylinders

MouseX()
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()
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(long x, long y, long width, long height, PieSliceType pSlice)     (BETA)
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.

Parameters

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.

Examples

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 (*long[] vertices, long fill=-1, long numVertices)
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.

    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 (*long[] vertices, long numVertices, long x, long y), long
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.

    !---- 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 (long x, long y)
Put a pixel of the current pen color (see SetPenColor) at the coordinates given by x and y.

Resize(long width=-1, long height=-1)
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

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)

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

RgbToHsv (long rgbColor, *hsvColorType HSV)
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.

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

hsvColor       group(hsvColorType)
              end

Drawer.RgbToHsv(color:red, hsvColor)

aaRoundRect Procedure (long x, long y, long width, long height, long eWidth, long eHeight, long lineColor=color:none)

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. This method does not support filling the shape.

Parameters

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 curernt pen color is used.

• PEN:solid
• PEN:dash
• PEN:dot
• PEN:dashdot
• PEN:dashdotdot

SetPenWidth(long width)
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 (ulong color)
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

Examples

            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 (String Pattern)
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.

Parameters

Examples

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.

Parameters

Parameters

Examples

    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

Parameters

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	2) Single Shaded Boxes	3) Double Shaded Boxes

Examples

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)

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)

Parameters

Example

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

    

See Also

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

Parameters

Parameters

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()

See Also

ShadeLine, ShadeEllipse, ShadeBox, Sphere, Polygon

Show (long x, long y, string text, long rotation=0)
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 initally 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

    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(<string textString>), long
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

See Also

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

Strlen(string text), long
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.

See Also

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

Parameters

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() 

See Also

Ellipse, ShadeEllipse

Parameters

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()

See Also

Line, ShadeLine

StringToFile(string source, string fileName, long newFile=0, long clipData=0), long, proc
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:

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

Notes

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

ToClipboard ()
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.

None.

Return Value

None.

WritePNG (string path)
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. PNGs are supported by a wide variety of applications, including Internet Explorer and Netscape Navigator (Versions 4 and above of both applications).

Why PNG and not JPG or GIF? 
PNG files are losslessly compressed, unlike JPEGs which are lossy. JPEGs tend to corrupt edges quite badly, which means they are not very suitable for images with text, or fine detail. 
GIF images are not supported as the format uses compression algorithms which are patented by Unisys (in particular LZW compression), which means a licensing fee would need to be paid by CapeSoft for using the GIF format, as well as by you as a programmer implementing GIF support in your application, in addition a fee for each copy of the software sold would be charged. The initial license fee is around $2500.

While GIF only supports 8 bit colour (256 colours), PNGs support up to 48 bit colour, plus alpha channels and many other features. Draw writes a standard 24 bit PNG (which is compressed using zlib compression). If you are interested in what PNGs are capable of have a look at Macromedia Fireworks, which uses PNGs as it's native format to store a large variety of data (including layers, vector and bitmap data, true type text and layer effects), while still allowing the image to be viewed by any PNG decoder (such as Internet Explorer).

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
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.


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.

Example

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

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:

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

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

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

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.

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

Dot (vector v1, vector v2), long

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.

The dot product of X and Y is show in red. is the unit vector of Y.

The dot product is given by where 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:



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:                 where X and Y are vectors
It is associative:                  where X and Y are vectors and r is a real number
It is distributive:                   where X, Y and Z are vectors

Distance (point p, line3D line), long

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

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 (vector v1, vector v2), long

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

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

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 (vector v1, vector v2), long

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

PointOnLine (point p, line line1), long

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

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

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 (vector v1, vector v2, *vector r)

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 aproximations, 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                 &string

A 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.

colors256                      long

Flag 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.

fontColor                      long

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
The 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 Show() method for more details.

See Also

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

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                         long
The height of the current layer, in pixels. The height of the actual Draw image is Draw.baseLayer.height.

penColor                       long

Setting 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                       long
The pen style, uses the same equates as Clarion pen styles.

penWidth                       long

The 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

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

width                          long
The width of the current layer in pixels. The width of the Draw image is Draw.baseLayer.width.