XcmsQueryColor(XS)       X Version 11 (Release 5)         XcmsQueryColor(XS)
                                6 January 1993


 Name

    XcmsQueryColor - obtain color values

 Syntax


    Status XcmsQueryColor(display, colormap, color_in_out, result_format)
          Display *display;
          Colormap colormap;
          XcmsColor *color_in_out;
          XcmsColorFormat result_format;

    Status XcmsQueryColors(display, colormap, colors_in_out, ncolors,
                           result_format)
          Display *display;
          Colormap colormap;
          XcmsColor colors_in_out[];
          unsigned int ncolors;
          XcmsColorFormat result_format;

    Status XcmsLookupColor(display, colormap, color_string, color_exact_return,
                           color_screen_return, result_format)
          Display *display;
          Colormap colormap;
          char *color_string;
          XcmsColor *color_exact_return, *color_screen_return;
          XcmsColorFormat result_format;


 Arguments


    display        Specifies the connection to the X server.

    colormap       Specifies the colormap.

    colorexactreturn
                   Returns the color specification parsed from the color
                   string or parsed from the corresponding string found in a
                   color name database.

    colorinout   Specifies the pixel member that indicates the color cell
                   to query, and the color specification stored for the color
                   cell is returned in this XcmsColor structure.

    colorscreenreturn
                   Returns the color that can be reproduced on the Screen.

    colorstring   Specifies the color string.

    resultformat  Specifies the color format for the returned color specifi-
                   cations (colorscreenreturn and colorexactreturn argu-
                   ments).  If format is XcmsUndefinedFormat and the color
                   string contains a numerical color specification, the spec-
                   ification is returned in the format used in that numerical
                   color specification.  If format is XcmsUndefinedFormat and
                   the color string contains a color name, the specification
                   is returned in the format used to store the color in the
                   database.

    ncolors        Specifies the number of XcmsColor structures in the color
                   specification array.

 Description

    The XcmsQueryColor function obtains the RGB value for the pixel value in
    the pixel member of the specified XcmsColor structure, and then converts
    the value to the target format as specified by the resultformat argu-
    ment.  If the pixel is not a valid index into the specified colormap, a
    ``BadValue'' error results.  The XcmsQueryColors function obtains the RGB
    values for pixel values in the pixel members of XcmsColor structures, and
    then converts the values to the target format as specified by the
    resultformat argument.  If a pixel is not a valid index into the speci-
    fied colormap, a ``BadValue'' error results.  If more than one pixel is
    in error, the one that gets reported is arbitrary.

    XcmsQueryColor and XcmsQueryColors can generate ``BadColor'' and ``Bad-
    Value'' errors.

    The XcmsLookupColor function looks up the string name of a color with
    respect to the screen associated with the specified colormap.  It returns
    both the exact color values and the closest values provided by the screen
    with respect to the visual type of the specified colormap.  The values
    are returned in the format specified by resultformat.  If the color name
    is not in the Host Portable Character Encoding the result is implementa-
    tion dependent.  Use of uppercase or lowercase does not matter.
    XcmsLookupColor returns XcmsSuccess or XcmsSuccessWithCompression if the
    name is resolved, otherwise it returns XcmsFailure.  If XcmsSuccessWith-
    Compression is returned, then the color specification in
    colorscreenreturn is the result of gamut compression.

 Diagnostics


    ``BadColor''   A value for a Colormap argument does not name a defined
                   Colormap.

    ``BadValue''   Some numeric value falls outside the range of values
                   accepted by the request.  Unless a specific range is
                   specified for an argument, the full range defined by the
                   argument's type is accepted.  Any argument defined as a
                   set of alternatives can generate this error.

 See also

    XcmsAllocColor(XS), XcmsStoreColor(XS), XQueryColor(XS)
    Xlib - C Language X Interface