Manipulating Graphs

Using graphs

Supported environment

PowerBuilder

Graphs are supported. Because you can print DataStores, PowerBuilder provides some events and functions for DataStores that pertain to the visual presentation of the data. However, graph functions such as CategoryCount, CategoryName, GetData, SeriesCount, and so forth depend on the visual graph control, which is not created for a DataStore. These functions return an error value or an empty string when used with DataStore objects.

It is common for developers to design DataWindow objects that include one or more graphs. When users need to quickly understand and analyze data, a bar, line, or pie graph can often be the most effective format to display.

To learn about designing graphs, see the section called “Working with Graphs” in Users Guide.

Working with graphs in your code

The following sections describe how you can access (and optionally modify) a graph by addressing its properties in code at execution time. There are two kinds of graph properties:

Properties of the graph definition itself

These properties are initially set in the DataWindow painter when you create a graph. They include a graph's type, title, axis labels, whether axes have major divisions, and so on. For 3D graphs, this includes the Render 3D property that uses transparency rather than overlays to enhance a graph's appearance and give it a more sophisticated look.
Properties of the data

These properties are relevant only at execution time, when data has been loaded into the graph. They include the number of series in a graph (series are created at execution time), colors of bars or columns for a series, whether the series is an overlay, text that identifies the categories (categories are created at execution time), and so on.

Using graphs in other PowerBuilder controls

Although you will probably use graphs most often in DataWindow objects, you can also add graph controls to windows, and additional PowerScript functions and events are available for use with graph controls.

For more information, see the section called “Using graphs” in Application Techniques.

Modifying graph properties

How parts of a graph are represented
Referencing parts of a graph

When you define a graph in the DataWindow painter, you specify its behavior and appearance. For example, you might define a graph as a column graph with a certain title, divide its Value axis into four major divisions, and so on. Each of these entries corresponds to a property of a graph. For example, all graphs have a property GraphType, which specifies the type of graph.

When dynamically changing the graph type

If you change the graph type, be sure also to change the other properties as needed to properly define the new graph.

You can change these graph properties at execution time by assigning values to the graph's properties in code.

Property expressions

PowerBuilder

You can modify properties using property expressions. For example, to change the type of the graph gr_emp to Column, you could code:

dw_empinfo.Object.gr_emp.GraphType = ColGraph!

To change the title of the graph at execution time, you could code:

dw_empinfo.Object.gr_emp.Title = "New title"

Modify method

You can use the Modify method to reference parts of a graph.

Example for PowerBuilder

For example, to change the title of graph gr_emp in DataWindow control dw_empinfo, you could code:

dw_empinfo.Modify("gr_emp.Title = 'New title'")

For a complete list of graph properties, see the section called “Properties for Graph controls in DataWindow objects” in DataWindow Reference.

How parts of a graph are represented

Graphs consist of parts: a title, a legend, and axes. Each of these parts has a set of display properties. These display properties are themselves stored as properties in a subobject (structure) of Graph called grDispAttr.

For example, graphs have a Title property, which specifies the text for the title. Graphs also have a property TitleDispAttr, of type grDispAttr, which itself contains properties that specify all the characteristics of the title text, such as the font, size, whether the text is italicized, and so on.

Similarly, graphs have axes, each of which also has a set of properties. These properties are stored in a subobject (structure) of Graph called grAxis. For example, graphs have a property Values, of type grAxis, which specifies the properties of the Value axis, such as whether to use autoscaling of values, the number of major and minor divisions, the axis label, and so on.

Here is a representation of the properties of a graph:

Graph
       int Height
       int Depth
       grGraphType GraphType
       boolean Border
       string Title
       ...
 grDispAttr TitleDispAttr, LegendDispAttr, PieDispAttr
       string FaceName
       int TextSize
       boolean Italic
       ...
 grAxis Values, Category, Series
       boolean AutoScale
       int MajorDivisions
       int MinorDivisions
       string Label
       ...

Referencing parts of a graph

You use dot notation or the Describe and Modify methods to reference the display properties of the various parts of a graph. For example, one of the properties of a graph's title is whether the text is italicized or not. That information is stored in the boolean Italic property in the TitleDispAttr property of the graph.

This example changes the label text for the Value axis of graph gr_emp in the DataWindow control dw_empinfo:

dw_empinfo.Object.gr_emp.Values.Label="New label"

For a complete list of graph properties, see the section called “Properties for Graph controls in DataWindow objects” in DataWindow Reference.

You can use the PowerBuilder Browser to examine the properties of a DataWindow object that contains a graph. For more information, see the Users Guide.

