Documentation
Download Latest Version Index JumpStart FAQ History Classes Draw Gauge Draw Paint Draw QR
CapeSoft Logo

CapeSoft Draw
Documentation

Installed Version Latest Version

Introduction

The CapeSoft Draw control allows you to draw directly to an image control. Not only is this fast, but has the added advantage that if the control is refreshed, it simply redraws the image, rather than re-calling each of drawing commands. And it allows: Draw now supports multiple drawing surfaces, otherwise known as layers. Some of the features include: And best of all the upgrade to Draw 2 from previous versions is free!

What's New

This section briefly describes what's new in the current release, and important information when upgrading from older versions.

Draw 4.22

The DRAW class has been renamed to DrawClass. This is to resolve a compatibility issue originating in Clarion 11.0.13622
Users on this build of Clarion (or later) will need to be on Draw 4.22 or later. This will also trigger the following other accessory updates; Although iDash uses Draw, it uses a derived class, not the DRAW class, so does not need to be updated.
NetTalk 9 and earlier did not use Draw, so are not affected.

Draw 4.00

Added the DrawGauge class and template support for gauges.

Draw 2.64

Updated DrawHeader template and added a new DrawHeader Class.

The DrawHeader no longer uses the local procedure, and the Utility templates are no longer needed. The new options on the Global extension allow the old template to be used (tick the Use Old Drawheader template option), and also allows all settings for the DrawHeader object to be overridden at the template level. The local extension provides the same settings, and allows the global settings to be overridden where needed.

DrawHeader control can use the new or old template code as needed, simply tick the box for control that should use the old DrawHeader template code, and use the Global extension to specify whether the old of new template should be the default.

Draw 2.55

Updated DrawHeader template
For projects using the DrawHeader template run the DrawHeadingABC or DrawHeadingLegacy utility template to import the update DrawMakeHeading function into your application. This release adds resizing support and the ability to redraw the control without recreating the icon.

Draw 2.30

Major new features include handling of Complex Script languages such as Arabic and Hebrew (see the new Show() method documentation for more) as well as Right-To-Left text ordering etc., support for curve drawing. See the History section for more.

Draw 2.13

Draw and Progress Compatibility
Draw 2.13 and Progress 1.14 both have template changes that make them incompatible with the previous versions of the products, so please ensure that you upgrade both products to Draw 2.13 and Progress 1.14 or later!

Draw 2.07

Important: Because the equates that draw uses now all begin with 'Draw:', compiling programs that use version prior to 2.07 may produce errors, in order to fix these errors simply add the text 'Draw:' to each equate used in your source code. This mainly affects the internal drawing methods, as a number of the API equates now have Draw: prepended to the label (e.g. LOGPIXELSX becomes Draw:LOGPIXELSX). Most of the Draw equates already use the Draw: naming scheme. Only a very small number of equates have been changed, so it is unlikely that you will comes across this error.

See the History section for a full list and for features added in previous releases.

Support

Your questions, comments and suggestions are welcome. See our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways:
CapeSoft Support
Email
Telephone +27 87 828 0123

Installation

Run the supplied installation file.

Distribution

If you need to save images as PNG files you need to ship the cs_libpng.DLL and the zlib.DLL files. These will be in your application folder, or if not, in the \clarion\accessory\bin folder.  Cs_libpng.DLL and zlib.DLL are linked at runtime. If they are not present Draw will simply not allow PNGs to be written.

If you are using the Barcode method to create PDF417 compatible 2D barcodes then you need to ship the Barcode.DLL file.

If you are using the FreeImage functionality then you will need to ship the FreeImage.DLL as well. Please note that you will need to comply with the FreeImage License if you ship this DLL.

If you are using the QR Code functionality then you will need to ship QRCodeGen.DLL.

Acknowlegements

This product includes the FreeImage DLL and is included here under the terms of the FIPL.

This product includes the LibPng DLL and is included here under the terms of the Libpng License.

This product includes ZLIB and is included here under the terms of the Zlib License.

This product includes QRCodeGen.DLL and is included here under the terms of the MIT license.

Jump Start

Keen to get started? Or just don't like wading through all the documentation? This section is just for you - the basics on how to get Draw working as quickly and simply as possible.

This jump start will show you how to place a Draw control on a window and draw a red rectangle into the control. The completed app is in the /examples/Draw4/JumpStart/ directory in you Clarion directory (QuickDraw.app is the ABC version and QuickLegacy is the Legacy version).



Useful Information:

Methods use in the quickstart

