Function CDM_AddAnnotation


Definition:#include <CDM.h>
Prototype:long CDM_AddAnnotation(CDM_Document Document, CDM_Annotation Ann);
Arguments:

Document: A Document object. (CDM_Document)
Ann: The Annotation to be added. (CDM_Annotation)


Prototype:CDM_AnnotationSet CDM_AddAnnotation(CDM_AnnotationSet Set, CDM_Annotation Ann);
Arguments:

Set: Annotation Set. (CDM_AnnotationSet)
Ann: Annotation. (CDM_Annotation)

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

Description:

long CDM_AddAnnotation(CDM_Document Document, CDM_Annotation Ann):
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.

CDM_AnnotationSet CDM_AddAnnotation(CDM_AnnotationSet Set, CDM_Annotation Ann):
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:

long CDM_AddAnnotation(CDM_Document Document, CDM_Annotation Ann):
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).

    CDM_AnnotationSet CDM_AddAnnotation(CDM_AnnotationSet Set, CDM_Annotation Ann):
    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:

    long CDM_AddAnnotation(CDM_Document Document, CDM_Annotation Ann):
    This function is equivelant to tip_AddAnnotation (Tcl API).

    CDM_AnnotationSet CDM_AddAnnotation(CDM_AnnotationSet Set, CDM_Annotation Ann):
    This function is equivelant to tip_AddAnnotation (Tcl API).

    See Also:

    long CDM_AddAnnotation(CDM_Document Document, CDM_Annotation Ann):
    Tcl_IsShared, Tcl_DuplicateObj, tip_AddAnnotation

    CDM_AnnotationSet CDM_AddAnnotation(CDM_AnnotationSet Set, CDM_Annotation Ann):
    CDM_Free, Tcl_DecrRefCount, tip_AddAnnotation


    Generated by: petasis@aias on Wed Aug 16 10:31:57 PM EEST 2006.