Mirage Client Controls Spotlight

Recital Developer Center / Technical Articles /Mirage Client Controls Spotlight - Graph Controls: Line Charts

Mirage Client Controls Spotlight - Graph Controls: Line Charts

Related Links
Recital Home Recital Product Family Recital Terminal Developer Recital Visual Developer Recital Database Server Recital Web Developer

	Email this article
	Print this article

The first in a series of articles examining in depth a particular Mirage .NET control. This month the spotlight is on the Graph Controls. Part 3, Line Charts.

Yvonne Milne
July, 2007.

Overview

Data visualization using graphs can be a particularly effective way to transform raw data into useful information. The Recital Mirage .NET Client offers three graph controls:

Part 3 examines Line Charts.

Line Charts - Simple

The Line Chart is based on the @<row>,<col> TO <row>,<col> box drawing command with graph control specific properties. The following properties are required as a minimum:

Property	Example	Description
control	control=graphcontrol	This defines the box as a graph control and must be specified.
id	id=chart1	A unique id for the control.
type	type=line	The type of graph control: bar for a bar chart, pie for a pie chart and line for a line chart.
data	data=20,30,50,60,0,50	A comma-separated list of the data to graph.

Click image to display full size

Fig 1: Simple Line Chart.

@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=20,30,50,60,0,50"
read

If not configured, the vertical axis defaults to six ticks with an increment of 20, ranging from 0 to 100: 0,20,40,60,80,100. To configure the vertical axis, use the following properties:

Property	Example	Description
minValue	minValue=0	The minimum data value.
maxValue	maxValue=600	The maximum data value.
yTicks	yTicks=7	The number of tick marks.
yTickinc	yTickinc=100	The tick mark interval.
yValueLabels	yValueLabels=0,100,200,300,400,500,600	The tick mark text labels.

Click image to display full size

Fig 2: Simple Line Chart: vertical axis configured.

@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=103,220,300,450,150,560;;
	minvalue=0;;
	maxvalue=600;;
	yTicks=7;;
	yTickinc=100;;
	yValueLabels=0,100,200,300,400,500,600"
read

The data itself is labeled, using the xValueLabels property:

Property	Example	Description
xValueLabels	xValueLabels=One,Two,Three,Four,Five,Six	The data labels.

Click image to display full size

Fig 3: Simple Line Chart: vertical axis configured, data labeled.

@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=103,220,300,450,150,560;;
	minvalue=0;;
	maxvalue=600;;
	yTicks=7;;
	yTickinc=100;;
	yValueLabels=0,100,200,300,400,500,600;;
	xValueLabels=One,Two,Three,Four,Five,Six"
read

Line charts can of course have multiple sets of data displayed. The numgroups property is used to define the number of data sets. The data for each set is listed in the data property: the first value applies to the first set, the second value to the second set, the third value to the third set and so on, looping through the data sets.

Property	Example	Description
numgroups	numgroups=3	The number of data sets or groups of data, corresponding to the number of lines displayed on the line chart.

Click image to display full size

Fig 4: Simple Line Chart with multiple data sets.

@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=103,53,153,220,340,200,180,320,80,200,450,400,150,450,350,560,0,260;;
	minvalue=0;;
	maxvalue=600;;
	yTicks=7;;
	yTickinc=100;;
	yValueLabels=0,100,200,300,400,500,600;;
	xValueLabels=One,Two,Three,Four,Five,Six;;
	numgroups=3"
read

Line Charts - Data Based

The simple line chart examples above have the data and labels specified as constant values, but in most cases these will be strings built up from the source data tables. This example uses the orders tables from the southwind database that is included in Recital product distributions.

Click image to display full size

Fig 5: Data Based Line Chart.

The SQL query pulls obtains the number of orders from the orders table that correspond to each shipping company for each month in the specified year. For ease of manipulation, the query is saved into a temporary table.

// Define variables to be used including a temporary table
c_values = "" 
c_names  = ""
c_table  = "_" + tmpnam()

// Open the database and extract the data into the temporary table
exec sql
open database southwind;

exec sql
select count(orderid) orders,
	shipvia shipper,
	month(orderdate) month
	from orders 
	where year(orderdate)=1997
	group by 3,2
	save as &c_table;

Traverse the temporary table using the 4GL SCAN command to build up the comma-separated string c_values with the number of orders.

// Scan the table to build up the strings
use &c_table
scan
	c_values = c_values + ltrim(str(orders))+","
endscan

The c_values variable can then be used as the line chart's data property.

Define the graph, macro-substituting the c_values variable (using the 4GL & macro operator).

// Define the graph
@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=&c_values;;
	minvalue=0;;
	maxvalue=20;;
	yTicks=11;;
	yTickinc=2;;
	yValueLabels=0,2,4,6,8,10,12,14,16,18,20;;
	xValueLabels=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec;;
	numgroups=3"
read

