|
CHARTrunner 1.6 Software Developer's Kit |
Reference Manual |
|
Date: 09-Jan-2004 |
This document applies only to CHARTrunner version 1.6. 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, 98, ME, NT, 2000 and XP. 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.
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.
CHARTrunner was created by PQ Systems, Inc. the developers of SQCpack™. To learn more about PQ Systems, visit:
To learn more about CHARTrunner, visit:
The new features in CHARTrunner 1.6 are: parameter
queries, statistics in chart titles, chart review, and support for Cusum
charts.
Refer to the ReadMe.htm
file that accompanies CHARTrunner for an up-to-date list of new features.
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. Please review the complete terms of the license agreement at:
http://www.chartrunner.com/license.htm
Click here for the Programmer's Guide which provides an overview of programming using the CHARTrunner ActiveX components. Click here for the most recent version on the web.
Returns a Boolean indicating if the CHARTrunner16.Application object could find the appropriate license file.
Data type
Boolean
bNoChartNameInWindowTitle Property
Returns or sets whether the chart name will be displayed as part of the chart window title.
Data type
Boolean
Returns or sets whether "Black and White" printing mode is enabled. On some black & white printers lines and text are not printed visibly due to the way the printer driver converts colors to the black and white space. This boolean forces all chart lines and text to be printed as Black. Fills still behave as expected and show up as a shade of gray.
Data type
Boolean
Returns or sets whether the progress bar will be displayed as part of a lengthy charting operation.
Data type
Boolean
Returns or sets whether message boxes will be displayed when errors occur. Set this to True to suppress messages boxes. This is useful for unattended or batch processing where you do not want a single error to put up a message box and prevent the rest of the batch from processing.
Data type
Boolean
Default value
False
A collection of PqCrFileDesc objects. Each member describes a single CHARTrunner style file contained in the styles folder. This collection is filled by calling the RefreshStylesCollection method. The property sStyleFolder specifies the drive/path to the folder containing the chart styles. This collection will contain as many members as there are style files in the style folder. Each member of the collection describes a control chart style, histogram style, or pareto chart style.
Data type
Collection
Default value
Empty
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDesc As PQCrFileDesc
Call oChRunApp.RefreshStylesCollection
For Each oCrDesc In oChRunApp.cStyles
MsgBox "The Style name is " & oCrDesc.sName
Next oCrDesc
This is an AppEnv object. It contains properties and methods related to the environment in which CHARTrunner is operating. Among other things, this object handles language localization and registry information management.
Data type
AppEnv (object)
fPrintMarginBottom
fPrintMarginLeft
fPrintMarginRight
fPrintMarginTop
Properties
These properties return or set the printer margins to be used when printing charts. These will default to values set by users of the CHARTrunner application.
Data type
Single
This property is returns a PqStrList object which contains a list of strings, one string for each .CRF chart definition in the current chart folder. Each string entry contains the full path to the .CRF chart definition file. This list is populated by CHARTrunner16.Application.GetPeerChartLists().
Data type
PqStrList (object)
This property is returns a PqStrList object which contains a list of strings, one string for each .CRM Multi-chart definition in the current chart folder. Each string entry contains the full path to the .CRM Multi-chart definition file. This list is populated by CHARTrunner16.Application.GetPeerChartLists().
Data type
PqStrList (object)
An SqcOOC object. This object contains a list of out-of-control test rules that will be used to evaluate data for out-of-control conditions. These rules are used when any control chart is created that has the ControlChartSettings.bDoOOCTests property set to True. The SqcOOC object contains a list of tests. The tests take the following form:
1 Point beyond limits
7 Points ascending
2 of 3 above 2 sigma
Data type
SqcOOC
Remarks
In CHARTrunner the user can choose Setup | Out-of-control tests to set the active set of test rules; these rules are stored in the CHARTrunner16.Application.oOocTests property. In CHARTrunner 1.1 this set of test rules was applied to all control charts when the chart was drawn.
Starting in CHARTrunner 1.5 the active set of test rules is copied into the PQCrDef.oOocTests property when a PQCrDef object is created. Also, the Boolean CHARTrunner16.Application.Preferences.bUseMasterOocTests is copied into PQCrDef.bUseMasterOocTests when a PQCrDef object is created.
If PQCrDef.bUseMasterOocTests is False then the test rules stored in PQCrDef.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn. If a chart definition file doesn't contain any test rules (e.g. a CHARTrunner 1.1 chart definition) then the rules from CHARTrunner16.Application.oOocTests will apply to the chart (because these rules were copied into PQCrDef.oOocTests when the PQCrDef object was created and were never replaced by rules from the chart definition file).
If PQCrDef.bUseMasterOocTests is True then the test rules stored in CHARTrunner16.Application.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn.
See also: CHARTrunner16.Application.ReadOOCFile, PQCrDef.ReadOOCFile.
Example
Dim bRtn As Boolean
Dim j As Integer
Dim oChRunApp As New CHARTrunner16.Application
' Display the current set of test rules.
For j = 1 To oChRunApp.oOocTests.Tests.Count
MsgBox oChRunApp.oOocTests.Tests(j)
Next j
' Load a new set of test rules from a disk file. This will replace any existing
' tests with those from the file.
bRtn = oChRunApp.ReadOOCFile("C:\MyRules\OocTests1.ooc")
' Add a new test rule to those we loaded from the file.
oChRunApp.oOocTests.Tests.Append "2 of 3 above 2 sigma"
This is a PqCrPrefs object which contains various preference properties that affect how the CHARTrunner application operates.
The Preferences.bUseMasterOocTests is new in version 1.5.
Data type
PqCrPrefs (object)
Sets or returns the full path to the file containing templates for ADO data sources. Used primarily by the CHARTrunner application and not generally useful in scripting applications.
Data type
String
Sets or returns the full path to the folder where
CHARTrunner is installed.
The CHARTrunner16.Application object needs access to certain files located in
the folder where CHARTrunner is installed. Setting this property to a
folder path causes the sSysDataFolder, sStyleFolder,
sLogFile, sHelpFileChartRunner,
sHelpFileAdvisor, and sHelpFileFormulas
properties to be updated if they have not already been set.
Data type
String
Sets or returns the full path to the current folder containing the chart definition files.
Data type
String
Returns the current height of the screen in twips as reported by Screen.Height.
Data type
Integer
Returns the current width of the screen in twips as reported by Screen.Width.
Data type
Integer
This read-only property returns the current hex Locale ID that is in effect
Data type
String
Sets or returns a string that is the name of the printer that will be used (by default) for printing charts. If this is an empty string, the Windows default printer will be used. Note that the printer dialog box will allow the user to override this printer before charts are printed.
Data type
String
Default value
An empty string or the name of the printer selected by the CHARTrunner user.
sHelpFileAdvisor
sHelpFileChartRunner
sHelpFileFormulas
sHelpFileTutorial Properties
These properties return or set the full path for the four primary on-line help files used by the CHARTrunner application. These default to the help files as installed with CHARTrunner and generally are never changed.
Data type
String
Many CHARTrunner16.Application methods return a Boolean value. When the return value of False indicates an error, this property may be examined for a description of the error. This is a read-only property.
Data type
String
A read-only property that returns the full path to the CHARTrunner license file.
Data type
String
A read-only property that returns only the filename portion of the CHARTrunner license file.
Data type
String
Sets or returns the full path to the log file. If the property bSilentMode is True, no message boxes will be displayed when errors occur. However, if errors occur, the messages will be written into the file specified by this property.
Data type
String
Sets or returns the current hex Locale ID that is stored in LocaleID in the CHARTrunner section of the Registry. In CHARTrunner if the current language is set to a language other than U.S. English then this property holds the Locale ID of the specified language.
Data type
String
Sets or returns the full path to the folder that contains the chart style files. Setting this property results in a call to RefreshStylesCollection which causes the collection cStyleFiles to be filled with one member for each chart style file found in the folder. A chart style file contains information about colors, fonts, and styles that will be used when charts are drawn.
Data type
String
Sets or returns the full path to the folder that is the SysData folder for the current CHARTrunner installation. This folder is used to store out-of-control test files, default chart files, and other system level files used by CHARTrunner. This property will default to the correct folder and is generally not changed by scripting code.
Data type
String
Displays a dialog box allowing the user to browse for and select CHARTrunner files. If the user selects one or more files, the full path to the file is returned to the caller as an element of the returned array.
Syntax
Public Function BrowseForCrFile(ByVal bShowCRF As
Boolean, _
ByVal bShowCRM As Boolean, ByVal bShowCRW As Boolean) _
As String()
Returns
An array of String where each element in the array is a selected CHARTrunner file.
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim sFileName() As String
sFileName() = oChRunApp.BrowseForCrFile(True, True, True)
Remarks
If bShowCRF is True then regular Chart files will be shown. If bShowCRM is True then MultiChart files will be shown. If bShowCRW is True then Workspace files will be shown.
Check to see if the CHARTrunner license is valid.
Syntax
Public Function CheckLicense(Optional ByVal sLicFile as String = “”) as Boolean
Remarks
Note that sLicFile is an optional argument that defaults to an empty string. If present it specifies the full path to the license file.
Returns
True = Success.
False = Failure (see sLastError).
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim bRtn As Boolean
bRtn = oChRunApp.CheckLicense()
Close all currently open chart windows.
Syntax
Public Sub CloseAllCharts()
Create the clipCHART file specified by sCcFile from the chart definition file specified by sCrFile.
Syntax
Function CreateClipChart(ByVal sCrFile As String, ByVal sCcFile As String) As Boolean
Remarks
See also: PQCrDef.CreateClipChart
Returns
True = Success.
False = Failure (see sLastError).
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim bRtn As Boolean
bRtn = oChRunApp.CreateClipChart("C:\MyCharts\MyChart.crf", "C:\ClipCharts\MyChart.ccf")
This method is used to create various CHARTrunner objects and returns a reference to the created object. Many objects used by the CHARTrunner16.Application may not be created directly. Instead, use this method to instantiate these objects.
Syntax
Public Function CreatePqObject(eObjType As eCrObjType) As Object
Returns
An object reference to an object of the type requested.
Nothing = Failure (see sLastError)
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDef as PQCrDef
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
Remarks
A table of valid object types follows. Notice that the object variable being Set is usually declared as an object of the type you are asking to create.
|
eObjPQCrDef |
1 |
Chart definition object |
|
eObjPQCrFileDesc |
2 |
File descriptor object |
|
eObjPQCrColDef |
3 |
Column definition object |
|
eObjPQCrLimit |
4 |
Control limit object |
|
eObjPQRsViewer |
5 |
Recordset viewer object |
|
eObjPQMRUFileMenu |
6 |
Recently used menu object |
|
eSqcControlChartStyle |
7 |
Control chart style object |
|
eSqcHistogramStyle |
8 |
Histogram chart style object |
|
eSqcParetoStyle |
9 |
Pareto chart style object |
|
eSqcOOC |
10 |
Out-of-control test object |
|
eSqcOOCMgr |
11 |
Out-of-control test manager object |
Displays a CHARTrunner chart from an existing chart definition file. sFileName specifies the full path to an existing CHARTrunner chart definition file.
Syntax
Public Function DisplayChart(ByVal sFileName As String, _
Optional ByVal bShowModal As Boolean = False, _
Optional ByVal bReadOnly As Boolean = False, _
Optional ByVal bAllowRefresh As Boolean = True, _
Optional vTagVariant As Variant) As Boolean
When the chart is displayed the user may use the Edit | Chart definition menu to alter the definition of the chart. They may also highlight subgroups and compute new sets of control limits. If you prefer that the user only view the chart and not have the ability to change it, set the bReadOnly argument to True. Some scripting environments do not allow a non-modal form to be displayed. If this is the case, you must set the bShowModal argument to True. If you do not want to allow the user to Refresh (F5) the chart then set bAllowRefresh to False. If vTagVariant is specified then it will be used to set the PQCrDef.TagVariant property.
Returns
True = Success.
False = Failure (see sLastError).
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim bRtn as Boolean
bRtn = oChRunApp.DisplayChart("C:\MyCharts\MyChart.crf")
If Not bRtn then
Msgbox oChRunApp.sLastError
End if
DisplayChartFromClipboard Method
Displays a CHARTrunner chart using data currently on the Windows clipboard.
Syntax
Public Function DisplayChartFromClipboard(ByVal
eChartType As eCrChartType) _
As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim bRtn as Boolean
bRtn = oChRunApp.DisplayChartChartFromClipboard(eCrTypeXbar)
If Not bRtn then
Msgbox oChRunApp.sLastError
End if
Remarks
This method is sensitive to the type and format of data currently on the clipboard. As an example, for charts requiring a subgroup size greater than 1 (such as an X-bar chart which plots an average value), this method expects to find at least 2 columns of data on the clipboard. Generally, this method expects data to be in a format consistent with the format used when you copy a range of data from Excel to the clipboard. For a Pareto chart, this method expects a column of data containing category names and optionally, a column of data containing counts (for the categories).
This method is generally used to give the user a quick or summary sense of a data set. If you require specific customizing in the chart, use other methods such as CHARTrunner16.Application.DisplayChart or PQCrDef.Display.
CHARTrunner is installed with several on-line help files. Use this method to launch the on-line help file of your choice.
Syntax
Public Function DisplayHelp(eHelpFileType As
CrHelpFileTypeEnum, _
hWndParent As Long, eCmdType As HelpCommandTypeEnum, _
Optional lTopic As Long = 0) As Boolean
Public Enum CrHelpFileTypeEnum
eCrHelpFileChartRunner = 1
eCrHelpFileAdvisor
eCrHelpFileFormulas
eCrHelpFileClipChart
eCrHelpFileTutorial
End Enum 'CrHelpFileTypeEnum'
Public Enum HelpCommandTypeEnum
eHlpCmdTypeContext = cdlHelpContext
eHlpCmdTypeQuit = cdlHelpQuit
eHlpCmdTypeIndex = cdlHelpIndex
eHlpCmdTypeContents = cdlHelpContents
eHlpCmdTypeHelpOnHelp = cdlHelpHelpOnHelp
eHlpCmdTypeSetIndex = cdlHelpSetIndex
eHlpCmdTypeSetContents = cdlHelpSetContents
eHlpCmdTypeSetContextPopup = cdlHelpContextPopup
eHlpCmdTypeForceFile = cdlHelpForceFile
eHlpCmdTypeHelpKey = cdlHelpKey
eHlpCmdTypeCommandHelp = cdlHelpCommandHelp
eHlpCmdTypePartialKey = cdlHelpPartialKey
End Enum 'HelpCommandTypeEnum'
hWndParent is the window handle of the parent window that launches the help.
Returns
True = Success.
False = Failure (see sLastError).
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim bRtn as Boolean
bRtn = oChRunApp.DisplayHelp(eCrHelpFileChartRunner, Me.hWnd, eHlpCmdTypeContents)
This method displays and lets the user interact with a form for modifying the chart definition specified by sFileName.
Syntax
Public Function EditChartDefinition(ByVal sFileName As
String, _
ByRef bDidFileChange As Variant) As Boolean
Remarks
If bDidFileChange is True upon return from the method, it means that the user did change the chart definition and that the new definition was saved to disk. This means that the existing file was overwritten with the changes made by the user.
Returns
True = Success.
False = Failure (see sLastError).
Generate an image file based on an existing CHARTrunner chart definition file. The image will be either a Windows bitmap file (*.bmp), a Windows enhanced metafile (*.emf) or a JPEG compressed image file (*.jpg). The sCrFileName argument specifies the full path to an existing CHARTrunner chart (*.crf) or multi-chart (*.crm) definition file.
Syntax
Public Function GenerateChartImageFile(ByVal sCrFileName
As String, _
Optional ByVal sOutputImageFileName As String = "", _
Optional ByVal eType As eCrImageType =
0, _
Optional ByVal lWidthInPixels As Long = 0, _
Optional ByVal lHeightInPixels As Long = 0) As Boolean
Remarks
The only required argument to this method is sCrFileName. All the other arguments have corresponding settings stored in the chart definition file itself. If the caller does not specify these arguments, the contents of the file will determine the settings used for the optional arguments.
Returns
True = Success.
False = Failure (see sLastError).
This method displays a dialog box that provides information about a chart image file that a user wants to generate. The caller must provide arguments for file name, image type, width, and height. Returns True if user specifies all valid information and clicks OK. Returns False if the user cancels or if information is invalid or incomplete. This method changes the contents of its arguments. If the method returns True, the arguments will contain the user selections from the dialog box.
Syntax
Public Function GetImageInfoFromUser(sFileName As String,
_
eType As eCrImageType, lWidthInPixels
As Long, _
lHeightInPixels As Long) As Boolean
Remarks
Can be used before calling GenerateChartImageFile to allow the programmer to override parameters such as image type and image size that are stored in the chart definition file.
Returns
True = Success.
False = Failure (see sLastError).
Syntax
Public Sub GetPeerChartLists(ByVal eWhichList As PeerListEnum, _
ByVal sChartFolder As String)
Remarks
This method fills CHARTrunner16.Application.oChartListCRF and/or CHARTrunner16.Application.oChartListCRM with a list of the available peer charts that are found in the chart folder specified by sChartFolder. The parameter eWhichList specifies which list (or both) to be filled.
Print the CHARTrunner chart specified by sFile. sFile is the only required argument.
Syntax
Public Function PrintChart(ByVal sFileName As String, _
Optional ByVal bPrintWithDialog As Boolean = True, _
Optional ByVal bPrnMCSep As Boolean = False, _
Optional ByVal sPrinterName As String) As Boolean
Parameters
| sFileName | Full path to the chart definition file to print |
| bPrintWithDialog | Show a printer dialog? |
| bPrnMCSep | Print MultiChart children on separate pages? |
| sPrinterName | Name of the printer to send the output to |
Remarks
Note that like the DisplayChart and GenerateChartImageFile methods, this method will query the chart's data source and create a fresh chart based on the current data. If this method returns False, the caller should check the contents of sLastError for a description of the problem.
Returns
True = Success.
False = Failure (see sLastError).
This method reads an out-of-control test definition file and stores the rules into the CHARTrunner16.Application.oOocTests object. An out-of-control test file is a text file containing out-of-control test rules. Here is an example of an out-of-control test rule:
1 Point beyond limits
This means that if a data point is beyond the control limits (on a control chart) it will be considered an “out-of-control” data point. Several example OOC files can be found in the SysData folder where CHARTrunner is installed.
Syntax
Public Function ReadOOCFile(sFileName As String) As Boolean
Remarks
If sFileName contains valid out-of-control test rules, they will be read and will become the current out-of-control tests stored in CHARTrunner16.Application.oOocTests.
In CHARTrunner the user can choose Setup | Out-of-control tests to set the active set of test rules; these rules are stored in the CHARTrunner16.Application.oOocTests property. In CHARTrunner 1.1 this set of test rules was applied to all control charts when the chart was drawn.
Starting in CHARTrunner 1.5 the active set of test rules is copied into the PQCrDef.oOocTests property when a PQCrDef object is created. Also, the Boolean CHARTrunner16.Application.Preferences.bUseMasterOocTests is copied into PQCrDef.bUseMasterOocTests when a PQCrDef object is created.
If PQCrDef.bUseMasterOocTests is False then the test rules stored in PQCrDef.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn. If a chart definition file doesn't contain any test rules (e.g. a CHARTrunner 1.1 chart definition) then the rules from CHARTrunner16.Application.oOocTests will apply to the chart (because these rules were copied into PQCrDef.oOocTests when the PQCrDef object was created and were never replaced by rules from the chart definition file).
If PQCrDef.bUseMasterOocTests is True then the test rules stored in CHARTrunner16.Application.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn.
See also: PQCrDef.ReadOOCFile.
Returns
True = Success.
False = Failure (see sLastError).
RefreshStylesCollection Method
Syntax
Public Sub RefreshStylesCollection()
Remarks
This method fills the cStyleFiles collection. cStyleFiles contains one member for each CHARTrunner style definition file found in the current working chart folder (as specified by the sChartFolder property) or the system styles folder (as specified by the sStyleFolder property). The members of this collection are PQCrFileDesc file descriptor objects. Each PQCrFileDesc member has the following properties:
|
PQCrFileDesc Object |
|
| sName | The name of the style file. |
| sDescription | The description for the style file. |
| sChartType | String version of what type of chart or style this is. |
| sFileName | Full path to the chart or style file the definition was loaded from. |
| sLastError | String describing the last error condition for the object. |
| eFileType | What type of CHARTrunner definition is this? |
| eChartType | Enum version of what type of chart or style this is. |
This method generates a chart image file for each chart defined in a chart workspace definition (*.crw). A chart workspace is a collection of one or more CHARTrunner charts.
Syntax
Public Function SaveWorkspaceImages(ByVal sWsFile As String, _
Optional ByVal eImageType As eCrImageType
= 0, _
Optional ByVal lChartWidth As Long = 0, _
Optional ByVal lChartHeight As Long = 0, _
Optional ByVal sFolder As String = "") As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Remarks
As with DisplayChart and PrintChart, this method will query the data source for each chart and generate a fresh chart based on current data each time it is called. If you create image files for a number of charts on a regular basis, this method allows you to automate and/or streamline this task by handling all the charts in the workspace with one call.
Setup the application to localize for the locale
specified by sLocaleID.
Syntax
Function SetLocale(Optional ByVal sLocaleID As String = "") As Boolean
Returns
True = Success (see sHexLocaleID for the current Hex
Locale ID).
False = Failure (see sLastError).
Remarks
Normally sLocaleID specifies a locale ID that
looks like "080A" (a standard hex Windows LCID) or "PQHC" (a
PQ special ID). If the LLD file that corresponds to sLocaleID is
not found, then no localization will be done and the active language defaults to
U.S. English.
However, sLocaleID can also specify one of these special values:
|
"" |
Do not localize. |
|
"=" |
Localize based upon the current windows Locale ID. |
|
"@" |
Localize based upon LocaleID in the Registry. |
|
"!" |
Localize in "Test String Width" mode. |
Open the specified sLanguageDB language database
and use the specified sLanguageColumn column for the foreign language.
Setup the Env.lg localization engine object as appropriate for the chosen
language.
If either sLanguageDB or sLanguageColumn are zero length strings
then the application will use the native language (U.S. English) because
the current language database (if any) will be closed.
Syntax
Public Function SetupLanguage(sLanguageDB As String,
sLanguageColumn As String) _
As Boolean
Returns
True = Success.
False = Failure.
This event is raised from the Form_Unload event of a frmChartDisplay form that is used to display a chart in a window. A reference to the frmChartDisplay is passed as the oFrmChart argument. If Cancel is set to a non-zero value the unload of the form will be canceled.
This event is supported in version 1.6.68 and higher.
Syntax
Public Event ChartUnload(oFrmChart As Object, Cancel As Integer)
Example
Private WithEvents oChRunApp As New CHARTrunner16.Application
Public Sub DrawMyChart()
Dim bRtn as Boolean
bRtn = oChRunApp.DisplayChart("C:\MyCharts\MyChart.crf")
If Not bRtn then
Msgbox oChRunApp.sLastError
End if
End Sub 'DrawMyChart'
Private Sub oChRunApp_ChartUnload(oFrmChart As Object, Cancel As Integer)
MsgBox "The chart " & oFrmChart.mCrDef.sChartName & " is unloading."
End Sub 'oChRunApp_ChartUnload'
A PQCrDef is a chart definition object. It is the in-memory representation of a CHARTrunner chart definition file. The following describe the properties and methods of the PQCrDef object.
This property sets or returns a Boolean indicating if the chart window should always be on top of other windows.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether automatic scaling of the scattergram chart's X-axis is performed.
Data type
Boolean
Default value
False
bAutoYAxisControlChart Property
This property sets or returns a Boolean that determines whether automatic scaling of the control chart's Y-axis is performed.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether automatic scaling of the histogram chart's Y-axis is performed.
Data type
Boolean
Default value
False
bAutoYAxisMultiLineChart Property
This property sets or returns a Boolean that determines whether automatic scaling of the Multi-line chart's Y-axis is performed.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether automatic scaling of the scattergram chart's Y-axis is performed.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether the connection to the chart's data source is closed immediately after the chart data has been fetched. This property corresponds to the Close data source after drawing chart checkbox on the Misc tab of the chart definition form in CHARTrunner.
Setting this property to True will eliminate the problem
where CHARTrunner locks a data source (such as Excel or a text file)
while the chart is displayed so that other users are unable to open or edit the
data source. It also corrects the problem where changes made to the chart data
are not seen in the chart after the chart is refreshed. Even though CHARTrunner
opens all data sources for "read-only" this results in a lock on some
data sources which may prevent other users from opening the data source once CHARTrunner
has displayed the chart. With bCloseDbAfter set to True CHARTrunner will
open the data source only long enough to get the chart data and then the data
source is closed. If the chart has a refresh interval, it will re-open the data
source only when needed to refresh and then close it immediately.
This makes the Excel chart refresh problem much less frequent. However, it might
still occur if CHARTrunner and another user try to access the data source
at exactly the same time. For customers who are charting Excel data best results
will be obtained when the Close data source after drawing chart
option is checked in the CHARTrunner chart definition and the Excel
spreadsheet is setup in Shared Workbook mode.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether the current chart style definition (contained in oControlChartStyle, oHistogramStyle or oParetoStyle) is embedded into the XML chart definition (returned by the sXmlDefinition property). When bEmbedStyleDef is False the XML chart definition contains only the name of the chart style that is to be used with the chart.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether the current filter definition (as defined by the FilterDef property) is applied to the chart.
Data type
Boolean
Default value
False
This is a read-only property. A PQCrDef contains several properties that together define the data that will be used for this chart. This property returns True if the database for this PQCrDef is currently open. Scripting code which instantiates a PQCrDef object will not directly open the database. Instead, other methods such as GetChartRecordset will open the database internally.
Data type
Boolean
Default value
False
This property sets or returns a Boolean that determines whether to retain the data object(s) used by the PrintChart() or GenerateChartImageFile() method. If True, then a call to GetDataObject() allows you to get a reference to the data object(s) used by the last PrintChart() or GenerateChartImageFile() method. The data object for a chart gives you access to statistics such as Grand Mean, Sigma and Kurtosis for that chart.
This property is available in version 1.6.68 and higher. See the VBScript example file Sample9.vbs for an example of using GetDataObject() to get access to chart statistics.
Data type
Boolean
Default value
False
bNoChartNameInWindowTitle Property
Returns or sets whether the chart name will be displayed as part of the chart window title.
Data type
Boolean
This property sets or returns a Boolean indicating if this PQCrDef (which describes a Pareto chart) should count records where the category name is missing or blank.
Data type
Boolean
bParetoIncludeMissingBar Property
This feature sets or returns a Boolean indicating whether this PQCrDef (which describes a Pareto chart) should display a bar on the chart indicating how many records contained a blank or missing category.
Data type
Boolean
bParetoShowTotalsChart Property
This property sets or returns a Boolean that determines whether a Pareto Totals Chart is shown.
Data type
Boolean
If this PQCrDef is a Pareto chart, this property sets or returns a value indicating that the Pareto bars should be displayed in Descending order. See also: eParOrderBy
Data type
Boolean
This property sets or returns a Boolean indicating whether to prompt the user to update the parameter query values prior to rendering the chart. See also: cQueryParameters
Data type
Boolean
This property sets or returns a value indicating whether the user should be prompted for user name and password when opening the database associated with this chart definition. This is generally an issue when the source database requires all users to login with a name and password. See also: sAdoOdbcConnect, sAdoOdbcUser, and sAdoOdbcPassword.
Data type
Boolean
This Read-Only property indicates whether the cSrcColDefs
collection has been filled via the GetSrcColDefsCollection
method.
Data type
Boolean
Charts may be defined with 10 rows and 3 columns of titles both above and below the chart. If you want these titles to be formatted with grid lines between the rows and columns, set this to True; otherwise, set it to False.
Data type
Boolean
Use this property to return or set a Boolean indicating whether the chart definition may be edited while the chart is displayed.
Data type
Boolean
Use this property to return or set a value indicating whether the Advanced Row Selection properties should be used. The Advanced button on the data definition tab (when running CHARTrunner) displays a dialog allowing the user to check or un-check this option. See also: eEveryNRowsUse, eFormSgsGroupingUnit,eRowSelectOption, lEveryNRowsN, lEveryNRowsFirstLastX, sColChangeColName.
Data type
Boolean
Use this command to return or set a value indicating whether SQL statements should surround table names and column names with brackets. For example:
If True: SELECT * FROM [Data Table]
If False: SELECT * FROM Data Table
This property works in conjunction with the sSQLBracketLeft and sSQLBracketRight properties, which specify the character that should be used for bracketing. Note that these will almost always be the [ and ] characters. If your table names and/or column names contain spaces, this must usually be set to True.
Data type
Boolean
bUseExternalRecordset Property
This property sets or returns a Boolean that determines whether an external (i.e. programmer supplied) recordset is being used to fetch the chart's data. The programmer should typically not attempt to set this property directly but rather should use the UseExternalRecordset method to setup the chart definition to use an external recordset.
Data type
Boolean
This property sets or returns a Boolean that determines which set of Out-of-Control tests are used when a chart is drawn for this PQCrDef object.
Remarks
In CHARTrunner the user can choose Setup | Out-of-control tests to set the active set of test rules; these rules are stored in the CHARTrunner16.Application.oOocTests property. In CHARTrunner 1.1 this set of test rules was applied to all control charts when the chart was drawn.
Starting in CHARTrunner 1.5 the active set of test rules is copied into the PQCrDef.oOocTests property when a PQCrDef object is created. Also, the Boolean CHARTrunner16.Application.Preferences.bUseMasterOocTests is copied into PQCrDef.bUseMasterOocTests when a PQCrDef object is created.
If PQCrDef.bUseMasterOocTests is False then the test rules stored in PQCrDef.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn. If a chart definition file doesn't contain any test rules (e.g. a CHARTrunner 1.1 chart definition) then the rules from CHARTrunner16.Application.oOocTests will apply to the chart (because these rules were copied into PQCrDef.oOocTests when the PQCrDef object was created and were never replaced by rules from the chart definition file).
If PQCrDef.bUseMasterOocTests is True then the test rules stored in CHARTrunner16.Application.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn.
Data type
Boolean
A collection of PqCrColDef objects, each member of this collection describes a column from the data source recordset and information about how CHARTrunner should treat or use this column when creating the chart. When running CHARTrunner, this collection is created based on information the user specifies on the Data definition tab. This collection is highly coupled to the data source definition for the chart. In other words, each member of this collection must describe a column from the current data source recordset.
Data type
Collection
Example 1
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDef As PQCrDef
Dim oCrCol As PQCrColDef
' Assume you have a data table with 2 columns
' named: Date, DownTimeMinutes
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Create the first column object.
Set oCrCol = oChRunApp.CreatePqObject(eObjPQCrColDef)
' Set some properties of the column object.
oCrCol.sName = "Date"
oCrCol.eTreatColAs = eCrColId
' Add it to the charts collection of column definition objects.
oCrDef.cColDefs.Add oCrCol
' Create the second column object.
Set oCrCol = oChRunApp.CreatePqObject(eObjPQCrColDef)
' Set some properties of the column object.
oCrCol.sName = "DownTimeMinutes"
oCrCol.eTreatColAs = eCrColMeasurement
' Add it to the charts collection of column definition objects.
oCrDef.cColDefs.Add oCrCol
Example 2
Dim bRtn As Boolean
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDef As PQCrDef
Dim oCrCol As PQCrColDef
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Read a chart definition file.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Machine1.crf", eCrPathFull)
' Look at each member of the cColDefs collection.
For Each oCrCol In oCrDef.cColDefs
MsgBox "Column name is: " & oCrCol.sName
Next
A collection of ADODB.Parameter objects. Each member of this collection describes an input query parameter that is used with the parameterized query associated with the data source for the chart.
Only the name and value properties of the ADODB.Parameter object are used to store the name and value of the query parameter.
If bPromptForParameters is True then CHARTrunner will prompt the user to enter query parameter values when the data source for the chart is opened.
Data type
Collection
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDef As PQCrDef
Dim oParm as ADODB.Parameter
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Read a chart definition file that uses a parameterized query.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\MyQueryParmChart.crf", eCrPathFull)
' Look at each member of the cQueryParameters collection.
For Each oParm In oCrDef.cQueryParameters
MsgBox "Query parameter name is: " & oParm.name _
& ", value is: " & oParm.value
Next
This property returns a reference to a collection of PqCrColDef objects that describe the current chart data source. This collection is created as a result of calling the GetSrcColDefsCollection method. See also: bSrcColDefsCurrent
Data type
Collection
List of PQCrChartSize objects that describe the chart
window size and position for each chart of a Workspace. If the chart is a
MultiChart or normal single chart then ChartPositionList(1) contains the
information for the single chart window. When a chart display windows is closed
the current chart window size and position information is written back to the
parent chart definition file.
Data type
PqObjList (object)
This property is returns a PqStrList object which contains a list of strings, one string for each child chart that is a member of a MultiChart or Workspace. Each string entry contains the full path to the child CHARTrunner chart definition file. This property is only relevant for MultiCharts and Workspaces. A PqStrList is similar to a collection in that it has a .Count property.
Data type
PqStrList (object)
Example
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDef As PQCrDef
Dim bRtn As Boolean
Dim j As Integer
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Open a chart definition file that is a multi-chart.
bRtn = oCrDef.ReadChartDefinition("C:\Charts\MyMultiChart.crm", eCrPathFull)
For j = 1 To oCrDef.ChartFileList.Count
MsgBox "The file for child chart " & j & " is " & oCrDef.ChildChartList(j)
Next j
Each member of this collection of PQCrLimitSet objects is a set of control limits. This collection is relevant only if the chart is defined as a control chart. A set of control limits has a name and several values that represent the limits to be used on the chart. Note that the chart type determines what limits exist. For example, a set of limits for an X-bar and Range chart contains upper, center, and lower limit values for both the X-bar chart and the Range chart. A chart may be defined with zero or more sets of control limits in this collection. This collection is filled by calling the ReadChartDefinition method.
Data type
Collection (of PqCrLimitSet objects)
ControlChartSettings
HistogramSettings
MlChartSettings
ParetoChartSettings
ScatterChartSettings
Properties
Each of these properties represents a different type of settings object. Depending on the type of chart, only one of these objects will contain properties that are relevant to the current chart. For example, if the chart is an X-bar chart, only the ControlChartSettings object will be used; if the chart is a Pareto chart, only the ParetoChartSettings will be used. These are documented together because their use is identical for all charts; the only difference being which object is used.
There are many properties contained by each of these settings objects. The properties have explanatory names. See PQCM_Interface.html for more detailed information about the public properties of each type of settings object.
Each type of settings object shares the overall design of being a "bag" where chart settings are stored. Each chart setting is identified in the "bag" by its enum identifier. For instance, the enum identifier for a PqControlChartSettings object is the pqEnumChartSetting type. Many of the most frequently used chart settings are explicitly exposed via a property of the settings object, such as oCrDef.ControlChartSettings.bDoOOCTests. All the chart settings in the "bag" are accessible via the Prop property as shown in the example below.
Data Type
ControlChartSettings is a PqControlChartSettings object.
HistogramSettings is a PQHistogramChartSettings object.
MlChartSettings is a PqControlChartSettings object (Multi-line charts use this)
ParetoChartSettings is a PQCategoryChartSettings object.
ScatterChartSettings is a PQScattergramChartSettings object.
Example
Dim bRtn As Boolean
Dim oChRunApp As New CHARTrunner16.Application
Dim oCrDef As PQCrDef
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Open a chart definition file.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Sample 01.crf", eCrPathFull)
' Change some chart settings via properties of the ControlChartSettings object.
oCrDef.ControlChartSettings.bDoOOCTests = False
oCrDef.ControlChartSettings.bDrawDataPoints = False
oCrDef.ControlChartSettings.bDrawVerticalGrid = True
oCrDef.ControlChartSettings.bDrawHorizontalGrid = True
' Change the same chart settings via the Prop property of the ControlChartSettings object.
oCrDef.ControlChartSettings.Prop(eControlChart_bDoOOCTests) = False
oCrDef.ControlChartSettings.Prop(eControlChart_bDrawDataPoints) = False
oCrDef.ControlChartSettings.Prop(eControlChart_bDrawVerticalGrid) = True
oCrDef.ControlChartSettings.Prop(eControlChart_bDrawHorizontalGrid) = True
Sets or returns the current chart type.
Data type
Remarks
Note that setting this property will automatically set the sChartType read-only property which will return a human readable version of the chart type. For example, if eChartType = eCrTypeXbarRange then sChartType will be “X-bar and Range”.
This property sets or returns the CHARTrunner file type.
A PQCrDef object may only be one of these file types:
Regular chart, ePqCrFileTypeChart, *.crf file extension.
Multi-chart, ePqCrFileTypeMultiChart, *.crm file extension.
Chart Workspace, ePqCrFileTypeWorkspace, *.crw file extension.
Data type
Public Enum ePqCrFileType
ePqCrFileTypeChart = 1
ePqCrFileTypeMultiChart = 2
ePqCrFileTypeWorkspace = 3
ePqCrFileTypeControlChartStyle = 4
ePqCrFileTypeHistogramStyle = 5
ePqCrFileTypeParetoStyle = 6
End Enum 'ePqCrFileType'
This property specifies the type of data source to be used for this chart.
Data type
If the chart is defined to use Advanced Row Selection, the user has the option of sampling rows from the data source. For example, the data may return 10,000 rows but you want a chart that examines every 100th row. Once the chart gets to the 100th row, this property specifies what to do when the chart gets to the 100th row. See also: bUseAdvRowSelection.
Data type
Public Enum eCrRowsToUse
eCrRowsToUseAll = 1
eCrRowsToUseFirstX = 2
eCrRowsToUseLastX = 3
End Enum 'eCrRowsToUse'
If the chart is defined to use Advanced Row Selection, i.e. bUseAdvRowSelection is True, the user has the option to form subgroups for the chart by grouping together 2 or more rows of data based on the recordset column specified by sColChangeColName. If the grouping column is a date or date/time column, subgroups may be formed based on the options listed below.
Data type
Public Enum eCrDateGroupingUnit
eCrDateGroupNone = 0
eCrDateGroupMinute = 1
eCrDateGroupHour = 2
eCrDateGroupDay = 3
eCrDateGroupWeek = 4
eCrDateGroupMonth = 5
eCrDateGroupQuarter = 6
eCrDateGroupYear = 7
End Enum 'eCrDateGroupingUnit'
This sets or returns a value indicating the type of graphic image that will be generated. See also: GenerateChartImageFile
Data type
When eDataSourceType is eCrDataSourceTypeJet this property specifies what type of Jet data source will be used to fetch chart data.
Data type
Public Enum CrJetDataTypeEnum
eCrJetDataNotUsed = 0
eCrJetDataAccess = 1
eCrJetDataExcel3 = 2
eCrJetDataExcel4 = 3
eCrJetDataExcel5 = 4 ' Excel 95 / 5.0.
eCrJetDataExcel8 = 5 ' Excel 97 / 8.0.
eCrJetDataText = 6
eCrJetDataParadox3 = 7
eCrJetDataParadox4 = 8
eCrJetDataParadox5 = 9
eCrJetDataDBase3 = 10
eCrJetDataDBase4 = 11
eCrJetDataDBase5 = 12
eCrJetDataLotus123_WK1 = 13
eCrJetDataLotus123_WK3 = 14
eCrJetDataLotus123_WK4 = 15
End Enum
For control charts, this property sets or returns a value indicating which control limit option should be used. If the option eCrAllSavedLimits is selected and there are no members in the cLimits collection, the chart will be displayed with no control limits.
Data type
Public Enum eCrLimitOption
eCrNoLimits = 0
eCrTempLimits = 1
eCrAllSavedLimits = 2
End Enum 'eCrLimitOption'
For Pareto charts, this property sets or returns a value describing if and how the number of bars appearing on a Pareto chart should be limited. If you set this to eCrLimitParBarsByCount and you set the sParBarCountCutoff property to 10, this results in a Pareto chart that includes only the top ten categories. If you set this to eCrLimitParBarsByPercent and you set the sParBarPerCentCutoff to “80%”, this results in a Pareto chart that inlcudes only the top 80% of the categories.
Data type
Public Enum eCrParBarLimitBy
eCrLimitParBarsByCount = 1
eCrLimitParBarsByPercent = 2
End Enum 'eCrParBarLimitBy'
How to arrange the child charts of a Multi-chart, e.g. tile horizontally or vertically. See also: iMultiChartColumns, iMultiChartRows.
Data type
FormArrangeConstants (only vbTileHorizontal and vbTileVertical are used)
Sets or returns a value indicating how data points should be plotted on a Multi-line chart. A Multi-line chart can display up to four separate data lines. Depending on how the data source is defined, the lines may plot either raw data values (eMultiLinePlotIndividuals), averages, ranges, or sigmas.
Data type
Public Enum eMultiLinePlotType
eMultiLinePlotNotSet = 0
eMultiLinePlotIndividuals = 1
eMultiLinePlotAverages = 2
eMultiLinePlotRanges = 3
eMultiLinePlotSigmas = 4
End Enum 'eMultiLinePlotType'
This is an AppEnv object. It contains properties and methods related to the environment in which CHARTrunner is operating. Among other things, this object manages language localization and registry information management.
Data type
AppEnv (object)
This property sets or returns a value indicating how the bars on a Pareto chart should be ordered. A s