 |
 |
||
 |
|||
Version 
Gold  www.capesoft.com Updated 22 January 2008 |
 |
||
|
|
|
||
|
|
|||
| Version
Gold www.capesoft.com Updated 22 January 2008 |
|
||
Documentation Guide |
||||
IntroductionFor a long time now we have been wanting a tool which easily allows us to draw graphs in our Clarion programs. Our ideal tool should have both a strong drawing engine and a template for linking the graph to the data in the dictionary. Up to now, however, none of the tools provided were sufficiently capable on the template side of making adding a graph to our applications simple.
This is a pity, because a graph is an incredibly powerful way of managing large clumps of data. Many browse windows can be enhanced with a simple graph, and it's much easier to spot trends and anomalies on a graph than on a plain browse screen or report.
Late in 1999 a Clarion programmer (we'll call him "The programmer formerly known as Mike") showed us a really nice engine written entirely in Clarion. We encouraged him to complete the job by writing the necessary template. He asked us to do it, and of course we can't resist a challenge. After rather more work than we expected, the template is now here. Actually, we quite like it - it contains some features never before implemented in a Clarion Template, including a Dynamic User Interface (i.e. the template makes fewer options available to a beginner than to an advanced user).
We think you'll find that the power of this template truly does make adding graphs to your applications simple, with no hand-coding required. Rather than listing all the features here, though, we refer you to the section entitled Features.
Because we've broken new ground in the way some aspects of the template work, we've also had a large number of bug reports where the "bug" is actually a feature. So, before you report a bug, please read One Man's Bug is Another Man's feature.
BETA Notes: For a list of features added during the beta program, see the Version History. As a beta user you will be entitled to free upgrades for the duration of the beta program, and also the Gold release. As a CapeSoft user you will, in all likelihood, be receiving free upgrades for some time beyond that. As we have never charged for a product upgrade (and some of the products are 5 years old) it's safe to say you won't need to spend money on your graphing tool for some time to come.
Upgrading
from Beta 6Every effort has been made to make sure that upgrading from beta 6 to beta 7 (or later) goes as smoothly as possible. There are however some cases where your manual intervention is required. If you have been referred here by the generated code then check the Reference Number next to each point to see which item applies to you.
| Reference 1 | Reports: Up to beta 6 the "control" used on the report has been the 'box' control. This allows you to put a border around your graph. From beta 7 onwards there also needs to be an image control. Your options are:
|
SupportYour questions, comments and suggestions are welcome. Check our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways.
support@capesoft.com Telephone +27 21 715 4000 Fax +27 21 715 2535 Post PO Box 511, Plumstead, 7801, Cape Town, South Africa
Insight Graphing is available for purchase at $349 from:
Web www.capesoft.com sales@capesoft.com Telephone +27 21 715 4000 Fax +27 21 715 2535 Post PO Box 511, Plumstead, 7801, Cape Town, South Africa OR
Web
License & CopyrightThis template is copyright © 2000-2006 by CapeSoft Software (Pty) Ltd, and Mike Berkeley. None of the included files may be distributed, except for DLL files which are required by your application. Your programs which use Insight can be distributed without any Insight royalties.
Each developer needs his own license to use Insight Graphing (need to buy more licenses?).
This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of copyright stated above. In no way will CapeSoft Software (Pty) Ltd, 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.
DistributionIf you are compiling your application in Stand-Alone mode (which means that you are shipping the Clarion runtime DLL's), you will need to ship the Insight DLLs as well as your EXE (and other Clarion DLL's). The exact names of the files to ship depends on your version of Clarion:
DLL required Clarion 5 C5IGX.DLL, LIBPNG.DLL and ZLIB.DLL Clarion 5.5 C55IGX.DLL, LIBPNG.DLL and ZLIB.DLL Clarion 6 C60IGX.DLL, LIBPNG.DLL and ZLIB.DLL
If you are compiling in Local mode (which means you end up with one all-inclusive exe), then you only need to ship the LIBPNG.DLL and ZLIB.DLL files.
Installation1. Run the supplied installation file.
Features
Graphing Engine
- Support for Bar, Pareto, Line, Gantt, Time, Donut, Hi-Lo, Candle and Pie Charts
- Full control over the look and feel of the graph, and the data
- 20 built-in Axis styles, 12 built-in Data Styles
- Automatic Y-Axis Scaling
- Multiple Y-Axis Labeling
- Supports Data-Point Labeling
- Dynamic Interface, exposes more options as you learn.
- Directly interfaces to the tables in your Dictionary
- Supports the Graphing of Fields or Expressions
- Supports the Counting, Summing, and Averaging of records
- Supports dynamic labeling based on the data in your tables
- Uses Views for efficient access to the data, regardless of the File Driver
- Supports plotting data from Queues and Memory Variables as well
- Supports Multiple Views per graph, and Multiple Fields per View
- Supports dynamic (changing) numbers of data sets
- Supports drilling down from one graph to another based on the point clicked on in the first graph
- Allows Graphs on all Windows including Browses, Forms etc.
- Allows multiple graphs on the same window
- Allows for Mouse-Over information
- Allows for a Right-Click menu including options like Zoom In, Zoom Out, Print, Save As, Drill Down, Back Up, Select Graph Type and so on.
- Allows for a default Left-Click action to be set
- Allows automatic placement of Graphs at the beginning or end of the report
- Allows placement of graphs during the report, based on your criteria
- Allows graphs to be added to existing reports
- Allows graphs to be placed next to or above each other
- Allows multiple graphs on one detail
- No Hand-Coding required
- Allows you to set the "look" of your graphs from one global extension, but also allows you to override the look for every individual graph
- Supports Clarion 5, 5.5 and 6
- Supports Legacy and ABC templates
- Supports EXE and DLL apps
- Supports 32 bit (not 16 bit) programs
One
Man's Bug is another Man's Feature There are two combinations of the above that we don't support, because they simply are not useful. If either of these two combinations is set, the legend is will not be displayed. They are:
- Legend position ( where it is in relation to the graph)
- Legend type (Stacked or Inline)
- Font Angle (0 or 90 degrees)
- Position Left or Right (4 or 6), Inline = 1 and Font Angle = 0
- Position Top or Bottom (8 or 2), Inline = 1 and Font Angle = 90
Both of these legend combinations would essentially leave no space for the graph itself.
Tip: A good place to experiment with the legend properties is in the included school example. Click on the Grand Tour button on the toolbar and keep clicking next until you reach the legends example.
A
Bit of BackgroundLike all things, it helps to understand a little bit of the terminology used in the template before you get going. Probably the best way to start is with a diagram:
As you work through the various template options you'll see these words, especially Data Points, Sets and Point Names, a lot. Feel free to refer to the above diagram until you are comfortable with the terms.
- Graph Heading: The heading of the graph. In this case, "Sales for the Year".
- X-Axis Name: The name of the x-axis. In this case, "Quarter".
- Y-Axis Name: The Name of the y-axis. In this case, "Sales".
- Y-Axis Values: These are the values next to the y-axis. In this case they are 0, 27, 55, 82, 109.
- Data Points: Each bar on the chart above is a (data-) point. In general, "data points" refers to the actual points plotted on the graph.
- Set: A set is a collection of data points. In the above graph, there are two sets, each drawn in a different color. So, in this example, the first set consists of all the data points drawn in gray, and the second consists of all the data points drawn in blue.
- Legend: The legend appears to the right of this graph. It lists the color of each set next to its description.
- Point Numbers: These are the x-axis values. One can also see the point numbers as the x-coordinates of the data points. Usually, what appears as labels beneath the x-axis are not the point numbers, but the point names (note that it is possible to use the former as labels), since these are usually more informative. See below.
- Point Names: The point names usually appear below the x-axis. A point name is a (very) short description for a point number. In this case the point names are "1st Quarter", "2nd Quarter", "3rd Quarter" and "4th Quarter".
In this section we give a step-by-step example that will guide you through creating your first application containing an Insight Graph.
Code Example: There is a copy of the source code of this example in your Clarion?/3rdParty/Examples/Insight/JumpStart folder.
What we are doing: Our aim is to create a simple window containing a graph control that will refresh every time new data is loaded. Our end-result will look something like this:
(1) Open Clarion 5, and create a new application. Add the Active Insight Functions Global Extension. In the Template Level dropdown list, choose Advanced. Click OK.
(2) For the main procedure, create a generic window and add a close button. Add to the local data of this procedure the following fields (leave the window formatter, right-click on the Main procedure, choose Data, click Insert):
plottingQueue queue
setNumber long
setName string(128)
pointNumber long
pointName string(128)
value real
end
Give the above queue the prefix "pq".
(3) Go to the window, go to Populate Control Template and add an Insight_Graph Control Template to your window. Resize the region it creates to fit the window, and then right-click on the region and choose Actions. Enter your Graph Heading on the Graph tab ('Sales for the Year' - Tip: Note that for Insight Graphing, every string that is not a variable must be included in single quotes).
(4) Now choose the Data Tab and click on Insert. On the Primary Source Tab of the window that pops up, select Queue from the Data From dropdown list. Select plottingQueue from the Local Data for the Queue Name. Now choose the Sets Tab and click on Insert. On the Set Tab of the new window that pops up, enter pq:setName as the Set Description. For High Field, choose pq:value. Now go to the Advanced Tab of this window, check Override Setnumber and select pq:setNumber for the value. Click OK and OK again.
(5) Now go to the X-Axis Tab and enter the X-axis Name ('Quarter'). Uncheck Automatically Generate. For Point Name, enter pq:pointName, and for Point Number select pq:pointNumber.
(6) Next, go to the Y-Axis Tab and enter a name for the Y-axis ('Sales').
(7) Now click on the Legend Tab and check Override Global Settings, check Display Legend and choose Right in the Position group.
(8) Go to the ThisWindow.Init Procedure embed, just after GlobalErrors.SetProcedureName('Main'), and paste the following code:
PlottingQueue.setNumber = 1
PlottingQueue.setName = 'Sales'
PlottingQueue.pointNumber = 1
PlottingQueue.pointName = '1st Quarter'
PlottingQueue.value = random(1,100)
add(PlottingQueue)
PlottingQueue.setNumber = 1
PlottingQueue.setName = 'Sales'
PlottingQueue.pointNumber = 2
PlottingQueue.pointName = '2nd Quarter'
PlottingQueue.value = random(1,100)
add(PlottingQueue)
PlottingQueue.setNumber = 1
PlottingQueue.setName = 'Sales'
PlottingQueue.pointNumber = 3
PlottingQueue.pointName = '3rd Quarter'
PlottingQueue.value = random(1,100)
add(PlottingQueue)
PlottingQueue.setNumber = 1
PlottingQueue.setName = 'Sales'
PlottingQueue.pointNumber = 4
PlottingQueue.pointName = '4th Quarter'
PlottingQueue.value = random(1,100)
add(PlottingQueue)
PlottingQueue.setNumber = 2
PlottingQueue.setName = 'Refunds'
PlottingQueue.pointNumber = 1
PlottingQueue.pointName = '1st Quarter'
PlottingQueue.value = random(1,10)
add(PlottingQueue)
PlottingQueue.setNumber = 2
PlottingQueue.setName = 'Refunds'
PlottingQueue.pointNumber = 2
PlottingQueue.pointName = '2nd Quarter'
PlottingQueue.value = random(1,10)
add(PlottingQueue)
PlottingQueue.setNumber = 2
PlottingQueue.setName = 'Refunds'
PlottingQueue.pointNumber = 3
PlottingQueue.pointName = '3rd Quarter'
PlottingQueue.value = random(1,10)
add(PlottingQueue)
PlottingQueue.setNumber = 2
PlottingQueue.setName = 'Refunds'
PlottingQueue.pointNumber = 4
PlottingQueue.pointName = '4th Quarter'
PlottingQueue.value = random(1,10)
add(PlottingQueue)(9) Now add a button called ?NewGraph to the window, and in the EVENT:Accepted embed, paste the above code again, but preceded by
free(PlottingQueue) !Wipe out all the data and enter some new ones
and succeeded by
ThisGraph1.Reset() !Reload the data for the graph
ThisGraph1.Draw() !Draw the graph again to reflect the changes(12) If you are using Clarion 5, go to Project Properties and click on the Defines Tab. Enter
_IGDLL_=>0
(11) Compile and Run the application.
When the application launches, click on the New Graph button and see the Insight magic at work. A new graph will be drawn every time, depending on the random numbers generated by the above code.
Tips:
- The values in pq:pointName are used to label each new point on the x-axis.
- pq:value is the value on the y-axis, and pq:pointnumber is the value on the x-axis.
- The value of pq:setnumber indicates to which dataset the value in pq:value belongs to. Each data set is drawn in a different color on the graph.
- The values in pq:setName are used for the names in the legend - they are the names of the different datasets.
- Checking Override Set Number, as we did above, allows one to draw multiple datasets on the same graph without having to add each set individually on the Sets Tab (choosing the latter route means adding a filter on the Set Tab of the Set Window for each set to filter out all points in the queue not belonging to that set).
- The fonts of the legend and headings can be changed by going to the Fonts Tab.
Pie Graphs Pie Graphs are a little differrent than the rest of the graphs. There will only be one set, and each slice in the pie is seen as a point on the X-Axis. So, supposing you had a queue where each record in the queue is a new slice, you would have to take the following steps (see the JumpStart above r.e. more specifics on how to get to the mentioned windows and tabs):
- Add your queue as a data source on the Data Tab.
- For your data source, add one Set. Go to the Set Tab on the Set Window. There is no need to give it a description.
- In the "Field" entry for the set, enter the field containing the value to plot. You can now close the Set Window.
- If you have fields in the queue containing the slice numbers and/or names, you should go to the X-Axis Tab and enter them in the point name and number fields (untick Automatically Generate).
- On the Data Tab you can set what information should be displayed for each slice. On the Legend Tab you can do something similar, but the information will be shown next to the graph as opposed to in labels for the slices.
To make Insight use differrent colors for the slices other than the defaults, we need to override the colors for the points, not the sets. Lets suppose you had a field in your queue that specified the color for that point/slice. We need to take the following steps:
- Go to the one set you created for the pie, and go to its Colors Tab.
- Click Insert for the "Conditional Point Overrides" listbox.
- Enter "true" for the condition.
- Tick "Use Variables for Colors".
- Enter the queue field containing the slice color in the provided fields.
Graph
GalleryJust a small sample of some of the graphs which you make using Insight Graphing.Bar Graphs
Pareto Graphs
Different Shading Techniques
Scattergrams
Line Graphs
Pie Graphs
Mixed Graphs
Different Backgrounds
Complete Control of the Legends
Adding Insight to your ApplicationAdding Insight to your Application is easy.
1. Open your application and click on the Global Button. 2. Click on Extensions, and add the Activate Insight Global Extension. 3.
You don't have to set any of the values, the defaults will all be fine. When you want to, read up on the Global Template Settings to see all the power you have.
Adding
an Insight Graph to a WindowThe hardest part of adding the Graph is deciding on what exactly the Graph is going to show. In other words the data is probably right there in the dictionary, but you need to get the relationship right in your mind first. After that it's easy.
1. Go to the Window Editor 2. Either
Click on the Populate menu and select Control Template, and then choose the Insight Graphing Control.
Or
Place a Region Control on the screen. When asked, select Insight Graph for the region.3.
Go to Actions for the control. Set the various graph properties here. There will appear to be quite a lot to do at first glance, but after you've done a couple it will get easier.
Remember, the interface is dynamic - as you get the hang of it go back to the global extension and increase the Template Interface Level in order to see more options.
A complete list of all the settings, and what they all do, can be found in Options for the Insight Graph Control Template.
Adding
an Insight Graph to a ReportPrinting Insight Graphs on reports is supported. There is however a problem. Due to the nature of report writing in Clarion it is likely that you've either
a. used the standard report templates,
b. used a 3rd party report template, or
c. hand-coded the report yourself.
In addition to this, the placement of graphs on a report will obviously differ greatly from one report to the next. We have therefore tried to make the template for placing a graph on a report as flexible as possible.
If you are using the standard report templates, we recommend the following steps for adding a graph to your report:
- Make a new report band.
- Give the band a name (for example, Graph) and a use equate (for example ?Graph).
- Populate the Insight Control Template onto the band. Set the size of the graph as you wish.
- Select from the default options for the graph (Print at Beginning of Report, Print at End of Report, Other).
- Set the filter for the band. To do this, close the report editor, click on the Report Properties Button, tab across to the Filters Tab and select the filter for the Graph Tab.
Tip: If you selected Print at Beginning or Print at End, set the filter to 1=2. This will ensure that the report template does not trigger the graph. Instead, the graph template will trigger itself.
Tip: If you selected Other then enter the appropriate filter here. If you want to trigger the graph yourself by hand-coding then set the filter to 1=2.
The Insight Template generates four different bits of code for the report. The first is the View (or Views) for the object, along with the object definition. This is done in the Data Section of the template.
The second consists of any overriding methods that may be required by the template.
The third and fourth pieces are generated together in the Procedure Routines Section. You need to call the first routine to initialize the graph. This is done just after the open(report)command. You can simply call the routine in the appropriate place, for example:open(report)
do InitThisGraph1The second routine actually reads the data from the file or queue and prints the graph for you. You call it by simply adding the lines
do DrawThisGraph1
do PrintThisGraph1where you want the graph to print.
If you have multiple graphs on the same detail, you will need to call the drawing routine for each of them individually before calling the printing routine for the last one. Calling the printing routines for the other graphs is not necessary. For example, your code would look something like this:DO DrawThisGraph1
DO DrawThisGraph2
DO PrintThisGraph2Last, but not least, be sure to kill the graphs when the report closes to avoid memory leaks:
DO KillThisGraph1
DO KillThisGraph2Tip: The InsightCPCS example shipped with Insight shows how to add an Insight graph to a CPCS report.
You can add the necessary code to your report by hand as well. The easiest way to do this is as follows:
- Create a basic report and populate it as described in Using the Standard Report Templates.
- Cut & Paste the code from the generated report into the hand-coded report. This code will consist of two (possibly three) sections.
- Section 1: The object declaration and associated Views.
- Section 2: The procedure routines (DrawGraph, PrintGraph and InitGraph).
- Section 3: (may not be there) The new methods for the Graph object. These methods only exist if you have set certain options, so if you can't find them, don't worry.
All the Examples Shipped with Insight include examples of putting graphs onto reports.
ExamplesThe examples shipped with Insight can be found in the \Clarion?\3rdparty\Examples\Insight directory (where \Clarion? is your Clarion 5, Clarion 5.5 or Clarion 6 directory).
Examples include:
- ABC: A single EXE based on the ABC templates. See \ABC\School.app.
- Legacy: A single EXE based on the Legacy templates. See \Legacy\School.app.
Intermediate Level Graphs
: Making your Graph InteractiveNow that you've got a graph on your window, you can start getting really creative. This section assumes that your Template Level is set to Intermediate or higher.
The Mouse Click tab lets you set the default action for the Left-Mouse click and also the possible actions for the Right-Click menu. Most of the items need little explanation. See the Mouse Click Tab section of the Insight Template Guide for more information on how to implement these options.
- Zoom In: Allows you to zoom in on the graph.
- Zoom Out: Zoom out on the graph.
- Cycle Sets: Rotates the order of the data sets on the graph. Use this if you want to bring a specific set to the front of the graph.
- Drill Down: This allows you to drill down to another graph. The idea is that you can create multiple graphs at the same place in the window, with all of them except the top one hidden. As you drill down, the current graph is hidden and the new graph is displayed. The useful thing here is that the data displayed by the graph you are drilling down to can be made to depend on the point of the top graph last clicked on. See Setting Up a Drill Down/Back Up Sequence.
- Back Up: If you are currently on a graph that was drilled down to, this takes you back to the graph that was drilled down from.See Setting Up a Drill Down/Back Up Sequence.
- Graph Type: Allows the end user to change the type of the graph.
- Remember Graph Type: Save the last-chosen graph type for this graph in the INI file and restore it the next time this application is opened.
- Copy: Copy the graph to the windows clipboard.
- Save As... : Allows the graph to be saved as a BMP or PNG file.
- Print Graph: Prints the graph on the current printer.
- What's This: Support for CapeSoft's EzHelp product.
As the mouse moves over the graph it is often nice to be able to see the values of either the current mouse position (line graphs) or the item under the mouse (bar and pie graphs). This information can then be displayed on either the status bar, window caption, in the tip, or on a control elsewhere on the window.
Tip: Only those sets which have a set name will appear in the values list. To suppress a set, make sure its set name to blank.For more information on implementing the mouse over actions, see the section on the Mouse Move Tab in the Insight Template Guide.
Intermediate Level Graphs: Mutiple Y-Axies You may want each of your data sets to have its own y-axis. The end-result would look something like this:
Doing this in Insight is easy:
- Make sure your Global Template Level is on level Intermediate or higher.
- Go to the Y-Axis Tab and tick the Use a Seperate Y-Axis for each Set checkbox.
- Go to the Y-Axis Tab for each Set, and adjust the settings there.
Intermediate Level Graphs: Setting Up a Drill Down/Back Up Sequence Insight has an exciting new feature allowing you drill down from one graph to another.
Say, for example, that you had a bar graph representing the total sales of the twelve departments in your store. Suppose also that you can break down the sales of each department into several smaller categories, depending on the department. Suppose now that right-clicking on a bar and choosing Drill Down makes the graph display the sales break-down for the department to which the bar belongs. Insight makes this possible in just a few easy steps.
- Add a graph to your application and configure it to display the data of the top graph - lets call this the Level 0 graph (displaying the total sales of each department in your store). Suppose its formal name is ThisGraph0.
- Now add a second graph over the first, and make sure that this region is invisible - lets call this the Level 1 graph. Suppose its formal name is ThisGraph1.
- Configure the second graph to display the relevant data - we will fill in the filter on the data below.
- Note that for each graph with name ThisGraphN in your application, the template automatically creates the following local variables:
ThisGraphN:ClickedOnPointName string(255)
ThisGraphN:ClickedOnPointNumber real
ThisGraphN:ClickedOnPointName contains the point name of the point on which you last clicked on ThisGraphN. ThisGraphN:ClickedOnPointNumber works similarly.
- Now Set up the Filter on the Primary Source Tab of the Level1 Graph by making use of the ThisGraph0:ClickedOnPointName and ThisGraph0:ClickedOnPointNumber local variables. If, for example, MySource1:DepartmentName holds the department name for the data to be displayed by ThisGraph1, then you could set the filter to be MySource1:DepartmentName = ThisGraph0:ClickedOnPointName to get the desired result.
The DrillOnStores procedure (the Stores menu item on the Specific Configurations menu) of the Included School Example has implemented the above steps to give you a working example.
Advanced
Level Graphs: International Language / Translation SupportNote: The Template Level on the global extension has to be set to Advanced for you to make use of this feature.
Insight makes it possible for you to translate the right-click menu options to any language of your choice. To do this, go to the Global Extension, and then to the Global Advanced Tab. Enter the text you would like to be displayed as your menu options here. Note that if you are entering a fixed value then you must use quotes. You are also allowed to use variables here.
Advanced Level Graphs: Manually Printing Screen GraphsNote: The Template Level on the global extension has to be set to Advanced for you to make use of this feature.
There are 3 ways to make a graph appear on paper at the printer. The first is to make a report with a graph on it (See Adding Graphs to Reports). The second is to use the "right-click" Print feature (See the the section on Mouse Click Actions above). The third is to call the PrintGraph() method. The SetReportProperties() method has been supplied to be used in conjunction with this method call.
The PrintGraph() method takes four parameters. The syntax is:
PrintGraph (string DeviceName, long ProgramerId=0, long Width=220, long Height=170)
The DeviceName is the name of the printer you would like to print the graph. If blank, the graph is sent to the current default printer. The ProgrammerId is there purely for the benefit of the programmer (it comes in handy if you use the SetReportProperties method, discussed in a moment.) The Width and Height parameters set the width and height of the graph control on the page.
The SetReportProperties() method is called from inside PrintGraph() (after the internal report structure is opened). SetReportProperties() is there to allow you to set additional report properties (for example the paper size, report orientation, and so on) before the internal report is printed by PrintGraph(). The code to do this can just be embedded in SetReportProperties(). The syntax for the method is:SetReportProperties (long ProgrammerID)In your embed code you'll have access to the ProgrammerID. This is the same number as was passed to the PrintGraph() method. This allows you to have multiple behaviors in the SetReportProperties() method. Note that the right-click Print option calls this method with a ProgrammerID of 255.
To generate this method so that you can embed your own code in it, go to Actions of the graph control, and then to the Advanced Tab. Tick the option named Generate SetReportProperties on. Then use the embeditor to add any code you'd like.
Examples:
ThisGraph1.PrintGraph('')Tip: The GraphSales procedure in the Insight School Example (\clarion?\3rdparty\examples\insight\abc\school.app) has a print button that uses these techniques.
ThisGraph1.PrintGraph('Laser Series Printer')
ThisGraph1.PrintGraph('',1,100,100)
Advanced Level Graphs: Adding to the Available Fonts ListNote: The Template Level on the global extension has to be set to Advanced for you to make use of this feature.
There is the danger when working with fonts that the font your program requires will not be present on the end-user's computer. Therefore, instead of presenting you with a list of all the fonts available on your computer in the templates, we present a subset consisting of the most common fonts. These include Arial, MS Sans Serif, Times New Roman, and so on.
There are however cases where you would want to add a font to this list. For example, you may need to use a font which supports a different character set, or you may want to use your favorite exotic font. Fortunately, we have a way for you to do this.
To add fonts to the available list, follow the two easy steps below:
- Using Notepad (or any other text file editor), create a file called Fonts.Ini in the \Clarion?\3rdparty\Bin directory.
- Inside this file put a list of the fonts you would like to include. Note that this file isn't actually an INI file, so section headings, etc. are not required. Your file might look something like this:
Verdana
Tahoma
Comic Sans Ms
Note that the items in this list are added to the standard Insight list, so you don't have to add the standard ones here too. You only have to add your new special ones.
Tip: Please remember - you need to enter the name of the font exactly as it appears in Windows. And also remember, if you use an exotic font, then you need to make sure it is on your customer's machine as well.
Advanced Level Graphs: Using a Variable Number of Sets Note: The Template Level on the global extension has to be set to Advanced for you to make use of this feature.
Consider the following graph:
You have a Invoicing type program where the different products are broken up into departments. The number of departments and their names are set by the user and can vary from site to site.
Now you want to graph the total sales for each month of the year, but you want to include all the departments on the graph as different sets. Clearly, the number of departments in this example will vary, and up to now we have only seen how to define the sets in the template. Insight does however cater for this phenomenon of a variable number of data sets, and setting this up is actually quite easy.
Before continuing, let's review the existing methods for creating graphs with a fixed number of sets. First, you can add multiple entries to the Data Tab. That would look something like this:
You can also create multiple entries on the Sets Tab:
Using filters and ranges it is possible to create a fixed number of sets, and it's easy to put the data in the right set.
In the case of a variable number of sets, though, the secret is to create just one set, and then to use the Override Set Number facility on the Advanced Tab:
By setting the Set Number explicitly to a variable or expression, you can send the data to different (and a variable number of) sets.
Note that all Sum, Average and Count functions should work fine, even in a variable set environment, and even if the the data is not ordered.For a more detailed example on how to implement this, see the JumpStart section in this document. The source code is available in your c:\clarion?\3rdparty\examples\insight\jumpstart folder.
Advanced Level Graphs: Drawing on your Graph Some users find it useful to be able to draw their own shapes and write their own text on the graph area. With Insight this is possible by making use of some low-level drawing methods.
To start drawing on your graph, you first need to make sure that your Global Template Level is set to Advanced. Now go to the Advanced Tab of your Insight control, and tick the Generate Draw() checkbox. This tells the Insight template to generate the .Draw() method.
All you need to do now is to embed the code needed to display the objects and text you want on your graph in the .Draw() method, after the parent call. Make sure you call .Display(). after adding all the text and objects to your graph, as otherwise your changes will not reflect onscreen.
Note that if your desire is to draw horisontal or vertical lines on your graph, one or two calls to .AddSpecialAxis() may accomplish what you need. Note that this method does not fall under the low-level drawing methods, though. Here, you only need to make your calls to .AddSpecialAxis() followed by a call to .Draw() at an appropriate place in your code.
An example illustrating the use of the low-level drawing methods can be found in the included school example - see the PreDrawn window under the Advanced menu.
How to Know When to Use a Pie GraphWe thought it might be worth mentioning some tips and tricks regarding how best to represent your data, especially with respect to pie graphs.
Firstly, a pie graph is expected to have around six slices. If there are many more slices, it is usually because there are a number of very small slices. In the latter case, it is advisable that these get combined to form one slice labeled"Other". Doing this will not only make the pie chart easier to understand, but the labels for the pie slices will also have more space and will therefore be more legible.
Another thing we also recommend is that you order your pie slices from largest to smallest . Again, this will impart more information to the reader by making the slices more easily comparable.
Playing around with certain pie properties, such as PieAngle and PieLabelLines, may also improve the way your graph looks to some extent. For example, Insight tries its best to calculate the optimum number of lines over which the data label for each pie slice should be spread. You might, however, find that the graph layout improves when setting PieLabelLines to 2 when insight is choosing 1. In cases where the left-hand side of your graph looks cluttered, you can also try setting PieAngle to merely 1 or 2 (degrees), especially if your last slice is tiny. This will move the small slice and its label to the right, making more space for the rest of the data labels on the left.
If none of the above suggestions make your pie chart seem any friendlier to the eye, it may be that a pie is not the optimal representation for your data. Bar charts are often better representations in these cases.
How to Use the Standard Windows Colors The good news is that Insight now supports the use of the Standard Windows Colors. The way they have been implemented is that the template creates a number of local variables (actually belonging to a group) which contain these values. They are populated when a window or report containing an insight graph is initialized. You can use them anywhere in the Insight template or in the rest of your program in the same way you would use the usual color equates (e.g. COLOR:Aqua). Note that for every insight object another such group is created.
Tip: Note that you are actually using variables here, and not equates. Hence, In some cases, such as on the Colors Tab of a Given Set, it might be necessary to tick the Use Variables for Colors checkbox.
Note for Hand-Coders: See the .GetWindowsColors() method in the Insight Technical Guide.
The available colors may vary depending on the version of Windows you are running. The names have to a large extent remained the same, except where Clarion does not allow it - so, for example, 3DFace has become Face3D. Asuming your Insight graph object is called ThisGraph1, the available colors are as follows:
ThisGraph1:Color:Scrollbar
ThisGraph1:Color:Background
ThisGraph1:Color:ActiveCaption
ThisGraph1:Color:InactiveCaption
ThisGraph1:Color:Menu
ThisGraph1:Color:Window
ThisGraph1:Color:WindowFrame
ThisGraph1:Color:MenuText
ThisGraph1:Color:WindowText
ThisGraph1:Color:CaptionText
ThisGraph1:Color:ActiveBorder
ThisGraph1:Color:InactiveBorder
ThisGraph1:Color:AppWorkSpace
ThisGraph1:Color:Highlight
ThisGraph1:Color:HighlightText
ThisGraph1:Color:BTNFace
ThisGraph1:Color:BTNShadow
ThisGraph1:Color:GrayText
ThisGraph1:Color:BTNText
ThisGraph1:Color:InactiveCaptionText
ThisGraph1:Color:BTNHighlightThisGraph1:Color:DKShadow3D
ThisGraph1:Color:Light3D
ThisGraph1:Color:InfoText
ThisGraph1:Color:InfoBKThisGraph1:Color:HotLight
ThisGraph1:Color:GradientActiveCaption
ThisGraph1:Color:GradientInactiveCaptionThisGraph1:Color:MenuHighlight
ThisGraph1:Color:MenuBarThisGraph1:Color:Desktop
ThisGraph1:Color:Face3D
ThisGraph1:Color:Shadow3D
ThisGraph1:Color:Highlight3D
ThisGraph1:Color:HiLight3D
ThisGraph1:Color:BTNHiLight
How to Use Insight in a Multi-DLL Application Simply make sure you add the Insight Global Extension to every DLL, program or anything else that makes use of Insight Graphing.
Special
Information for Clarion 5 UsersIt is our goal to support Clarion 5 for as long as is possible. However, Clarion 5 does not offer all the facilities that Clarion 5.5 and later offer. Thus there are occasionally small additional tasks required if you are using Clarion 5.
1. Define needed in Local Mode
If you are compiling in local mode , then you need to add the following define to your application:
_IGDLL_=>0
Failure to do this will result in a GPF on any procedure that contains a graph.
To add the define to your application:
- Open the app
- Click on the PROJECT button
- Click on the PROPERTIES button
- Click on the DEFINES tab
- Enter
_IGDLL_=>0
Common Errors
1. The xxx.Exe file is linked to missing export yyyyy
This means that you have an old Insight DLL in the application directory or in the path. Check your machine for C60IGX.DLL (or C55IGX.DLL, or C5IGX.DLL, depending on your Clarion version).
2. The Right-Click, Left-Click or MouseOver functionality has stopped working.
The IMM (Immediate) attribute has been turned off on the Insight control.
3. I'm using Clarion 5 and my APP GPF's whenever I get to a window with a graph.
See the Special Information for Clarion 5 users section.
4. When I try to add an Insight Graph to my window, I get a whole lot of messages of the form "Unknown Variable '%GlobalGridVGridColor'.
Before adding an Insight Graph to your application, make sure you have Added the Global Extension.
5. When compiling my application, I get errors of the form "Syntax error: Prototype is: SETPOINTNAME(INSIGHTROOT, long)" and "Syntax error: Procedure doesn't belong to module: THISGRAPH1.SETPOINTNAME".
This aften happens when one embeds code in a procedure that appears when the Source is being edited, but that is not actually included in the generated source module. For the above error in particular, the problem is solved by entering a '+' in the Point Name field on the X-Axis Tab. For other methods, check the specific entry under the Embed Points Section of the Technical Guide.
Tips
& FAQ1. Clarion Versions: Insight is available for Clarion 5, 5.5, 6.1 and 6.2. There is no upgrade charge. However, you will need the correct installer to match the version of Clarion that you are using. Download the correct version from www.capesoft.com\insightd.htm.
2. Does Insight use an OCX? Insight does not make use of any external OCX or other installed component. Insight does use a DLL containing pure Clarion code, which you can ship with your program. See the Distribution section.
3. Does Insight have to use the DLL, or can you make a single EXE? Insight uses a DLL when you are compiling in Stand-Alone mode (in this mode you are shipping Clarion Runtime DLL's as well). If you compile in Local mode, the Insight code is linked into your single EXE.
4. Is there any limit to the number of sets on a graph? None, other than practical screen real-estate issues.
5. Is there any limit to the number of graphs on a window or report? Not that we're aware of. On a window only visible graphs are loaded and drawn, so performance is not an issue.
6. Can graphs be placed side by side on a report? Yes. There is no limit to the number of graphs on a detail, and no limit to the number of details containing graphs.
7. Can you add graphs to existing reports? Yes. The template supports automatically placing graphs at the beginning or end of the report. With a line or two of code (explained in the section on Adding Graphs to Reports) you can put the graph wherever you like.
8. The templates seem to imply that I need two or more related files. What if I just want to graph points from a single file? You can ignore the Related Files Tab.
9. The range and/or filters for the graph are not working. If you are using your own variables (i.e. not file fields) in the range or filter, and these variables do NOT appear on either the Local Data button or the Global Data button, you will need to BIND the fields yourself:
10. Making
your own point names: There
are cases where you will want to insert your own code for setting or formatting
the point names. For example, you might want to convert a month number (1 to
12) to a name (Jan, Feb and so on). The method for doing this is a two step process:
11. Why are the number of x-axis grid lines less than what is specified on the Grid Tab? On the X-axis Tab there is a check-box labeledOptimize X-ticks. If this has been checked, Insight will automatically calculate and use the optimal number of grid lines. For the quantity specified on the Grid Tab to be used, the Optimize X-ticks check-box on the X-Axis Tab has to be unticked.
12. Why is my flat button not being displayed as flat? Go to the Advanced Tab of the template (the global extension must have its Template Level set to Advanced) and uncheck the "Enable window buffering mode" checkbox. If this option is checked, the line of code window{prop:buffer} = 1 is generated and called directly after the Insight Init() method.
13. Why does my graph take so long to load when the window starts up? Go to the Advanced Tab of the template (the global extension must have its Template Level set to Advanced) and uncheck the "Reset graph on window reset" checkbox. If this option is checked, the graph is reset every time the window's Reset() method is called.
14. In my 3D pie chart with custom colors the drop colors are not the same as the slice colors. How can I change this? The color used by Insight to draw the drops is the Shadow Color - this is changed on the same tab as the Fill Color that you customized (see the Insight Control's Colors Tab). If you leave the shadow color to COLOR:None, Insight will use the default colors for the drops, which explains why they don't match up to your customized colors.
15. My report that includes an Insight graph takes forever to produce. The problem is that the graph gets redrawn way more times than is necessary. To prevent this, the DrawThisGraph routine needs to be filtered out in the TakeRecord() method. To do this, go to the Procedure Properties of the report, click on the big Report Properties button, go to the Filters Tab, choose the Graph entry and enter "1 = 2".
16. My Y-Axis is not being scaled as I specified. Firstly, note that the default number of y-axis grid lines is 5 (you can change this on the Grid Tab). Insight always draws the exact amount of grid lines specified. If you specify the max (and min) value for the y-axis and the step value, and these three values don't all line up perfectly, Insight will change some of your specified values to allow it to draw the graph. For example, it is impossible to draw a graph with 5 y-axis grid lines, a max value of 50, a min value of 0 and a step value of 15, and Insight will modify at least one of these values before drawing the graph. Note that using multiple y-axies complicates this further, because all the y-axies must have the same number of grid lines.
17. When there is an x-axis point with no data values plotted at that point, Insight just leaves it out. I want to see every x-axis point, even if there is no data for it. You need to specify the point numbers (and names) yourself. If you don't, Insight will do this for you automatically and this will result in empty x-axis points being ignored. To do this, go to the X-Axis Tab and fill in the Point Number (and Point Name) (untick Automatically Generate).
18. How can I change my graph header at run time? Embed the code self.headername = 'New Header Name' in the ThisGraph.Reset() method. Note that, if you have set the Graph Heading in the template, the code for the header is also generated in the ThisGraph.Reset() method. Therefore, either make sure you leave the heading in the template blank, or embed the above line of code after the parent call.
19. At a given x-axis point, how do you make sure all the bars touch each other? Set the Point Width on the Set Tab to 100.
20. I have four numeric variables I want to plot on a pie chart, but it only shows the first variable - the pie is one big red circle. What am I doing wrong? There are two things you need to make sure of when using variables to plot your pie graph: Firstly, make sure you have filled in the Point Name and Point Number for each variable on the X-Axis Tab of the Set Window - note that this is NOT the main X-Axis Tab. Because you are using variables, and since these tend to be single-valued, Insight does not know which point on the x-axis to plot the value in the variable for. For the first variable you can fill in 1, for the second 2, and so on. Then you must also make sure Insight knows that all the values in these variables belong to the same set - by design, a pie graph consists of slices that are points belonging to a single set. To do this, for each variable go to the Advanced Tab of the Set Window (make sure the Template Level is set to Advanced on the global extension), click Override Set Number, and fill in 1.
21. I have a variable number of data sets in my graph. However, when there are just one or two sets present, all of the data sets are still listed in the legend and point summaries. What happens is that the legend and point summaries use the data sets that have nonempty set descriptions. Every time the graph is reset, the sets are not cleared or deleted, as this would result in all the information you have saved regarding the sets being deleted, e.g. the color, pattern, y-axis information, data-label formats, etc. If you are not concerned with this information, you could use the .ClearSetQ() to delete all the sets.
The safer option is to embed in the .Reset method, before the parent call, code that calls .SetSetDescription(Set, '') for each Set. For example, the code will look something like this:
set(Graduates)
loop until Access:Graduates.next()
self.setsetDescription(Graduates.year, '')
endThe sets appearing in the graph will have their descriptions added by the parent call, so you need not worry about that. For a working example, see Variable Sets under the Specific Configurations menu in the included School Example.
22. Why does my pareto graph not have the same number of x-axis grid lines as specified on the Grid Tab? On the X-Axis Tab, if Optimise X-Ticks is on, Insight will calc
