## visu_pickMesure

visu_pickMesure — Some methods to treat a VisuPick informations.

## Synopsis

    enum                PickMesureType;
                        PickMesure;
    void                initPick_module                     ();
    gchar*              pickMesureGet_errors                (PickMesure *mesureData);
    gchar*              pickMesureGet_infos                 (PickMesure *mesureData);
    VisuNode*           pickMesureGet_firstReference        (PickMesure *mesureData);
    gboolean            pickMesureGet_newsAvailable         (PickMesure *mesureData,
                                                             PickMesureType *type);
    VisuNode*           pickMesureGet_selectedNode          (PickMesure *mesureData);
    float*              pickMesureGet_drag                  (PickMesure *mesureData);
    int                 pickMesureGet_regionNNodes          (PickMesure *mesureData);
    GList*              pickMesureGet_regionNodes           (PickMesure *mesureData);
    void                pickMesureSet_storeDistance         (PickMesure *mesureData,
                                                             gboolean storeDistance);
    void                pickMesureSet_formatedOutput        (PickMesure *mesureData,
                                                             gboolean formatedOutput);
    void                pickMesureSet_highlight             (PickMesure *mesureData,
                                                             int idNode,
                                                             gboolean status);
    void                pickMesureSet_dragMove              (PickMesure *mesureData,
                                                             float dx,
                                                             float dy,
                                                             float dz);
    void                pickMesureSet_dragStart             (PickMesure *mesureData,
                                                             int nodeId);
    void                pickMesureSet_dragStop              (PickMesure *mesureData);
    void                pickMesureSet_pickNode              (PickMesure *mesureData,
                                                             int nodeId,
                                                             PickMesureType type);
    void                pickMesureSet_pickRegion            (PickMesure *mesureData,
                                                             GList *nodeIds);
    void                pickMesureToggle_highlight          (PickMesure *mesureData,
                                                             GList *idNodes);
    gboolean            pickMesureRemove_allDistanceMarks   (PickMesure *mesureData);
    gboolean            pickMesureRemove_allMarks           (PickMesure *mesureData);
    gboolean            pickMesureRemove_allHighlights      (PickMesure *mesureData);
    void                pickMesureUpdate                    (VisuData *newData,
                                                             VisuData *oldData);

## Description

The pick mesures work on static variables, thus only one pick session is possible at a time. Each time a node is selected, `marksAndMesures()` should be called. To retrieve then the results of the measurements, `getPickMesureInfos()` and `getPickMesureErrors()` are available.

## Details

### enum PickMesureType

    typedef enum
      {
        PICK_SELECTED,
        PICK_REFERENCE_1,
        PICK_REFERENCE_2,
        PICK_REGION,
        PICK_DRAG_START,
        PICK_DRAG_MOVE,
        PICK_DRAG_STOP
      } PickMesureType;

These values are used with `pickMesureSet_pickNode()` to specify that the selected node is a simple one or a reference.

`PICK_SELECTED` | a node has been selected with simple clic ;
`PICK_REFERENCE_1` | a node has been selected has a first reference ;
`PICK_REFERENCE_2` | a node has been selected has a second reference ;
`PICK_REGION` | a list of nodes as been selected ;
`PICK_DRAG_START` | the selected node has been picked for a drag ;
`PICK_DRAG_MOVE` | the selected node is moving ;
`PICK_DRAG_STOP` | the selected node has just been released from a drag.

### PickMesure

    typedef struct _PickMesure PickMesure;

Short way to address PickMesure_struct objects.

### initPick_module ()

    void                initPick_module                     ();

Call by V_Sim on startup, don't use it.

### pickMesureGet_errors ()

    gchar*              pickMesureGet_errors                (PickMesure *mesureData);

When a pick session is running with the format flag (see `pickMesureSet_formatedOutput()` for deatils), calls to `pickMesureSet_selection()` creates strings that represent the values of the mesure. If error occurs, they are retrievable with this method.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | a string (own by V_Sim, should not be freed).

### pickMesureGet_infos ()

    gchar*              pickMesureGet_infos                 (PickMesure *mesureData);

When a pick session is running with the format flag (see `pickMesureSet_formatedOutput()` for deatils), calls to `pickMesureSet_selection()` creates strings that represent the values of the mesure. These values are retrievable with this method.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | a string (own by V_Sim, should not be freed).

### pickMesureGet_firstReference ()

    VisuNode*           pickMesureGet_firstReference        (PickMesure *mesureData);

The first reference is a store node.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | the node that has been picked as first reference, or NULL if none.

### pickMesureGet_newsAvailable ()

    gboolean            pickMesureGet_newsAvailable         (PickMesure *mesureData,
                                                             PickMesureType *type);

When a pick is done, maybe nothing interesting happen, get informed with this method.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
`type` : | if not NULL, contains on output the kind of news available.
Returns : | TRUE if values stored in the given `mesureData` have changed.

### pickMesureGet_selectedNode ()

    VisuNode*           pickMesureGet_selectedNode          (PickMesure *mesureData);

The selected node is a node selected by a normal pick, i.e. neither a first nor a second reference.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | the last selected node, or NULL if none.

### pickMesureGet_drag ()

    float*              pickMesureGet_drag                  (PickMesure *mesureData);

Retrieve the translation vector in a drag session.

`mesureData` : | a PickMesure structure.
Returns : | a three float vector owned by V_Sim.

