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


 Name

    XcmsAllocColor - allocate device-independent colors

 Syntax


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

    Status XcmsAllocNamedColor(display, colormap, color_string,
                               color_screen_return, color_exact_return,
                               result_format)
          Display *display;
          Colormap colormap;
          char *color_string;
          XcmsColor *color_screen_return;
          XcmsColor *color_exact_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 color to allocate and returns the pixel and
                   color that is actually used in the colormap.

    colorscreenreturn
                   Returns the pixel value of the color cell and color speci-
                   fication that actually is stored for that cell.

    colorstring   Specifies the color string whose color definition struc-
                   ture is to be returned.

    resultformat  Specifies the color format for the returned color specifi-
                   cation.

 Description

    The XcmsAllocColor function is similar to XAllocColor except the color
    can be specified in any format.  The XcmsAllocColor function ultimately
    calls XAllocColor to allocate a read-only color cell (colormap entry)
    with the specified color.  XcmsAllocColor first converts the color speci-
    fied to an RGB value and then passes this to XAllocColor.  XcmsAllocColor
    returns the pixel value of the color cell and the color specification
    actually allocated.  This returned color specification is the result of
    converting the RGB value returned by XAllocColor into the format speci-
    fied with the resultformat argument.  If there is no interest in a
    returned color specification, unnecessary computation can be bypassed if
    resultformat is set to XcmsRGBFormat.  The corresponding colormap cell
    is read-only.  If this routine returns XcmsFailure, the colorinout
    color specification is left unchanged.

    XcmsAllocColor can generate a ``BadColor'' errors.

    The XcmsAllocNamedColor function is similar to XAllocNamedColor except
    the color returned can be in any format specified.  This function ulti-
    mately calls XAllocColor to allocate a read-only color cell with the
    color specified by a color string.  The color string is parsed into an
    XcmsColor structure (see XcmsLookupColor(XS)), converted to an RGB value,
    then finally passed to the XAllocColor.  If the color name is not in the
    Host Portable Character Encoding the result is implementation dependent.
    Use of uppercase or lowercase does not matter.

    This function returns both the color specification as a result of parsing
    (exact specification) and the actual color specification stored (screen
    specification).  This screen specification is the result of converting
    the RGB value returned by XAllocColor into the format specified in
    resultformat.  If there is no interest in a returned color specifica-
    tion, unnecessary computation can be bypassed if resultformat is set to
    XcmsRGBFormat.

    XcmsAllocNamedColor can generate a ``BadColor'' errors.

 Diagnostics


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

 See also

    XcmsQueryColor(XS), XcmsStoreColor(XS)
    Xlib - C Language X Interface