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

Next: XYPlot Attributes, Previous: XYPlot Interaction, Up: XYPlot Object [Contents][Index]

#### 21.2.4 Other XYPlot Routines

There are several routines to change the appearance of an XYPlot. First of all, you can change the number of tic marks using the following routine

    void fl_set_xyplot_xtics(FL_OBJECT *obj, int major, int minor);
    void fl_set_xyplot_ytics(FL_OBJECT *obj, int major, int minor);

where `major` and `minor` are the number of tic marks to be placed on the axis and the number of divisions between major tic marks. In particular, -1 suppresses the tic marks completely while 0 restores the default settings (which is 5 for the major and 2 for the minor tic arguments).

Note that the actual scaling routine may choose a value other than that requested if it decides that this would make the plot look nicer, thus `major` and `minor` are only taken as a hint to the scaling routine. However, in almost all cases the scaling routine will not generate a major tic that differs from the requested value by more than 3.

Normally the minor tics of logarithmic scales are drawn equidistant. To have them also drawn logarithmically use the functions

    int fl_set_xyplot_log_minor_xtics(FL_OBJECT *obj, int yesno);
    int fl_set_xyplot_log_minor_ytics(FL_OBJECT *obj, int yesno);

With this enabled e.g., the minor tics between 1 and 10 (when the interval is to be divided into 5 subintervals) will be drawn at the positions 2, 4, 6, and 8 instead of at 10^0.2, 10^0.4, 10^0.6 and 10^0.8. The functions return the previous setting.

It is possible to label the major tic marks with alphanumerical characters instead of numerical values. To this end, use the following routines

    void fl_set_xyplot_alphaxtics(FL_OBJECT *obj, const char *major,
                                  const char *minor);
    void fl_set_xyplot_alphaytics(FL_OBJECT *obj, const char *major,
                                  const char *minor);

where `major` is a string specifying the labels with the embedded character `|` that specifies major divisions. For example, to label a plot with Monday, Tuesday etc, `major` should be given as `"Monday|Tuesday|..."`.

Parameter `minor` is currently unused and the minor divisions are set to 1, i.e, no divisions between major tic marks. Naturally the number of major/minor divisions set by this routine and `fl_set_xyplot_xtics()` and `fl_set_xyplot_ytics()` can’t be active at the same time and the one that gets used is the one that was set last.

The above two functions can also be used to specify non-uniform and arbitary major divisions. To achieve this you must embed the major tic location information in the alphanumerical text. The location information is introduced by the `@` symbol and followed by a float or integer number specifying the coordinates in world coordinates. The entire location info should follow the label. For example, `"Begin@1|3/4@0.75|1.9@1.9"` will produce three major tic marks at 0.75, 1.0, and 1.9 with labels "3/4", "begin" and "1.9".

To get a gridded XYPlot use the following routines

    void fl_set_xyplot_xgrid(FL_OBJECT *obj, int xgrid);
    void fl_set_xyplot_ygrid(FL_OBJECT *obj, int ygrid);

where `xgrid` and `ygrid` can be one of the following

`FL_GRID_NONE`

  No grid.

`FL_GRID_MAJOR`

  Grid for the major divisions only.

`FL_GRID_MINOR`

  Grid for both the major and minor divisions.

The grid line by default is drawn using a dotted line, which you can change using the routine

    int fl_set_xyplot_grid_linestyle(FL_OBJECT *obj, int style);

where `style` is the line style (`FL_SOLID`, `FL_DASH` etc. See Drawing Objects, for a complete list). The function returns the old grid linestyle.

By default, the plotting area is automatically adjusted for tic labels and titles so that a maximum plotting area results. This can in certain situations be undesirable. To control the plotting area manually, the following routines can be used

    void fl_set_xyplot_fixed_xaxis(FL_OBJECT *obj, const char *lm,
                                   const char *rm)
    void fl_set_xyplot_fixed_yaxis(FL_OBJECT *obj, const char *bm,
                                   const char *tm)

