NCL Website header
NCL Home > Documentation > HLUs > Classes

AnnoManager class

The AnnoManager class allows an arbitrary user-created View object to be managed as an annotation of a plot object.

Synopsis

Header File:		ncarg/hlu/AnnoManager.h
Class Name:		annoManagerClass
Class Pointer:		<Not Referenceable>
Fortran Class Function:	<Not Referenceable>
Super-Class:		Obj
Composite-Classes:	<None>

Resources

Local resources

+---------------------------------------------------------------+
|			AnnoManager Resource Set		|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| amOn                          NhlTBoolean             RCSG    |
|       AmOn                            True                    |
|---------------------------------------------------------------|
| amViewId                      NhlTObjId               CG      |
|       AmViewId                        <dynamic>               |
|---------------------------------------------------------------|
| amResizeNotify                NhlTBoolean             RCSG    |
|       AmResizeNotify                  False                   |
|---------------------------------------------------------------|
| amTrackData                   NhlTBoolean             RCSG    |
|       AmTrackData                     False                   |
|---------------------------------------------------------------|
| amZone                        NhlTInteger             RCSG    |
|       AmZone                          0                       |
|---------------------------------------------------------------|
| amSide                        NhlTPosition            RCSG    |
|       AmSide                          Bottom                  |
|---------------------------------------------------------------|
| amOrthogonalPosF              NhlTFloat               RCSG    |
|       AmOrthogonalPosF                0.0                     |
|---------------------------------------------------------------|
| amParallelPosF                NhlTFloat               RCSG    |
|       AmParallelPosF                  0.0                     |
|---------------------------------------------------------------|
| amJust                        NhlTJustification       RCSG    |
|       AmJust                          CenterCenter            |
|---------------------------------------------------------------|
| amDataXF                      NhlTFloat               RCSG    |
|       AmDataXF                        0.0                     |
|---------------------------------------------------------------|
| amDataYF                      NhlTFloat               RCSG    |
|       AmDataYF                        0.0                     |
+---------------------------------------------------------------+

Composite resources

The AnnoManager object class has no composite class resources.

Superclass resources

There are no resources defined by the superclass of the AnnoManager object class.


Description

AnnoManager objects allow you to treat arbitrary user-created View objects as annotations of a plot object. The resources provided by the AnnoManager allow these external annotations to be manipulated in a very similar manner to the intrinsic annotations provided by the PlotManager, or the embedded annotations supplied by certain Transform subclasses.

You may turn any View object, from a simple TextItem to a plot object with plot members of its own, into an annotation. As a user, you do not create AnnoManager objects directly. You only need to create the views you wish to have managed as annotations. When you inform a plot object about these views, it will create a separate AnnoManager object to manage each of them.

When you draw a plot object, any of its external annotations whose AnnoManager resource amOn is set True are automatically drawn as well. Using the resources of the AnnoManager object, you set the location and usually the size of the View annotation relative to the viewport or the data coordinate space of its base plot. Then whenever the base plot changes size and/or location the annotation adjusts itself appropriately.

Adding annotations to a plot

There are two ways to add View objects as annotations to a plot object. You can make a group of View objects into annotations by setting the PlotManager resource pmAnnoViews with an array containing the ids of the View objects. Or you can add a single view to the existing set of annotations by calling the function NhlAddAnnotation. The view must belong to the same Workstation as the plot object to which it is added.

NhlAddAnnotation returns the id of a newly created AnnoManager whose resources you can set to control the view as an annotation. Alternatively, you can retrieve the ids of all current AnnoManager objects at once by getting the value of the array resource pmAnnoManagers. Each element of pmAnnoManagers contains the id of the AnnoManager object used to manage the view specified by the corresponding element of pmAnnoViews. Finally, you can also determine the AnnoManager id currently associated with any particular view by getting the value of the read-only View resource vpAnnoManagerId. If the view is not currently functioning as an annotation, the value of this resource will be NullObjId (0).

Setting pmAnnoViews removes any previously established annotations, although if a View object id in the array to be set matches an id in the existing array, the PlotManager does not destroy the corresponding AnnoManager object. It may, however, rearrange its position in the pmAnnoManagers array, based on the order of the new pmAnnoViews array. In contrast, when you call NhlAddAnnotation, the ids of the View and its new AnnoManager are simply appended to the ends of the pmAnnoViews and pmAnnoManagers arrays.

You can add an annotation to a plot object even if the plot object is currently an overlay or an annotation itself. If the plot object is an overlay, the overlay's base plot assumes responsibility for its for its annotations. This means that the annotations belonging to the overlay are positioned with respect to the base plot just as if they belonged to the base plot itself. However, if the plot object is itself an annotation it acts as a subordinate base plot and manages any annotations added to it with respect to its own viewport.

Removing annotations from a plot

You may remove an annotation from a plot either by setting pmAnnoViews with a different set of View object ids, or one at a time by calling the function NhlRemoveAnnotation. When an annotation is removed, the plot object deletes the View object id from pmAnnoViews and the AnnoManager object id from pmAnnoManagers, and destroys the AnnoManager object. However, note that you are responsible for destroying the View object when you are finished with it. If you destroy a View object that is currently functioning as an annotation, it will remove itself from the plot object to which it belongs before it goes away.

Positioning annotations

There are two distinct ways to position annotation items: in NDC space or in data coordinate space. When the resource amTrackData is set False, the base plot sets the position in NDC space following the PlotManager Location Control Model. In this case, the base plot uses the resources amZone, amSide, amParallelPosF, amOrthogonalPosF and amJust, in conjunction with its knowledge of its viewport and the location and size of all the other associated annotations to determine the location of the annotation. If amTrackData is True, the base plot uses the resources amDataXF, amDataYF, and amJust, along with its knowledge of the current data transformation in order to set the location. If the resource amResizeNotify is set True, the base plot also adjusts the view size of the annotation proportionally to changes in the size of its viewport.

Restrictions on use of View annotations

While a View object is functioning as an external annotation, you cannot draw it directly. It can only be drawn as a consequence of drawing the primary base plot of which it is a plot member.

Likewise, you cannot change the workstation of an external annotation directly. However, when you change the workstation of the primary base plot, the annotation's workstation changes along with it.

The annotation can belong only to one plot object. Attempts to call either NhlAddAnnotation or NhlAddOverlay using the id of any View object currently functioning as an external annotation will result in an error.


Support functions

The support functions used to manipulate AnnoManager objects are defined by the Transform object.

Status


See also