## visu_pickMesure

visu_pickMesure — Some methods to treat a VisuPick informations.

## Synopsis

    struct      PickMesure_struct;
    typedef     PickMesure;
    void        initPick_module                 ();
    PickMesure* initPickMesure                  (VisuData *data,
                                                 gboolean formatFlag,
                                                 gboolean storeDistance);
    void        endPickMesure                   (PickMesure *pickMesureData);
    void        marksAndMesures                 (const VisuPick *info,
                                                 gpointer data);
    gchar*      getPickMesureInfos              (PickMesure *mesureData);
    gchar*      getPickMesureErrors             (PickMesure *mesureData);
    VisuNode*   pickMesureGet_firstReference    (PickMesure *mesureData);
    gboolean    pickMesureGet_newsAvailable     (PickMesure *mesureData);
    VisuNode*   pickMesureGet_selectedNode      (PickMesure *mesureData);
    void        pickMesureSet_storeDistance     (PickMesure *mesureData,
                                                 gboolean storeDistance);
    void        pickMesureSet_formatedOutput    (PickMesure *mesureData,
                                                 gboolean formatedOutput);
    gboolean    pickMesureRemove_allDistanceMarks
                                                (PickMesure *mesureData);
    gboolean    pickMesureRemove_allMarks       (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

### struct PickMesure_struct

    struct PickMesure_struct;

Opaque structure that store the pick informations.

### PickMesure

    typedef struct PickMesure_struct PickMesure;

Short way to address PickMesure_struct objects.

### initPick_module ()

    void        initPick_module                 ();

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

### initPickMesure ()

    PickMesure* initPickMesure                  (VisuData *data,
                                                 gboolean formatFlag,
                                                 gboolean storeDistance);

Initialized the static values that are used when a pick session is running. If `formatFlag` if set, strings about the pick actions are available with calls to `getPickMesureInfos()` and `getPickMesureErrors()`. If not set, only pointers informations on which nodes have been picked are available. If the `storeDistance` argument is TRUE, distance marks are used.

`data` : | a VisuData object to pick on ;
`formatFlag` : | a boolean ;
`storeDistance` : | a boolean.
Returns : | a newly created object. Use `endPickMesure()` when this object is no longer necessary.

### endPickMesure ()

    void        endPickMesure                   (PickMesure *pickMesureData);

Free the static values that have been allocated and call `unSetReferencePickMesure()` to clear the marks.

`pickMesureData` : | the PickMesure structure that as been used during the pick session.

### marksAndMesures ()

    void        marksAndMesures                 (const VisuPick *info,
                                                 gpointer data);

The `info` argument contains which element has been picked and static values are adapted accordingly. Strings ae created to represent the return of the mesure. These strings are available with a call to `getPickMesureInfos()` and `getPickMesureErrors()`. When this method is given as argument to `initPickObserve()`, for instance, the associated user data must be an allocated PickMesure object.

`info` : | some VisuPick informations ;
`data` : | a location on an allocated PickMesure structure.

### getPickMesureInfos ()

    gchar*      getPickMesureInfos              (PickMesure *mesureData);

When a pick session is running with the format flag (see `initPickMesure()` for deatils), calls to `marksAndMesures()` create strings that represnt 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).

### getPickMesureErrors ()

    gchar*      getPickMesureErrors             (PickMesure *mesureData);

When a pick session is running with the format flag (see `initPickMesure()` for deatils), calls to `marksAndMesures()` create strings that represnt 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_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);

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

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

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

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