### pickMesureGet_regionNNodes ()

    int                 pickMesureGet_regionNNodes          (PickMesure *mesureData);

Return only the number of selected nodes in a region, without actually creating the list. See `pickMesureGet_regionNodes()` to get this list.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | the number of selected nodes in a region.

### pickMesureGet_regionNodes ()

    GList*              pickMesureGet_regionNodes           (PickMesure *mesureData);

Create a list of VisuNode from a selected region. There should be a selected region, see `pickMesureGet_newsAvailable()`.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | a newly created list of selected nodes. Should be freed with `g_list_free()` after use.

### pickMesureSet_storeDistance ()

    void                pickMesureSet_storeDistance         (PickMesure *mesureData,
                                                             gboolean storeDistance);

If this flag is TRUE, distance marks are used. If FALSE, only future distance marks are disable. Previously stored distance marks are kept, use `pickMesureRemove_allDistanceMarks()` to remove them all.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes ;
`storeDistance` : | a boolean.

### pickMesureSet_formatedOutput ()

    void                pickMesureSet_formatedOutput        (PickMesure *mesureData,
                                                             gboolean formatedOutput);

If this flag is TRUE, one can retrieve some formatted output using the `getPickMesureInfos()` and `getPickMesureErrors()` methods.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes ;
`formatedOutput` : | a boolean.

### pickMesureSet_highlight ()

    void                pickMesureSet_highlight             (PickMesure *mesureData,
                                                             int idNode,
                                                             gboolean status);

Put an highlight (or remove it) on a given node. The OpenGL area should be redraw after the call.

`mesureData` : | a PickMesure structure ;
`idNode` : | the node to highlight ;
`status` : | switch on or off the highlight.

### pickMesureSet_dragMove ()

    void                pickMesureSet_dragMove              (PickMesure *mesureData,
                                                             float dx,
                                                             float dy,
                                                             float dz);

Update the information of measurement when drag is done with the given translation vector.

`mesureData` : | a PickMesure structure ;
`dx` : | a variation in cartesian coordinates ;
`dy` : | a variation in cartesian coordinates ;
`dz` : | a variation in cartesian coordinates.

### pickMesureSet_dragStart ()

    void                pickMesureSet_dragStart             (PickMesure *mesureData,
                                                             int nodeId);

Update the information of measurement when drag is begun on node `nodeId`.

`mesureData` : | a PickMesure structure ;
`nodeId` : | a node id.

### pickMesureSet_dragStop ()

    void                pickMesureSet_dragStop              (PickMesure *mesureData);

Update the information of measurement when drag is stopped.

`mesureData` : | a PickMesure structure.

### pickMesureSet_pickNode ()

    void                pickMesureSet_pickNode              (PickMesure *mesureData,
                                                             int nodeId,
                                                             PickMesureType type);

Update the information of measurement when the `nodeId` is selected. See PickMesureType for further information on the different kind of possible selection. For this method, only PICK_SELECTED, PICK_REFERENCE_1 and PICK_REFERENCE_2 are possible. See `pickMesureGet_newsAvailable()` to catch possible changes in a callback.

Strings are created to represent the return of the mesure (if this has been activated using `pickMesureSet_formatedOutput()`). These strings are available with a call to `pickMesureGet_infos()` and `pickMesureGet_errors()`.

`mesureData` : | a PickMesure structure ;
`nodeId` : | a node id ;
`type` : | a value in PickMesureType.

### pickMesureSet_pickRegion ()

    void                pickMesureSet_pickRegion            (PickMesure *mesureData,
                                                             GList *nodeIds);

Update the information of measurement when a region containing `nodeIds` is selected. See `pickMesureGet_newsAvailable()` to catch possible changes in a callback.

`mesureData` : | a PickMesure structure ;
`nodeIds` : | a list of node ids.

### pickMesureToggle_highlight ()

    void                pickMesureToggle_highlight          (PickMesure *mesureData,
                                                             GList *idNodes);

Toggle the highlight for the given nodes.

`mesureData` : | a PickMesure structure ;
`idNodes` : | a list of node ids (use `GPOINTER_TO_INT()` to read them).

### pickMesureRemove_allDistanceMarks ()

    gboolean            pickMesureRemove_allDistanceMarks   (PickMesure *mesureData);

Call this method to erase all previously marked distances.

`mesureData` : | a PickMesure structure that contains the informations about picked nodes.
Returns : | TRUE if the "OpenGLAskForReDraw" signal show be emitted.

### pickMesureRemove_allMarks ()

    gboolean            pickMesureRemove_allMarks           (PickMesure *mesureData);

Erase all marks corresponding to given object.

`mesureData` : | a PickMesure structure that contains the informations about Nodes with marks that need to be erased.
Returns : | TRUE if the "OpenGLAskForReDraw" signal show be emitted.

### pickMesureRemove_allHighlights ()

    gboolean            pickMesureRemove_allHighlights      (PickMesure *mesureData);

It empties the list of all highlights.

`mesureData` : | a PickMesure structure.
Returns : | TRUE if the redraw signal should be emitted.

### pickMesureUpdate ()

    void                pickMesureUpdate                    (VisuData *newData,
                                                             VisuData *oldData);

This method try to retrieve a PickMesure object associated to each given VisuData object and to update the marks and distances on the new from the values of the old.

`newData` : | a VisuData object (can be NULL) ;
`oldData` : | a VisuData object (can be NULL).