Using graphs in DataWindow objects

You will probably use most of your graphs in DataWindow objects–the
data for the graph comes from tables in the database.

Graphs in DataWindow objects are dynamic

Graphs in DataWindow objects are tied directly to the data that is
in the DataWindow object. As the data changes, the graph is automatically
updated to reflect the new values.

Two techniques

You can use graphs in DataWindow objects in two ways:

• By including a graph as a
  control in a DataWindow object
  Here you use a graph to enhance the display of information
  in a DataWindow object, such as a tabular or freeform DataWindow object. This
  technique is described next.
• By using the Graph presentation style
  Here the entire DataWindow object is a graph. The underlying data
  isn’t visible. This technique is described in “Using the Graph presentation
  style”.

Placing a graph in a DataWindow object

To place a graph in a DataWindow object:

1. Open or create the DataWindow object that will
   contain the graph.

2. Select Insert>Control>Graph
   from the menu bar.

3. Click where you want the graph.

   PowerBuilder displays the Graph Data dialog box:

   

4. Specify which columns contain the data and the
   type of graph you want, and click OK.

   For more information, see “Associating
   data with a graph”.

   The Design view now contains a representation of the graph:

   

5. Specify the graph’s properties in the
   Properties view.

Using the graph’s Properties view

A graph has a Properties view in which you can specify the
data as well as the other properties of the graph.

To display the graph’s Properties view:

1. Select Properties from the graph’s
   popup menu.

The Properties view for a graph has 6 property pages in which
you specify information about the graph. The following table lists
the property pages and describes what each property page specifies:

Property page	What it specifies
Axis	Labels, scale, information about major and minor divisions for the category axes
Data	Where to get the graph’s data
General	Various general graph properties, including border, graph colors, whether to size the graph to the full screen display, suppression in newspaper columnsGraph type, title, legend locationFor 3D graphs, perspective, rotation, and elevationFor bar graphs, overlap, spacing and depth of bars
Pointer	The pointer to use when the mouse is positioned over the graph
Position	The x,y location of the upper left corner of the graph, its width and height, sliding options, the layer in which the graph is to be positionedWhether the graph can be resized and moved during execution
Text	Text properties for text controls that display on the graph, including title, axis text, axis label, and legendText properties include font, font style, font size, alignment, rotation, color, display expression, display format

Changing a graph’s
position and size

When you initially place a graph in a DataWindow object, it is in
the foreground–it sits above the bands in the DataWindow object.
Unless you change this setting, the graph displays in front of any
retrieved data.

The initial graph is also movable and resizable, so users have
complete flexibility as to the size and location of a graph at execution
time.

You can change these properties if you want.

To specify a graph’s position and size:

1. Select Properties from the graph’s
   popup menu and then select the Position page or the General page
   in the Properties view.

   The Position page contains most of the options:

   

2. Select the settings for the following options
   on the Position property page:

   Setting	Meaning
   Layer	Background — The graph displays behind other elements in the DataWindow objectBand — The graph displays in one particular band. If you choose this setting, you should resize the band to fit the graph. Often you will want to place a graph in the Footer band. As users scroll through rows in the DataWindow object, the graph remains at the bottom of the screen as part of the footerForeground — (Default) The graph displays above all other elements in the DataWindow object. Typically, if you choose this setting, you also make the graph movable so it won’t obscure data while users display the DataWindow object
   Moveable	The graph can be moved in the Preview view and during execution
   Resizable	The graph can be resized in the Preview view and during execution
   Slide Left, Slide Up	The graph slides to the left or up to remove extra white spaceFor more information, see “Sliding controls to remove blank space in a DataWindow object”
   X, Y	The location of the upper-left corner of the graph
   Width, Height	The width and height of the graph

3. Select the settings for the following options
   on the General property page:

   Setting	Meaning
   Size To Display	The graph fills the DataWindow object and resizes when users resize the DataWindow object. This setting is used with the Graph presentation style
   HideSnaked	Don’t repeat graph after the first column in a DataWindow object using newspaper-style columns

Associating data with a graph

When using a graph in a DataWindow object, you associate axes of
the graph with columns in the DataWindow object.

