Chapter 11:
Annotation Functions
 

The annotation functions provide control for annotation objects

 

AnodeHdl2ID(); Convert Annotation Node Handle to Annotation ID

 

AnodeID2DetRef(); Convert Annotation Node ID to a Detection Reference

 

AnodeID2ZLayer(); Annotation Node ID -to- Z-Layer Conversion

 

Bring2Front(); Bring Selection List to Front

 

BringForward(); Bring Selection List Forward

 

CreateAnode(); Create an Annotation Node

 

CreatePictureAnode(); Create Picture Annotation Node

 

DetRef2AnodeID(); Detection Node Reference-to-Annotation Node ID conversion

 

DrawAllAnodes(); Draw all annotation nodes

 

DrawAnAnode(); Draw an annotation node

 

Duplicate(); Duplicate all annotation nodes

 

FreeAllAnodes(); Free All Annotation Nodes

 

GetAnnotationText(); Get Annotation Text

 

GetAnodeFromTextboxID(); Get Annotation Node from Text Box ID

 

GetRectAnodeInfo(); Get Rectangle Annotation Node Information

 

ID2AnodeHdl(); Annotation Node ID -to- Annotation Node Handle Conversion

 

IsAnode(); Is the object in at detection record an annotation node?

 

SelectAnode_AddItem(); Select Annotation Node Add Item to Selection List

 

SelectAnode_All(); Select All Annotation Nodes in Selection List

 

Send2Back(); Send Selection List to Back

 

SendBackward(); Send Selection List Backward

 

SetAnnotationText(); Set Annotation Text

 

SetRectAnodeInfo(); Set Rectangle Annotation Node Information

 

ZLayer2AnodeID(); Get annotation object ID of a given Z-layer

   

AnodeHdl2ID()

 

This function returns the Annotation Node ID for the Annotation Information Handle specified by the input parameter hNode.

Syntax:

INT16 PUBLIC
AnodeHdl2ID (
     AnodeInfoHdl hNode
);

Input:

hNode: Pointer to an annotation node information handle returned by ID2AnodeHdl()

Return:

INT16

 

Zero = Invalid or non-existent hNode

 

Non-Zero = Annotation Node ID

Example:

InsertAnode(pGraph, hNode);
anodeID = AnodeHdl2ID(hNode);
if (pSelList!=0L)
{
     pItem = SelectAnode_AddItem(pGraph,
          pSelList, anodeID);
     Select_CalcHandlesItem(pDE, pItem);
}

Also See:

ID2AnodeHdl()

   

AnodeID2DetRef()

 

This function sets pDetRef to the detection node reference associated with the annotation object identified by anodeID.

Syntax:

void PUBLIC
AnodeID2DetRef (
     GraphPtr pGraph,
     INT16 anodeID,
     DetNodeRefPtr pDetRef
);

Input:

pGraph: Pointer to an graph created by AllocGraphPtr()

 

anodeID: INT16 value of an annotation node ID

 

pDetRef: Pointer to a location to store a detection node reference pointer. Set the DetNodeRef structure in Appendix A.

Return:

None

Also See:

AnodeID2ZLayer()

   

AnodeID2ZLayer()

 

This function returns an INT16 value that identifies the z-layer (front-to-back order) of the annotation object identified by anodeID. In other words, at what layer in the graph does anodeID reside?

Syntax:

INT16 PUBLIC
AnodeID2ZLayer (
     GraphPtr pGraph,
     INT16 anodeID
);

Input:

pGraph: Pointer to an graph created by AllocGraphPtr()

 

anodeID: INT16 value of an annotation node ID

Return:

INT16: Integer z-layer

Also See:

AnodeID2DetRef()

   

Bring2Front()

 

This function sets the Z-layer of all selected objects to the front in the order that they were selected.:

Syntax:

int PUBLIC
Bring2Front (
     GraphPtr pGraph,
     SelListPtr pSelList
);

Input:

pGraph: Pointer to a graph created by AllocGraphPtr()

 