Accessing data properties

Getting information about the data
Saving graph data
Modifying colors, fill patterns, and other data
Using graph methods

To access properties related to a graph's data during execution, you use DataWindow methods for graphs. There are three categories of these methods related to data:

Methods that provide information about a graph's data
Methods that save data from a graph
Methods that change the color, fill patterns, and other visual properties of data

How to use the methods

To call the methods for a graph in a DataWindow control, use the following syntax:

DataWindowName.methodName ( "graphName", otherArguments... )

For example, there is a method CategoryCount, which returns the number of categories in a graph. So to get the category count in the graph gr_printer (which is in the DataWindow control dw_sales), write:

Ccount = dw_sales.CategoryCount("gr_printer")

Getting information about the data

There are quite a few methods for getting information about data in a graph in a DataWindow control at execution time. For all methods, you provide the name of the graph within the DataWindow as the first argument. You can provide your own name for graph controls when you insert them in the DataWindow painter. If the presentation style is Graph, you do not need to name the graph.

PowerBuilder

These methods get information about the data and its display. For several of them, an argument is passed by reference to hold the requested information:

Method	Information provided
CategoryCount	The number of categories in a graph
CategoryName	The name of a category, given its number
DataCount	The number of data points in a series
FindCategory	The number of a category, given its name
FindSeries	The number of a series, given its name
GetData	The value of a data point, given its series and position (superseded by GetDataValue, which is more flexible)
GetDataLabelling	The display setting for the data label at a given data point in a DirectX 3D graph
GetDataPieExplode	The percentage at which a pie slice is exploded
GetDataStyle	The color, fill pattern, or other visual property of a specified data point
GetDataTransparency	The transparency percentage of a data point in a DirectX 3D graph
GetDataValue	The value of a data point, given its series and position
GetSeriesLabelling	The display setting for the series label for a given series in a DirectX 3D graph
GetSeriesStyle	The color, fill pattern, or other visual property of a specified series
GetSeriesTransparency	The transparency percentage of a series in a DirectX 3D graph
ObjectAtPointer	The graph element the mouse was positioned over when it was clicked
SeriesCount	The number of series in a graph
SeriesName	The name of a series, given its number

Saving graph data

PowerBuilder

The following methods allow you to save data from the graph:

Method	Action
Clipboard	Copies a bitmap image of the specified graph to the clipboard
SaveAs	Saves the data in the underlying graph to the clipboard or to a file in one of a number of formats

Modifying colors, fill patterns, and other data

PowerBuilder

The following methods allow you to modify the appearance of data in a graph:

Method	Action
ResetDataColors	Resets the color for a specific data point
SetDataLabelling	Specifies the display setting for a data label in a DirectX 3D graph
SetDataStyle	Sets the color, fill pattern, or other visual property for a specific data point
SetDataTransparency	Sets the transparency percentage for a data point in a DirectX 3D graph
SetSeriesLabelling	Specifies the display setting for a series label in a DirectX 3D graph
SetSeriesStyle	Sets the color, fill pattern, or other visual property for a series
SetSeriesTransparency	Sets the transparency percentage of a series in a DirectX 3D graph

Using graph methods

You call the data-access methods after a graph has been created and populated with data. Some graphs, such as graphs that display data for a page or group of data, are destroyed and re-created internally as the user pages through the data. Any changes you made to the display of a graph, such as changing the color of a series, are lost when the graph is re-created.

Event for graph creation

To be assured that data-access methods are called whenever a graph has been created and populated with data, you can call the methods in the code for an event that is triggered when a graph is created. The event is:

PowerBuilder

Event ID pbm_dwngraphcreate, which you can assign to a user event for a DataWindow control (described below)

The graph-creation event is triggered by the DataWindow control after it has created a graph and populated it with data, but before it has displayed the graph. By accessing the data in the graph in this event, you are assured that you are accessing the current data and that the data displays the way you want it.

Setting up the PowerBuilder user event

PowerBuilder provides an event ID, pbm_dwngraphcreate, that you can assign to a user event for a DataWindow control.

To access data properties of a graph in a DataWindow control:

Place the DataWindow control in a window or user object and associate it with the DataWindow object containing the graph.

Next you create a user event for the DataWindow control that is triggered whenever a graph in the control is created or changed.
Select Insert>Event from the menu bar.

The Script view displays and includes prototype fields for adding a new event.
Select the DataWindow control in the first drop-down list of the prototype window.

If the second drop-down list also changes to display an existing DataWindow event prototype, scroll to the top of the list to select New Event or select Insert>Event once again from the menu bar.
Name the user event you are creating.

