Function tip_AddAnnotation
|
|
Prototype: | tip_AddAnnotation(Document);
|
---|
Arguments: | Document: A Document object. (CDM_Document) Ann: The Annotation to be added. (CDM_Annotation)
|
---|
|
|
Prototype: | tip_AddAnnotation(Annotation);
|
---|
Arguments: | Document: A Document object. (CDM_Document) Ann: The Annotation to be added. (CDM_Annotation)
|
---|
|
|
Description:
tip_AddAnnotation(Document): |
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.
tip_AddAnnotation(Annotation): |
Return Value:
tip_AddAnnotation(Document): |
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).
tip_AddAnnotation(Annotation): |
Notes:
tip_AddAnnotation(Document): |
This function is equivelant to CDM_AddAnnotation (C++ API). Warning:
This function modifies the given Annotation, if
MODIFY_SHARED_OBJECTS is defined during compilation of CDM!
(Note that it is not totally safe to enable this option!
This option is disabled by default.)
We decided to offer this option (to modify the Annotation instead of
creating a copy and modify the copy), in order to be more memory
efficient, as annotation numbers tend to get really large...
tip_AddAnnotation(Annotation): |
See Also:
tip_AddAnnotation(Document): |
Tcl_IsShared, Tcl_DuplicateObj, tip_AddAnnotation tip_AddAnnotation(Annotation): |
Generated by: petasis@aias on Wed Aug 16 10:31:45 PM EEST 2006.