## Scale

Scale — Draw an arrow with a label.

## Synopsis

                        Scale;
    #define             MASK_XYZ_ALL
    #define             MASK_XYZ_X
    #define             MASK_XYZ_Y
    #define             MASK_XYZ_Z

    Scale*              scaleNew                            (float origin[3],
                                                             float orientation[3],
                                                             float length,
                                                             const gchar *legend);
    float               scaleGet_length                     (Scale *scale);
    float*              scaleGet_orientation                (Scale *scale);
    float*              scaleGet_origin                     (Scale *scale);
    const gchar*        scaleGet_legend                     (Scale *scale);
    gboolean            scaleSet_legend                     (Scale *scale,
                                                             const gchar *value);
    gboolean            scaleSet_length                     (Scale *scale,
                                                             float lg);
    gboolean            scaleSet_orientation                (Scale *scale,
                                                             float xyz[3],
                                                             int mask);
    gboolean            scaleSet_origin                     (Scale *scale,
                                                             float xyz[3],
                                                             int mask);

    void                scalesDraw                          (VisuData *dataObj);
    gboolean            scalesGet_areOn                     ();
    float               scalesGet_defaultLineWidth          ();
    float*              scalesGet_defaultRGBColor           ();
    guint16             scalesGet_defaultStipple            ();
    GList*              scalesGet_scales                    ();
    gboolean            scalesSet_areOn                     (gboolean value);
    gboolean            scalesSet_defaultLineWidth          (float width);
    gboolean            scalesSet_defaultRGBValues          (float rgba[4],
                                                             int mask);
    gboolean            scalesSet_defaultStipple            (guint16 stipple);

## Description

This little extension is used to draw an arrow at a given position displaying a given length.

## Details

### Scale

    typedef struct _Scale Scale;

All fields are private, use the access routines.

### MASK_XYZ_ALL

    #define MASK_XYZ_ALL (7)

This value can be used to create a mask for methods that require one for reading xyz coordinates array. This value is a shortcut for MASK_XYZ_X | MASK_XYZ_Y | MASK_XYZ_Z.

### MASK_XYZ_X

    #define MASK_XYZ_X (1 << 0)

This value can be used to create a mask for methods that require one for reading xyz coordinates array. This value actually correspond to the x direction.

### MASK_XYZ_Y

    #define MASK_XYZ_Y (1 << 1)

This value can be used to create a mask for methods that require one for reading xyz coordinates array. This value actually correspond to the y direction.

### MASK_XYZ_Z

    #define MASK_XYZ_Z (1 << 2)

This value can be used to create a mask for methods that require one for reading xyz coordinates array. This value actually correspond to the z direction.

### scaleNew ()

    Scale*              scaleNew                            (float origin[3],
                                                             float orientation[3],
                                                             float length,
                                                             const gchar *legend);

Create a new arrow pointing somewhere in the box with a label. If `legend` is NULL, then the label will be the value of the length.

`origin` : | the origin ;
`orientation` : | the orientation in cartesian coordinates ;
`length` : | the length of the arrow ;
`legend` : | the text going with the arrow (can be NULL).
Returns : | a newly created Scale object.

### scaleGet_length ()

    float               scaleGet_length                     (Scale *scale);

A Scale is characterised by its length.

`scale` : | the Scale to poll.
Returns : | a positive floating point value.

### scaleGet_orientation ()

    float*              scaleGet_orientation                (Scale *scale);

A Scale is characterised by its orientation in cartesian coordinates.

`scale` : | the Scale to poll.
Returns : | three floating point values.

### scaleGet_origin ()

    float*              scaleGet_origin                     (Scale *scale);

A Scale is characterised by its origin in cartesian coordinates.

`scale` : | the Scale to poll.
Returns : | three floating point values.

### scaleGet_legend ()

    const gchar*        scaleGet_legend                     (Scale *scale);

A Scale can have a legend. This is not actualy the string printed on screen but the one used to generate it.

`scale` : | the Scale to poll.
Returns : | a string (private, do not free it).

