Class Reference - Methods and Properties

Capesoft Draw
Return to the main Draw documentation

 Version
     

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
     

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.

Basic Methods
Draw.Arc Draw an arc of an ellipse
Draw.Blank Clear the entire drawing area
Draw.Box Draw a box (filled and line only)
Draw.Chord Draw a chord (a closed arc)
Draw.Ellipse Draw an Ellipse
Draw.Line Draw a Line
Draw.Polygon Draw a Polygon
Draw.Show Write text to the drawing area

     


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 Class Methods
Draw.Arc  Draws an arc
Draw.Barcode Draws a PDF417 compatible 2D barcode.
Draw.BestFit Calculates the best proportional scaling when passed dimensions.
Draw.Blank  Clears the drawing area
Draw.Blur Blurs a layer, supports blurring horizontally, vertically, or a standard blur.
Draw.Box Draws a rectangle
Draw.Chord Draws a chord (and arc with the ends connected by a straight line)
Draw.ClarionToRGB Converts a Clarion color to a standard RGB color .
Draw.ColorRange Used to calculate the colors at two points anywhere on a color gradient
Draw.Create256
 Create a 256 colour bitmap from the 24 bit version.
Draw.Curve Draws a smooth curve through the points passed.
Draw.Cylinder
 Draws a variety of cylinders, with multiple shading options
Draw.Display Displays the draw control. Display() needs to be called every time control needs to be updated
Draw.Ellipse Draws an ellipse
Draw.EnumFonts Populates a queue for all available fonts on the system.
Draw.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.
Draw.FileToString Reads the content of a file into a string, also see StringToFile
Draw.FormatMessage Returns the error message for a passed Window API error code.
Draw.GetDeviceCaps Gets information about the current device capabilities (screen size, resolution etc.)
Draw.GetDevicePixel Returns the color of a pixel anywhere on the screen
Draw.GetDisplay Loads the current image control contents into the Draw buffer, useful for getting an image that Clarion has loaded into the control.
Draw.GetIconHandle Gets a handle to an icon on disk or in a resource for passing to LoadIcon
Draw.GetImagePixel Returns a pixel on the Draw control, faster than GetDevicePixel, and the coordinates are relative to the origin of the Draw control.
Draw.GetPixel Identical to GetImagePixel, simply provides an alternative name.
Draw.GetWindowsColors Populates the Draw Windows colors variable with the current interface colors stored by Windows.
Draw.GrabScreen Grabs the specified area of the screen and loads it into the Draw control
Draw.HalfEllipse Draws half of an ellipse
Draw.Highlight Turns a highlight on and off over the area specified. Gives a "selected" effect.
Draw.HsvToRgb Converts an HSV color to a standard Clarion RGB color
Draw.Image Displays and image from a file
Draw.ImageDimensions Returns the pixel dimensions of a bitmap image file.
Draw.imageFromBuffer Writes from a buffer that contains RGB data to a layer as an image.
Draw.Init Initialises the Draw control, called automatically
Draw.Init256 Initialises 256 colour drawing capabilities
Draw.Kill
 Destroys the Draw control, called automatically
Draw.Kill256
 Halts 256 colour drawing and cleans up
Draw.Line Draws a line
Draw.LoadIcon Places an image from an icon file onto the Draw control
Draw.Log Log to the OS debug output (see Debugging and Logging)
Draw.MetallicCylinder Draws a double shaded cylinder with a metallic look
Draw.MouseX Return the current x position of the mouse relative to the Draw control
Draw.MouseY Return the current y position of the mouse relative to the Draw control
Draw.PieSlice Draws a shaded slice of a pie (a segment of a pie chart).
Draw.PointInPolygon Returns whether an x and y coordinate are within a polygon.
Draw.PointInPieSlice Whether a coordinate is within a specific pie slice (ellipse segment)
Draw.Polygon Draw a polygon
Draw.Putpixel Puts a pixel on the Draw control
Draw.RadLine Draws a line radially (from a point to a length along an angle)
Draw.Resize Changes the size of the Draw buffer
Draw.ResizeControl Changes the size of the Clarion control Draw uses
Draw.RgbToHsv Convert and RGB color to an HSV color
Draw.SetFontColor Sets the current Draw font color
Draw.SetFill Sets the current fill type to patterned instead of solid
Draw.SetPenColor Sets the current Draw pen color
Draw.SetPenstyle
 Sets the current Draw pen style
Draw.ShadeBox Draws a rectangular box with multiple shading options
Draw.ShadeEllipse Draw an ellipse shaded from one color to another.
Draw.ShadeLine
 Draws a line shaded from one color to another
