@node Part III Other Objects
@chapter Other Objects


@ifnottex
@menu
* Timer Object:     Timer Object
* XYPlot Object:    XYPlot Object
* Canvas Object:    Canvas Object
@end menu

@end ifnottex


@node Timer Object
@section Timer Object

Timer objects can be used to make a timer that runs down toward 0 or
runs up toward a pre-set value after which it starts blinking and
returns itself to the application program. This can be used in many
different ways, for example, to give a user a certain amount of time
for completing a task, etc. Also hidden timer objects can be created.
In this case the application program can take action at the moment the
timer expires. For example, you can use this to show a message that
remains visible until the user presses the "OK" button or until a
certain amount of time has passed.

The precision of the timer is not very high. Don't count on anything
better than, say, 50 milli-seconds. Run demo @file{timerprec.c} for an
actual accuracy measurement.


@ifnottex

@menu
* Adding Timer Objects:    Adding Timer Objects
* Timer Types:             Timer Types
* Timer Interaction:       Timer Interaction
* Other Timer Routines:    Other Timer Routines
* Timer Attributes:        Timer Attributes
* Remarks:                 Timer Remarks
@end menu

@end ifnottex


@node Adding Timer Objects
@subsection Adding Timer Objects

To add a timer to a form you use the routine
@findex fl_add_timer()
@anchor{fl_add_timer()}
@example
FL_OBJECT *fl_add_timer(int type, FL_Coord x, FL_Coord y,
                        FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual.


@node Timer Types
@subsection Timer Types

There are at the moment three types of timers:
@table @code
@tindex FL_NORMAL_TIMER
@item FL_NORMAL_TIMER
Visible, Shows a label in a box which blinks when the timer expires.
@tindex FL_VALUE_TIMER
@item FL_VALUE_TIMER
Visible, showing the time left or the elapsed time. Blinks if the
timer expires.
@tindex FL_HIDDEN_TIMER
@item FL_HIDDEN_TIMER
Not visible.
@end table


@node Timer Interaction
@subsection Timer Interaction

When a visible timer expires it starts blinking. The user can stop the
blinking by pressing the mouse on it or by resetting the timer to 0.

The timer object is returned to the application program or its
callback called when the timer expired per default. You can
also switch off reporting the expiry of the timer by calling
@example
int fl_set_object_return(FL_OBJECT *obj, unsigned int when)
@end example
with @code{when} set to @code{@ref{FL_RETURN_NONE}}. To re-enable
reporting call it with one of @code{@ref{FL_RETURN_CHANGED}},
@code{@ref{FL_RETURN_END}}, @code{@ref{FL_RETURN_END_CHANGED}} or
@code{@ref{FL_RETURN_ALWAYS}}.


@node Other Timer Routines
@subsection Other Timer Routines

To set the timer to a particular value use
@findex fl_set_timer()
@anchor{fl_set_timer()}
@example
void fl_set_timer(FL_OBJECT *obj, double delay);
@end example
@noindent
@code{delay} gives the number of seconds the timer should run.
Use 0.0 to reset/de-blink the timer.

To obtain the time left in the timer use
@findex fl_get_timer()
@anchor{fl_get_timer()}
@example
double fl_get_timer(FL_OBJECT *obj);
@end example

 By default, a timer counts down toward zero and the value shown (for
@code{FL_VALUE_TIMER}s) is the time left until the timer expires. You
can change this default so the timer counts up and shows elapsed time
by calling
@findex fl_set_timer_countup()
@anchor{fl_set_timer_countup()}
@example
void fl_set_timer_countup(FL_OBJECT *obj, int yes_no);
@end example
@noindent
with a true value for the argument @code{yes_no}.

 A timer can be temporarily suspended (stopwatch) using the following
routine
@findex fl_suspend_timer()
@anchor{fl_suspend_timer()}
@example
void fl_suspend_timer(FL_OBJECT *obj);
@end example
@noindent
and later be resumed by
@findex fl_resume_timer()
@anchor{fl_resume_timer()}
@example
void fl_resume_timer(FL_OBJECT *obj);
@end example
@noindent
Unlike @code{@ref{fl_set_timer()}} a suspended timer keeps its
internal state (total delay, time left etc.), so when it is resumed,
it starts from where it was suspended.

Finally there is a routine that allows the application program to
change the way the time is presented in @code{FL_VALUE_TIMER}:
@tindex FL_TIMER_FILTER
@findex fl_set_timer_filter()
@anchor{fl_set_timer_filter()}
@example
typedef char *(FL_TIMER_FILTER)(FL_OBJECT *obj, double secs);
FL_TIMER_FILTER fl_set_timer_filter(FL_OBJECT *obj,
                                    FL_TIMER_FILTER filter);
@end example
@noindent
The function @code{filter} receives the timer ID and the time left for
count-down timers and the elapsed time for up-counting timers (in
units of seconds) and should return a string representation of the
time. The default filter returns the time in a
@code{hour:minutes:seconds.fraction} format.


@node Timer Attributes
@subsection Timer Attributes

Never use @code{FL_NO_BOX} as the boxtype for @code{FL_VALUE_TIMER}s.

The first color argument (@code{col1}) to
@code{@ref{fl_set_object_color()}} controls the color of the timer,
the second (@code{col2}) is the blinking color.


@node Timer Remarks
@subsection Remarks

Although having different APIs and the appearance of a different
interaction behaviour, the way timers and timeout callbacks work is
almost identical with one exception: you can deactivate a timer by
deactivating the form it belongs to. While the form is deactivated,
the timers callback will not be called, even if it expires. The
interaction will only resume when the form is activated again.

See @file{timer.c} for the use of timers.


@node XYPlot Object
@section XYPlot Object

A xyplot object gives you an easy way to display a tabulated function
generated on the fly or from an existing data file. An active xyplot
is also available to model and/or change a function.


@ifnottex

@menu
* Adding XYPlot Objects:   Adding XYPlot Objects
* XYPlot Types:            XYPlot Types
* XYPlot Interaction:      XYPlot Interaction
* Other XYPlot Routines:   Other XYPlot Routines
* XYPlot Attributes:       XYPlot Attributes
* Remarks:                 XYPlot Remarks
@end menu

@end ifnottex


@node Adding XYPlot Objects
@subsection Adding XYPlot Objects

To add an xyplot object to a form use the routine
@findex fl_add_xyplot()
@anchor{fl_add_xyplot()}
@example
FL_OBJECT *fl_add_xyplot(int type, FL_Coord x, FL_Coord y,
                         FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
It shows an empty box on the screen with the label per default below it.


@node XYPlot Types
@subsection XYPlot Types

The following types are available:
@table @code
@tindex FL_NORMAL_XYPLOT
@item FL_NORMAL_XYPLOT
A solid line is drawn through the data points.
@tindex FL_SQUARE_XYPLOT
@item FL_SQUARE_XYPLOT
Data drawn as a solid line plus squares at data points.
@tindex FL_CIRCLE_XYPLOT
@item FL_CIRCLE_XYPLOT
Data drawn as a solid line plus circles at data points.
@tindex FL_FILL_XYPLOT
@item FL_FILL_XYPLOT
Data drawn as a solid line with the area under the curve filled.
@tindex FL_POINTS_XYPLOT
@item FL_POINTS_XYPLOT
Only data points are drawn with. per default, stars.
@tindex FL_LINEPOINTS_XYPLOT
@item FL_LINEPOINTS_XYPLOT
Data drawn as a solid line plus, per default, stars at data point.
@tindex FL_DASHED_XYPLOT
@item FL_DASHED_XYPLOT
Data drawn as a dashed line.
@tindex FL_DOTTED_XYPLOT
@item FL_DOTTED_XYPLOT
Data drawn as a dotted line.
@tindex FL_DOTDASHED_XYPLOT
@item FL_DOTDASHED_XYPLOT
Data drawn as a dash-dot-dash line.
@tindex FL_IMPULSE_XYPLOT
@item FL_IMPULSE_XYPLOT
Data drawn by vertical lines.
@tindex FL_ACTIVE_XYPLOT
@item FL_ACTIVE_XYPLOT
Data drawn as a solid line plus squares at data points, accepting
manipulations.
@tindex FL_EMPTY_XYPLOT
@item FL_EMPTY_XYPLOT
Only the axes are drawn.
@end table

All xyplots display the curve auto-scaled to fit the plotting area.
Although there is no limitation on the actual data, a non-monotonic
increasing (or decreasing) x-axis might be plotted incorrectly. For
@code{FL_ACTIVE_PLOT} the x-coordinate of the data must be
monotonically increasing.

XYPlots of type @code{FL_POINTS_XYPLOT} and
@code{FL_LINEPOINTS_XYPLOT} are special in that the application can
change the symbol drawn on the data point.


@node XYPlot Interaction
@subsection XYPlot Interaction

Only @code{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
@example
int fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
where @code{when} can have the folowing values:
@table @code
@item @ref{FL_RETURN_NONE}
Never return or invoke callback.

@item @ref{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.

@item @ref{FL_RETURN_CHANGED}
Return or invoke callback whenever a point has been moved.

@item @ref{FL_RETURN_END}
Return or invoke callback at end (mouse release) regardless if a
point has been moved is changed or not.

@item @ref{FL_RETURN_ALWAYS}
Return or invoke callback when a point has been moved or the mouse
button has been release).
@end table

Please note: a object can also been in inspect mode (see function
@code{@ref{fl_set_xyplot_inspect()}} below). In this case the object
gets returned (or its callback invoked) for all of the above settings
except (@code{@ref{FL_RETURN_NONE}}) when the mouse was released on
top of such one of the points.


To obtain the current value of the point that has changed, use the
routine
@findex fl_get_xyplot()
@anchor{fl_get_xyplot()}
@example
void fl_get_xyplot(FL_OBJECT *obj, float *x, float *y, int *i);
@end example
@noindent
where via @code{i} the data index (starting from 0) is returned while
@code{x}, @code{y} is the actual data point. If no point is changed,
@code{i} is set to -1.

It is possible to not to draw the squares that mark an active plot
using the following routine
@findex fl_set_xyplot_mark_active()
@anchor{fl_set_xyplot_mark_active()}
@example
void fl_set_xyplot_mark_active(FL_OBJECT *obj, int yes_no);
@end example
@noindent
with @code{yes_no} being set to false (0).

To set or replace the data for an xyplot, use
@findex fl_set_xyplot_data()
@anchor{fl_set_xyplot_data()}
@findex fl_set_xyplot_data_double()
@anchor{fl_set_xyplot_data_double()}
@example
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);
@end example
@noindent
(The @code{fl_set_xyplot_data_double()} function allows to pass data
of type @code{double} but which get "demoted" to @code{float} type
when assigned to the xyplot object.) Here @code{x}, @code{y} is the
tabulated function, and @code{n} is the number of data points. If the
xyplot object being set exists already, old data will be cleared. Note
that the tabulated function is copied internally so you can free or do
whatever you want with the @code{x} and @code{y} arrays after the
function returns. @code{title} is a title that is drawn above the
XYPlot and @code{xlabel} and @code{ylabel} are the labels drawn at the
x- and y-axes.

You can also load a tabulated function from a file using the following
routine
@findex fl_set_xyplot_file()
@anchor{fl_set_xyplot_file()}
@example
int fl_set_xyplot_file(FL_OBJECT *obj, const char *filename,
                       const char *title, const char *xlabel,
                       const char *ylabel);
@end example
@noindent
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 (@code{,}) separating the two columns. Lines that
start with any of @code{!}, @code{;} or @code{#} are considered to be
comments and are ignored. The functions returns the number of data
points successfully read or 0 if the file can't be opened/

To get a copy of the current XYPLot data, use
@findex fl_get_xyplot_data()
@anchor{fl_get_xyplot_data()}
@example
void fl_get_xyplot_data(FL_OBJECT *obj, float x[], float y[], int *n);
@end example
@noindent
The caller must supply the space for the data.

All XYPlot objects can be made aware of mouse clicks by using the
following routine
@findex fl_set_xyplot_inspect()
@anchor{fl_set_xyplot_inspect()}
@example
void fl_set_xyplot_inspect(FL_OBJECT *obj, int yes_no);
@end example
@noindent
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 can use
@code{@ref{fl_get_xyplot()}} to find out which point the mouse was
clicked on.

Another, perhaps even more general, way to read-off the values from an
XYPlot is to use a posthandler or an overlay positioner. See demo
@file{xyplotall.c} for the use of posthandler and
@file{positionerXOR.c} for an example of reading-off xyplot values
using an overlap positioner.


@node Other XYPlot Routines
@subsection 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
@findex fl_set_xyplot_xtics()
@anchor{fl_set_xyplot_xtics()}
@findex fl_set_xyplot_ytics()
@anchor{fl_set_xyplot_ytics()}
@example
void fl_set_xyplot_xtics(FL_OBJECT *obj, int major, int minor);
void fl_set_xyplot_ytics(FL_OBJECT *obj, int major, int minor);
@end example
@noindent
where @code{major} and @code{minor} are the number of tic marks to be
placed on the plot and the number of divisions between major tic
marks. In particular, -1 suppresses the tic marks completely while 0
restores the default settings.

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 @code{major} and @code{minor} are only taken as a hint to the
scaling routine. However, in almost all cases the scaling routine will
not generate a major that differs from the requested value by more
than 3.

It is possible to label the major tic marks with alphanumerical
characters instead of numerical values. To this end, use the following
routines
@findex fl_set_xyplot_alphaxtics()
@anchor{fl_set_xyplot_alphaxtics()}
@findex fl_set_xyplot_alphaytics()
@anchor{fl_set_xyplot_alphaytics()}
@example
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);
@end example
@noindent
where @code{major} is a string specifying the labels with the embedded
character @code{|} that specifies major divisions. For example, to
label a plot with Monday, Tuesday etc, @code{major} should be given as
@code{Monday|Tuesday|...}. Parameter @code{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 @code{@ref{fl_set_xyplot_xtics()}} and
@code{@ref{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 be used to specify non-uniform and
arbitary major divisions. To achieve this, you should embed the major
tic location information in the alphanumerical text. The location
information is introduced by the @ symbol and followed by a float
number specifying the coordinates in world coordinates. The entire
location info should follow the label. For example,
@code{"Begin@@1.0|3/4@@0.75|1.9@@1.9"} will produce three major tic
marks at 0.75, 1.0, and 1.9 and labeled "3/4", "begin", and "1.9".

To get a gridded XYPlot, use the following routine
@findex fl_set_xyplot_xgrid()
@anchor{fl_set_xyplot_xgrid()}
ffindex fl_set_xyplot_ygrid()
@example
void fl_set_xyplot_xgrid(FL_OBJECT *obj, int xgrid);
void fl_set_xyplot_ygrid(FL_OBJECT *obj, int ygrid);
@end example
@noindent
where @code{xgrid} and @code{ygrid} can be one of the following
@table @code
@tindex FL_GRID_NONE
@item FL_GRID_NONE
No grid.
@tindex FL_GRID_MAJOR
@item FL_GRID_MAJOR
Grid for the major divisions.
@tindex FL_GRID_MINOR
@item FL_GRID_MINOR
Grid for the major and minor divisions.
@end table

The grid line by default is drawn using a dotted line, which you can
change using the following routine
@findex fl_set_xyplot_grid_linestyle()
@anchor{fl_set_xyplot_grid_linestyle()}
@example
int fl_set_xyplot_grid_linestyle(FL_OBJECT *obj, int style);
@end example
@noindent
where @code{style} is the line style (@code{FL_SOLID}, @code{FL_DASH}
etc. @xref{Part IV Drawing Objects, , 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 be
undesirable in certain situations. To control the plotting area
manually, the following routines can be used
@findex fl_set_xyplot_fixed_xaxis()
@anchor{fl_set_xyplot_fixed_xaxis()}
@findex fl_set_xyplot_fixed_yaxis()
@anchor{fl_set_xyplot_fixed_yaxis()}
@example
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)
@end example
@noindent
where @code{lm} and @code{rm} specify the right and left margin,
respectively, and @code{bm} and @code{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 @code{m}) or two narrow characters (say
@code{ii}) should be used.

To restore automatic margin computation, set all margins to
@code{NULL}.

To change the size of the symbols drawn at data points, use the
following routine
@findex fl_set_xyplot_symbolsize()
@anchor{fl_set_xyplot_symbolsize()}
@example
void fl_set_xyplot_symbolsize(FL_OBJECT *obj, int size);
@end example
@noindent
where @code{size} should be given in pixels. The default is 4.

For @code{FL_POINTS_XYPLOT} and @code{FL_LINEPOINTS_XYPLOT} (main
plot or overlay), the application program can change the symbol using
the following routine
@tindex FL_XYPLOT_SYMBOL
@findex fl_set_xyplot_symbol()
@anchor{fl_set_xyplot_symbol()}
@example
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);
@end example
@noindent
where @code{id} is the overlay id (0 means the main plot, and you can
use -1 to indicate all), and @code{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 @code{id}, the center of the symbol (@code{p->x},
@code{p->y}), the number of data points (@code{n}) and the preferred
symbol size (@code{w}, @code{h}). If the type of the XYPlot
corresponding to @code{id} is not @code{FL_POINTS_XYPLOT} or
@code{FL_LINESPOINTS_XYPLOT}, the function will not be called.

To change or example a @code{FL_LINEPOINTS_XYPLOT} XYPlot to plot
filled small circles instead of the default crosses, the following
code could be used
@example
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);
...
@end example

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

To use absolute bounds as opposed to actual bounds in data, use the
following routines
@findex fl_set_xyplot_xbounds()
@anchor{fl_set_xyplot_xbounds()}
@findex fl_set_xyplot_ybounds()
@anchor{fl_set_xyplot_ybounds()}
@example
void fl_set_xyplot_xbounds(FL_OBJECT *obj, double min, double max);
void fl_set_xyplot_ybounds(FL_OBJECT *obj, double min, double max);
@end example
@noindent
Data that fall outside of the range set this way will be clipped. To
restore autoscaling, call the function with @code{max} and @code{min}
set to exactly the same value. To reverse the axes (e.g., @code{min}
at right and @code{max} at left), set @code{min > max} for that axis.

To get the current bounds, use the following routines
@findex fl_get_xyplot_xbounds()
@anchor{fl_get_xyplot_xbounds()}
@findex fl_get_xyplot_ybounds()
@anchor{fl_get_xyplot_ybounds()}
@example
void fl_get_xyplot_xbounds(FL_OBJECT *obj, float *min, float *max);
void fl_get_xyplot_ybounds(FL_OBJECT *obj, float *min, float *max);
@end example
@noindent
Note that the bounds returned are the bounds used in clipping the
data, which are not necessarily the bounds used in computing the
world/screen mapping due to tic rounding.

To replace the value of a particular point use the routine
@findex fl_replace_xyplot_point()
@anchor{fl_replace_xyplot_point()}
@example
void fl_replace_xyplot_point(FL_OBJECT *obj, int index,
                             double x, double y);
@end example
@noindent
Here @code{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 using the following
call
@findex fl_add_xyplot_overlay()
@anchor{fl_add_xyplot_overlay()}
@example
void fl_add_xyplot_overlay(FL_OBJECT *obj, int id, float *x, float *y,
                           int npoints, FL_COLOR col);
@end example
@noindent
where @code{id} must be between 1 and
@tindex FL_MAX_XYPLOTOVERLAY
@code{FL_MAX_XYPLOTOVERLAY} (currently 32). Again, the data is 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
@findex fl_add_xyplot_overlay_file()
@anchor{fl_add_xyplot_overlay_file()}
@example
int fl_add_xyplot_overlay_file(FL_OBJECT *obj, int ID,
                               const char *file, FL_COLOR col);
@end example
@noindent
The function returns the number of data points successfully read. The
type (@code{FL_NORMAL_XYPLOT} etc.) used in overlay plot is the same
as the object itself. To change an overlay style, use the following
call
@findex fl_set_xyplot_overlay_type()
@anchor{fl_set_xyplot_overlay_type()}
@example
void fl_set_xyplot_overlay_type(FL_OBJECT *obj, int id, int type);
@end example
@noindent
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
@findex fl_get_xyplot_overlay_data()
@anchor{fl_get_xyplot_overlay_data()}
@example
void fl_get_xyplot_overlay_data(FL_OBJECT *obj, int id,
                                float x[], float y[], int *n);
@end example
@noindent
where @code{id} specifies the overlay number between 1 and
@code{FL_MAX_XYPLOTOVERLAY} or the number set via
@code{@ref{fl_set_xyplot_maxoverlays()}} (see below). (Actually, when
@code{id} is zero, this function returns the base data). The caller
must supply the storage space for the data. Upon function return,
@code{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
@findex fl_get_xyplot_data_pointer()
@anchor{fl_get_xyplot_data_pointer()}
@example 
void fl_get_xyplot_data_pointer(FL_OBJECT *obj, int id,
                                float **x, float **y, int *n);
@end example
@noindent
Upon function return, @code{x} and @code{y} are set to point to the
data storage. You're free to modify the data and redraw the XYPlot
(via @code{@ref{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
@findex fl_set_xyplot_maxoverlays()
@anchor{fl_set_xyplot_maxoverlays()}
@example
int fl_set_xyplot_maxoverlays(FL_OBJECT *obj, int maxoverlays);
@end example
@noindent
The function returns the previous maximum number of overlays.

To obtain the number of data points, use the following routine
@findex fl_get_xyplot_numdata()
@anchor{fl_get_xyplot_numdata()}
@example
int fl_get_xyplot_numdata(FL_OBJECT *obj, int id);
@end example
@noindent
where @code{id} is the overlay ID with 0 being the base data set.

To insert a point into an xyplot, use the following routine
@findex fl_insert_xyplot_data()
@anchor{fl_insert_xyplot_data()}
@example
void fl_insert_xyplot_data(FL_OBJECT *obj, int id, int n,
                           double x, double y);
@end example
@noindent
where @code{id} is the overlay ID; @code{n} is the index of the point
after which the data new point specified by @code{x} and @code{y} is
to be inserted. Set @code{n} to -1 to insert the point in front. To
append to the data, set @code{n} to be equal or larger than the return
value of @code{fl_get_xyplot_numdata(obj, id)}.

To delete an overlay, use the following routine
@findex fl_delete_xyplot_overlay()
@anchor{fl_delete_xyplot_overlay()}
@example
void fl_delete_xyplot_overlay(FL_OBJECT *obj, int id);
@end example

It is possible to place inset texts on an XYPlot using the following
routine (up to @code{FL_MAX_XYPLOTOVERLAY} or the value set via
@code{@ref{fl_set_xyplot_maxoverlays()}} of such insets can be
accommodated):
@findex fl_add_xyplot_text()
@anchor{fl_add_xyplot_text()}
@example
void fl_add_xyplot_text(FL_OBJECT *obj, double x, double y,
                        const char *text, int align, FL_COLOR col);
@end example
@noindent
where @code{x} and @code{y} are the coordinates where text is to be
placed and align specifies the placement options relative to the
specified point (See @code{@ref{fl_set_object_lalign()}} for valid
options). If you for example specify @code{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 @code{@@} a
symbol is drawn.

To remove an inset text, use the following routine
@findex fl_delete_xyplot_text()
@anchor{fl_delete_xyplot_text()}
@example
void fl_delete_xyplot_text(FL_OBJECT *obj, const char *text);
@end example

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
@findex fl_set_xyplot_key()
@anchor{fl_set_xyplot_key()}
@example
void fl_set_xyplot_key(FL_OBJECT *obj, int id, const char *keys);
@end example
@noindent
where @code{id} again is the overlay ID. To remove a key, set the key
to @code{NULL}. All the keys will be drawn together inside a box. The
position of the keys can be set via
@findex fl_set_xyplot_key_position()
@anchor{fl_set_xyplot_key_position()}
@example
void fl_set_xyplot_key_position(FL_OBJECT *obj, float x, float y,
                                int align)
@end example
@noindent
where @code{x} and @code{y} should be given in world coordinate
system. @code{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
@findex fl_set_xyplot_keys()
@anchor{fl_set_xyplot_keys()}
@example
void fl_set_xyplot_keys(FL_OBJECT *obj, char *keys[],
                         float x, float y, int align);
@end example
@noindent
where @code{keys} specifies the keys for each plot. The last element
of the array must be @code{NULL} to indicate the end. The array index
is the plot id, i.e., @code{key[0]} is the key for the base plot,
@code{key[1]} the key for the the first overlay etc.

To change the font the key text uses, the following routine is available
@findex fl_set_xyplot_key_font()
@anchor{fl_set_xyplot_key_font()}
@example
void fl_set_xyplot_key_font(FL_OBJECT *obj, int style, int size);
@end example

Data may be interpolated using an nth order Lagrangian polynomial:
@findex fl_set_xyplot_interpolate()
@anchor{fl_set_xyplot_interpolate()}
@example
void fl_set_xyplot_interpolate(FL_OBJECT *obj, int id, int degree,
                               double grid);
@end example
@noindent
where @code{id} is the overlay ID (use 0 for the base data set);
@code{degree} is the order of the polynomial to use and @code{grid} is
the working grid onto which the data are to be interpolated. To
restore the default linear interpolation, use @code{degree} set to 0
or 1.

To change the line thickness of an xyplot (base data or overlay), the
follow routine is available:
@findex fl_set_xyplot_linewidth()
@anchor{fl_set_xyplot_linewidth()}
@example
void fl_set_xyplot_linewidth(FL_OBJECT *obj, int id, int width);
@end example
Again, use a @code{id} of value 0 to indicate the base data. Setting
@code{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
@findex fl_set_xyplot_xscale()
@anchor{fl_set_xyplot_xscale()}
@findex fl_set_xyplot_yscale()
@anchor{fl_set_xyplot_yscale()}
@example
void fl_set_xyplot_xscale(FL_OBJECT *obj, int scale, double base);
void fl_set_xyplot_yscale(FL_OBJECT *obj, int scale, double base);
@end example
@noindent
where the valid scaling options for scale are
@tindex FL_LINEAR
@tindex FL_LOG
@code{FL_LINEAR} and @code{FL_LOG}, and @code{base} is used only for
@code{FL_LOG} and in that case it is the base of the logarithm to be
used.

Use the following routine to clear an xyplot
@findex fl_clear_xyplot()
@anchor{fl_clear_xyplot()}
@example
void fl_clear_xyplot(FL_OBJECT *obj);
@end example
@noindent
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
@code{@ref{fl_free_object()}} is needed.

The mapping between the screen coordinates and data can be obtained
using the following routines
@findex fl_get_xyplot_xmapping()
@anchor{fl_get_xyplot_xmapping()}
@findex fl_get_xyplot_ymapping()
@anchor{fl_get_xyplot_ymapping()}
@example
void fl_get_xyplot_xmapping(FL_OBJECT *obj, float *a, float *b);
void fl_get_xyplot_xmapping(FL_OBJECT *obj, float *a, float *b);
@end example
@noindent
where @code{a} and @code{b} are the mapping constants and are used as
follows:
@example
screenCoord = a * data + b       (linear scale)
screenCoord = a * log(data) / log(p) + b (log scale)
@end example
@noindent
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
@findex fl_xyplot_s2w()
@anchor{fl_xyplot_s2w()}
@example
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);
@end example
@noindent
where @code{sx} and @code{sy} are the screen coordinates and @code{wx}
and @code{wy} are the world coordinates.


@node XYPlot Attributes
@subsection XYPlot Attributes

Don't use @code{FL_NO_BOX} as the boxtype of an XYPlot object that is
to be changed dynamically. To change the font size and style for the
tic labels, inset text etc., use @code{@ref{fl_set_object_lsize()}}
and @code{@ref{fl_set_object_lstyle()}}.

The first color argument (@code{col1}) to
@code{@ref{fl_set_object_color()}} controls the color of the box and
the second (@code{col2}) the actual XYPlot color.


@node XYPlot Remarks
@subsection Remarks


The interpolation routine is public and can be used in the application
program
@findex fl_interpolate()
@anchor{fl_interpolate()}
@example
int fl_interpolate(const float *inx, const float *iny, int num_in,
                   float *outx, float *outy, double grid, int ndeg);
@end example
@noindent
If successful, the function returns the number of points in the
interpolated function (@code{(inx[num_in - 1] - inx[0]) / grid +
1.01}), otherwise it returns -1. Upon return, @code{outx} and
@code{outy} are set to the interpolated values. The caller must
allocate the storage for @code{outx} and @code{outy}.

See @file{xyplotall.c} and @code{xyplotactive.c} for examples of the
use of XYPlot objects. There is also an example program called
@file{xyplotover.c}, which shows the use of overlays. In addition,
@code{xyplotall.c} shows a way of getting all mouse clicks without
necessarily using an active XYPlot.

It is possible to generate a PostScript output of an XYPlot. See the
function @code{@ref{fl_object_ps_dump()}} documented in Part V.




@node Canvas Object
@section Canvas Object

A canvas is a managed plain X (sub)window. It it different from the
free object in that a canvas is guaranteed to be associated with a
window that is not shared with any other object, thus an application
program has more freedom in utilizing a canvas, such as using its own
colormap or rendering double-buffered OpenGL in it etc. A canvas is
also different from a raw application window because a canvas is
decorated differently and its geometry is managed, e.g., you can use
@code{@ref{fl_set_object_resize()}} to control its position and size
after its parent form is resized.

@ifnottex

@menu
* Adding Canvas Objects:     Adding Canvas Objects
* Canvas Types:              Canvas Types
* Canvas Interaction:        Canvas Interaction
* Other Canvas Routines:     Other Canvas Routines
* Canvas Attributes:         Canvas Attributes
* OpenGL Canvas:             OpenGL Canvas
@end menu

@end ifnottex


@node Adding Canvas Objects
@subsection Adding Canvas Objects

Adding an object To add a canvas to a form you use the routine
@findex fl_add_canvas()
@anchor{fl_add_canvas()}
@example
FL_OBJECT *fl_add_canvas(int type, FL_Coord x, FL_Coord y,
                         FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
The meaning of the parameters is as usual. The label is not drawn but
used as the window name for possible resource and playback purposes.
If label is empty, the window name will be generated on the fly as
@code{flcanvasn}, where @code{n = 0, 1,...}.

@node Canvas Types
@subsection Canvas Types

The only types of canvases currently available is
@tindex FL_NORMAL_CANVAS
@code{FL_NORMAL_CANVAS}.


@node Canvas Interaction
@subsection Canvas Interaction

The canvas class is designed to maximize the programmer's ability to
deal with situations where standard form classes may not be flexible
enough. With canvases, the programmer has complete control over
everything that can happen to a window. It thus doesn't work like
other objects that get returned by @code{@ref{fl_do_forms()}} etc.@:
or have their callbacks invoked.

Instead the user can request that for specific @code{X} events (not
XForms object events like @code{FL_PRESS}, @code{FL_KEYPRESS} etc.!)
callbacks are invoked that receive all information about the
@code{XEvent} that led to their invocation. This obviously requires
some understanding of how the X Window system works.

The interaction with a canvas is typically set up as follows. First,
you register the @code{X} events you're interested in and their
handlers using the following routine
@tindex FL_HANDLE_CANVAS
@findex fl_add_canvas_handler()
@anchor{fl_add_canvas_handler()}
@example
typedef int (*FL_HANDLE_CANVAS)(FL_OBJECT *obj, Window win,
                                int win_width, int win_height,
                                XEvent *xev, void *user_data);
void fl_add_canvas_handler(FL_OBJECT *obj, int event,
                           FL_HANDLE_CANVAS handler, void *user_data);
@end example
@noindent
where @code{event} is the @code{XEvent} type, e.g. @code{Expose} etc.
The @code{@ref{fl_add_canvas_handler()}} function first registers a
procedure with the event dispatching system of the Forms Library, then
it figures out the event masks corresponding to the event @code{event}
and invokes @code{@ref{fl_addto_selected_xevent()}} to solicit the
event from the server. Other book keeping (e.g.@: drawing the box that
encloses the canvas, etc.) is done by the object handler.

When a canvas handler is installed the library tries to set the
correct mask for the the @code{Xevent} (which then tells the X Window
system which events to pass on to the Forms Library). But since
translation from an @code{Xevent} to a @code{Xevent} mask is not
unique, the default translation of the @code{Xevent} to a mask may or
may not match exactly the intention of the application. Two events,
namely @code{MotionNotify} and @code{ButtonPress}, are likely
candidates that need further clarification from the application. There
are two functions to add or delete from the mask,
@code{@ref{fl_addto_selected_xevent()}} and
@code{@ref{fl_remove_selected_xevent()}}.

By default, when a mouse motion handler (i.e.@: for the
@code{MotionNotify} events) is registered, it is assumed that, while
the application wants to be informed about mouse movements, it's not
interested in a continous motion monitoring (tracking), thus per
default @code{MotionNotify} events are requested with
@code{PointerMotionHintMask} being set in the mask to reduce the
number of events generated. If this is not the case and in fact the
application wants to use the mouse motion as some type of graphics
control, the default behavior would appear "jerky" as not every mouse
motion is reported. To change the default behavior so that every mouse
motion is reported, you need to call
@code{@ref{fl_remove_selected_xevent()}} with mask set to
@code{PointerMotionHintMask}. Furthermore, the mouse motion is
reported regardless if a mouse button is pressed or not. If the
application is interested in mouse motion only when a mouse button is
pressed @code{@ref{fl_remove_selected_xevent()}} should be called with
a mask of @code{PointerMotionMask|PointerMotionHintMask}.

With @code{ButtonPress} events you need to call
@code{@ref{fl_addto_selected_xevent()}} with a mask of
@code{OwnerGrabButtonMask} if you are to add or remove other canvas
handlers in the button press handler.

To remove a registered handler, use
@findex fl_remove_canvas_handler()
@anchor{fl_remove_canvas_handler()}
@example
void fl_remove_canvas_handler(FL_OBJECT *obj, int event,
                              FL_CANVAS_HANDLER handler);
@end example
@noindent
After this function call the canvas ceases to receive the events for
@code{event}. The corresponding default bits in the @code{XEvent} mask
as were set by @code{@ref{fl_add_canvas_handler()}} are cleared.
If you added extra ones with @code{@ref{fl_addto_selected_xevent()}}
you should reset them using @code{@ref{fl_remove_selected_xevent()}}.

To obtain the window ID of a canvas, use
@findex fl_get_canvas_id()
@anchor{fl_get_canvas_id()}
@example
Window fl_get_canvas_id(FL_OBJECT *obj);
@end example
@noindent
or use the generic function (macro) (recommended)
@findex FL_ObjWin()
@anchor{FL_ObjWin()}
@example
Window FL_ObjWin(FL_OBJECT *obj);
@end example
@noindent

Of course, the window ID only has a meaning after the form/canvas is
shown. When the canvas or the form the canvas is on is hidden (via
@code{@ref{fl_hide_object()}} or @code{@ref{fl_hide_form()}}), the
canvas window may be destroyed. If the canvas is shown again, a new
window ID for the canvas may be created. Thus recording the canvas
window ID in a static variable is not the right thing to do. It is
much safer (and it doesn't add any run-time overhead) to obtain the
canvas window ID via @code{@ref{FL_ObjWin()}} whenever it's needed. If
your application must show and hide the canvas/form repeatedly, you
might consider to "unmap" the window, a way of removing the window
from the screen without actually destroying it and later re-mapping
the window to show it. The Xlib API functions for doing this are
@code{XUnmapWindow()} and @code{XMapWindow()}. Both require two
arguments. the display, which you can determine by calling
@code{@ref{fl_get_display()}} and the window ID, which can be obtained
by using @code{form->window} if you want to (un)map a form or
@code{FL_ObjWin(obj)} for a canvas.


@node Other Canvas Routines
@subsection Other Canvas Routines

Upon canvas creation, all its window related attributes, e.g.@:
visual, depth and colormap etc., are inherited from its parent (i.e.@:
the window of the form the canvas belongs to). To modify any
attributes of the canvas, use the following routine
@findex fl_set_canvas_attributes()
@anchor{fl_set_canvas_attributes()}
@example
void fl_set_canvas_attributes(FL_OBJECT *obj, unsigned mask,
                              XSetWindowAttributes *xswa);
@end example
@noindent
See @code{XSetWindowAttributes()} for the definition of the structure
members. Note that this routine should not be used to manipulate
events.

Other functions exists that can be used to modify the color/visual
property of a canvas:
@findex fl_set_canvas_colormap()
@anchor{fl_set_canvas_colormap()}
@findex fl_get_canvas_colormap()
@anchor{fl_get_canvas_colormap()}
@findex fl_set_canvas_visual()
@anchor{fl_set_canvas_visual()}
@findex fl_set_canvas_depth()
@anchor{fl_set_canvas_depth()}
@findex fl_get_canvas_depth()
@anchor{fl_get_canvas_depth()}
@example
void fl_set_canvas_colormap(FL_OBJECT *obj, Colormap map);
Colormap fl_get_canvas_colormap(FL_OBJECT *obj);
void fl_set_canvas_visual(FL_OBJECT *obj, Visual *vi);
void fl_set_canvas_depth(FL_OBJECT *obj, int depth);
int fl_get_canvas_depth(FL_OBJECT *obj);
@end example
@noindent
Note that changing visual or depth does not generally make sense once
the canvas window is created (which happens when the parent form is
shown). Also, typically if you change the canvas visual, you probably
should also change the canvas depth to match the visual.

Caution should also applied when using
@code{@ref{fl_set_canvas_colormap()}}: when the canvas window goes
away, e.g.@: as a result of a call of @code{@ref{fl_hide_form()}}, the
colormap associated with the canvas is freed (destroyed). This likely
will cause problems if a single colormap is used for multiple canvases
as each canvas will attempt to free the same colormap, resulting in
an X error. If your application works this way, i.e.@: the same
colormap is used on multiple canvases (via
@code{@ref{fl_set_canvas_colormap()}}), you should use the following
routine to prevent the canvas from freeing the colormap:
@findex fl_share_canvas_colormap()
@anchor{fl_share_canvas_colormap()}
@example
void fl_share_canvas_colormap(FL_OBJECT *obj, Colormap colormap);
@end example
@noindent
This function works the same way as
@code{@ref{fl_set_canvas_colormap()}} except that it also sets a
internal flag so the colormap isn't freed when the canvas goes away.

By default, canvases are decorated with an @code{FL_DOWN_FRAME}. To
change the decoration, change the the boxtype of the canvas and the
boxtype will be translated into a frame that best approximates the
appearance of the request boxtype (e.g.@: a @code{FL_DOWN_BOX} is
translated into a @code{FL_DOWN_FRAME} etc). Note that not all frame
types are appropriate for decorations.

The following routine is provided to facilitate the creation of a
colormap appropriate for a given visual to be used with a canvas:
@findex fl_create_colormap()
@anchor{fl_create_colormap()}
@example
Colormap fl_create_colormap(XVisualInfo *xvinfo, int n_colors);
@end example
@noindent
where @code{n_colors} indicates how many colors in the newly created
colormap should be filled with XForms' default colors (to avoid
flashing effects). Note however, that the colormap entry 0 is
allocated with either black or white even if you specify 0 for
@code{n_colors}. To prevent this from happening (so you get a
completely empty colormap), set @code{n_colors} to -1. @xref{Part
IV Drawing Objects, , Drawing Objects}, on how to obtain the
@code{XVisualInfo} for the window. Depending on the window manager, a
colormap other than the default may not get installed correctly. If
you're working with such a window manager, you may have to install the
colormap yourself when the mouse pointer enters the canvas using
@code{XInstallColormap()}.

By default, objects with shortcuts appearing on the same form as the
canvas will "steal" keyboard inputs if they match the shortcuts. To
disable this feature, use the following routine with a false (0)
value for @code{yes_no}:
@findex fl_canvas_yield_to_shortcut()
@anchor{fl_canvas_yield_to_shortcut()}
@example
void fl_canvas_yield_to_shortcut(FL_OBJECT *obj, int yes_no);
@end example


@node Canvas Attributes
@subsection Canvas Attributes

Some of the attributes, such as boxtype, do not apply to the canvas
class.

The first color argument (@code{col1}) to
@code{@ref{fl_set_object_color()}} can be used to set the background
color of the canvas (by default, a canvas has no background color).
The second argument (@code{col2}) controls the decoration color (if
applicable).


@node OpenGL Canvas
@subsection OpenGL Canvas

Deriving specialized canvases from the general canvas object is
possible. See the next subsection for general approaches how this is
done. The following routines work for OpenGL (under X) as well as
Mesa, a free OpenGL clone.

To add an OpenGL canvas to a form, use the following routine
@findex fl_add_glcanvas()
@anchor{fl_add_glcanvas()}
@example
FL_OBJECT *fl_add_glcanvas(int type, FL_Coord x, FL_Coord y,
                           FL_Coord w, FL_Coord h, const char *label);
@end example
@noindent
where @code{type} is the same as for a normal canvas. A "glcanvas"
created this way will have the following attributes by default
@example
GLX_RGBA,
GLX_DEPTH_SIZE: 1,
GLX_RED_SIZE: 1, GLX_GREEN_SIZE: 1, GLX_BLUE_SIZE: 1,
GLX_DOUBLEBUFFER
@end example

The application program can modify these defaults using the following
routine (before the creation of glcanvases)
@findex fl_set_glcanvas_defaults()
@anchor{fl_set_glcanvas_defaults()}
@example
void fl_set_glcanvas_defaults(const int *attributes);
@end example
@noindent
See @code{glXChooseVisual()} for a list of valid attributes.

To get the current defaults use
@findex fl_get_glcanvas_defaults()
@anchor{fl_get_glcanvas_defaults()}
@example
void fl_get_glcanvas_defaults(int *attributes);
@end example

It is also possible to change the attributes on a canvas by canvas
basis by utilizing the following routine:
@findex fl_set_glcanvas_attributes()
@anchor{fl_set_glcanvas_attributes()}
@example
void fl_set_glcanvas_attributes(FL_OBJECT *obj, const int *attributes);
@end example
@noindent
Note that this routine can be used to change a glcanvas attributes on
the fly even if the canvas is already visible and active.

To obtain the attributes of a particular canvas, use the following routine
@findex fl_get_glcanvas_attributes()
@anchor{fl_get_glcanvas_attributes()}
@example
void fl_get_glcanvas_attributes(FL_OBJECT *obj, int attributes[]);
@end example
@noindent
The caller must supply the space for the attribute values.

To obtain the the glx context (for whatever purposes), use
@findex fl_get_glcanvas_context()
@anchor{fl_get_glcanvas_context()}
@example
GLXContext fl_get_glcanvas_context(FL_OBJECT *obj);
@end example

Note that by default the rendering context created by a glcanvas uses
direct rendering (i.e., by-passing the Xserver). To change this
default, i.e.@: to always render through the Xserver, use the following
routine:
@findex fl_set_glcanvas_direct()
@anchor{fl_set_glcanvas_direct()}
@example
void fl_set_glcanvas_direct(FL_OBJECT *obj, int yes_no);
@end example
@noindent
with the argument @code{yes_no} set to false (0).

Remember that OpenGL drawing routines always draw into the window the
current context is bound to. For application with a single canvas,
this is not a problem. In case of multiple canvases, the canvas driver
takes care of setting the proper context before invoking the expose
handler. In some cases, the application may want to draw into canvases
actively. In this case, explicit drawing context switching may be
required. To this end, use the following routine
@findex fl_activate_glcanvas()
@anchor{fl_activate_glcanvas()}
@example
void fl_activate_glcanvas(FL_OBJECT *obj);
@end example
@noindent
before drawing into glcanvas object.

Finally there is a routine that can be used to obtain the @code{XVisual}
information that is used to create the context
@findex fl_get_glcanvas_xvisualinfo()
@anchor{fl_get_glcanvas_xvisualinfo()}
@example
XVisualInfo *fl_get_glcanvas_xvisualinfo(FL_OBJECT *obj);
@end example
@noindent
See demo program @code{gl.c} for an example use of a glcanvas.