Synopsis

#include <adg-1/adg.h>

struct              AdgMarker;
struct              AdgMarkerClass;
void                adg_marker_set_trail                (AdgMarker *marker,
                                                         AdgTrail *trail);
AdgTrail *          adg_marker_get_trail                (AdgMarker *marker);
void                adg_marker_set_n_segment            (AdgMarker *marker,
                                                         guint n_segment);
guint               adg_marker_get_n_segment            (AdgMarker *marker);
void                adg_marker_set_segment              (AdgMarker *marker,
                                                         AdgTrail *trail,
                                                         guint n_segment);
const CpmlSegment * adg_marker_get_segment              (AdgMarker *marker);
void                adg_marker_backup_segment           (AdgMarker *marker);
const CpmlSegment * adg_marker_get_backup_segment       (AdgMarker *marker);
void                adg_marker_set_pos                  (AdgMarker *marker,
                                                         gdouble pos);
gdouble             adg_marker_get_pos                  (AdgMarker *marker);
void                adg_marker_set_size                 (AdgMarker *marker,
                                                         gdouble size);
gdouble             adg_marker_get_size                 (AdgMarker *marker);
void                adg_marker_set_model                (AdgMarker *marker,
                                                         AdgModel *model);
AdgModel *          adg_marker_get_model                (AdgMarker *marker);
AdgModel *          adg_marker_model                    (AdgMarker *marker);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----AdgEntity
               +----AdgMarker
                     +----AdgArrow

Properties

  "model"                    AdgModel*             : Read / Write
  "n-segment"                guint                 : Read / Write
  "pos"                      gdouble               : Read / Write / Construct
  "size"                     gdouble               : Read / Write
  "trail"                    AdgTrail*             : Read / Write / Construct

Description

A marker is an entity to be applied at the start or end of a segment. Typical examples include arrows, ticks, dots and so on.

The "trail" and "n-segment" properties specify the segment where the marker should be applied. Similarly to the AdgStroke type, if the associated trail is destroyed the above properties are unset.

The local map is used internally to align the marker to the trail end, so adg_entity_set_local_map() and friends is reserved. Therefore, if the trail is modified and the marker had no way to know it, you should call adg_entity_local_changed() to update the marker position.

Use adg_marker_set_pos() to select the position where the marker should be put: 0 means the start point of the segment while 1 means the end point.

The "model" property and APIs are intended only for marker implementation purposes.

Details

struct AdgMarker

struct AdgMarker;

All fields are privates and should not be used directly. Use its public methods instead.

Since 1.0


struct AdgMarkerClass

struct AdgMarkerClass {
    /* Virtual table */
    AdgModel *          (*create_model)         (AdgMarker      *marker);
};

The create_model method must be implemented by any AdgMarker derived classes. The derived classes are expected to apply a single model (the one returned by this method) to every path endings by using different transformations.

create_model ()

abstract virtual method that creates a model template for all the markers used by this class.

Since 1.0


adg_marker_set_trail ()

void                adg_marker_set_trail                (AdgMarker *marker,
                                                         AdgTrail *trail);

Sets the "trail" property to trail. It is allowed to pass NULL to clear the current trail.

This method could fail unexpectedly if the segment index specified by the "n-segment" property is not present inside the new segment: if you want to set a new segment it is more convenient to change both properties ("trail" and "n-segment") at once with adg_marker_set_segment().

marker :

an AdgMarker

trail :

the new trail to use

Since 1.0


adg_marker_get_trail ()

AdgTrail *          adg_marker_get_trail                (AdgMarker *marker);

Gets the trail where this marker should be applied. The returned object is owned by marker and should not be freed or modified.

marker :

an AdgMarker

Returns :

the requested trail or NULL on errors. [transfer none]

Since 1.0


adg_marker_set_n_segment ()

void                adg_marker_set_n_segment            (AdgMarker *marker,
                                                         guint n_segment);

Sets the "n-segment" property to n_segment. The trail is unchanged. If you want to set both properties at once (as usually requested to refer to a specific segment), adg_marker_set_segment() should be more convenient.

marker :

an AdgMarker

n_segment :

the new segment index

Since 1.0


adg_marker_get_n_segment ()

guint               adg_marker_get_n_segment            (AdgMarker *marker);

Returns the segment of the associated trail where this marker will be applied, where 1 is the first segment.

marker :

an AdgMarker

Returns :

an index greather than 0 on success or 0 on errors

Since 1.0


adg_marker_set_segment ()

void                adg_marker_set_segment              (AdgMarker *marker,
                                                         AdgTrail *trail,
                                                         guint n_segment);

Sets a new segment where the marker should be applied at once. A dependency between trail and marker is added, so when trail changes marker is invalidated.

A callback is added to "remove-dependency" so manually removing the dependency (such as when trail is destroyed) will unlink marker from it.

marker :

an AdgMarker

trail :

the AdgTrail

n_segment :

a segment index

Since 1.0


adg_marker_get_segment ()

const CpmlSegment * adg_marker_get_segment              (AdgMarker *marker);

Note

This function is only useful in marker implementations.

Gets the segment where the marker will be applied. This segment is eventually a modified version of the backup segment, after having applied the marker.

marker :

an AdgMarker

Returns :

the segment or NULL on errors

Since 1.0


adg_marker_backup_segment ()

void                adg_marker_backup_segment           (AdgMarker *marker);

Note

This function is only useful in marker implementations.

Duplicates the current subject segment for backup purpose: this segment can be accessed by adg_marker_get_backup_segment(). Obviously, a current segment should exist (either the "trail" and "n-segment" properties must be properly defined) or this method will fail without further processing.

When the subject segment is changed (either by changing "trail" or "n-segment") the original segment is automatically restored.

marker :

an AdgMarker

Since 1.0


adg_marker_get_backup_segment ()

const CpmlSegment * adg_marker_get_backup_segment       (AdgMarker *marker);

Note

This function is only useful in marker implementations.

Gets the original segment where the marker has been applied. Applying a marker could modify the underlying trail, usually by trimming the original segment of a "size" dependent length from the ends. The marker instance holds a copy of the original segment, generated by adg_marker_backup_segment(), to be used in recomputation, for example when the marker changes its size.

When the subject segment is changed (either by changing "trail" or "n-segment") the original segment is automatically restored.

marker :

an AdgMarker

Returns :

the original segment or NULL on errors

Since 1.0


adg_marker_set_pos ()

void                adg_marker_set_pos                  (AdgMarker *marker,
                                                         gdouble pos);

Sets a new position on marker. Check out adg_marker_get_pos() for details on what pos represents.

marker :

an AdgMarker

pos :

the new pos

Since 1.0


adg_marker_get_pos ()

gdouble             adg_marker_get_pos                  (AdgMarker *marker);

Gets the current position of marker. The returned value is a ratio position referred to the segment associated to marker: 0 means the start point and 1 means the end point of the segment.

marker :

an AdgMarker

Returns :

the marker position

Since 1.0


adg_marker_set_size ()

void                adg_marker_set_size                 (AdgMarker *marker,
                                                         gdouble size);

Sets a new size on marker. The size is an implementation-dependent property: it has meaning only when used by an AdgMarker derived type.

marker :

an AdgMarker

size :

the new size

Since 1.0


adg_marker_get_size ()

gdouble             adg_marker_get_size                 (AdgMarker *marker);

Gets the current size of marker.

marker :

an AdgMarker

Returns :

the marker size, in global space

Since 1.0


adg_marker_set_model ()

void                adg_marker_set_model                (AdgMarker *marker,
                                                         AdgModel *model);

Note

This function is only useful in marker implementations.

Sets a new model for marker. The reference to the old model (if an old model was present) is dropped while a new reference is added to model.

marker :

an AdgMarker

model :

a new AdgModel

Since 1.0


adg_marker_get_model ()

AdgModel *          adg_marker_get_model                (AdgMarker *marker);

Note

This function is only useful in marker implementations.

Gets the current model of marker. This is an accessor method: if you need to get the model for rendering, use adg_marker_model() instead. The returned object is owned by marker and should not be freed or modified.

marker :

an AdgMarker

Returns :

the cached model or NULL on errors. [transfer none]

Since 1.0


adg_marker_model ()

AdgModel *          adg_marker_model                    (AdgMarker *marker);

Note

This function is only useful in marker implementations.

Gets the model of marker. If the model is not found, it is automatically created by calling the create_model() virtual method. The returned object is owned by marker and should not be freed or modified.

marker :

an AdgMarker

Returns :

the current model or NULL on errors. [transfer none]

Since 1.0

Property Details

The "model" property

  "model"                    AdgModel*             : Read / Write

A general purpose model usable by the marker implementations.


The "n-segment" property

  "n-segment"                guint                 : Read / Write

The segment on trail where this marker should be applied (where 0 means undefined segment, 1 the first segment and so on).

Default value: 0


The "pos" property

  "pos"                      gdouble               : Read / Write / Construct

The position ratio inside the segment where to put the marker (0 means the start point while 1 means the end point).

Allowed values: [0,1]

Default value: 0


The "size" property

  "size"                     gdouble               : Read / Write

The size (in global space) of the marker.

Allowed values: >= 0

Default value: 10


The "trail" property

  "trail"                    AdgTrail*             : Read / Write / Construct

The subject AdgTrail for this marker.