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)

C++ API Sections
Tcl API Sections
Description
Return Value
Notes
See Also
Index

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.