## interactive interactive — Gives tools to interact with the rendered area. |

## Synopsis

    enum                VisuInteractiveMethod;
    enum                VisuInteractiveId;
    enum                VisuInteractivePick;
    enum                VisuInteractivePickError;
    #define             VISU_INTERACTIVE_TYPE
    #define             VISU_INTERACTIVE                    (obj)
    #define             VISU_INTERACTIVE_CLASS              (klass)
    #define             IS_VISU_INTERACTIVE                 (obj)
    #define             IS_VISU_INTERACTIVE_CLASS           (klass)
    #define             VISU_INTERACTIVE_GET_CLASS          (obj)
                        VisuInteractive;
                        VisuInteractiveClass;
    GType               visuInteractive_get_type            (void);
    void                visuInteractiveClassSet_preferedObserveMethod
                                                            (VisuInteractiveMethod method);
    VisuInteractiveMethod  visuInteractiveClassGet_preferedObserveMethod
                                                            ();
    VisuInteractive*    visuInteractiveNew                  (VisuInteractiveId type);
    VisuInteractiveId   visuInteractiveGet_type             (VisuInteractive *inter);
    void                visuInteractiveHandle_event         (VisuInteractive *inter,
                                                             VisuData *dataObj,
                                                             SimplifiedEvents *ev);
    void                visuInteractiveSet_movingNodes      (VisuInteractive *inter,
                                                             GList *nodeIds);
    void                visuInteractiveSet_movingAxe        (VisuInteractive *inter,
                                                             float axe[3]);
    VisuOpenGLCamera*   visuInteractivePop_savedCamera      (VisuInteractive *inter);
    void                visuInteractivePush_savedCamera     (VisuInteractive *inter,
                                                             VisuOpenGLCamera *camera);
    void                visuInteractiveGet_savedCameras     (VisuInteractive *inter,
                                                             GList **cameras,
                                                             GList **head);
    void                visuInteractiveSet_references       (VisuInteractive *inter,
                                                             VisuInteractive *from);
    void                getNodes2DCoordinates               (VisuData *dataObj,
                                                             unsigned int *nodeIds,
                                                             unsigned int nNodes,
                                                             float *coordinates2D,
                                                             unsigned int *size);

## Object Hierarchy

      GObject
       +----VisuInteractive

## Signals

      "move"                                           : Run Last / No Recursion / No Hooks
      "node-selection"                                 : Run Last / No Recursion
      "observe"                                        : Run Last / No Recursion
      "region-selection"                               : Run Last / No Recursion / No Hooks
      "selection-error"                                : Run Last / No Recursion / No Hooks
      "start-move"                                     : Run Last / No Recursion / No Hooks
      "stop"                                           : Run Last / No Recursion / No Hooks

## 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

### enum VisuInteractiveMethod

    typedef enum
      {
        interactive_constrained,
        interactive_walker
      } VisuInteractiveMethod;

Describes the different possible methods for observe moves.

`interactive_constrained` | the camera is moved keeping the north pole up. The north pole is defined by the Z axis et periodic boundary conditions and by normal to surface in surface conditions.
`interactive_walker` | the camera is moved following the mouse moves, orienting the view as a walker would do along a sphere.

### enum VisuInteractiveId

    typedef enum
      {
        interactive_none,
        interactive_observe,
        interactive_measureAndObserve,
        interactive_measure,
        interactive_pick,
        interactive_move,
        interactive_mark
      } VisuInteractiveId;

These are the possible mouse interaction that are implemented.

`interactive_none` | no interaction ;
`interactive_observe` | interaction to rotate the view ;
`interactive_measureAndObserve` | interaction to rotate the view and access limited pick action on the right click ;
`interactive_measure` | interaction to pick and measure ;
`interactive_pick` | interaction to select node ;
`interactive_move` | interaction to move nodes ;
`interactive_mark` | interaction to mark nodes.

### enum VisuInteractivePick

    typedef enum
      {
        PICK_NONE,
        PICK_SELECTED,
        PICK_DISTANCE,
        PICK_ANGLE,
        PICK_HIGHLIGHT,
        PICK_REFERENCE_1,
        PICK_UNREFERENCE_1,
        PICK_REFERENCE_2,
        PICK_UNREFERENCE_2,
        PICK_INFORMATION,
        PICK_REGION
      } VisuInteractivePick;

Possible significations of a click.