Blank() - clears the current layer to the color specified
Display() - writes all visible layers to the image control
Box() - Draws a rectangle
Setpencolor() - sets the current pen color (used for drawing lines and borders)

Layers

In the above example we completely ignored the fact that Draw supports multiple layers. When the Draw object is first created it creates a layer and sets it as the active layer, so it is possible to simply ignore the fact that a layer is being used. Layers allow a huge amount of flexibility and power, see the section on layers for more information.

Lines and Fills

In addition to setting the pen and fill colors, Draw also supports patterned fill and pens. See SetFill() and Setpenstyle()

Shading

As well as supporting simple shapes like boxes, lines and ellipses Draw has methods that create shapes with complex color shaded fills for boxes, cylinders, ellipses and even shaded lines.

Adding a Draw Control to your Window

Adding a Draw Control to your window is easy:

The Draw Global Extension Template

The global extension is used to enable Draw in your application and also allows you to disable all Draw code, primarily for debugging. From Beta 11, Draw uses runtime DLL linking for writing to PNGs, see the section on Distribution for the DLL required for PNG writing.

Using Draw in Multi-DLL applications

Draw provide options on the global extension to make using it in multi DLL applications simple.
Draw is exported from the Data DLL, and then used in the other apps in your system as required.

Data DLL App
  1. Add the Draw Global extension
  2. On the Multi-DLL tab tick on both options.
Other Apps (DLLs and EXEs)
  1. Add the Draw Global Extension
  2. On the Multi-DLL tab tick on ONLY the first option. (DLL's will default to this being on, but EXE's need it explicitly set.)

Options for the Draw Control

Setting the Object Name

Under 'actions' in the control properties box you can set the object name. This is the object whose methods you will call to do the actual drawing. All examples in this document use the object name "Drawer".

Setting the Class Name

You can also set the class that Draw uses to create objects, this allows you to modify or replace the Draw class with your own customized version with a different name. If you do this please remember to add your own .clw to the project (under "external source files").

Don't generate this Draw Object

This option works similarly to the option on the global template "Don't generate Draw code", rather than disabling all draw code globally, this option allows you to disable any generated code for this object only.

IMPORTANT: The origin of the Draw control is the top left corner and is (1,1). See the image below.
Draw image control

Pixels and Dialog Units

Draw uses pixels throughout rather than dialog units. There are a number of reason behind this, however the primary one is that for drawing pixels is the natural unit of measurement, as whatever is drawn will eventually be rendered in pixels. Changing the font or font size used for a window will not affect Draw at all, unlike other controls which will be affected by the change in dialog units. Using pixels also ensures that there are no rounding errors that result in inaccurate drawing. In addition you can do calculations far more accurately than the screen can render and simply pass the Rounded values to Draw.

You can convert from dialog units to pixels - to get the current number of pixels per dialog units (this is likely to be a fraction, not a whole integer):

pixPerUnit real   ! A variable to store the number of pixels per dialog unit.
curUnits   byte   ! The current "mode" that is being used (either pixels or DLUs).
 
code
    curUnits =
target{prop:pixels} ! Store the current unit setting.
    target{PROP:Pixels} = 0 ! Set to DLUs instead of pixels.

  
 ! Calculate the current pixels per dialog unit using the DLU measurement
    ! and the stored pixels measurement.

    pixPerUnit = self.width/self.control{
prop:width}
   
target{prop:pixels} = curUnits ! Restore the units setting.

Examples

Notes on getting started.

Unlike the Clarion drawing functions, the Draw control does not display the result as each function is called, you need to call the Draw.Display() method to update the Draw control. Before drawing, you can call the Blank method to erase everything on the Draw control, or simply draw over the existing image. This allows you to do real-time animation, simply by calling all the drawing commands before calling Display to update the control, and Blank between each frame of the animation. Note that Blank does not take effect until Display is called.

A typical usage of the Draw methods would be:

!--- Call draw methods and call Display() to display the result
Drawer.Blank()            ! Blanks image control
Drawer.SetPenColor(COLOR:Red)
Drawer.
Ellipse(1, 1, Drawer.width, Drawer.height, COLOR:Green)
Drawer.
Display()        ! Redraws image control with new contents

This would display an ellipse with red line and a green fill that is the width and height of the Draw control.

You can draw to any image control on a window or a report, however when drawing to a report, you need to call the Clarion SetTarget(Report) function before calling any Draw methods. You can call SetTarget() with no parameters to make the current topmost window the current target. See the section on Using Draw on a Report