Draw.ShadePolygon Draw a polygon horizontally shaded from one color to another.
Draw.StrHeight Returns the height of the current font
Draw.StrLen Returns the length of a string in pixels
Draw.Sphere Draws a sphere shaded between two colors (the "sphere" can be elliptical).
Draw.SetPenWidth Sets the current Draw pen width
Draw.SetFill Sets the current fill style, allows patterned fill to be used
Draw.SetFontColor Set the current font color
Draw.SetFontMode Set the font render mode (anti-aliased etc.)
Draw.Show Write text to the drawing area
Draw.StringToFile Writes a string to a file, see FileToString
Draw.SwapBuffers Writes the buffer passed into the image control
Draw.ToClipboard Copies the current Draw control contents to the clipboard
Draw.WriteBMP Writes the Draw control to a bitmap image file
Draw.WriteLayerBMP Writes the current layer to a Windows Bitmap file.
Draw.WriteLayerPNG Writes the current layer to a PNG file.
Draw.WritePNG Writes the Draw control to a PNG image file
     

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.

LayerMethods
  Draw.Addalpha
Add an alpha channel to a layer
  
Draw.AlphaCopy
Handles alpha blending for CopyLayer. Do not call directly.
Draw.CopyLayer
Copy a block of pixels from one layer to another (handles transparency).
Draw.IndexTransparency
Set the index transparency of the layer.
Draw.HasAlpha Returns whether a layer has an alpha channel
Draw.HideLayer
Set a layer to hidden.
Draw.InitLayer
Initialise a new layer
Draw.KillLayer Delete a layer.
Draw.LayerMode
Return whether a layer has a display mode enabled or disabled.
Draw.MoveLayer
Change a layer's display order.
Draw.NumLayers
Return the number of initialised layers.
Draw.ResizeLayer
Resize a specific layer.
Draw.SetMode
Set the display mode.
Draw.Showlayer
Set a layer to be shown when Display() is called.
Draw.SwapLayers
Swap two slayer's display order.
Draw.ToAlpha
Copy one RGB channel from one layer to another.
Draw.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
  Draw.Add3D
Add two points or vectors
  
Draw.CrossProd
Calculate the cross product of two vectors (or points).
Draw.Dot
Calculate the dot product of two vectors
Draw.Distance
Calculate the distance from a line to a point
Draw.Equal3D
Determine equality of two vectors or points
Draw.LinesIntersect
Determine if two lines intersect, and if so the point of intersection
Draw.Perp
Calculate the length of the perpendicular
Draw.PointOnLine
Determine if a point is on a line, and if so where.
Draw.ScalarProd
Calculate the scalar product of a point or vector multiplied by a real number
Draw.Sub3D
Subtract two points or vectors
     

 

Utility and Internal Methods
  Draw.BigEndian
Converts a long to Big Endian bit order
  
Draw.GetLastError Returns the error code for the last API function called. Not a member of the Draw calss, so it can be called without a Draw object.
 
     

 

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

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.

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 PDF 417 compatible 2D barcode using the data passed. The method can draw a barcode one the Draw control, as well as automatically resizing the Draw control to the size of the barcode. In addition the of the barcode can be increased by using the sizeFactor parameter. 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 the the barcode is drawn over whatever is within the Draw control (the sections of the barcode that are no the pen color are transparent). If the forceRes parameter is non zero then the barcode is drawn in the current pen color with a white background and the Draw buffer is resized to the size of the resultant barcode.

Parameters

Parameter Description
string barcodeText The text to turn into a barcode.
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 a non zero value then the Draw buffer is resize to the size of the barcode. This is useful for creating controls filled by a barcodes, which take up the entire Draw 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 trailing spaces).

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


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.

Parameters:

ulong color The color to blank to, this is optional as the default color is black

Examples:

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

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

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: 

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

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.

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:

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

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

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:

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

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:

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:

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

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:

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

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

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:

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.
   


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:

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

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:

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:

    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:

 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:

    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:

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

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.

 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:

    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.

Return Values

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:

 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, 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
  Parameter   Description
*hsvColorType HSV An HSVColor group that will be converted to RGB.

 

  Return Values 
  None

 

  Example   
 
 
hsvColor       group(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()

 

See Also

RgbToHsv, ClarionToRgb

 

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:

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

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 initialised 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 (*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:

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

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:

 Property
  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 (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:

ulong control Handle to the image control to draw to.

Example: 

            Drawer.Init(?Drawer)

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