
GUIDELINES FOR DEVELOPMENT
==========================

Explorer
========
Remark: with the introduction tree links in QDobject, this wil be
obsolete in a near future.

A project is given a tree structure inspired by grace-6 and visualized
by the explorer popup but in order to manage a smooth transition from
Grace-5, it is managed with two modes:  
array of QDobject objs[] and the links in the structure.

Each node in the tree is given a type indexed in the Qtype enum (in
defines.h) and a human readable name (Qtype_name[] in globals.h).
To avoid redundancy in the management of a lot of objects,
the old structures boxtype, linetype, ellipsetype, plotstr, legend
are gathered into a unique QDobject structure realized in the objs[] array.

Each Q_Line, Q_String, Q_Arc, Q_Box, Q_TimeStamp  object
as an objs[] element attached.
For each type above, a id number is stored:
* for graphs, it is the graph number,
* for lines, arcs, strings and boxes  we use a numbering for each type,
  but it is global in the sens that it is not  related to a particular graph.
* To manage the tree structure, parent_typ and parent_id are also
  stored: it is assumed that the quadruple (typ ,id ,parent_typ ,parent_id) 
  allows to retrieve without ambiguity the parent in the tree.
  If it is not the case, it is always possible to retrieve the grandfather...


STYLE
=====
Comments in C++ style (i.e. //) are used to signal pending issues.

Prefixes
--------
gg_* : Motif to GTK transition was made with new GTK files that have
       the Motif name prefixed with gg_  with sometimes  obvious
       changes, e.g.: 
motifutils.c  -> gg_gtkutils.c
xprotos.h -> gg_protos.h
xmgrace.c -> gg.c

ge_* : explorer GTK files

gw_* : custom GtkWidget that can be used in a more general frame then
       Grace. 

ng_* : new files not directly related to explorer popup

nn_cmd* : New NoGUI (actually GUI independent) follow_me files

When the existing files need changes in calls (to gg_ fonctions),
the flag WITH_GTK is used: "grep" on it to search this lines.

The line number in the "Replace ..." comments are only
indications: I have used a hacked version of grace-5.1.22

Tree links
==========
For historical reasons (grace-5 ancestor), drawables are managed
through arrays. The table below summarize the main arrays:

Drawable   array    struct     struct            element                Qtype
           name     name       definition        created by
-------------------------------------------------------------------------------
graph      g        graph      ./src/graphs.h     realloc_graphs        Q_Graph
set        g[]->p   plotarr        "              realloc_graph_plots   Q_Set
axis       g[]->t   tickmarks  ./src/defines.h    new_graph_tickmarks   Q_Axis
g.legend   g[].l    legend         "                                    Q_LegendBox
general    objs     QDobject       "              obj_next
---------------------------------------------------------------------

In order to manage the drawables as nodes in a tree, each drawable
is associated to an element in the "objs" array. 
In  QDobject, the pointers self ,elder ,brother ,child; 
are indexes in array objs[] and managed through the
functions defined in ./src/nn_tree.c 

Special values for tree links pointers:
	-1 :  not initialized
	objs[].elder == -2 : element is possibly created before its parent, thus
	     is orphaned and must be linked after its parent exists

id values for different types
=============================
Some QDobject(s) are unique in there branch, thus have a
     id = -1 : Q_TimeStamp, Q_LegendBox, Q_Project, 
     	        (and for other reason  Q_Undef)
Numbered globally in the project: 
	geometric objs: id for Q_Line, Q_Arc, Q_String, Q_Box
	Q_Graph       : gno, get_cg ()   )
Numbered in each graph:
	 Q_Axis       : curaxis, axisno
	 Q_Set        : setno
Templates for Q_Line, Q_Arc, Q_String, Q_Box:
         have a id=-1 and parent_typ=typ

GTK tree, objs tree and arrays
==============================
In order to keep a good separation between GUI/noGUI files and
functions, the GTK facilities provided by GtkTree are used only 
to synchronize the explorer window, mainly in ge_* files,  
and functions provided by  ./src/nn_tree.c to synchronize the objs
tree with the arrays in the table above.

Q_Graph trees
-------------
Q_LegendBox must be the last element before the geometrical objects


Handles management
==================
The low level function gg_handles in ./src/gg_gutil.c is based on a XORed
GC. It is called by intermediate level functions in ./src/ng_handles.c
called according to mouse and explorer events i.e.
from ./src/gg_events.c , ./src/ge.c and ./src/ge_obj.c

Undo/Redo
=========
It is based on Grace language and libundo library (see src/nn_cmd.c)
Each time changes are made effective (i.e. when "Apply" or "Accept" is 
clicked), a set of command lines is registered with "undo_snapshot" via 
nn_cmd_undo_snap with two lines for each change: the first is the old
value, the second the new one. Thus undo is performed using odd lines,
and redo using even lines. As one click can be related to several
changes, the "libundo_count" is different from the "user_undo_count" 

Buildinfo
=========
I use "mkmf", the makefile editor written by Peter J. Nicklin to maintains 
the src/Makefile, assuming that there is only one main() in a directory,
thus I created a buildinfo directory for the program of the same name
and move it into that directory.

Menu3
=====
Used for menus raised by mouse Button3 in graph_list or sets_list.
When I try to use a unique GraphMenu3Struct in gg_gtkutils.c 
the menu3 is poped out as wanted but the actions are performed on
using the items selected in the first popup created, not in the
current one. Thus an instance of menu3 is created for each gw_list:
this is not very satisfactorily.

Vector maps
===========


Hints for emacs users
=====================
My preferred tools for GraceGTK development is emacs (23): 
I give here some hints for the inexperienced user.

* Maximize emacs windows and split it in two buffers with C-x 3 
  (or 3 by repeating C-x 3 and equalizing sizes with  C-x +)

* Display direds with selected files (e.g. C-x d <return> *.h will
  display only include files,  C-x d <return> *.c the *.c files, etc.

* The Makefile run etags (not ctags) to build the TAGS file. 
   I have added the path  to grace-5.1.22 files to gain a direct
   access to the old functions,  but you will have to adapt this path
   if you want to use that. 
   To ease the use I have added in one of the emacs configuration
   files (e.g. .emacs) the following elisp function:

(defun pv-find-tag  (click)
  "To run find-tag with the mouse."
  (interactive "e")
  (mouse-set-point click)
  (require 'etags)
  (find-tag-other-window (find-tag-default))
  (recenter 0))

;;   and added the following binding
(global-set-key [S-mouse-3] 'pv-find-tag)   

  Thus, when I click with mouse Button3 with the shift key pressed,
  the pointed function is displayed in another buffer

* The ffap package gives hypertext possibilities to emacs. To open the
  new file in another window, I added the elisp function

(defun pv-ffap-at-mouse-other-window (e)
  "Hypertext: comme ffap-at-mouse mais utilise une autre fenetre."
  (interactive "e")
  (mouse-set-point e)
  (switch-to-buffer-other-window
   (save-window-excursion
     (call-interactively 'ffap-at-mouse) (current-buffer))))

;;   and added the following binding
(global-set-key [mouse-3] 'pv-ffap-at-mouse-other-window) 

   Thus, When I click with mouse Button3 on a file name (of URL), the
   file is displayed in another buffer

;;; Local Variables: ***
;;; mode: auto-fill  ***
;;; mode: flyspell   ***
;;; ispell-local-dictionary: "english" ***
;;; End: ***