Creating Multi-Line Titles/Annotations in iTools

Note: IDL 8.x has now introduced a new set of graphical functions, based on iTools, that are more flexible and easy to use. For the case explained below, the new graphics functions make is very easy to implement programatically. We recommend the user to experiment with those new graphic functions as well.  

Topic
Although it is documented in the "iTools User Guide" pdf file (itooluserguide.pdf) that comes with the IDL distribution, it is probably a little-known fact to most users that iTools annotations - in any font - can be set to be multiline. This is thanks to the observance of all iTools fonts of "embedded text formatting commands." This Help Article shows the syntax for creating two-line text annotations, as well as the use of a few other embedded formatting commands.

Discussion
iTools is implemented with a choice of five fonts. Four are TrueType fonts and the fifth is the Hershey font set best known to IDL Direct Graphics programmers. IDL's 'embedded formatting commands' have particular significance for Hershey font users, who sometimes need these to select which of the dozen Hershey font sets they want their text to be draw in. In iTools TrueType font users can not use the embedded formatting commands that change a font table. However, all of the other formatting commands are observed by all four built-in TrueType fonts. This then allows a relatively simple syntax to insert in an annotation or title string a newline/carriage return, an ASCII character that is not on the standard English keyboard, a footnote reference, a subscript, an exponent, and more.

The full set of options for embedded formatting commands is shown in the Online Help topic "Embedded Formatting Commands" (accessible via index topic 'format codes -> embedded in IDL strings'). If you read that section closely, you will see how Hershey fonts provide the widest range of possibilities for annotating an iTool, because they give access to tables of math symbol characters that the TrueType fonts do not have. The example below, however, shows how some of the most popular embedded formatting command tokens can be applied to iTools' default TrueType Helvetica font. The explanation for the syntax shown is as follows:

• !C - inserts a newline/carriage return.

• !Z(E5) - draws the character with hexadecimal value 0xE5. In Helvetica that is the Swedish lower case 'a' with circle. (If you know only the decimal value of the character, in this case 229, then IDL can show you the hexadecimal equivalent with this call: IDL> print, 229, FORMAT='(Z)'. On Windows, the 'Start -> Accessories -> System Tools ->Character Map' can help you find the hexadecimal values of your iTools TrueType font.)

• !E - draws the character(s) that follow in the style of an exponent or, as demonstrated below, a footnote reference.

The batch commands below try to show a practical IPLOT call where multiline labels, extended Western European characters and footnoting are called for. Try the code below by copying and pasting into your IDL DE:

; Make up some declining plot data with noise
depth = indgen(12) * 12 + 1
temp = reverse(findgen(12) + 4) + randomu(seed, 12)
; Title with Swedish characters and a footnote reference
plotTitle = 'Lake Temperatures!CStor-Bl!Z(E5) Sj!Z(F6)n!E3'
yTitle = 'Temperature!C(!Z(B0)C)'
xTitle = 'Depth!C(m)'
iplot, depth, temp, XRANGE=[0,144], YRANGE=[0,30], XTICKINTERVAL=24.0, $
    VIEW_TITLE=plotTitle, XTITLE=xTitle, YTITLE=yTitle