pSelList: Pointer to a selection list allocated by Select_AllocList(). See the SelListRec in Appendix A.

Return:

INT16: The code returned by the engine

 

Value

Description

 

E00_OK

Success

 

E00_MEM_ERROR

Memory Error

 

E00_RANGE_ERROR

Invalid Parameter(s)

Example:

void CGraph::Bring2Front()
{
     ::Bring2Front((GraphPtr) m_pGraph,
      (SelListPtr) m_SelList.GetList());
}
case U_BRING_TO_FRONT:
     pGraph->Bring2Front();
     break;

Also See:

BringForward(), Send2Back(), SendBackward()

   

BringForward()

 

This function sets the Z-layer of all selected objects one step closer to the front

Syntax:

int PUBLIC
BringForward (
     GraphPtr pGraph,
     SelListPtr pSelList
);

Input:

pGraph: Pointer to a graph created by AllocGraphPtr()

 

pSelList: Pointer to a selection list allocated by Select_AllocList(). See the SelListRec in Appendix A.

Return:

INT16: The code returned by the engine

 

Value

Description

 

E00_OK

Success

 

E00_MEM_ERROR

Memory Error

 

E00_RANGE_ERROR

Invalid Parameter(s)

Example:

void CGraph::BringForward()
{
     ::BringForward((GraphPtr) m_pGraph,
      (SelListPtr) m_SelList.GetList());
}
case U_BRING_FORWARD:
     pGraph->BringForward();
     break;

Also See:

Bring2Front(), Send2Back(), SendBackward()

CreateAnode()

 

This function calls the annotation engine to create an annotation object of the specified type (aType).

Syntax:

INT16 PUBLIC CreateAnode (
     GraphPtr pGraph,
     INT16 aType,
     Rect FAR * bounds,
     MEMHDL hText,
     _PolyHandle hPoly,
     WedgeInfoPtr pWedge,
     Point startPt,
     Point endPt
);

Input:

pGraph: Pointer to a graph object created by AllocGraphPtr()

 

aType: The type of annotation node to create. It can be any one of the OAN_... objects (e.g., OAN_POLYGON, OAN_POLYLINE, OAN_FREEHAND, etc.)

 

bounds: Pointer to a rectangle data structure where the boundaries of the annotation object are stored.

 

hText: If aType is OAN_TEXTBOX, pointer to a buffer where the text for the OAN_TEXTBOX object is stored.

 

hPoly: A polygon handle created by the AllocPolyHandle() function

 

pWedge: Pointer to a wedge information data structure. See the WedgeInfoRec in Appendix A.

 

startPt: Pointer to a Point data structure that identifies the starting location of the annotation object.

 

endPt: Pointer to a Point data structure that identifies the ending location of the annotation object.

Return:

INT16; NULL = error/annotation node not created, Non-Zero = Annotation Node ID

Example:

INT16 anodeID;
INT16 objType = OAN_RECTANGLE;
anodeID = CreateAnode ( gpGraph, objType,
     &aRect,hText, ghPoly,&thisWedge, p0, p1);

Also See:

CreatePictureAnode(), DrawAllAnodes(), DrawAnAnode(),
FreeAllAnodes()

CreatePictureAnode()

 

This function creates a rectangle annotation object with a picture special effect inside the rectangle.

Syntax:

INT16 PUBLIC
CreatePictureAnode (
     GraphPtr pGraph,     
     DrawEnvPtr pDE,
     INT16 x,
     INT16 y,
     char *szPictName,
     INT32 hdl,
     INT16 xExt,
     INT16 yExt,
     Rect *bounds,
     INT16 *pResized
);

Input:

pGraph: Pointer to a graph object created by AllocGraphPtr()

 

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

x/y: Location to create rectangle

 

szPictName: File name of picture to be applied to rectangle

 

hdl: Handle of opened file containing the picture

 

xExt/yExt: Size of picture

 

bounds: Place to store the location of the created rectangle.

 

pResized: On return, will be set to TRUE if picture was resized to fit in the rectangle.

Return:

