coyote: PICKCOLOR

NAME
PICKCOLOR
PURPOSE
A modal dialog widget allowing the user to select
the RGB color triple specifying a color. The return
value of the function is the color triple specifying the
color or the "name" of the color if the NAME keyword is set.
AUTHOR
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY
Graphics, Color Specification. See related program cgCOLOR.
CALLING SEQUENCE
color = PickColor(colorindex)
RETURN VALUE
The return value of the function is a 1-by-3 array containing
the values of the color triple that specifies the selected color.
The color can be loaded, for example, in any color index:
    color = PickColor(240)
    TVLCT, color, 240
The return value is the original color triple if the user
selects the CANCEL button.
IF the NAMES keyword is set, the return value of the function is
the "name" of the selected color. This would be appropriate for
passing to the cgCOLOR program, for example.
OPTIONAL INPUT POSITIONAL PARAMETERS
COLORINDEX: The color index of the color to be changed. If not
       specified the color index !D.Table_Size - 2 is used.
       The Current Color and the Color Sliders are set to the
       values of the color at this color index.
OPTIONAL INPUT KEYWORD PARAMETERS
CANCEL: A keyword that is set to 1 if the CANCEL button is selected
       and to 0 otherwise.
COMMON BLOCKS
None.
SIDE EFFECTS
88 pre-determined colors are loaded in the color table.
In addition, the color index at COLORINDEX is modified while
the program is on the display. When the program exits, the
entry color table is restored. Thus, on 8-bit displays there
might be some color effects in graphics windows while PICKCOLOR
is on the display. Changes in the color table are not noticable
on 16-bit and 24-bit displays.
EXAMPLE
To specify a color for a plot in color decomposition OFF mode:
   Device, Decomposed=0
   !P.Color = !P.Color < (!D.Table_Size - 1)
   color = PickColor(!P.Color, Cancel=cancelled)
   IF NOT cancelled THEN BEGIN
       TVLCT, color, !P.Color
       Plot, data
   ENDIF
To specify a color for a plot in color decomposition ON mode:
   Device, Decomposed=1
   color = PickColor(Cancel=cancelled)
   !P.Color = Color24(color)
   IF NOT cancelled THEN Plot, data
 To obtain the name of the selected color to pass to GetColor:
   selectedColor = PickColor(/Name)
   axisColor = cgColor(selectedColor, !D.Table_Size-4)
MODIFICATION HISTORY
Written by: David Fanning, 28 Oct 99.
Added NAME keyword. 18 March 2000, DWF.
Fixed a small bug when choosing a colorindex less than !D.Table_Size-17. 20 April 2000. DWF.
Added actual color names to label when NAMES keyword selected. 12 May 2000. DWF.
Modified to use 88 colors and cgCOLOR instead of 16 colors and GETCOLOR. 4 Dec 2000. DWF.
Changed FSC_Color to cgColor everywhere. 16 Jan 2013. DWF.