 |
 |
|
AxPqCrChart20 Broken Reference |
Broken Interop References |
|
CHARTrunner 2.0 Software Developer's Kit |
|
Programmer's Guide |
|
Date: 21-December-2005 |
This document applies only to CHARTrunner version 2.0. It does not apply to earlier versions.
CHARTrunner is a software application for creating, displaying, and publishing statistical process control (SPC) charts. The charts may use data from a wide variety of sources including Microsoft Access, SQL Server, Microsoft Excel, Oracle, and even simple text files. It runs on Microsoft Windows 95 and higher. CHARTrunner may be used as an SPC charting component that is integrated with other systems or applications. This document describes some of the techniques available for performing this integration.
The CHARTrunner ActiveX components can be used from within your own program to define a chart definition using code, read a chart definition from disk, save a chart definition to disk, display a chart in a window, display a chart on your own form (VB6, VB.NET or Internet Explorer) using the CHARTrunner 2.0 Charting Control, print a chart, save a chart as an image file, save a chart as a clipCHART, save a chart as a web page, send a chart as an e-mail, get chart statistics, and more.
CHARTrunner-e is the web server version of CHARTrunner. It may be used to publish charts defined in CHARTrunner so that the charts may be viewed by anyone with a web browser and access to the web server where CHARTrunner-e is installed. The CHARTrunner-e client has the ability to completely customize any chart or to define and draw a chart definition "on-the-fly". Currently this feature is only available via scripting code on the client. Click here for more information.
CHARTrunner was created by PQ Systems, Inc. the developers of SQCpack™. To learn more about PQ Systems, visit:
To learn more about CHARTrunner, visit:
http://www.chartrunner.com and http://www.chartrunner.com/sdk
Box and Whisker charts
Short-Run SPC charts
Three-way control charts
Cpk for six sigma
Save chart as web page
Send chart as e-mail
Display data values near points
1, 2, 3 sigma options
Improved "Extra lines on the chart" capability
Improved "Data above the chart grid"
Three dimensional bars for Pareto and Histogram charts
View charts in a folder or workspace as a slideshow
Improvements to "Advanced Row Selection"
Swed Eisenhart out-of-control test rules for healthcare
Improved documentation
SDK updated to include .NET applications
The changes that have been made to the API (Application Programming Interface) for the CHARTrunner 2.0 SDK are detailed in CrSDK_API_Changes.htm.
If you install CHARTrunner or any CHARTrunner component on a computer, you must purchase a CHARTrunner license for that computer. CHARTrunner and/or CHARTrunner components are licensed on a per-computer basis. Any system or application derived from CHARTrunner and/or CHARTrunner components may be used only on computers for which a CHARTrunner license has been purchased. Click here for the details on each type of CHARTrunner license agreement.
Click here for the Reference Manual which provides more information about the objects, properties and methods exposed by the CHARTrunner ActiveX components. Click here for the most recent version on the web.
SDK programmers sometimes ask us why the CLSID (Class ID or GUID) for PqCr20.dll (or one of the other CHARTrunner ActiveX components) changes, which causes the programmer to have to open their application project and fix the reference to the "CHARTrunner 2.0 Application DLL" (or one of the other CHARTrunner ActiveX components). We regret this inconvenience to our customers, but due to the way VB6 works we cannot prevent this from happening without losing the ability to localize CHARTrunner in foreign languages. The localization scheme that we use depends upon a public Enum value that is exposed by PqCr20.dll. This Enum is used to identify each English language string constant that is used in CHARTrunner. As a result, whenever we change this public Enum because we add or remove a string constant, the result is that VB6 creates a new CLSID for PqCr20.dll.
To add the CHARTrunner 2.0 Charting Control to a .NET project click Tools > Add/Remove Toolbox Items > COM Components. Select PqCrChart20.PqCrChart and click OK. The PqCrChart20.PqCrChart control is added to the Toolbox tab currently having focus.
Alternatively, open the Toolbox, right-click on the tab you want to use, and select Add/Remove Items, then click on the COM Components tab, select PqCrChart20.PqCrChart and click OK. This ensures that the PqCrChart20.PqCrChart control gets added to that specific tab.
If you like, you can right-click the PqCrChart20.PqCrChart item in the Toolbox and rename it to whatever name you desire. When you place an instance of this control onto a Windows Form or other container it will be of type AxPqCrChart20.AxPqCrChart, which is the type that was automatically assigned by Visual Studio .NET during the interop process.
If you look in Solution Explorer under References for the project, at this point no interop references to the CHARTrunner ActiveX components exist. However, when you place the first instance of the PqCrChart20.PqCrChart control onto a Windows Form the following References are automatically created by Visual Studio .NET:
You will note that no reference to CHARTrunner20 has been created. That is because no public method or property of PqCrChart20.PqCrChart refers to a type that is contained within the CHARTrunner 2.0 Application DLL. This behavior is by design so that if the CLSID of the CHARTrunner 2.0 Application DLL ever changes, which it probably will, then the CLSID of PqCrChart20.PqCrChart doesn't have to change.
To add the CHARTrunner 2.0 Application DLL to a .NET project click Project > Add Reference > COM and select "CHARTrunner 2.0 Application DLL", then click OK. Now you should have a CHARTrunner20 entry under References in Solution Explorer. Because the "CHARTrunner 2.0 Application DLL" itself depends on other COM components a number of other interop references will be added to your project.
The following list of references will be added:
The Problem. You have a project with existing interop references to CHARTrunner components and you get a newer version of CHARTrunner that causes one or more of your interop referrences to display a yellow exclamation mark as shown in the figures below.
|
|
|
AxPqCrChart20 Broken Reference |
Broken Interop References |
The broken references result from the fact that your .NET project file records information about the CLSID, type library version, and locale ID of each interop component. We try to avoid changes to the CHARTrunner components that result in a changed reference, but from time to time we may make such changes, which will result in the yellow exclamation icons and a project that no longer runs.
IMPORTANT: If you find that you have a broken reference to AxPqCrChart20 or PqCrChart20 as shown in the left figure above, or if instances of the PQCrChart20 control that you have placed on forms suddenly vanish, then close your project immediately and do not save any changes. If Visual Studio .NET cannot successfully load the PqCrChart20 control via interop then it silently removes all instances of this control from all affected forms in your project. If you save your project in this state it could take a lot of work to recover by having to place the PqCrChart20 control in the proper place with the correct properties on each of the affected forms. We will certainly try to avoid making any changes to the PqCrChart20 ActiveX control that cause this to happen because we know what a problem it causes. Follow these instructions to fix this situation.
The Fix for a Broken Reference to the CHARTrunner Charting Control (AxPqCrChart20 or PqCrChart20).
<Reference
Name = "AxPqCrChart20"
Guid = "{84DE6D53-07C3-4FA5-8823-FC1EC682D5CC}"
VersionMajor = "1"
VersionMinor = "0"
Lcid = "0"
WrapperTool = "aximp"
/>
<Reference
Name = "PqCrChart20"
Guid = "{84DE6D53-07C3-4FA5-8823-FC1EC682D5CC}"
VersionMajor = "1"
VersionMinor = "0"
Lcid = "0"
WrapperTool = "tlbimp"
/>
The Fix for Broken Interop References. Display Solution Explorer's References in your project so that the yellow exclamation icons are shown as in the figure above. Right click each entry that has the yellow exclamation and remove it. If you have not already done so, also remove the CHARTrunner20 entry, even if it doesn't have the yellow exclamation icon. Then click Project > Add Reference > COM and select "CHARTrunner 2.0 Application DLL", then click OK. Now you should have a new CHARTrunner20 entry under References and the yellow exclamation should not be visible on any of the CHARTrunner components.
It is not recommended that you use tlbimp.exe to rebuild Interop.CHARTrunner20.dll in order to repair a changed CHARTrunner reference for these reasons (which also apply to any of the other CHARTrunner interop DLLs):
You may want to install the CHARTrunner SDK components during the installation of your application. The standard single EXE CHARTrunner installation file is typically called chartrunner20_trial.exe and can be downloaded from www.chartrunner.com. For this discussion it is assumed that chartrunner20_trial.exe was downloaded and renamed as CrSetup.exe.
Here is the command line to do a silent SDK install for CHARTrunner 2.0:
CrSetup.exe -s -a NO_PROMPT SDK
The "-s" tells CrSetup.exe to run silently.
The "-a" tells CrSetup.exe to install using the arguments that follow. Actually, what it does is pass these arguments to the setup.exe that lives inside of CrSetup.exe.
NO_PROMPT specifies not to prompt the user for input during the install and not to display any information messages.
CHARTrunner will be installed to the \Program Files\PQ Systems\CHARTrunner 2.0\ folder on the drive where the operating system is installed. If you would like to specify a different location then create the InstallPath registry value (of type String or REG_SZ) as follows to specify where CHARTrunner should be installed. Of course, you must create this registry value before you launch CrSetup.exe.
HKEY_LOCAL_MACHINE\SOFTWARE\PQ Systems\CHARTrunner 2.0\Install\InstallPath
SDK specifies to only install the SDK components. The desktop shortcut to CHARTrunner will not be installed. The right-click Windows Explorer file associations will not be installed. The sample charts and sample data will not be installed. The CHARTrunner-XL Excel Add-In will not be installed. The ChRn20.L32 license file that normally gets installed with CHARTrunner will not be installed (if the standard ChRn20. L32 license file were to be installed then the CHARTrunner components would operate in "30 day trial mode").
It will be up to your install program to copy the ChRn20.L32 that you received (after you signed the "CHARTrunner IP License Agreement") into the CHARTrunner installation folder. After CrSetup.exe has completed the CHARTrunner portion of the install your install program can examine the following CrAppPath registry value in order to obtain where your L32 file should be copied:
HKEY_LOCAL_MACHINE\SOFTWARE\PQ Systems\CHARTrunner 2.0\General\CrAppPath
If a reboot is needed in order to complete the CHARTrunner install, then the RebootNeeded registry value will be set to 1. Your install should read this registry value and reboot at the end of your application's install if the value is non-zero.
HKEY_LOCAL_MACHINE\SOFTWARE\PQ Systems\CHARTrunner 2.0\Install\RebootNeeded
CHARTrunner uses a set of ActiveX components. ActiveX is a Microsoft standard for developing programmable, interchangeable software components. These components may be programmed using a variety of software development environments. For example, Microsoft ships a version of the Visual Basic programming language, called VBA, with Microsoft Word and Excel. Macros in Word and Excel are implemented using this VBA scripting language. One way to program the CHARTrunner components is to use VBA from within Word or Excel.
Here is a partial list of programming environments that can be used with CHARTrunner components:
The CHARTrunner Software Developer's Kit includes examples using many of these programming environments.
When programming CHARTrunner, it is helpful to understand the following terms:
An Object is a programming construct which can be created, used, and destroyed while a program is running. A Property describes some aspect of the object. For example, a car is an object, the color of the car is a property. A Method is some action that can be taken with the object or done to the object. For example:
Object: car
Property: car.color = red
Method: car.start (as in start the car)
Objects may have many properties and many methods. As a programmer, if you can see an object’s properties or methods, these are known as public; either public properties or public methods. Objects may have properties and methods that the programmer does not see. These are known as private. Generally, you do not need to know anything about the private properties and methods; you need only to know they exist.
When programming CHARTrunner, the two primary objects you will use are:
Each of these objects has various properties and methods. By setting these properties and calling the methods, you can take advantage of CHARTrunner functionality without actually running CHARTrunner. These two objects will allow you to do the most common integration tasks. For example, from within your own program or macro you can:
When CHARTrunner is installed, an ActiveX file named PqCr20.DLL is installed and registered. It defines many of the CHARTrunner objects you will use in your SDK application. If you are programming in Visual Basic or in VBA (within Word, Excel or Access) you typically add a reference to the CHARTrunner 2.0 Application DLL in your project so that you will be able to use the CHARTrunner objects in your program.
To add this reference in Visual Basic 5.0 or 6.0, open the Projects > References pull-down menu. In Excel, you do this by selecting Tools > Macro > Visual Basic Editor (to launch VB) and then selecting Tools > References from the VB menu. In either case, you need to check the box next to the CHARTrunner 2.0 Application DLL reference.
In addition to needing a reference to the CHARTrunner 2.0 Application DLL, many SDK projects will also need to create references to PQCM4.DLL, PQDM4.DLL, or one of the other CHARTrunner ActiveX components listed below. Fortunately, Visual Basic 6.0 will typically inform you when your project needs to add a reference and will offer to add the correct reference for you. In Visual Studio .NET, when you add an interop reference to the CHARTrunner 2.0 Application DLL, interop references to all the other CHARTrunner ActiveX components will be created automatically.
The Advanced button on the Data definition tab displays the Advanced Row Selection dialog (shown below). This gives you options for controlling how records (rows) are selected from your data source. There are three general things you can do using Advanced Row Selection:
The properties of the PQCrDef chart definition class that control Advanced Row Selection are shown below to the right of the Advanced Row Selection dialog. The PQCrDef.bArsEnabled property controls whether Advanced Row Selection is enabled or not. The checkbox to the left of the Advanced button on the data definition tab (when editing a chart definition in CHARTrunner) corresponds to this bArsEnabled property.
If a chart definition includes an Advanced Row Selection, Advanced settings in use will appear in blue below the Advanced button on the Data definition tab.
Sample SDK program code is available in these folders of the CHARTrunner Software Developer's Kit:
Some examples of SDK coding follow.
In this first example, we show you how to get started in the Excel VB editor. The rest of the examples will be source code only and assume you can get into an appropriate development environment such as VBA in Excel, VB 6, or one of the others mentioned above.
Start Excel. From the pull down menu, select Tools/Macro/Macros. You should see a dialog as shown above.
Give the macro a name by typing DrawFirstChart. Next, click on the Create button. You should see something like the picture below (you will put your source code between the Sub and the End Sub):
From the pull down menu, select Tools > References. Put a check next to CHARTrunner 2.0 Application DLL so that the properties and methods of the objects contained in that ActiveX DLL are available to your scripting code.
Enter the following code for our first example:
Sub DrawFirstChart()
Dim bRtn As Boolean
Dim bShowModal As Boolean
Dim sFile As String
Dim sMsg As String
Dim oApp As New CHARTrunner20.Application
sFile = "C:\Program Files\PQ Systems\CHARTrunner 2.0\SampleCharts\Sample 01.crf"
' Show the chart window modally. In some scripting environments you must display the chart
' in a modal window or an error will occur. In others, you can use a non-modal chart
' window if you like.
bShowModal = True
bRtn = oApp.DisplayChart(sFile, bShowModal)
If Not bRtn Then
MsgBox oApp.sLastError, vbExclamation
End If
End Sub 'DrawFirstChart'
Once you have entered this source code try to run the macro. Do this by pressing the F5 (run) key while in the Excel VB editor. A CHARTrunner chart should be displayed in a modal chart window. If a chart is not displayed, you will need to debug the source code! Remember, if you installed CHARTrunner in a different folder, you will have to modify this source code accordingly.
Let’s discuss this example source code. The first five lines that start with Dim declare some variables that will be used in the macro. The most important variable is oApp. This variable is declared using the New keyword which ensures that a new instance of this object will be created. In this case, the object is a CHARTrunner20.Application object. This is the primary object you will use when programming CHARTrunner.
The next line sets the variable sFile to the full path to one of the CHARTrunner sample charts.
This line of code is where all the action is:
bRtn = oApp.DisplayChart(sFile, bShowModal)
We are using a method of the CHARTrunner20.Application object that is identified by the variable oApp. The method is the DisplayChart method. The DisplayChart method requires only the first argument, the remaining arguments are optional and assume a default value if they are not supplied. In this case, the required argument is sFile, a string variable that contains the full path to a CHARTrunner chart definition file. The DisplayChart method returns a Boolean value, either True or False, that indicates whether the method completed successfully. By checking the variable bRtn, we can ask (in the next line of code) if the DisplayChart method was successful or not. When DisplayChart fails (returns False) the oApp.sLastError property can be checked to see what went wrong.
When you use the DisplayChart method, the chart is generated from fresh data. This means that the data source, as setup in the chart definition file, is queried for the most recent data, then the chart is displayed. The same is true for printing a chart or saving a chart image.
Your first lesson in programming CHARTrunner is now complete. Although this example was done using VBA within Excel¸ the same general steps can be used in the other development environments.
Additionally, an Excel spreadsheet (ChartRunner.xls) containing example code can be found in the ..\Excel folder within the CHARTrunner Software Developer's Kit. The example (above) used "early binding" that required you to create a reference to the CHARTrunner 2.0 Application DLL using Tools/References. The sample code in ChartRunner.xls is setup by default to use "late binding" which does not require that a reference to CHARTrunner 2.0 Application DLL be established. The code shown in Example 1 below also uses "late binding" since that is the only binding method supported by Windows Script Host.
Microsoft® Windows® Script Host (WSH) is a language-independent scripting host for ActiveX® scripting engines. You can download Windows Scripting host from the Microsoft web site. The WSH allows you to create and run programs that use ActiveX components such as the CHARTrunner components.
If you remember batch files from the days of MS-DOS, you will recognize that the WSH gives you similar capability within the Windows environment. You can use a simple text editor such as the Windows Notepad to create files containing scripts. These scripts can instantiate ActiveX objects and then use their properties and methods. Currently, WSH scripts can be written in either VBScript or JavaScript.
Once a script has been written, it is saved either as a .vbs file or a .js file. The .vbs file is for VBScript ; the .js file is for JavaScript. Double clicking on either of these files in the Windows Explorer will run the scripts. Listed below are two WSH scripts that will display a CHARTrunner chart. They do the same thing that we did in the previous Excel example. You can use Notepad to create and try these scripts or you can look at these examples in the CHARTrunner Software Developer's Kit folders. You will notice slight syntax differences from the Excel example, but conceptually these scripts do the same thing.
Dim bRtn
Dim bShowModal
Dim sChartDefPath
Dim oApp
Set oApp = CreateObject("CHARTrunner20.Application")
' Get the path to one of the sample charts.
sChartDefPath = oApp.sAppPath & "\SampleCharts\Sample 01.crf"
' Windows Scripting Host requires that the chart display form be modal.
bShowModal = True
' Ask the Application object to display the chart.
bRtn = oApp.DisplayChart( sChartDefPath, bShowModal)
' If DisplayChart failed, then display the error message.
If bRtn = False Then
MsgBox oApp.sLastError
End If
The first four lines declare some variables. Note that these variables do not have a type, such as string or Boolean. In WSH, all variables are variants. Next, we create a CHARTrunner20.Application object by calling the CreateObject method. Notice that bShowModal is set to True. This tells the DisplayChart method to display the chart form modally. WSH does not allow the display of non-modal chart windows. Not setting this will cause the DisplayChart method to fail and return False. The rest of the code is similar to the previous Excel example. Next, we’ll look at the same script in JavaScript.
// Example Windows Script Host JavaScript - CHARTrunner // Declare some variables. var bShowModal var bRtn var sChartDefPath var sMsg var oApp // Get the path to one of the sample charts. sChartDefPath = oApp.sAppPath + "\\SampleCharts\\Sample 01.crf"; // Windows Scripting Host requires that the chart display form be modal. bShowModal = true; // Ask the Application object to display the chart. bRtn = oApp.DisplayChart(sChartDefPath, bShowModal); // If DisplayChart failed, then display the error message. if (bRtn != true) WScript.Echo(oApp.sLastError);
The JavaScript syntax is slightly different from VBScript but the example script does the same thing as the previous one. Notice that we set bShowModal to true. When using WSH, you must set this to true to display a chart. Another difference to notice is the use of double \\ characters in the file name. Any line beginning with // is a comment in JavaScript.
The remaining examples will each demonstrate a different capability. These examples are from the ChRunExamples.vbp sample project in the Visual Basic folder where you installed your CHARTrunner Software Developer's Kit.
Sub SaveChartAsImage()
Dim bRtn As Boolean
Dim sChartDefPath As String
Dim sOutputFile As String
Dim sMsg As String
Dim oApp As New CHARTrunner20.Application
' The path to the chart definition.
sChartDefPath = PathJoin(oApp.sAppPath, "SampleCharts\Sample 01.crf")
' The image file to be created. Not specifying a path here
' usually results in the file being saved in the "My Documents" folder.
sOutputFile = PathJoin(G_sOutputFolder, "Sample 01.jpg")
' Bitmap size is 640x480 pixels, Image type = eCrImageJpg
' Other valid image types are eCrImageBmp or eCrImageWmf.
bRtn = oApp.SaveChartAsImage(sChartDefPath, sOutputFile, _
eCrImageJpg, 640, 480)
If Not bRtn Then
MsgBox oApp.sLastError
End If
End Sub 'SaveChartAsImage
When you use the DisplayChart method, the chart is displayed in its own window with its own pull down menus. While the chart is displayed, the user may interact with the chart in various ways. There are options for editing the chart definition, computing control limits, and modifying the style definition used with the chart. If you would prefer not to allow the end users to make these changes, then set the bReadOnly parameter to True for the DisplayChart method. Here is an example:
Sub DisplayChartInReadOnlyMode()
Dim bRtn As Boolean
Dim bShowModal As Boolean
Dim bReadOnly As Boolean
Dim sChartDefPath As String
Dim sMsg As String
Dim oApp As New CHARTrunner20.Application
' The path to the chart definition.
sChartDefPath = PathJoin(oApp.sAppPath, "SampleCharts\Sample 02.crf")
' This is what makes it impossible to edit the chart definition.
bReadOnly = True
' Display the chart window modally.
bShowModal = True
' Display the chart.
bRtn = oApp.DisplayChart(sChartDefPath, bShowModal, bReadOnly)
If Not bRtn Then
MsgBox oApp.sLastError
End If
End Sub 'DisplayChartInReadOnlyMode
When you call the PrintChart method, the only required argument is sChartPath, the full path to the chart definition file. The other arguments are optional. If bPrintSep is True, each child chart in a Multi-chart will print on its own page. If bShowPrintDialog is True, the printer dialog will be displayed.
The following example uses a CHARTrunner workspace file instead of a regular chart definition file. CHARTrunner deals with three types of chart definitions. 1) Regular chart definitions that have a .CRF file extension, 2) Multi-chart definitions that contain a list of 1 or more regular charts and have a .CRM file extension, and 3) Chart workspace definitions that also contain a list of 1 or more regular charts and have a .CRW file extension. The difference between multi-charts and workspaces is that a multi-chart is viewed or printed with all charts in a single window or on a single page; for chart workspaces, each chart is viewed in its own window or printed on its own page.
Sub PrintChartsInWorkspace()
Dim bRtn As Boolean
Dim bShowPrintDialog As Boolean
Dim bPrintSep As Boolean
Dim sChartPath As String
Dim sMsg As String
Dim sPrinterName As String
Dim oApp As New CHARTrunner20.Application
' The path to the chart definition.
sChartPath = PathJoin(oApp.sAppPath, "SampleCharts\Sample workspace.crw")
' Let the user interact with the printer dialog.
bShowPrintDialog = True
' Do not print each child chart of a Multi-chart on a separate page.
bPrintSep = False
' Use the default Windows printer.
sPrinterName = ""
' Print the chart.
bRtn = oApp.PrintChart(sChartPath, bShowPrintDialog, bPrintSep, sPrinterName)
If Not bRtn Then
MsgBox oApp.sLastError
End If
End Sub 'PrintChartsInWorkspace'
A chart workspace is defined to contain several regular charts. You may want to generate an image file of each chart in the workspace. In the following example, we generate JPEG images. Remember that you also have options to generate BMP images, PNG images, or EMF images. EMF is Enhanced Windows Metafile.
Sub SaveWorkspaceAsImages()
Dim bRtn As Boolean
Dim lWidth As Long
Dim lHeight As Long
Dim sChartPath As String
Dim sDestFolder As String
Dim sMsg As String
Dim oApp As New CHARTrunner20.Application
' The path to the sample workspace chart.
sChartPath = PathJoin(oApp.sAppPath, "SampleCharts\Sample workspace.crw")
' Where to create the chart images.
sDestFolder = "C:\MyChartImages"
' Size of the created images.
lWidth = 640
lHeight = 480
' Create the workspace images as JPEGs.
bRtn = oApp.SaveWorkspaceImages(sChartPath, eCrImageJpg, lWidth, lHeight, sDestFolder)
If Not bRtn Then
MsgBox oApp.sLastError
End If
End Sub 'SaveWorkspaceAsImages
In the method SaveWorkspaceImages used above, there are five arguments:
sChartPath, eImageType, lChartWidth, lChartHeight, sFolder
Only the first argument, sChartPath, is required. All the other arguments are optional. If you do not set them, CHARTrunner will use default values. The following line of code would also have worked in the previous example:
bRtn = oApp.SaveWorkspaceImages(sChartPath)
In CHARTrunner, each chart has a property that specifies the default path to use when saving a chart image. You can see this on the Misc. tab of the chart definition form. If you do not specify the last argument (sFolder), when you call SaveWorkspaceImages, each chart will save its image into the path specified on the Misc. tab of the chart definition form. If you do specify a folder and it does not exist on your computer, an error will occur.
Up to this point, all of the examples have used only the CHARTrunner20.Application object. This is a commonly used object in CHARTrunner but there are others. The next example uses the PqCrDef object, which is a chart definition object. Like all other objects, it has various properties you can set and various methods you can call. Think of a PqCrDef object as an in-memory instance of a complete CHARTrunner chart definition.
In this example we use an existing chart definition but change some of its settings before displaying the chart.
Sub ChangeChartProperties()
Dim bRtn As Boolean
Dim sPath As String
Dim sMsg As String
Dim oApp As New CHARTrunner20.Application
Dim oCrDef As PQCrDef
' Create an instance of a PqCrDef.
Set oCrDef = oApp.CreatePqObject(eObjPQCrDef)
' Start with the Sample 03 chart definition.
sPath = PathJoin(oApp.sAppPath, "SampleCharts\Sample 03.crf")
' Read the chart definition.
bRtn = oCrDef.ReadChartDefinition(sPath, eCrPathFull)
If Not bRtn Then
sMsg = "Error opening chart file: " & oCrDef.sLastError
MsgBox sMsg, vbExclamation
End If
' Next, we'll change some of the chart settings, like titles.
oCrDef.sBottomTitle(1, 1) = "Titles Changed Via Code"
oCrDef.sBottomTitleFont(1, 1) = "Arial,14,B,L"
oCrDef.sBottomTitle(1, 3) = "Date: " & Date & " Time: " & Time
oCrDef.sBottomTitle(3, 2) = "Is this cool,,, or what?"
oCrDef.sBottomTitleFont(3, 2) = "Arial,16,I,C"
' And grid lines.
oCrDef.ControlChartSettings.bDrawVerticalGrid = True
oCrDef.ControlChartSettings.bDrawHorizontalGrid = True
' Set the chart to compute temporary control limits based
' on all the data.
oCrDef.eLimitOption = eCrTempLimits
' Display the chart.
bRtn = oCrDef.Display(bShowModal:=True)
If Not bRtn Then
MsgBox "Error in Display: " & oCrDef.sLastError
End If
MyExit:
Exit Sub
End Sub 'ChangeChartProperties'
In this example, almost all the work used the PqCrDef object. The CHARTrunner20.Application object was used only to create the instance of the PqCrDef object, which we named oCrDef in the example. Notice that the PqCrDef object has a Display method. This is similar to the DisplayChart method of the CHARTrunner20.Application object that we have been using in the previous examples. The PqCrDef object has many properties; we set only a few of them in this example. For details about the other properties and methods of the PQCrDef object, see the Reference Manual.
The previous examples assume that someone has used CHARTrunner to create and save a chart definition file. You may need to create charts on-the-fly from within other systems you are running. The next example creates and displays a chart using only macro or script code. The chart is never read from nor saved to the disk. Rather, it is created by code and used only in memory.
First, we will review basic information about how CHARTrunner gets to data. Every CHARTrunner chart has a data source and a data definition. The data source describes the overall type and location of the data. For example, Microsoft Excel, Access, and SQL Server are all valid data sources. If you are using Excel, a path like C:\data\datasheet.xls describes the specific location of the data. The data definition is a more detailed description of the specific data (within the data source) that you want to include in the chart. For example, if your data source is an Access database named C:\mydata.mdb, the data definition could name a specific table within mydata.mdb such as a table named DailyRuns. Now, the DailyRuns table will contain several different columns of data. The data definition also tells CHARTrunner which specific columns you want to include for analysis in this chart.
The example shown below also demonstrates how to specify the size and position of the chart display window via code. Notice how the oChartSize object along with oCrDef.ChartPositionList are used.
To create a chart from scratch, you will be working with many properties and methods of the PqCrDef object. See the Reference Manual for more details on the PQCrDef properties and methods that are used in this example.
Sub CreateChartWithSizeAndPosition()
' Create the chart definition via code, specify the size and position of the
' chart display window, and display the chart.
On Error GoTo ErrorHandler
Dim bRtn As Boolean
Dim j As Integer
Dim sPath As String
Dim sMsg As String
Dim sStyleName As String
Dim oCrDef As PQCrDef
Dim oColDef As PQCrColDef
Dim oChartSize As New PQCrChartSize
Dim oApp As New CHARTrunner20.Application
' Assume success.
bRtn = True
Screen.MousePointer = vbHourglass
' Create an instance of a chart definition object.
Set oCrDef = oApp.CreatePqObject(eObjPQCrDef)
' Give the chart a name.
oCrDef.sChartName = "My Sample Chart"
' Set the type of chart we want.
oCrDef.eChartType = eCrTypeXbarRange
' Tell the chart object to use DAO/JET as the data source.
oCrDef.eDataSourceType = eCrDataSourceTypeJet
' Tell the chart object we will be using an Access database.
oCrDef.eJetDataType = eCrJetDataAccess
' Use the sample database installed with CHARTrunner.
oCrDef.sDataSourceFile = PathJoin(oApp.sAppPath, "SampleData\SampleAccess2K.mdb")
' Tell oCrDef that we will select records from a table.
oCrDef.eRecSelectType = eCrRecSetTable
' Tell it the name of the table.
oCrDef.sTableName = "GapDimA"
' Next, we add a PqCrColDef object to the oCrDef's cColDefs collection
' for each column we want to reference in the chart.
' We setup the same oColDef object several times adding it to the
' oCrDef.cCols collection each time.
' First the identifier.
Set oColDef = oApp.CreatePqObject(eObjPQCrColDef)
oColDef.sName = "Date"
oColDef.eTreatColAs = eCrColId
oCrDef.cColDefs.Add oColDef
Set oColDef = Nothing
' Then the 'measurements'.
For j = 1 To 3
Set oColDef = oApp.CreatePqObject(eObjPQCrColDef)
oColDef.sName = "Gap" & CStr(j)
oColDef.eTreatColAs = eCrColMeasurement
oCrDef.cColDefs.Add oColDef
Set oColDef = Nothing
Next j
' Set the chart to compute temporary limits.
oCrDef.eLimitOption = eCrTempLimits
' Label the x-axis with one of the identifiers.
oCrDef.ControlChartSettings.eLabelWith = eLineChartLabelTypeID
' Use this column for the x-axis identifier label.
oCrDef.ControlChartSettings.sChartLabelColumn = "Date"
' Label every subgroup on the x-axis.
oCrDef.ControlChartSettings.eHowToLabelXAxis = eLineChartLabelAll
' Use the 'default' style for control charts.
sStyleName = "Default control chart style"
' Read the chart style definition into this chart object. When building
' the chart definition in code you must read the desired style definition
' into the chart definition object. When using oCrDef.ReadChartDefinition()
' to read a chart definition file the chart style specified by the chart
' definition file is automatically read into the chart object.
bRtn = oCrDef.ReadStyleDefinition(sStyleName, eCrPathRelative)
' Set some control chart settings.
oCrDef.ControlChartSettings.bDrawDataLines = True
oCrDef.ControlChartSettings.bDrawMarkers = True
oCrDef.ControlChartSettings.bShowChartTitle = True
' Put some titles on the chart.
oCrDef.sTopTitle(1, 2) = "This chart created from SCRATCH using Visual Basic code."
oCrDef.sTopTitleFont(1, 2) = "Arial,18,B,C"
oCrDef.sBottomTitle(1, 2) = "The chart position and size were specified by the code."
oCrDef.sBottomTitleFont(1, 2) = "Arial,16,B,C"
' Specify the size and position for the chart display window using the
' oChartSize object that was instantiated earlier in this routine. This
' object lets you specify chart size and position information either in
' normalized units or twips. The normalized units represent the chart window
' size and position in normalized percent of the screen. The units are
' (FractionalPercent * 10000), i.e. 40% ==> (0.40 * 10000) = 4000.
#If True Then
' Make the chart 60% of screen height and width and in the upper right corner
' of the screen using the "normalized units" properties.
oChartSize.lNormTop = 0
oChartSize.lNormLeft = 4000
oChartSize.lNormHeight = 6000
oChartSize.lNormWidth = 6000
#Else
' Alternatively, you could use this code which sets the size and position
' of the chart as above, i.e. 60% of screen height and width and in the upper
' right corner of the screen, but uses "absolute" units of Twips. Setting one of
' these "absolute" properties results in the corresponding "normalized" property
' being changed to the appropriate value, i.e. the value for .lTop is actually
' stored as a normalized number in the .lNormTop property.
oChartSize.lTop = 0
oChartSize.lLeft = Screen.Width * 0.4
oChartSize.lHeight = Screen.Height * 0.6
oChartSize.lWidth = Screen.Width * 0.6
#End If
' Specify whether or not to maximize the chart window.
oChartSize.bMaximized = False
' Give the chart size/position object to the chart definition so that it can
' properly size and position the chart display window on the screen. For a
' normal chart (CRF) or Multi-Chart (CRM) the first position in the list, i.e.
' ChartPositionList(1), contains the size/position information for the chart.
' A new PQCrDef object will have ChartPositionList(1) equal to Nothing, which
' defaults to a centered chart occupying 80% of the screen height and width.
Set oCrDef.ChartPositionList(1) = oChartSize
' Display the chart. The chart size/position specified by oCrDef.ChartPositionList(1)
' defines the size and position of the chart display window on the screen.
bRtn = oCrDef.Display(bShowModal:=True, bReadOnly:=False)
If Not bRtn Then
MsgBox oCrDef.sLastError, vbExclamation
End If
MyExit:
Screen.MousePointer = vbNormal
Exit Sub
ErrorHandler:
MsgBox Err.Description & " - " & Err.Number, vbExclamation
Resume MyExit
End Sub 'CreateChartWithSizeAndPosition
This is a VBScript example (Sample9.vbs) that demonstrates using an in-memory ADO recordset to chart data that has been generated or gathered by your program. The chart definition is built in code. The chart is either displayed or an image file is generated, then PQCrDef.GetDataObject() is used to get a reference to the measurement data object (oMD) for the chart. The data object allows access to all the statistics for the chart.
' VBScript - Sample9.vbs
MsgBox "This example builds a chart from scratch using VBScript and a PQCrDef object." _
& vbCrLf & vbCrLf _
& "In addition, an in-memory ADO recordset is created as the source of data for" _
& " the chart, and after the chart is rendered some statistics from the chart are" _
& " displayed to demonstrate using PQCrDef.GetDataObject() to get the chart's data" _
& " object."
Call Process
' ===========================================================
' Process the chart.
' ===========================================================
Sub Process()
Const SGNUM = "SubgroupNumber"
Const MEAS1 = "Measurement1"
' Since we are using late binding, we have to define some constants
' in place of Enum values we would have gotten with early binding.
Const adInteger = 3
Const adSingle = 4
Const eUseAll = 0
Const eCrColId = 11
Const eCrColMeasurement = 14
Const eCrTypeInd = 8
Const eCrDataSourceTypeAdo = 3
Const eObjPQCrDef = 1
Const eObjPQCrColDef = 3
Const eCrImageJpg = 1 ' JPEG image.
Const eCrImageBmp = 2 ' Bitmap image.
Const eCrImageEmf = 3 ' Windows enhanced metafile.
Const eCrImagePng = 4 ' Portable network graphic.
Dim bRtn
Dim bGenerateImage
Dim j
Dim sFileName
Dim sMsg
Dim oRs
Dim oApp ' CHARTrunner20.Application.
Dim oCrDef ' PQCrDef.
Dim oLocColDef ' PQCrColDef.
Dim oMD ' PQDM4.PQMeasurementData
' The output image file.
sFileName = "C:\TestImage.jpg"
sMsg = "You can either generate the chart image file (" & sFileName _
& ") or display the chart in a window." _
& vbCrLf & vbCrLf _
& "Click Yes to generate the chart image file, No to display the chart, or Cancel"
j = MsgBox( sMsg, vbYesNoCancel, "What to do?")
Select Case j
Case vbYes
bGenerateImage = True
Case vbNo
bGenerateImage = False
Case Else
' Cancel.
Exit Sub
End Select
' Whether to display the chart.
bDisplayChart = Not bGenerateImage
Set oApp = CreateObject("CHARTrunner20.Application")
If oApp Is Nothing Then
MsgBox "Cannot create CHARTrunner20.Application"
Exit Sub
End If
Set oRs = CreateObject("ADODB.Recordset")
If oRs Is Nothing Then
MsgBox "Cannot create ADODB.Recordset"
Exit Sub
End If
' Create a small, simple, in-memory recordset to use for the chart.
oRs.Fields.Append SGNUM, adInteger
oRs.Fields.Append MEAS1, adSingle
' Open the recordset.
oRs.Open
' Add 10 records with random data for our chart.
Randomize
For j = 1 To 10
oRs.AddNew
oRs.Fields(SGNUM) = j
oRs.Fields(MEAS1) = 10 * Rnd(1)
oRs.Update
Next
' Have the CHARTrunner Application object instantiate
' a chart definition object for us.
Set oCrDef = oApp.CreatePqObject(eObjPQCrDef)
' Bail out if we are not running 1.6.68 or higher which has support
' for the oCrDef.bKeepDataObjects property.
On Error Resume Next
bRtn = oCrDef.bKeepDataObjects
If Err.Number <> 0 Then
MsgBox "CHARTrunner 1.6.68 or higher is required for this demo."
Exit Sub
End If
On Error GoTo 0
' Get the chart definition from the default chart.
Call oCrDef.SetToDefaults()
' Specify some chart titles.
oCrDef.sTopTitle(1, 2) = "Chart built from code using PQCrDef object with an in-memory external recordset"
oCrDef.sTopTitleFont(1, 2) = "Arial,12,B,C"
oCrDef.sTopTitle(2, 2) = "~"
oCrDef.sTopTitle(3, 1) = "Grand Mean=@MEAN"
oCrDef.sTopTitleFont(3, 1) = "Arial,14,B,L"
oCrDef.sTopTitle(3, 2) = "Sigma=@SIGMA"
oCrDef.sTopTitleFont(3, 2) = "Arial,14,B,C"
oCrDef.sTopTitle(3, 3) = "Kurtosis=@KURT"
oCrDef.sTopTitleFont(3, 3) = "Arial,14,B,R"
oCrDef.sTopTitle(4, 2) = "~"
oCrDef.sBottomTitle(2, 2) = "~"
oCrDef.sBottomTitle(3, 2) = "http://www.chartrunner.com"
oCrDef.sBottomTitleFont(3, 2) = "Arial,14,B,C"
' Tell the chart how many decimal places to use for chart statistics.
oCrDef.iControlChartDecimalDigits = 5
' Tell the chart definition object to use the in-memory recordset we just created.
Call oCrDef.UseExternalRecordset(oRs)
' Tell the chart definition object we want an Individuals chart.
oCrDef.eChartType = eCrTypeInd
' Tell the chart to use "all" the records.
oCrDef.eResultRecSelectType = eUseAll
' Create "Column Definition" object #1.
Set oLocColDef = oApp.CreatePqObject(eObjPQCrColDef)
' Set the ColumnDef properties for the first field in our recordset.
oLocColDef.eDataSourceType = eCrDataSourceTypeAdo
oLocColDef.eColType = adInteger
oLocColDef.sName = SGNUM
oLocColDef.eTreatColAs = eCrColId
oLocColDef.bUniqueID = True
' Add the ColumnDef to the chart's collection of ColumnDefs
oCrDef.cColDefs.Add oLocColDef, "1"
' Create "Column Definition" object #2.
Set oLocColDef = oApp.CreatePqObject(eObjPQCrColDef)
' Set the ColumnDef properties for the second field in our recordset.
oLocColDef.eDataSourceType = eCrDataSourceTypeAdo
oLocColDef.eColType = adSingle
oLocColDef.sName = MEAS1
oLocColDef.eTreatColAs = eCrColMeasurement
' Add the ColumnDef to the chart's collection of ColumnDefs
oCrDef.cColDefs.Add oLocColDef, "2"
' Give the chart a name.
oCrDef.sChartName = "Sample9.vbs"
' Set the default output image filename, so that oCrDef.Validate()
' does not complain.
oCrDef.sImageFileName = sFileName
' Validate the chart definition using the Validate() method.
bRtn = oCrDef.Validate()
If bRtn = False Then
' We have a validation error, so display the error message.
MsgBox "Validation Error: " & oCrDef.sLastError
Exit Sub
End If
' Tell the chart to retain the measurement data object after the chart
' image file is created. This allows us to use oCrDef.GetDataObject()
' later to get a reference to the data object that was used during the
' call to oCrDef.SaveChartAsImage().
oCrDef.bKeepDataObjects = True
If bGenerateImage Then
' Have the chart form generate a chart image.
bRtn = oCrDef.SaveChartAsImage(eCrImageJpg, sFileName, 800, 600)
If bRtn Then
MsgBox "Image File Generated = " & sFileName
Else
MsgBox oCrDef.sLastError
Exit Sub
End If
End If
If bDisplayChart Then
' Display the chart.
bRtn = oCrDef.Display( True)
If bRtn = False Then
' We have an error, so display the error message.
MsgBox oCrDef.sLastError
Exit Sub
End If
End If
' Get a reference to the measurement data object for this chart.
Set oMD = oCrDef.GetDataObject()
If oMD Is Nothing Then
MsgBox "GetDataObject() Failed: " & oCrDef.sLastError
Exit Sub
End If
' Demonstrate some of the properties you can get from the
' measurement data object.
sMsg = "Statistics from the chart's measurement data object:" _
& vbCrLf & vbCrLf _
& "Grand Mean = " & oMD.GrandMean & vbCrLf _
& "Minimum = " & oMD.Minimum & vbCrLf _
& "Maximum = " & oMD.Maximum & vbCrLf _
& "Sigma = " & oMD.Sigma & vbCrLf _
& "Kurtosis = " & oMD.Kurtosis
MsgBox sMsg
End Sub 'Process'
The code for this example is taken from the CrControlExample VB.NET project in the "Visual Studio.NET\Charting Control" folder. In this example, an instance of the CHARTrunner Charting Control named PqCrChart1 has been placed on a form. This code fragment is taken from the TextChanged event for the txtChartDef TextBox control. When the user enters a valid path to a chart definition the code displays a preview of the chart in the PqCrChart1 control.
Dim bRtn As Boolean
Try
btnDisplay.Enabled = DoesFileExist(txtChartDef.Text)
If btnDisplay.Enabled Then
' The user has specified a chart definition path that exists, so
' attempt to show the user a preview of the chart.
Cursor.Current = Cursors.WaitCursor
' Draw the chart preview in the PqCrChart1 control.
bRtn = PqCrChart1.DrawChartExt(txtChartDef.Text)
Cursor.Current = Cursors.Arrow
If bRtn Then
' The chart displayed OK, so make it visible.
PqCrChart1.Visible = True
Else
If Not PqCrChart1.bCanceledByUser Then
' The user didn't cancel on the Query Parameters form, so
' we must have an error condition we need to show the user.
MsgBox(PqCrChart1.sLastError, MsgBoxStyle.Exclamation)
End If
PqCrChart1.Visible = False
End If
Else
' Hide the chart preview in the PqCrChart1 control.
PqCrChart1.Visible = False
End If
Catch ex As Exception
MsgBox(ex.Message, MsgBoxStyle.Exclamation)
' Hide the chart preview in the PqCrChart1 control.
PqCrChart1.Visible = False
End Try
As you can see from the code shown above, it is very simple to draw a chart using the charting control. The call to PqCrChart1.DrawChartExt(txtChartDef.Text) causes the charting control to internally instantiate a PQCrDef chart definition object, read the chart definition specified by txtChartDef.Text into the PQCrDef object, and then draw the chart defined by the PQCrDef object in the charting control.
Alternatively, if your program already has a PQCrDef object called oCrDef that contains a chart defintion that you want to display in the charting control, you could do so by using the PqCrChart1.DrawChart( oCrDef) method.
If the chart definition uses query parameters and the user clicks Cancel on the query parameters form then PqCrChart1.bCanceledByUser will be True, in which case we don't want to display the error message in PqCrChart1.sLastError.
You can see a VB6 version of the code shown above in the ChRunOcxExample.vbp project located in the "Visual Basic\Charting Control" folder.
This is a VBScript example (clipCHART1.vbs) that uses CHARTrunner20.Application.CreateClipChart to create a clipCHART from an existing chart definition file. See also the JavaScript example clipCHART1.js.
Dim oApp
Dim bRtn
Dim sChartDefPath
Dim sClipChartFile
Dim sMsg
' You will need to change the location of the output clipCHART file if
' you do not have a C:\Temp folder.
sClipChartFile = "C:\Temp\clipCHART1.ccf"
sMsg = "This VBScript example will create the clipCHART file " _
+ sClipChartFile + " using the Application.CreateClipChart method."
MsgBox sMsg
Set oApp = CreateObject("CHARTRunner20.Application")
' Get the path to one of the sample charts.
sChartDefPath = oApp.sAppPath & "\SampleCharts\Sample 01.crf"
' Here is the function prototype for CreateClipChart():
'
' Public Function CreateClipChart(ByVal sChartDefPath As String, _
' ByVal sClipChartFile As String)) As Boolean
'
' Parameters:
' sChartDefPath is the full path to a CHARTrunner chart definition.
'
' sClipChartFile is the full path for the generated clipCHART file.
bRtn = oApp.CreateClipChart(sChartDefPath, sClipChartFile)
If bRtn = False Then
' We have an error, so display the error message.
MsgBox oApp.sLastError
Else
MsgBox "Output clipCHART file = " & sClipChartFile
End If
Here is a JavaScript example (clipCHART2.js) that uses PQCrDef.CreateClipChart to create a clipCHART from the chart definition contained in a PQCrDef object. Also see the corresponding VBScript example clipCHART2.vbs.
// Declare some variables.
var bRtn
var sChartDefPath
var sClipChartPath
var sMsg
var oApp
var oCrDef
// Define some CHARTrunner Enum values since we don't have early binding.
var eObjPQCrDef = 1;
var eCrPathFull = 1;
// You will need to change the location of the output image file if
// you do not have a C:\Temp folder.
sClipChartPath = "C:\\Temp\\clipCHART2.ccf";
sMsg = "This JavaScript example will create the clipCHART file "
+ sClipChartFile + " using the PQCrDef.CreateClipChart method.";
WScript.Echo(sMsg);
// Create the CHARTrunner Application object.
oApp = WScript.CreateObject("CHARTRunner20.Application");
// Create the Chart Definition object.
oCrDef = oApp.CreatePQObject(eObjPQCrDef);
// Get the path to one of the sample charts.
sChartDefPath = oApp.sAppPath + "\\SampleCharts\\Sample 01.crf";
// Read the Chart Definition file.
bRtn = oCrDef.ReadChartDefinition(sChartDefPath, eCrPathFull);
if (bRtn != true)
WScript.Echo(oCrDef.sLastError);
// Specify some chart titles.
oCrDef.sTopTitle(1, 2) = "Example clipCHART Created in JavaScript using PQCrDef.CreateClipChart";
oCrDef.sTopTitleFont(1, 2) = "Arial,14,B,C";
oCrDef.sTopTitle(2, 2) = "~";
// Here is the function prototype for SaveChartAsClipChart():
//
// Public Function SaveChartAsClipChart(ByVal sClipChartPath As String) As Boolean
//
// Parameters:
// sClipChartPath is the full path for the generated clipCHART file.
// Save the chart as a clipCHART.
bRtn = oCrDef.CreateClipChart( sClipChartPath);
if (bRtn != true)
WScript.Echo(oCrDef.sLastError);
else
WScript.Echo("Output clipCHART file = " + sClipChartFile);