NAME: GETCOLOR PURPOSE: The original purpose of this function was to enable the user to specify one of the 16 colors supported by the McIDAS color map by name. Over time, however, the function has become a general purpose function for handling and supporting drawing colors in a device-independent way. In particular, I have been looking for ways to write color handling code that will work transparently on both 8-bit and 24-bit machines. On 24-bit machines, the code should work the same where color decomposition is turned on or off. (The 16 supported colors in GETCOLOR come from the McIDAS color table offered on the IDL newsgroup by Liam Gumley.) CATEGORY: Graphics, Color Specification. CALLING SEQUENCE: result = GETCOLOR(color) OPTIONAL INPUT PARAMETERS: COLOR: A string with the "name" of the color. Valid names are: black magenta cyan yellow green red blue navy gold pink aqua orchid gray sky beige white The color YELLOW is returned if the color name can't be resolved. Case is unimportant. If the function is called with just this single input parameter, the return value is either a 1-by-3 array containing the RGB values of that particular color, or a 24-bit integer that can be "decomposed" into that particular color, depending upon the state of the TRUE keyword and upon whether color decomposition is turned on or off. The state of color decomposition can ONLY be determined if the program is being run in IDL 5.2 or higher. INDEX: The color table index where the specified color should be loaded. If this parameter is passed, then the return value of the function is the index number and not the color triple. (If color decomposition is turned on AND the user specifies an index parameter, the color is loaded in the color table at the proper index, but a 24-bit value is returned to the user in IDL 5.2 and higher.) If no positional parameter is present, then the return value is either a 16-by-3 byte array containing the RGB values of all 16 colors or it is a 16-element long integer array containing color values that can be decomposed into colors. The 16-by-3 array is appropriate for loading color tables with the TVLCT command: Device, Decomposed=0 colors = GetColor() TVLCT, colors, 100 INPUT KEYWORD PARAMETERS: NAMES: If this keyword is set, the return value of the function is a 16-element string array containing the names of the colors. These names would be appropriate, for example, in building a list widget with the names of the colors. If the NAMES keyword is set, the COLOR and INDEX parameters are ignored. listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16) LOAD: If this keyword is set, all 16 colors are automatically loaded starting at the color index specified by the START keyword. Note that setting this keyword means that the return value of the function will be a structure, with each field of the structure corresponding to a color name. The value of each field will be an index number (set by the START keyword) corresponding to the associated color, or a 24-bit long integer value that creates the color on a true-color device. What you have as the field values is determined by the TRUE keyword or whether color decomposition is on or off in the absense of the TRUE keyword. It will either be a 1-by-3 byte array or a long integer value. START: The starting color index number if the LOAD keyword is set. This keyword value is ignored unless the LOAD keyword is also set. The keyword is also ignored if the TRUE keyword is set or if color decomposition in on in IDL 5.2 and higher. The default value for the START keyword is !D.TABLE_SIZE - 17. TRUE: If this keyword is set, the specified color triple is returned as a 24-bit integer equivalent. The lowest 8 bits correspond to the red value; the middle 8 bits to the green value; and the highest 8 bits correspond to the blue value. In IDL 5.2 and higher, if color decomposition is turned on, it is as though this keyword were set. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: The TRUE keyword causes the START keyword to be ignored. The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be ignored. The COLOR parameter is ignored if the LOAD keyword is used. On systems where it is possible to tell the state of color decomposition (i.e., IDL 5.2 and higher), a 24-bit value (or values) is automatically returned if color decomposition is ON. EXAMPLE: To load a yellow color in color index 100 and plot in yellow, type: yellow = GETCOLOR('yellow', 100) PLOT, data, COLOR=yellow or, PLOT, data, COLOR=GETCOLOR('yellow', 100) To do the same thing on a 24-bit color system with decomposed color on, type: PLOT, data, COLOR=GETCOLOR('yellow', /TRUE) or in IDL 5.2 and higher, DEVICE, Decomposed=1 PLOT, data, COLOR=GETCOLOR('yellow') To load all 16 colors into the current color table, starting at color index 200, type: TVLCT, GETCOLOR(), 200 To add the color names to a list widget: listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16) To load all 16 colors and have the color indices returned in a structure: DEVICE, Decomposed=0 colors = GetColor(/Load, Start=1) HELP, colors, /Structure PLOT, data, COLOR=colors.yellow To get the direct color values as 24-bit integers in color structure fields: DEVICE, Decomposed=1 colors = GetColor(/Load) PLOT, data, COLOR=colors.yellow Note that the START keyword value is ignored if on a 24-bit device, so it is possible to write completely device-independent code by writing code like this: colors = GetColor(/Load) PLOT, data, Color=colors.yellow MODIFICATION HISTORY: Written by: David Fanning, 10 February 96. Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF Added the McIDAS colors to the program. 24 Feb 99. DWF Added the INDEX parameter to the program 8 Mar 99. DWF Added the NAMES keyword at insistence of Martin Schultz. 10 Mar 99. DWF Reorderd the colors so black is first and white is last. 7 June 99. DWF Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF Added LOAD AND START keywords. 7 June 99. DWF.