NCL Home > Documentation > HLUs > User Guide

AnnoManager class

You can add annotations to any of the plot object classes. These are classes whose name ends with "Plot", as in XyPlot, ContourPlot, or MapPlot. Annotations that you add are called "external annotations", as opposed to the built-in, or "intrinsic", annotations that are automatically available to all plot objects. The remainder of this module refers exclusively to external annotations.

Annotations can be created from any View class object. Thus, an annotation can be a simple TextItem, a LabelBar, a Legend, or even a complex ContourPlot.

The PlotManager is actually responsible for positioning and sizing annotations. However, the AnnoManager object associated with each annotation contains resources that specify how to place and size the annotation.

Why use annotations?

Suppose that, besides the built-in title annotations, you want to associate some additional explanatory text with a plot. You may want to create a TextItem and make it into an annotation of the plot. If the plot is to be drawn repeatedly, an advantage is that the TextItem annotation is drawn automatically each time you draw the plot. Also, whenever the plot object is moved or resized, the size and position of the TextItem is modified proportionally. It is as if the TextItem becomes an integral part of the plot object. On the other hand, if the plot object always maintains its original size, and you are only creating a few View objects, it may not be worth the extra code and overhead required to make the TextItem into an annotation.

Adding annotations to a plot

Once you have created the set of View objects intended to be annotations, there are two ways to add them as annotations of a plot. One is simply to set the array resource pmAnnoViews with an array containing each of the View object ids. The other is to add the annotations implicitly to the pmAnnoViews array, one at a time, by using the function NhlAddAnnotation, as in:

C: 


      anno_manager_id = NhlAddAnnotation(plot_id, view_id);
Fortran: 

      Call NhlFAddAnnotation(plot_id, view_id, anno_manager_id)
where "plot_id" is the identifier of the plot object, "view_id" is the identifier of the annotation object, and "anno_manager_id" is a returned identifier of the AnnoManager object that is created to manage the annotation.

For example, say you have created a MapPlot object whose identifier is "mapid". You want to add a TextItem annotation, so you create an object whose identifier is "textid". You then add the TextItem as an annotation of the MapPlot using NhlAddAnnotation. A Fortran code segment would look like this: 

C
C  Create a plot object with the identifier mapid.
C
      call NhlFRLClear(rlist)
      call NhlFCreate(mapid,'Map0',NhlFMapPlotClass,wid,rlist,ierr)
C
C  Create a TextItem with identifier, textid.
C
      call NhlFRLClear(rlist)
      call NhlFRLSetstring(rlist,'txString',text,ierr)
      call NhlFCreate(textid,'Text0',NhlFtextitemClass,wid,rlist,ierr)
C
C  Add the TextItem to the MapPlot object as an annotation.
C
      call NhlFAddAnnotation(mapid,textid,annoid)

Alternately, you can use pmAnnoViews directly: 

C
C  Create the TextItem with identifier, textid.
C
      call NhlFRLClear(rlist)
      call NhlFRLSetstring(rlist,'txString',text,ierr)
      call NhlFCreate(textid,'Text0',NhlFtextitemClass,wid,rlist,ierr)
C
C  Create the plot object, mapid, and assign textid to pmAnnoViews.
C
      call NhlFRLClear(rlist)
      call NhlFRLSetintegerarray(rlist,'pmAnnoViews',textid,1,ierr)
      call NhlFCreate(mapid,'Map0',NhlFMapPlotClass,wid,rlist,ierr)

Data-tracking annotations

By default, annotations are positioned and sized relative to the plot viewport. However, it is also possible to place the annotations relative to data coordinate space. For example, consider the case of a series of MapPlot frames that, when animated, shows a rotating globe. Suppose you want to label a number of world cities on this rotating globe.

In this situation, you would first need to create a TextItem for each label and set the txString resource to the name of the city. Then you would make the TextItem objects into a set of annotations that are positioned relative to the lat-lon coordinate system used as the data coordinates of MapPlot. To do this, you would set to True the amTrackData resource of each AnnoManager object created to manage the TextItem annotations. At the same time, you would set each of the AnnoManager objects' amDataXF and amDataYF resources to the longitude and latitude, respectively, of each city.

The ng4ex examples mp04c.c (C), and mp04f.f (Fortran), demonstrate this data-tracking process.

Removing or disabling annotations

Annotations can be removed from pmAnnoViews using the function NhlRemoveAnnotations (C), NhlFRemoveAnnotations (Fortran), or can simply be disabled by setting the AnnoManager resource amOn to False.

See also: