Chapter 8—Omnis Graphs

Some parts of this chapter refer to creating Charts and Graphs using the Graph2 window component, which is available for Window classes only, and therefore may not be available in your edition of Omnis Studio. You can however use the Graph2 External Object to generate a chart image in your Omnis code, save it as a JPG image and display it in the JavaScript Client in a remote form Picture control (this technique is shown in the JS Picture example app in the Hub in the Studio Browser), or you can add the chart image to a PDF report. Alternatively, you can use the Bar or Pie Chart JavaScript component to display a chart in your web & mobile apps. As a further alternative for displaying charts in the JavaScript Client, you could embed a third-party chart engine into a remote form, a technique which is described in the tech note: Integrating AmCharts into Omnis Studio TNJC0014.

About Graph2

You can create many different types of chart in Omnis using the Graph2 component 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 to simplify graphing functionality in Omnis. The 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.

High Resolution Charts

From Studio 10.2 Rev 29538 onwards, the Graph2 component draws charts in high resolution suitable for display on high resolution displays. In this case, charts are generated at twice the size and are displayed at the correct physical size on high resolution displays.

You can disable this behavior by setting the property $disablehighresolution to kTrue (the default is kFalse meaning high resolution charts are supported). If the client is running on a display that does not support high resolution, the property will be set to kTrue automatically, and you will not be able to change the value of the property.

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.

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.

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.

Polar Charts

Polar Area

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 Line

See later in this section for a description of how to draw the 2 graphs above.

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 Spline Line and Area

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.

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.

The following common properties are found under the Prefs tab in the Property Manager.

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

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:

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.

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.

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

XY Charts

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

XY chart properties

XY chart methods

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

| 20% Method Name | 10% Returns | 70% 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.

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 list.$define(Name,Sales,Expenses)
Do list.$add('Andy',85000,20000)
Do list.$add('Sam',80000,15000)
Do list.$add('Lisa',92000,34000)
Do list.$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 list
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)}

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 list.$define(Name,#1,#2,#3,#4,#5,#6,#7,#8, #9,#10,#11,#12,#13,#14,#15,#16,#17,#18,#19,#20)
Do list.$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 list.$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	3d Area chart \$majortype=kG2xy, $minorxytype=kG2xyArea

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 list.$define(Name,#1,#2,#3,#4)
Do list.$add('Pt1',10,130,5,100)
Do list.$add('Pt2',15,150,12,95)
Do list.$add('Pt3',6,80,8,105)
Do list.$add('Pt4',12,110,7,82)
Do list.$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.

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 list.$define(Name,#1,#2,#3,#4,#5)
Do list.$add('',55,70,80,40,62)
Do list.$add('',60,80,90,45,70)
Do list.$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:

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 list.$define(Name,#1,#2,#3,#4,#5)
Do list.$add('',2043,1931,2000,1950)
Do list.$add('',2039,1921,1957,1991)
Do list.$add('',2076,1985,1993,2026)

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.

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).

$datacombine = kG2dataSide: The data sets are shown as individual bars side-by-side (the default for XY bar charts)	$datacombine = kG2dataStack: The data sets are combined by stacking up the bar segments, therefore showing individual amounts in relation to the total amount for the data group
$datacombine = kG2dataOverlay: The data sets are overlayed each other providing a clearer comparison of data than the side-by-side type	$datacombine = kG2dataPercentage shows each individual amount as a percentage of the 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.

Pie Charts

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

Pie chart properties

Pie chart methods

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

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 list.$define(Name,Sales)  
Do list.$add('Andy',85)  
Do list.$add('Sam',80) 
Do list.$add('Liza',92) 
Do list.$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.

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.

Polar Charts

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

Polar chart properties

Polar chart methods

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

* 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 list.$define(Name,Score)
Do list.$add("Speed",90)
Do list.$add("Reliability",60)
Do list.$add("Comfort",65)
Do list.$add("Safety",75)
Do list.$add("Efficiency",40)

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 list.$define(Name,#1,#3)
Do list.$add("",90,15)
Do list.$add("",25,60)
Do list.$add("",40,110)
Do list.$add("",55,180)
Do list.$add("",68,230)
Do list.$add("",44,260)
Do list.$add("",79,260)
Do list.$add("",85,310)
Do list.$add("",50,340)

# $columnheadings of graph is set to listNames 
Do list.$define(#S1)
Do list.$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.

# $event() method for graph window object
# define listLayer2 (List), local vars lLayer and OpenLoop 
On evPreLayout
  Do list.$define(Name,OpenLoop,#1)
  Do list.$add("",80,40)
  Do list.$add("",91,65)
  Do list.$add("",66,88)
  Do list.$add("",80,110)
  Do list.$add("",92,150)
  Do list.$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 list.$define(#S1)
  Do list.$add("Open loop")
  Do $cinst.$objs.GROBJ.$addlinelayer(list) 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:

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

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)

Meter chart methods

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

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

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.

1. $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:

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:

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 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:

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.

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:

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.

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)

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%)"

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

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, 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.

Additional Parameters for HLOC and CandleStick Layers

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

Additional Parameters for Box Whisker Layers

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

Additional Parameters for Trend Layers

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

Parameters for Polar Charts

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

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, you can use (value|2.,) where 2 and '.' (dot) is used to specify the decimal point precision, and ',' (comma) as the thousand separator. The number 123456.789 will therefore be displayed as 123,456.79.

For numbers, the formatting options are specified using the following syntax:

([param]|[a][b][c][d])

where:

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:

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}%)")

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 macOS 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.

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:

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.

# 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:

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 list.$define(Name,Sales)
Do list.$add('Andy',85)
Do list.$add('Sam',80)
Do list.$add('Liza',92)
Do list.$add('Harry',45)
Do cGraphObj.$majortype.$assign(kG2pie)
Do cGraphObj.$dataname.$assign(list)
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.

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 list.$define(Name,Sales,Expenses)
Do list.$add('Andy',850,400)
Do list.$add('Sam',800,600)
Do list.$add('Liza',920,560)
Do list.$add('Harry',450,230)
Do cGraphObj.$majortype.$assign(kG2xy)
Do cGraphObj.$minorxytype.$assign(kG2xyBar)
Do cGraphObj.$dataname.$assign(list)
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

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.