NCL Website header
NCL Home > Documentation > HLUs > API

NhlRemoveOverlay

The Fortran name of this function is NhlFRemoveOverlay.

This function removes an overlay plot member from a base plot.


C Synopsis

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

NhlErrorTypes NhlRemoveOverlay(
	        int		base_id,
		int		overlay_id,
		NhlBoolean	restore
		)

Fortran Synopsis

      subroutine NhlFRemoveOverlay(base_id, overlay_id, restore, ierr)
      integer base_id, overlay_id, restore, ierr

Arguments

base_id (input)
Identifies the base plot from which the overlay is to be removed.
overlay_id (input)
Identifies the overlay plot member to be removed. If plot_id is equal to base_id all overlays are restored to their previous status as Transform objects.
restore (input)
If this boolean value is True, and the overlay was originally an plot object with overlays of its own, the overlay is restored to its original condition along with all its overlay member plots. Otherwise, its overlays remain behind with the base plot. Annotations belonging to the plot object are always restored.
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 remove an overlay from a base plot. If the overlay was originally itself a base plot, you can choose to restore any overlays that originally belonged to it, or leave them behind with the base plot identified by the base_id parameter. Note that annotations belonging to the plot object are always returned to it.

If base_id and plot_id are the same, the effect of this function is to remove all the overlays from the base plot. In this case, the restore parameter has no effect. All plot objects are restored to their original state before being added to the base plot.


Return Values

The NhlRemoveOverlay function returns a value of type NhlErrorTypes, and the NhlFRemoveOverlay Fortran subroutine returns the error value in ierr. The following table indicates what the various return Error Values mean:
Value	|			Meaning
--------+-------------------------------------------------
NOERROR	|	overlay successfully removed from the 
	|	base plot.
--------+-------------------------------------------------
INFO	|	minor recoverable error.
--------+-------------------------------------------------
WARNING	|	recoverable error - the base_id may not
	|	have referred to a base plot object, or 
	|       the plot_id may not currently be an overlay.
--------+-------------------------------------------------
FATAL	|	the base_id or plot_id may not be valid object
	!       ids, or a system-level error has occurred.


See Also