RtTrend

A realtime trend graph

Class hierarchy:

PtWidget --> PtBasic --> RtTrend

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

PhAB icon:

Public header:

<photon/realtime/RtTrend.h>

Description:

An RtTrend 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.

An RtTrend widget.

New resources:

Rt_ARG_TREND_ATTRIBUTES

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

int map

An index into Rt_ARG_TREND_COLOR_LIST to indicate the color that the trend will use. This index is used as follows:

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.

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. Thus, to set the attributes for all trends at the same time, set PtSetArg's len argument to 0 and have the value argument point to an array of RtTrendAttr_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};
RtTrendAttr_t one_attr, several_attr[3];
PtArg_t args[2];
PtWidget_t trend_widget;

...

/* Set up the color list. */
PtSetArg (&args[0], Rt_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], Rt_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 RtTrendAttr_t. For example, the following would change the color of trend 2 to Pg_GREEN:

one_attr.map = 1;
PtSetArg (&args[0], Rt_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.

Rt_ARG_TREND_COLOR_LIST

The list of colors that the trend may use. To assign one of these colors to a trend, use the Rt_ARG_TREND_ATTRIBUTES resource.

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

Rt_ARG_TREND_COUNT

The number of trends that the widget will display.

Rt_ARG_TREND_DATA (write-only)

The data displayed by the trends. This resource is used to set the data; it can't be used 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 will be cleared.

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

Rt_ARG_TREND_FLAGS

Flags that control the appearance of the widget. Possible values:

Rt_GRID

Draw a grid. If this flag is set, you must also set exactly one of Rt_GRID_IS_TRANSLUCENT, Rt_GRID_ABOVE_TRENDS, or Rt_TRENDS_ABOVE_GRID.

Rt_GRID_IS_TRANSLUCENT

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

Rt_GRID_ABOVE_TRENDS

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

Rt_GRID_FORCE

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

Rt_PIXEL

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

Rt_TRENDS_ABOVE_GRID

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

Rt_TREND_HORIZONTAL

Make the trends horizontal. If this is set, you must also set exactly one of Rt_TREND_LEFT_TO_RIGHT and Rt_TREND_RIGHT_TO_LEFT.

Rt_TREND_VERTICAL

Make the trends vertical. If this is set, you must also set exactly one of Rt_TREND_TOP_TO_BOTTOM and Rt_TREND_BOTTOM_TO_TOP.

Rt_TREND_LEFT_TO_RIGHT

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

Rt_TREND_RIGHT_TO_LEFT

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

Rt_TREND_TOP_TO_BOTTOM

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

Rt_TREND_BOTTOM_TO_TOP

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

If you set Rt_ARG_TREND_FLAGS to an invalid value, the widget will draw only the background.

Rt_ARG_TREND_GRID_COLOR

The color of the grid, specified as an RGB value. The grid is displayed only if Rt_GRID is set in Rt_ARG_TREND_FLAGS.

Rt_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 Rt_GRID is set in Rt_ARG_TREND_FLAGS.

Rt_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 Rt_GRID is set in Rt_ARG_TREND_FLAGS.

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

Rt_ARG_TREND_MAX

The maximum data value for all the trends.

Rt_ARG_TREND_MIN

The minimum data value for all the trends.

Rt_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 RtTrend widget and you want to make sure their palette entries don't overlap.

Each RtTrend widget uses:

• two palette entries for each entry in the Rt_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 Rt_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 Rt_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 RtTrend widget defines the following convenience functions that make it easier to use the widget once it's been created:

RtTrendChangeData()

Replace some samples for all trends

RtTrendChangeTrendData()

Replace some samples for one trend