where `lm` and `rm` specify the right and left margin, respectively, and `bm` and `tm` the bottom and top margins. The pixel amounts are computed using the current label font and size. Note that even for y-axis margins the length of the string, not the height, is used as the margin, thus to leave space for one line of text, a single character (say `m`) or two narrow characters (say `ii`) should be used.

To restore automatic margin computation, set all margins to `NULL`.

To change the size of the symbols drawn at data points, use the following routine

    void fl_set_xyplot_symbolsize(FL_OBJECT *obj, int size);

where `size` should be given in pixels. The default is 4.

For `FL_POINTS_XYPLOT` and `FL_LINEPOINTS_XYPLOT` (main plot or overlay), the application program can change the symbol using the following routine

    typedef void (*FL_XYPLOT_SYMBOL)(FL_OBJECT *, int id,
                                     FL_POINT *p, int n, int w, int h);
    FL_XYPLOT_SYMBOL fl_set_xyplot_symbol(FL_OBJECT *obj, int id,
                                          FL_XYPLOT_SYMBOL symbol);

where `id` is the overlay id (0 means the main plot, and you can use -1 to indicate all), and `symbol` is a pointer to the function that will be called to draw the symbols on the data point. The parameters passed to this function are the object pointer, the overlay `id`, the center of the symbol (`p->x`, `p->y`), the number of data points (`n`) and the preferred symbol size (`w`, `h`). If the type of the XYPlot corresponding to `id` is not `FL_POINTS_XYPLOT` or `FL_LINESPOINTS_XYPLOT`, the function will not be called.

To change for example a `FL_LINEPOINTS_XYPLOT` XYPlot to plot filled small circles instead of the default crosses, the following code could be used

    void drawsymbol(FL_OBJECT *obj, int id,
                    FL_POINT *p, int n, int w, int h) {
        int r = (w + h) / 4;
        FL_POINT *ps = p + n;

        for (; p < ps; p++)
            fl_circf(p->x, p->y, r, FL_BLACK);
    }

    ...
    fl_set_xyplot_symbol(xyplot, 0, drawsymbol);
    ...

If a Xlib drawing routine is used it should use the current active window (`FL_ObjWin(obj)`) and the current GC. Take care not to call routines inside the `drawsymbol()` function that could trigger a redraw of the XYPlot (such as `fl_set_object_color()`, `fl_set_xyplot_data()` etc.).

To use absolute bounds (as opposed to the bounds derived from the data), use the following routines

    void fl_set_xyplot_xbounds(FL_OBJECT *obj, double min, double max);
    void fl_set_xyplot_ybounds(FL_OBJECT *obj, double min, double max);

Data that fall outside of the range set this way will be clipped. To restore autoscaling, call the function with `max` and `min` set to exactly the same value. To reverse the axes (e.g., `min` at right and `max` at left), set `min > max` for that axis.

To get the current bounds, use the following routines

    void fl_get_xyplot_xbounds(FL_OBJECT *obj, float *min, float *max);
    void fl_get_xyplot_ybounds(FL_OBJECT *obj, float *min, float *max);

To replace the value of a particular point use the routine

    void fl_replace_xyplot_point(FL_OBJECT *obj, int index,
                                 double x, double y);

Here `index` is the index of the value to be replaced. The first value has an index of 0.

It is possible to overlay several plots together by calling

    void fl_add_xyplot_overlay(FL_OBJECT *obj, int id, float *x, float *y,
                               int npoints, FL_COLOR col);

where `id` must be between 1 and `FL_MAX_XYPLOTOVERLAY` (currently 32). This limit can be raised (or lowered) by calling the function `fl_set_xyplot_maxoverlays()`. Again, the data are copied to an internal buffer (old data are freed if necessary).

As for the base data, a data file can be used to specify the (x,y) function

    int fl_add_xyplot_overlay_file(FL_OBJECT *obj, int ID,
                                   const char *file, FL_COLOR col);

The function returns the number of data points successfully read. The type (`FL_NORMAL_XYPLOT` etc.) used in overlay plot is the same as the object itself.

To change an overlay style, use the following call

    void fl_set_xyplot_overlay_type(FL_OBJECT *obj, int id, int type);