Define the legend with the Shipping Company names.

// Define the legend
@18,24 to 22,55
@19,28 say bold("<- Speedy Express") color b
@20,28 say bold("<- United Package") color r
@21,28 say bold("<- Federal Shipping") color g

Complete source:

// Define variables to be used including a temporary table
c_values = "" 
c_names  = ""
c_table  = "_" + tmpnam()

// Open the database and extract the data into the temporary table
exec sql
open database southwind;

exec sql
select count(orderid) orders,
	shipvia shipper,
	month(orderdate) month
	from orders 
	where year(orderdate)=1997
	group by 3,2
	save as &c_table;

// Scan the table to build up the strings
use &c_table
scan
	c_values = c_values + ltrim(str(orders))+","
endscan

// Define the graph
@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=&c_values;;
	minvalue=0;;
	maxvalue=20;;
	yTicks=11;;
	yTickinc=2;;
	yValueLabels=0,2,4,6,8,10,12,14,16,18,20;;
	xValueLabels=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec;;
	numgroups=3"
	
// Define the legend
@18,24 to 22,55
@19,28 say bold("<- Speedy Express") color b
@20,28 say bold("<- United Package") color r
@21,28 say bold("<- Federal Shipping") color g	

read

close databases

Drilling-Down

Unlike the bar chart and pie chart graph controls, the line chart has no onDoubleClick event handler.

Display Properties

There is a whole range of further properties that can be used to configure the display of the Line Chart:

Property	Example	Description
xtitle	xtitle=No of Orders	The vertical axis title.
ytitle	ytitle=Shipping Company	The horizontal axis title.
pixelyTitle	pixelyTitle=20	The row position in pixels of the horizontal axis title.
pixelxTitle	pixelxTitle=500	The column position in pixels of the horizontal axis title.
pixelWidthTitle	pixelWidthTitle=200	The width of the horizontal axis title.
borderColor	borderColor=red	The foreground color of the border.
borderWidth	borderWidth=3	The width of the border line.
shadowStyle	shadowStyle=raised	The shadowing effect style: raised, recessed, etchedIn, etchedOut. The shadowing effect is only available if borderWidth is 0 or not specified.
shadowWidth	shadowWidth=3	The width in pixels of the shadowing effect.
wallpaper	wallpaper=+gradient_blue.gif	The background, 'wallpaper' image. The image file name can be preceded by a '-' to tile the image to fit or by a '+' to stretch the image to fit.
titleBackColor	titleBackColor=blue	The background color of the horizontal and vertical axes titles.
titleForeColor	titleForeColor=white	The foreground color of the horizontal and vertical axes titles.
labelForeColor	labelForeColor=navy	The foreground color of the data labels (xValueLabels) and tick labels (yValueLabels).
colorData	colorData=red,yellow,green	The line colors. The default colors are: blue, red, green, yellow, aqua, pink, fuchsia, gray, orange, navy, white, coral, beige, paleturquoise, darkgray. These are repeated as required
axisForeColor	axisForeColor=navy	The color of the vertical and horizontal axes.
horiLineColor	horiLineColor=gray	The color of the horizontal gridlines.
vertLineColor	vertLineColor=silver	The color of the vertical gridlines.

Click image to display full size

Fig 6: Line Chart with additional display properties set.

@02,05 to 13,75 properties "control=graphcontrol;;
	id=chart1;;
	type=line;;
	data=&c_values;;
	minvalue=0;;
	maxvalue=20;;
	yTicks=11;;
	yTickinc=2;;
	yValueLabels=0,2,4,6,8,10,12,14,16,18,20;;
	xValueLabels=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec;;
	numgroups=3"

// Use SHOW OBJECT TO avoid "String is too long" errors
show object "graphcontrol" properties "command=properties;id=chart1;;
	xtitle=No of Orders;;
	ytitle=Month;;
	borderColor=navy;;
	borderWidth=3;;
	wallpaper=+gradient_blue.gif;;
	titleBackColor=blue;;
	titleForeColor=white;;
	labelForeColor=navy;;
	colorData=red,blue,green;;
	axisForeColor=navy;;
	horiLineColor=gray;;
	vertLineColor=silver"

@18,24 to 22,55 
@19,28 say bold("<- Speedy Express") color r
@20,28 say bold("<- United Package") color b
@21,28 say bold("<- Federal Shipping") color g

read

Appendix 1: Color Name Reference

The following color names can be used by the Mirage .NET client.

Colors
aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue	darkslategray darkturquoise darkviolet deeppink deepskyblue dimgray dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green greenyellow honeydew hotpink indianred indigo ivory khaki lavendar lavendarblush lawngreen lemonchiffon lightblue lightcoral lightcyan lightgray lightgreen lightpink lightsalmon	lightseagreen lightskyblue lightslategray lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred	papayawhip peachpuff peru pink plum powderblue purple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen