NAME

XcmsAllocColor, XcmsAllocNamedColor - allocate colors

SYNTAX

Status XcmsAllocColor(Display *_d_i_s_p_l_a_y, Colormap _c_o_l_o_r_m_a_p, XcmsColor *_c_o_l_o_r___i_n___o_u_t, XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t); Status XcmsAllocNamedColor(Display *_d_i_s_p_l_a_y, Colormap _c_o_l_o_r_m_a_p, char *_c_o_l_o_r___s_t_r_i_n_g, XcmsColor *_c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n, XcmsColor *_c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n, XcmsColorFormat _r_e_s_u_l_t___f_o_r_m_a_t);

ARGUMENTS

_d_i_s_p_l_a_y Specifies the connection to the X server.
_c_o_l_o_r_m_a_p Specifies the colormap.
_c_o_l_o_r___e_x_a_c_t___r_e_t_u_r_n Returns the color specification parsed from the color string
or parsed from the corresponding string found in a color-name database.
_c_o_l_o_r___i_n___o_u_t Specifies the color to allocate and returns the pixel and color
that is actually used in the colormap.
_c_o_l_o_r___s_c_r_e_e_n___r_e_t_u_r_n Returns the pixel value of the color cell and color specification
that actually is stored for that cell.
_c_o_l_o_r___s_t_r_i_n_g Specifies the color string whose color definition structure is to be returned.
_r_e_s_u_l_t___f_o_r_m_a_t Specifies the color format for the returned color specification.

DESCRIPTION

The _X_c_m_s_A_l_l_o_c_C_o_l_o_r function is similar to _X_A_l_l_o_c_C_o_l_o_r except the color can be specified in any format. The _X_c_m_s_A_l_l_o_c_C_o_l_o_r function ultimately calls _X_A_l_l_o_c_C_o_l_o_r to allocate a read-only color cell (colormap entry) with the specified color. _X_c_m_s_A_l_l_o_c_C_o_l_o_r first converts the color specified to an RGB value and then passes this to _X_A_l_l_o_c_C_o_l_o_r. _X_c_m_s_A_l_l_o_c_C_o_l_o_r 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 _X_A_l_l_o_c_C_o_l_o_r into the format specified with the result_format argument. If there is no interest in a returned color specification, unnecessary computation can be bypassed if result_format is set to _X_c_m_s_R_G_B_F_o_r_m_a_t. The corresponding colormap cell is read-only. If this routine returns _X_c_m_s_F_a_i_l_u_r_e, the color_in_out color specification is left unchanged.

_X_c_m_s_A_l_l_o_c_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r errors.

The _X_c_m_s_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r function is similar to _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r except that the color returned can be in any format specified. This function ultimately calls _X_A_l_l_o_c_C_o_l_o_r to allocate a read-only color cell with the color specified by a color string. The color string is parsed into an _X_c_m_s_C_o_l_o_r structure (see _X_c_m_s_L_o_o_k_u_p_C_o_l_o_r), converted to an RGB value, and finally passed to _X_A_l_l_o_c_C_o_l_o_r. 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 _X_A_l_l_o_c_C_o_l_o_r into the format specified in result_format. If there is no interest in a returned color specification, unnecessary computation can be bypassed if result_format is set to _X_c_m_s_R_G_B_F_o_r_m_a_t. If color_screen_return and color_exact_return point to the same structure, the pixel field will be set correctly, but the color values are undefined.

_X_c_m_s_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r errors.

DIAGNOSTICS

_B_a_d_C_o_l_o_r
A value for a Colormap argument does not name a defined Colormap.

SEE ALSO

XcmsQueryColor(3X11), XcmsStoreColor(3X11)
_X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e