Home

	Expand Search

DataWindow Programmer's Guide

Chapter 5: Manipulating Graphs

Chapter 5

Manipulating Graphs

About this chapter

This chapter describes how to write code that allows you to access and change a graph in your application at execution time.

Using graphs

Supported environments

PowerBuilder and Web ActiveX

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.

Web DataWindow

Graphs are not supported. If you use a DataWindow object that includes graphs, the graphs are ignored. If you use a DataWindow object with the Graph presentation style, nothing displays.

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 PowerBuilder User's Guide or the DataWindow Builder User's 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.

• 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 PowerBuilder Application Techniques.

Modifying graph properties

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

In any environment , 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'")

Example for Web ActiveX

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

dw_empinfo.Modify("gr_emp.Values.Label = 'New label'");

For a complete list of graph properties, see the 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 auto scaling 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 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 PowerBuilder User's Guide.

Accessing data properties

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:

Web ActiveX

These methods get information about the data and its display. There are additional helper methods available whenever the equivalent PowerBuilder method uses an argument passed by reference. These helper methods are identified in the second column of the following table (and are described in the DataWindow Reference):

Saving graph data

PowerBuilder

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

Web ActiveX

You can save an image of the graph on the clipboard, but you cannot save data in a file. Writing to the file system is a security violation for an ActiveX control:

Modifying colors, fill patterns, and other data

PowerBuilder

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

Web ActiveX

These methods modify the appearance of data in a 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)

• Web ActiveX

  The onGraphCreate event

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.

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

2. Select Insert>Event from the menu bar.

   The Script view displays and includes prototype fields for adding a new event.

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

   

4. Name the user event you are creating.

   For example, you might call it GraphCreate.

5. Select pbm_dwngraphcreate for the event ID.

   

6. Click OK to save the new user event.

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

Web ActiveX

The following statement sets the foreground (fill) color to black in one of the series in the graph gr_quarter, which is in the DataWindow control dw_report. The statement is in the onGraphCreate event:

dw_report.SetSeriesStyleColor("gr_quarter", 1, 0, 0);

For more information

For complete information about the data-access graph methods, see the DataWindow Reference.

For more about PowerBuilder user events, see the PowerBuilder User's 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

• Web ActiveX

  Write code for the MouseDown or onButtonClick event

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

Using ObjectAtPointer

ObjectAtPointer works differently in PowerBuilder and the Web ActiveX.

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 the chapter on constants in the 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

Web ActiveX

ObjectAtPointer is used with two supporting methods to get all the information. ObjectAtPointer has this syntax:

DataWindowName.ObjectAtPointer ( "graphName" )

To get the information, you:

1. Call ObjectAtPointer, which returns the kind of graph element the user clicked.

   The element type is identified by a number. For example, if the user clicks on a series, ObjectAtPointer returns 1. If the user clicks on a graph's title, ObjectAtPointer returns 4.

   For a list of values for individual graph elements, see the chapter on constants in the DataWindow Reference.

2. Call ObjectAtPointerSeries, which returns the number of the series the pointer was over.

3. Call ObjectAtPointerDataPoint, which returns the number of the data point the pointer was over.

The second two methods must be called after ObjectAtPointer.

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

Web ActiveX

This code is for the MouseDown event:

number SeriesNum, DataNum, ObjectType, Success, Value;

string SeriesName, GraphName;

GraphName = "gr_sales";

ObjectType =

        dw_sales.GrObjectAtPointer(GraphName);

if (ObjectType == 1) {

        SeriesName =

            dw_sales.GetSeriesName(GraphName, SeriesNum);

        alert("You clicked on the series " + SeriesName);

}

else {

        if (ObjectType == 2) {

            Success = dw_sales.GetDataNumber(GraphName,

                SeriesNum, DataNum, 1);

            if (Success == 1) {

                Value = GetDataNumberVariable( );

                alert(dw_sales.GetSeriesName(GraphName,

                    SeriesNum) +        " value is " + Value);    

            }        }

}