# coyote: CGDCBAR

- coyote/Graphics
- [Source code]

Description

      The purpose of this routine is to add a discrete color bar to
      a graphics plot. A "discrete" color bar is one with a handful
      of colors. Labels are centered beneath or beside the color fields.
      .. image:: cgcolorbar3.png
      .. image:: cgdcbar.png
      The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
      to be installed on your machine.

Categories

      Graphics

Params

      colors, in, required
         A vector of "colors" to be represented in the color bar. The vector can be a
         vector of color "names" that are known to cgColor. Or, it can be a vector of
         24-bit color values that can be decomposed into color triples. Or, it can be a
         vector of byte or integer values that can be used as indices into the current
         color table. If both colors and NCOLORS (see below) are undefined, a 10-element
         color table will be loaded and used.

Keywords

      addcmd: in, optional, type=boolean, default=0
         Set this keyword to add the command to the resizeable graphics window cgWindow.
      barcolor: in, optional, type=string
         This is the name of a color known to cgCOLOR that can be used to draw the color
         bar outlines. By default, the same as specified with the COLOR keyword.
      bottom: in, optional, type=integer, default=0
         The lowest color index of the colors to be loaded in the color bar.
      charpercent: in, optional, type=float, default=0.85
         A value from 0.0 go 1.0 that is multiplied by the CHARSIZE to produce
         the character size for the color bar. This value is only used if CHARSIZE is
         undefined. This keyword is primarily useful for using color bars in resizeable
         graphics windows (cgWindow).
      charsize: in, optional, type=float
         The character size of the color bar annotations. Default is cgDefCharsize()*charPercent.
      color: in, optional, type=string, default="opposite"
          The name of the color to use for color bar annotations.
      filename: in, optional, type=string
          The name of a color table file that can be read by cgCOLOR. This allows you to
          specify your own color names for your own colors.
      fit: in, optional, type=boolean, default=0
         If this keyword is set, the colorbar tries to "fit" itself to the normalized
         coordinates of the last graphics command executed. In other words, for
         a horizontal color bar, postition[[0,2]] = !X.Window, and for a vertical
         color bar, position[[1,3]] = !Y.Window. Other positions are adjusted
         to put the colorbar "reasonably" close to the plot. Because there are so many
         ways this colorbar can be displayed, the "fit" may not always be a good one.
         If you are fitting to an image, be sure to set the SAVE keyword on cgImage
         to establish a data coordinate system.
      font: in, optional, type=integer, default=!P.Font
         Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
      labels: in, optional, type=string
         An array of string labels that should annotate each color. Must be the same length
         as the colors vector. Colors are labelled consecutively by default.
      ncolors: in, optional, type=integer, default=256
         An alternative way to specify the colors in the color bar is by
         using the NCOLORS and BOTTOM keywords to locate the colors in the
         current color table. The NCOLORS and BOTTOM keywords have the same
         meaning as in the LOADCT, XLOADCT, XCOLORS, or cgCOLORBAR programs.
      position: in, optional, type=float
         A four-element array of normalized coordinates in the same
         form as the POSITION keyword on a plot. Default is [0.88, 0.10, 0.95, 0.90]
         for a vertical bar and [0.10, 0.88, 0.90, 0.95] for a horizontal bar.
         See the FIT keyword, also.
      right: in, optional, type=boolean, default=0
         This puts the title on the right-hand side of a vertical color bar. It applies
         only to vertical color bars.
      rotate: in, optional, type=float, default=0.0
         Set this keyword to a value that will rotate the label text.
         Positive values between 0 and 180 degrees rotate in a counter-clockwise
         sense. Negative values between 0 and 180 degress rotate in a
         clockwise sense.
      spacing: in, optional, type=float, default=1.0
         When labels are rotated, it is a little difficult to determine where,
         exactly, they should be located. This keyword gives the user some control
         over this location. The location "spacer" is multiplied by this amount.
         So, for example, to move the labels a little further away from the color bar,
         make this number greater than 1 (e.g, 1.25). To move the labels a little closer,
         use a number less than 1 (e.g, 0.75).
      tcharsize: in, optional, type=float
         The character size of the title. By default, set to cgDefCharsize().
      treverse: in, optional, type=boolean, default=0
         Set this keyword to reverse the direction of the title on a vertical color bar.
      title: in, optional, type=string, default=""
         This is title for the color bar. The default is to have no title.
      vertical: in, optional, type=boolean, default=0
         Setting this keyword give a vertical color bar. The default is a horizontal color bar.
      window: in, optional, type=boolean, default=0
         Set this keyword to display the plot in a resizeable graphics window (cgWindow).

Examples

      To display a 12 color horizontal color bar, labels with a three-letter
      month abbreviation::
         cgDisplay
         cgLoadCT, 5, NCOLORS=12, BOTTOM=1
         cgDCBar, NCOLORS=12, BOTTOM=1, LABELS=cgMonths(/Abbreviation)
      To load a 5 color vertical color bar, with the labels rotated 45 degrees::
         cgDisplay
         labels = StrArr(5)
         FOR j=0,4 DO labels[j] = 'City ' + StrTrim(j+1,2)
         colors = ['dodger blue', 'yellow', 'forest green', 'purple', 'tan']
         cgDCBar, colors, LABELS=labels, ROTATE=45, /VERTICAL

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

History

      Change History::
        Written by: David W. Fanning, 15 March 2009.
        Modification to code to avoid changing the colors vectors. 15 March 2009.
        Added FONT keyword. 1 April 2009. DWF.
        Code modified to support 24-bit PostScript printers. 23 September 2009. DWF.
        Fixed a problem with determining visual depth in Z-buffer. 15 January 2010. DWF.
        Added SPACING keyword and changed the default spacing on horizontal color bars slightly.  23 Apr 2010. DWF.
        Modified the spacing of the labels on the color bar, specifically for the PostScript device. 3 November 2010. DWF.
        Added Window and AddCmd keywords. 28 Jan 2011. DWF.
        Added a Right keyword and changed the title spacing a little bit for aesthetic reasons. 2 July 2011. DWF.
        Fixed a problem with assigning the color with the COLOR keyword in the Z-buffer. 30 Aug 2011. DWF.
        The default BOTTOM keyword value was incorrect. Fixed in this version. 5 December 2011. DWF.
        Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
        Previous change incorrectly implemented for PS device. Fixed. 29 Dec 2011. DWF.
        Added CHARPERCENT, FIT, and TREVERSE keywords. Cleaned up documentation. 20 March 2012. DWF.
        Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
        Fixed a problem in which the colors variable was set to long integers if the BOTTOM keyword was used with
            NCOLORS. 2 Oct 2013. DWF.

Copyright

      Copyright (c) 2009-2012, Fanning Software Consulting, Inc.