Note that although the API of adding an overlay is similar to adding an object, an XYPlot overlay is not a separate object. It is simply a property of an already existing XYPlot object.

To get the data of an overlay, use the following routine

    void fl_get_xyplot_overlay_data(FL_OBJECT *obj, int id,
                                    float x[], float y[], int *n);

where `id` specifies the overlay number between 1 and `FL_MAX_XYPLOTOVERLAY` or the number set via `fl_set_xyplot_maxoverlays()` (see below). (Actually, when `id` is zero, this function returns the base data). The caller must supply the storage space for the data. Upon function return, `n` will be set to the number of data points retrieved.

Sometimes it may be more convenient and efficient to get the pointer to the data rather than a copy of the data. To this end, the following routine is available

    void fl_get_xyplot_data_pointer(FL_OBJECT *obj, int id,
                                    float **x, float **y, int *n);

Upon function return, `x` and `y` are set to point to the data storage. You’re free to modify the data and redraw the XYPlot (via `fl_redraw_object()`). The pointers returned may not be freed.

If needed, the maximum number of overlays an object can have (which by default is 32) can be changed using the following routine

    int fl_set_xyplot_maxoverlays(FL_OBJECT *obj, int maxoverlays);

The function returns the previous maximum number of overlays. If the new number is smaller that what it was before overlays with IDs higher that the previous number are deleted.

To obtain the number of data points, use the routine

    int fl_get_xyplot_numdata(FL_OBJECT *obj, int id);

where `id` is the overlay ID (with 0 being the base data set).

To insert a point into an xyplot, use the following routine

    void fl_insert_xyplot_data(FL_OBJECT *obj, int id, int n,
                               double x, double y);

where `id` is the overlay ID; `n` is the index of the point after which the data new point specified by `x` and `y` is to be inserted. Set `n` to -1 to insert the point in front. To append to the data, set `n` to be equal or larger than the return value of `fl_get_xyplot_numdata(obj, id)`.

To delete an overlay, use the following routine

    void fl_delete_xyplot_overlay(FL_OBJECT *obj, int id);

It is possible to place inset texts on an XYPlot using the following routine (up to `FL_MAX_XYPLOTOVERLAY` or the value set via `fl_set_xyplot_maxoverlays()` of such insets can be accommodated):

    void fl_add_xyplot_text(FL_OBJECT *obj, double x, double y,
                            const char *text, int align, FL_COLOR col);

where `x` and `y` are the (world) coordinates where text is to be placed and align specifies the placement options relative to the specified point (See `fl_set_object_lalign()` for valid options). If you for example specify `FL_ALIGN_LEFT`, the text will appear on the left of the point and flushed toward the point (see Fig. 21.1). This is mostly consistent with the label alignment except that now the bounding box (of the point) is of zero dimension. Normal text interpretation applies, i.e., if text starts with `@` a symbol is drawn.

To remove an inset text, use the following routine

    void fl_delete_xyplot_text(FL_OBJECT *obj, const char *text);

Another kind of inset is the "keys" to the plots. A key is the combination of drawing a segment of the plot line style with a piece of text that describes what the corrsponding line represents. Obviously, keys are most useful when you have more than one plot (i.e., overlays). To add a key to a particular plot, use the following routine

    void fl_set_xyplot_key(FL_OBJECT *obj, int id, const char *keys);

where `id` again is the overlay ID. To remove a key, set the key to `NULL`. All the keys will be drawn together inside a box. The position of the keys can be set via

    void fl_set_xyplot_key_position(FL_OBJECT *obj, float x, float y,
                                    int align)

where `x` and `y` should be given in world coordinates. `align` specifies the alignment of the entire key box relative to the given position (see Fig.21.1).

The following routine combines the above two functions and may be more convenient to use

    void fl_set_xyplot_keys(FL_OBJECT *obj, char *keys[],
                             float x, float y, int align);

where `keys` specifies the keys for each plot. The last element of the array must be `NULL` to indicate the end. The array index is the plot id, i.e., `key[0]` is the key for the base plot, `key[1]` the key for the the first overlay etc.

