GET_NAMED_COLOR Function

PV-WAVE Advantage > JWAVE User Guide > JWAVE Wrapper API > GET_NAMED_COLOR Function

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

Usage

color = GET_NAMED_COLOR(color_name)

Input Parameters

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.setNamedColor—or setNamedColorSet—method.)

Input Keywords

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))

Output Keywords

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.

Returned Value

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

Discussion

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

Managing the Color Table

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: Retreiving a Color 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.

Figure A-1: Retreiving a Color

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: Named Colors in a Color Table, 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].

Figure A-2: Named Colors in a Color Table

The following example demonstrates how the Range_Of_Colors keyword identifies 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)

Notes and Restrictions

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.

note

To create a default color, supply a long integer containing red, green, and blue components of the desired color. For example, the color chartreuse is represented by red=127, green=255, and blue=0 (in hex, 7F, FF, and 00). To create this color, use '00ff7f'xL as a constant. In an equation, you can form this constant using PV‑WAVE expressions such as:

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

or:

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

Examples

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