There are a number of examples in your \Clarion\Examples\Draw4 directory. The examples are a great way to get started and see a few of the ways you can use CapeSoft Draw. Draw ships with the following examples:
JumpStart The result of following the JumpStart section. Th most basic example of how to use Draw. The ABC version is called QuickDraw.app, the Legacy version is QuickLegacy.app

See JumpStart for more details.
3Dmap The 3D map example uses Draw to create really cool 3D maps, with a number of shading and display options. The app file is /examples/Draw4/3DMap/map.app
pattern Pattern.app is both an example and a useful tool. It creates a patterned fill that is used to fill a rectangle. It also displays the pattern string that can be used within your source code. See the Pattern section for more information.
Demo Draw 2.10 ships with a new Demo application that is a great place to get a feel for some of the things that are possible to do quite simply using Draw. This application demonstrates all the basic functions in Draw as well as some neat effects like drop shadows, pie slices, shaded bars etc.
Draw Layers The new Draw example application that ships with Draw 2.00 and later. Allows you to Draw to an image control and shows off a few of Draw's layer features.
DrawImage This example utilizes the Clarion FreeImage template (available from www.clarionfreeimage.com) to save to different file formats and to read images from different file formats. You must have downloaded and installed the Clarion FreeImage template in order to compile this application

Debugging and Logging

Draw provides a Log() method to assist in debugging your Draw applications. This method outputs a string to the windows debug output, all output can be viewer using the free DebugView application from www.sysinternals.com. DebugView can also be used to view any error message that Draw might encounter, even is Draw.suppressErrors = 1. In order to use the build in logging in Draw you should set the Draw.logging property to 1. Any error that a Draw method encounters will then be sent to the debug output. This has the advantage of allowing debug output to be viewed regardless of whether the app is compiled in debug or release mode. It also allows debug output with affecting the program execution, and allows debug logs to be saved. You can view both your own output (using the Log() method) and Draw's output using Debugview, in addition DebugView can be used for producing log files for other CapeSoft products, such as File Manager 3 and NetTalk.

Compiler Errors

Unknown template type. Activate ClarionFreeImage - You are trying to compile/load a draw application that uses the Clarion FreeImage template. This is an independent template available for free download from www.clarionfreeimage.com which you can use to add additional functionality to Draw (like loading and saving images from/to jpg, and other common graphic file formats).

Using the Draw Pattern Fill Maker

Versions from Beta 7 and later include the Draw Pattern Fill Maker, an application which allows you to easily design your own patterned fills with an easy to use graphical interface. See the Setfill() method for more information on pattern fills. To use the Draw Pattern Fill Maker, simply compile the pattern.app that ships with Draw. The files that you need are:

pattern.app - the app file
about.jpg, back.jpg and tick.jpg - image files used in the app
pattern.ico - the application icon

These files are installed in your Clarion directory under 3rdparty/examples/pattern

Simply open pattern.app in Clarion, compile it and run it.

To create a pattern click on the boxes on the left, you will see the resultant pattern in real time on the right of the window. To use the pattern in your clarion app, copy across the string displayed in the text box at the bottom of the window. You can use a variable to store the string, or simply pass it as a string, for example:

Drawer.SetFill('0000000010101010000100011010101000000000101010100001000110101010')

Each pattern is a 8x8 block of pixels that is tiled as necessary to cover the entire fill area, hence the string is 64 characters long, a 1 (one) represents a pixel to filled with the current color, while a 0 (zero) represents a pixel that remains untouched.

See the Setfill() method for more information on pattern fills.

CapeSoft Draw pattern fill maker

Using Draw on Reports

Draw supports the same command on reports as it does on windows, however reports do differ in some ways. When calling Clarion's drawing functions to draw to a report it is necessary to call SetTarget(Report), similarly Draw requires that you call SetTarget(Report) before calling any Draw methods that will draw to the report. When you are finished you can call SetTarget() to set the current target to the last window opened on the current thread. See the Clarion documentation on SetTarget() for more information.

Populating the Draw control on a report is identical to populating it on a window, simply place an image control on the Report and select the "DrawR - CapeSoft Draw Control" template list under "Class Draw - CapeSoft Draw Template" when populating it. The "R" on the end of "Draw" in the template name signifies that it is the Report template control.

When drawing to a report, you will most likely want to increase the resolution when you are drawing (unless you like big pixels and jagged edges of course), as printing is generally done at a much higher resolution than your monitor might display (most screens typically display 96 DPI or less, whereas most desktop printers will print at at least 200DPI, and possibly considerably higher.) So how do we increase the resolution of the Draw control so that our printed reports look really good?