`PICK_NONE` | click to void ;
`PICK_SELECTED` | click to select one node ;
`PICK_DISTANCE` | click to measure a distance between two nodes ;
`PICK_ANGLE` | click to measure an angle ;
`PICK_HIGHLIGHT` | click to highlight a node ;
`PICK_REFERENCE_1` | click to select a first reference ;
`PICK_UNREFERENCE_1` | click to un-select a first reference ;
`PICK_REFERENCE_2` | click to select a second reference ;
`PICK_UNREFERENCE_2` | click to un-select a second reference ;
`PICK_INFORMATION` | click to measure distances and angles around one node ;
`PICK_REGION` | click to select a list of nodes.

### enum VisuInteractivePickError

    typedef enum
      {
        PICK_ERROR_NONE,
        PICK_ERROR_NO_SELECTION,
        PICK_ERROR_SAME_REF,
        PICK_ERROR_REF1,
        PICK_ERROR_REF2
      } VisuInteractivePickError;

Possible errors to occur when pick or measure.

`PICK_ERROR_NONE` | no error during click ;
`PICK_ERROR_NO_SELECTION` | click to sleect but nothing selected ;
`PICK_ERROR_SAME_REF` | click to set a reference but reference already exists ;
`PICK_ERROR_REF1` | click to select a first reference but impossible to choose this one ;
`PICK_ERROR_REF2` | the same for second reference.

### VISU_INTERACTIVE_TYPE

    #define VISU_INTERACTIVE_TYPE	     (visuInteractive_get_type ())

return the type of VisuInteractive.

### VISU_INTERACTIVE()

    #define VISU_INTERACTIVE(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, VISU_INTERACTIVE_TYPE, VisuInteractive))

Cast the given `obj` into VisuInteractive type.

`obj` : | a GObject to cast.

### VISU_INTERACTIVE_CLASS()

    #define VISU_INTERACTIVE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, VISU_INTERACTIVE_TYPE, VisuInteractiveClass))

Cast the given `klass` into VisuInteractiveClass.

`klass` : | a GObjectClass to cast.

### IS_VISU_INTERACTIVE()

    #define IS_VISU_INTERACTIVE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, VISU_INTERACTIVE_TYPE))

Test if the given `ogj` is of the type of VisuInteractive object.

`obj` : | a GObject to test.

### IS_VISU_INTERACTIVE_CLASS()

    #define IS_VISU_INTERACTIVE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, VISU_INTERACTIVE_TYPE))

Test if the given `klass` is of the type of VisuInteractiveClass class.

`klass` : | a GObjectClass to test.

### VISU_INTERACTIVE_GET_CLASS()

    #define VISU_INTERACTIVE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, VISU_INTERACTIVE_TYPE, VisuInteractiveClass))

It returns the class of the given `obj`.

`obj` : | a GObject to get the class of.

### VisuInteractive

    typedef struct _VisuInteractive VisuInteractive;

All fields are private.

### VisuInteractiveClass

    typedef struct _VisuInteractiveClass VisuInteractiveClass;

An opaque structure representing the class of VisuInteractive objects.

### visuInteractive_get_type ()

    GType               visuInteractive_get_type            (void);

This method returns the type of VisuInteractive, use VISU_INTERACTIVE_TYPE instead.

Returns : | the type of VisuInteractive.