For example, you might call it GraphCreate.
Select pbm_dwngraphcreate for the event ID.
Click OK to save the new user event.
Write a script for the new GraphCreate event that accesses the data in the graph.

Calling data access methods in the GraphCreate event assures you that the data access happens each time the graph has been created or changed in the DataWindow.

Examples

PowerBuilder

The following statement sets to black the foreground (fill) color of the Q1 series in the graph gr_quarter, which is in the DataWindow control dw_report. The statement is in the GraphCreate event, which is associated with the event ID pbm_dwngraphcreate in PowerBuilder:

dw_report.SetSeriesStyle("gr_quarter", "Q1", &
       foreground!, 0)

The following statement changes the foreground (fill) color to red of the second data point in the Stellar series in the graph gr_sale in a window. The statement can be in a script for any event:

int SeriesNum
 // Get the number of the series.
 SeriesNum = gr_sale.FindSeries("Stellar")

 // Change color of second data point to red
 gr_sale.SetDataStyle(SeriesNum, 2, foreground!, 255)

For more information

For complete information about the data-access graph methods, see Methods for Graphs in the DataWindow Control in DataWindow Reference.

For more about PowerBuilder user events, see the section called “Working with User Events” in Users Guide.

Using point and click

Users can click graphs during execution. The DataWindow control provides a method called ObjectAtPointer that stores information about what was clicked. You can use this method in a number of ways in mouse events. For example, with the ObjectAtPointer information, you can call other graph methods to report to the user the value of the clicked data point. This section shows you how.

Mouse events and graphs

To cause actions when a user clicks a graph, you might:

PowerBuilder

Write a Clicked script for the DataWindow control

You should call ObjectAtPointer in the first statement of the event's code.

Using ObjectAtPointer

ObjectAtPointer works differently in PowerBuilder.

PowerBuilder

ObjectAtPointer has this syntax:

DataWindowName.ObjectAtPointer ( "graphName", seriesNumber, dataNumber )

ObjectAtPointer does these things:

Returns the kind of object the user clicked

The object is identified by a grObjectType enumerated value. For example, if the user clicks on a data point, ObjectAtPointer returns TypeData!. If the user clicks on the graph's title, ObjectAtPointer returns TypeTitle!.

For a list of object values, see DataWindow Constants in DataWindow Reference. In PowerBuilder, you can also open the Browser and click the Enumerated tab.
Stores the number of the series the pointer was over in the variable seriesNumber, which is an argument passed by reference
Stores the number of the data point in the variable dataNumber, also an argument passed by reference

Example

Assume there is a graph named gr_sales in the DataWindow control dw_sales. The following code for the control's MouseDown event displays a message box:

If the user clicks on a series (that is, if ObjectAtPointer returns 1), the message box shows the name of the series clicked on. The example uses the method GetSeriesName to get the series name, given the series number stored by ObjectAtPointer.
If the user clicks on a data point (that is, if ObjectAtPointer returns 2), the message box lists the name of the series and the value clicked on. The example uses GetDataNumber to get the data's value, given the data's series and data point number.

PowerBuilder

This code is for the Clicked event:

int SeriesNum, DataNum
double Value
grObjectType ObjectType
string SeriesName, ValueAsString
string GraphName
GraphName = "gr_sale"

// The following method stores the series number
// clicked on in SeriesNum and stores the number
// of the data point clicked on as DataNum.
ObjectType = &
      dw_printer.ObjectAtPointer (GraphName, &
      SeriesNum, DataNum)

IF ObjectType = TypeSeries! THEN
      SeriesName = &
         dw_printer.SeriesName (GraphName, SeriesNum)
      MessageBox("Graph", &
         "You clicked on the series " + SeriesName)

ELSEIF ObjectType = TypeData! THEN
      Value = dw_printer.GetData (GraphName, &
         SeriesNum, DataNum)
      ValueAsString = String(Value)
      MessageBox("Graph", &
         dw_printer.SeriesName (GraphName, &
         SeriesNum) + " value is " + ValueAsString)
END IF

Prev	Up	Next
Using DataStore Objects	Home	DataWindow Export/Import Template

DataWindow Programmers GuideDataWindow and DataStore basics

Using graphs

Supported environment

Using graphs in other PowerBuilder controls

Modifying graph properties

When dynamically changing the graph type

How parts of a graph are represented

Referencing parts of a graph

Accessing data properties

Getting information about the data

Saving graph data

Modifying colors, fill patterns, and other data

Using graph methods

Using point and click

DataWindow Programmers Guide
DataWindow and DataStore basics