Bargraph with Time-History
Histspectr





Classname: XwHistspectrWidgetClass

Description:

Sometimes, a calculated set of points shall be displayed as x/ graphic, p.e. A frequency spectrum. No, this calculation is repeated every n time interval and the result shall be displayed with the history. Tis is exactly what Histspectr does.
It displays a scan of points as y over x, next time it moves the previous scan a time delta into the background and plot the new one. As the region below the curve is filled, a 3D-like effect is generated. The widget is fast enough to plot scans of 100 point every 50 milliseconds and faster so generating a smooth 3D timehistory of spectrum like plots. The shape of a single plot may be changed between ponts and line, the background, curve, annotation and filling color may be changed. The annotation is optional, and may be defined with different digits after decimal points for each axis. Scaling may be setup at any time (clearing the display) or set to autoscale, where the next (two ) scans will be used to calculate the scale. In addition, a marker line may be set (and changed) at an abscissa value, resulting in a line of annotation color.

The following examples shows plot with some sine wave, annotation and a marker.

Example :

Resources:

The widget includes the »core« and the »primitive« class with all resources. To describe it's special features, it has several resources for it's own. The following table contains the resource-name, the resource-class and the access-type. Defining the resource in a general resourcefile like .Xdefaults, means, leave out the prefix XwN or XwC. The access type defines if the resource may be set at creation »C«, using XtSetValues »S«, only at creation using XtSetArg »CS« and being read using XtGetValues »G«.

Name

Class

Type

Default

Access

XmNexposeCallback

XmCExposeCallback

XtCallbackList

NULL

S C

XmNresizeCallback

XmCResizeCallback

XtCallbackList

NULL

S C

XwNhistspectrAutoscale

XwCHistspectrAutoscale

enum

NoAuto

S CS

XwNhistspectrGridScale

XwCHistspectrGridScale

Float[6]

NULL

CS S

XwNhistspectrScale

XwCHistspectrScale

Float[6]

NULL

CS S

XwNhistspectrBackground

XwCHistspectrBackground

Pixel

inherit

C S

XwNhistspectrAnnotColor

XwCHistspectrAnnotColor

Pixel

inherit

C S

XwNhistspectrFill

XwCHistspectrFill

Pixel

inherit

C S

XwNhistspectrCurveColor

XwCHistspectrCurveColor

Pixel

inherit

C S

XwNhistspectrAnnotTNdec

XwCHistspectrAnnotTNdec

Int

0

C S

XwNhistspectrAnnotXNdec

XwCHistspectrAnnotXNdec

Int

0

C S

XwNhistspectrAnnotYNdec

XwCHistspectrAnnotYNdec

Int

0

C S

XwNnistspectrAnnotTNgrid

XwCHistspectrAnnotTNgrid

Int

0

C S

XwNhistspectrAnnotXNgrid

XwCHistspectrAnnotXNgrid

Int

0

C S

XwNHistspectrAnnotYNgrid

XwCHistspectrAnnotYNgrid

Int

0

C S

XwNHistspectrAnnotation

XwCHistspectrAnnotation

Bool

TRUE

C S

XwNhistspectrAddtext

XwCHistspectrAddtext

Text

NULL

C S *

XwNhistspectrLines

XwCHistspectrLines

Bool

TRUE

C S

XmNfontList

XmCFontList

XmFontList

inherit

C S

XwNHistspectrAngle

XwCHistspectrAngle

Int

XwHistspectrDefaultAngle

C S

Detailed Description of special Resources:

Callbacks:

Possible Callbacks are:

XwNdestroyCallback, XmNexposeCallback, XmresizeCallback. Depending on type of callback, the items within the callbackstructure will have slightly different meaning.

Callback Structure: (not available using destroy callback)

typedef struct {
int reason;
XEvent *event; int fd;
Dimension width;
Dimension height;
}XwHistspectrCallbackStruct;



width and height are the dimension of the visible area used for 3D.



Normally there is no need to handle expose or resize, as the widget does all necessary things itself, but sometimes, it might be useful to react on resize,.





Resources, that must be set:

XwNHistspectrScale XwNHistspectrGridScale

There is no possibility to create a plot without having any scale, so these resources must be set at creation, they might be changed during lifetime.The only method to set them is using SetValue, as they need an array of six float values. The first pair defines the timescale, the second the ordinate, the third pair the abscissa. Hold in mind, that the ordinate scale describes only half of the height of the widget. There must be enough space for the history display. XwNHistspectrScale uses the first value as the minimum value of the visible area and the second as the size(width/height) of visible area. Internally it scales the total pixmap according to these values. XwNHistspectrGridScale uses the first value as the minimum (first) grid(and annotation) value and the second as distance to next annotation. Again, not only the visible, but the total pixmap will be given a time annotation.

Optional resources:

XwNhistspectrAutoscale

This resource may be set to a combination of flags, ored together:

AutoTime : uses the next two scans for calculating scal and grid of the timeaxis
AutoAbs : The next scan is used to calculate scale and grid of abscissa
AutoAmpl : The next scan is the base for scale and grid calculation of the ordinate. This might be a bit dangerous, as scans following later with bigger amplitudes may leave the window.