### scaleSet_legend ()

    gboolean            scaleSet_legend                     (Scale *scale,
                                                             const gchar *value);

Routine that changes the legend of the scale. If `value` is NULL then the length of the scale is printed.

`scale` : | the Scale to modify ;
`value` : | a string (can be NULL).
Returns : | TRUE if `scalesDraw()` should be called.

### scaleSet_length ()

    gboolean            scaleSet_length                     (Scale *scale,
                                                             float lg);

Routine that changes the length of the scale.

`scale` : | the Scale to modify ;
`lg` : | a positive length.
Returns : | TRUE if `scalesDraw()` should be called.

### scaleSet_orientation ()

    gboolean            scaleSet_orientation                (Scale *scale,
                                                             float xyz[3],
                                                             int mask);

Routine that changes the direction of the scale.

`scale` : | the Scale to modify ;
`xyz` : | a vector in cartesian coordinates ;
`mask` : | relevant values in `xyz`.
Returns : | TRUE if `scalesDraw()` should be called.

### scaleSet_origin ()

    gboolean            scaleSet_origin                     (Scale *scale,
                                                             float xyz[3],
                                                             int mask);

Routine that changes the origin of the scale.

`scale` : | the Scale to modify ;
`xyz` : | a vector in cartesian coordinates ;
`mask` : | relevant values in `xyz`.
Returns : | TRUE if `scalesDraw()` should be called.

### scalesDraw ()

    void                scalesDraw                          (VisuData *dataObj);

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

`dataObj` : | the VisuData object to build axes for.

### scalesGet_areOn ()

    gboolean            scalesGet_areOn                     ();

The scales can be turned off or on.

Returns : | TRUE if scale are drawn, FALSE otherwise.

### scalesGet_defaultLineWidth ()

    float               scalesGet_defaultLineWidth          ();

The scales share a line width for the stick of the arrow.

Returns : | the value of current width.

### scalesGet_defaultRGBColor ()

    float*              scalesGet_defaultRGBColor           ();

All the scales shared a common colour.

Returns : | a four component array.

### scalesGet_defaultStipple ()

    guint16             scalesGet_defaultStipple            ();

The scales share a line pattern for the stick of the arrow.

Returns : | the value of current stipple pattern.

### scalesGet_scales ()

    GList*              scalesGet_scales                    ();

All the available scales can be retrieve with this method.

Returns : | a private GList.

### scalesSet_areOn ()

    gboolean            scalesSet_areOn                     (gboolean value);

Method used to change the value of the parameter Scale_are_on.

`value` : | 1 if a scale must be drawn, 0 otherwise.
Returns : | 1 if `scaleDraw()` should be called. In all cases, 'OpenGLAskForReDraw' signal should then be emitted.

### scalesSet_defaultLineWidth ()

    gboolean            scalesSet_defaultLineWidth          (float width);

Method used to change the value of the parameter scale_line_width. This affects all the drawn scales.

`width` : | value of the desired width.
Returns : | TRUE if `scaleDraw()` should be called and then 'OpenGLAskForReDraw' signal be emitted.

### scalesSet_defaultRGBValues ()

    gboolean            scalesSet_defaultRGBValues          (float rgba[4],
                                                             int mask);

Method used to change the value of the private parameter scales_color. This affects all the drawn scales.

`rgba` : | a four floats array with values (0 <= values <= 1) for the red, the green, the blue and the alpha color. Only values specified by the mask are really relevant.
`mask` : | use MASK_RGB_R, MASK_RGB_G, MASK_RGB_B, MASK_RGB_ALL or a combinaison to indicate what values in the rgb array must be taken into account.
Returns : | TRUE if `scaleDraw()` should be called and then 'OpenGLAskForReDraw' signal be emitted.

### scalesSet_defaultStipple ()

    gboolean            scalesSet_defaultStipple            (guint16 stipple);

The scales share a line pattern for the stick of the arrow.

`stipple` : | a pattern for line.
Returns : | TRUE if scale are drawn, FALSE otherwise.