| QChart Documentation by Michael Zito (c) 2003-2004 | Appendix A: QChart |
=============================================================================================
QChart: A Charting Class for Rapid-Q
Copyright (c) 2003-2004 Michael J. Zito
Released under the LPGL License
=============================================================================================
QChart provides a rich set of 2-D charting routines for Rapid-Q programmers.
It generates histograms, bar charts, XY-scatter plots, line graphs, pie charts
and box plots. Each charting routine will calculate an appropriate scale and plot
the data contained in the .Data or .XYData property of the object. The user may
optionally specify the scaling as well as fonts, grids or other properties
(see code and HTML documentation). Once the data is formatted graphs can be called
with a few lines of simple code.
----> To create an instance and call QChart:
$INCLUDE "QChart.inc"
CREATE YourInstanceName AS QChart
Parent = QForm, QTabControl or QPanel
Set any other desired properties of a QCanvas
END CREATE
WITH YourInstanceName
.Initialize
.ChartType = ctXXXX
.ChartStyle = csXXXX
---->Change Any Desired Properties (See code or HTML Documentation)
---->REDIM .Data array property (See below)
---->Load Data Into .LabelList, .LegendList and .Data Array
.DrawChart (Overlay T or F)
END WITH
NOTE: There is little error checking in this class. It is up to the user
to insure that the data is formatted properly before calling each routine.
LegendList and LabelList are implemented as QStringLists.
*Use the .AddItems Method of each property to add text to the lists.
*LegendList contains legend text and usually refers to the Cols (i.e. Series)
*LabelList contains text used to label the X Axis and usually refers to Rows
(i.e. Categories). LabelList items are NOT USED by XY Charts
The .Data property is a 2 dimensional array of DOUBLE which must be REDIMd by the user
prior to filling the grid with data. The first dim is Cols and the second is Rows.
Each Col represents a series to be plotted. The Rows represent the data values
within each series. Use the .Data property for all charts EXCEPT XY Charts.
XY Charts have their own data array.
The .XYData property is a 3 dimensional array of DOUBLE. The first dim is Cols
and the second is Rows. The third dim is ALWAYS 2. Each Col represents a series
to be plotted. The Rows represent the number of XY data pairs within each
series. The third dimension refers to the X and Y data values for each
point to be plotted: 1 = X and 2 = Y values
----> To REDIM the .Data or .XYData array property:
You MUST set the .Cols and .Rows properties before calling QChart. These values are used
throughout the QChart class as loop counters. Set .Cols to number of series to be plotted
and set .Rows to number of values in each series. REDIM the array using .Cols and .Rows.
NOTE: To REDIM you MUST EXPLICITLY REFERENCE your QChart instance by name (even inside a
WITH block) or RapidQ will not find and REDIM the array. (A RapidQuirk?!?)
WITH YourInstanceName
.Cols = 2 <-- Num series
.Rows = 2 <-- Num values in each series
REDIM YourInstanceName.Data(.Cols, .Rows) <-- for all EXCEPT XY Charts
REDIM YourInstanceName.XYData(.Cols, .Rows, 2)<-- for XY Charts
END WITH
----> Sample Data Formats (given the DIMs above):
XY Charts All Other Charts
===================== ================
Series NumPts Values Series Values
(Col) (Row) (dim 3) (Col) (Row)
1 1 1 <-- X 1 val 11
1 1 2 <-- Y 1 val 12
1 2 1 2 val 21
1 2 2 2 val 22
2 1 1
2 1 2
2 2 1
2 2 2
Box Plots HiLo Plots Pie Charts BarLine Plots
(5 rows only) (3 rows only) (1 Col only) (2 Cols only)
================ ================= ============== ===============
Row 1 = Max Row 1 = Hi Col Row Col 1 Col 2
2 = Q3 2 = Close ===== ===== ===== =====
3 = Median 3 = Lo 1 1 Bar Line
4 = Q1 1 2 Data Data
5 = Min 1 n
See QChartEx.rqb for more examples of setting up and calling each chart type.
See QChart.inc for named CONSTs used for ChartType, ChartStyle, HatchStyle and LineStyle
| Field | Type | R/W | Default | Support |
| Align | INTEGER | RW | alNone | W |
| ClientHeight | INTEGER | RW | W | |
| ClientWidth | INTEGER | RW | W | |
| Color | INTEGER | RW | WXG | |
| CopyMode | INTEGER | RW | cmBlackness | W |
| Cursor | INTEGER | RW | crDefault | W |
| Enabled | INTEGER | RW | True | WXG |
| Font | QFONT | W | W | |
| Height | INTEGER | RW | WXG | |
| Hint | STRING | RW | W | |
| Left | INTEGER | RW | 0 | WXG |
| Parent | QFORM/QPANEL/QTABCONTROL | W | WXG | |
| Pixel | 2D ARRAY of INTEGER | RW | WXG | |
| PopupMenu | QPOPUPMENU | W | W | |
| ShowHint | INTEGER | RW | False | W |
| Tag | INTEGER | RW | WXG | |
| Top | INTEGER | RW | 0 | WXG |
| Width | INTEGER | RW | WXG | |
| Visible | INTEGER | RW | True | WXG |
| Field | Type | Description | RW | Default |
| AxisBorder | BYTE | Draws border around plot | RW | True |
| ChartBorder | BYTE | Draws border around entire chart | RW | True |
| Colors() | ARRAY of LONG | Array of predefined colors | RW | |
| bgColor | LONG | Chart background color | RW | |
| fgColor | LONG | Chart foreground color | RW | |
| PlotAreaColor | LONG | Color of plot area | RW | |
| GridColor | LONG | Color of gridlines | RW | |
| BW | BYTE | Plots in Black and White | RW | False |
| GreyScale | BYTE | Plots in GreyScale | RW | False |
| DoLegend | BYTE | Draw a legend to right of chart | RW | True |
| MarkerSize | SINGLE | Size of markers for XY and Line charts | RW | 3 |
| Viewport | INTEGER | Specifies Viewport width for Real Time Graphs | RW | 100 |
| ChartType | INTEGER | Sets type of Chart to plot | RW | ctXY |
ctBar, ctLine, ctXY, ctPie, ctHiLo, ctBox, ctBarLine, ctReal | ||||
| ChartStyle | INTEGER | Sets style of Chart Type to plot | RW | csPoints |
Bar Line and XY Pie HiLo ================================================== csBar csPoints csPisPct csAntenna csHisto csLines csPieVal csHiLoBox csStacked csBoth csPctStacked | ||||
| Missing | DOUBLE | Value used to represent missing data | RW | -9.999E-45 |
| Data | 2D ARRAY of DOUBLE | Data used in plotting all Charts EXCEPT XY | RW | |
Series Values (Col) (Row) 1 val 11 1 val 12 2 val 21 2 val 22 | ||||
| XYData | 3D ARRAY of DOUBLE | Data used to plot XY Charts ONLY | RW | |
| Series NumPts Values (Col) (Row) (dim 3) 1 1 1 <-- X 1 1 2 <-- Y 1 2 1 1 2 2 2 1 1 2 1 2 2 2 1 2 2 2 | ||||
| Cols | INTEGER | Number of series to plot | RW | 1 |
| Rows | INTEGER | Number of data values in each series | RW | 1 |
| To REDIM the .Data or .XYData array property: You MUST set the .Cols and .Rows properties before calling QChart. These values are used throughout the QChart class as loop counters. Set .Cols to number of series to be plotted and set .Rows to number of values in each series. REDIM the array using .Cols and .Rows. NOTE: To REDIM you MUST EXPLICITLY REFERENCE your QChart instance by name (even inside a WITH block) or RapidQ will not find and REDIM the array. (A RapidQuirk?!?) WITH YourInstanceName .Cols = 2 <-- Num series .Rows = 2 <-- Num values REDIM YourInstanceName.XYData(.Cols, .Rows, 2) <-- XY Only REDIM YourInstanceName.Data(.Cols, .Rows) <-- All Others END WITH | ||||
| MainFont | QFONT | Font used to draw the Main Title | RW | Times |
| MainTitle.Text | STRING | RW | "" | |
| SubFont | QFONT | Font used to draw the Sub Title | RW | Times |
| SubTitle.Text | STRING | RW | "" | |
| LegendFont | QFONT | Font used to draw the Legend | RW | Times |
| LegendList | QSTRINGLIST | Legend text items; usually one for each series | RW | "" |
| Use the .AddItems Method to add text to the lists. LegendList contains legend text and usually refers to the Cols (i.e. Series) | ||||
| AxisFont | QFONT | Font used to draw the Axis Labels | RW | Times |
| LabelList | QSTRINGLIST | Axis label text items; usually one for each category | RW | "" |
| Use the .AddItems Method to add text to the lists. LabelList contains text used to label the X Axis and usually refers to Rows (i.e. Categories). LabelList items are NOT USED by XY Charts | ||||
| XTitle.Text | STRING | RW | "" | |
| YTitle.Text | STRING | RW | "" | |
| XAxis / YAxis | UDTs (Elements Below) | There is 1 UDT for the XAxis and 1 for the YAxis | RW | |
| .AutoScale | BYTE | QChart scales the axes | RW | True |
| .Color | LONG | Color of axis line | RW | |
| .Div | INTEGER | Number of divisions on the axis | RW | 10 |
| .DrawZero | BYTE | Draw a zero line if data spans origin | RW | True |
| .ZeroColor | LONG | Color of Zero line | RW | |
| .Grid | BYTE | Draw gridlines for the axis | RW | True |
| .Labeled | BYTE | Label the axis at tic intervals | RW | True |
| .LogScale | BYTE | TRUE = Log Scale, FALSE = Linear Scale | RW | False |
| .Min | DOUBLE | Data Minimum. Must be set if AutoScale = FALSE | RW | |
| .Max | DOUBLE | Data Maximum. Must be set if AutoScale = FALSE | RW | |
| .Tics | BYTE | Draw tic marks on the axis | RW | True |
| .MnrTics | BYTE | Draw minor tic marks on the axis | RW | True |
| Series() | UDT ARRAY (Elements Below) | Contains format inforamtion for each series plotted | RW | |
| .AutoColor | BYTE | Cycle through 18 available colors | RW | True |
| .AutoMark | BYTE | Cycle through 8 available marker styles | RW | True |
| .Color | LONG | Color used in plotting the series | RW | |
| .HatchStyle | LONG | Hatch style used in plotting the series | RW | hsSolid |
| .LineStyle | LONG | Line style used in plotting the series | RW | lsSolid |
| .LineWidth | LONG | LineWidth used in plotting the series | RW | 1 |
| .Marker | BYTE | Marker style used in plotting the series | RW | msFilledCircle |
| Method | Type | Description | Params |
| Initialize | SUB | Sets all values to default | 0 |
| ClearAll | SUB | Clears drawing buffer and paints blank canvas | 0 |
| PaintChart | SUB | Draws Chart on Canvas. Assign this method to your OnPaint event | 0 |
| DrawChart | SUB (Overlay%) | Draws the currently defined chart to screen | 1 |
| RedrawChart | SUB | Redraws chart at new size. Call from Resize event | 0 |
| CopyToClipboard | SUB (Wid%, Hgt%) | Copies at specified width and height | 2 |
| SaveChart | SUB (SaveAs%) | SaveAs = 0:No dialog if previously saved; 1:Always shows dialog | 1 |
| PrintChart | SUB (Prn%, Orient%, Margin%, Copies%, Color%) | Uses CopyRect method to print chart. May not work with all printers | 5 |
| Event | Type | Occurs when... | Params | Support |
| OnClick | VOID | User clicked on canvas | 0 | WXG |
| OnMouseDown | SUB (Button%, X%, Y%, Shift%) | Mouse button held down | 4 | WXG |
| OnMouseMove | SUB (X%, Y%, Shift%) | Mouse moves | 3 | WXG |
| OnMouseUp | SUB (Button%, X%, Y%, Shift%) | Mouse button is released | 4 | WXG |
| OnPaint | VOID | Receives WM_PAINT message | 0 | WXG |
$OPTIMIZE ON
$TYPECHECK ON
$INCLUDE "QChart.inc" '<--- change path to point to file on your system
'----- Form Event SUB Declarations
Declare Sub btnOnClick (SENDER As QBUTTON)
Declare Sub frmMainResize (SENDER As QFORM)
Declare Sub frmMainClose (SENDER As QFORM)
'----- Define the main form
Create frmMain As QFORM
Center
Width = 640
Height = 480
Caption = "QChart Example"
OnResize = frmMainResize
OnClose = frmMainClose
Create drwBar1 As QBUTTON
Caption = "Bar Graph"
OnClick = btnOnClick
End Create
Create btnPie As QBUTTON
Caption = "Pie Chart"
Top = 25
OnClick = btnOnClick
End Create
Create drwXYboth As QBUTTON
Caption = "XY Both"
Top = 50
OnClick = btnOnClick
End Create
Create drwBox As QBUTTON
Caption = "Box Plot"
Top = 75
OnClick = btnOnClick
End Create
Create drwHiLo1 As QBUTTON
Caption = "HLC Style 1"
Top = 100
OnClick = btnOnClick
End Create
Create Graph As QCHART 'Create a copy of the new object
Align = 4 'alRight
Width = frmMain.ClientWidth - btnPie.Width
Height = frmMain.ClientHeight
OnPaint = Graph.PaintChart 'This line REQUIRED to process Repaints
End Create'Graph
End Create'frmMain
Graph.ClearAll
frmMain.Showmodal
Sub btnOnClick (SENDER As QBUTTON)
Dim i As Integer 'Loop counters...
Dim j As Integer
Dim k As Single 'A Scratch Variable
Select Case Sender.Caption
Case "Bar Graph"
With Graph
.Initialize 'Set defaults
.ChartType = ctBar 'Bar Chart
.ChartStyle = csBar 'Grouped Bars
.MainTitle.Text = "Bar Graph Example 1" 'change desired options
.SubTitle.Text = "Standard Bar Graph"
.XTitle.Text = "X Axis"
.YTitle.Text = "Y Axis"
.Cols = 6 '<- Set Num Series
.Rows = 3 '<- Set Num Groups
REDIM Graph.Data(.Cols,.Rows) '<- REDIM the Data Array
k = 75
Randomize
For j = 1 To .Rows 'Do this outside data loop
.LabelList.AddItems "Treatment " + Str$(j) 'to avoid duplication of entries
Next j
For i = 1 To .Cols 'Load the data
.LegendList.AddItems "Grp " + Str$(i)
For j = 1 To .Rows
.Data(i,j) = Rnd * k
Next j
Next i
.DrawChart (FALSE) 'Draw it!
End With
Case "Pie Chart"
With Graph
.Initialize 'Always call this first
.ChartType = ctPie
.ChartStyle = csPiePct 'Show % at wedges (csPieVal shows Values)
.AxisFont.Size = 12
.LegendFont.Size = 12
.MainTitle.Text = "Pie Chart"
.SubTitle.Text = "Click Again For New Data"
.Cols = 1 'Only 1 col for pie data
.Rows = 6 'Set Num data points
REDIM Graph.Data(.Cols,.Rows) 'Redim the Data Array
k = 100 'Load the data
Randomize
For i = 1 To .Rows
.Series(i).AutoColor = FALSE
.Series(i).Color = .Colors(i + 12)
.LegendList.AddItems "Group " + Str$(i)
.Data(1,i) = Rnd * k ' * i
Next
.DrawChart(FALSE) 'Always call this last
End With
Case "XY Both"
With Graph
.Initialize 'Set defaults
.ChartType = ctXY 'XY Scatter Chart
.ChartStyle = csBoth 'Lines and Points
.MainTitle.Text = "Scatter Plot With Lines" 'change desired options
.SubTitle.Text = "Double Width Lines"
.XTitle.Text = "X Axis"
.YTitle.Text = "Y Axis"
.MarkerSize = .MarkerSize * 1.5
.Cols = 3 'Number of series
.Rows = 11 'Number of data points per series
REDIM Graph.XYData(.Cols,.Rows,2) 'Redim XYData. Note 3rd dim always 2
k = 132 'Load the data
Randomize
For i = 1 To .Cols
.LegendList.AddItems "Group " + Str$(i)
.Series(i).LineWidth = 2
For j = 1 To .Rows
.XYData(i,j,1) = Str$(j) 'X Values (3rd dim 1)
.XYData(i,j,2) = Str$(Rnd * k) 'Y Values (3rd dim 2)
Next j
Next i
.DrawChart (FALSE) 'Draw it!
End With
Case "Box Plot"
With Graph
.Initialize 'Set defaults
.ChartType = ctBox 'Box and Whisker Plot
.MainTitle.Text = "Box and Whisker Plot" 'change desired options
.XTitle.Text = "X Axis"
.YTitle.Text = "Y Axis"
.XAxis.Grid = FALSE
.DoLegend = FALSE
.Cols = 6 'Number of series
.Rows = 5 'Always 5 for Box Plots
REDIM Graph.Data(.Cols,.Rows) 'Redim the data array
k = 20 'Load the data
Randomize
For i = 1 To .Cols 'for each col
.Series(i).AutoColor = FALSE
.Series(i).Color = .Colors(2)
.LabelList.AddItems "Group " + Str$(i)
.Data(i , 1) = Str$(Rnd * k + 100) 'Max Values
.Data(i , 2) = Str$(Rnd * k + 75) 'Q3 Values
.Data(i , 3) = Str$(Rnd * k + 50) 'Q2 Values
.Data(i , 4) = Str$(Rnd * k + 25) 'Q1 Values
.Data(i , 5) = Str$(Rnd * k) 'Min Values
Next i
.DrawChart (FALSE) 'Draw it!
End With
Case "HLC Style 1"
With Graph
.Initialize 'Set defaults
.ChartType = ctHiLo 'Hi-Lo-Close Plot
.ChartStyle = csAntenna
.MainTitle.Text = "Hi-Lo-Close Plot" 'change desired options
.SubTitle.Text = "Antenna Style"
.XTitle.Text = "X Axis"
.YTitle.Text = "Y Axis"
.XAxis.Grid = FALSE
.Cols = 12 'Number of series
.Rows = 3 'Always 3 for HiLo charts
REDIM Graph.Data(.Cols,.Rows) 'Redim the data array
k = 10 'Load the data
Randomize
For i = 1 To .Cols 'for each col
.LabelList.AddItems "Group " + Str$(i)
.Data(i , 1) = Rnd * k + 100 'Hi Value
.Data(i , 2) = Rnd * k + 75 'Close Value
.Data(i , 3) = Rnd * k + 50 'Lo Value
Next i
.DrawChart (FALSE) 'Draw it!
End With
End Select
End Sub
'-------------------------------------------------------------------------------------------
Sub frmMainResize (SENDER As QFORM)
With Graph
.Width = frmMain.ClientWidth - btnPie.Width 'Calculate new sizes
.Height = frmMain.ClientHeight
.RedrawChart 'Redraw the QChart Object
End With
End Sub
'-------------------------------------------------------------------------------------------
Sub frmMainClose (SENDER As QFORM)
Application.Terminate
End Sub
'-------------------------------------------------------------------------------------------