Resources, that should be set:



XwNHistspectrAnnotation

This resources defines the existance of annotation. Changing the resource at run-time will change the display immediately.

Possible values:
XwHistspectrAnno TRUE /* annotation */
XwHistspectrNoAnno FALSE/* no annotation */

XwNHistspectrAnnotTNdec XwNHistspectrAnnotYNdec XwNhistspectrAnnotXNdec


These three control the number of decimals for annotation. Be careful and reduce them to a minimum, as there is no protection against overwriting of numbers. Together with the GridScale it might happen, that the annotation distance is to small for big numbers, therefor the next two resources allow to skip some annotation items without drawing annotation. The number of decimals for the ordinate will influence the number of decimals for displaying the current value.

XwNHistspectrAnnotTNgrid XwNHistspectrAnnotYNgrid XwNhistspectrAnnotXNgrid

As the default of 1 shows, they define, how often annotation should be plotted to gridlines. So a value of 2 will say, that every other gridline gets annotation.

Additional controlling Resources:

Colours:

The colour of the bar itself must be set via a public function, as each bar may have a different colour. But all other colours, background, grid, annotation and annotation background may be set as resource.

Resource

Function

default

Remark

XwCHistspectrBackground

Background color of the plotting area

Inherited from background

No immediate change

XwNHistspectrAnnotColor

Color for Annotation text

Inherited from foreground

No immediate change

background

Background colour



XwNhistspectrCurveColor

Color of the plotted curve (or points)

Inherited from foreground


XwNhistspectrFill

Filling color under curve

Inherited from background


XwNhistspectrAddtext

Add a descriptive text a bottom of widget

Null

Valid only with annotation



Some of the above colors won't change immediately when you change the resource, but will be effective only when a total redraw is enforced,



Angle of z-axis(time)

XwNHistspectrAngle

This resource allows the user to change the history angle, influencing so the 3D-effect. The angle may be varied between 0 an 90 degree, the default is set to 45 degree.



Public Functions



XwHistdoscan

void XwHistdoscan (Widget w , w3dPoint xy[] . int npoints , float time);

The basic function for plotting. It adds an array of point pairs a a given time and plots the new curve, moving the remaining plot into the past. The Number of point pairs may vary from call to call, but this is not recommended.

The points must be given as an array of the following structure.

typedef struct {
float x;
float y;
}w3dPoint;



XwCreateHistspectr

Widget XwCreateHistspectr (Widget parent , char *name , ArgList arglist , Cardinal argcount);

Just a conveniance function for creating a Histspectr Widget.

XwHistspectrSettext

void XwHistspectrSettext (Widget w , int ID , char *text);

The given text will be displayed below the scaling area of abscissa using the annotation color. An empty text (or a NULL pointer) will delete the text display.

XwHistspectrSetMarker

void XwHistspectrSetMarker (Widget w ,float x);

The marker feature is set a the x position. To disable this feature, just set it outside the area of abscissa.

Example (code fragments)

#include "WHistspectr.h"

/* creating the widget */
n=0;
XtSetArg(args[n], XmNbottomAttachment, XmATTACH_FORM );n++;
XtSetArg(args[n], XmNleftAttachment, XmATTACH_FORM );n++;
XtSetArg(args[n], XmNrightAttachment, XmATTACH_FORM );n++;
{ float scal[6]={0.000000,100.000000,-250.000000,500.00,0.,2120} ,
grid[6]={0.000000,20.000000,-250.000000,100.000000,0.,500.};
XtSetArg(args[n], XmNx, 0); n++;
XtSetArg(args[n], XmNy, 36); n++;
XtSetArg(args[n], XwNhistspectrScale , scal ); n++;
XtSetArg(args[n],XwNhistspectrFill,MGetPixel("cyan", DI1));n++;
XtSetArg(args[n],XwNhistspectrLines ,FALSE ); n++;
XtSetArg(args[n], XwNhistspectrGridScale , grid ); n++;
XtSetArg(args[n],XwNhistspectrAnnotTNdec ,1 ); n++;
XtSetArg(args[n], XwNhistspectrAnnotYNdec ,2); n++;
XtSetArg(args[n], XwNhistspectrAnnotXNdec ,1 ); n++;
XtSetArg(args[n], XwNhistspectrAutoscale , AutoAbs ); n++;
DI1_WH1 = XwCreateHistspectr(DI1, "WH_1", args, n);
XtManageChild(DI1_WH1);
}

/* do a scan to plot */
void plot ( void ) {
w3dPoint xy[240];
int i;
for(i=0;i<216;i++){
xy[i].y = (sin(base + i*0.1) *(125*sin(base)+125) ) ;
xy[i].x = i*10.0;
}
XwHistdoscan ( DI1_WH1 , xy , 216, base);
base += 0.1;
plottimer = XtAppAddTimeOut(XtWidgetToApplicationContext(DI1_WH1), rate , (XtTimerCallbackProc)plot , NULL);
}