PtMTrend

A medical trend widget

Class hierarchy:

PtWidgetPtBasicPtMTrend

PhAB icon:

PtMTrend button in PhAB

Public header:

<photon/PtMTrend.h>

Description:

A PtMTrend widget displays trend graphs intended for medical applications. 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, or at a rate specified by the application.

PtMTrend is similar to PtTrend, but with some added capabilities:


PtMTrend


A PtMTrend widget.

Example

This simple example illustrates how you can display data in a PtMTrend widget (in this case, random data generated by a timer callback):

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <Pt.h>

/****************************************************************** STATICS ***/
static  PtWidget_t  *feed_toggle_wgt, *mtrend_wgt;

/*************************************************************** TIMER_CB() ***/
// This is the function which is changing (feeding) the trend widget data.
int
timer_cb( PtWidget_t *widget, void *data, PtCallbackInfo_t *cbinfo )
{
    if( Pt_SET & PtWidgetFlags( feed_toggle_wgt ) ) {
        int val1 = rand() % 100,
            val2 = rand() % 200;
        PtMTrendAddData( mtrend_wgt, 0, &val1, 1 );
        PtMTrendAddData( mtrend_wgt, 1, &val2, 1 );
    }
    return Pt_CONTINUE;
}

/******************************************************************* MAIN() ***/
int
main( int argc, char *argv[] )
{
    PtWidget_t     *window, *wgt;
    PtArg_t         args[20];
    int             i;

    // application window
    i = 0;
    PtSetArg( &args[i++], Pt_ARG_WINDOW_TITLE, "MTrend Sample Application", 0 );
    PtSetArg( &args[i++], Pt_ARG_HEIGHT, 200, 0 );
    PtSetArg( &args[i++], Pt_ARG_WIDTH,  400, 0 );

    if( NULL == ( window = PtAppInit( NULL, &argc, argv, i, args ) ) ) {
        perror( "PtAppInit()" );
        return 1;
    }

    // feed toggle
    i = 0;
    PtSetArg( &args[i++], Pt_ARG_TEXT_STRING, "Feed data", 0 );
    feed_toggle_wgt = PtCreateWidget( PtToggleButton, NULL, i, args );

    // mtrend
    {
        PhArea_t        area = { {20, 30}, {360,140} };
        PtMTrendAttr_t  graph1_attr[] = { Pt_MTREND_STATE_SHOWN, Pg_RED, 1,
                                          Pg_MITER_JOIN, 0, 100 };
        PtMTrendAttr_t  graph2_attr[] = { Pt_MTREND_STATE_SHOWN, Pg_BLUE, 1,
                                          Pg_MITER_JOIN, 0, 200 };

        i = 0;
        PtSetArg( &args[i++], Pt_ARG_MTREND_N_GRAPHS, 2, 0 );
        PtSetArg( &args[i++], Pt_ARG_MTREND_N_SAMPLES, 100,  0 );
        PtSetArg( &args[i++], Pt_ARG_MTREND_FLAGS, Pt_TRUE, Pt_MTREND_BLIT );
        PtSetArg( &args[i++], Pt_ARG_MTREND_GRAPH_ATTR, &graph1_attr, 0 );
        PtSetArg( &args[i++], Pt_ARG_MTREND_GRAPH_ATTR, &graph2_attr, 1 );
        PtSetArg( &args[i++], Pt_ARG_AREA, &area, 0 );

        mtrend_wgt = PtCreateWidget( PtMTrend, NULL, i, args );
    }

    // timer
    {
        PtCallback_t callback = { timer_cb, NULL };

        i = 0;
        PtSetArg( &args[i++], Pt_ARG_TIMER_INITIAL, 100, 0 );
        PtSetArg( &args[i++], Pt_ARG_TIMER_REPEAT, 100, 0 );
        PtSetArg( &args[i++], Pt_CB_TIMER_ACTIVATE, &callback, 0 );

        PtCreateWidget( PtTimer, NULL, i, args );
    }

    PtRealizeWidget( window );

    PtMainLoop();
    return 0;
}

Note: To run this example, save it as a file named mtrend_sample.c, and compile it with cc -o mtrend_sample -lph mtrend_sample.c. You can then run the application ./mtrend_sample.

New resources:

Resource C type Pt type Default
Pt_ARG_MTREND_FLAGS int Flag Pt_MTREND_ALWAYS_SCROLL
Pt_ARG_MTREND_N_SAMPLES unsigned Scalar 0
Pt_ARG_MTREND_N_GRAPHS unsigned Scalar 0
Pt_ARG_MTREND_GRAPH_ATTR PtMTrendAttr_t Struct N/A
Pt_ARG_MTREND_GRAPH_STATE int Scalar N/A
Pt_ARG_MTREND_GRAPH_DATA PtMTrendData_t Struct N/A
Pt_ARG_MTREND_TRACE_WIDTH int Scalar 5
Pt_ARG_MTREND_TRACE_COLOR PgColor_t Scalar 0xC0C0C0
Pt_ARG_MTREND_TRACE_DRAW_F See below pointer N/A
Pt_ARG_MTREND_GRID_X unsigned Scalar 5
Pt_ARG_MTREND_GRID_Y unsigned Scalar 5
Pt_ARG_MTREND_GRID_COLOR PgColor_t Scalar 0xC0C0C0
Pt_ARG_MTREND_GRID_DRAW_F See below pointer N/A
Pt_ARG_MTREND_ADVANCE_BY_N_SAMPLES unsigned Scalar 1

Pt_ARG_MTREND_FLAGS

C type Pt type Default
int Flag 0

Flags that control the way the widget draws data.

Direction flags; one of:

Pt_MTREND_HORZ_L2R
Draw the trend left to right.
Pt_MTREND_HORZ_R2L
Draw the trend right to left.
Pt_MTREND_VERT_T2B
Draw the trend top to bottom.
Pt_MTREND_VERT_B2T
Draw the trend bottom to top.

When setting the direction flag, use Pt_MTREND_DIRECTION_MASK as the len argument for the PtSetArg() or PtSetResource() function.

Grid flags; one of:

Pt_MTREND_GRID_NONE
Do not show a grid.
Pt_MTREND_GRID_ABOVE
Draw the grid over the graphs.
Pt_MTREND_GRID_BELOW
Draw the grid under the graphs.

To set the grid, use Pt_MTREND_GRID_MASK as the len argument for the PtSetArg() or PtSetResource() function.

Graphs drawing mode; one of:

Pt_MTREND_TRACE
Draw a trace line indicating where new graph data is being drawn on the trend.
Pt_MTREND_BLIT
Use blit mode — blit the data to reduce CPU use. Blit mode is available only if Pt_MTREND_TRACE isn't set and no grid is shown.
Pt_MTREND_ALWAYS_SCROLL
When data is first drawn on an empty graph, start drawing from the side of the graph that represents the newest data. The side that represents new data is dependent on the direction flag. For example, if the direction is Pt_MTREND_HORZ_L2R, new data is drawn on the right hand side of the graph, and older data is scrolled to the left.

If this flag is not set, when data is first drawn in the graph, it is drawn on the side that represents old data. Once the graph fills with data, it begins to scroll in the direction indicated by the direction flag.

Pt_ARG_MTREND_N_SAMPLES

C type Pt type Default
unsigned Scalar 0

The maximum number of samples shown in the trend. If you reduce this number when there is sample data in the trend, the oldest samples are trimmed.

Pt_ARG_MTREND_N_GRAPHS

C type Pt type Default
unsigned Scalar 0

The number of graphs drawn in the trend. Note that graphs are numbered starting at 0, but this resource indicates the actual number of graphs.

If you add new graphs to a trend widget, they appear with minimum values until you set the graph data. If you reduce the number of graphs, existing graphs are removed from the trend. For example, if you have 5 graphs numbered 0 to 4 in your trend, and you change Pt_ARG_MTREND_N_GRAPHS from 5 to 3, graphs 3 and 4 are removed from the trend.

Pt_ARG_MTREND_GRAPH_ATTR

C type Pt type Default
PtMTrendAttr_t Struct N/A

Set attributes of a graph. PtMTrendAttr_t contains the following members, which your application must fill in:

int state
The trend state; one of Pt_MTREND_STATE_SHOWN (visible) or Pt_MTREND_STATE_HIDDEN (not visible).
PgColor_t color
The line color.
int line_thickness
The line thickness, in pixels.
int join_type
The line join type; see PgSetStrokeJoin() in the Photon Library Reference for more information about join types.
int min and max
The minimum and maximum values for sample data.
void *draw_f
A pointer to a customized draw function for the graph. You can set the pointer to your own function (see below).

