.\

cglegenditem__define.pro

Graphics

The purpose of this program is to create a simple legend object that can be drawn on a data plot. The user can include any number of legend "items" in the final legend.

Examples

A plot with a simple legend:

   cgDisplay, 800, 450
   cgPlot, cgDemoData(17), PSym=-6, SymColor='red7', Position=[0.15, 0.15, 0.7, 0.9]
   cgOPlot, cgDemoData(17), PSym=-15, SymColor='blu7'
   legendObj = Obj_New('cgLegendItem', SymColor=['red7', 'blu7'], $
       PSym=[6,15], Symsize=1.5, Location=[0.725, 0.9], Titles=['May 27', 'June 27'], $
       Length=0.075, /Box, VSpace=2.75, /Background, BG_Color='rose', /Draw)
   Obj_Destroy, legendObj

Same as the previous example, but in a resizeable graphics window:

   cgWindow, WXSize=800, WYSize=450
   cgPlot, cgDemoData(17), PSym=-6, SymColor='red7', Position=[0.15, 0.15, 0.7, 0.9], /AddCmd
   cgOPlot, cgDemoData(17), PSym=-15, SymColor='blu7', /AddCmd
   legendObj = Obj_New('cgLegendItem', SymColor=['red7', 'blu7'], $
       PSym=[6,15], Symsize=1.5, Location=[0.725, 0.9], Titles=['May 27', 'June 27'], $
       Length=0.075, /Box, VSpace=2.75, /Background, BG_Color='rose', /AddCmd)

Class description for cgLegendItem

Inheritance

IDL_OBJECT

Properties

Properties in cgLegendItem

CHARSIZE get set init
SYMCOLORS get set init
BOX get set init
COLORS get set init
LINESTYLES get set init
BX_COLOR get set init
ADDCMD init
TCOLORS get set init
BX_THICK get set init
SYMTHICK get set init
DRAW init
LENGTH get set init
WINDOW init
TT_FONT get set init
CENTER_SYM get set init
BACKGROUND get set init
VISIBLE get set init
HARDWARE get set init
ALIGNMENT get set init
LOCATION get set init
DATA get set init
TITLES get set init
CHARTHICK get set init
SYMSIZE get set init
THICK get set init
BG_COLOR get set init
VSPACE get set init
PSYMS get set init

Fields

Fields in IDL_OBJECT

IDL_OBJECT_BOTTOM 0LL
__OBJ__ obj_new()
IDL_OBJECT_TOP 0LL

Fields in cgLegendItem

ALIGN_VCENTER 0L
CHARSIZE 0.000000
SYMCOLORS ptr_new()
BOX 0L
ALIGN_BOTTOM 0L
COLORS ptr_new()
ALIGN_RIGHT 0L
LINESTYLES ptr_new()
BX_COLOR ptr_new()
TCOLORS ptr_new()
BX_THICK 0.000000
SYMTHICK 0.000000
LENGTH 0.000000
WID 0L
TT_FONT ptr_new()
CENTER_SYM 0L
BX_POS [0.000000, 0.000000, 0.000000, 0.000000]
ALIGN_HCENTER 0L
BACKGROUND 0L
VISIBLE 0L
HARDWARE 0L
ALIGNMENT 0L
LOCATION [0.000000, 0.000000]
DATA 0L
TITLES ptr_new()
CHARTHICK 0.000000
SYMSIZE ''
THICK 0.000000
BG_COLOR ptr_new()
VSPACE 0.000000
PSYMS ptr_new()
WIDTH ptr_new()

Author information

Author

FANNING SOFTWARE CONSULTING:

  David W. Fanning
  1645 Sheely Drive
  Fort Collins, CO 80526 USA
  Phone: 970-221-0438
  E-mail: david@idlcoyote.com
  Coyote's Guide to IDL Programming: http://www.idlcoyote.com

Copyright

History

Change History:

  Written 18 July 2012. DWF.
  Adapted to accept multiple legend elements. Legend elements are stacked vertically.
     Each legend element can be given its own title, color, symbol symbol color, and
     linestyle. Legend elements are offset  by 1.3*!D.Y_CH_Size/!D.YSize.  A single
     symbol can now be drawn in the center of the line instead of one at each end
     point with the CENTER_SYM keyword. 04/25/2013, Matthew Argall.
  Many changes to make this work like a simple, but useful, legend-drawing program. Now
     called by the wrapper cgLegend. 5 Dec 2013. DWF.
  Several small problems with pointers in the SetProperty method fixed. 10 June 2014. DWF.
  Added CharThick keyword. 1 Sept 2014. DWF.