In fact, the only way to get data into a graph in a DataWindow object is
through columns in the DataWindow object. You cannot add, modify, or delete
data in the graph except by adding, modifying, or deleting data
in the DataWindow object.

You can graph data from any columns retrieved into the DataWindow object. The
columns don’t have to be displayed.

About the examples The process of specifying data for a graph is illustrated
below using the Printer table in the EAS Demo DB.

To specify data for a graph:

1. If you are creating a new graph, the Graph
   Data dialog box displays. Otherwise, select Properties from the
   graph’s popup menu and select the Data tab in the Properties
   view.

2. Fill in the boxes as described below.

3. Click OK.

Specifying which rows to include
in a graph

The Rows dropdown listbox allows you to specify which rows
of data are graphed at any one time:

Setting	Meaning
All	Graphs the data from all the rows that have been retrieved but not filtered or deleted (that is, the rows in the primary buffer of the DataWindow object)
Page	Graphs only the data from the rows that are currently displayed on the page
Group n	Graphs only the data in the specified group (in a grouped DataWindow object)

If you select Group If you are graphing data in the current group in a grouped DataWindow object and
may have several groups displayed at the same time, you should localize the
graph in a group-related band in the Design view to ensure that
it is clear which group the graph represents. Usually, the group
header band is the most appropriate band.

Specifying the categories

Specify the column or expression whose values determine the
categories. In the Graph Data dialog box in the Graph wizard and
in the Data tab in the Properties view, you can select a column
name from a dropdown listbox. In the Data tab, you can also type
an expression:

There will be an entry along the Category axis for each different
value of the column or expression you specify.

Using display values of data If you are graphing columns that use code tables–data
is stored with a data value but displayed to users with more
meaningful display values–by default the graph will use
the column’s data values. To have the graph use a column’s display
values, use the LookupDisplay function when specifying Category
or Series. LookupDisplay returns a string that matches the display
value for a column:

For more about code tables, see “Defining a code table”. For more about
LookupDisplay, see the DataWindow Reference
.

Specifying the values

PowerBuilder populates the Value dropdown listbox. The listbox
includes the names of all the retrieved columns as well as the following
aggregate functions:

• Count for all non-numeric columns
• Sum for all numeric columns

Select an item from the dropdown listbox or type an expression
(in the Properties view). For example, if you want to graph the
sum of units sold, you can specify:

To graph 110 percent of the sum of units sold, you can specify:

Specifying the series

Graphs can have one or more series.

Single-series graphs

If you want only one series (that is, if you want to graph
all retrieved rows as one series of values), leave the Series box
empty.

Multiple-series graphs

If you want to graph more than one series, select the Series
checkbox and specify the column that will provide the series values.

You can select column names from the dropdown listbox:

There will be a set of data points for each different value
of the column you specify here. For example, if you specify in the
Series box a column that has 10 values, then your graph will have
10 series: one set of data points for each different value of the
column.

Using expressions

You can also specify expressions for Series (in the Data tab
of the Properties view). For example, you could specify the following
for Series:

In this case, if a table had unit values of 10,000, 20,000,
and 30,000, the graph would show series values of 10, 20, and 30.

Specifying multiple entries

You can specify more than one of the retrieved columns to
serve as series. Separate multiple entries by commas.

You need to specify the same number of entries in the Value
box as you do in the Series box. The first value in the Value box
corresponds to the first series identified in the Series box, the
second value corresponds to the second series, and so on. The example
about graphing actual and projected sales in “Examples” illustrates
this technique.

Examples

This section shows how to specify the data for several different
graphs of the data in the Printer table in the EAS Demo DB. The table
records quarterly unit sales of three printers by three sales representatives:

Rep	Quarter	Product	Units
Simpson	Q1	Stellar	12
Jones	Q1	Stellar	18
Perez	Q1	Stellar	15
Simpson	Q1	Cosmic	33
Jones	Q1	Cosmic	5
Perez	Q1	Cosmic	26
Simpson	Q1	Galactic	6
Jones	Q1	Galactic	2
Perez	Q1	Galactic	1
…	…	…	…
Simpson	Q4	Stellar	30
Jones	Q4	Stellar	24
Perez	Q4	Stellar	36
Simpson	Q4	Cosmic	60
Jones	Q4	Cosmic	52
Perez	Q4	Cosmic	48
Simpson	Q4	Galactic	3
Jones	Q4	Galactic	3
Perez	Q4	Galactic	6

