Gwy3DLabels

Gwy3DLabels — Labels in 3D view

Synopsis




            Gwy3DLabelDescription;
enum        Gwy3DLabelName;
            Gwy3DLabels;
            Gwy3DLabelsClass;
Gwy3DLabels* gwy_3d_labels_new              (GwyContainer *container);
void        gwy_3d_labels_update            (Gwy3DLabels *labels,
                                             GwySIUnit *si_unit);
void        gwy_3d_labels_update_with_units (Gwy3DLabels *labels,
                                             GwySIUnit *si_unit_xy,
                                             GwySIUnit *si_unit_z);
gchar*      gwy_3d_labels_expand_text       (Gwy3DLabels *labels,
                                             Gwy3DLabelName label_name);
Gwy3DLabelDescription* gwy_3d_labels_get_description
                                            (Gwy3DLabels *gwy3dlabels,
                                             Gwy3DLabelName label_name);
void        gwy_3d_label_description_set_text
                                            (Gwy3DLabelDescription *label_description,
                                             const gchar *text);
void        gwy_3d_label_description_reset  (Gwy3DLabelDescription *label_description);
gboolean    gwy_3d_label_description_get_autoscale
                                            (Gwy3DLabelDescription *label_description);
void        gwy_3d_label_description_set_autoscale
                                            (Gwy3DLabelDescription *label_description,
                                             const gboolean autoscale);
#define     gwy_3d_labels_get_delta_x       (labels, name)
#define     gwy_3d_labels_get_delta_y       (labels, name)
#define     gwy_3d_labels_get_rotation      (labels, name)
#define     gwy_3d_labels_get_size          (labels, name)
gdouble     gwy_3d_labels_user_size         (Gwy3DLabels *labels,
                                             Gwy3DLabelName name,
                                             gint user_size);

Object Hierarchy


  GObject
   +----Gwy3DLabels

Signals


"label-changed"
            void        user_function      (Gwy3DLabels *gwy3dlabels,
                                            gpointer     user_data)        : Run first / No recursion

Description

The object stores the informations about individual labels taking place within a Gwy3DView. The fields of this class should be considered private. The class provides methods to obtain individual GwyLabelDescription's (gwy_3d_labels_get_description()) and takes care of expanding the variables within text filed of GwyLabelDescriptions (gwy_3d_labels_format_text() method). Currently four variables are implemented and can be used ($X, $Y, $MIN and $MAX). Other variables are ignored.

Details

Gwy3DLabelDescription

typedef struct {
    gchar          * base_key;
    gchar          * default_text;
    gchar          * text;
    gboolean         auto_scale;
    GtkAdjustment  * delta_x;
    GtkAdjustment  * delta_y;
    GtkAdjustment  * rotation;
    GtkAdjustment  * size;
    Gwy3DLabels    * owner;
} Gwy3DLabelDescription;

The structure contains informations about individual labels taking place in the 3DView.

This structure is created and owned by Gwy3DLabes class. Note that some of the fields are considered as private and should not be modified by user. Some other fields have the set methods which should be used instead of direct settings of values. Changes of text, auto_scale, delta_x, delta_x, rotation or size field causes emitting the "label_cghanged" signal.

Since 1.5

gchar *base_key; Path to the node within GwyContainer storing the informations about this LabelDescription. This field should be considered private and should not be modified.
gchar *default_text; Value to which the text would be set after calling gwy_3d_label_description_reset.
gchar *text; Text of the label. May contain names of the variables. Each word beginning with $ is considered to be a variable. Currently following variables can be used: %$X, %$Y, %$MIN and %$MAX. To set the value of text use gwy_3d_label_description_set_text.
gboolean auto_scale; Whether the size of text should be calculated automatically or use the value obtained through size field and gwy_3d_labels_user_size mathod. To obratin this value it is possible to use gwy_3d_label_description_get_autoscale method and to set auto_scale use gwy_3d_label_description_set_autoscale method.
GtkAdjustment *delta_x; Horizontal displacement of the label within 3DView. The label text is moved by delta_x->value pixels from the calculated point.
GtkAdjustment *delta_y; Vertical displacement of the label within 3DView. The label text is moved by delta_y->value pixels from the calculated point.
GtkAdjustment *rotation; Rotation of the label text within 3DView. The rotations are not implemented yet.
GtkAdjustment *size; The size of the label text within 3DView (only if auto_scale == FALSE)
Gwy3DLabels *owner; A pointer to the Gwy3DLabels that created this description. This field should be considered private and should not be modified.

enum Gwy3DLabelName

typedef enum {
    GWY_3D_VIEW_LABEL_X = 0,
    GWY_3D_VIEW_LABEL_Y,
    GWY_3D_VIEW_LABEL_MIN,
    GWY_3D_VIEW_LABEL_MAX
} Gwy3DLabelName;

Identifiers of the labels of the axes within 3D View.

Since 1.5

GWY_3D_VIEW_LABEL_X Identifier of the label describing x-axis
GWY_3D_VIEW_LABEL_Y Identifier of the label describing y-axis
GWY_3D_VIEW_LABEL_MIN Identifier of the label describing minimal z-value
GWY_3D_VIEW_LABEL_MAX Identifier of the label describing maximal z-value

Gwy3DLabels

typedef struct _Gwy3DLabels Gwy3DLabels;


Gwy3DLabelsClass

