/*   EXTRAITS DE LA LICENCE
	Copyright CEA, contributeurs : Luc BILLARD et Damien
	CALISTE, laboratoire L_Sim, (2001-2006)
  
	Adresse mèl :
	BILLARD, non joignable par mèl ;
	CALISTE, damien P caliste AT cea P fr.

	Ce logiciel est un programme informatique servant à visualiser des
	structures atomiques dans un rendu pseudo-3D. 

	Ce logiciel est régi par la licence CeCILL soumise au droit français et
	respectant les principes de diffusion des logiciels libres. Vous pouvez
	utiliser, modifier et/ou redistribuer ce programme sous les conditions
	de la licence CeCILL telle que diffusée par le CEA, le CNRS et l'INRIA 
	sur le site "http://www.cecill.info".

	Le fait que vous puissiez accéder à cet en-tête signifie que vous avez 
	pris connaissance de la licence CeCILL, et que vous en avez accepté les
	termes (cf. le fichier Documentation/licence.fr.txt fourni avec ce logiciel).
*/

/*   LICENCE SUM UP
	Copyright CEA, contributors : Luc BILLARD et Damien
	CALISTE, laboratoire L_Sim, (2001-2006)

	E-mail address:
	BILLARD, not reachable any more ;
	CALISTE, damien P caliste AT cea P fr.

	This software is a computer program whose purpose is to visualize atomic
	configurations in 3D.

	This software is governed by the CeCILL  license under French law and
	abiding by the rules of distribution of free software.  You can  use, 
	modify and/ or redistribute the software under the terms of the CeCILL
	license as circulated by CEA, CNRS and INRIA at the following URL
	"http://www.cecill.info". 

	The fact that you are presently reading this means that you have had
	knowledge of the CeCILL license and that you accept its terms. You can
	find a copy of this licence shipped with this software at Documentation/licence.en.txt.
*/
#ifndef INTERACTIVE_H
#define INTERACTIVE_H

#include <glib.h>

#include <visu_nodes.h>
#include <visu_data.h>

/**
 * OPENGL_OBSERVE_CONSTRAINED
 *
 * This is a key for the constrained mode in the observe session.
 * In this mode, the movements are along meridians when the mouse is
 * dragged along y axis and along parallels when the movement is along x axis.
 */
#define OPENGL_OBSERVE_CONSTRAINED 0
/**
 * OPENGL_OBSERVE_WALKER
 *
 * This is a key for the constrained mode in the observe session.
 * In this mode, the movementsare those of a walking ant on a sphere,
 * when mouse move along y axis, the ant goes strait on, when mouse is
 * dragged along x axis, the ant translates on its right or on its left.
 */
#define OPENGL_OBSERVE_WALKER 1

/**
 * VisuPick_struct:
 * @data: a pointer to the #VisuData whose @node belongs to ;
 * @node: a pointer to a #VisuNode that has been selected ;
 * @button: an integer identifying the button that clicked on the node ;
 * @shiftMod: a boolean to set if shift button was pushed during the click ;
 * @x: x coordinate of the click in window pixels ;
 * @y: y coordinate of the click in window pixels
 *
 * This structure is used when the user uses the pick
 * interface. It stores some informations on the pick action.
 */
struct VisuPick_struct
{
  VisuData *data;
  VisuNode *node;
  unsigned int button;
  int shiftMod;
  int x, y;
};
/**
 * VisuPick
 *
 * A short definition for #VisuPick_struct objects.
 */
typedef struct VisuPick_struct VisuPick;

/**
 * openGLSet_preferedObserveMethod:
 * @method: an integer that identify the method, see #OPENGL_OBSERVE_CONSTRAINED,
 *          and #OPENGL_OBSERVE_WALKER flags.
 *
 * There are two methods to move the camera in a pick and observe sesion. These
 * two methods are described in the commentary of the keys #OPENGL_OBSERVE_CONSTRAINED
 * an d#OPENGL_OBSERVE_WALKER.
 */
