IDLgrLegend

The IDLgrLegend object provides a simple interface for displaying a legend. 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. The glyph itself can be in one of two types (see the TYPE keyword). In line type, the glyph is a line segment with linestyle, thickness and color attributes and an optional symbol object drawn over it. In fill type, the glyph is a square patch drawn with color and optional pattern object attributes.

An IDLgrLegend object is an atomic graphic object ; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects.

This object class is implemented in the IDL language. Its source code can be found in the file idlgrlegend.pro in the lib subdirectory of the IDL distribution.

Superclasses

This class is a subclass of IDLgrModel

Subclasses

This class has no subclasses.

Creation

See IDLgrLegend::Init

Methods

Intrinsic Methods

This class has the following methods:

Inherited Methods

This class inherits the following methods:


IDLgrLegend::Cleanup

The IDLgrLegend:: Cleanup procedure method performs all cleanup on the object. IDLgrLegend is described above.

Calling Sequence

OBJ_DESTROY, Obj

or

Obj -> [IDLgrLegend::] Cleanup                               ( In a subclass' Cleanup method only .)

Arguments

There are no arguments for this method.

Keywords

There are no keywords for this method.


IDLgrLegend::ComputeDimensions

The IDLgrLegend:: ComputeDimensions function method retrieves the dimensions of a legend object for the given destination object. The result is a three-element floating-point vector [ xDim , yDim , zDim ] representing the dimensions of the legend object measured in data units. IDLgrLegend is described above.

Calling Sequence

Obj -> [IDLgrLegend::] ComputeDimensions( DestinationObj )

Arguments

DestinationObject

The object reference to a destination object (IDLgrBuffer, IDLgrClipboard, IDLgrPrinter, or IDLgrWindow) for which the dimensions of the legend are being requested.

Keywords

There are no keywords for this method.


IDLgrLegend::GetProperty

The IDLgrLegend:: GetProperty procedure method retrieves the value of a property or group of properties for the legend. IDLgrLegend is described above.

Calling Sequence

Obj -> [IDLgrLegend::] GetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrLegend::Init

ALL

Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object.

PARENT

Set this keyword to a named variable that will contain an object reference to the object that contains this legend.

XRANGE

Set this keyword to a named variable that will contain a two-element vector of the form [ xmin , xmax ] specifying the range of the X data coordinates covered by the legend.

YRANGE

Set this keyword to a named variable that will contain a two-element vector of the form [ ymin , ymax ] specifying the range of the Y data coordinates covered by the legend.

ZRANGE

Set this keyword to a named variable that will contain a two-element vector of the form [ zmin , zmax ] specifying the range of the Z data coordinates covered by the legend.


IDLgrLegend::Init

The IDLgrLegend:: Init function method initializes the legend object. IDLgrLegend is described above.

Calling Sequence

Obj = OBJ_NEW('IDLgrLegend')

or

Result = Obj -> [IDLgrLegend::] Init( [aItemNames] )         ( In a subclass' Init method only .)

Arguments

aItemNames

An array of strings to be used as the displayed item label. The length of this 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 the number of items (as defined by the ITEM_NAME array) exceeds any of the attribute vectors, the attribute defaults will be used for any additional items.

Keywords

Properties retrievable via IDLgrLegend::GetProperty

BORDER_GAP (Get, Set)

Set this keyword to a floating-point value to indicate the amount of blank space to be placed around the outside of the glyphs and text items. The units for this property are fractions of the legend label font height. The default is 0.1 (10% of the label font height).

COLUMNS (Get, Set)

Set this keyword to an integer value to indicate the number of columns the legend items should be displayed in. The default is one column.

FILL_COLOR (Get, Set)

Set this keyword to the color to be used to fill the legend background box. The color may be specified as a color lookup table index or as an RGB vector. The default is [255,255,255].

FONT (Get, Set)

Set this keyword to an instance of an IDLgrFont object class to describe the font to use to draw the legend labels. The default is 12 point Helvetica.

GAP (Get, Set)

Set this keyword to a floating-point value to indicate the amount of blank space to be placed vertically between each legend item. The units for this keyword are fractions of the legend label font height. The default is 0.1 (10% of the label font height). The same gap is placed horizontally between the legend glyph and the legend text string.

GLYPH_WIDTH (Get, Set)

Set this keyword to a floating-point value to indicate the width of the glyphs, measured as a fraction of the font height. The default is 0.8 (80% of the font height).

HIDE (Get, Set)

Set this keyword to a boolean value to indicate whether this object should be drawn:

ITEM_COLOR (Get, Set)

Set this keyword to an array of colors defining the color of each item. The array defines M different colors, and should be either of the form [3, M ] or [ M ]. In the first case, the three values are used as an RGB triplet, in the second case, the single value is used as a color index value. The default color is [0,0,0].

ITEM_LINESTYLE (Get, Set)

Set this keyword to an array of integers defining the style of the line to be drawn if the TYPE property is set to zero. The array can be of the form [ M ] or [2, M ]. The first form selects the linestyle for each legend item from the predefined defaults:

The second form specifies the stippling pattern explicitly for each legend item (see IDLgrPolyline::Init LINESTYLE keyword for details).

ITEM_NAME (Get, Set)

Set this keyword to an array of strings. Specifying this keyword is the same as providing the aName argument for the IDLgrLegend::Init method.

ITEM_OBJECT (Get, Set)

Set this keyword to an array of object references of type IDLgrSymbol or IDLgrPattern. A symbol object is drawn only if the TYPE property is set to zero. A pattern object is used when drawing the color patch if the TYPE property is set to one. The default object is the NULL object.

ITEM_THICK (Get, Set)

Set this keyword to an array of integers which define the thickness of each item line, in pixels. This property is only used if the TYPE property is set to zero. The default is 1 pixel.

ITEM_TYPE (Get, Set)

Set this keyword to an array of integers which define the type of glyph to be displayed for each item:

NAME (Get, Set)

Set this keyword to a string representing the name to be associated with this object. The default is the null string, ''.

OUTLINE_COLOR (Get, Set)

Set this keyword to the color to be used to draw the legend outline box. The color may be specified as a color lookup table index or as an RGB vector. The default is [0,0,0].

OUTLINE_THICK (Get, Set)

Set this keyword to an integer which defines the thickness of the outline frame. The default is 1 pixel.

SHOW_FILL (Get, Set)

Set this keyword to a boolean value indicating whether the background should be filled with a color:

SHOW_OUTLINE (Get, Set)

Set this keyword to a boolean value indicating whether the outline box should be displayed:

TEXT_COLOR (Get, Set)

Set this keyword to the color to be used to draw the legend item text. The color may be specified as a color lookup table index or as an RGB vector. The default is [0,0,0].

TITLE (Get, Set)

Set this keyword to an instance of the IDLgrText object class to specify the title for the legend. The default is the null object, specifying that no title is drawn. The title will be centered at the top of the legend, even if the text object itself has an associated location.

UVALUE (Get, Set)

Set this keyword to a value of any type. Use this value to contain any information you wish.

XCOORD_CONV (Get, Set)

Set this keyword to a vector, [ s 0 , s 1 ], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows:

Normalized X = s 0 + s 1 * Data X

Recommended values are:

[(- X min )/( X max - X min ), 1/( X max - X min )]

The default is [0.0, 1.0].

YCOORD_CONV (Get, Set)

Set this keyword to a vector, [ s 0 , s 1 ], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows:

Normalized Y = s 0 + s 1 * Data Y

 

 

Recommended values are:

[(- Y min )/( Y max - Y min ), 1/( Y max - Y min )]

The default is [0.0, 1.0].

ZCOORD_CONV (Get, Set)

Set this keyword to a vector, [ s 0 , s 1 ], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows:

Normalized Z = s 0 + s 1 * Data Z

Recommended values are:

[(- Z min )/( Z max - Z min ), 1/( Z max - Z min )]

The default is [0.0, 1.0].


IDLgrLegend::SetProperty

The IDLgrLegend:: SetProperty procedure method sets the value of a property or group of properties for the legend. IDLgrLegend is described above.

Calling Sequence

Obj -> [IDLgrLegend::] SetProperty

Arguments

There are no arguments for this method.

Keywords

Any keyword to IDLgrLegend::Init