Firstly add the following data to the report procedure:

resized                byte

Then, in the source code for the report procedure, directly after the call to PARENT.Open() the Draw template would have populated the following code:

  SetTarget(report)
  drawer.Init(?Draw)
  SetTarget()

When you would like to draw to the report:

  SetTarget(report)
  drawer.SetPenColor(color:green)
  drawer.SetFontColor(color:red)
  drawer.SetPenWidth(1)
  drawer.Blank()
  if resized = 0                ! checks if the image control should be resized
      drawer.Resize(drawer.width*4, drawer.height*4)
      resized = 1
  end


Once you have finished drawing to the report call SetTarget(), this will set the target back to the last window.

That's it, you can now Draw to reports with high resolution Draw controls. Bear in mind that you should multiply the size of anything that you draw by the amount that you multiply the Draw buffer by (in this case four). If you don't you will get a tiny version of whatever you are drawing in the bottom left corner of the Draw control, this is simply because each pixel is taking up 1/16 (in this case) of what it was taking up before we resized the buffer. For example if we draw a box before the resize: Draw.Box(10, 10, 100, 122, color:red) we should modify the call to Draw.Box(40, 40, 400, 488, color:red). If you are going to be changing the resolution frequently, or allowing the user to specify the resolution you should probably create a variable to store the multiplication factor.

For example the above code to resize the control and draw a box would become:

resMult            long

    resMult = 4
    if resized = 0
        drawer.Resize(drawer.width*resMult, drawer.height*resMult)
        resized = 1
    end


    drawer.Box(10*resMult, 10*resMult, 100*resMult, 122*resMult, color:red)

The call to Draw.Resize() sets the size of the Draw buffer to be 16 times larger (four times as wide and four times as high). You can experiment with a multiplication value that suits you, the higher the value, the higher the resolution, but obviously the more memory you will use.
In order to reduce the amount of memory used by high resolution Draw controls on reports, as well as provide a significant speed improvement, you can use 256 colour drawing. See the section on Init256() for how to draw in 256 colours on a report.

It is also useful to be able to change the font size on reports, especially at higher resolution. To do this you can simply set the Draw.fontZoom class property. The fontZoom property defaults to 1, to increase the size that the fonts draw, increase fontZoom. In the example above we increased the resolution by a factor of 4, so we can set the fontZoom property to 4. When you increase the fontZoom factor, it allows you to use the same point size at higher resolutions. See the Show() method for more information.

A note on printer and monitor resolutions:

A fairly reasonable heuristic (rule of thumb) for estimating the needed resolution of an image for printing is to simply divide the required printer resolution by 4. So for a 360DPI inkjet, a 90 DPI image will print reasonably well, for a 720 DPI inkjet you should use around 180 DPI. More resolution will generally give you a crisper printout and fewer jagged edges (to a point, the resolution is limited by the printer capabilities). The default resolution of the Draw control is 72 DPI.

License & Copyright

This template is copyright © 2024 by CapeSoft Software.  None of the included files may be distributed. Your programs which use Draw can be distributed without any Draw royalties.

Each developer needs his own license to use Draw. (Need to buy more licenses?)

This product is provided as-is. CapeSoft Software and CapeSoft Electronics (collectively trading as CapeSoft), their employees and dealers explicitly accept no liability for any loss or damages which may occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft , their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

For the full EULA see https://capesoft.com/eula.html

Version History

Download latest version here


Version 4.36 (5 February 2024) Version 4.35 (31 January 2024) Version 4.34 (10 November 2023) Version 4.33 (18 July 2022) Version 4.32 (10 June 2021) Version 4.31 (31 May 2021)
Version 4.30 (21 May 2021)
Version 4.29 (14 February 2021) Version 4.28 (9 November 2020) Version 4.27 (3 November 2020)    Version 4.26 (2 November 2020)    Version 4.25 (22 September 2020)    Version 4.24 (21 September 2020)    Version 4.23 (16 September 2020)    Version 4.22 (7 September 2020)    Version 4.21 (24 Feb 2020)    Version 4.20 (13 Sept 2018)    Version 4.19 (24 July 2018)    Version 4.18 (12 June 2018)    Version 4.17 (27 February 2018)    Version 4.16 (16 February 2018)    Version 4.15 (20 December 2017)    Version 4.14 ( 14 December 2017)    Version 4.13 ( 28 July 2017)    Version 4.12 ( 28 July 2017)    Version 4.11 ( 3 October 2016)    Version 4.10 ( 16 September 2016)    Version 4.09 ( 1 September 2016)    Version 4.08 ( 31 August 2016)    Version 4.07 ( 29 August 2016)    Version 4.06 ( 4 August 2016)    Version 4.05 ( 9 June 2016)    Version 4.04 ( 26 May 2016)   
Version 4.03 ( 3 May 2016)   

