Description of Cartesian library v.0.9
.2



1. Canvas class
-------------------

Ca_Canvas:public Fl_Box


This is the area where the objects are plotted. It can have unlimited number of axes to which object co-ordinates are related.
It contains of a background of a "Fl_Box" type, grids generated by the axes and the objects. It features of incremental plotting if possible
which in some cases can peed-up the drawing espetially for wery complex graphics with many objects. Use Fl_Double_Window(Fl_Owerlay_Window)
to take full adwantage of the speed.

public methods:
    
    Ca_Canvas* current()
    void current(Ca_Canvas * _current)
    - gets or sets the canavas as current (to which all new constructed axes are related and objects will be placed in the canvas.
    Construction of a canavas makes it active.


    void current_x(Ca_Axis_ * axis)
    void current_y(Ca_Axis_ * axis)
    Ca_Axis_* current_x()
    Ca_Axis_* current_y()
    - sets the co-ordination system for new constructed objects. Note, that this does not sets the canvas active itself, so use 
     canvas->current() to do that. The first axes (of X or Y type) are active after their construction.

    
    void clear()
    - destroys all objects and redraws the canvas.
    
    int border()
    void border(int border)
    - gets and sets the blank border around the graphics. The min_pos() and max_pos() axes values are set with respect to that value
	(plus natural border of a box type). 
    

    Ca_Canvas(int x, int y, int w, int h, const char *label=0)
    - a Fl_Widget_ (and fluid) compatible constructor.

    ~Ca_Canvas()
    - Destroys also all objects and axes which belongs to the canvas!

2. Axis classes
---------------

Ca_Axis_:Fl_Box

    A virtual base class for Ca_X_Axis, CA_Y_Axis:

    Ca_Axis_
     |
     +-- Ca_X_Axis
     |
     |
     +-- Ca_Y_Axis






Public methods:
---------------
	void scale(int s);
	- sets the character of axes (can be CA_LOG, CA_LIN and or-ed with CA_REV) and it can be called "on the fly"

    virtual void current()=0;
    - Sets the current axis. All new objects will be placed relative to that co-ordinate.
    
    virtual double position(double)=0;
    - The method gives the real x or y position corresponding to the given value. It is should be used inside draw() method of Ca_Object_ for its drawing.

    virtual double value(int)=0;
    - Gives the value for given position, it can be used i.e. for cursor implementation (i.e.in overlay of Fl_Overlay_Window).

    Ca_Canvas * canvas()
    - Gives information about the canvas to which the axis belongs to.
       
    int border()
    void border(int border)
    - a gap between the tics and the widget edge - only aesthetical purpose
    
    double min() 
    double max()
    void minimum(double x);
    void maximum(double x);
    - sets or gets the range of the axis.
    
    void rescale(int when, double x);
     The method rescales the axis if x exceeds min() or max(). The condition when (values CA_WHE_MIN, CA_WHEN_MAX) -
     can be combined - rescale(CA_WHEN_MIN|CA_WHEN_MAX, x);

    void rescale_move(int when, double  x)
    - That one allows to implement something like "moving" or "scrolling" window without changing axis scale so max()-min()
	(for logarithmic axes min()/max()) remains constant.
    
    void tick_interval(double interval)
    double tick_interval()
    - tick_intedval is one of the most important functions to control tick appearance.
     it can have  a value:
     in range <1,10):sets the interval between the tics except the order, so i.e. if you define
         tick_interval(2) you can get tics like  (0.92, 0.94, ......1.16 ) if say min() is 0.93 and max() 1.15. The tics order
         is "calculated" to keep tics density in reasonable values - the density can be further controled by tick_separation(..) method.
     negative:  (only for linear axes) the  interval is set include the order, so -0.002 will give you tics of values (0.930, 0.932, 0.934 ....1.170)
     0(default):  The engine tries to find the best separation from values 1,2,5.  


    void tick_separation(int separation)
    int tick_separation()
    - The value (in pixels) is a distance between minor tics which the drawing method tries to fit (calculating tick order or even internally changing
     "tick_interval" when 0

    void tick_length(int length)
    int tick_length()
    - a length of the tics. If 0(default), the size of tics label font is used.

    void major_step(int step)
    int major_step()

    - The number of minor tics between two successive major ones. For default tick_interval(0) they are:
     5 if "tick interval" was "calculated" as 1
     5 if "tick interval was calculated 2
     2 is fick interval was calculated 5
    
    void label_step(int step)
    int label_step()
    - number of minor tics between labeled ones (linear: 10,5,4, logarithmic: 10, 5, 2 or every order
     or every three orders, depends on the density)

    void label_format(const char *format)
    const char* label_format()
    - Format of the tics labels, if 0 (default) than format is something like "%.nf" where n "corresponds" to the ticks order.

    void label_font(Fl_Font face)
    Fl_Font label_font()
    - font for tics labels

    void label_size(int size)
    int label_size()
    - and their size

    void axis_color(Fl_Color _axis_color)
    - Color for tics and labels.

    void minor_grid_color(Fl_Color color)
    void major_grid_color(Fl_Color color)
    void label_grid_color(Fl_Color color)
    Fl_Color minor_grid_color()
    Fl_Color major_grid_color()
    Fl_Color label_grid_color()
    char *major_grid_dashes()
    void minor_grid_style(int style, int width=0, char * dashes=0)
    void major_grid_style(int style, int width=0, char * dashes=0)
    void label_grid_style(int style, int width=0, char * dashes=0)
	- These functions define the appereance of the grid in the canvas.

	
	void minor_grid_style(int *style, int *width=0, char ** dashes=0)
    void major_grid_style(int *style, int *width=0, char ** dashes=0)
    void label_grid_style(int *style, int *width=0, char ** dashes=0)
	- For the querry of the grid line style you can pass 0 if you do not need to know particular variable value.


    void grid_visible(int visible)
	int grid_visible()
    - Define which grid lines have to be plottedand. They can have a form of full lines or internal tics "a la Gnuplot"  -left,right (tbottom, top) or both.
	use (and "or") values:
	CA_MINOR_GRID,
	CA_LEFT_MINOR_TICK,
	CA_BOTTOM_MINOR_TICK,
	CA_RIGHT_MINOR_TICK,
	CA_TOP_MINOR_TICK,
	CA_MINOR_TICK(==CA_LEFT_MINOR_TICK|CA_RIGHT_MINOR_TICK),
	CA_MAJOR_GRID,
	CA_LEFT_MAJOR_TICK,
	CA_BOTTOM_MAJOR_TICK,
	CA_RIGHT_MAJOR_TICK,
	CA_TOP_MAJOR_TICK,
	CA_MAJOR_TICK,(==CA_LEFT_MAJOR_TICK|CA_RIGHT_MAJOR_TICK),
	CA_LABEL_GRID,
	CA_LEFT_LABEL_TICK,
	CA_BOTTOM_LABEL_TICK,
	CA_RIGHT_LABEL_TICK,
	CA_TOP_LABEL_TICK,
	CA_LABEL_TICK,(==CA_LEFT_LABEL_TICK|CA_RIGHT_LABEL_TICK).

    As the labeled ticks are also major ones, setting i.e. grid_visible(CA_MAJOR_GRID) will plot no minor-ticks grid,
    but major and labelled of the same color. 
	When or-ed with CA_ALWAYS_VISIBLE the grid is plotted even if the axis is not itselfvisible.
	Normaly the grid is plotted ad the background, if you want to plot them in the front of the objects you can "or"
	the parameter with CA_FRONT.
    
    
    void axis_align(unsigned char align)
    unsigned char axis_align()
    - Use CA_LEFT (default), CA_RIGHT, CA_TOP, CA_BOTTOM (default) to choose axis appearance. When "or"-ed with CA_LINE (default), a base axis
     line is drawn as well 



	Ca_*_Axis(int x, int y, int w, int h, const char * label=0);
    - The axes have standard constructor and can be used in fluid.

    ~Ca_*_Axis()
	 If you destroy the axis yourself, do not forget unregister it from it's parent group.
	 It destroys also all objects related to the axis.
     The destructors of axes is also called when canvas is destroyed.




3. Class Ca_Object_
-------------------
This is a base class of all drawings.
You should subclass it and define your draw() method using x_axis->position(...) and y_axis->position(...).
Although only points(and lines) are included in the library, the object can be any 2D graphics.
If the canvas is not damaged and you add some objects the incremental  drawing  is performed for maximum speed.

Members:    
    
    protected:

    Ca_Canvas *canvas_;
    - the canvas to which it belongs to (the active canvas when the object was created)

    public:
	
	Ca_Axis_ *x_axis_;
    Ca_Axis_ *y_axis_;
    - co-ordination axes for the object (again with respect to active axes when crearted, you can chage it by 
     axis->give_objects() method

    virtual void draw()
    - here is your drawing code of your objects
     
    public:
    Ca_Object_(Ca_Canvas * canvas=0);
    - if Ca_Canvas is 0, the object is assigned to current canvas

    virtual ~Ca_Object_();
    - override it when your objects are complex and you have to made sophisticated destruction.



The library contains some real objects:

Class Ca_Point:Ca_Object_
-------------------------
Simple points with different shapes. For the simplicity of the member access all are public.
If you make to them "on the fly" redraw the canvas after.

    double x;
    double y;
    - co-ordination values

    Fl_Color color;
    Fl_Color border_color;
	int border_width;
    unsigned char style;
    int size;
    - The point color, shape and size. The shape can have one of the values: CA_SIMPLE, CA_ROUND,CA_SQUARE, CA_UP_TRIANGLE, CA_DOWN_TRIANGLE, CA_DIAMOND, CA_NO_POINT.
     When or-ed wirh CA_BORDER, the bordered line of border_color is also plotted.
     For drawing of CA_SIMPLE a fl_point(..)is used.

    
	Ca_Point(double _x, double _y, Fl_Color color=FL_BLACK, int style=CA_SIMPLE, int size=DEFAULT_POINT_SIZE, Fl_Color border_color=FL_BLACK, int border_width=0);
    - The constructor sets all parameters.


class Ca_LinePoint:Ca_Point
---------------------------
It can be used for plotting of "Ca_Point" points connected with lines. (with the same color)

public members:
    Ca_LinePoint *previous;
	int line_width;

    Ca_LinePoint(Ca_LinePoint *_previous, double _x, double _y, int line_width, Fl_Color color=FL_BLACK,  int style=CA_SIMPLE, int size=DEFAULT_POINT_SIZE, Fl_Color border_color=FL_BLACK, int border_width=0);
    Ca_LinePoint(Ca_LinePoint *_previous, double _x, double _y);


class Ca_PolyLine:Ca_LinePoint
------------------------------
This features the styles for connecting lines.

	int line_style;
	Ca_PolyLine * next;
	Ca_PolyLine(Ca_PolyLine *_previous, double _x, double _y,int line_style, int line_width=0, Fl_Color color=FL_BLACK, int style=CA_SIMPLE, int size=DEFAULT_POINT_SIZE,  Fl_Color border_color=FL_BLACK, int border_width=0);
	Ca_PolyLine(Ca_PolyLine *_previous, double _x, double _y);


Class Ca_Line:Ca_Point
----------------------
Although the appereance is similar to Ca_PolyLine, there are a few differences:
    
	1. It is a single object
	2. The coordination values are not stored in the object - only ponters to the x (data) and y (data_2) data arrays.
	If dada_2==0, both sets should be stored in *data in order x1,y1,x2,y2.....xn,yn.

Public members:
	int line_style;
	int line_width;
	int n;
	double * data;
	double * data_2;

	Ca_Line(int _n, double *_data, double *_data_2, int _line_style, int _line_width=0, Fl_Color color=FL_BLACK, int style=CA_SIMPLE, int size=DEFAULT_POINT_SIZE, Fl_Color border_color=FL_BLACK, int border_width=0);
	Ca_Line(int _n, double *_data, int _line_style, int _line_width=0, Fl_Color _color=FL_BLACK, int style=CA_SIMPLE, int size=DEFAULT_POINT_SIZE, Fl_Color border_color=FL_BLACK, int border_width=0);

Class Ca_Text:Ca_Object_
-------------------------
Plots formated text inside coordinates x1, x2, y1, y2.

public members:
	double x1,x2,y1,y2;
	char * label;
	uchar align;
	Fl_Color label_color;
	Fl_Font label_font;
	int label_size;

	Ca_Text(double _x1, double _x2, double _y1, double _y2, char *_label, uchar _align=FL_ALIGN_CENTER, Fl_Font _label_font=FL_HELVETICA, int _label_size=CA_DEFAULT_LABEL_SIZE, Fl_Color _label_color=FL_BLACK);
	Ca_Text(double x, double y, char *_label=0, uchar _align=FL_ALIGN_CENTER, Fl_Font _label_font=FL_HELVETICA, int _label_size=CA_DEFAULT_LABEL_SIZE, Fl_Color _label_color=FL_BLACK);


Class Ca_Bar:public Ca_Text
---------------------------
A bar with optional border (if border_width >=0) and label which can be formatted and aligned similar to the widget labels.

public members:
	Fl_Color color;
	Fl_Color border_color;
	int border_width;
	Ca_Bar(double _x1, double _x2, double _y1, double _y2, Fl_Color _color=FL_RED,  Fl_Color _border_color=FL_BLACK, int _border_width=0,  char *_label=0, uchar _align=FL_ALIGN_CENTER, Fl_Font _label_font=FL_HELVETICA, int _label_size=CA_DEFAULT_LABEL_SIZE, Fl_Color _label_color=FL_BLACK);




4. Example program
------------------

It generates the points in 0.1 s intervals you can see axis rescalling on the fly.
The mode od "power" axis  can be changed to demonstrate possible axis types.


5. FAQ
------

  Q1: What is the difference between Ca_LinePoint Ca_PolyLine (and Ca_Line?)
  A: Ca_LinePoint Ca_PolyLine are multi-oblect creatures and can be incrementaly construcred
  (i.e. during data acquisition). Ca_LinePoint is faster because it can perform incremental drawing
  (esperially important if you have many thousands points and you are appending new ones to the structure).
  Ca_PolyLine have additional features (like line_style) but when a point is added to it,
  all the canvas is redrawn. It is not so important for static data byt for Real-Time data asquisition
  the CPU ussade is much lower using Ca_LinePoint (and Fl_DoubleWindow). Ca_Line have traditional array-like data storage.

  Q2: What about cursors (like Fl_Positioner?) 
  A: It can be implemented ie using an overlay window and plot wire cursors over canvas.
  You have to overrire canvas handle() method in which you can get the position of the cursor for use in
  for draw_overlay() (call redraw_overlay() to update drawing) You can also show the axis coordinates (in say Fl_Value_Output) using value(position)
  methods for axes.

  Q3: Can I print the graphics:
  A: Please use FL_Device patched FLTK (see baazaar). You maybe want to change background before printing canvas/axes (but change it back after printing...)




Roman