## interactive

interactive — Gives tools to interact with the rendered area.

## Synopsis

    struct      VisuPick_struct;
    typedef     VisuPick;
    void        (*callBackOnNodeSelectedFunc)   (const VisuPick *pickData,
                                                 gpointer data);
    #define     OPENGL_OBSERVE_CONSTRAINED
    #define     OPENGL_OBSERVE_WALKER
    void        openGLInteractiveInit_session   (GenericRenderingWindow window,
                                                 callBackOnNodeSelectedFunc handler,
                                                 gpointer data,
                                                 GDestroyNotify stopPickObserve);
    void        openGLInteractiveEnd_session    ();
    void        openGLInteractiveBegin_mark     (VisuData *data);
    void        openGLInteractiveBegin_move     ();
    void        openGLInteractiveBegin_observe  ();
    void        openGLInteractiveBegin_pick     ();
    void        openGLInteractiveBegin_pickAndObserve
                                                ();
    void        openGLInteractiveSet_preferedObserveMethod
                                                (int method);
    int         openGLInteractiveGet_preferedObserveMethod
                                                ();
    gboolean    openGLInteractiveRemove_allMarks
                                                (VisuData *data);

    void        openGLInteractive_init          ();

## Description

When one wants some interactions on the rendering area (either from the mouse or from the keyboard), one should initialise it using `openGLInteractiveInit_session()`. Then, during the interactive session, several modes have been implemented:

- `openGLInteractiveBegin_mark()`, is a mode where the mouse can select a node and this nodes become highlighted.

- `openGLInteractiveBegin_move()`, the mouse is then used to move picked nodes. Moves are possible in the plane of the screen or constrained along axis of the bounding box.

- `openGLInteractiveBegin_observe()`, in this mode, the mouse is used to change the position of camera, its orientation and its zoom characteristics.

- `openGLInteractiveBegin_pick()`, this mode is the most complex picking mode. It can select atoms up to two references and measure distances and angles.

- `openGLInteractiveBegin_pickAndObserve()`, this mode is a simplified mix of obervation and picking.

The observe mode has two different moving algorithms that can be changed using `openGLInteractiveSet_preferedObserveMethod()`. The first, called 'constrained' (cf. OPENGL_OBSERVE_CONSTRAINED) corresponds to movements along parallels and meridians. When the mouse is moved along x axis, the camera raotates along a parallel. When the camera is moved along y axis, the camera rotate along a meridian. The top is always pointing to the north pole (in fact, omega is always forced to 0 in this mode). This mode has a 'strange' behavior when the observer is near a pole: moving mouse along x axis make the box rotates on itself. It is normal, because movements on x axis is equivalent to movements on parallel and near the poles, parallel are small circle around the z axis. This can be unnatural in some occasion and the other mode, called 'walker' (see OPENGL_OBSERVE_WALKER) can be used instead of the 'constrained' mode. In the former, the moving is done has if the observer was a walking ant on a sphere : moving the mouse along y axis makes the ant go on or forward ; and x axis movements makes the ant goes on its left or on it right. This is a more natural way to move the box but it has the inconvient that it is hard to return in a given position (omega has never the right value).

## Details

### struct VisuPick_struct

    struct VisuPick_struct {
      VisuData *data;
      VisuNode *node;
      unsigned int button;
      int shiftMod;
      int x, y;
    };

This structure is used when the user uses the pick interface. It stores some informations on the pick action.

VisuData *`data`; | a pointer to the VisuData whose `node` belongs to ;
VisuNode *`node`; | a pointer to a VisuNode that has been selected ;
unsigned int `button`; | an integer identifying the button that clicked on the node ;
int `shiftMod`; | a boolean to set if shift button was pushed during the click ;
int `x`; | x coordinate of the click in window pixels ;
int `y`; | y coordinate of the click in window pixels

### VisuPick

    typedef struct VisuPick_struct VisuPick;

A short definition for VisuPick_struct objects.

### callBackOnNodeSelectedFunc ()

    void        (*callBackOnNodeSelectedFunc)   (const VisuPick *pickData,
                                                 gpointer data);

This interface defines functions that are called whenever a node is selected.

`pickData` : | the structure containing the informations of the pick (mouse click, position...) ;
`data` : | a pointer to user define data.

### OPENGL_OBSERVE_CONSTRAINED

    #define OPENGL_OBSERVE_CONSTRAINED 0

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.

### OPENGL_OBSERVE_WALKER

    #define OPENGL_OBSERVE_WALKER 1

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.

### openGLInteractiveInit_session ()

    void        openGLInteractiveInit_session   (GenericRenderingWindow window,
                                                 callBackOnNodeSelectedFunc handler,
                                                 gpointer data,
                                                 GDestroyNotify stopPickObserve);

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.

`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).

### openGLInteractiveEnd_session ()

    void        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.

### openGLInteractiveBegin_mark ()

    void        openGLInteractiveBegin_mark     (VisuData *data);

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.

`data` : | a VisuData object.

### openGLInteractiveBegin_move ()

    void        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.

### openGLInteractiveBegin_observe ()

    void        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.

### openGLInteractiveBegin_pick ()

    void        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.

### openGLInteractiveBegin_pickAndObserve ()

    void        openGLInteractiveBegin_pickAndObserve
                                                ();

During a pick or observe session, the client can both observe (normal way) and do minimal pick with the right button.

### openGLInteractiveSet_preferedObserveMethod ()

    void        openGLInteractiveSet_preferedObserveMethod
                                                (int method);

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 dOPENGL_OBSERVE_WALKER.

`method` : | an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags.

### openGLInteractiveGet_preferedObserveMethod ()

    int         openGLInteractiveGet_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 dOPENGL_OBSERVE_WALKER.

Returns : | an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags.

### openGLInteractiveRemove_allMarks ()

    gboolean    openGLInteractiveRemove_allMarks
                                                (VisuData *data);

It empties the list of all marks.

`data` : | a VisuData object.
Returns : | TRUE if the redraw signal should be emitted.

### openGLInteractive_init ()

    void        openGLInteractive_init          ();

Used to initialise this part of code, don't use it.