Graphing total sales Say you want to graph total sales of printers in each quarter.
Retrieve all the columns into a DataWindow object and create a graph with
the following data specification:

You want to graph sales by quarter, so the Quarter column
serves as the category. Because the Quarter column has four values
(Q1, Q2, Q3, and Q4), there will be four categories along the Category
axis. You want only one series (total sales in each quarter), so
you can leave the Series box empty as done in the preceding dialog
box, or type a string literal to identify the series in a legend.
You want to graph total sales in each quarter, so the Value box
is specified as sum(units for graph).

Here is the resulting column graph. PowerBuilder automatically
generates the category text based on the data in the table:

In the preceding graph, there is one set of data points (one
series) across four quarters (the category values).

The following is a pie graph, which has exactly the same properties
as the column graph above except for the type, which is 3D Pie:

In pie graphs, categories are shown in the legend.

Graphing unit sales of each printer Say you want to graph total quarterly sales of each printer.
Create a graph with the following data specification:

You want a different series for each printer, so the column
Product serves as the series. Because the Product column has three
values (Cosmic, Galactic, and Stellar), there will be three series
in the graph. As in the first example, you want a value for each
quarter, so the Quarter column serves as the category. And you want
to graph total sales in each quarter, so the Value box is specified
as sum(units for graph).

Here is the resulting graph. PowerBuilder automatically generates
the category and series labels based on the data in the table. The
series labels display in the graph’s legend:

Graphing unit sales by representative Say you want to graph the quarterly sales made by each representative.
Here you want a different series for each representative, so the
column Rep serves as the series. Your category is still the Quarter
column. And you still want to graph total sales in each quarter
for each series, so the Value box is still sum(units for graph):

Here is the resulting graph:

Graphing unit sales by representative and total
sales Say you want to graph sales by representative, as shown above,
plus total sales for each printer. Here is how to specify the data:

Here you have two types of categories: the first is Quarter,
which shows quarterly sales, as in the preceding graph. You also
want a category for total sales. There is no corresponding column
in the DataWindow object, so you can simply type the literal “Total” to
identify the category. The Category box looks like this:

You separate multiple entries with a comma.

For each of these category types you want to graph the sum
of units sold for each representative. So the Value entry is:

And the Series entry is:

Here is the resulting graph:

Notice that PowerBuilder uses the literal “Total” supplied in
the Category box in the Graph Data window as a value in the Category
axis.

Graphing actual and projected
sales Say you want to graph total quarterly sales of all printers
and also want to graph projected sales for next year. You figure
that next year you will sell about 10 percent more printers. Here
is how to specify the data:

You are using labels to identify two series, Actual and Projected.
Note the single quotation marks around the literals. For Values,
you enter the expressions that correspond to Actual and Projected
sales. For Actual, you use the same expression as in the examples
above, sum(units for graph). For Projected sales, you multiply each
unit sale by 1.1 to get the 10 percent increase. Therefore, the
second expression is sum(units*1.1 for graph).

Here is the resulting graph. PowerBuilder uses the literals
you typed for the series as the series labels in the legend:

Using overlays

It is often useful to call special attention to one of the
series in a graph, particularly in a bar or column graph. You can
do that by defining the series as an overlay.
An overlay series is graphed as a line on top of the other series
in the graph. To define a series as an overlay, define the series
as follows:

• If specifying a column name to identify the series,
  specify this for the series:
  PowerBuilder

  "@overlay~t" + <i>ColumnName</i>

  1	"@overlay~t" + <i>ColumnName</i>

• If using a label to identify the series, specify
  this for the series:
  PowerBuilder

  "@overlay~t<i>SeriesLabel</i> "

  1	"@overlay~t<i>SeriesLabel</i> "

Examples

Say you want to graph sales in each quarter and overlay the
sales of each individual printer. Specify the graph’s data
like this:

Here is the resulting graph:

To graph unit sales of printers by quarter and overlay the
largest sale made in each quarter, specify the graph’s
data like this:

Here is the resulting graph:

---