Function CDM_AddAnnotation
|
|
|
|
Description:
This function will add the given Annotation (specified by the "Ann"
parameter) into the Document specified by the "Document" parameter.
If the Annotation does not already have an Id, a new unique Id will be
assigned to that Annotation and the Annotation will be added to the
current Annotation set of the Document. If the Annotation already has an Id, then this Id will left intact.
If an Annotation with the same Id already exists in the current
Annotation set, then the new Annotation will replace the old one. If
an Annotation with the same Id does not exist, the given Annotation will
be appended to the existing Annotation set.
This function will add the given Annotation (specified by the "Ann"
parameter) into the Annotation set specified by the "Set" parameter.
This function (unlike CDM_AddAnnotation for Documents) will not
modify in any way the Id of the provided Annotation: it is the
responsibility of the caller to set a proper Id to the provided
Annotation. The Annotation object will be appended to the Annotation
set even if it does not have an Id (Id = -1). This function will simply append the provided Annotation object to the
provided Annotation set. It will not check if an Annotation with the
same Id already exists in order to replace it, as CDM_AddAnnotation
will do when it is applied on a Document object.
Return Value:
This function returns the Id of the Annotation that was added to the
specified Document object. Whether the Annotation had or had not an Id
makes no difference to the returned value. Note that after using this
function, CDM will keep a reference to the given Annotation. This will
transform the given Annotation into a shared
object, that cannot be manipulated any more by the caller. Always
remember that an attempt to modify a shared object will abort the
execution of the whole platform. If the caller wants to modify a shared
object, the following steps must be followed:
A check should be made in order to find if an object is shared
or not, by using the Tcl function Tcl_IsShared.
If the object is not shared (i.e. Tcl_IsShared returns an
integer value < 2), the object can be safely modified.
If the object is shared, a new copy of the object must be
created by using the Tcl function Tcl_DuplicateObj. The new object will
be an exact copy of the original one but it will not be shared. The
returned object can be safely modified. In case of an error the return value will be -1 and
an error message describing the error will be left at the current Tcl
interpreter (CDM_Interp).
This function will create and return a new AnnotationSet object (of
type CDM_AnnotationSet) that will contain all elements of the provided
through the "Set" parameter set (with exactly the same order) plus the
provided Annotation object. CDM does not own the returned
object: the caller is responsible to use Tcl_DecrRefCount or CDM_Free
in order to free the object and the memory associated with it.
In case of an error, NULL will be return and an error message will be
left at the current active Tcl interpreter (CDM_Interp).
Notes:
This function is equivelant to tip_AddAnnotation (Tcl API). This function is equivelant to tip_AddAnnotation (Tcl API).
See Also:
Tcl_IsShared,
Tcl_DuplicateObj,
tip_AddAnnotation CDM_Free, Tcl_DecrRefCount,
tip_AddAnnotation
Generated by: petasis@aias on Wed Aug 16 10:31:57 PM EEST 2006.