Routines

result = cgLegendItem::INIT( [/ADDCMD] [, ALIGNMENT=integer] [, /BACKGROUND] [, BG_COLOR=string] [, /BOX] [, BX_COLOR=varies] [, BX_THICK=float] [, /CENTER_SYM] [, CHARSIZE=float] [, CHARTHICK=float] [, COLORS=varies] [, /DATA] [, /DRAW] [, /HARDWARE] [, LENGTH=float] [, LINESTYLES=integer] [, LOCATION=fltarr] [, PSYMS=integer] [, SYMCOLORS=varies] [, SYMSIZE=float] [, SYMTHICK=float] [, TCOLORS=varies] [, THICK=float] [, TITLES=string/strarr] [, TT_FONT=string] [, /VISIBLE] [, VSPACE=float] [, /WINDOW]): This is the initialization method for the object.
cgLegendItem::AddCmd [, /REPLACE] [, METHOD=string] [, /DESTROY_OBJECT]: Adds the object as a command (the DRAW method is called) in a cgWindow resizeable graphics window.
cgLegendItem::CalculateBoxSize: This method calculates the size of the box needed for the legend.
cgLegendItem::Draw: This method draws the legend item or items in a graphics window.
cgLegendItem::GetProperty [, ALIGNMENT=integer] [, /BACKGROUND] [, BG_COLOR=string] [, /BOX] [, BX_COLOR=BX_COLOR] [, BX_THICK=float] [, /CENTER_SYM] [, CHARSIZE=float] [, CHARTHICK=float] [, COLORS=string/strarr] [, /DATA] [, /HARDWARE] [, LENGTH=float] [, LINESTYLES=integer/intarr] [, LOCATION=fltarr] [, PSYMS=integer/intarr] [, SYMCOLORS=string/strarr] [, SYMSIZE=float] [, SYMTHICK=float] [, TCOLORS=string/strarr] [, THICK=float] [, TITLES=string/strarr] [, TT_FONT=string] [, /VISIBLE] [, VSPACE=float]: This method obtains properties from the object.
cgLegendItem::SetProperty, $ [, ALIGNMENT=integer] [, /BACKGROUND] [, BG_COLOR=string] [, /BOX] [, BX_COLOR=varies] [, BX_THICK=float] [, /CENTER_SYM] [, CHARSIZE=float] [, CHARTHICK=float] [, COLORS=string/strarr] [, /DATA] [, /HARDWARE] [, LENGTH=float] [, LINESTYLES=integer/intarr] [, LOCATION=fltarr] [, PSYMS=integer/intarr] [, SYMCOLORS=string/strarr] [, SYMSIZE=float] [, SYMTHICK=float] [, TCOLORS=string/strarr] [, THICK=float] [, TITLES=string/strarr] [, TT_FONT=string] [, /VISIBLE] [, VSPACE=float]: This method sets properties of the object.
cgLegendItem::CLEANUP: This method destroys anything the object uses that retains memory space.
cgLegendItem__Define [, class]: The class definition module for the object.

Routine details

top cgLegendItem::INIT

result = cgLegendItem::INIT( [/ADDCMD] [, ALIGNMENT=integer] [, /BACKGROUND] [, BG_COLOR=string] [, /BOX] [, BX_COLOR=varies] [, BX_THICK=float] [, /CENTER_SYM] [, CHARSIZE=float] [, CHARTHICK=float] [, COLORS=varies] [, /DATA] [, /DRAW] [, /HARDWARE] [, LENGTH=float] [, LINESTYLES=integer] [, LOCATION=fltarr] [, PSYMS=integer] [, SYMCOLORS=varies] [, SYMSIZE=float] [, SYMTHICK=float] [, TCOLORS=varies] [, THICK=float] [, TITLES=string/strarr] [, TT_FONT=string] [, /VISIBLE] [, VSPACE=float] [, /WINDOW])

This is the initialization method for the object. It creates an instance of the object.

Keywords

ADDCMD in optional type=boolean default=0

If this keyword is set, the object is added to the resizeable graphics window, cgWindow. The DRAW method of the object is called in cgWindow.