To change the font the key text uses, the following routine is available

    void fl_set_xyplot_key_font(FL_OBJECT *obj, int style, int size);

Data may be interpolated using an nth order Lagrangian polynomial:

    void fl_set_xyplot_interpolate(FL_OBJECT *obj, int id, int degree,
                                   double grid);

where `id` is the overlay ID (use 0 for the base data set); `degree` is the order of the polynomial to use (between 2 and 7) and `grid` is the working grid onto which the data are to be interpolated. To restore the default linear interpolation, use `degree` set to 0 or 1.

To change the line thickness of an xyplot (base data or overlay), the follow routine is available:

    void fl_set_xyplot_linewidth(FL_OBJECT *obj, int id, int width);

Again, use a `id` of value 0 to indicate the base data. Setting `width` to zero restores the server default and typically is the fastest.

By default, a linear scale in both the x and y direction is used. To change the scaling, use the following call

    void fl_set_xyplot_xscale(FL_OBJECT *obj, int scale, double base);
    void fl_set_xyplot_yscale(FL_OBJECT *obj, int scale, double base);

where the valid scaling options for scale are q`FL_LINEAR` and `FL_LOG`, and `base` is used only for `FL_LOG` and in that case is the base of the logarithm to be used.

Use the following routine to clear an xyplot

    void fl_clear_xyplot(FL_OBJECT *obj);

This routine frees all data associated with an XYPlot, including all overlays and all inset texts. This routine does not reset all plotting options, such as line thickness, major/minor divisions etc. nor does it free all memories associated with the XYPlot, for this `fl_free_object()` is needed.

The mapping between the screen coordinates and data can be obtained using the following routines

    void fl_get_xyplot_xmapping(FL_OBJECT *obj, float *a, float *b);
    void fl_get_xyplot_xmapping(FL_OBJECT *obj, float *a, float *b);

where `a` and `b` are the mapping constants and are used as follows:

    screenCoord = a * data + b                 (linear scale)
    screenCoord = a * log(data) / log(p) + b   (log scale)

where `p` is the base of the requested logarithm.

If you need to do conversions only occasionally (for example, converting the position of a mouse click to a data point or vice versa) the following routines might be more convenient

    void fl_xyplot_s2w(FL_OBJECT *obj, double sx, double sy,
                       float *wx, float *wy);
    void fl_xyplot_w2s(FL_OBJECT *obj, double wx, double wy,
                       float *sx, float *sy);

where `sx` and `sy` are the screen coordinates and `wx` and `wy` are the world coordinates.

Finally, there’s a function for returning the coordinates of the area of the object used for drawing the data (i.e., the area, when axes are displayed, which is enclosed by the axes):

    void fl_get_xyplot_screen_area(FL_OBJECT *obj,
                                   FL_COORD *llx, FL_COORD *lly,
                                   FL_COORD *urx, FL_COORD *ury);
    void fl_get_xyplot_world_area(FL_OBJECT *obj,
                                  float *llx, float *lly,
                                  float *urx, float *ury);

where via `llx` and `lly` the coordinates of the lower left hand corner and via `urx` and `ury` those of the upper right hand corner are returned. The first function returns the corner positions in screen coordinates (relative to the object), while the secoind returns them in "world" coordinates.

Per default an XYPlot object only reacts to the left mouse button. But sometimes it can be useful to modify this. To set this call

    void fl_set_xyplot_mouse_buttons(FL_OBJECT *obj,
                                     int mbuttons);

`mbuttons` is the bitwise OR of the numbers 1 for the left mouse button, 2 for the middle and 4 for the right mouse button.

To determine which mouse buttons an XYPlot object reacts to use

    void fl_get_xyplot_mouse_buttons(FL_OBJECT *obj,
                                     unsigned int *mbuttons);

The value returned via `mbuttons` is the same value as would be used in `fl_set_slider_mouse_buttons()`.

Next: XYPlot Attributes, Previous: XYPlot Interaction, Up: XYPlot Object [Contents][Index]