NCL Home > Documentation > Graphics > Graphical Interfaces

gsn_add_text

Attaches text strings to the given plot.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"  ; This library is automatically loaded
                                                          ; from NCL V6.2.0 onward.
                                                          ; No need for user to explicitly load.

	function gsn_add_text (
		wks  [1] : graphic,  
		plot [1] : graphic,  
		text     : string,   
		x        : numeric,  
		y        : numeric,  
		res  [1] : logical   
	)

	return_val [dimsizes(text)] :  graphic

Arguments

wks

A Workstation identifier. The identifier is one returned either from calling gsn_open_wks or calling create to create a Workstation object.

plot

A plot identifier created by using one of the many gsn functions, or by calling create to create a View object.

text

A array of text strings to attach to plot.

x
y

Arrays of the same size as text containing the X and Y coordinates of the text strings, and must be in the range of the X/Y coordinates of the data in plot. If you are adding the text to a map, then X should correspond to longitude values, and Y to latitude values.

res

A variable containing an optional list of text resources, attached as attributes. Set to True if you want the attached attributes to be applied, and False if you either don't have any resources to set, or you don't want the resources applied.

Return value

An array of the same size as text representing the ids of the text strings will be returned.

Description

This function attaches a list of text strings to the given plot. The text strings will be drawn only when the plot is drawn. If a missing value is encountered in the text strings or x/y values, then no text string will be drawn at this pair. A bug was fixed in NCL V6.5.0 in which missing text strings were showing up in the plot as the missing string.

There are many fonts available, and you can use the txFont resource to change the font.

If you resize the plot (i.e. by passing the plot to gsn_panel), then the text strings will be automatically resized with the plot.

If you call this function multiple times to attach several text strings to a plot, each return value must be assigned to a unique variable.

Examples

For an application example, see:

"conwomap_3.ncl" (view example)