ALIGNMENT in optional type=integer default=0

This keyword affects the alignment of the legend box with respect to the Location point. There are nine possible values (0 to 8) that assign the location point to be one of the four corners of the legend box, or the middle of one of the four sides of the legend box. The values are specified as follows:

  0 - Location specifies the upper left corner of the legend box.
  1 - Location specifies the upper right corner of the legend box.
  2 - Location specifies the lower right corner of the legend box.
  3 - Location specifies the lower left corner of the legend box.
  4 - Location specifies the top side of the legend box (centered horizontally).
  5 - Location specifies the bottom side of the legend box (centered horizontally).
  6 - Location specifies the left side of the legend box (centered vertically).
  7 - Location specifies the right side of the legend box (centered vertically).
  8 - Location specified the very center of the legend box.

BACKGROUND out optional type=boolean default=0

Set this keyword to draw a colored background for the legend.

BG_COLOR out optional type=string default=white

The name of the background color.

BOX in optional type=boolean default=0

Set this keyword to draw a box around the legend items.

BX_COLOR in optional type=varies default=black

The color of the box drawn around the legend items.

BX_THICK in optional type=float

The thickness of the line used to draw the box around the legend items. If not set, use !P.Thick at drawing time.

CENTER_SYM in optional type=boolean

Set this keyword to place a single symbol in the center of the line. The default is to draw a symbol at each endpoint of the line.

CHARSIZE in optional type=float

The character size for the legend text. Uses cgDefCharsize by default. Ignored if using hardware fonts on the display.

CHARTHICK in optional type=float

The thickness of the legend text. If undefined, use Thick value.

COLORS in optional type=varies default=black

The name of the data color. This is the color of each data line. May be an array.

DATA in optional type=boolean default=0

If set the values specified by the Location keyword are taken to be in data coordinate space.

DRAW in optional type=boolean default=0

Set this keyword to immediately draw the object as soon as it has been initialized.

HARDWARE in optional type=boolean

Set this keyword if you want to output the legend text in a hardware font.

LENGTH in optional type=float default=0.075

The length of the line connecting symbols in the legend, in normalized coordinates (0 to 1 in the graphics window). Set this equal to 0.0 if you wish to only plot symbols in the legend.

LINESTYLES in optional type=integer

The line style for drawing each line. May be an array.

LOCATION in optional type=fltarr

A two-element vector giving the X and Y location of upper-left corner of the legend (or legend box, if the Box keyword is set) in normalized coordinates. If the Data keyword is set, the locations are taken to be in data coordinate space.

PSYMS in optional type=integer

Any normal IDL PSYM values, plus any value supported by the Coyote Library routine cgSYMCAT. An integer between 0 and 46. May be an array.

SYMCOLORS in optional type=varies

The name of the symbol color. By default, the same as the COLOR keyword. May be an array.

SYMSIZE in optional type=float default=1.0

The symbol size.

SYMTHICK in optional type=float

The thickness of the symbol. If not set, use !P.Thick at drawing time.

TCOLORS in optional type=varies default=black

The Title color. May be an array.

THICK in optional type=float

The thickness of the line. If not set, use !P.Thick at drawing time.

TITLES in optional type=string/strarr default=Plot Item

The "title" or text for each legend item.

TT_FONT in optional type=string

The name of a true-type font to use for the legend text.

VISIBLE in optional type=boolean default=1

Set this keyword to determine if the legend should be drawn (visible=1), or if the legend should not be drawn (visible=0).

VSPACE in optional type=float default=1.5

A scale factor for vertical spacing between legend items. This number is multiplied by Charsize to determine vertical spacing.

WINDOW in optional type=boolean default=0

If this keyword is set, the object replaces any commands in a current cgWindow or it opens a new cgWindow and adds itself to it.

top cgLegendItem::AddCmd

cgLegendItem::AddCmd [, /REPLACE] [, METHOD=string] [, /DESTROY_OBJECT]

Adds the object as a command (the DRAW method is called) in a cgWindow resizeable graphics window. If there is no current cgWindow, one is created. The object is destroyed when the cgWindow is destroyed.

Keywords

REPLACE in optional type=boolean default=0: If this keyword is set, object DRAW method replaces any commands in the current graphics window.
METHOD in optional type=string: The object method to add to the cgWindow.
DESTROY_OBJECT in optional type=boolean default=0: Set this keyword to allow the cgWindow to destroy the object when finished with it.

