Omnis Graphs

Using the Graph2 component

TigerLogic Corporation
November 2007
The software this document describes is furnished under a license agreement. The software may be
used or copied only in accordance with the terms of the agreement. Names of persons, corporations, or
products used in the tutorials and examples of this manual are fictitious. No part of this publication may
be reproduced, transmitted, stored in a retrieval system or translated into any language in any form by
any means without the written permission of TigerLogic.
© TigerLogic Corporation, and its licensors 1992-2008. All rights reserved.
Portions © Copyright Microsoft Corporation.
Regular expressions Copyright (c) 1986,1993,1995 University of Toronto.
© 1999-2007 The Apache Software Foundation. All rights reserved.
This product includes software developed by the Apache Software Foundation
(http://www.apache.org/).
OMNIS® and Omnis Studio® are registered trademarks of TigerLogic Corporation.
Microsoft, MS, MS-DOS, Visual Basic, Windows, Windows 95, Win32, Win32s are registered
trademarks, and Windows NT, Visual C++ are trademarks of Microsoft Corporation in the US and other
countries.
SAP, R/3, mySAP, mySAP.com, xApps, xApp, and other SAP products and services mentioned herein
as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and
in several other countries all over the world.
IBM, DB2, and INFORMIX are registered trademarks of International Business Machines Corporation.
ICU is Copyright © 1995-2003 International Business Machines Corporation and others.
UNIX is a registered trademark in the US and other countries exclusively licensed by X/Open Company
Ltd.
Sun, Sun Microsystems, the Sun Logo, Solaris, Java, and Catalyst are trademarks or registered
trademarks of Sun Microsystems Inc.
J2SE is Copyright (c) 2003 Sun Microsystems Inc under a licence agreement to be found at:
http://java.sun.com/j2se/1.4.2/docs/relnotes/license.html
MySQL is a registered trademark of MySQL AB in the United States, the European Union and other
countries (www.mysql.com).
ORACLE is a registered trademark and SQL*NET is a trademark of Oracle Corporation.
SYBASE, Net-Library, Open Client, DB-Library and CT-Library are registered trademarks of Sybase
Inc.
Acrobat is a trademark of Adobe Systems, Inc.
Apple, the Apple logo, AppleTalk, and Macintosh are registered trademarks and MacOS, Power
Macintosh and PowerPC are trademarks of Apple Computer, Inc.
HP-UX is a trademark of Hewlett Packard.
OSF/Motif is a trademark of the Open Software Foundation.
CodeWarrior is a trademark of Metrowerks, Inc.
This software is based in part on ChartDirector, copyright Advanced Software Engineering
(www.advsofteng.com).
This software is based in part on the work of the Independent JPEG Group.
This software is based in part of the work of the FreeType Team.
Other products mentioned are trademarks or registered trademarks of their corporations.
 Table of Contents

Table of Contents
OMNIS GRAPHS .................................................................6
CHART TYPES ..........................................................................6
XY Charts............................................................................6
Pie Charts...........................................................................8
Polar Charts .......................................................................9
Meter Charts.....................................................................10
The Graph2 Example Library...........................................10
COMMON GRAPH PROPERTIES ...............................................11
Setting the major and minor type .....................................13
COMMON GRAPH METHODS ..................................................14
XY CHARTS ..........................................................................16
XY chart properties...........................................................16
XY chart methods..............................................................17
List data structure for XY charts.......................................18
Data presentation in XY charts.........................................24
PIE CHARTS ...........................................................................26
Pie chart properties ..........................................................26
Pie chart methods .............................................................27
List data structure for Pie charts......................................27
POLAR CHARTS .....................................................................29
Polar chart properties ......................................................29
Polar chart methods .........................................................30
List data structure for Polar charts ..................................30
METER CHARTS .....................................................................33
Meter chart properties......................................................33
Meter chart methods.........................................................34
List data structure for Meter charts..................................34
Adding Pointers ................................................................35
Adding Rings ....................................................................37
GRAPH LAYERS AND THE PRELAYOUT EVENT .......................38
Adding layers to charts.....................................................38
GRAPH CLICKS AND DRILLDOWN ..........................................40
CHANGING THE COLOR OF GRAPH ELEMENTS........................41
ADDING COLORED ZONES .....................................................42
PARAMETER SUBSTITUTION AND FORMATTING .....................42
Parameters for Pie charts.................................................43
Parameters for all XY Chart Layers .................................43
Additional Parameters for HLOC and CandleStick Layers45
Additional Parameters for Box Whisker Layers ...............45

3
Table of Contents

Additional Parameters for Trend Layers..........................45

Parameters for Polar Charts ............................................46
Parameters for Axis ..........................................................46
Number Formatting ..........................................................46
Date/Time Formatting ......................................................47
Further formatting options ...............................................48
LABELS..................................................................................50
Adding Text to a Chart .....................................................50
USING GRAPHS IN REPORTS ...................................................51
USING GRAPHS IN THE WEB CLIENT ......................................53
Drilldown in Web Client graphs.......................................54
INDEX .................................................................................56
 About This Manual

About This Manual

This manual describes how you can use the Graph2 component to create a number of
different types of graph or chart in Omnis Studio.
The information in this guide replaces that given in Chapter 13 Extending Omnis in the
Omnis Programming manual (issued with Studio 4.1 in Nov 2005).

5
Omnis Graphs

Omnis Graphs
You can create many different types of chart in Omnis using the Graph component (called
Graph2) and display them in your windows, remote forms, or reports. The data and
appearance of a chart is based on the data stored in an Omnis list variable. The different
chart types require a different list data structure to represent their data points. The Graph2
component supports four main types of chart, XY charts, Pie charts, Polar charts and Meter
charts, each of which has a number of subtypes (except Pie). The major and minor types of
the graph are specified as properties of the graph window object (found under External
Components in the Component Store) and the associated list variable is specified in the
$dataname property of the object.

Note to existing Omnis developers

The Graph2 component is based on a new graphing engine (called ChartDirector from
Advanced Software Engineering Ltd) and was introduced in order to simplify graphing
functionality in Omnis. The new Graph2 component can produce many more types of chart
and is easier to use than the old Graph component, which for backwards compatibility is
still available in Omnis, but is no longer maintained or supported.

Chart Types
XY Charts
XY charts can be one of several different minor types or subtypes.
Bar charts
Bar charts represent individual amounts, or
compare individual amounts; you can
change the graph orientation to show
horizontal bars. There are several subtypes
which you can select, including Line,
Scatter, Area, and Box whisker.

6
 Chart Types

Line charts
Line charts emphasize the rate of change
rather than individual amounts.

Scatter charts
Scatter charts show the relationship of
different groups of numerical data, and plot
the data as xy coordinates.

Area charts
Area charts emphasize the amount or
magnitude of change rather than the rate of
change.

Box whisker charts

Box whisker charts normally consist
of five items of data to represent each
element. Gantt charts are also
constructed using the Box Whisker
type, using three items of data per
graph element.

7
Omnis Graphs

High/Low/Open/Close charts
High/Low/Open/Close (HLOC) charts are
used to represent financial data; this type
uses four data items to represent each
element.

Candlestick charts
Candlestick charts are used to represent
financial data; this type uses four data
items to represent each element.

Pie Charts
The data in a pie chart is represented as
sections, or slices of a pie. There are no
minor types for this chart type, but pies have
numerous visual effects.

8
 Chart Types

Polar Charts
Polar charts represent data points on a radial axis with the values represented as the distance
from the center; four minor types are available.

Polar Area Polar Line

See later in this section for a description of how to

draw the 2 graphs above

Polar Spline Line and Area

9
Omnis Graphs

Meter Charts
Numeric amounts or measurements can be shown as a meter or gauge; angular (or dial) or
linear styles are available.

A meter chart with the Linear subtype. In addition to

changing the orientation of meter charts, you can add
extra pointers for showing multiple data points, and
colored zones to mark the scale or dial, for example.

A Meter chart with Angular subtype

providing a dial or gauge effect, shown here
with rounded frame

The Graph2 Example Library

There is an example library showing how the Graph2 component works, which is located
under the Examples link in the Welcome window when you first launch Omnis – you can
open this window by clicking on the New Users button in the main Omnis toolbar. Code
from the example library is used later in this manual to show you how to use the component.

10
 Common Graph Properties

Common Graph Properties

All the different graph types have the following properties; one of the most important
properties is the $dataname which contains the name of the Omnis list variable containing
the data for the graph; this is found under the General tab in the Property Manager.

Property Name Data Type Description

$dataname List The name of the Omnis list variable supplying the data
to the graph; the structure of the data in the list must
match the type of graph you wish to draw
The following common properties are found under the Prefs tab in the Property Manager.

Property Name Data Type Description

$deviceindependent Boolean If True report printing creates a device
independent bitmap (DIB), used for printing in
the Web client and cross-platform applications
$imagesearchpath Char The path and folder name where the Graph
component will search for images (on Mac OS
X the property uses a standard HFS colon-
separated pathname); if empty (the default), the
component searches in the Omnis\Icons folder
$legendbackgroundcolor RGB Color The legend background color
$legendbackgroundeffect Constant The legend background effect: kG2colorSolid,
kG2colorMetal, or kG2colorNotUsed
$legendpos Constant The legend position: kG2legendNone,
kG2legendLeft, kG2legendRight,
kG2legendTop, kG2legendBottom,
kG2legendManual ($legendx & legendy apply)
$legendtextcolor RGB Color The legend text color
$legendvert Boolean If True the legend is drawn vertically
$legendx Integer The X Position of the legend (only if
$legendpos is kG2legendManual)
$legendy Integer The Y Position of the legend (only if
$legendpos is kG2legendManual)
$majortype Constant The graph type, a constant: kG2xy, kG2pie,
kG2polar, or kG2meter
$minorxytype Constant Minor type for XY, Polar, or Meter graphs
$minorpolartype only; there are no minor types for Pie charts
$minormetertype
$roundedframe Boolean If True the graph frame has rounded corners

11
Omnis Graphs

The following common properties are found under the Custom tab in the Property Manager
for all graph types.

Property Name Data Type Description

$3d Boolean If true the graph is 3d
$backgroundborder RGB Color The background border color
$backgroundcolor RGB Color The background color
$backgroundeffect Constant kG2colorSolid or kG2colorMetal
$backgroundraised Integer The degree to which the background is raised (if
positive) or sunken (if negative); 0 is not raised
$columnheadings Character Character value which may be used to override the
column names which are normally taken from the
list assigned to the graph
$labelfont Character Name of the font for the graph label (appears under
the main title); must be a font in the Omnis/fonts
folder; see the Labels section later in this manual
$maintitle Character The main title of the graph
$offsetwidth Integer The offset width for the graph
$offsetx Integer Additional x offset for the graph
$offsety Integer Additional y offset for the graph
$titlefont Character Name of the font for the graph title; must be a font
in the Omnis/fonts folder; see the Labels section
later in this manual
$titlefontheight Integer Height of the font for the graph title
$wallpaper Character The path/filename of an image; leave blank for no
image
$xaxisfontangle Integer The angle of rotation, -1 is the default
$xaxistitle Character The title displayed on the X-Axis
$xlabelfontangle Integer angle of rotation for X axis label, -1 is the default
$y2axisfontangle Integer angle of rotation for Y2 axis label, -1 is the default
$yaxisfontangle Integer angle of rotation for Y axis label, -1 is the default
$yaxistitle Character The title displayed on the Y axis

12
 Common Graph Properties

Setting the major and minor type

The different types of graph are specified using the $majortype and $minortype of the graph
object. The following types are available, specified under the Prefs tab in the Property
Manager:

Major type ($majortype) Minor type Minor type constants

kG2xy $minorxytype kG2xyBar
kG2xyLine
kG2xyScatter
kG2xyArea
kG2xyBoxwhisker
kG2xyHLOC
kG2xyCandlestick
kG2xyTrend
kG2polar $minorpolartype kG2polarArea
kG2polarLine
kG2polarSplineArea
kG2polarSplineLine
kG2meter $minormetertype kG2meterAngular
kG2meterLinear
kG2pie No minor types
When you have placed a Graph2 component on your window, you can set its $majortype in
the Property Manager and select the appropriate minor type. As you change the major and
minor type of the graph, several properties will be shown or hidden according to the graph
type selected.

13
Omnis Graphs

Common Graph Methods

All the graph types have the following methods under the Methods tab in the Property
Manager. More details about each method is supplied later in this section. Note these
methods apply to the window graph object; methods are also available for the non-visual
graph object, described in the second table.

Method Name Returns Description

$addmark() None $addmark(iAxisID, nValue, iColor [,cText,
cFontname, iFontsize]) adds a mark or separator at the
specified axis, value and color; you can add text to the
mark with the specified font name and size
$addtext() None $addtext(cText, iX, iY [,cFontname, iFontsize, iColor,
iAlign, iAngle, bVertical]) adds the specified text
positioned according to the X & Y co-ordinates; this
must be done during the evPreLayout event; the co-
ordinates are taken from the top left of the graph object
and the Y component is inverted so that as Y increases
the text string will appear further down the object
$addzone() None $addzone(iAxisID, iLowerlimit, iUpperlimit,
iFillcolor) adds a zone from the lower and upper limits,
in the color and on the axis specified
$convdate() Integer $convdate(dDatetime) converts a date/time variable to
an integer equivalent which can then be used in graph
data
$dispose() None Disposes the graph and rebuilds it. Useful if you need
to change something other than a property on the graph
which requires it to be rebuilt, such as adding more
layers
$findobject() kTrue for $findobject(iX, iY, iSetno, iItemno [,cSetname,
success cItemname]) obtains the set & item information for the
graph object under the mouse given its position as the
X & Y co-ordinates: see Drilldown
$formatvalue() Char $formatvalue(nValue, cFormatstring) formats a
number/date using the formatting syntax described in
the Parameter Substitution and Formatting section
$getcolors() List $getcolors([PaletteID]) returns a list of RGB colors
used for the graph, or palette if specified, a constant:
kG2paletteDefault, kG2paletteTransparent, or
kG2paletteWhiteOnBlack

14
 Common Graph Methods

Method Name Returns Description

$getmainlayer() Object Returns the main layer object
$redraw() None Redraws the graph
$setcolors() kTrue for $setcolors(lPaletteList) sets the colors for the graph
success using the specified list of RGB colors returned using
$getcolors()
$setlinearscale() None $setlinearscale(iAxisid, nLowerlimit, nUpperlimit,
[,nMajortick, nMinortick, lLabellist]) sets the linear
scale for the specified axis
$setlogscale() None $setlogscale(iAxisid, [cFormatstringORLowerlimit,
nUpperlimit, ,cMajortick, nMinortick, nLabellist]) sets
the log scale for the specified axis
$snapshot() Picture $snapshot([iWidth, iHeight]) captures a snapshot of the
graph with the specified width & height in pixels;
omitting the parameters will return an image with the
same dimensions as the current graph; the $snapshot()
method causes the evPrelayout event to occur which
allows you to add layers; see Graph Layers section
below

The following method is available for the non-visual graph object, that is, object variables
based on the Graph2 object.

Method Name Returns Description

$prelayout() None Available for object variables based on Graph2
component only; called during construction of the
graph enabling layers to be added; see Graph Layers
section below

15
Omnis Graphs

XY Charts
The XY chart type has several subtypes, which all share the following properties and
methods.

XY chart properties
Property Name Data Type Description
$datacombine Constant The combine method of the data for Bar, Area, and
Line graphs, a constant: kG2dataSide,
kG2dataStack, kG2dataOverlay,
kG2dataPercentage; these constants can also be
used in the $addarealayer(), $addbarlayer(), and
$addlinelayer() XY chart methods
$3ddepth Integer Specifies the depth of a 3d XY chart; the default is
–1 but can be set to a positive integer value to
specify a custom depth which is useful for 3d line
and area graphs with multiple series
$hgridcolor RGB Color The horizontal grid color
$minorxytype Constant The minor type of a kG2xy graph; can be one of the
following: kG2xyBar, kG2xyLine, kG2xyScatter,
kG2xyArea, kG2xyBoxWhisker, kG2xyHLOC,
kG2xyCandleStick
$offsetheight Integer The additional offset height of the graph
$subtitle Character The subtitle of the graph
$swapxy Boolean if true the X & Y axis are swapped
$xaxisontop Character if true the X axis is to be displayed on the top
$xaxiswidth Integer Width of the X axis in pixels
$y2axistitle Character Y2 axis title
$yaxisonright Character if true the Y axis is to be displayed on the right
$yaxiswidth Integer Width of the Y axis in pixels
$layereffect Constant The effect for all layers, a constant:
kG2effectNone, kG2effectGlass,
kG2effectSoftLight
$layereffectalign Constant The alignment or direction for the effect for all
layers, as set by $layereffect; a constant:
kG2alignTop, kG2alignBottom, kG2alignLeft,
kG2alignCenter, kG2alignRight

16
 XY Charts

Property Name Data Type Description

$plotareacolorend RGB Color The end gradient color for the plot area
$plotareacolorstart RGB Color The start gradient color for the plot area
$vgridcolor RGB Color The vertical grid color

XY chart methods
All the following methods can only be executed during the evPreLayout event; see below
for details.

Method Name Returns Description

$addarealayer() Integer $addarealayer(pList [,iCombineType]) adds an area
layer to the graph; pList is the area data*
$addbarlayer() Integer $addbarlayer(pList [,iCombineType]) adds a bar
layer to the graph; pList is the bar data*
$addboxwhiskerlayer() Integer $addboxwhiskerlayer(pList) adds a box whisker
layer to the graph; pList is the box whisker data*
$addcandlesticklayer() Integer $addcandlesticklayer(pList) adds candlestick layer
to the graph; pList is the candlestick data*
$addhloclayer() Integer $addhloclayer(pList) adds a HLOC layer to the
graph; pList is the HLOC data*
$addlinelayer() Integer $addlinelayer(pList [,iCombineType]) adds a line
layer to the graph; pList contains the Line data*
$addscatterlayer() Integer $addscatterlayer(pList [,pSymbol, pSymbolSize])
adds a scatter layer to the graph.; pList is the scatter
data*; pSymbol is an optional symbol type (of type
kG2symbolXXX, defaults is kG2symbolSquare);
pSymbolSize is the symbol size, default is 10.
$addtrendlayer() Integer $addtrendlayer(pList) adds a trend layer to the
graph using the data in pList*
$getxaxis() Object $getxaxis([bSecondAxis]) returns the x-axis object,
or the x2-axis object if bSecondAxis is true; only
available during prelayout
$getyaxis() Object $getyaxis([bSecondAxis]) returns the y-axis object,
or the y2-axis object if bSecondAxis is true; only
available during prelayout
* See appropriate chart section below for the format of the data in pList. In addition, see
$datacombine for details of the various data combine types available.

17
Omnis Graphs

List data structure for XY charts

Bar Charts
The bar chart is one of the most common forms of chart. The list format is one row per
series with the first column being the group name followed by the data for each group. You
can build the list data for your graph from a database or construct it on the fly: you need to
use the $define() method to specify the columns in your list, and you can use $add() (or the
SQL database list methods) to build the list line by line.
The following method will construct the list data for a simple bar chart.
; define vars listGraph (List), Name (Char), Sales (Long Int),
Expenses (Long Int)
Do listGraph.$define(Name,Sales,Expenses)
Do listGraph.$add('Andy',85000,20000)
Do listGraph.$add('Sam',80000,15000)
Do listGraph.$add('Lisa',92000,34000)
Do listGraph.$add('Harry',45000,15000)
The list variable listGraph is specified as the $dataname of the graph field. The above
method will create a graph of two groups each with four series:

Note you can use the Omnis 4GL commands to build the list data for the graph, either from
an Omnis database, a SQL database, or on-the-fly, such as the following:
Set current list listGraph
Define list {(Name,Sales,Expenses)}
Add line to list {('Andy',85000,20000)}
Add line to list {('Sam',80000,15000)}
Add line to list {('Lisa',92000,34000)}
Add line to list {('Harry',45000,15000)}

18
 XY Charts

Line/Area Charts
The line and area chart in their data representation are very similar to the bar chart. So given
the following data:
; define vars listGraph (List), colList (List), Name (Char), and use
built-in #vars
Do listGraph.$define(Name,#1,#2,#3,#4,#5,#6,#7,#8,
#9,#10,#11,#12,#13,#14,#15,#16,#17,#18,#19,#20)
Do listGraph.$add('Andy',30,28,40,55,75,68,
54,60,50,62,75,65,75,91,60,55,53,35,50,66,56,48,52,65,62)
Do listGraph.$add('Liza',48,52,65,62,30,68,54,60,
50,28,40,55,75,62,75,65,75,35,50,66,56,91,60,55,53)
; now build the column headings list
Do colList.$define(#1,#2,#3,#4,#5,#6,#7,#8,#9,#10,#11,#12,
#13,#14,#15,#16,#17,#18,#19,#20)
Do colList.$add(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20)
Note the use of the colList list in the portion of code, which can be assigned to the
$columnheadings property of the graph field, overriding the normal x-axis variable names.
You should set the $majortype and minor type properties ($minorxytype or
$minorpolartype) of the graph to specify its type and subtype. The above method will
display the following line or area graph:

3d Line chart 3d Area chart

$majortype=kG2xy, $minorxytype=kG2xyLine $majortype=kG2xy, $minorxytype=kG2xyArea

19
Omnis Graphs

Scatter Charts
Each individual row in the chart list data represents a new plot (or series). The X & Y plot
positions are then represented in two columns. Additional columns represent the other
groups, so given the following data:
Do listGraph.$define(Name,#1,#2,#3,#4)
Do listGraph.$add('Pt1',10,130,5,100)
Do listGraph.$add('Pt2',15,150,12,95)
Do listGraph.$add('Pt3',6,80,8,105)
Do listGraph.$add('Pt4',12,110,7,82)
Do listGraph.$add('Pt5',10.5,125,10.5,99)
There are two groups of five series which will result in the following chart:

Note that the symbols used to represent each series are in the order of square, diamond,
triangle, right-triangle, left-triangle, inverted triangle, circle, cross, and cross #2.

20
 XY Charts

Box Whisker Charts

Box whisker charts represent data ranges as boxes and/or marks. A common application is
to represent the maximum, 3rd quartile, median, 1st quartile and minimum values of some
statistics.
Each individual row in the chart list data represents each series.
Do listGraph.$define(Name,#1,#2,#3,#4,#5)
Do listGraph.$add('',55,70,80,40,62)
Do listGraph.$add('',60,80,90,45,70)
Do listGraph.$add('',50,65,75,40,60)

Gantt Charts
You can create Gantt charts using a Box Whisker chart and setting the $swapxy property to
kTrue so the bars are displayed horizontally. For Gantt charts you only need to provide two
groups of data in your list. The example Graph2 library contains a simple Gantt chart, as
follows:

21
Omnis Graphs

The following method is executed in the $construct() of the Gantt chart window:
; define inst vars: iGraphList (List), Name (Char)
Do iGraphList.$define(Name,#1,#2)
Do method $addline ('Market Research',2004,8,16,14)
Do method $addline ('Define Specifications',2004,8,30,14)
Do method $addline ('Overall Architecture',2004,9,13,14)
Do method $addline ('Project Planning',2004,9,20,14)
Do method $addline ('Detail Design',2004,9,27,14)
Do method $addline ('Software Development',2004,10,4,35)
Do method $addline ('Test Plan',2004,10,25,14)
Do method $addline ('Testing and QA',2004,11,1,21)
Do method $addline ('User documentation',2004,11,8,14)
The $addline() class method is:
; Params: p1 (Char) p2-p5 (Long Int)
; Local var: chartdate (Date time D m y)
Calculate Name as p1
Calculate chartdate as dat(con(p2,"-",p3,"-",p4),"Y-M-D")
Calculate #1 as $cinst.$objs.ganttChart.$convdate(chartdate)
Calculate chartdate as dadd(kDay,p5,chartdate)
Calculate #2 as $cinst.$objs.ganttChart.$convdate(chartdate)
Add line to list
You can use the $convdate() method to convert a date/time variable to an integer equivalent
which can be used in graph data.

High/Low/Open/Close (HLOC) Charts

The HLOC chart is often used to represent financial stock data. Each series consists of four
pieces of information, the highest price, the lowest price, the open price, and the close price.
The volatility is then shown as a vertical line, with the opening price as a horizontal line to
the left and the closing price as a horizontal line to the right.
Do listGraph.$define(Name,#1,#2,#3,#4,#5)
Do listGraph.$add('',2043,1931,2000,1950)
Do listGraph.$add('',2039,1921,1957,1991)
Do listGraph.$add('',2076,1985,1993,2026)

22
 XY Charts

Candlestick Charts
The candlestick chart is very similar to the HLOC chart and the list data is formatted in the
same way. The difference in the graphical representation is that the area between the
opening and closing price is shown as a filled rectangle; in the following example a black
rectangle indicates that the closing price was lower than the opening price (a bad day). Both
examples of the HLOC and Candlestick charts used the same data.

23
Omnis Graphs

Trend Chart
A trend chart allows you to view and compare data values over a given period or within a
group. The first column in the data list contains the name of item and the second column
onwards contains the data values for the item. A trend chart will contain one line for each
row of data in the list.
; iColList is a List var assigned to $columnheadings of the graph
object
Do lReturnList.$define(
lName,#1,#2,#3,#4,#5,#6,#7,#8,#9,#10,
#11,#12,#13,#14,#15,#16,#17,#18,#19,#20)
Do lReturnList.$add(
0,50,55,47,34,42,49,63,62,73,59,
56,50,64,60,67,67,58,59,73,77)
Do iColList.$define(
#1,#2,#3,#4,#5,#6,#7,#8,#9,#10,
#11,#12,#13,#14,#15,#16,#17,#18,#19,#20)
Do iColList.$add(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20)

Data presentation in XY charts

You can change the way data is presented in Bar, Area, and Line graphs using the
$datacombine property, which can be set to one of the following constants: kG2dataSide,
kG2dataStack, kG2dataOverlay, or kG2dataPercentage. When $datacombine is changed the
bars, areas, or lines, and the Y-axis, are redrawn to reflect the selected combine type. The
following example graphs shown how the different combine types affect the presentation of
the same set of data (these graphs are available in the Graph example library).

24
 XY Charts

$datacombine = kG2dataSide: The data sets are $datacombine = kG2dataStack: The data sets
shown as individual bars side-by-side (the default are combined by stacking up the bar segments,
for XY bar charts) therefore showing individual amounts in relation
to the total amount for the data group

$datacombine = kG2dataOverlay: The data sets are $datacombine = kG2dataPercentage shows

overlayed each other providing a clearer each individual amount as a percentage of the
comparison of data than the side-by-side type total for the data group

These different combine types can also be used when adding data layers to a graph using the
$addarealayer(), $addbarlayer(), or $addlinelayer() XY chart methods; see the Graph
Layers section.

25
Omnis Graphs

Pie Charts
Pie charts have the following properties and methods, in addition to the Common graph
properties and methods.

Pie chart properties

Property Name Data Type Description
$depth Integer The depth of the pie (-1 is default)
$depthcolumn Integer The column number (0 if not required) of the depth
values in the list. This can be used to enable different
slice depths
$donutradius Integer The amount of cut out from the center of the pie,
specified as the percentage of the total radius of the pie;
the range is 0-100, with 0 being no donut (the default)
$drawclockwise Boolean if true the slices are drawn clockwise
$feelercolor RGB The feeler color
$feelerwidth Integer The feeler width
$framecolor RGB The color of frame around pie slices, if $frameon is true
$frameon Boolean If true a frame is drawn around each pie slice
$labelformat Character Overrides the default formatting of labels; see section
Parameter Substitution and formatting
$labelpos Integer Position of the labels relative to the edge of the pie, only
used if $labelposon is true
$labelposon Boolean If true $labelpos is enabled
$rotate Number The pie rotation, in degrees
$shadow Boolean If true a pie shadow is displayed
$showfeeler Boolean if true feelers are shown
$sidelayout Boolean If true the labels are displayed by the side of pie
$tilt Integer If $tilton is enabled this contains the degree of tilt
$tilton Boolean if true the tilt is enabled (see $tilt); note $3d has to be
enabled as well to display tilt

26
 Pie Charts

Pie chart methods

Pie charts have the following method(s), in addition to the common methods.

Method Name Returns Description

$slicemove() None $slicemove(iDistance, iSlice [,iSliceend]) moves iSlice
or range of slices (iSlice to iSliceend) the specified
iDistance from the center of the pie; the first slice in the
chart is value 0; to move non-adjacent slices, iSlice
should be a comma-separated list of slices, e.g.
.$slicemove(iDistance,’0,2’) to move slices 1 and 3

Note that some ‘actions’ on a pie chart are controlled by setting a particular property, such
as $tilt; see the previous section for pie chart properties. Note also that you cannot add
layers to a pie chart using methods, such as those used on XY and Polar charts.

List data structure for Pie charts

The following list data will result in the graph shown.
Do listGraph.$define(Name,Sales )
Do listGraph.$add('Andy',85)
Do listGraph.$add('Sam',80)
Do listGraph.$add('Liza',92)
Do listGraph.$add('Harry',45)

Pie charts have several properties that allow you to alter the appearance of the chart, such as
$tilt and $rotate. These can be used together with a set of sliders to create a dynamic
representation of the user’s data. See the Graph2 example in the Welcome screen when
Omnis starts up (click the New Users button on the main Omnis toolbar) – the Graph2
example application shows many effects for Pie charts.

27
Omnis Graphs

The code behind the slider can change the appropriate property in the pie chart, such as the
following, which allows the user to change the tilt of the pie chart:
; $event method for Tilt slider
; $min and $max of slider component are set to 0 and 100
On evNewValue
Calculate $cinst.$objs.GR.$tilt as pNewVal
The following code for a slider component allows the user to change the rotation of the
chart.
; $event method for Rotate slider
; $min and $max of slider component are set to 0 and 360
On evNewValue
Calculate $cinst.$objs.GR.$rotate as pNewVal
In addition, the $slicemove(iDistance, iSlice) method lets you move or ‘slice out’ one of the
slices in the pie chart. For example, the Slice move slider in the above window has the
following method:
; $event method for Slice-move slider
; $min and $max of slider component are set to 0 and 50
On evNewValue
Do $cinst.$objs.GR.$slicemove(pNewVal,’0,2’) ;; items 1 and 3
Using a combination of properties you can create some good effects for Pie charts. The
following pie chart uses $sidelayout set to kTrue, a custom $labelformat, and $slicemove is
set to slice out the first and the third slices in the chart.

28
 Polar Charts

Polar Charts
The Polar chart has the following properties and methods, in addition to the Common graph
properties and methods.

Polar chart properties

Property Name Data Type Description
$angularcolor RGB color Color of angular grid
$angularlabelson Boolean If true labels are shown on the angular axis
$angularwidth Integer Width of the angular grid
$circulargrid Boolean If true the grid is circular, otherwise the default is
polygonal
$minorpolartype Constant The minor type for kG2polar type graphs; can be
one of the following: kG2polarArea, kG2polarLine,
kG2polarSplineArea, kG2polarSplineLine
$radialcolor RGB color Color of radial grid
$radiallabelson Boolean If true labels are shown on the radial axis
$radialwidth Integer Width of the radial grid

29
Omnis Graphs

Polar chart methods

The following methods must only be executed during the evPreLayout event; see below for
details.

Method Name Returns Description

$addarealayer() None $addarealayer(pList [,iCombineType]) adds an area
layer to the graph; pList is the area data*
$addlinelayer() None $addlinelayer(pList [,iCombineType]) adds a line
layer to the graph; pList contains the Line data*
$addsplinearealayer() None $addsplinearealayer(pList [,pSymbol, pSymbolSize])
adds a spline area layer to the graph; pList is the
spline area data list (same format as all polar charts)
$addsplinelinelayer() None $addsplinelinelayer(pList [,pSymbol, pSymbolSize])
adds a spline line layer to the graph; pList is the
spline line data list (same format as all polar charts)
$getradialaxis() Object $getradialaxis() returns the radial axis object

* See appropriate chart section for the format of the data in pList. In addition, see
$datacombine for details of the various data combine types available.

List data structure for Polar charts

The data points in a polar chart are plotted using polar co-ordinates (radius,angle) whereby
radius is the distance or amount from the center of the chart and angle is the relative angle
with reference to the "12 o'clock position" in the chart. The first three columns in the Omnis
list for a polar chart should therefore be Name (Label), Amount, Angle. If the angle is
omitted from the list data, then the data points are distributed evenly around the chart. For
example, consider the following data:
; define listGraph (List), Name (Char), Score (Long int)
Do listGraph.$define(Name,Score)
Do listGraph.$add("Speed",90)
Do listGraph.$add("Reliability",60)
Do listGraph.$add("Comfort",65)
Do listGraph.$add("Safety",75)
Do listGraph.$add("Efficiency",40)

30
 Polar Charts

Will give the following polar chart:

Note the following properties are set for the

chart:
$majortype = kG2polar, $minorpolartype =
kG2polarArea,
$legendpos = kG2legendManual, $legendx &
$legendy = 10,
$angularlabelson = kTrue, $offsetwidth = 30,
$angularcolor = 187,187,255, $radialcolor =
153,153,255,
$maintitle = ‘Speed Reliability Test’

Adding layers to a polar chart

To draw a second set of data in a polar chart, from a second list perhaps, you can add the
additional data in a layer over the first set of data. You can add layers to charts during the
evPrelayout event which is triggered as the graph component is instantiated.
Consider the following example. The first set of data is constructed in the $construct()
method of the graph window: the second set of data is added as a layer.
; $construct() method for graph window
; define listGraph (List), listNames (List), Name (Char)
Do listGraph.$define(Name,#1,#3)
Do listGraph.$add("",90,15)
Do listGraph.$add("",25,60)
Do listGraph.$add("",40,110)
Do listGraph.$add("",55,180)
Do listGraph.$add("",68,230)
Do listGraph.$add("",44,260)
Do listGraph.$add("",79,260)
Do listGraph.$add("",85,310)
Do listGraph.$add("",50,340)
; $columnheadings of graph is set to listNames
Do listNames.$define(#S1)
Do listNames.$add("Closed loop")
The second data set is constructed during the evPrelayout event for the graph object and
added as a line layer using the $addlinelayer() method.

31
Omnis Graphs

; $event() method for graph window object

; define listLayer2 (List), local vars lLayer and OpenLoop
On evPreLayout
Do listLayer2.$define(Name,OpenLoop,#1)
Do listLayer2.$add("",80,40)
Do listLayer2.$add("",91,65)
Do listLayer2.$add("",66,88)
Do listLayer2.$add("",80,110)
Do listLayer2.$add("",92,150)
Do listLayer2.$add("",87,200)
Do $cinst.$objs.GROBJ.$getmainlayer() Returns lLayer
Do lLayer.$setlinewidth(2)
Do lLayer.$setsymbol(kG2symbolTriangle,11)
Do lLayer.$setdatalabelformat("({value},{angle})")
Do listNames.$define(#S1)
Do listNames.$add("Open loop")
Do $cinst.$objs.GROBJ.$addlinelayer(listLayer2) Returns lLayer
Do $cinst.$objs.GROBJ.$setlinearscale(kG2axisAngular,0,360,30)
Do lLayer.$setlinewidth(2)
Do lLayer.$setcloseloop(kFalse)
Do lLayer.$setsymbol(kG2symbolDiamond,11)
Do lLayer.$setDataLabelFormat("({value},{angle})")
The above code produces the following graph:

32
 Meter Charts

Meter Charts
You can create Linear or Angular (radial) meter charts, and change their appearance using a
range of properties and methods. Meter charts have the following properties and methods,
in addition to the common graph properties and methods.

Meter chart properties

Property Name Data Type Description
$minormetertype Constant The minor type for meter charts, a constant:
kG2meterLinear, kG2meterAngular
$linearalignment Constant The alignment for linear meter charts, a constant:
kG2alignTop, kG2alignBottom, kG2alignLeft,
kG2alignRight, kG2alignCenter
$angulardegrees Integer The start and end degrees for an angular chart in the
form n,n, the default is 0,360
$angularpositionh Integer The horizontal position of the center (start) of an
angular meter chart; the default is 50 which centers
the chart horizontally
$angularpositionv Integer The vertical position of the center (start) of an
angular meter chart; the default is 50 which centers
the chart vertically
$majortickwidth Integer The width of the major tick in pixels; the default is 1
$microtickwidth Integer The width of the micro tick in pixels; the default is 1
$minortickwidth Integer The width of the minor tick in pixels; the default is 1
$pointercolor RGB color The color of the pointer for a meter chart

Changing the minor type for Meter charts

You can change the minor type of a meter graph using the following method:
Do $cinst.$objs.meterGraph.$minormetertype.$assign(kG2meterAngular)
or
Do $cinst.$objs.meterGraph.$minormetertype.$assign(kG2meterLinear)

33
Omnis Graphs

Meter chart methods

Meter charts have the following methods in addition to the common methods.

Method Name Returns Description

$addpointer() None $addpointer(nValue, iColor [,nPointertype]) adds a
pointer to a meter chart with the specified value and
color; this must be done during the evPreLayout
event; the pointer type is a number in the range 0-5;
see the Adding Pointers section below
$addring() None $addring(iStartradius, iEndradius, iFillcolor) adds a
colored ring to an angular meter with the specified
start and end radius in pixels; this must be done
during the evPreLayout event; you can use this to add
a colored band or a number of bands around a
standard meter dial; you can color the entire face by
setting the start radius to zero and the end radius to
beyond the meter ticks

List data structure for Meter charts

The Meter chart type (kG2meter) lets you create Angular and Linear meters to represent
single data points. The properties of the meter type let you specify analog and digital read
outs, colored backgrounds, multiple pointers per chart, pointers of different shapes, and so
on. The example library demonstrates angular/radial and linear charts.
The data in the list associated with the graph object is used to specify the data point and
various properties of the graph, as follows:
Do iGraphList.$add(45.17) ;; the data point
Do iGraphList.$add(0) ;; scale start
Do iGraphList.$add(100) ;; scale end
Do iGraphList.$add(10) ;; major tick interval
Do iGraphList.$add(5) ;; minor tick interval
Do iGraphList.$add(1) ;; micro tick interval

34
 Meter Charts

The example library uses the above data to create the following chart:

Note that this and the next meter chart has colored zones defined on the scale; these are
described on the Adding Colored Zones section.
When the minor type is set to kG2meterLinear, the following method:
Do iGraphList.$add(75.35)
Do iGraphList.$add(0)
Do iGraphList.$add(100)
Do iGraphList.$add(10)
Can be used to build the following linear chart:

Adding Pointers
The standard meter chart represents a single data point, which is shown using the default
pointer, but you can add one or more additional pointers to a chart to show other data. You
can add extra pointers to a meter chart (angular or linear) using the $addpointer() method,
which must be executed during the evPreLayout event for the graph object; see the Graph
Layers section for information about evPreLayout.
! $addpointer(nValue, iColor [,nPointertype])
adds a pointer to an angular or linear meter chart with the specified value and color;
this must be done during the evPreLayout event; the pointer type is a number in the
range 0-5, as follows:

35
Omnis Graphs

0 Pencil pointer (the default pointer for linear charts)

1 Diamond pointer (the default pointer for angular charts)
2 Triangular pointer
3 Arrow with square ends
4 Arrow with sharp/pointed ends
5 Line pointer

The different pointer styles are shown in the following linear chart:

The following method adds two pointers to an angular chart:

On evPreLayout
If iAddpointer ;; var behind checkbox on window
Do $cinst.$objs.meterGraph.$addpointer(30,kGreen,2) ;; triangle
Do $cinst.$objs.meterGraph.$addpointer(10,kMagenta,5) ;; line
End If
;; etc
The method produces the following chart:

36
 Meter Charts

Adding Rings
A ring is the region in an Angular chart between two concentric circles. You can add rings
to an Angular chart using the $addring() method, which is useful for adding circular borders
and backgrounds to a meter; this must be done during the evPreLayout event.
! $addring(iStartradius, iEndradius, iFillcolor)
adds a colored ring to an angular meter with the specified start and end radius in pixels
The difference between the start and end radius is, in effect, the width or thickness of the
ring in pixels. If you use a start radius of zero, the ring will be drawn starting from the
center of the chart face and, depending on the value of the end radius, will draw a circle on
the chart with the given radius.
The example library demonstrates adding a ring to a radial meter chart, and uses the
following method, which is added to the $event() method for the graph window object:
On evPreLayout
Do $cinst.$objs.meterGraph.$addring(
173-abs(iBackgroundRaised),
174-abs(iBackgroundRaised),
$cinst.$objs.ringColor.$contents)
; etc...
Which produces the following chart; note the ring has been changed to red using the color
picker:

In the example library, the start and end radius settings for the $addring() method take
account of the raised background, since when the background is raised or inset by any
amount, the radius of the meter dial is reduced by the same amount. The color for the ring is

37
Omnis Graphs

taken from the color picker, which is returned in the value of the $contents property of the
color picker button.
A ring must be added to a meter chart during the evPreLayout event, which is triggered
following a $dispose() method for the graph object. For example, the method for the color
picker in the example library is as follows:
On evClick
Do $cinst.$objs.meterGraph.$dispose()
This causes the $event() method for the graph window object to be called and the
evPreLayout event is triggered, which in this case runs the method to add the ring.

Graph Layers and the Prelayout Event

You can add multiple layers to certain types of XY and Polar graph using the
$add<layertype> methods during the Prelayout event (evPreLayout) event, which is
triggered just before the graph instance is created in a window. Note you cannot add layers
to Pie charts.
You can add layers to any type of XY or Polar chart using one of the $add<layertype>
methods. In theory, any combination of chart type and layer is possible within the major XY
and Polar types, but not all combinations are that meaningful. It largely depends on what
type of data you are trying to represent or what data sets you might want to compare by
showing the data sets as different layers.

Adding layers to charts

You can specify how the layer data is combined with or added to the graph using one of the
data combine type constants as follows:
kG2dataOverlay The additional data layer is added on top of the
existing graph data
kG2dataPercentage The existing and additional data sets are combined
and scaled so each adds up to 100
kG2dataSide The existing and additional data sets are shown side
by side
kG2dataStack The additional data set is stacked on top of the
existing graph data

38
 Graph Layers and the Prelayout Event

For example, in the case of the High/Low/Open/Close charts, it is quite common in financial
applications to draw a line between the open and close points. This can be achieved by
adding a line layer during the evPreLayout event using the $addlinelayer() method, as
follows:
; $event() method for graph window object
; define var: lineLayer (List)
On evPreLayout
Do lineLayer.$define(Name,#1,#2,#3)
Do lineLayer.$add('',1950,1991,2026) ;; Closing prices
Do $cinst.$objs.GraphObj.$addlinelayer(lineLayer, kG2dataOverlay)
Refer to the appropriate layers section for the exact format of the list. The above method
will result in the following graph:

When using an object variable based on the Graph2 component you can use the
$prelayout() method in the object to add layers in the same way as described above.
Caution: A word of warning, evPreLayout events occur during the construction of a graph
image which typically happens during the drawing of the graph control. This can make
debugging the graph object’s $event() method potentially troublesome.

39
Omnis Graphs

Graph Clicks and Drilldown

The Graph2 window component reports an evGraphClick event when the user clicks on the
object. The event returns the following event parameters:

pItem The number of the item or data point clicked on within

the current data set or group; the first item or data point
is 1, the second is 2, and so on.
pItemname The name of the data point clicked on.
pSet The number of the data set or group clicked on; the first
set or group is 1, the second is 2, and so on.
pSetname The name of the data set or group clicked on.

For example, using the following method behind the $event() method of the graph object:
; the $event() for the graph object
On evGraphClick
OK message
{Graph Click =
// Item Number [pItem] (Name = [pItemname])
// Set Number [pSet] (Name = [pSetname])}
And clicking on the first item in the second set or group of the following graph

Will give the following message:

Graph Click =
Item Number 1 (Name = Andy)
Set Number 2 (Name = Expenses)
You can use the item and set number/name information to drilldown into the data by
reformatting the list data and redrawing the graph.
Note that pSet and pSetname are not valid for pie charts since they represent a single set of
data only.

40
 Changing the Color of Graph elements

Changing the Color of Graph elements

The methods $getcolors() and $setcolors() allow you to get and set the color of elements
within a graph at runtime. $getcolors() returns a list containing the RGB color of each
element in the current graph.
The first eight color values in the color list have special significance. The first three palette
colors are the background color, default line color, and the default text color of the chart.
The fourth to seventh palette colors are reserved for future use. The eighth color is a special
dynamic color indicating the “current data set”. The ninth color (index = 8) and subsequent
colors in the list represent the elements in the graph, such as lines and text objects.
In a pie chart, Omnis will automatically use the ninth color for the first slice, the tenth color
for the second slice, and so on. Similarly, for a multi-line chart, Omnis will use the ninth
color for the first line, the tenth color for the second line, and so on.
The $setcolors() method allows you to set the color of any element in the graph. For
example, the following method will set the color of the first data element in the chart to
black (value 0):
; define local var: lColorList (List)
Do $cinst.$objs.GR.$getcolors() Returns lColorList
Calculate lColorList.9.1 as 0 ;; 0 = black
Do $cinst.$objs.GR.$setcolors(lColorList)
You can return the color palette for a graph by specifying one of the palette constants in the
$getcolors([PaletteID]) method. The constants are: kG2paletteDefault,
kG2paletteTransparent, or kG2paletteWhiteOnBlack (the latter inverts the black and white
colors in the graph). The following method can be used to switch to a transparent color
palette for a graph:
; define local var: lColorList (List)
Do $cinst.$objs.polarGraph.$getcolors(kG2paletteTransparent) Returns
lColorList
Do $cinst.$objs.polarGraph.$setcolors(lColorList)
The following method can be used to switch the graph colors back to the default palette,
perhaps after having colored individual elements or switching the whole graph palette to
transparent or White-on-black:
Do $cinst.$objs.polarGraph.$getcolors(kG2paletteDefault) Returns
lColorList
Do $cinst.$objs.polarGraph.$setcolors(lColorList)

41
Omnis Graphs

Adding Colored Zones

A zone is a color band on the back of the plot area. Like marks, zones can be horizontal or
vertical. They are particularly useful for marking different parts of the scale on a meter
chart, or adding bands of color behind a bar, area or line chart.
You can add zones to the background of a chart using the $addzone() method; this must be
done in the evPreLayout event. For example, the following method can be used to set the
color for different parts of the scale on a linear meter.
On evPreLayout
Do $cinst.$objs.meterGraph.$addzone(0,50,kGreen)
Do $cinst.$objs.meterGraph.$addzone(50,80,kYellow)
Do $cinst.$objs.meterGraph.$addzone(80,100,kRed)
; etc…
This method produces the following chart.

Parameter Substitution and Formatting

Charts often contain a lot of text strings, such as sector labels in pie charts, axis labels for
XY charts, data labels for the data points, graph titles, and so on. You can substitute many
of these parameters to allow you to configure precisely the information contained in the text
and their format. For example, when drawing a pie chart with side label layout, the default
sector label format is:
"{label} ({percent}%)"
In drawing the sector labels, the graph component will replace "{label}" with the sector
name, and "{percent}" with the sector percentage. So the label will be something like:
"ABC (34.56%)"
You can change the sector label format by changing the format string. For example, you can
change it to:
"{label}: US${value}K ({percent}%)"
The sector value will then be something like:
"ABC: US$123 (34.56%)"

42
 Parameter Substitution and Formatting

Here is an example method that changes the $labelformat property in a pie chart.
Calculate $cinst.$objs.GROBJ.$labelformat as con("{label}
${value}K",chr(10),"({percent}%)")

Pie chart with default labels Same pie chart with modified labels

For fields that are numbers, dates, or times, the Graph component supports a special syntax
in parameter substitution to allow formatting of these values. Please refer to the Number
Formatting and Date/Time Formatting sections below for details.
The following tables describe the fields available for various chart objects.

Parameters for Pie charts

Parameter Description
sector The sector number. The first sector is 1, the second is 2,
and so on.
dataSet Same as {sector}. See above.
label The text label of the sector.
dataSetName Same as {label}. See above.
value The data value of the sector.
percent The percentage value of the sector.

Parameters for all XY Chart Layers

The following are parameters that apply to all XY Chart layers in general. Some layer types
may have additional parameters (see below).
Note that some parameters do not apply in certain cases. For example, when specifying the
aggregate label of a stacked bar chart, the {dataSetName} parameter does not apply,

43
Omnis Graphs

because a stacked bar is composed of multiple data sets. It does not belong to any particular
data set and hence does not have a data set name.

Parameter Description
x The x value of the data point.
xLabel The bottom x-axis label of the data point.
x2Label The top x-axis label of the data point.
value The value of the data point.
accValue The accumulative value of the data point. This is useful for stacked
charts, such as stacked bar chart and stacked area chart.
totalValue The total value of all data points. This is useful for stacked charts, such
as stacked bar chart and stacked area chart.
percent The percentage of the data point based on the total value of all data
points.
accPercent The accumulated percentage of the data point based on the total value
of all data points. This is useful for stacked charts, such as stacked bar
chart and stacked area chart.
dataSet The data set number to which the data point belongs. The first data set
is 1, the second is 2, and so on.
dataSetName The name of the data set to which the data point belongs.
dataItem The data point number within the data set. The first data point is 1, the
second is 2, and so on.
dataGroup The data group number to which the data point belongs. The first data
group is 1, the second is 2, and so on.
dataGroupName The name of the data group to which the data point belongs.
layerId The layer number to which the data point belongs. The first layer is 1,
the second is 2, and so on.

44
 Parameter Substitution and Formatting

Additional Parameters for HLOC and

CandleStick Layers
The following are in addition to the parameters for all XY Chart layers.

Parameter Description
high The high value of the data representation.
low The low value of the data representation.
open The open value of the data representation.
close The close value of the data representation.

Additional Parameters for Box Whisker Layers

The following are in addition to the parameters for all XY Chart layers.

Parameter Description
top The value of the top edge of the box-whisker symbol.
bottom The value of the bottom edge of the box-whisker symbol.
max The value of the maximum mark of the box-whisker symbol.
min The value of the minimum mark of the box-whisker symbol.
med The value of the median mark of the box-whisker symbol.

Additional Parameters for Trend Layers

The following are in addition to the parameters for all XY Chart layers.

Parameter Description
slope The slope of the trend line.
intercept The y-intercept of the trend line.
corr The correlation coefficient in linear regression analysis.
stderr The standard error in linear regression analysis.

45
Omnis Graphs

Parameters for Polar Charts

Parameter Description
radius The radial value of the data point.
value Same as {radius}. See above.
angle The angular value of the data point.
x Same as {angle}. See above.
label The angular label of the data point.
xLabel Same as {label}. See above.
name The name of the layer to which the data point belongs.
dataSetName Same as {name}. See above.
i The data point number. The first data point is 1, the second is 2,
and so on.
dataItem Same as {i}. See above.

The following method sets the label for the data points in a polar chart.
Do $cinst.$objs.GROBJ.$getmainlayer() Returns lLayer
Do lLayer.$setdatalabelformat("({value},{angle})")

Parameters for Axis

Parameter Description
value The axis value at the tick position.

Number Formatting
For parameters that are numbers, the Graph component supports a number of formatting
options in parameter substitution.
For example, if you want a numeric field (value) to have a precision of two digits to the
right of the decimal point, use ',' (comma) as the thousand separator, and use '.' (dot) as the
decimal point, and you may use (value|2,.). The number 123456.789 will therefore be
displayed as 123,456.79.

46
 Parameter Substitution and Formatting

For numbers, the formatting options are specified using the following syntax:
([param]|[a][b][c][d])
where:

Parameter Description
[param] The name of the parameter
[a] An integer specifying the number of digits to the right of the decimal
point. The default is automatic. To use the default, simply skip this
parameter.
[b] The thousand separator. Should be a non-alphanumeric character (not
0-9, A-Z, a-z). Use '~' for no thousand separater.
[c] The decimal point character.
[d] The negative sign character. Use '~' for no negative sign character.

You may skip the trailing formatting options if they are needed. For example, (value|2)
means formatting the value with two digits to the right, where the thousand separator,
decimal point character, and negative sign character are all using the default settings of the
chart.

Date/Time Formatting
For parameters that are dates & times, the formatting options can be specified using the
following syntax:
([param]|[datetime_format_string])
where [datetime_format_string] must start with an alphabetic character (A-Z or a-z), and
may contain any characters except ')'. Certain characters are substituted according to the
following table:
Parameter Description
yyyy Year in 4 digits (e.g. 2005)
yyy Year showing only the least significant 3 digits (e.g. 007 for the year 2007)
yy Year showing only the least significant 2 digits (e.g. 07 for the year 2007)
y Year showing only the least significant 1 digit (e.g. 7 for the year 2007)
mmm Month formatted as its name. The default is to use the first 3 characters of the
English month name (Jan, Feb, Mar ...).
mm Month formatted as 2 digits from 01 - 12, with leading zero if necessary.
m Month formatted using the minimum number of digits from 1 - 12.
dd Day of month formatted as 2 digits from 01 - 31, with leading zero if

47
Omnis Graphs

Parameter Description
necessary.
d Day of month formatted using the minimum number of digits from 1 - 31.
w The name of the day of week. The default is to use the first 3 characters of the
English day of week name (Sun, Mon, Tue ...).
hh The hour of day formatted as 2 digits, adding leading zero if necessary. The 2
digits will be 00 - 23 if the 'a' option (see below) is not specified, otherwise it
will be 00 - 12.
h The hour of day formatted using the minimum number of digits. The digits
will be 0 - 23 if the 'a' option (see below) is not specified, otherwise it will be
0 - 12.
nn The minute formatted as 2 digits from 00 - 59, adding leading zero if
necessary.
n The minute formatted using the minimum number of digits from 00 - 59.
ss The second formatted as 2 digits from 00 - 59, adding leading zero if
necessary.
s The second formatted using the minimum number of digits from 00 - 59.
a Display either 'am' or 'pm', depending on whether the time is in the morning
or afternoon.

For example, a parameter substitution format of (value|mm-dd-yyyy) will display a date as

something similar to 09-15-2002. A format of (value|dd/mm/yy hh:nn:ss a) will display a
date as something similar to 15/09/02 03:04:05 pm.

Further formatting options

You can use a type of Mark Up Language (supported in the underlying graph engine and
called ChartDirector Mark Up Language or CDML) to include formatting information in
text strings by marking up the text with tags. This Mark Up Language allows a single text
string to be rendered using multiple fonts, with different colors, and even embed images in
the text. CDML is supported in all text objects including chart titles, legend keys, axis
labels, data labels, and so on.
Font Styles
You can change the style of the text by using special tags. For example, the following code
substitutes some of the parameters and formats the fonts using tags:
Calculate $cinst.$objs.GR.$labelformat as
con("<*font=timesi.ttf,size=16,color=FF0000*>{label}
${value}K",chr(10),
"<*font=arial.ttf,size=12,color=8000*>({percent}%)")

48
 Parameter Substitution and Formatting

In general, all tags in CDML are enclosed by <* and *>. Attributes within the tags
determine the styles of the text following the tags within the same block. If you want to
include <* in text without being interpreted as CDML tags, use <<* as the escape sequence.
The following font style attributes can be used:
! font
The font file name.
! size
The font size.
! width
The font width. This attribute is used to set the font width and height to different
values. If the width and height are the same, use the size attribute.
! height
The font height. This attribute is used to set the font width and height to different
values. If the width and height are the same, use the size attribute.
! color
The text color in hex format.
! underline
The line width of the line used to underline the following characters. Set to 0 to disable
underline.

Embedding Images
You can embed images in text using the <*img*> tag and the following syntax:
<*img=my_image_file.png*>
You can use the $imagesearchpath property (on the Preference tab) to specify the folder
where the Graph component will search for images (on Mac OS X the property uses a
standard HFS colon-separated pathname). If you leave the property blank (the default), the
component sets the search path to the icons folder in the Studio tree, which means your
image file must be located in this folder. Having set the image search path you can use the
image file name only in the <*img*> tag. For example, the line:
; set $imagesearchpath to C:\Program Files\RainingData\OS43\images
Calculate $cinst.$objs.GR.$labelformat as con(
"{label} ${value}K",chr(10),
"({percent}%)",chr(10),"<*img= sun_bullet.gif*>")
embeds the image file sun_bullet.gif which is located in the Omnis\images folder.

49
Omnis Graphs

Labels
You can override the default fonts for the main title and labels in a graph by setting the
$titlefont and $labelfont properties (found under the Custom tab in the Property Manager).
You can specify any true type font (TTF) or True type collection (TTC) that is located in
the Fonts folder in the main Omnis folder. If a folder called ‘Fonts’ does not exist you can
create one with this name. If you add fonts to this folder, you have to restart Omnis before
the fonts become available in Omnis.
The default value is set to “(DEFAULT)” which means the default font for your system will
be used (e.g. Times Roman under Windows). You can adjust the height or size of the main
graph title by setting the $titlefontheight property.

Adding Text to a Chart

You can add text to a chart using the $addtext() method, but this must be done during the
evPreLayout event.
! $addtext(cText, iX, iY [,cFontname, iFontsize, iColor, iAlign, iAngle, bVertical])
adds the specified text positioned according to the X & Y co-ordinates
The X & Y co-ordinates are taken from the top left of the graph object, but the Y
component is inverted, so that as Y increases the text string will appear further down the
chart. The following method adds some text to a Linear meter chart. Note the
$formatvalue() method is used to format a number before it is added.
On evPreLayout
Calculate lTextToAdd as
$cinst.$objs.meterGraph.$formatvalue(75.35,"2")
Do $cinst.$objs.meterGraph.$addtext(
lTextToAdd,345,70,
"arialbd.ttf",8,kBlack,kG2alignBottomRight)
Do $cinst.$objs.meterGraph.$addtext(
"Temperature °C",10,68,
"arialbd.ttf",8,kBlack,kG2alignBottomLeft)
This method produces the following chart:

50
 Using Graphs in Reports

Using Graphs in Reports

You can use the Graph2 component on Omnis reports in much the same way as you can for
windows for displaying data contained in an Omnis list. That is, you can place a graph
component on a report class, assign a list variable to it, print the report and the data will be
displayed in a chart as expected, depending on the properties you have set in the graph
object.
However, if you wish to manipulate a graph using any of the graph methods, this must be
done within the report instance itself and before the report is printed. Therefore to do this,
you must instantiate an object variable based on the Graph2 component, execute any
methods against the graph object and transfer the image of the graph to an Omnis picture
variable using the $snapshot() method. The graph image contained in the picture variable
can be displayed in the report using a standard Omnis Picture field.
For example, the following report class has a single picture field with its $dataname set to
the variable iPicture. The $height and $width properties are set to 7.9cm and 10.5cm
respectively, which corresponds the height and width of the graph image created in the
report instance.

The following method is contained in the $construct() method of the report class, therefore
the method is executed when the report is instantiated, and the graph object is created and
transferred to the picture variable before the report is printed. The $snapshot() method is
used to capture the graph image and returns it to the picture variable.

51
Omnis Graphs

; Define class var: cGraphObj (Object), subtype Graph2

; Define instance var: iList1 (List), iPicture (Picture)
; Define instance var: iCol1, iCol2 (Char)
Do iList1.$define(iCol1,iCol2)
Do iList1.$add('Col1',10)
Do iList1.$add('Col2',60)
Do iList1.$add('Col3',30)
Do cGraphObj.$majortype.$assign(kG2xy)
Do cGraphObj.$dataname.$assign(iList1)
Do cGraphObj.$snapshot(400,300) Returns iPicture
Do $cinst.$printrecord()
Do $cinst.$endprint()
Note that the graph object will use all the default properties, so if you want to change the
appearance, type or subtype of graph, you need to change the appropriate properties of the
graph object at runtime using the notation. The above method sets the graph major type and
assigns the list variable to the object.
The report will look something like the following:

52
 Using Graphs in the Web client

Using Graphs in the Web client

If you wish to display a chart in a remote form you have to use a similar technique to
displaying graphs in a report – this is because there is no visual graph component for use
with remote forms. Instead, you can use the graph component as an object variable and
construct the graph image in memory on the Omnis Server and ‘save’ and display it as a
picture in the remote form. When the graph is constructed in memory, the $snapshot()
method lets you transfer the graph image to an image variable suitable for displaying in an
Omnis picture field in a remote form.
You have to create an Object variable in your remote form with the Graph object specified
as the object subtype. The following method will do this:
; cGraphObj is an Object variable with Subtype of ‘Graph2’
Do listGraph.$define(Name,Sales)
Do listGraph.$add('Andy',85)
Do listGraph.$add('Sam',80)
Do listGraph.$add('Liza',92)
Do listGraph.$add('Harry',45)
Do cGraphObj.$majortype.$assign(kG2pie)
Do cGraphObj.$dataname.$assign(listGraph)
Do cGraphObj.$maintitle.$assign("WebClient Pie Example")
Do cGraphObj.$snapshot(640,400) Returns iWebImage
This will result in this image:

The Graph2 example library contains a Remote form example, showing all the main chart
types. In this case, the remote form uses an object class based on the Graph2 component
and uses $snapshot() to transfer the graph image to a picture field in the remote form.

53
Omnis Graphs

Drilldown in Web Client graphs

The remote form Picture field type reports the mouse X and Y co-ordinates when an
evClick event is triggered. This allows you to pinpoint where in the image the user has
clicked. You can use this information to find out which active graph element has been
clicked, such as a bar, line or pie slice. Having captured the graph image using the
$snapshot() method you can use the $findobject() method to return the item and set
information for the selected object. For example:
; do code to construct the graph object, such as
Do listGraph.$define(Name,Sales,Expenses)
Do listGraph.$add('Andy',850,400)
Do listGraph.$add('Sam',800,600)
Do listGraph.$add('Liza',920,560)
Do listGraph.$add('Harry',450,230)
Do cGraphObj.$majortype.$assign(kG2xy)
Do cGraphObj.$minorxytype.$assign(kG2xyBar)
Do cGraphObj.$dataname.$assign(listGraph)
Do cGraphObj.$maintitle.$assign("Web Client Bar Chart")
Do cGraphObj.$snapshot(640,400) Returns iWebImage
Do $cinst.$objs.pic.$redraw
; graph image is transferred to remote form picture field and
redrawn
The bar chart would look something like the following:

; $event() method for remote form Picture field

On evClick
Do cGraphObj.$findobject(pMouseX,pMouseY,
setno,itemno,setname,itemname)
Returns ok ;; true if successful

54
 Using Graphs in the Web client

The mouse co-ordinates are returned in pMouseX and pMouseY in the evClick event. The
$findobject() method uses the mouse co-ordinates to get the setno, itemno, setname, and
itemname which contain information about the graph object clicked on. Clicking on the first
bar in the second group of the above chart produces this data:
setno = 2, itemno = 1, setname = Expenses, itemname = Andy
You can use the item and set number/name information to drilldown into the data by
reformatting the list data and redrawing the graph in the remote form.
Note that the Set number and name are not valid for pie charts.

55
Index

Index
$addarealayer(), 17, 30 Angular charts, 33
$addbarlayer(), 17 Area charts, 7, 19
$addboxwhiskerlayer(), 17 Bar charts, 6, 7, 18
$addcandlesticklayer(), 17 Box whisker charts, 7, 21
$addhloclayer(), 17 Candlestick charts, 8, 23
$addlinelayer(), 17, 30, 39 CDML, 48
$addmark(), 14 Chart types, 6
$addpointer(), 34, 35 ChartDirector, 6, 48
$addring(), 34, 37 Color palettes, 41
$addscatterlayer(), 17 Colors
$addsplinearealayer(), 30 Changing graph elements, 41
$addsplinelinelayer(), 30 Date formatting, 47
$addtext(), 14, 50 Drilldown, 40
$addtrendlayer(), 17 Web client, 54
$addzone(), 14, 42 evPreLayout, 38
$columnheadings, 19 Gantt charts, 21
$convdate(), 14, 22 Graph layers, 38
$datacombine, 16, 24 Graph methods
$dataname Common, 14
Graph field, 18 Graph properties
Graphs, 11 Common, 11
$dispose(), 14 Graph2 component, 6
$findobject(), 14, 54 Graphs
$formatvalue(), 14, 50 Web client, 53
$getcolors(), 14, 41 HLOC charts, 8, 22
$getmainlayer(), 15 Images
$getradialaxis(), 30 Embedding images, 49
$getxaxis(), 17 kG2meter, 13
$getyaxis(), 17 kG2pie, 13
$imagesearchpath, 49 kG2polar, 13
$majortype, 11, 13 kG2xy, 13
$minormetertype, 11 Labels, 50
$minorpolartype, 11, 29 Layers, 38
$minortype, 13 Line charts, 19
$minorxytype, 11, 16 Linear charts
$prelayout(), 15, 39 Meter charts, 33
$redraw() Major type, 13
Graphs, 15 Meter charts, 33
$setcolors(), 15, 41 Methods, 34
$setlinearscale(), 15 Properties, 33
$setlogscale(), 15 Meters, 10
$slicemove(), 27 Minor type, 13
$snapshot(), 15, 51, 53 Number formatting, 46
$swapxy, 21 Parameters

56
 Index

Substitution, 42 Polar Spline Line / Area charts, 9

Pie charts, 8, 26 Prelayout event, 38
List structure, 27 Scatter charts, 7, 20
Pie properties, 26 Time formatting, 47
Polar area charts, 9 Trend charts, 24
Polar charts, 9, 29 Web client
List structure, 30 Graphs, 53
Methods, 30 XY charts, 6, 16
Properties, 29 List structure, 18
Polar line charts, 9 Zones, 42

57