INT16: annotation object ID

Also See:

CreateAnode(), DrawAllAnodes(), DrawAnAnode(), FreeAllAnodes()

DetRef2AnodeID()

 

This function returns the ID of the annotation node associated with the specified detection node reference (pDetRef).

Syntax:

INT16 PUBLIC
DetRef2AnodeID (
     DetNodeRefPtr pDetRef
);

Input:

pDetRef: Detection Node Reference Pointer. See the DetNodeRef structure in Appendix A.

Return:

INT16

 

-1 = invalid detection node reference pointer

 

Non-Zero = Annotation Node ID

Also See:

AnodeID2DetRef()

   

DrawAllAnodes()

 

This function draws the entire annotation layer for given graph (pGraph) and draw environment (pDE).

Syntax:

INT16 PUBLIC
DrawAllAnodes (
     DrawEnvPtr pDE,
     GraphPtr pGraph
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pGraph: A graph pointer allocated by AllocGraphPtr()

Return:

INT16

 

E00_OK =

No Errors

 

E00_RANGE_ERROR =

Failure

Also See:

CreateAnode(), DrawAnAnode()

DrawAnAnode()

 

This function draws a single annotation node (anodeID) in the graph (pGraph).

Syntax:

INT16 PUBLIC
DrawAnAnode (
     DrawEnvPtr pDE,
     GraphPtr pGraph,
     INT16 anodeID
);

Input:

pDe: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pGraph: A graph pointer allocated by AllocGraphPtr()

 

anodeID: Annotation node ID

Return:

INT16

 

E00_OK =

No Errors

 

E00_RANGE_ERROR =

Failure

Also See:

CreateAnode(), DrawAllAnodes()

   

Duplicate()

 

This function creates a duplicate copy of all annotation nodes in a selection list (pSelList).

Syntax:

INT16 PUBLIC
Duplicate (
     DrawEnvPtr pDE,
     GraphPtr pGraph,
     SelListPtr pSelList
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pGraph: A graph pointer created by AllocGraphPtr()

 

pSelList: Point to a selection list allocated by Select_AllocList(). See the SelListRec in Appendix A.

Return:

INT16: Zero

   

FreeAllAnodes()

 

This function frees all annotation memory associated with the graph identified by pGraph. It de-allocates all anodes in the annotation layer.

Syntax:

void PUBLIC
FreeAllAnodes (
     GraphPtr pGraph
);

Input:

pGraph: A graph pointer allocated by AllocGraphPtr()

Return:

None

Example:

//If data1 is negative,
//remove all annotation objs.
if(*(INT16 *)pData < 0)
{
     FreeAllAnodes(pGraph);
     FreeDetListHandle(
     &pGraph->Layer[ANNOTATION_LAYER].hDetList);
}

Also See:

DrawAllAnodes()

   

GetAnnotationText()

 

This function gets the ASCII-Text String of an existing Text-Annotation. It copies the current annotation text into the string pointed to by pText. It will copy up to nLength bytes. If pText is NULL, the function will return the length of the current annotation text (including the NULL byte at the end of string) into *pnLength.:

Syntax:

INT16 PUBLIC
GetAnnotationText (
     GraphPtr pGraph,
     INT16 anodeID,
     char FAR * pText,
     INT16 FAR *pnLength
);

Input:

pGraph: A graph pointer allocated by AllocGraphPtr()

 

anodeID: INT16 value of an Annotation Node ID

 

pText: Pointer to location to store ASCII string

 

pnLength: Length of string

Return:

INT16:

 

Value

Description

 

Zero =

Successful

 

Non-Zero =

Failure

Example:

/* If pString = NULL,
function returns string length only */
GetAnnotationText(gpGraph, gTextAnodeID,
      (char FAR *) NULL, &nLength);
//Get Length of String;
/* If we pass a string ptr,
function will copy annotation string
into szNewText (up to nLength chars
will be copied) */
GetAnnotationText(gpGraph, gTextAnodeID,
     szNewText,&nLength);// Get String
if (nLength < 35)
     strcat(szNewText," Also");
SetAnnotationText(gpGraph, gpDrawEnv,
     gTextAnodeID,
     szNewText); // Set String

Also See:

SetAnnotationText()

   

GetAnodeFromTextboxID()

 

This function returns an annotation node information handle for the text box ID identified by nBox. It returns NULL if nBox is not defined in an annotation information structure in pGraph.

Syntax:

AnodeInfoHdl PUBLIC GetAnodeFromTextboxID (
     GraphPtr pGraph,
     INT16 nBox
);

Input:

pGraph: A graph pointer allocated by AllocGraphPtr()

 

nBox: Series number of text box

Return:

AnodeInfoHdl: Annotation node information handle or NULL

Example:

if(pCurr->nObjectID == OTX_BOX_ANNOTATION)
{
     FreeAnode(pGraph,
     GetAnodeFromTextboxID(pGraph,
          pCurr->nSeriesID));
     FreeDetNode(&pCurr->refDetNode);
}

Also See:

ChangeXanTextboxID(), IsObjectATextBox()

   

GetRectAnodeInfo()

 

This function sets the x,y coordinates at bounds to the location/size of the annotation object identified by anodeID.

Syntax:

INT16 PUBLIC GetRectAnodeInfo (
     GraphPtr pGraph,
     INT16 anodeID,
     Rect *bounds
);

Input:

pGraph: Pointer to a Graph created by AllocGraphPtr()

 

anodeID: INT16 value of an Annotation Node ID

 

bounds: Pointer to a rectangle data structure. See the rect structure in Appendix A.

Return:

INT16 = 0

Example:

anodeID = AnodeHdl2ID (pSelItem->data.hAnode);
GetRectAnodeInfo (pGraph, anodeID, &rcVirt );

Also See:

SetRectAnodeInfo()

ID2AnodeHdl()

 

This function returns the AnodeInfoHdl for the given anodeID or NULL if there is none.

Syntax:

AnodeInfoHdl PUBLIC
ID2AnodeHdl (
     GraphPtr gPtr,
     INT16 anodeID
);

Input:

gPtr: Graph Point

 

anodeID: Annotation ID

Return:

AnodeInfoHdl: Non-Zero = Handle to an annotation information data structure or NULL if there is none.

Also See:

AnodeHdl2ID()

   

IsAnode()

 

This function returns a value indicating whether or not the object defined at pDetNode is an annotation object.

Syntax:

BOOLEAN16 PUBLIC
IsAnode (
     DetNodePtr pDetNode
);

Input:

pDetNode: Pointer to a detection node record. See the DetNodeRec structure in Appendix A.

Return:

BOOLEAN16: TRUE/FALSE

 

TRUE=

object is an annotation object

 

FALSE=

object is not an annotation object

Example:

DetNodePtr pDetNode;
pDetNode = LockDetNodeRef(pDetRef);
XorDetNode(pDE, pDetNode);
if (IsAnode(pDetNode))
     XOrRect(pBounds);
UnlockDetNodeRef(pDetRef);

Also See:

AnodeHdl2ID(), AnodeID2DetRef(), AnodeID2ZLayer()

   

SelectAnode_AddItem()

 

This function adds a new selection item record (SelItemRec) to the Selection List identified by pSelList. It is used for Annotations only! This will add an invalid annotation object BEFORE it has a detection node (DetNode). Select_RebuildList() should be called SOON after SelectAnode_AddItem() as part of a redraw.

Syntax:

SelItemPtr PUBLIC
SelectAnode_AddItem (
     GraphPtr pGraph,
     SelListPtr pSelList,
     INT16 anodeID
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

pSelList: Pointer to a selection list allocated by Select_AllocList(). See the SelListRec in Appendix A.

 

anodeID: ID of the annotation node to be added to the selection list

Return:

SelItemPtr; Pointer to a selection item if successful. NULL if error.

Also See:

SelectAnode_All()

   

SelectAnode_All()

 

This function adds all annotations objects from the given graph (pGraph) to the selection list identified by pSelList.

Syntax:

INT16 PUBLIC
SelectAnode_All (
     GraphPtr pGraph,
     SelListPtr pSelList
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

pSelList: Pointer to a selection list allocated by Select_AllocList(). See the SelListRec in Appendix A.

Return:

INT16: Number of items selected.

Also See:

SelectAnode_AddItem()

   

Send2Back()

 

This function sets the Z-layer of all selected objects to the back in the order selected.

Syntax:

int PUBLIC
Send2Back (
     GraphPtr pGraph,
     SelListPtr pSelList
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

pSelList: Pointer to a selection list. See the SelListRec in Appendix A.

Return:

INT:

 

Possible Values

Description

 

E00_OK =

Successful

 

Any other value =

Error

Example:

void CGraph::Send2Back()
{
     ::Send2Back((GraphPtr) m_pGraph,
      (SelListPtr) m_SelList.GetList());
}
case U_SEND_TO_BACK:
pGraph->Send2Back();
break;

Also See:

Bring2Front(), BringForward(), SendBackward()

SendBackward()

 

This function sets the Z-layer of all selected objects one step closer to the back.

Syntax:

int PUBLIC
SendBackward (
     GraphPtr pGraph,
     SelListPtr pSelList
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

pSelList: Pointer to a selection list. See the SelListRec in Appendix A.

Return:

INT: Standard Error Code. See Appendix B.

 

Possible Values

Description

 

E00_OK =

Successful

 

Any other value =

Error

Example:

void CGraph::SendBackward()
{
     ::SendBackward((GraphPtr) m_pGraph,
      (SelListPtr) m_SelList.GetList());
}
case U_SEND_BACKWARD:
pGraph->SendBackward();
break;

Also See:

Bring2Front(), BringForward(), Send2Back()

SetAnnotationText()

 

This function assigns the ASCII-Text String at psNewText to an existing text-annotation object identified by anodeID.

Syntax:

INT16 PUBLIC
SetAnnotationText (
     GraphPtr pGraph,
     DrawEnvPtr pDE,
     INT16 anodeID,
     char FAR * psNewText
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

pDE: Pointer to a draw environment

 

anodeID: INT16 value of an Annotation Node ID

 

psNewText: Pointer to ASCII Text String

Return:

INT16:

 

Possible Values

Description

 

0 =

Successful

 

NON-ZERO =

Error

Example:

/* If pString = NULL,
function returns string length only */
GetAnnotationText(gpGraph, gTextAnodeID,
      (char FAR *) NULL, &nLength);
//Get Length of String;
/* If we pass a string ptr,
function will copy annotation string
into szNewText (up to nLength chars
will be copied) */
GetAnnotationText(gpGraph, gTextAnodeID,
     szNewText,&nLength);// Get String
if (nLength < 35)
     strcat(szNewText," Also");
SetAnnotationText(gpGraph, gpDrawEnv,
     gTextAnodeID,
     szNewText); // Set String

Also See:

GetAnnotationText()

   

SetRectAnodeInfo

 

Given the detection node reference of an annotation object (anodeID), this function creates a temporary selection list with that annotation object in it and sets the AAN_BOUNDS attribute of the object.

Syntax:

void PUBLIC
SetRectAnodeInfo (
     GraphPtr pGraph,
     INT16 anodeID,
     Rect *bounds
);

Input:

pGraph: A graph pointer allocated by AllocGraphPtr()

 

anodeID: ID of an annotation node

 

bounds: Bounds of rectangle

Return:

None

Also See:

GetRectAnodeInfo()

   

ZLayer2AnodeID()

 

This function returns the Anode ID for the annotation object of a given Z-layer.

Syntax:

INT16 PUBLIC
ZLayer2AnodeID (
     GraphPtr pGraph,
     INT16 zLayer
);

Input:

pGraph: Pointer to the graph object created by AllocGraphPtr()

 

zLayer: Z-Layer number

Return:

INT16: value of an annotation node ID

Also See:

AnodeID2ZLayer()