### visuInteractiveClassSet_preferedObserveMethod ()

    void                visuInteractiveClassSet_preferedObserveMethod
                                                            (VisuInteractiveMethod 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.

### visuInteractiveClassGet_preferedObserveMethod ()

    VisuInteractiveMethod  visuInteractiveClassGet_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.

### visuInteractiveNew ()

    VisuInteractive*    visuInteractiveNew                  (VisuInteractiveId type);

Creates a new interactive session of the given `type`.

`type` : | a VisuInteractiveId flag.
Returns : | a newly created object.

### visuInteractiveGet_type ()

    VisuInteractiveId   visuInteractiveGet_type             (VisuInteractive *inter);

It returns the kind of interactive session.

`inter` : | a VisuInteractive object.
Returns : | a VisuInteractiveId value.

### visuInteractiveHandle_event ()

    void                visuInteractiveHandle_event         (VisuInteractive *inter,
                                                             VisuData *dataObj,
                                                             SimplifiedEvents *ev);

This routine should be called by the rendering window when some event is raised on the rendering surface.

`inter` : | a VisuInteractive object ;
`dataObj` : | the VisuData object to interact with ;
`ev` : | a simplified event.

### visuInteractiveSet_movingNodes ()

    void                visuInteractiveSet_movingNodes      (VisuInteractive *inter,
                                                             GList *nodeIds);

Defines the nodes that should be moved if `inter` is a move action session. The list is actually copied.

`inter` : | a VisuInteractive object.
`nodeIds` : | a list of node ids.

### visuInteractiveSet_movingAxe ()

    void                visuInteractiveSet_movingAxe        (VisuInteractive *inter,
                                                             float axe[3]);

Defines the axe that can be used to move along if `inter` is a move action session.

`inter` : | a VisuInteractive object.
`axe` : | a direction.

### visuInteractivePop_savedCamera ()

    VisuOpenGLCamera*   visuInteractivePop_savedCamera      (VisuInteractive *inter);

`inter` object stores camera settings as a ring. This routine goes to the next camera in the ring and returns the current one. The popped camera is not actually removed from the ring.

`inter` : | a VisuInteractive object.
Returns : | a pointer to the previously current VisuOpenGLCamera. It is owned by V_Sim and should not be touched.

Since 3.6

### visuInteractivePush_savedCamera ()

    void                visuInteractivePush_savedCamera     (VisuInteractive *inter,
                                                             VisuOpenGLCamera *camera);

`inter` object stores camera settings as a ring. The given `camera` is copied in the ring if its values not already exist. The current camera is set to this new one.

`inter` : | a VisuInteractive object.
`camera` : | a VisuOpenGLCamera object.

Since 3.6

### visuInteractiveGet_savedCameras ()

    void                visuInteractiveGet_savedCameras     (VisuInteractive *inter,
                                                             GList **cameras,
                                                             GList **head);

`inter` object stores camera settings as a ring. One can access the set of saved cameras thanks to `cameras` or to the current position in the ring thanks to `head`. `cameras` or `head` are not copied and are owned by V_Sim. They should be considered read-only.

`inter` : | a VisuInteractive object.
`cameras` : | a location to store a list of cameras.
`head` : | a location to store a list of cameras.

Since 3.6

### visuInteractiveSet_references ()

    void                visuInteractiveSet_references       (VisuInteractive *inter,
                                                             VisuInteractive *from);

Copies all node ids used as reference from `from` to `inter`.

`inter` : | a VisuInteractive object.
`from` : | another VisuInteractive object.

### getNodes2DCoordinates ()

    void                getNodes2DCoordinates               (VisuData *dataObj,
                                                             unsigned int *nodeIds,
                                                             unsigned int nNodes,
                                                             float *coordinates2D,
                                                             unsigned int *size);

From nodes ids, compute and store in `coordinates2D` their 2D coordinates.

`dataObj` : | a VisuData object ;
`nodeIds` : | an array of VisuNode ids ;
`nNodes` : | the number of nodes in the array ;
`coordinates2D` : | an array of nodes 2D coordinates ;
`size` : | the size of the coordinates array.

## Signal Details

### The `"move"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            gpointer         nodes,
                                                            gpointer         user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted each time a set of nodes are moved. The corresponding nodes are stored in `nodes`.

`obj` : | the object emitting the signal.
`nodes` : | an array of node ids.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"node-selection"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            guint            kind,
                                                            gpointer         nodes,
                                                            gpointer         user_data)      : Run Last / No Recursion

This signal is emitted each time a single node selection succeed, providing the kind in `kind` (see VisuInteractivePick). The corresponding nodes are stored in `nodes`.

`obj` : | the object emitting the signal.
`kind` : | a flag.
`nodes` : | an array of three node ids.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"observe"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            gboolean         bool,
                                                            gpointer         user_data)      : Run Last / No Recursion

This signal is emitted each time an observe session is start (`bool` is TRUE) or finished (`bool` is FALSE).

`obj` : | the object emitting the signal.
`bool` : | a boolean.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"region-selection"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            gpointer         nodes,
                                                            gpointer         user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted each time a region selection succeed. The corresponding nodes are stored in `nodes`.

`obj` : | the object emitting the signal.
`nodes` : | an array of node ids.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"selection-error"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            guint            err,
                                                            gpointer         user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted each time a selection fails, providing the error in `err` (see VisuInteractivePickError).

`obj` : | the object emitting the signal.
`err` : | an error value.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"start-move"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            gpointer         nodes,
                                                            gpointer         user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted each time a set of nodes are clicked to be moved. The corresponding nodes are stored in `nodes`.

`obj` : | the object emitting the signal.
`nodes` : | an array of node ids.
`user_data` : | user data set when the signal handler was connected.

Since 3.6

### The `"stop"` signal

    void                user_function                      (VisuInteractive *obj,
                                                            gpointer         user_data)      : Run Last / No Recursion / No Hooks

This signal is emitted each time a set of nodes are stopped to be moved.

`obj` : | the object emitting the signal.
`user_data` : | user data set when the signal handler was connected.

Since 3.6