Legend Objects
Legend objects provide a simple interface for displaying legends. The legend itself consists of a (filled and/or framed) box around one or more legend items (arranged in a single column) and an optional title string. Each legend item consists of a glyph patch positioned to the left of a text string. The glyph patch is drawn in a square which is a fraction of the legend label font height.
Creating Legend Objects
To create a legend object, you must provide an array of item names, along with arrays of symbols, line styles, or objects, along with arrays of attributes (such as color or thickness) for the items. The following simple example creates a legend object with two items. The first item (Cows) is represented by the predefined symbol number four (a diamond), and the second item (Weasels) is represented by a line-filled box.
itemNameArr = ['Cows', 'Weasels'] mytitle = OBJ_NEW('IDLgrText', 'My Legend') mysymbol = OBJ_NEW('IDLgrSymbol', 4) mypattern = OBJ_NEW('IDLgrPattern', 1) myLegend = OBJ_NEW('IDLgrLegend', itemNameArr, TITLE=mytitle, $ ITEM_TYPE=[0,1], ITEM_OBJECT=[mysymbol, mypattern], $ /SHOW_OUTLINE)
See "IDLgrLegend" (IDL Reference Guide) for details on creating legend objects. See the next section for a more detailed explanation of the elements of the legend.
Using Legend Objects
The legend object allows you to define the annotations that correspond to the array of strings used as legend names in a variety of ways. The length of the argument string array is used to determine the number of items to be displayed. Each item is defined by taking one element from the ITEM_NAME, ITEM_TYPE, ITEM_LINESTYLE, ITEM_THICK, ITEM_COLOR, and ITEM_OBJECT vectors, if they are defined. If the number of items (as defined by the argument array or the ITEM_NAME array) exceeds any of the attribute vectors, the attribute defaults will be used for any additional items.
Specify a list of item names either via the argument to IDLgrLegend::Init, or via the ITEM_NAME property. The length of this array determines the size of the legend.
Use the ITEM_TYPE property to define whether an element in the legend is represented by a line (with an optional plotting symbol) or by a filled or unfilled box. There should be one element of the ITEM_TYPE array per element in the input array or ITEM_NAME array.
Use the ITEM_LINESTYLE and ITEM_THICK properties to define the style and thickness of lines used as legend items. These arrays are ignored for elements that are not lines. Use the ITEM_COLOR property to specify the color of each legend element independently.
Use the ITEM_OBJECT property to specify that a graphic object be used as an annotation.
Dimensions
Until the legend is drawn to the destination object, the [XYZ]RANGE properties will be zero. Because you must know the size of the legend object in order to scale it properly for your window, you must use the ComputeDimensions method on the legend object to get the data dimensions of the legend prior to a draw operation.
The following example builds and displays a three-element legend.
; Create a window, view, and model: mywindow = OBJ_NEW('IDLgrWindow') myview = OBJ_NEW('IDLgrView') mymodel = OBJ_NEW('IDLgrModel') myview->Add, mymodel ; Create the legend with two items: itemNameArr = ['Original Data', 'Histogram Plot', $ 'Boxcar-filtered (Width=5)'] mytitle = OBJ_NEW('IDLgrText', 'Plot Legend') mysymbol = OBJ_NEW('IDLgrSymbol', 5, SIZE=[0.3, 0.3]) myLegend = OBJ_NEW('IDLgrLegend', itemNameArr, TITLE=mytitle, $ BORDER_GAP=0.8, GAP=0.5, $ ITEM_TYPE=[0,1], ITEM_LINESTYLE=[0,4,2], $ ITEM_OBJECT=[mysymbol, OBJ_NEW(), OBJ_NEW()], $ GLYPH_WIDTH=2.0, /SHOW_OUTLINE) ; Add the legend to the model: mymodel->Add, mylegend ; Center the legend in the window. ; Note that you must use the ComputeDimensions method ; to get the dimensions of the legend. dims = mylegend->ComputeDimensions(mywindow) mymodel->Translate, -(dims[0]/2.), -(dims[1]/2.), 0 ; Draw the legend: mywindow->Draw, myview