top cgLegendItem::CalculateBoxSize

cgLegendItem::CalculateBoxSize

This method calculates the size of the box needed for the legend.

top cgLegendItem::Draw

cgLegendItem::Draw

This method draws the legend item or items in a graphics window.

top cgLegendItem::GetProperty

cgLegendItem::GetProperty [, ALIGNMENT=integer] [, /BACKGROUND] [, BG_COLOR=string] [, /BOX] [, BX_COLOR=BX_COLOR] [, BX_THICK=float] [, /CENTER_SYM] [, CHARSIZE=float] [, CHARTHICK=float] [, COLORS=string/strarr] [, /DATA] [, /HARDWARE] [, LENGTH=float] [, LINESTYLES=integer/intarr] [, LOCATION=fltarr] [, PSYMS=integer/intarr] [, SYMCOLORS=string/strarr] [, SYMSIZE=float] [, SYMTHICK=float] [, TCOLORS=string/strarr] [, THICK=float] [, TITLES=string/strarr] [, TT_FONT=string] [, /VISIBLE] [, VSPACE=float]

This method obtains properties from the object.

Keywords

ALIGNMENT out optional type=integer: The current alignment of the legend box.
BACKGROUND out optional type=boolean default=0: Set this keyword to draw a colored background for the legend.
BG_COLOR out optional type=string default=white: The name of the background color.
BOX out optional type=boolean default=0: Set to 1 if a box is drawn around the legend items.
BX_COLOR out optional: The color of the box drawn around the legend items.
BX_THICK out optional type=float: The thickness of the line used to draw the box around the legend items.
CENTER_SYM out optional type=boolean: This keyword is set if symbols are placed in the center of the line.
CHARSIZE out optional type=float: The character size for the legend text. Uses cgDefCharsize by default. Ignored if using hardware fonts on the display.
CHARTHICK out optional type=float: The thickness of the legend text.
COLORS out optional type=string/strarr: The name of the data color. This is the color of each data line.
DATA out optional type=boolean: Indicates if the Location is in data coordinates.
HARDWARE out optional type=boolean: Set this keyword if you want to output the legend text in a hardware font.
LENGTH out optional type=float default=0.075: The length of the line connecting symbols in the legend, in normalized coordinates (0 to 1 in the graphics window). Set this equal to 0.0 if you wish to only plot symbols in the legend.
LINESTYLES out optional type=integer/intarr: The line style for drawing each line.
LOCATION out optional type=fltarr: The location of the upper-left corner of the legend item, in normalized coordinates (0 to 1 in the graphics window).
PSYMS out optional type=integer/intarr: Any normal IDL PSYM values, plus any value supported by the Coyote Library routine cgSYMCAT. An integer between 0 and 46.
SYMCOLORS out optional type=string/strarr: The name of the symbol color. By default, the same as the COLORS keyword.
SYMSIZE out optional type=float default=1.0: The symbol size.
SYMTHICK out optional type=float default=1.0: The thickness of the symbol.
TCOLORS out optional type=string/strarr: The Titles color. Set by default to Colors.
THICK out optional type=float default=1.0: The thickness of the line.
TITLES out optional type=string/strarr default=Plot Item: The "title" or text for each legend item.
TT_FONT out optional type=string: The name of a true-type font to use for the legend text.
VISIBLE out optional type=boolean default=1: The current visibility of the legend.
VSPACE out optional type=float default=1.5: A scale factor for vertical spacing between legend items. This number is multiplied by Charsize to determine vertical spacing.

top cgLegendItem::SetProperty

cgLegendItem::SetProperty, $ [, ALIGNMENT=integer] [, /BACKGROUND] [, BG_COLOR=string] [, /BOX] [, BX_COLOR=varies] [, BX_THICK=float] [, /CENTER_SYM] [, CHARSIZE=float] [, CHARTHICK=float] [, COLORS=string/strarr] [, /DATA] [, /HARDWARE] [, LENGTH=float] [, LINESTYLES=integer/intarr] [, LOCATION=fltarr] [, PSYMS=integer/intarr] [, SYMCOLORS=string/strarr] [, SYMSIZE=float] [, SYMTHICK=float] [, TCOLORS=string/strarr] [, THICK=float] [, TITLES=string/strarr] [, TT_FONT=string] [, /VISIBLE] [, VSPACE=float]

