PtTrend

A trend graph

Class hierarchy:

PtWidgetPtBasicPtTrend

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

PhAB icon:

PtTrend button in PhAB

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.


PtTrend


A PtTrend widget.

New resources:

Resource C type Pt type Default
Pt_ARG_TREND_ATTRIBUTES PtTrendAttr_t, short Array 1 or (1,1,1,1..)
Pt_ARG_TREND_COLOR_LIST PgColor_t, short Array NULL
Pt_ARG_TREND_COUNT int Scalar 1
Pt_ARG_TREND_DATA short, int Array None (write-only)
Pt_ARG_TREND_FLAGS long Flag See below
Pt_ARG_TREND_GRID_COLOR PgColor_t Scalar Pg_GRAY
Pt_ARG_TREND_GRID_X short int Scalar 5
Pt_ARG_TREND_GRID_Y short int Scalar 5
Pt_ARG_TREND_INC short int Scalar 1
Pt_ARG_TREND_MAX short int Scalar SHRT_MAX
Pt_ARG_TREND_MIN short int Scalar SHRT_MIN
Pt_ARG_TREND_PALETTE_END unsigned short Scalar 256

Pt_ARG_TREND_ATTRIBUTES

C type Pt type Default
PtTrendAttr_t, short Array 1 or (1,1,1,1..)

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:
Index Color used
0 Pt_ARG_FILL_COLOR (that is, the background color for the widget)
1 the first color in Pt_ARG_TREND_COLOR_LIST (which is the same as Pt_ARG_COLOR)
2 the second color in Pt_ARG_TREND_COLOR_LIST
3 etc.

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

Note: 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

C type Pt type Default
PgColor_t, short Array NULL

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.


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

Pt_ARG_TREND_COUNT

C type Pt type Default
int Scalar 1

The number of trends that the widget displays.

Pt_ARG_TREND_DATA (write-only)

C type Pt type Default
short, int Array None

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

C type Pt type Default
long Flag Pt_TREND_HORIZONTAL | Pt_GRID | Pt_TREND_RIGHT_TO_LEFT | Pt_GRID_IS_TRANSLUCENT

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.

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

Pt_ARG_TREND_GRID_COLOR

C type Pt type Default
PgColor_t Scalar Pg_GRAY

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

C type Pt type Default
short int Scalar 5

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

C type Pt type Default
short int Scalar 5

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

C type Pt type Default
short int Scalar 1

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

C type Pt type Default
short int Scalar SHRT_MAX

The maximum data value for all the trends.

Pt_ARG_TREND_MIN

C type Pt type Default
short int Scalar SHRT_MIN

The minimum data value for all the trends.

Pt_ARG_TREND_PALETTE_END

C type Pt type Default
unsigned short Scalar 256

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:

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.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic Pg_RED
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_BLACK
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget
Pt_ARG_STYLE PtBasic
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_UNREALIZED PtWidget

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