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
- NhlSetValues function
- NhlGetValues function
- NhlAddAnnotation function
- NhlRemoveAnnotation function
- PlotManager object