typedef struct {
    GObjectClass parent_class;

    void (* label_changed) (Gwy3DLabels *labels);

    gpointer reserved1;
    gpointer reserved2;
} Gwy3DLabelsClass;


gwy_3d_labels_new ()

Gwy3DLabels* gwy_3d_labels_new              (GwyContainer *container);

Creates a new 3D label collection object.

container : the settings of the labels are stored in this container
Returns : A new Gwy3DLabels object.

Since 1.5


gwy_3d_labels_update ()

void        gwy_3d_labels_update            (Gwy3DLabels *labels,
                                             GwySIUnit *si_unit);

Warning

gwy_3d_labels_update is deprecated and should not be used in newly-written code.

Updates the 3D labels.

See and use gwy_3d_labels_update_with_units() instead. This function cannot distinguish between lateral and height units.

labels : 3D label collection object
si_unit : SI Unit appended to the numerical values of variables in text field of Gwy3DLabelDescription

Since 1.5


gwy_3d_labels_update_with_units ()

void        gwy_3d_labels_update_with_units (Gwy3DLabels *labels,
                                             GwySIUnit *si_unit_xy,
                                             GwySIUnit *si_unit_z);

Updates the numerical values of the variables in text field of Gwy3DLabelDescription. Also appends the SI unit to this numerical values.

labels : 3D label collection object
si_unit_xy : SI Unit appended to the numerical values of variables in text field of Gwy3DLabelDescription for lateral values.
si_unit_z : SI Unit appended to the numerical values of variables in text field of Gwy3DLabelDescription for height values.

Since 1.16


gwy_3d_labels_expand_text ()

gchar*      gwy_3d_labels_expand_text       (Gwy3DLabels *labels,
                                             Gwy3DLabelName label_name);

Expands the variables within text field of Gwy3DLabelDescription to the numerical values. The LabelDescription is identified by label_name.

labels : a 3D labels collection object.
label_name : identifier of the label
Returns : The text field of Gwy3DLabelDescription after expanding varibles to their numerical values. The returned string should not be modied, freed of referenced. It is freed during next call of this function or during destroying labels.

Since 1.5


gwy_3d_labels_get_description ()

Gwy3DLabelDescription* gwy_3d_labels_get_description
                                            (Gwy3DLabels *gwy3dlabels,
                                             Gwy3DLabelName label_name);

gwy3dlabels : 3D label collection object
label_name : identifier of the label
Returns : a Gwy3DLabelDescription structure identified by name from the gwy3dlabels

Since 1.5


gwy_3d_label_description_set_text ()

void        gwy_3d_label_description_set_text
                                            (Gwy3DLabelDescription *label_description,
                                             const gchar *text);

Sets the text field of label_description to the value of text.

Emits the "label_changed" signal.

label_description : A label desctiption.
text : new value of text field

Since 1.5


gwy_3d_label_description_reset ()

void        gwy_3d_label_description_reset  (Gwy3DLabelDescription *label_description);

Resets the values of the text, delta_x, delta_y, size and rotation fields of label_description to their default vaules. uuto_scale field is set to TRUE.

label_description : A label desctiption.

Since 1.5


gwy_3d_label_description_get_autoscale ()

gboolean    gwy_3d_label_description_get_autoscale
                                            (Gwy3DLabelDescription *label_description);

label_description : A label desctiption.
Returns : value of auto_scale

Since 1.5


gwy_3d_label_description_set_autoscale ()

void        gwy_3d_label_description_set_autoscale
                                            (Gwy3DLabelDescription *label_description,
                                             const gboolean autoscale);

Sets whether use automatically calculated size of label text or whether use value of size->value.

Emits "label_changed" signal.

label_description : A label desctiption.
autoscale : new value of auto_scale field

Since 1.5


gwy_3d_labels_get_delta_x()

#define     gwy_3d_labels_get_delta_x(labels, name)

Gets the value of delta_x displacement (delta_x->value) of the label identified by name.

Since 1.5

labels : a 3D labels collection object
name : identifier of the label

gwy_3d_labels_get_delta_y()

#define     gwy_3d_labels_get_delta_y(labels, name)

Gets the value of delta_y displacement (delta_y->value) of the label identified by name.

Since 1.5

labels : a 3D labels collection object
name : identifier of the label

gwy_3d_labels_get_rotation()

#define     gwy_3d_labels_get_rotation(labels, name)

Gets the value of angle of rotation (rotation->value) of the label identified by name.

Since 1.5

labels : a 3D labels collection object
name : identifier of the label

gwy_3d_labels_get_size()

#define     gwy_3d_labels_get_size(labels, name)

Gets the value of label text size (size->value) of the label identified by name. Does not take auto_scale into account.

Since 1.5

labels : a 3D labels collection object
name : identifier of the label

gwy_3d_labels_user_size ()

gdouble     gwy_3d_labels_user_size         (Gwy3DLabels *labels,
                                             Gwy3DLabelName name,
                                             gint user_size);

According auto_scale decides whether to use user_size or size->value size of the 3D View label text.

labels : a 3D labels collection object
name : identifier of the label
user_size : automatically calculated size of the text
Returns : size of the label text in 3D View

Signal Details

The "label-changed" signal

void        user_function                  (Gwy3DLabels *gwy3dlabels,
                                            gpointer     user_data)        : Run first / No recursion

gwy3dlabels : the object which received the signal.
user_data : user data set when the signal handler was connected.