Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/colors.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Colormaps and Colors
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 manipulation of colors and colormaps.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These functions are used to modify colormaps.
  10 A colormap is an object that contains the mapping
  11 between the color values stored in memory and
  12 the RGB values that are used to display color
  13 values. In general, colormaps only contain
  14 significant information for pseudo-color visuals,
  15 but even for other visual types, a colormap object
  16 is required in some circumstances.
  17 </para>
  18
  19 <para>
  20 There are a couple of special colormaps that can
  21 be retrieved. The system colormap (retrieved
  22 with gdk_colormap_get_system()) is the default
  23 colormap of the system. If you are using GdkRGB,
  24 there is another colormap that is important - the
  25 colormap in which GdkRGB works, retrieved with
  26 gdk_rgb_get_cmap(). However, when using GdkRGB,
  27 it is not generally necessary to allocate colors
  28 directly.
  29 </para>
  30
  31 <para>
  32 In previous revisions of this interface, a number
  33 of functions that take a #GdkColormap parameter
  34 were replaced with functions whose names began
  35 with "gdk_colormap_". This process will probably
  36 be extended somewhat in the future -
  37 gdk_color_white(), gdk_color_black(), and
  38 gdk_color_change() will probably become aliases.
  39 </para>
  40
  41 <!-- ##### SECTION See_Also ##### -->
  42 <para>
  43
  44 </para>
  45
  46 <!-- ##### STRUCT GdkColor ##### -->
  47 <para>
  48 The #GdkColor structure is used to describe an
  49 allocated or unallocated color.
  50
  51 <informaltable pgwide=1 frame="none" role="struct">
  52 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
  53 <tbody>
  54
  55 <row>
  56 <entry><structfield>pixel</structfield></entry>
  57 <entry>For allocated colors, the value used to
  58 draw this color on the screen.</entry>
  59 </row>
  60
  61 <row>
  62 <entry><structfield>red</structfield></entry>
  63 <entry>The red component of the color. This is
  64 a value between 0 and 65535, with 65535 indicating
  65 full intensitiy.</entry>
  66 </row>
  67
  68 <row>
  69 <entry><structfield>green</structfield></entry>
  70 <entry>the blue component of the color.</entry>
  71 </row>
  72
  73 <row>
  74 <entry><structfield>blue</structfield></entry>
  75 <entry>the green component of the color..</entry>
  76 </row>
  77
  78 </tbody></tgroup></informaltable>
  79 </para>
  80
  81 @pixel:
  82 @red:
  83 @green:
  84 @blue:
  85
  86 <!-- ##### STRUCT GdkColormap ##### -->
  87 <para>
  88 The colormap structure contains the following public
  89 fields.
  90
  91 <informaltable pgwide=1 frame="none" role="struct">
  92 <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
  93 <tbody>
  94
  95 <row>
  96 <entry><structfield>size</structfield></entry>
  97 <entry>For pseudo-color colormaps, the number of colors
  98 in the colormap..</entry>
  99 </row>
 100
 101 <row>
 102 <entry><structfield>colors</structfield></entry>
 103 <entry>An array containing the current values in the
 104 colormap. This can be used to map from pixel values
 105 back to RGB values. This is only meaningful for
 106 pseudo-color colormaps.</entry>
 107 </row>
 108
 109 </tbody></tgroup></informaltable>
 110 </para>
 111
 112 @parent_instance:
 113 @size:
 114 @colors:
 115
 116 <!-- ##### FUNCTION gdk_colormap_new ##### -->
 117 <para>
 118 Create a new colormap for the given visual.
 119 </para>
 120
 121 @visual: a #GdkVisual.
 122 @allocate: if %TRUE, the newly created colormap will be
 123   a private colormap, and all colors in it will be
 124   allocated for the applications use.
 125 @Returns: the new #GdkColormap.
 126
 127
 128 <!-- ##### FUNCTION gdk_colormap_ref ##### -->
 129 <para>
 130 Increase the reference count of a colormap.
 131 </para>
 132
 133 @cmap: a #GdkColormap.
 134 @Returns: @cmap
 135
 136
 137 <!-- ##### FUNCTION gdk_colormap_unref ##### -->
 138 <para>
 139 Decrease the reference count of a colormap. If the
 140 resulting reference count is zero, destroys the colormap.
 141 </para>
 142
 143 @cmap: a #GdkColormap.
 144
 145
 146 <!-- ##### FUNCTION gdk_colormap_get_system ##### -->
 147 <para>
 148 Returns the system's default colormap.
 149 </para>
 150
 151 @Returns: the default colormap.
 152
 153
 154 <!-- ##### FUNCTION gdk_colormap_get_system_size ##### -->
 155 <para>
 156 Returns the size of the system's default colormap.
 157 (See the description of struct #GdkColormap for an
 158 explanation of the size of a colormap.)
 159 </para>
 160
 161 @Returns: the size of the system's default colormap.
 162
 163
 164 <!-- ##### FUNCTION gdk_colormap_change ##### -->
 165 <para>
 166 Change the value of the first @ncolors in a private colormap
 167 to match the values in the <structfield>colors</structfield>
 168 array in the color map. This function is obsolete and
 169 should not be used. See gdk_color_change().
 170 </para>
 171
 172 @colormap: a #GdkColormap.
 173 @ncolors: the number of colors to change.
 174
 175
 176 <!-- ##### FUNCTION gdk_colormap_alloc_colors ##### -->
 177 <para>
 178 Allocates colors from a colormap.
 179 </para>
 180
 181 @colormap: a #GdkColormap.
 182 @colors: The color values to allocate. On return, the pixel
 183  values for allocated colors will be filled in.
 184 @ncolors: The number of colors in @colors.
 185 @writeable: If %TRUE, the colors are allocated writeable
 186  (their values can later be changed using gdk_color_change()).
 187  Writeable colors cannot be shared between applications.
 188 @best_match: If %TRUE, GDK will attempt to do matching against
 189  existing colors if the colors cannot be allocated as
 190  requested.
 191 @success: An array of length @ncolors. On return, this
 192  indicates whether the corresponding color in @colors was
 193  sucessfully allocated or not.
 194 @Returns: The number of colors that were not sucessfully
 195  allocated.
 196
 197
 198 <!-- ##### FUNCTION gdk_colormap_alloc_color ##### -->
 199 <para>
 200 Allocate a single color from a colormap.
 201 </para>
 202
 203 @colormap: a #GdkColormap.
 204 @color: the color to allocate. On return the
 205 <structfield>pixel</structfield> field will be
 206 filled in if allocation succeeds.
 207 @writeable: If %TRUE, the color is allocated writeable
 208  (their values can later be changed using gdk_color_change()).
 209  Writeable colors cannot be shared between applications.
 210 @best_match: If %TRUE, GDK will attempt to do matching against
 211  existing colors if the color cannot be allocated as
 212  requested.
 213 @Returns: %TRUE if the allocation succeeded.
 214
 215
 216 <!-- ##### FUNCTION gdk_colormap_free_colors ##### -->
 217 <para>
 218 Free previously allocated colors.
 219 </para>
 220
 221 @colormap: a #GdkColormap.
 222 @colors: the colors to free.
 223 @ncolors: the number of colors in @colors.
 224
 225
 226 <!-- ##### FUNCTION gdk_colormap_get_visual ##### -->
 227 <para>
 228 Return the visual for which a given colormap was created.
 229 </para>
 230
 231 @colormap: a #GdkColormap.
 232 @Returns: the visual of the colormap.
 233
 234
 235 <!-- ##### FUNCTION gdk_colors_store ##### -->
 236 <para>
 237 Change the value of the first @ncolors colors in
 238 a private colormap. This function is obsolete and
 239 should not be used. See gdk_color_change().
 240 </para>
 241
 242 @colormap: a #GdkColormap.
 243 @colors: the new color values.
 244 @ncolors: the number of colors to change.
 245
 246
 247 <!-- ##### FUNCTION gdk_color_copy ##### -->
 248 <para>
 249 Make a copy of a color structure. The result
 250 must be freed using gdk_color_free().
 251 </para>
 252
 253 @color: a #GdkColor.
 254 @Returns: a copy of @color.
 255
 256
 257 <!-- ##### FUNCTION gdk_color_free ##### -->
 258 <para>
 259 Free a color structure created with
 260 gdk_color_copy().
 261 </para>
 262
 263 @color: a #GdkColor.
 264
 265
 266 <!-- ##### FUNCTION gdk_colors_alloc ##### -->
 267 <para>
 268 Allocate colors from a colormap. This function
 269 is obsolete. See gdk_colormap_alloc_colors().
 270 For full documentation of the fields, see
 271 the Xlib documentation for XAllocColorCells.
 272 </para>
 273
 274 @colormap: a #GdkColormap.
 275 @contiguous: if %TRUE, the colors should be allocated
 276  in contiguous color cells.
 277 @planes: an array in which to store the plane masks.
 278 @nplanes: the number of planes to allocate. (Or zero,
 279  to indicate that the color allocation should not be
 280  planar.)
 281 @pixels: an array into which to store allocated pixel
 282  values.
 283 @npixels: the number of pixels in each plane to allocate.
 284 @Returns:
 285
 286
 287 <!-- ##### FUNCTION gdk_colors_free ##### -->
 288 <para>
 289 Free colors allocated with gdk_colors_alloc(). This
 290 function is obsolete. See gdk_colormap_free_colors().
 291 </para>
 292
 293 @colormap: a #GdkColormap.
 294 @pixels: the pixel values of the colors to free.
 295 @npixels: the number of values in @pixels.
 296 @planes: the plane masks for all planes to free, OR'd
 297  together.
 298
 299
 300 <!-- ##### FUNCTION gdk_color_white ##### -->
 301 <para>
 302 Return the white color for a given colormap. The resulting
 303 value has already allocated been allocated.
 304 </para>
 305
 306 @colormap: a #GdkColormap.
 307 @color: the location to store the color.
 308 @Returns: %TRUE if the allocation succeeded.
 309
 310
 311 <!-- ##### FUNCTION gdk_color_black ##### -->
 312 <para>
 313 Return the black color for a given colormap. The resulting
 314 value has already benn allocated.
 315 </para>
 316
 317 @colormap: a #GdkColormap.
 318 @color: the location to store the color.
 319 @Returns: %TRUE if the allocation succeeded.
 320
 321
 322 <!-- ##### FUNCTION gdk_color_parse ##### -->
 323 <para>
 324 Parse a textual specification of a color and fill in
 325 the <structfield>red</structfield>,
 326 <structfield>green</structfield>, and
 327 <structfield>blue</structfield> fields of a
 328 #GdkColor structure. The color is <emphasis>not</emphasis>
 329 allocated, you must call gdk_colormap_alloc_color() yourself.
 330 The text string can be in any of the forms accepted
 331 by <function>XParseColor</function>; these include
 332 name for a color from <filename>rgb.txt</filename>, such as
 333 <literal>DarkSlateGray</literal>, or a hex specification
 334 such as <literal>305050</literal>.
 335 </para>
 336
 337 @spec: the string specifying the color.
 338 @color: the #GdkColor to fill in
 339 @Returns:
 340
 341
 342 <!-- ##### FUNCTION gdk_color_alloc ##### -->
 343 <para>
 344 Allocate a single color from a colormap.
 345 This function is obsolete. See gdk_colormap_alloc_color().
 346 </para>
 347
 348 @colormap: a #GdkColormap.
 349 @color: The color to allocate. On return, the
 350 <structfield>pixel</structfield> field will be
 351 filled in.
 352 @Returns: %TRUE if the allocation succeeded.
 353
 354
 355 <!-- ##### FUNCTION gdk_color_change ##### -->
 356 <para>
 357 Change the value of a color that has already
 358 been allocated. If @colormap is not a private
 359 colormap, then the color must have been allocated
 360 using gdk_colormap_alloc_colors() with the
 361 @writeable set to %TRUE.
 362 </para>
 363
 364 @colormap: a #GdkColormap.
 365 @color: a #GdkColor, with the color to change
 366 in the <structfield>pixel</structfield> field,
 367 and the new value in the remaining fields.
 368 @Returns:
 369
 370
 371 <!-- ##### FUNCTION gdk_color_equal ##### -->
 372 <para>
 373 Compare two colors.
 374 </para>
 375
 376 @colora: a #GdkColor.
 377 @colorb: another #GdkColor.
 378 @Returns: %TRUE if the two colors compare equal
 379
 380
 381 <!-- ##### FUNCTION gdk_color_hash ##### -->
 382 <para>
 383 A hash function suitable for using for a hash
 384 table that stores #GdkColor's.
 385 </para>
 386
 387 @colora: a #GdkColor.
 388 @Returns: The hash function appled to @colora
 389 <!-- # Unused Parameters # -->
 390 @colorb: NOT USED.
 391
 392