GET_NAMED_COLOR Function

Gets a color from a color name supplied by a JWAVE client application.

color = GET_NAMED_COLOR(color_name)

colorName A string containing the name of the color you wish to retrieve from the client. (This name must have been supplied in the client Java application using the JWaveView.setNamedColoror setNamedColorSetmethod.)

Color_Set If set, GET_NAMED_COLOR returns an array of colors corresponding to a named color set. (In other words, use this keyword to retrieve colors that were packed by the client with the JWaveView.setNamedColorSet method.) You may have a color and a color set with the same name.

DefaultRGB Specifies a long integer (RGB value) representing the default color if the named color does not exist. (Default: '000000'xL (black))

Range_Of_Colors Retrieves the a two-element array containing the range of colors that are available for use by images. The first element represents the first color in the range, and the second element represents the last color. This range is equivalent to the number of colors in the color table minus the number of named colors that have been retrieved. See the Discussion for information on how this keyword is used.

Color A color value that can be used by PV-WAVE.

GET_COLOR_NAME unpacks a color object sent from a Java client and returns a corresponding PV-WAVE color index (or, if you are using a 24-bit device, a 24-bit color is returned). The returned color can be used in any PV-WAVE context that uses color, such as the Color keyword associated with many of the graphics routines.

For example, the following calls might appear in a Java client application. They associate names with color objects. These name/color object pairs are sent to the JWAVE wrapper function when the execute method is called in the Java application.

myJWaveView.setNamedColor("BACKGROUND", java.awt.Color.lightGray)
myJWaveView.setNamedColor("COLOR", java.awt.Color.red)

The following GET_NAMED_COLOR calls retrieve these name/color pairs in the JWAVE wrapper function.

back = GET_NAMED_COLOR("BACKGROUND", Default='000000'xL)
fore = GET_NAMED_COLOR("COLOR", Default = 'ffffff'xL)

Now, back and fore can be used in any PV-WAVE expression that takes a color value. For example:

PLOT, x, Color=fore, Background=back 

To load a color table in a JWAVE wrapper, you must call the JWAVE_LOADCT procedure. The resulting color table is subsetted into two parts that include (a) the named colors returned by GET_NAMED_COLOR and (b) the rest of the colors in the specified color table.

Figure A-1 illustrates how a color table is created in a JWAVE wrapper. When LOAD_JWAVECT is called, a color table is created with the named colors loaded into a subset of the color table.

• First, a named color is passed to the wrapper and retrieved with GET_NAMED_COLOR.

• Next, the retrieved color is given a reserved spot in the color table.

• Finally, the color table specified by LOAD_JWAVECT (the image colors) is loaded into the remainder of the color table.

Use the Range_Of_Colors keyword to obtain the range of colors that are allocated for images in the color table (that is, all of the colors except the named colors retrieved by GET_NAMED_COLOR). For instance, in Figure A-2, the first five colors are allocated to the named colors. The remaining colors fall in the range {5..255}. These are the colors that are available for use by images, and {5..255} is the range that is returned by the Range_Of_Colors keyword. This range is expressed as a two-element array, such as: range=[5, 255].

Example 1-1 demonstrates how the Range_Of_Colors keyword is used to identify the image portion of the color table, and then this range is used to "smooth" this portion of the color table using the BYTSCL function.

; Get colors
      JWAVE_LOADCT, 1
   back = get_Named_Color("BACKGROUND", Default = '000000'xL) 
   fore = get_Named_Color("COLOR", Default = 'ffffff'xL)
      bot  = get_Named_Color("BOTTOM", Default = fore, $ 
                Range_Of_Colors=crange)

; Re-map image values into the range of image colors. 
      s = BYTSCL(s, Top = crange(1)-crange(0)) + crange(0)

• Only 256 colors are available for use in JWAVE wrapper functions.

• You may use the output of a previous call to GET_NAMED_COLOR as a default color.

• Valid color names must start with a letter and contain only letters (A-Z), digits (0-9), and underscores (_). They are not case sensitive.

• If you request a color set (set by the client with the method setNamedColorSet), then GET_NAMED_COLOR returns an array of color indices. This is useful for things such as the CONTOUR procedure's C_Color keyword.

• To ensure that the value of Range_Of_Colors keyword is valid, use the value of Range_Of_Colors from the last call to either GET_NAMED_COLOR or JWAVE_LOADCT.

red + 256L*(green + 256L*blue) 

or

LONG(red) OR ISHFT(LONG(green), 8) OR ISHFT(LONG(blue), 16)

See the previous Discussion section for examples. See also Chapter 5, JWAVE Server Development for additional information and examples.

GETPARAM

For more information on color tables and using color in PV-WAVE, refer to the PV-WAVE User's Guide.