PtMTrend

A medical trend widget

Class hierarchy:

PtWidget → PtBasic → PtMTrend

PhAB icon:

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:

• A trace mode that displays a trace line, indicating where new data is being drawn.
• Each graph has its own minimum and maximum values.
• Customizable line thickness and join type for each graph.
• You can provide your own customized functions for drawing graphs, the grid, and the trace line.

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

---

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:

Pt_ARG_MTREND_FLAGS

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

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

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

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

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

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

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

The trace strip color.

Pt_ARG_MTREND_TRACE_DRAW_F

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

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

Pt_ARG_MTREND_GRID_Y

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

Pt_ARG_MTREND_GRID_COLOR

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

Pt_ARG_MTREND_GRID_DRAW_F

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

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.

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.