XYPlot Interaction (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Other XYPlot Routines, Previous: XYPlot Types, Up: XYPlot Object [Contents][Index]

#### 21.2.3 XYPlot Interaction

Only `FL_ACTIVE_XYPLOT` report mouse events by default. Clicking and dragging the data points (marked with little squares) will change the data and result in the object getting returned to the application (or the object’s callback getting invoked). By default, the reporting happens only when the mouse is released. In some situations, reporting changes as soon as they happen might be desirable. To control when mouse events are returned use the function

    int fl_set_object_return(FL_OBJECT *obj, unsigned int when);

where `when` can have the folowing values:

`FL_RETURN_NONE`

  Never return or invoke callback.

`FL_RETURN_END_CHANGED`

  Return or invoke callback at end (mouse release) if one of the points has been moved to a different place. This is the default.

`FL_RETURN_CHANGED`

  Return or invoke callback whenever a point has been moved.

`FL_RETURN_END`

  Return or invoke callback at end (mouse release) regardless if a point has been moved is changed or not.

`FL_RETURN_ALWAYS`

  Return or invoke callback when a point has been moved or the mouse button has been release).

Please note: an object can also be in inspect mode (see function `fl_set_xyplot_inspect()` below). In this case the object gets returned (or its callback invoked) for all of the above settings except (`FL_RETURN_NONE`) when the mouse was released on top of one of the points.

To obtain the current value of the point that has changed, use the routine

    void fl_get_xyplot(FL_OBJECT *obj, float *x, float *y, int *i);

where via `i` the data index (starting from 0) is returned while via `x` and `y` the actual data point gets returned. If no point has changed `i` will be set to -1.

It is possible to switch drawing of the squares that mark an active plot on and off (default is on) using the following routine

    void fl_set_xyplot_mark_active(FL_OBJECT *obj, int yes_no);

with `yes_no` being set to false (0).

To set or replace the data for an xyplot, use

    void fl_set_xyplot_data(FL_OBJECT *obj, float *x, float *y, int n,
                            const char *title, const char *xlabel,
                            const char *ylabel);
    void fl_set_xyplot_data_double(FL_OBJECT *obj, double *x, double *y, int n,
                                   const char *title, const char *xlabel,
                                   const char *ylabel);

(The `fl_set_xyplot_data_double()` function allows to pass data of type `double` but which get "demoted" to `float` type when assigned to the xyplot object.) Here `x`, `y` is the tabulated function, and `n` is the number of data points. If the xyplot object being set already exists old data will be cleared. Note that the tabulated function is copied internally so you can free or do whatever you want with the `x` and `y` arrays after the function has returned. `title` is a title that is drawn above the XYPlot and `xlabel` and `ylabel` are the labels drawn at the x- and y-axes.

You can also load a tabulated function from a file using the routine

    int fl_set_xyplot_file(FL_OBJECT *obj, const char *filename,
                           const char *title, const char *xlabel,
                           const char *ylabel);

The data file should be an ASCII file consisting of data lines. Each data line must have two columns, indicating the (x,y) pair with a space, tab or comma separating the two columns. Lines that start with any of `!`, `;` or `#` are considered to be comments and are ignored. The functions returns the number of data points successfully read or 0 if the file couldn’t be opened.

To get a copy of the current XYPLot data, use

    int fl_get_xyplot_data_size(FL_OBJECT *obj);
    void fl_get_xyplot_data(FL_OBJECT *obj, float *x, *float y, int *n);

The first function returns the number of data points which the second will return. The caller must supply the space for the data returned by `fl_get_xyplot_data()`. The last argument of that function is again the number of points that got returned.

All XYPlot objects can be made aware of mouse clicks by using the following routine

    void fl_set_xyplot_inspect(FL_OBJECT *obj, int yes_no);

Once an XYPlot is in inspect mode, whenever the mouse is released and the mouse position is on one of the data point, the object is returned to the caller or its callback is invoked. You then can use `fl_get_xyplot()` to find out which point the mouse was clicked on. Note that for an object of type `FL_ACTIVE_XYPLOT` the data can’t be modified while in inspect mode!

Another, perhaps even more general, way to obtain the values from an XYPlot is to use a posthandler or an overlay positioner. See demo `xyplotall.c` for the use of posthandler and `positionerXOR.c` for an example of reading-out xyplot values using an overlayed positioner.

Next: Other XYPlot Routines, Previous: XYPlot Types, Up: XYPlot Object [Contents][Index]