## box box — Draw a bounding box around nodes. |

## Synopsis

    VisuExtension*      initExtensionBox                    ();
    #define             VISU_GLEXT_BOX_ID
    gboolean            visu_glExt_box_setRGBValues         (float rgb[3],
                                                             int mask);
    gboolean            visu_glExt_box_setLineWidth         (float width);
    gboolean            visu_glExt_box_setOn                (int value);
    gboolean            visu_glExt_box_setLineStipple       (guint16 stipple);
    gboolean            visu_glExt_box_setExpandStipple     (guint16 stipple);
    float*              visu_glExt_box_getRGBValues         ();
    int                 visu_glExt_box_getOn                ();
    float               visu_glExt_box_getLineWidth         ();
    guint16             visu_glExt_box_getLineStipple       ();
    guint16             visu_glExt_box_getExpandStipple     ();
    void                visu_glExt_box_draw                 (VisuData *data);
    void                visu_glExt_box_draw_legend          (VisuData *dataObj);
    gboolean            visu_glExt_box_getShowLegend        ();
    gboolean            visu_glExt_box_setShowLegend        (gboolean value);

## Description

This extension allows V_Sim to draw a box around the nodes. The box is defined in the VisuData structure and can be retrieved with `visu_data_getBoxGeometry()`. This box is not necessary orthogonal.

It has several properties, namely, its colour, its line width and its line pattern. It is represented in OpenGL with simple lines and is affected by the antialiasing property. Defined resources:

- box_is_on (boolean): controls if a box is drawn around the rendering area (since 3.0).

- box_color (RGB in [0;1]): defines the color of the box(since 3.0).

- box_line_width (integer in [1;10]): defines the width of the lines of the box (since 3.0).

- box_line_stipple (2 integers in ]0;65535]): dot scheme detail for the lines of the box. The first value is the pattern for the line of the main box and the second is the pattern for the lines of the expanded areas (since 3.4).

## Details

### initExtensionBox ()

    VisuExtension*      initExtensionBox                    ();

It initialises all variables of the OpenGL extension. It creates all resources and parameters introduced by this extension. This method should be added in the `listInitExtensionFunc` to be called automatically by the `initVisuExtensions()` at V_Sim startup.

Returns : | a pointer to the VisuExtension it created or NULL otherwise.

### VISU_GLEXT_BOX_ID

    #define VISU_GLEXT_BOX_ID "Box"

The id used to identify this extension, see `visuExtensions_rebuildList()` for instance.

### visu_glExt_box_setRGBValues ()

    gboolean            visu_glExt_box_setRGBValues         (float rgb[3],
                                                             int mask);

Method used to change the value of the parameter box_color.

`rgb` : | a three floats array with values (0 <= values <= 1) for the red, the green and the blue color. Only values specified by the mask are really relevant.
`mask` : | use TOOL_COLOR_MASK_R, TOOL_COLOR_MASK_G, TOOL_COLOR_MASK_B, TOOL_COLOR_MASK_RGBA or a combinaison to indicate what values in the rgb array must be taken into account.
Returns : | TRUE if `visu_glExt_box_draw()` should be called.

### visu_glExt_box_setLineWidth ()

    gboolean            visu_glExt_box_setLineWidth         (float width);

Method used to change the value of the parameter box_line_width.

`width` : | value of the desired box line width.
Returns : | TRUE if `visu_glExt_box_draw()` should be called.

### visu_glExt_box_setOn ()

    gboolean            visu_glExt_box_setOn                (int value);

Method used to change the value of the parameter box_is_on.

`value` : | 1 if box must be drawn, 0 otherwise.
Returns : | TRUE if `visu_glExt_box_draw()` should be called.

### visu_glExt_box_setLineStipple ()

    gboolean            visu_glExt_box_setLineStipple       (guint16 stipple);

Method used to change the value of the parameter box_line_stipple (main part).

`stipple` : | a pattern for line stipple in OpenGL.
Returns : | TRUE if `visu_glExt_box_draw()` should be called.

### visu_glExt_box_setExpandStipple ()

    gboolean            visu_glExt_box_setExpandStipple     (guint16 stipple);

Method used to change the value of the parameter box_line_stipple (expanded part).

`stipple` : | a pattern for line stipple in OpenGL.
Returns : | TRUE if `visu_glExt_box_draw()` should be called.

### visu_glExt_box_getRGBValues ()

    float*              visu_glExt_box_getRGBValues         ();

Read the colour components of box (in [0;1]).

Returns : | all the colour values of the current box line.

### visu_glExt_box_getOn ()

    int                 visu_glExt_box_getOn                ();

Read if the box is drawn or not.

Returns : | 1 if a box is drawn, 0 otherwise.

### visu_glExt_box_getLineWidth ()

    float               visu_glExt_box_getLineWidth         ();

Read the line width used for box.

Returns : | the value of current box line width.

### visu_glExt_box_getLineStipple ()

    guint16             visu_glExt_box_getLineStipple       ();

Read the line stipple pattern used for box (main part).

Returns : | the value of current box line pattern.

### visu_glExt_box_getExpandStipple ()

    guint16             visu_glExt_box_getExpandStipple     ();

Read the line stipple pattern used for box (expanded part).

Returns : | the value of current box line pattern.

### visu_glExt_box_draw ()

    void                visu_glExt_box_draw                 (VisuData *data);

This method create a compile list that draw a box for the given `data`.

`data` : | a VisuData object.

### visu_glExt_box_draw_legend ()

    void                visu_glExt_box_draw_legend          (VisuData *dataObj);

Draw a legend giving the different box lengths.

`dataObj` : | the VisuData defining the box.

### visu_glExt_box_getShowLegend ()

    gboolean            visu_glExt_box_getShowLegend        ();

The box extension can draw a frame showing the lengths of the box.

Returns : | TRUE if the frame is displayed.

Since 3.6

### visu_glExt_box_setShowLegend ()

    gboolean            visu_glExt_box_setShowLegend        (gboolean value);

Draw or not the lengths near the axis.

`value` : | a boolean.
Returns : | TRUE if status changed.