This method sets properties of the object.

Parameters

$

Keywords

ALIGNMENT in optional type=integer default=0

  0 - Location specifies the upper left corner of the legend box.
  1 - Location specifies the upper right corner of the legend box.
  2 - Location specifies the lower right corner of the legend box.
  3 - Location specifies the lower left corner of the legend box.
  4 - Location specifies the top side of the legend box (centered horizontally).
  5 - Location specifies the bottom side of the legend box (centered horizontally).
  6 - Location specifies the left side of the legend box (centered vertically).
  7 - Location specifies the right side of the legend box (centered vertically).
  8 - Location specified the very center of the legend box.

BACKGROUND in optional type=boolean default=0

Set this keyword to draw a colored background for the legend.

BG_COLOR in optional type=string default=white

The name of the background color.

BOX in optional type=boolean default=0

Set this keyword to draw a box around the legend items.

BX_COLOR in optional type=varies default=black

The color of the box drawn around the legend items.

BX_THICK in optional type=float

The thickness of the line used to draw the box around the legend items. If not set, use !P.Thick at drawing time.

CENTER_SYM in optional type=boolean

Set this keyword to place a single symbol in the center of the line.

CHARSIZE in optional type=float

The character size for the legend text. Uses cgDefCharsize by default. Ignored if using hardware fonts on the display.

CHARTHICK in optional type=float

The thickness of the legend text. If undefined, use Thick value.

COLORS in optional type=string/strarr

The name of the data color. This is the color of each data line.

DATA in optional type=boolean default=0

If set the values specified by the Location keyword are taken to be in data coordinate space.

HARDWARE in optional type=boolean

Set this keyword if you want to output the legend text in a hardware font.

LENGTH in optional type=float default=0.075

The length of the line connecting symbols in the legend, in normalized coordinates (0 to 1 in the graphics window). Set this equal to 0.0 if you wish to only plot symbols in the legend.

LINESTYLES in optional type=integer/intarr

The line style for drawing each line.

LOCATION in optional type=fltarr

The location of the upper-left corner of the legend item, in normalized coordinates (0 to 1 in the graphics window). The default is [0.1, 0.95].

PSYMS in optional type=integer/intarr

Any normal IDL PSYM values, plus any value supported by the Coyote Library routine cgSYMCAT. An integer between 0 and 46.

SYMCOLORS in optional type=string/strarr

The name of the symbol color. By default, the same as the COLOR keyword.

SYMSIZE in optional type=float default=1.0

The symbol size.

SYMTHICK in optional type=float default=1.0

The thickness of the symbol.

TCOLORS in optional type=string/strarr

The Titles color. Set by default to Color.

THICK in optional type=float default=1.0

The thickness of the line.

TITLES in optional type=string/strarr default=Plot Item

The "title" or text for each legend item.

TT_FONT in optional type=string

The name of a true-type font to use for the legend text.

VISIBLE in optional type=boolean default=1

Set this keyword to determine in the line should be drawn (visible=1), or if the line should not be drawn (visible=0).

VSPACE in optional type=float default=1.5

A scale factor for vertical spacing between legend items. This number is multiplied by Charsize to determine vertical spacing.

top cgLegendItem::CLEANUP

cgLegendItem::CLEANUP

This method destroys anything the object uses that retains memory space.

top cgLegendItem__Define

cgLegendItem__Define [, class]

The class definition module for the object.

Parameters

class out optional type=struct: The class definition as a structure variable. Occasionally useful.

File attributes

Modification date:	Fri Mar 27 11:07:35 2015
Lines:	1,138
Docformat:	rst rst

Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015

.\

cglegenditem__define.pro

Examples

Class description for cgLegendItem

Inheritance

Properties

Properties in cgLegendItem

Fields

Fields in IDL_OBJECT

Fields in cgLegendItem

Author information

Routines

Routine details

top cgLegendItem::INIT

Keywords

top cgLegendItem::AddCmd

Keywords

top cgLegendItem::CalculateBoxSize

top cgLegendItem::Draw

top cgLegendItem::GetProperty

Keywords

top cgLegendItem::SetProperty

Parameters

Keywords

top cgLegendItem::CLEANUP

top cgLegendItem__Define

Parameters

File attributes