|
CHARTrunner 1.7 Software Developer's Kit |
Reference Manual |
|
Date: 24-Feb-2004 |
This document applies only to CHARTrunner version 1.7. 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.
NOTE: Since CHARTrunner 1.7 contains no charting features that are not supported by version 1.6, there will not be a CHARTrunner-e 1.7 release. CHARTrunner-e 1.6 will fully support charts created by CHARTrunner 1.7.
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 major new feature in version 1.7 is CHARTrunner-XL, the Microsoft Excel Add-In that lets you use CHARTrunner from within Microsoft Excel. From an SDK perspective, only minor differences exist between 1.6 and 1.7. 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
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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.Application.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn.
See also: CHARTrunner17.Application.ReadOOCFile, PQCrDef.ReadOOCFile.
Example
Dim bRtn As Boolean
Dim j As Integer
Dim oChRunApp As New CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.Application.oChartListCRF and/or CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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.7.68 and higher.
Syntax
Public Event ChartUnload(oFrmChart As Object, Cancel As Integer)
Example
Private WithEvents oChRunApp As New CHARTrunner17.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 chart definition can be saved to disk. New in CHARTrunner 1.7.
When this property is True, both SaveChartDefinition() and SaveChartDefinitionAs() return True but do not actually save the chart definition to disk.
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
bExternalRecordsetAllowFiltering Property
This property sets or returns a Boolean that determines whether to allow the filter definition (if any) to be applied to an external recordset. New in CHARTrunner 1.7.
Data type
Boolean
Default value
True
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.7.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 standard Pareto chart orders the bars by value with the largest values appearing first. See also: bParOrderDescending.
Data type
pqEnumOrderBy (enumeration from PQDM3.DLL)
pqEnumOrderBy Enumeration Values
eOrderByNone = 0
eOrderByCategories = 1
eOrderByValues = 2
This property sets or returns a value indicating whether the chart should be printed in portrait or landscape orientation.
Data type
pqEnumPrintOrientation (enumeration from PQCM3.DLL)
pqEnumPrintOrientation Enumeration Values
ePrintOrientationNone = 0
ePrintOrientationPortrait = 1
ePrintOrientationLandscape = 2
Use this property set or return a value indicating the type of record selection that will be used. eCrRecSetTable is the most common setting and indicates that data is coming from a single table. Other options allow for named queries (also known as views), stored procedures, or custom queries. A custom query is a complete SQL select statement specifying what data to include in the chart. See also sSqlSelect, sTableName.
Data type
Public Enum eCrRecSelectType
eCrRecSetTable = 1
eCrRecSetNamedQuery = 2
eCrRecSetStoredProc = 3
eCrRecSetCustomQuery = 4
End Enum 'eCrRecSelectType'
Sets or returns a value indicating which records (after filtering, and after advanced row selection) should be included in the chart.
Data type
pqEnumUseRows (enumeration for PQDM3.DLL)
pqEnumUseRows Enumeration Values
eUseAll = 0
eUseFirstN = 1
eUseLastN = 2
Sets or returns a value indicating how rows should be selected when the bUseAdvRowSelection property is set to True, i.e. Advanced Row Selection is enabled.
If eCrRowSelectEveryNRows is selected then a subgroup is formed from all of the observations found on N consecutive rows of the recordset, where N is defined by lEveryNRowsN.
If eCrRowSelectEveryNRowsWhenColChanges is selected then a subgroup is formed from all of the observations found on all consecutive rows of the recordset where the column specified by sColChangeColName contains the same value. In other words, a new subgroup is formed whenever this column's value changes. If the column is a date or date/time column then eFormSgsGroupingUnit allows you to specify the units of the grouping inverval.
See also: eEveryNRowsUse, lEveryNRowsFirstLastX.
Data type
Public Enum eCrRowSelectOption
eCrRowSelectEveryNRows = 1
eCrRowSelectEveryNRowsWhenColChanges = 2
End Enum 'eCrRowSelectOption'
Returns the enum value indicating the validation error that occurred during the Validate or Validate2 method.
This property is available in version 1.7.68 and higher.
Data type
eCrDefInvalid
eCrDefInvalid Enumeration Values
There are a large number of error condition values in this enum. See the documentation for the CHARTrunner Interface.
The FilterDef property is a PqCrSqlFilterDef object. This object specifies filter conditions to use when the data source is a single table. Filtering allows you to select subsets of the data contained in a table. The PqCrSqlFilterDef mirrors the information on the Filter form that is displayed from the data definition tab when running CHARTrunner.
Data type
Read-Only child index for when this chart is a child of a Workspace or MultiChart. Always 1 for a CRF type of chart. Used to get the proper chart window size and position info from the chart definition. This gets set by ReadChartDefinition.
Data type
Integer
iControlChartDecimalDigits
iHistogramDecimalDigits
iScatterChartDecimalDigits
Properties
Use this property to set or return a value indicating how many decimal places should be used to display computed statistics on the chart.
Data type
Integer
Sets or returns the JPEG image quality value (1 - 99). The default value is 75. Setting this higher results in a better quality image with a larger image file size.
Data type
Integer
Sets or returns the number of columns to use when tiling Multi-charts. See also: eMultiChartTiling, iMultiChartRows.
Data type
Integer
Sets or returns the number of rows to use when tiling Multi-charts. See also: eMultiChartTiling, iMultiChartColumns.
Data type
Integer
This method returns the subgroup size (usually 1 to 40)
that a variables control chart will use based on the current definition of
columns as described by the cColDefs
collection. This method is useful only when the chart is defined as one of the variables
control charts. It represents the number of columns which are being treated as a
Measurement.
Data type
Integer
This property sets or returns a date/time value indicating the last time a chart (with a refresh interval) was refreshed.
Data type
Date
lDefaultImageHeight
lDefaultImageWidth Properties
This property sets or returns a value indicating the size (in pixels) of an image file created by the GenerateChartImagefile method.
Data type
Long
lEveryNRowsUseFirstLastX Property
This property sets or returns a value that represents X when the property eEveryNRowsUse is set to either eCrRowsToUseFirstX or eCrRowsToUseLastX. See also: bUseAdvRowSelection
Data type
Long
When the property eRowSelectOption is set to eCrRowSelectEveryN, this property sets or returns a value that represents N. See also: bUseAdvRowSelection
Data type
Long
This property sets or returns a value that represents the number of seconds in a refresh interval. If a chart with a refresh interval is displayed, it will be automatically refreshed (with any new data) each time this number of seconds passes.
Data type
Long
oControlChartStyle
oHistogramStyle
oParetoStyle Properties
Each of these properties represents a different type of chart style object. Depending on the type of chart, only one of these objects will contain properties that are relevant to the chart. For example, if the chart is a control chart, the oControlChartStyle object will be used. If the chart is a histogram, the oHistogramStyle will be used. These are documented together because their use is identical for all charts; the only difference is which object is used.
These contain many properties all of which are used to affect the appearance of the chart. Line colors, line styles, font sizes, chart colors, and many other properties are contained in one of these objects. Think of these as bags of style properties.
These properties are set during the OpenFile method. Each chart has an sStyleName property which (if set) specifies the style file to use. Style files have a .cst file extension and may be created by running the CHARTrunner program. The ReadChartStyleFile method may be used to directly read a style file.
Generally speaking, it will be easier to manipulate individual chart styles by running the CHARTrunner application than it will be to do so in scripting code.
Data Type
oControlChartStyle is an SqcStyleControl object.
oHistogramStyle is an SqcStyleHistogram object.
oParetoStyle is an SqcStylePareto object.
An SqcOOC object. This object contains the list of out-of-control test rules that will be used to evaluate out-of-control conditions for this PQCrDef object. These rules are used when any control chart is drawn 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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.Application.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn.
The PQCrDef.ReadOOCFile method can be used to load test rules from a file into PQCrDef.oOocTests. See also: CHARTrunner17.Application.ReadOOCFile.
Example
Dim bRtn As Boolean
Dim j As Integer
Dim oChRunApp As New CHARTrunner17.Application
Dim oCrDef as PQCrDef
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' At this point the oCrDef.oOocTests property will contain the test rules
' currently stored in oChRunApp.oOocTests.
' Read a chart definition file. If the chart definition file contains test rules
' they will replace any existing test rules in oCrDef.oOocTests.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Sample 01.crf", eCrPathFull)
' Display the current set of test rules.
For j = 1 To oCrDef.oOocTests.Tests.Count
MsgBox oCrDef.oOocTests.Tests(j)
Next j
' Load a new set of test rules from a disk file. This will replace any existing
' test rules with those from the file.
bRtn = oCrDef.ReadOOCFile("C:\MyRules\OocTests1.ooc")
' Add a new test rule to those we loaded from the file.
oCrDef.oOocTests.Tests.Append "2 of 3 above 2 sigma"
This property is a PqStrList object which contains a list of strings, where each string is the full path to a peer chart for "Chart Review". A PqStrList is similar to a collection in that it has a .Count property.
This property is used by the Display method to specify a list of peer charts for "Chart Review".
Data type
PqStrList (object)
rsDataADO
rsDataJet Properties
Each of these properties is a recordset object. If the property eCrDataSourceType is set to eCrDataSourceTypeJet, you should reference rsDataJet, otherwise, you should reference rsDataADO. Note that only one of these recordset objects will be valid for any given chart. This recordset contains the data that will be charted.
The appropriate recordset is made current by calling the GetChartRecordSet method after all the other data source properties have been set. Note that even though this is a public property that you could set directly, you should not do so. See also: eDataSourceType, sDataSourceFile.
Data Type
Recordset
This property sets or returns a string representing the percentage by which the subgroup size must change before control limits are adjusted on attributes control charts.
Data Type
String
This property sets or returns a string used as the ConnectionString to open the database when the data source is either an ODBC driver or an ADO provider.
Data Type
String
This property sets or returns a string that is the name of an ODBC data source. This is only set for ODBC data sources. For all others it is an empty string.
Data Type
String
This property sets or returns a string used as a password when opening a database for either ODBC or ADO. If this is saved with the CHARTrunner file, it is encrypted. However, this property is the plain text version of the password.
Data Type
String
This property sets or returns a string used as a user login name when opening a database for either ODBC or ADO.
Data Type
String
This packed string holds all the chart annotations that are associated with this chart. Contact PQ Systems if you have a need to define your own chart annotations.
Data type
String
sAtrConstNumInspected Property
This property sets or returns a string used as a constant number inspected for np charts (an attributes control chart.) Setting this property to a number allows you create the chart from a data source that does not include a column for storing this number.
Data Type
String
SBottomTitle
sTopTitle Properties
This property sets or returns title strings in an array property. CHARTrunner allows for ten rows of titles above the chart and ten rows of titles below the chart. Further, you may specify a left, center, and right title for each row. An empty cell may be filled with the "~" (tilde) character to prevent the cell from being collapsed. See also: ClearTitles, sBottomTitleFont, sTopTitleFont.
Data Type
String (two dimensional array)
Example
Dim oChRunApp As New CHARTrunner17.Application
Dim oCrDef As PQCrDef
Dim bRtn As Boolean
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Open a chart definition file.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Sample 01.crf", eCrPathFull)
oCrDef.sTopTitle(1, 1) = "Top left title"
oCrDef.sTopTitle(1, 2) = "Top center title"
oCrDef.sTopTitle(1, 3) = "Top right title"
oCrDef.sBottomTitle(1, 2) = "Bottom center title"
oCrDef.sBottomTitle(2, 2) = "2nd Bottom center title"
sBottomTitleFont
sTopTitleFont Properties
This property sets or returns strings in an array property that specifies custom fonts for titles in each allowable position. The font name, size, style, and alignment have default values that come from the current chart style. However, this property allows you to override the defaults on a per-title basis. The format for specifying these font strings must be followed precisely, as in the example below. See also: ClearTitles, sBottomTitle, sTopTitle.
Data Type
String (two dimensional array)
Example
Dim oChRunApp As New CHARTrunner17.Application
Dim oCrDef As PQCrDef
Dim bRtn As Boolean
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Open a chart definition file.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Sample 01.crf", eCrPathFull)
' Set a chart title.
oCrDef.sTopTitle(1, 1) = "Top left title"
' Set the font for the chart title.
oCrDef.sTopTitleFont(1, 1) = "Arial,18,I,B,C"
The general form of a title font should be:
FontName,Size,italic,bold,alignment
If you want italic, put an I in place of italic, or omit this position.
If you want bold, put a B in place of bold, or omit this position.
For alignment, use L for left, C for center, R for right.
Examples
"Courier,12,C"
"Tahoma,14,B,C"
This property sets or returns a string specifying the name of the chart. This is the name as it will appear to a CHARTrunner user. Note that the SetFileName method uses this name combined with the current working folder and the appropriate file extension to create a full path/file name for the sFileName property.
Data Type
String
Use this property to set or return a string specifying the name of the style to be used for this chart. This can be an empty string but the default appearance of most charts will probably encourage you to set this to the name of an existing chart style. This is the name as it appears to the CHARTrunner user. Note that all chart style files are stored in the ...\Sysdata folder where CHARTrunner is installed. This property should be set only to the style name; the folder and file extension will be handled internally.
Data Type
String
The Read-Only property returns the full path to the current style file.
Here are the rules for where we look for a style file:
1. If no style name has been specified, then use a style file
in the chart folder having the same name as the chart definition, if it exists.
This is the "per-chart" style file.
2. If a style name has been specified, and it specifies the full path to the
style file, then use it.
3. If a style name has been specified, but it doesn't specify the full path,
then assume the style file is found in the chart folder. If found, then use it.
4. If a style name has been specified, but it doesn't specify the full path, and
it wasn't found by Rule #3, then assume the style file exists in the Styles
folder.
Data type
String
This is a read-only property that returns a string specifying the chart type. It is set automatically when the eChartType property is set to a valid chart type. This provides a human readable chart type such as X-bar and Range.
Data Type
String
Use this property to set or return a string specifying a column name from the data source. This column name is used in conjunction with the Advanced Row Selection option that says to form subgroups whenever the contents of some column changes. This must be set to a valid column name for the current data source when eRowSelectOption is set to eCrRowSelectEveryNRowsWhenColChanges.
See also: bUseAdvRowSelection.
Data Type
String
Set or return a string specifying a file name to use for the data source. If the chart refers to data in an Excel spreadsheet or Access database, this will be the full path to the data file. For some data sources such a text files, FoxPro, and Paradox, this will contain only a full path to the folder that contains one or more of the appropriate files.
Data Type
String
This property is obsolete but still supported in version . In its place the eDataSourceType and eJetDataType should be used.
Use this property to set or return a string specifying a data source type. The data source type must be one of the following:
"Microsoft Access"
"Microsoft Excel"
"Text File"
"FoxPro"
"Paradox"
"Dbase"
"ODBC; Open database connectivity"
"ADO; OLE DB provider"
Data Type
String
Sets or returns a string that defines how to format a date when it is displayed. This will be passed into the Visual Basic Format() function as its second argument.
Data type
String
Use this property to set or return a string specifying a description for the chart. This is the description as it will appear to a CHARTrunner user.
Data Type
String
This read-only property returns a string specifying the full path to the chart definition file. It may not be set directly. Instead, use the SetFileName method in conjunction with the sChartName property. SetFileName works in conjunction with the sChartFolder property of the CHARTrunner17.Application object.
Data Type
String
This property returns a string that represents the current CHARTrunner chart definition file version. In the XML chart definition file the file version is stored in the <Version> element under the <General> element.
Data Type
String
Sets or returns a string that is the full path/file name for the image file to be created when this chart is saved as a graphic image file. See also GenerateChartImageFile.
Data Type
String
A read-only property. When any method of the PQCrDef object returns False to indicate that it failed, check this property for a description of errors which may have occurred.
Data Type
String
sLowerSpec
sTargetSpec
sUpperSpec Properties
Use this property to set or return a string that represents a specification related to the characteristic being charted. These are usually engineering specifications or tolerances. Although these are string properties, they should be set to string versions of numeric values that represent the specifications. The values of these properties affect several statistics related to histograms and capability analysis.
Data Type
String
sLeftTitle
sRightTitle Properties
This property sets or returns a string to be used as a chart title positioned vertically on either the left or right side of the chart.
Data Type
String
This property sets or returns a string that names the Order By column in the data table. This column will be used in the ORDER BY clause when selecting records from a table. This property is meaningful only when eRecSelectType is set to eCrRecSetTable.
Data Type
String
This property sets or returns a string that determines how many bars (categories) will be included in a Pareto chart. Setting this to “10” will create a chart showing only the first 10 categories (based on count) that appear in the data. The purpose of a Pareto chart is to help focus on the most common problems. Note that setting this option may make it appear that not all the data from your data source is included in the analysis. See also: eLimitParBarsBy, bParetoIncludeMissingBar, bParetoCountMissing, sParBarPercentCutoff.
Data Type
String
This property sets or returns a string that determines a percentage at which a Pareto chart will be cut off. Setting this to “80%” will create a chart where only the top 80% of the categories (based on count) will be shown. See also: eLimitParBarsBy, bParetoIncludeMissingBar, bParetoCountMissing, sParBarPercentCutoff.
Data Type
String
Returns the full path to the parent chart definition file. If the PQCrDef object specifies a child chart of a Workspace or MultiChart then return the full path to the Workspace/MultiChart chart definition file, otherwise return sFileName.
Data type
String
This property is used in conjunction with the eResultRecSelectType property. If you set the eResultRecSelectType property to eUseLastN and you set this property to “25”, the chart will include only the Last 25 records from your data source. Note that these properties are used after any filtering or advanced row selection properties have been applied to the data.
Data Type
String
Specifies the left-side character to be used to enclose or bracket database object names. See also: bUseBracketsInSql, sSqlBracketRight
Data type
String
Specifies the right-side character to be used to enclose or bracket database object names. See also: bUseBracketsInSql, sSqlBracketLeft.
Data type
String
This property sets or returns a string that contains the full text of an SQL select statement. This SQL statement specifies how to retrieve data records for the chart. Set this when eRecSelectType is set to eCrRecSetCustomQuery. See also: eRecSelectType.
Data Type
String
This property sets or returns a value that is the name of table in the database specified by the current data source. The table becomes the source of data records for this chart. See also: eRecSelectType.
Data Type
String
Sets or returns a string that defines how to format a time when it is displayed. This will be passed into the Visual Basic Format() function as its second argument.
Data type
String
Returns the XML chart definition currently defined by the PQCrDef object.
Data type
String
Clears all chart titles from the chart definition.
Syntax
Public Sub ClearTitles()
Save the current chart definition in this PQCrDef object as a clipCHART file specified by sCcFile.
Syntax
Public Function CreateClipChart(ByVal sCcFile As String) As Boolean
Remarks
This method is similar to the CHARTrunner17.Application.CreateClipChart method, however that method can only createa clipCHART from a chart definition on disk. The PQCrDef.CreateClipChart method creates a clipCHART based upon the chart definition currently specified by the PQCrDef object (i.e. Me).
Example
Dim bRtn As Boolean
Dim oChRunApp As New CHARTrunner17.Application
Dim oCrDef As PQCrDef
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Read the chart definition file.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Sample 01.crf", eCrPathFull)
' Specify some chart titles so that the chart definition in oCrDef is different
' from that in "C:\MyCharts\Sample 01.crf".
oCrDef.sTopTitle(1, 2) = "Example clipCHART Created using
PQCrDef.CreateClipChart"
oCrDef.sTopTitleFont(1, 2) = "Arial,14,B,C"
oCrDef.sTopTitle(2, 2) = "~"
oCrDef.sBottomTitle(2, 2) = "~"
oCrDef.sBottomTitle(3, 2) = "http://www.chartrunner.com"
oCrDef.sBottomTitleFont(3, 2) = "Arial,14,B,C"
' Generate a clipCHART having the custom titles we specified above.
bRtn = oCrDef.CreateClipChart("C:\MyCharts\Sample 01.ccf")
Returns
True = Success.
False = Failure (see sLastError).
Display this PQCrDef chart in a chart window. Use this method after you have called the ReadChartDefinition method (to read all the chart settings from disk) or after you have set these in memory. The optional Boolean arguments default to False if they are not set. If this method returns False, check the contents of the sLastError property for an indication of what went wrong.
Syntax
Public Function Display(Optional ByVal bShowModal As Boolean =
False, _
Optional ByVal bReadOnly As Boolean = False, _
Optional ByRef bCancel As Boolean, _
Optional ByVal bReview As Boolean) As Boolean
Remarks
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.
Set the bShowModal argument to True so that the chart display form is displayed modally. Some scripting environments do not allow a non-modal form to be displayed.
If the chart involves a parameter query then the user has the option to cancel the display of the chart from the "Query Parameters" form, in which case bCancel will be set to True to inform the caller.
If the chart definition is a Workspace, a new chart display window will be created for each child chart in the Workspace unless bReview is True, in which case only the first child chart is displayed in a new chart window, and the rest of the charts in the Workspace may be viewed via "Chart Review". If the chart definition is not a Workspace, bReview is True, and the PeerChartList property specifies a list of peer charts, then "Chart Review" will operate in the context of the peer charts specified by PeerChartList.
Returns
True = Success.
False = Failure (see sLastError).
Display a form which allows the user to modify the chart definition defined by this PQCrDef object.
Syntax
Public Function Edit(bDidChartChange As Variant, _
Optional ByVal bNew As Boolean = False, _
Optional ByVal bAllowNameChange As Boolean = True, _
Optional bCanceled As Variant) _
As Boolean
Remarks
Upon return the caller can check the bDidChartChange argument to see if the user changed the chart definition. The bNew parameter should be True only if this is a new chart definition that does not yet exist on disk. Set bAllowNameChange to True if you want to allow the user to change the name of the chart. If bCanceled is passed then the caller can check for True which means that the user pressed the Cancel button after editing the chart definition. Note: This routine does not save any changes to disk. If you intend to save changes to the disk, call the SaveFile method when Edit returns a True for bDidChartChange. If this method returns False, examine sLastError for details. See also: Validate.
Returns
True = Success.
False = Failure (see sLastError).
Generate an image file based this PQCrDef chart definition. The image type is specified by eImageType and will be either a Windows bitmap file (*.bmp), a Windows enhanced metafile (*.emf) or a Jpeg compressed image file (*.jpg). If lWidthInPixels or lHeightInPixels is zero then the image size information stored in the chart definition is used. If False is returned, examine the contents of sLastError.
Syntax
Public Function GenerateChartImageFile(ByVal eImageType
As eCrImageType, _
ByVal sImageFile As String, _
Optional ByVal lWidthInPixels As Long = 0, _
Optional ByVal lHeightInPixels As Long = 0) As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Remarks
Note that a PQCrDef object has properties that you may use as the arguments to this method. For example:
Example
Dim bRtn As Boolean
Dim oChRunApp As New CHARTrunner17.Application
Dim oCrDef As PQCrDef
' Create a chart definition object.
Set oCrDef = oChRunApp.CreatePqObject(eObjPQCrDef)
' Read the chart definition file.
bRtn = oCrDef.ReadChartDefinition("C:\MyCharts\Sample 01.crf", eCrPathFull)
' Generate the image, use the chart definition for the arguments.
bRtn = oCrDef.GenerateChartImageFile(oCrDef.eImageType, oCrDef.sImageFileName, 640, 480)
Generally speaking, this method should not be used by Software Developer's Kit programmers. It is called internally by other methods such as Display and PrintChart. This method retrieves the recordset that will be used for the chart, based on several related properties. If successful, then either rsDataADO or rsDataJET will contain the newly created recordset. If a parameter query is used in the chart's data source, and the user cancels on the "Parameter Query" form, then bCancel will be set to True. See also: eDataSourceType, sDataSourceFile, sTableName, UseExternalRecordset.
Syntax
Public Function GetChartRecordSet(bCancel As Boolean) As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Return a reference to the "Data Object" for the chart so that you can access chart statistics.
Syntax
Public Function GetDataObject(Optional ByVal iChartNumber As Integer = 1, _
Optional ByVal iLineNumber As Integer = 1) As Object
Remarks
If the current chart is a Multi-Chart, then use iChartNumber argument to get the "Data Object" for the appropriate child chart of the Multi-Chart.
Use the iLineNumber argument to specify which line of a Multi-Line chart to use.
If the current chart is a Workspace, then Nothing is returned.
If bKeepDataObjects is True, then calling PrintChart() or GenerateChartImageFile() causes the PQCrDef to save a reference to the temporary "Data Object" that was used to render the chart, so that this routine can return a reference to that "Data Object".
If bKeepDataObjects is False, or no previous call to PrintChart() or GenerateChartImageFile() has been performed, then a new "Data Object" is created for the chart so that the "Data Object" reference can be returned.
Note that if the last charting operation was Display() then the GetDataObject() method will always return a reference to a new "Data Object" because the "Data Object" that is used to display the chart form is destroyed when the chart form is closed.
The type of the returned "Data Object" depends upon the type of chart. For an attributes chart a PQCountData object is returned. For a pareto chart a PQCategoryData object is returned. For a scattergram a PQCorrelationData object is returned. All other chart types, including control, multi-line, and histogram, return a PQMeasurementData object. See PQDM_Interface.html for more information about the chart statistic properties for each type of "Data Object".
This method is available in version 1.7.68 and higher. See the VBScript example file Sample9.vbs for an example of using bKeepDataObjects and GetDataObject() to gain access to chart statistics.
Returns
Reference to the "Data Object".
Nothing = Failure (see sLastError).
GetSrcColDefsCollection Method
Build a collection containing one PqCrColDef object for
each column in the current chart data source.
If cCols is passed by the caller, then that collection will be updated
and bSrcColDefsCurrent will NOT be
changed. Otherwise the cSrcColDefs
collection will be updated and bSrcColDefsCurrent
will be updated to reflect that the collection is current.
Syntax
Public Function GetSrcColDefsCollection( _
Optional ByRef cCols As Collection = Nothing) As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Initialize the properties of this PQCrDef object to the "New Chart Definition" state.
Syntax
Public Sub Initialize()
Read the chart definition specified by sCrName and update the properties of this PQCrDef object.
This method is obsolete (but still supported)in this version and ReadChartDefinition should be used in its place.
Syntax
Public Function OpenFile(ByVal sCrName As String, _
Optional ByVal ePathType As ePqCrPathType
= eCrPathRelative) _
As Boolean
Generally, call this method with ePathType set to eCrPathFull and ensure that sCrName specifies the full path to a chart definition file. Setting ePathType to eCrPathRelative allows you to specify only the chart name for sCrName and the current working folder – CHARTrunner17.Application.sChartFolder – will be assumed.
Returns
True = Success.
False = Failure (see sLastError).
Print the chart defined by this PQCrDef chart definition. When printing a multi-chart where you want each chart to print on its own page, set bPrnMCSep to True. To print without displaying the printer dialog box, set bPrintWithDialog to False. Specify the name of the printer to use in sPrinterName (the default printer is used if this is blank).
Syntax
Function PrintChart(Optional ByVal bPrnMCSep As Boolean =
False, _
Optional ByVal bPrintWithDialog As Boolean = True, _
Optional ByVal sPrinterName As String) As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Read the chart definition specified by sChartDef from
the disk and update the properties of this PQCrDef object.
Syntax
Public Function ReadChartDefinition(ByVal sChartDef As String,
_
Optional ByVal ePathType As ePqCrPathType
= eCrPathRelative, _
Optional ByVal sParentChartDef As String, _
Optional ByVal iChildChartNum = 1) _
As Boolean
Remarks
Depending on ePathType we treat sChartDef either
as the name of a chart definition in the current working folder or the full path
for a chart definition file.
If sChartDef specifies a child chart of a parent MultiChart or Workspace
then both sParentChartDef and iChildChartNum should be specified. sParentChartDef
specifies the full path to the parent MultiChart or Workspace chart definition
file. iChildChartNum (having a value of 1 to N) specifies the index of
this child chart in the parent MultiChart or Workspace.
Returns
True = Success.
False = Failure (see sLastError).
Read the style properties from sStyleDef into the appropriate style object. Depending on style type, this method will store the style definition into the oControlChartStyle, oHistogramStyle, or oParetoStyle object. See also: ReadChartStyleFile.
Syntax
Public Function ReadChartStyle(ByVal sStyleDef As String) As Boolean
Remarks
sStyleDef can specify the full path to an XML or INI formatted style file (.CST). Or, it can contain the XML style definition.
Returns
True = Success.
False = Failure (see sLastError).
Read the contents of the CHARTrunner chart style file (.CST) specified by sStyleDef from disk into the appropriate chart style object in this PQCrDef. Note that sStyleDef can specify either the full path to a style file or it may contain an XML style definition string. Depending on chart type, this method will store the style definition into the oControlChartStyle, oHistogramStyle, or oParetoStyle object. Note that if the sChartStyleName property is already set when the OpenFile or ReadChartDefinition method is called, this method will be automatically called. See also: ReadChartStyle, SaveChartStyleFile.
Syntax
Public Function ReadChartStyle(ByVal sStyleDef As String) As Boolean
Returns
True = Success.
False = Failure (see sLastError).
This method reads an out-of-control test definition file. 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 PQCrDef.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.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 CHARTrunner17.Application.oOocTests are used to evaluate "out-of-control" conditions when a chart is drawn.
See also: CHARTrunner17.Application.ReadOOCFile.
Returns
True = Success.
False = Failure (see sLastError).
Read and parse the XML chart definition in sXml.
Syntax
Public Function ReadXmlDefinition(ByVal sXml As String) As Boolean
Remarks
sXml can specify the URL to the XML chart definition, or it can
contain the XML chart definition. If "<?xml" is found at the
beginning of sXml then it is assumed that it contains the XML chart
definition rather than pointing to it. This results in the properties of this PQCrDef
object being updated as the elements of sXml are parsed.
The XML does not have to specify a complete chart definition. For example, it
might only specify the chart type.
Returns
True = Success.
False = Failure (see sLastError).
Save the XML chart definition defined by this PQCrDef to the disk file specified by the sFileName property. Set bNew to True if this is a new chart definition that has not yet been written to disk; this causes the file to be saved in the folder specified by Application.sChartFolder. Set bDefault to True if you are writing a default chart definition; this causes the chart definition to be written to disk as appropriate for a default chart definition.
It is recommended that you successfully call the Validate method before calling SaveChartDefinition. The Validate method returns False if any errors occur, in which case check the contents of sLastError for details. See also: SetFileName.
Syntax
Public Function SaveChartDefinition(Optional ByVal bNew As
Boolean = False, _
Optional ByVal bDefault As Boolean = False) _
As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Save the XML chart definition defined by this PQCrDef to the disk file specified by sSaveChartAs.
If bSaveAsCopy is True then the Me.sChartName and Me.sFileName properties are not updated to reflect saved chart definition; in this case sSaveChartAs is truly a copy of the current chart definition. If bSaveAsCopy is False then both Me.sChartName and Me.sFileName are updated to reflect the newly saved chart definition.
Syntax
Public Function SaveChartDefinitionAs(ByVal sSaveChartAs As
String, _
Optional ByVal bSaveAsCopy As Boolean = True) _
As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Save the chart window size and position information to the XML chart definition file specified by sParentChartFile.
When a chart window is closed the size and postion of the window is saved to the XML chart definition file so that the next time the chart is displayed it will use the same chart window size and position. This method is automatically called by CHARTrunner.
Syntax
Public Function SaveChartPosition() As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Save the current style properties in this PQCrDef object to the style definition file specified by sStyle.
Syntax
Public Function SaveChartStyleFile(ByVal sStyle As String, _
Optional ByVal ePathType As ePqCrPathType = eCrPathRelative) _
As Boolean
Remarks
sStyle specifies the name of a style in the Styles folder
or the full path to a style file.
If ePathType = eCrPathRelative then sStyle specifies the name (only)
of a style in the Styles folder.
If ePathType = eCrPathFull then sStyle specifies the full path to the style file.
Depending on the type of chart currently defined by this PQCrDef object the style definition will be written from one of these style objects: oControlChartStyle, oHistogramStyle, or oParetoStyle. See also: ReadChartStyleFile
Returns
True = Success.
False = Failure (see sLastError).
Save the chart definition defined by this PQCrDef to the disk file specified by the sFileName property. Set bNew to True if this is a new chart definition that has not yet been written to disk. Set bDefault to True if you are writing a default chart definition.
This method is obsolete (but still supported) in this version and SaveChartDefinition should be used in its place.
It is recommended that you successfully call the Validate method before calling SaveFile. This method returns False if any errors occur, in which case check the contents of sLastError for details. See also: SetFileName.
Syntax
Public Function SaveFile(Optional ByVal bNew As Boolean =
False, _
Optional ByVal bDefault As Boolean = False) _
As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Set the sFileName read-only property to the full path to the chart definition file based on sChartName and CHARTrunner17.Application.sChartFolder. In CHARTrunner the file name for any chart is a combination of the chart name (sChartName) and the current working folder (CHARTrunner17.Application.sChartFolder).
Syntax
Public Sub SetFileName(Optional bNew As Boolean = False)
Remarks
Set bNew to True if this is a new chart definition that has not yet been written to disk. This ensures that the file is given the proper extension and is written into the folder specified by CHARTrunner17.Application.sChartFolder.
Setup this PQCrDef to contain default settings based on an existing CHARTrunner file specified by sDefaultFileName (the full path to the file). When CHARTrunner is installed the SysData folder always contains a file named default.crf. Generally, this is the full file path you should pass into this method.
Basically this method just calls the ReadChartDefinition method and then sets the chart name to a new name.
Syntax
Public Function SetToDefaults(ByVal sDefaultFileName As String) As Boolean
Returns
True = Success.
False = Failure (see sLastError).
Setup this PQCrDef object to use the programmer
supplied recordset specified by rsExtData as the source of the chart's
data. rsExtData may specify either an ADO or DAO recordset. It is the
programmer's responsibility to properly setup the cColDefs
collection when an external recordset is specified so that the columns of the
recordset are properly mapped. If rsExtData is Nothing then the
chart will not use an external recordset. See also: bUseExternalRecordset,
cColDefs
Syntax
Sub UseExternalRecordset(ByVal rsExtData As Object)
Remarks
The rsExtData parameter was changed to ByVal for better scripting compatibility in version 1.7.68 and higher.
Check to see if the current chart definition is valid. It is a good idea to use this method to validate a chart definition before writing it to disk.
This method is obsolete (but still supported) in this version and Validate2 should be used in its place.
Syntax
Public Function Validate(eErr As eCrDefInvalid,
bNew As Boolean, _
Optional bDupFilesOk As Boolean = False, _
Optional bCheckRecordset As Boolean = False) As Boolean
Remarks
eErr = (Output) Error enum value returned to caller.
bNew = (Input) Is this a new chart? If True, then do not allow duplicate chart names in the current
chart folder.
bDupFilesOK = (Input) This parameter is not currently used.
bCheckRecordset = (Input) Verify that the recordset can be gotten and is valid.
Returns
True = Chart definition is valid.
False = Chart definition is not valid (The error enum condition is returned in
eErr and is also available in Me.eValidationError.
See Me.sLastError for the error
message).
Check to see if the current chart definition is valid. This method, unlike Validate, can be called from script code such as VBScript.
It is a good idea to use this method to validate a chart definition before writing it to disk. This method is available in version 1.7.68 and higher.
Syntax
Public Function Validate2(Optional ByVal bCheckDuplicateName As Boolean = False, _
Optional ByVal bCheckRecordset As Boolean = False) As Boolean
Remarks
bCheckDuplicateName = (Input) If True, then do not allow duplicate chart
definition names in the current
chart folder.
bCheckRecordset = (Input) Verify that the recordset can be gotten and is valid.
Returns
True = Chart definition is valid.
False = Chart definition is not valid (see Me.eValidationError for the error condition
and Me.sLastError for the error message).
Execute the custom query defined in the PQCrDef object in order to validate it.
Syntax
Public Function ValidateCustomQuery() As Boolean
Returns
True if the query appears to be valid.
False if any query errors occur (see sLastError).
eCrChartType Enumeration
Public Enum eCrChartType
eCrTypeNone = -1
eCrTypeXbarRange = 0
eCrTypeXbarSigma = 1
eCrTypeIndMovRange = 2
eCrTypeIndMovSigma = 3
eCrTypeMovAvgMovRange = 4
eCrTypeXbar = 5
eCrTypeRange = 6
eCrTypeSigma = 7
eCrTypeInd = 8
eCrTypeMedian = 9
eCrTypeRun = 10
eCrTypeHistogram = 11
eCrTypePchart = 12
eCrTypeNPchart = 13
eCrTypeCchart = 14
eCrTypeUchart = 15
eCrTypePareto = 17
eCrTypeScatter = 17
eCrTypeMultiLine = 18
End Enum 'eCrChartType'
eCrDataSourceType Enumeration
Public Enum eCrDataSourceType
eCrDataSourceTypeJet = 1
eCrDataSourceTypeODBC = 2
eCrDataSourceTypeAdo = 3
End Enum 'eCrDataSourceType'
Public Enum eCrDefInvalid
eCrNameMissing = 1
eCrNameTooLong = 2
eCrDuplicateName = 3
eCrDescTooLong = 4
eCrRefreshIntervalTooShort = 5
eCrNeedCategoryOrCountColumn = 6 ' Changed name
11-17-00.
eCrMultipleCategoryColumns = 7
eCrUserLimitsMissing = 8
eCrUserLimitsInvalid = 9
eCrMultiLinePlotValueNotSet = 10
eCrMultiLinePlotValueInvalid = 11
eCrMultiLineInvalidColumns = 12
eCrIndChartInvalidColumns = 13
eCrAvgChartInvalidColumns = 14
eCrScatterInvalidColumns = 15
eCrInvalidMovingN = 17
eCrInvalidDecimalDigits = 17
eCrInvalidHistogramCells = 18
eCrInvalidNumHistoCells = 19
eCrInvalidHistoYMax = 20
eCrInvalidCustomYScale = 21
eCrRunChartInvalidColumns = 22
eCrNoDefaultImagePath = 23
eCrNoLimitsName = 24
eCrInvalidExtraLine = 25
eCrInvalidImageFileName = 26
eCrImageFilenameReqd = 27
eCrInvalidImageSize = 28
eCrInvalidCauseColumn = 29
eCrFailedToRetrieveRecSet = 30
eCrNoMeasureColsHistogram = 31
eCrNoColumnsMapped = 32
eCrMultipleGroupByColumns = 33
eCrMultipleCountColumns = 34 ' Obsolete 11-13-00.
eCrNoNumInspDefined = 35
eCrMultipleNumInspColumns = 36
eCrAmbiguousNumInsp = 37
eCrInvalidAtrCountCol = 38
eCrCchartCountColInvalid = 39
eCrNoRecordsReturned = 40
eCrMultipleCauseNoteCols = 41
eCrInvalidDataInPercentColumn = 42
eCrInvalidDataInRatioColumn = 43
eCrInvalidVariableNumInspData = 44
eHistMovingNErr = 45
eCrInvalidLastN = 46
eCrInvalidDfectsPerValue = 47
eCrInvalidSpecs = 48
eCrInvalidN1AdvRow = 49
eCrMismatchOrderGroupBy = 50
eCrAdvOrderByProblem = 51
eCrInvalidMultiChartTileSettings = 52
eCrInvalidDataInCountColumn = 53
eCrOrderByColumnNotIdentifier = 54
eCrNoCountColumns = 55 ' Added 11-13-00 RBS.
eCrGroupByColumnNotPermitted = 56 ' Added 11-17-00
RBS.
eCrInvalidChartName = 57 ' Added 02-05-01 RBS.
End Enum 'eCrDefInvalid'
eCrImageType Enumeration
Public Enum eCrImageType
eCrImageJpg = 1 ' JPEG image.
eCrImageBmp = 2 ' Bitmap image.
eCrImageEmf = 3 ' Windows enhanced metafile.
End Enum 'eCrImageType'
eCrTreatColAs Enumeration
' eCrTreatColAs = How a column is treated in the data recordset.
Public Enum eCrTreatColAs
eCrColUnMapped = 0
eCrColCategories = 1
eCrColCause
eCrColCount
eCrColData
eCrColData1
eCrColData2
eCrColData3
eCrColData4
eCrColDependentVar
eCrColGroupBy
eCrColId
eCrColIgnore
eCrColIndependentVar
eCrColMeasurement
eCrColNote
eCrColNumInspected
eCrColOrderBy
eCrColPercent
eCrColRatio
End Enum 'eCrTreatColAs'
ePqCrPathType Enumeration
Public Enum ePqCrPathType
eCrPathFull = 1
eCrPathRelative = 2
End Enum 'ePqCrPathType'
|
PQCrColDef Object |
||
| Property | Type | Description |
| bUniqueID | Boolean | This column is a "Unique Identifier" column? |
| eColType | Long | ADO or DAO recordset column type enum value. |
| eDataSourceType | eCrDataSourceType | Jet, ODBC or ADO data source. |
| eTreatColAs | eCrTreatColAs | How this column is treated as data for charting. |
| sColType | String | Text version of the eColType property. |
| sDisplayName | String | The Display As name for the column. |
| sName | String | The column name. |
| sTreatColAs | String | Text version of the eTreatColAs property. |
|
PQCrPrefs Object |
||
| Property | Type | Description |
| eDblClickAction | eCrDblClickAction | What action does a double-click on a chart in the tree take? |
| eNavigationBehavior | eCrNavigationBehavior | Navigate with the keyboard or the mouse? |
| bShowChartType | Boolean | Show the chart type in the tree? |
| bShowDescription | Boolean | Show the chart description in the tree? |
| bEnableSaveWarnings | Boolean | "Enable warnings" in Setup > Preferences. |
| bKeepChartsOnScreen | Boolean | Automatically adjust the chart position to keep it on the screen? |
| bSilentMode | Boolean | "Suppress message boxes" in Setup > Preferences. |
| bUseMasterOocTests | Boolean | This Boolean value is copied into PQCrDef.bUseMasterOocTests when a PQCrDef (i.e. a chart definition) object is created. If PQCrDef.bUseMasterOocTests is True when the chart is drawn then the master set of Out-Of-Control tests (defined in Setup > Out-of-control) stored in Application.oOocTests are used, otherwise the Out-Of-Control tests stored in the chart definition (in PQCrDef.oOocTests) are used. This property is new in version 1.5. |
| sTextEditor | String | Full path to the text editor to use when Shift-F12 is pressed to view the definition of a chart. |
| iJpgImageQuality | Integer | JPEG image quality (1 to 99) |
| eCrDblClickAction | Enum Definition | eCrDblClickDrawChart = 1, eCrDblClickEditChart = 2 |
| eCrNavigationBehavior | Enum Definition | eCrNavigateKeyboard = 1, eCrNavigateMouse = 2 |
|
PqCrSqlFilterDef Object |
||
| Property | Type | Description |
| sDateTimeColName | String | The Date/Time column name. |
| sDateTimeStart | String | The starting Date/Time boundary value. |
| sDateTimeStop | String | The ending Date/Time boundary value. |
| bInclusive | Boolean | If True then sDateTimeStart to sDateTimeStop is inclusive. |
| sF1ColName | String | Column name for the first filter. |
| sF1Op | String | Operator used in the first filter =, <, >, <>, etc. |
| sF1Const | String | Constant comparison value for the first filter. |
| sF12Combine | String | "AND" or "OR" - how to combine filters 1 & 2. |
| sF2ColName | String | Column name for the second filter. |
| sF2Op | String | Operator used in the second filter =, <, >, <>, etc. |
| sF2Const | String | Constant comparison value for the second filter. |
| sF23Combine | String | "AND" or " OR" - how to combine filters 2 & 3. |
| sF3ColName | String | Column name for the third filter. |
| sF3Op | String | Operator used in the third filter =, <, >, <>, etc. |
| sF3Const | String | Constant comparison value for the third filter. |
| sFAcCombine | String | " AND" or " OR" - how to combine with 'Additional Conditions', if present. |
| sAdditionConditions | String | User-entered additional SQL WHERE clause statements. |
| bUseBracketsInSql | Boolean | Do names need to be surrounded by brackets? |
| sSqlBracketLeft | String | The left bracket character when bUseBracketsInSql is True. |
| sSqlBracketRight | String | The right bracket character when bUseBracketsInSql is True. |
The PqStrList object is used to hold a list of strings. It is similar to an array of String objects, and it also has some characteristics of the VB Collection object. The elements of the list start at 1 and go to PqStrList.Count.
Dim oList As New PqStrList
Dim s As String
oList.Append "Robert"
oList.Append "Lee"
oList.Append "Carol"
Call oList.Sort(ePqStrListSortAscending)
' Read the string in the first element of the list.
s = oList(1)
' Replace the string in the third element of the list.
oList(3) = "Replacement String"
' Store a string in the fifth element of the list. Now element 4 contains a zero length string
' and oList.Count is 5.
oList(5) = "Bob"
|
PqStrList Object |
||
| Property | Type | Description |
| Count | Long | Count of the number of strings stored in the list. |
| Value(ByVal Index As Long) | String | You can read and write the string located at the specified 'Index'. It is permissible to assign a string to an index that is beyond the current Count of elements in the list. |
| Method | Description | |
| Append(sItem As String) As Long | Appends 'sItem' to the end of the list and return the current 'Count' of strings in the list. | |
| Sub Clear() | Clears all elements from the list. Afterwards 'Count' is zero. | |
| Sub Remove(ByVal Index As Long) | Removes the element specified by 'Index' from the list. Any elements in the list beyond the element specified by 'Index' will be shifted up to occupy the deleted slot. Thus, after each call to Remove() the Count property will decrease by one. | |
| Sub Insert(Index As Long, sData As String) | Inserts the string specified by 'sData' into the 'Index' element of the list. Any elements in the list beyond the element specified by 'Index' will be shifted down to accomodate the inserted slot. Thus, after each call to Insert() the Count property will increase by one. However, you cannot insert past the current end of the list. | |
| Sub Sort(eSortType As ePqStrListSortType, Optional vFirst As Variant, Optional vLast As Variant) | Sort the list ascending or descending as specified by 'eSortType'. Optionally specify the 'vFirst' starting element index and/or the 'vLast' ending element index to sort. | |