NhlAddOverlay

The Fortran name of this function is NhlFAddOverlay.

This function adds an overlay plot member to a base plot.


C Synopsis

#include <ncarg/hlu/hlu.h>
#include <hfile for Base Plot Object>

NhlErrorTypes NhlAddOverlay(
	        int		base_id,
		int		transform_id,
		int		after_id
		)

Fortran Synopsis

      subroutine NhlFAddOverlay(base_id, transform_id, after_id, ierr)
      integer base_id, transform_id, after_id, ierr

Arguments

base_id (input)
Identifies the plot object to be used as the base plot.
transform_id (input)
Identifies the Transform object to be overlaid on the base plot.
after_id (input)
If the base plot already contains one or more overlays, identifies the existing overlay that the new overlay is to follow in the overlay sequence. A value less than 0 specifies that the new overlay is to be added to the end of the sequence. If the value is the id of the base plot itself, the new overlay is placed just behind the base plot in the sequence.
ierr (output, Fortran only)
Error code.

Types

Type name:		NhlTErrorTypes
Definition:
typedef enum _NhlErrType{
	NhlFATAL	= -4,	/* "FATAL"	*/
	NhlWARNING	= -3,	/* "WARNING"	*/
	NhlINFO		= -2,	/* "INFO"	*/
	NhlNOERROR	= -1	/* "NOERROR"	*/
} NhlErrorTypes;

Description

Use this function to add a transform as an overlay of a base plot. The transform may be either a plot object (with or without plot members of its own) or a simple transform. The transform must have the same Workstation parent as the base plot, and it cannot already be a plot member. The transform becomes a plot member of the base plot. The base plot provides the coordinate transformation and data boundaries that together determine where the data coordinate space belonging to the overlay will appear and how much of it will be visible. In addition, if the transform is a plot object the base plot assumes management responsibilities for the plot object's plot members if it has any.

If the base plot already has overlays, you can place new overlay anywhere in the overlay sequence using the after_id parameter. The overlay sequence determines the basic drawing order for the overlays.

Note that the MapPlot cannot become an overlay, although it can serve as a base plot. Attempts to overlay an object of the MapPlot class results in an error.


Return Values

The NhlAddOverlay C function returns a value of type NhlErrorTypes, and the NhlFAddOverlay Fortran subroutine returns the error value in ierr. The following table indicates what the various return Error Values mean:
Value	|			Meaning
--------+-------------------------------------------------
NOERROR	|	Transform object successfully added to 
	|	the base plot
--------+-------------------------------------------------
INFO	|	minor recoverable error
--------+-------------------------------------------------
WARNING	|	recoverable error - transform object added 
        |	to the base plot but something was
	|      	was specified incorrectly.
--------+-------------------------------------------------
FATAL	|	The transform could not be added to the 
        |	base plot.


See Also


Copyright

Copyright 1987-1999 University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.

NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?


$Revision: 1.12 $ $Date: 1998/06/15 21:26:02 $