![]() |
![]() |
![]() |
adg-1 reference manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#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
);
"model" AdgModel* : Read / Write "n-segment" guint : Read / Write "pos" gdouble : Read / Write / Construct "size" gdouble : Read / Write "trail" AdgTrail* : Read / Write / Construct
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.
struct AdgMarker;
All fields are privates and should not be used directly. Use its public methods instead.
Since 1.0
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.
abstract virtual method that creates a model template for all the markers used by this class. |
Since 1.0
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()
.
|
an AdgMarker |
|
the new trail to use |
Since 1.0
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.
|
an AdgMarker |
Returns : |
the requested trail or NULL on errors. [transfer none]
|
Since 1.0
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.
|
an AdgMarker |
|
the new segment index |
Since 1.0
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.
|
an AdgMarker |
Returns : |
an index greather than 0 on success or 0 on errors |
Since 1.0
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.
Since 1.0
const CpmlSegment * adg_marker_get_segment (AdgMarker *marker
);
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.
|
an AdgMarker |
Returns : |
the segment or NULL on errors |
Since 1.0
void adg_marker_backup_segment (AdgMarker *marker
);
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.
|
an AdgMarker |
Since 1.0
const CpmlSegment * adg_marker_get_backup_segment (AdgMarker *marker
);
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.
|
an AdgMarker |
Returns : |
the original segment or NULL on errors |
Since 1.0
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.
|
an AdgMarker |
|
the new pos |
Since 1.0
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.
|
an AdgMarker |
Returns : |
the marker position |
Since 1.0
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.
|
an AdgMarker |
|
the new size |
Since 1.0
gdouble adg_marker_get_size (AdgMarker *marker
);
Gets the current size of marker
.
|
an AdgMarker |
Returns : |
the marker size, in global space |
Since 1.0
void adg_marker_set_model (AdgMarker *marker
,AdgModel *model
);
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
.
Since 1.0
AdgModel * adg_marker_get_model (AdgMarker *marker
);
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.
|
an AdgMarker |
Returns : |
the cached model or NULL on errors. [transfer none]
|
Since 1.0
AdgModel * adg_marker_model (AdgMarker *marker
);
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.
|
an AdgMarker |
Returns : |
the current model or NULL on errors. [transfer none]
|
Since 1.0
"model"
property"model" AdgModel* : Read / Write
A general purpose model usable by the marker implementations.
"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
"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
"size"
property "size" gdouble : Read / Write
The size (in global space) of the marker.
Allowed values: >= 0
Default value: 10
"trail"
property"trail" AdgTrail* : Read / Write / Construct
The subject AdgTrail for this marker.