PtTrend

A trend graph

Class hierarchy:

PtWidget → PtBasic → PtTrend

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtTrend.h>

Description:

A PtTrend widget displays a trend graph. The data is displayed as a set of connected points that shift in a specified direction and at the rate at which data is fed in.

A PtTrend widget.

New resources:

Pt_ARG_TREND_ATTRIBUTES

The attributes that the trend may have. This resource is an array of structures of type PtTrendAttr_t, which contains at least the following member:

int map

An index into Pt_ARG_TREND_COLOR_LIST to indicate the color that the trend uses. This index is used as follows:

In order to set this resource, you must use the arguments to PtSetArg() in an unusual way; the value argument points to the value of the resource, as usual, but len is used for the trend number, not the size of value.

To set the colors for all the trends at once, specify a list of mappings of trends onto colors, and use 0 for the trend number. That is, the len argument to 0 and have the value argument point to an array of PtTrendAttr_t structures.

For example, the following code fragment sets up the color list, and sets the colors to be used for three trends.

int trend_color_array[4] = {Pg_GREEN, Pg_RED,
                            Pg_YELLOW, Pg_BLUE};
PtTrendAttr_t one_attr, several_attr[3];
PtArg_t args[2];
PtWidget_t trend_widget;

…

/* Set up the color list. */
PtSetArg (&args[0], Pt_ARG_TREND_COLOR_LIST,
          trend_color_array, 4);
PtSetResources (trend_widget, 1, args);

/* Map the trends to colors. */
several_attr[0].map = 3;  /* Trend 0 is Pg_YELLOW */
several_attr[1].map = 2;  /* Trend 1 is Pg_RED    */
several_attr[2].map = 4;  /* trend 2 is Pg_BLUE   */

PtSetArg (&args[0], Pt_ARG_TREND_ATTRIBUTES,
          several_attr, 0);
PtSetResources (trend_widget, 1, args);

To set an attribute for a given trend, set PtSetArg's len argument to the number of that trend, and have the value argument point to a single structure of type PtTrendAttr_t. For example, the following changes the color of trend 2 to Pg_GREEN:

one_attr.map = 1;
PtSetArg (&args[0], Pt_ARG_TREND_ATTRIBUTES,
          &one_attr, 2);
PtSetResources (trend_widget, 1, args);
        

---

It isn't possible to set the color of trend 0 alone, as setting the len argument of PtSetArg() to 0 specifies that you want to set the color index for all the trends.

---

Pt_ARG_TREND_COLOR_LIST

The list of colors that the trend may use. See PgColor_t in the Photon Library Reference.

To assign one of these colors to a trend, use the Pt_ARG_TREND_ATTRIBUTES resource.

---

The first color in this list is always the same as Pt_ARG_COLOR.

---

Pt_ARG_TREND_COUNT

The number of trends that the widget displays.

Pt_ARG_TREND_DATA (write-only)

The data displayed by the trends. You can use this resource to set the data; you can't use it to extract the data from the trends.

When you want to add data to a trend, your application should set the value argument to PtSetArg() with a pointer to a data buffer that contains the new data points. The application must also set the len parameter to the number of new data points being added to the trend.

If the widget is displaying multiple trends, the data buffer must contain the new data for each trend: data for the first trend is followed by data for the second trend, and so on. The application must set len to be the total number of points being added, not the number of points per trend.

If you set the value parameter to NULL, the trend's display is cleared.

If you wish to replace some of the data for one trend, call PtTrendChangeData(). To replace data in all trends, call PtTrendChangeTrendData().

Pt_ARG_TREND_FLAGS

Flags that control the appearance of the widget. The bits include:

Pt_GRID

Draw a grid. If this flag is set, you must also set Pt_GRID_IS_TRANSLUCENT, Pt_GRID_ABOVE_TRENDS, or Pt_TRENDS_ABOVE_GRID.

Pt_GRID_ABOVE_TRENDS

Make the grid opaque, appearing over the trends. The grid is displayed only if Pt_GRID is set.

Pt_GRID_FORCE

Draw a grid even if the graphics device doesn't support planar hardware blitting. Some flickering may occur.

Pt_GRID_IS_TRANSLUCENT

Make the grid translucent, appearing over the trends. The grid is displayed only if Pt_GRID is set.

Pt_PIXEL

Draw the trend with PgDrawPixelArray() instead of PgDrawPolygon().

Pt_TREND_HORIZONTAL

Make the trends horizontal. If this is set, you must also set Pt_TREND_LEFT_TO_RIGHT or Pt_TREND_RIGHT_TO_LEFT.

Pt_TREND_BOTTOM_TO_TOP

Make the trends move from the bottom to the top of the widget. You can use this only with Pt_TREND_VERTICAL.

Pt_TREND_LEFT_TO_RIGHT

Make the trends move from left to right. You can use this only with Pt_TREND_HORIZONTAL.

Pt_TREND_RIGHT_TO_LEFT

Make the trends move from right to left. You can use this only with Pt_TREND_HORIZONTAL.

Pt_TREND_TOP_TO_BOTTOM

Make the trends move from the top to the bottom of the widget. You can use this only with Pt_TREND_VERTICAL.

Pt_TREND_VERTICAL

Make the trends vertical. If this is set, you must also set Pt_TREND_TOP_TO_BOTTOM or Pt_TREND_BOTTOM_TO_TOP.

Pt_TRENDS_ABOVE_GRID

Make the grid opaque, appearing under the trends. The grid is displayed only if Pt_GRID is set.

---

If you set Pt_ARG_TREND_FLAGS to an invalid value, the widget draws only the background.

---

Pt_ARG_TREND_GRID_COLOR

The color of the grid, specified as an RGB value. See PgColor_t in the Photon Library Reference.

The grid is displayed only if Pt_GRID is set in Pt_ARG_TREND_FLAGS.

Pt_ARG_TREND_GRID_X

The number of grid lines along the x axis; in other words, the number of vertical lines. The grid is displayed only if Pt_GRID is set in Pt_ARG_TREND_FLAGS.

Pt_ARG_TREND_GRID_Y

The number of grid lines along the y axis; in other words, the number of horizontal lines. The grid is displayed only if Pt_GRID is set in Pt_ARG_TREND_FLAGS.

Pt_ARG_TREND_INC

The distance between data points displayed on the screen. The default is 1. Note that if the increment is too large, the data won't be plotted correctly. Generally, you should use this resource only if you need a coarse-grained display.

Pt_ARG_TREND_MAX

The maximum data value for all the trends.

Pt_ARG_TREND_MIN

The minimum data value for all the trends.

Pt_ARG_TREND_PALETTE_END

Defines the range of palette entries the widget uses for drawing if the grid is displayed. This is useful if you have more than one PtTrend widget and you want to make sure their palette entries don't overlap.

Each PtTrend widget uses:

• two palette entries for each entry in the Pt_ARG_TREND_COLOR_LIST— one for the trend, and one for where the trend overlaps the grid
• one palette entry for the background
• one palette entry for the grid.

If E is the value of the Pt_ARG_TREND_PALETTE_END resource and N is the number of palette entries used for the widget (rounded up to the next power of 2), the widget uses palette entries from E - N to E - 1.

The value of Pt_ARG_TREND_PALETTE_END should be a multiple of N. If it isn't, it's rounded down to a multiple of N.

Inherited resources:

If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.

Convenience functions:

The PtTrend widget defines the following convenience functions that make it easier to use the widget once it's been created:

PtTrendChangeData()

Replace some samples for all trends

PtTrendChangeTrendData()

Replace some samples for one trend