void openGLInteractiveSet_preferedObserveMethod(int method);
/**
 * openGLGet_preferedObserveMethod:
 *
 * There are two methods to move the camera in a pick and observe sesion. These
 * two methods are described in the commentary of the keys #OPENGL_OBSERVE_CONSTRAINED
 * an d#OPENGL_OBSERVE_WALKER.
 *
 * Returns: an integer that identify the method, see #OPENGL_OBSERVE_CONSTRAINED,
 *          and #OPENGL_OBSERVE_WALKER flags.
 */
int openGLInteractiveGet_preferedObserveMethod();

/**
 * callBackOnNodeSelectedFunc:
 * @pickData: the structure containing the informations of the
 *            pick (mouse click, position...) ;
 * @data: a pointer to user define data.
 *
 * This interface defines functions that are called whenever a
 * node is selected.
 */
typedef void (*callBackOnNodeSelectedFunc) (const VisuPick *pickData, gpointer data);

/* observe and pick functions. */
/**
 * initPickObserve:
 * @window: a pointer to the window that ask to initialize
 *          an interactive mode ;
 * @handler: a pointer to a method to be called whenever
 *           an element is selected (can be NULL) ;
 * @data: a location for user data that can be given to handler ;
 * @stopPickObserve: a pointer to a method that will be called
 *                   every time a pick or an observe session are
 *                   finish (can be NULL).
 *
 * Initialises a period when the client can control an interactive session
 * (observe, pick, move...). It changes cursors shapes and initialises different
 * internal variables. It can be stop by a call to openGLInteractiveEnd_session().
 * The default first interactive session is an observe session.
 */
void openGLInteractiveInit_session(GenericRenderingWindow window,
				   callBackOnNodeSelectedFunc handler, gpointer data,
				   GDestroyNotify stopPickObserve);
/**
 * openGLInteractiveEnd_session:
 *
 * Stop the period when pick or observe sessions are allowed. Basically,
 * for the user point of view it returns the cursor to its initial shape.
 */
void openGLInteractiveEnd_session();
/**
 * openGLInteractiveBegin_observe:
 * 
 * During a pick or observe session, the client can begin an observe session
 * by a call to this method. It actually stops also a possibly running
 * pick session.
 */
void openGLInteractiveBegin_observe();
/**
 * openGLInteractiveBegin_pick:
 * 
 * During a pick or observe session, the client can begin a pick session
 * by a call to this method. It actually stops also a possibly running
 * observe session.
 */
void openGLInteractiveBegin_pick();
/**
 * openGLInteractiveBegin_move:
 * 
 * During an interactive session, the client can begin a move session
 * by a call to this method. It enables the press-button (and release), the motion-notify
 * and the scroll event. It returns the displacement and the node selected.
 */
void openGLInteractiveBegin_move();
/**
 * openGLInteractiveBegin_mark:
 * @data: a #VisuData object.
 * 
 * During an interactive session, the client can begin a mark session
 * by a call to this method. It enables the press-button (and release), the motion-notify
 * and the scroll event. A mark is drawn around the selected element (or removed) when clicked.
 */
void openGLInteractiveBegin_mark(VisuData *data);
/**
 * openGLInteractiveBegin_pickAndObserve:
 * 
 * During a pick or observe session, the client can both observe (normal way)
 * and do minimal pick with the right button.
 */
void openGLInteractiveBegin_pickAndObserve();

/**
 * openGLInteractiveRemove_allMarks:
 * @data: a #VisuData object.
 *
 * It empties the list of all marks.
 *
 * Returns: TRUE if the redraw signal should be emitted.
 */
gboolean openGLInteractiveRemove_allMarks(VisuData *data);

/**
 * openGLInteractive_init:
 *
 * Used to initialise this part of code, don't use it.
 */
void openGLInteractive_init();

#endif
