|
|||||||
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:
- Individual pixels to be modified, which is great for per pixel effects
- Faster special effects drawing.
- Images can be saved in either BMP or PNG formats, and with the new DrawImage functionality (which utilitizes the Clarion FreeImage library available from www.Clarionfreeimage.com) images can be loaded and saved to and from JPEG, BMP, TIFF, PNG, PCX and a large number of additional formats.
- Real-time animation in a standard Clarion image control.
- Very fast redraws.
- All commands are drawn directly to a buffer.
- Advanced drawing functions that easily allow you to achieve complex effects.
- Multiple layers, and transparency types.
Draw has evolved a long way in the 11 public Betas that Draw 1.0 went
through. In addition to Draw 2.00 being the first Gold release of Draw, some
exciting new functionality has been added:
Draw now supports multiple drawing surfaces, otherwise known as layers. Some of the features include:
- Layers can be any size (not necessarily the same as the image control).
- Layers can be hidden, which means you that can have hidden drawing surface that can be used as off-screen buffers.
- Pixels can be copied in blocks of any size from any layer to any layer, with full control over the exact size and location of the block.
- Any layer can be drawn directly to the image control.
- Drawing to a layer is as simple as selecting the layer using the WithLayer() method and then calling the Draw methods normally;
- Each layer supports index transparency (a single color can be selected as transparent).
- In addition each layer can have an associated alpha layer, which allows soft transparency effects. Alpha layers can store three separate channels of alpha information, which can be associated with any number of layers.
- See the section on layers for more information.
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 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
| |
Clarion 5 Users DrawDLLMode=>0 If you don't add this define you will GPF your application |
| |
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 | ||||||||||
|
||||||||||
| CapeSoft Sales | ||||||||||||
|
||||||||||||
| Buy Online | ||||||||
|
||||||||
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 file in you Clarion\3rdparty\bin directory with your application. libpng.dll and zlib.dll are inked at runtime, so if you don't ship them Draw will attempt to use the dlls (if they exists) on the system. If LibPNG and zlib are not present Draw will simply not allow PNGs to be written (by default no error will be displayed, and Draw will continue to work completely normally otherwise, see suppressErrors and ErrorTrap() for more information on error trapping). If you are using the Draw.Barcode function to create PDF417 compatible 2D barcodes then you need to ship the Barcode.dll file in your Clarion\3rdparty\bin\ directory.
 |
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 /3rdparty/examples/Draw/JumpStart/ directory in you Clarion directory (QuickDraw.app is the ABC version and QuickLegacy is the Legacy version). |
||||||||||||||||
|
|
 |
Create a new application (or open an existing one). The app must be compiled as 32-bit, as Draw does not support 16-bit programs. |
|||||||||||||||
|
|
Select a procedure with a window that you would like to place the Draw control on (create one if necessary), right click the procedure name and choose "window" to open the window formatter. | ||||||||||||||||
|
|
Place an image control on the window. You will be prompted to select the control template to use, choose "Draw - CapeSoft Draw control". Resize the Draw control - you can make it any size you like. |
||||||||||||||||
|
|
Right click on the Draw control and choose "Actions".
Change the name of the object to "drawer". Click OK |
||||||||||||||||
|
|||||||||||||||||
Adding a Draw Control to your Window
Note:
CapeSoft Draw only supports 32 bit applications
Adding a Draw Control to your window is easy:
-
(Optional) Add the global extension template for Draw. Go to the Global Properties Dialog box in you application, selection extensions, then insert the GloDraw extension.
-
Open the window editor for the window;
-
Place an image control on the window;
-
Select CapeSoft Draw Control from the template populate box;
-
Right click on the control and choose 'actions', here you can customize the Draw control's settings, such as giving the object a name - see Options for the Draw Control.
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 (and Progress) in Multi-DLL applications
Draw and Progress provide options on the global extension to make using Draw and Progress in multi DLL applications simple. For the Data DLL you need to add the global extension, and for every other app file that uses Draw and Progress exported from that DLL, you should add the the global extension and tick the "Use Draw that is exported in another DLL" option.
If you are not familiar with Multi-DLL development, or you need to create a new Multi-DLL from scratch rather than adding the extensions to existing applications the steps are as follows:
Data DLL
- Add the global extensions
- Compile the data DLL
Note: The "Use Draw (and Progress) that is exported in another DLL" settings on the template must be unticked for Draw and Progress in the data DLL (the DLL that they are being exported from)
Main APP
- Add the global extensions
- On both the Draw and Progress global extensions tick the "Use Draw (and Progress) that is exported in another DLL" tick boxes
- From the Application menu choose "Insert Module"
- Choose "External DLL"
- Click on the Lookup button next to the Name field and select the LIB file for your data DLL. Click OK.
The Multi-DLL example in the 3rdparty\examples\Draw\ folder in
your Clarion directory demonstrates this.
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 customised 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.
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\3rdParty\Examples\Draw 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 clarion/3rdparty/examples/Draw/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.
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.
Version History
Click Here for the Version History.