To set your graph draw function, draw_f should be a pointer of type:

void (*draw_f)( PtWidget_t *widget,
                PhTile_t *damage,
                struct pt_mtrend_graph_info *attr );

The widget argument is a pointer to the trend widget of type PtMTrend. The damage argument is the damage list for the widget. The attr argument is type pt_mtrend_graph_info, which has at least the following attributes:

PtMTrendAttr_t attr
A structure containing the attribute information for the graph.
int n_samples
The total number of samples in the data buffer.
int *data
A pointer to an array of data for the graph, with the oldest data at position 0.

When setting this resource with PtSetArg() or PtSetResource(), pass the graph number as the len argument.

Pt_ARG_MTREND_GRAPH_STATE

C type Pt type Default
int Scalar N/A

Enables or disables graph drawing. Values:

Pt_MTREND_STATE_SHOWN
Draw the graph.
Pt_MTREND_STATE_HIDDEN
Don't draw the graph.

When setting this resource with PtSetArg() or PtSetResource(), pass the graph number as the len argument.

Pt_ARG_MTREND_GRAPH_DATA

C type Pt type Default
PtMTrendData_t Struct N/A

Use to add or change data for a specified graph. When setting this resource with PtSetArg() or PtSetResource(), pass the graph number as the len argument. The PtMTrendData_t contains at least these members:

int mode
Can be one of Pt_MTREND_ADD or Pt_MTREND_PUT
unsigned n_samples
The number of data samples in the data array.
unsigned last_sample
The sample number where to put new data into the buffer, if mode is Pt_MTREND_PUT.
const int *data
The data samples array.

For convenience, the library provides PtMTrendAddData() and PtMTrendChangeData() for working with data in the graphs.

Pt_ARG_MTREND_TRACE_WIDTH

C type Pt type Default
int Scalar 5

The width of the trace strip. If positive, this is the number of pixels. If negative, the width is calculated as the absolute value of this resource multiplied by the width of one data sample.

Pt_ARG_MTREND_TRACE_COLOR

C type Pt type Default
PgColor_t Scalar 0xC0C0C0

The trace strip color.

Pt_ARG_MTREND_TRACE_DRAW_F

C type Pt type Default
See below Pointer N/A

By default, a pointer to the default trace drawing function. You can provide your own drawing function for the trace line by setting this resource to a pointer with the following type:

void (*draw_f)( PtWidget_t *widget, PhTile_t *damage );

The arguments are:

widget
A pointer to a PtMTrendWidget_t structure. The function should use the trace.pos and trace.dim members of this structure for drawing.
damage
The damage list for the draw function.

Pt_ARG_MTREND_GRID_X

C type Pt type Default
unsigned Scalar 5

The number of vertical grid lines, if the grid is turned on.

Pt_ARG_MTREND_GRID_Y

C type Pt type Default
unsigned Scalar 5

The number of horizontal grid lines, if the grid is turned on.

Pt_ARG_MTREND_GRID_COLOR

C type Pt type Default
PgColor_t Scalar 0xC0C0C0

The grid line color, if the grid is turned on.

Pt_ARG_MTREND_GRID_DRAW_F

C type Pt type Default
See below Pointer N/A

A pointer to the default grid drawing function. You can provide your own customized grid drawing function by setting this resource to a pointer to a function of the following type:

void (*draw_f)( PtWidget_t *widget, PhTile_t *damage );

The arguments are:

widget
A pointer to a PtMTrendWidget_t structure. The function should use the grid.* members for drawing.
damage
The damage list for the widget.

Pt_ARG_MTREND_ADVANCE_BY_N_SAMPLES

C type Pt type Default
unsigned Scalar 1

This resource specifies the number of data samples to be shifted when the limit (the edge of the trend widget) is reached. If set to 1 (default), the trend appears to be continuously scrolling. That is, for each draw cycle, the trend is scrolled by one sample, then the new sample is drawn.

If you set this resource to a larger value, the trend scroll behavior is different. For example, if you set the value to 10, each time the trend reaches the end of the widget, the trend is scrolled back by ten samples. Ten more samples are drawn before the trend is scrolled again.

You can set this resource to a value larger than 1 only for trends that aren't in trace mode.

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 PtMTrend defines the following convenience functions that make it easier to use the widget once it's been created:

PtMTrendAddData()
Add data to a trend.
PtMTrendChangeData()
Change existing data in a trend.