Commit 1f1f2e91 authored by Matthias Clasen's avatar Matthias Clasen

Documentation updates.

parent 5cc215cd
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/gdkcolor.c (gdk_colormap_alloc_color):
(gdk_colormap_get_visual):
(gdk_colors_store):
(gdk_color_copy):
(gdk_color_free):
(gdk_color_white):
(gdk_color_black):
(gdk_color_parse):
(gdk_color_alloc):
* gdk/x11/gdkcolor-x11.c (gdk_colormap_new):
(gdk_colormap_get_system_size):
(gdk_colormap_change):
(gdk_colormap_alloc_colors):
(gdk_colors_alloc):
(gdk_colors_free):
(gdk_color_change):
2002-10-23 Matthias Clasen <maclas@gmx.de> 2002-10-23 Matthias Clasen <maclas@gmx.de>
* gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target): * gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target):
......
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/gdkcolor.c (gdk_colormap_alloc_color):
(gdk_colormap_get_visual):
(gdk_colors_store):
(gdk_color_copy):
(gdk_color_free):
(gdk_color_white):
(gdk_color_black):
(gdk_color_parse):
(gdk_color_alloc):
* gdk/x11/gdkcolor-x11.c (gdk_colormap_new):
(gdk_colormap_get_system_size):
(gdk_colormap_change):
(gdk_colormap_alloc_colors):
(gdk_colors_alloc):
(gdk_colors_free):
(gdk_color_change):
2002-10-23 Matthias Clasen <maclas@gmx.de> 2002-10-23 Matthias Clasen <maclas@gmx.de>
* gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target): * gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target):
......
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/gdkcolor.c (gdk_colormap_alloc_color):
(gdk_colormap_get_visual):
(gdk_colors_store):
(gdk_color_copy):
(gdk_color_free):
(gdk_color_white):
(gdk_color_black):
(gdk_color_parse):
(gdk_color_alloc):
* gdk/x11/gdkcolor-x11.c (gdk_colormap_new):
(gdk_colormap_get_system_size):
(gdk_colormap_change):
(gdk_colormap_alloc_colors):
(gdk_colors_alloc):
(gdk_colors_free):
(gdk_color_change):
2002-10-23 Matthias Clasen <maclas@gmx.de> 2002-10-23 Matthias Clasen <maclas@gmx.de>
* gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target): * gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target):
......
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/gdkcolor.c (gdk_colormap_alloc_color):
(gdk_colormap_get_visual):
(gdk_colors_store):
(gdk_color_copy):
(gdk_color_free):
(gdk_color_white):
(gdk_color_black):
(gdk_color_parse):
(gdk_color_alloc):
* gdk/x11/gdkcolor-x11.c (gdk_colormap_new):
(gdk_colormap_get_system_size):
(gdk_colormap_change):
(gdk_colormap_alloc_colors):
(gdk_colors_alloc):
(gdk_colors_free):
(gdk_color_change):
2002-10-23 Matthias Clasen <maclas@gmx.de> 2002-10-23 Matthias Clasen <maclas@gmx.de>
* gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target): * gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target):
......
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/gdkcolor.c (gdk_colormap_alloc_color):
(gdk_colormap_get_visual):
(gdk_colors_store):
(gdk_color_copy):
(gdk_color_free):
(gdk_color_white):
(gdk_color_black):
(gdk_color_parse):
(gdk_color_alloc):
* gdk/x11/gdkcolor-x11.c (gdk_colormap_new):
(gdk_colormap_get_system_size):
(gdk_colormap_change):
(gdk_colormap_alloc_colors):
(gdk_colors_alloc):
(gdk_colors_free):
(gdk_color_change):
2002-10-23 Matthias Clasen <maclas@gmx.de> 2002-10-23 Matthias Clasen <maclas@gmx.de>
* gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target): * gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target):
......
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/gdkcolor.c (gdk_colormap_alloc_color):
(gdk_colormap_get_visual):
(gdk_colors_store):
(gdk_color_copy):
(gdk_color_free):
(gdk_color_white):
(gdk_color_black):
(gdk_color_parse):
(gdk_color_alloc):
* gdk/x11/gdkcolor-x11.c (gdk_colormap_new):
(gdk_colormap_get_system_size):
(gdk_colormap_change):
(gdk_colormap_alloc_colors):
(gdk_colors_alloc):
(gdk_colors_free):
(gdk_color_change):
2002-10-23 Matthias Clasen <maclas@gmx.de> 2002-10-23 Matthias Clasen <maclas@gmx.de>
* gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target): * gdk/linux-fb/gdkselection-fb.c (gdk_utf8_to_string_target):
......
2002-10-24 Matthias Clasen <maclas@gmx.de>
* gdk/tmpl/colors.sgml: Some docs moved inline.
2002-10-22 Matthias Clasen <maclas@gmx.de> 2002-10-22 Matthias Clasen <maclas@gmx.de>
* gdk/tmpl/gdkdisplay.sgml: Document GdkDisplayPointerHooks. * gdk/tmpl/gdkdisplay.sgml: Document GdkDisplayPointerHooks.
......
...@@ -72,14 +72,11 @@ The colormap structure contains the following public fields. ...@@ -72,14 +72,11 @@ The colormap structure contains the following public fields.
<!-- ##### FUNCTION gdk_colormap_new ##### --> <!-- ##### FUNCTION gdk_colormap_new ##### -->
<para> <para>
Creates a new colormap for the given visual.
</para> </para>
@visual: a #GdkVisual. @visual:
@allocate: if %TRUE, the newly created colormap will be @allocate:
a private colormap, and all colors in it will be @Returns:
allocated for the applications use.
@Returns: the new #GdkColormap.
<!-- ##### FUNCTION gdk_colormap_ref ##### --> <!-- ##### FUNCTION gdk_colormap_ref ##### -->
...@@ -108,74 +105,50 @@ Creates a new colormap for the given visual. ...@@ -108,74 +105,50 @@ Creates a new colormap for the given visual.
<!-- ##### FUNCTION gdk_colormap_get_system_size ##### --> <!-- ##### FUNCTION gdk_colormap_get_system_size ##### -->
<para> <para>
Returns the size of the system's default colormap.
(See the description of struct #GdkColormap for an
explanation of the size of a colormap.)
</para> </para>
@Returns: the size of the system's default colormap. @Returns:
<!-- ##### FUNCTION gdk_colormap_change ##### --> <!-- ##### FUNCTION gdk_colormap_change ##### -->
<para> <para>
Changes the value of the first @ncolors in a private colormap
to match the values in the <structfield>colors</structfield>
array in the color map. This function is obsolete and
should not be used. See gdk_color_change().
</para> </para>
@colormap: a #GdkColormap. @colormap:
@ncolors: the number of colors to change. @ncolors:
<!-- ##### FUNCTION gdk_colormap_alloc_colors ##### --> <!-- ##### FUNCTION gdk_colormap_alloc_colors ##### -->
<para> <para>
Allocates colors from a colormap.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@colors: The color values to allocate. On return, the pixel @colors:
values for allocated colors will be filled in. @ncolors:
@ncolors: The number of colors in @colors. @writeable:
@writeable: If %TRUE, the colors are allocated writeable @best_match:
(their values can later be changed using gdk_color_change()). @success:
Writeable colors cannot be shared between applications. @Returns:
@best_match: If %TRUE, GDK will attempt to do matching against
existing colors if the colors cannot be allocated as
requested.
@success: An array of length @ncolors. On return, this
indicates whether the corresponding color in @colors was
sucessfully allocated or not.
@Returns: The number of colors that were not sucessfully
allocated.
<!-- ##### FUNCTION gdk_colormap_alloc_color ##### --> <!-- ##### FUNCTION gdk_colormap_alloc_color ##### -->
<para> <para>
Allocates a single color from a colormap.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@color: the color to allocate. On return the @color:
<structfield>pixel</structfield> field will be @writeable:
filled in if allocation succeeds. @best_match:
@writeable: If %TRUE, the color is allocated writeable @Returns:
(their values can later be changed using gdk_color_change()).
Writeable colors cannot be shared between applications.
@best_match: If %TRUE, GDK will attempt to do matching against
existing colors if the color cannot be allocated as
requested.
@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_colormap_free_colors ##### --> <!-- ##### FUNCTION gdk_colormap_free_colors ##### -->
<para> <para>
Frees previously allocated colors.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@colors: the colors to free. @colors:
@ncolors: the number of colors in @colors. @ncolors:
<!-- ##### FUNCTION gdk_colormap_query_color ##### --> <!-- ##### FUNCTION gdk_colormap_query_color ##### -->
...@@ -190,11 +163,10 @@ Frees previously allocated colors. ...@@ -190,11 +163,10 @@ Frees previously allocated colors.
<!-- ##### FUNCTION gdk_colormap_get_visual ##### --> <!-- ##### FUNCTION gdk_colormap_get_visual ##### -->
<para> <para>
Returns the visual for which a given colormap was created.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@Returns: the visual of the colormap. @Returns:
<!-- ##### FUNCTION gdk_colormap_get_screen ##### --> <!-- ##### FUNCTION gdk_colormap_get_screen ##### -->
...@@ -208,157 +180,115 @@ Returns the visual for which a given colormap was created. ...@@ -208,157 +180,115 @@ Returns the visual for which a given colormap was created.
<!-- ##### FUNCTION gdk_colors_store ##### --> <!-- ##### FUNCTION gdk_colors_store ##### -->
<para> <para>
Changes the value of the first @ncolors colors in
a private colormap. This function is obsolete and
should not be used. See gdk_color_change().
</para> </para>
@colormap: a #GdkColormap. @colormap:
@colors: the new color values. @colors:
@ncolors: the number of colors to change. @ncolors:
<!-- ##### FUNCTION gdk_color_copy ##### --> <!-- ##### FUNCTION gdk_color_copy ##### -->
<para> <para>
Makes a copy of a color structure. The result
must be freed using gdk_color_free().
</para> </para>
@color: a #GdkColor. @color:
@Returns: a copy of @color. @Returns:
<!-- ##### FUNCTION gdk_color_free ##### --> <!-- ##### FUNCTION gdk_color_free ##### -->
<para> <para>
Frees a color structure created with
gdk_color_copy().
</para> </para>
@color: a #GdkColor. @color:
<!-- ##### FUNCTION gdk_colors_alloc ##### --> <!-- ##### FUNCTION gdk_colors_alloc ##### -->
<para> <para>
Allocates colors from a colormap. This function
is obsolete. See gdk_colormap_alloc_colors().
For full documentation of the fields, see
the Xlib documentation for <function>XAllocColorCells()</function>.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@contiguous: if %TRUE, the colors should be allocated @contiguous:
in contiguous color cells. @planes:
@planes: an array in which to store the plane masks. @nplanes:
@nplanes: the number of planes to allocate. (Or zero, @pixels:
to indicate that the color allocation should not be @npixels:
planar.)
@pixels: an array into which to store allocated pixel
values.
@npixels: the number of pixels in each plane to allocate.
@Returns: @Returns:
<!-- ##### FUNCTION gdk_colors_free ##### --> <!-- ##### FUNCTION gdk_colors_free ##### -->
<para> <para>
Frees colors allocated with gdk_colors_alloc(). This
function is obsolete. See gdk_colormap_free_colors().
</para> </para>
@colormap: a #GdkColormap. @colormap:
@pixels: the pixel values of the colors to free. @pixels:
@npixels: the number of values in @pixels. @npixels:
@planes: the plane masks for all planes to free, OR'd @planes:
together.
<!-- ##### FUNCTION gdk_color_white ##### --> <!-- ##### FUNCTION gdk_color_white ##### -->
<para> <para>
Returns the white color for a given colormap. The resulting
value has already allocated been allocated.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@color: the location to store the color. @color:
@Returns: %TRUE if the allocation succeeded. @Returns:
<!-- ##### FUNCTION gdk_color_black ##### --> <!-- ##### FUNCTION gdk_color_black ##### -->
<para> <para>
Returns the black color for a given colormap. The resulting
value has already benn allocated.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@color: the location to store the color. @color:
@Returns: %TRUE if the allocation succeeded. @Returns:
<!-- ##### FUNCTION gdk_color_parse ##### --> <!-- ##### FUNCTION gdk_color_parse ##### -->
<para> <para>
Parses a textual specification of a color and fill in
the <structfield>red</structfield>,
<structfield>green</structfield>, and
<structfield>blue</structfield> fields of a
#GdkColor structure. The color is <emphasis>not</emphasis>
allocated, you must call gdk_colormap_alloc_color() yourself.
The text string can be in any of the forms accepted
by <function>XParseColor</function>; these include
name for a color from <filename>rgb.txt</filename>, such as
<literal>DarkSlateGray</literal>, or a hex specification
such as <literal>305050</literal>.
</para> </para>
@spec: the string specifying the color. @spec:
@color: the #GdkColor to fill in @color:
@Returns: @Returns:
<!-- ##### FUNCTION gdk_color_alloc ##### --> <!-- ##### FUNCTION gdk_color_alloc ##### -->
<para> <para>
Allocates a single color from a colormap.
This function is obsolete. See gdk_colormap_alloc_color().
</para> </para>
@colormap: a #GdkColormap. @colormap:
@color: The color to allocate. On return, the @color:
<structfield>pixel</structfield> field will be @Returns:
filled in.
@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_change ##### --> <!-- ##### FUNCTION gdk_color_change ##### -->
<para> <para>
Changes the value of a color that has already
been allocated. If @colormap is not a private
colormap, then the color must have been allocated
using gdk_colormap_alloc_colors() with the
@writeable set to %TRUE.
</para> </para>
@colormap: a #GdkColormap. @colormap:
@color: a #GdkColor, with the color to change @color:
in the <structfield>pixel</structfield> field,
and the new value in the remaining fields.
@Returns: @Returns:
<!-- ##### FUNCTION gdk_color_equal ##### --> <!-- ##### FUNCTION gdk_color_equal ##### -->
<para> <para>
Compares two colors.
</para> </para>
@colora: a #GdkColor. @colora:
@colorb: another #GdkColor. @colorb:
@Returns: %TRUE if the two colors compare equal @Returns:
<!-- ##### FUNCTION gdk_color_hash ##### --> <!-- ##### FUNCTION gdk_color_hash ##### -->
<para> <para>
A hash function suitable for using for a hash
table that stores #GdkColor's.
</para> </para>
@colora: a #GdkColor. @colora:
@Returns: The hash function appled to @colora @Returns:
...@@ -56,6 +56,15 @@ gdk_colormap_unref (GdkColormap *cmap) ...@@ -56,6 +56,15 @@ gdk_colormap_unref (GdkColormap *cmap)
g_object_unref (cmap); g_object_unref (cmap);
} }
/**
* gdk_colormap_get_visual:
* @colormap: a #GdkColormap.
*
* Returns the visual for which a given colormap was created.
*
* Return value: the visual of the colormap.
**/
GdkVisual * GdkVisual *
gdk_colormap_get_visual (GdkColormap *colormap) gdk_colormap_get_visual (GdkColormap *colormap)
{ {
...@@ -63,7 +72,19 @@ gdk_colormap_get_visual (GdkColormap *colormap) ...@@ -63,7 +72,19 @@ gdk_colormap_get_visual (GdkColormap *colormap)
return colormap->visual; return colormap->visual;
} }
/**
* gdk_colors_store:
* @colormap: a #GdkColormap.
* @colors: the new color values.
* @ncolors: the number of colors to change.
*
* Changes the value of the first @ncolors colors in
* a private colormap. This function is obsolete and
* should not be used. See gdk_color_change().
*
* Return value:
**/
void void
gdk_colors_store (GdkColormap *colormap, gdk_colors_store (GdkColormap *colormap,
GdkColor *colors, GdkColor *colors,
...@@ -82,23 +103,17 @@ gdk_colors_store (GdkColormap *colormap, ...@@ -82,23 +103,17 @@ gdk_colors_store (GdkColormap *colormap,
gdk_colormap_change (colormap, ncolors); gdk_colormap_change (colormap, ncolors);
} }
/*
*--------------------------------------------------------------
* gdk_color_copy
*
* Copy a color structure into new storage.
*
* Arguments:
* "color" is the color struct to copy.
*
* Results:
* A new color structure. Free it with gdk_color_free.
*
*--------------------------------------------------------------
*/
static GMemChunk *color_chunk; static GMemChunk *color_chunk;
/**
* gdk_color_copy:
* @color: a #GdkColor.
*
* Makes a copy of a color structure. The result