DrawGauge DrawImage DrawPaint Version 4.02 (26 April 2016)   

DrawGauge Version 4.01 (25 April 2016)   

DrawGauge Version 4.00 (22 April 2016)    Version 3.57 (15 September 2015)    Version 3.56 (10 August 2015)    Version 3.55 (25 February 2015)    Version 3.54 (16 January 2015)    Version 3.53 (22 December 2014)    Version 3.52 (16 December 2014)    Version 3.51 (7 November 2014)    Version 3.50 (22 September 2014)    Version 3.49 (11 July 2014)    Version 3.48 (19 June 2014)    Version 3.47 (10 May 2014)    Version 3.46 (21 January 2014)    Version 3.45 (7 January 2014)    Version 3.44 (3 January 2014)    Version 3.43 (17 December 2013) Version 3.42 (13 September 2013) Version 3.41 (18 July 2013) Version 3.40 (5 July 2013) Version 3.39 (7 June 2013) Version 3.38 (23 May 2013) Version 3.37 (11 May 2013) Version 3.36 (30 April 2013) Version 3.35 (14 March 2013) Version 3.34 (11 February 2013) Version 3.33 (21 January 2013) Version 3.32 (6 November 2012) Version 3.31 (23 October 2012) Version 3.30 (12 July 2012) Version 3.26 (24 May 2012) Version 3.25 (23 May 2012) Version 3.23 (12 April 2012) Version 3.22 (14 December 2011) Version 3.21 (24 October 2011) Version 3.20 (16 September 2011) Version 3.11 (28 July 2011) Version 3.10 (28 July 2011) Version 3.09 (21 July 2011) Version 3.08 (12 July 2011) Version 3.07 (11 July 2011)
Version 3.06 (28 June 2011)
Version 3.05 (6 June 2011) Version 3.03 (25 February 2011) Version 3.02 (16 August 2010) Version 3.01 (10 August 2010) Version 3.00 (4 August 2010) Version 2.82 (30 December 2009) Version 2.81 (21 December 2009) Version 2.80 (29 October 2009) Version 2.79 (16 September 2009) Version 2.78 (27 August 2009) Version 2.77 (14 July 2009) Version 2.76 (15 May 2009) Version 2.75 (6 May 2009) Version 2.74 (03 December 2008) Version 2.73 (01 December 2008) Version 2.72 (10 November 2008) Version 2.71 (13 October 2008) Version 2.70 (12 September 2008) Version 2.69 (30 August 2008) Version 2.69 (28 August 2008) Version 2.68 (22 August 2008) Version 2.67 (02 July 2008) Version 2.66 (03 June 2008) Version 2.65 (03 June 2008) Version 2.64 (23 May 2008) Version 2.63 (23 April 2008) Version 2.62 (16 April 2008) Version 2.61 (13 February 2008) Version 2.60 (25 January 2008) Version 2.59 (06 December 2007) Version 2.58 (30 October 2007) Version 2.57 (25 October 2007) Version 2.56 (25 October 2007) Version 2.55 (18 September 2007) Version 2.53 (23 July 2007) Version 2.52 (16 July 2007) Version 2.41 (29 March 2007) Version 2.41 (29 March 2007) Version 2.40 (14 November 2006) Version 2.30 (29 September 2006) Version 2.26 (10 July 2006) Version 2.25 (24 November 2005) Version 2.20 (17 November 2005) Version 2.15 (08 September 2005) Version 2.14 (28 February 2005) Version 2.13 (10 January 2005) Version 2.12 (05 January 2005) Version 2.11 (04 January 2005) Version 2.10 (30 November 2004) Version 2.09 (21 April 2004) Version 2.08 (14 November 2003) Version 2.07 (04 November 2003)
Version 2.06 (20 August 2003) Version 2.05 (31 July 2003) Version 2.04 (29 July 2003) Version 2.03 Version 2.02 Version 2.01 Version 2.00 (Gold) Version 1.0 Beta 11a Version 1.0 Beta 11 Version 1.0 Beta 10 Version 1.0 Beta 7 Version 1.0 Beta 6 Version 1.0 beta 4
Version 1.0 beta 3 Version 1.0 beta 2
Version 1.0 beta 1: Released