1-----------------------------------------------------------------------
2--               GtkAda - Ada95 binding for Gtk+/Gnome               --
3--                                                                   --
4--   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   --
5--                Copyright (C) 2000-2003 ACT-Europe                 --
6--                                                                   --
7-- This library is free software; you can redistribute it and/or     --
8-- modify it under the terms of the GNU General Public               --
9-- License as published by the Free Software Foundation; either      --
10-- version 2 of the License, or (at your option) any later version.  --
11--                                                                   --
12-- This library is distributed in the hope that it will be useful,   --
13-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --
14-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --
15-- General Public License for more details.                          --
16--                                                                   --
17-- You should have received a copy of the GNU General Public         --
18-- License along with this library; if not, write to the             --
19-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --
20-- Boston, MA 02111-1307, USA.                                       --
21--                                                                   --
22-- As a special exception, if other files instantiate generics from  --
23-- this unit, or you link this unit with other files to produce an   --
24-- executable, this  unit  does not  by itself cause  the resulting  --
25-- executable to be covered by the GNU General Public License. This  --
26-- exception does not however invalidate any other reasons why the   --
27-- executable file  might be covered by the  GNU Public License.     --
28-----------------------------------------------------------------------
29
30--  <description>
31--
32--  This package provides an interface to the color handling facilities in
33--  gtk+. It is able to handle any kind of visual (monochrome, greyscale,
34--  color with different depths, ...), but provides a common and easy
35--  interface for all of them.
36--  Some of these functions expect a Colormap. There are two ways you can
37--  get such a colormap, either a system default colormap or a per-widget
38--  colormap. It is recommended, unless you are writing your own new widget,
39--  to always use the system default Colormap. All the functions to get
40--  these colormaps are found in Gtk.Widget.
41--
42--  Getting the Red/Green/Blue components can be done through Parse, and is
43--  actually recommended, since the exact color generally depends on the
44--  visual your application is running on.
45--
46--  Note for users transitioning from gtk+ 1.2: the Get_System call is now
47--  obsolete, and you should use Gtk.Widget.Get_Default_Colormap instead.
48--
49--  </description>
50--  <c_version>1.3.6</c_version>
51--  <group>Gdk, the low-level API</group>
52
53with Glib; use Glib;
54with Glib.Object;
55with Glib.Values;
56with Gdk.Visual;
57
58package Gdk.Color is
59
60   type Gdk_Color is private;
61   --  A color to be displayed on the screen.
62   --  Currently, GtkAda only supports the RGB standard, ie each color is
63   --  set by its red, green and blue components.
64   --  An extra field (Pixel) is the internal representation of the color,
65   --  which is set once the color has been allocated.
66
67   type Gdk_Color_Array is array (Natural range <>) of Gdk_Color;
68   --  An array of colors.
69
70   Null_Color : constant Gdk_Color;
71   --  No color. For most functions, this will select the default color in the
72   --  context, although this exact specification depends on the function you
73   --  want to use.
74
75   subtype Gdk_Colormap is Gdk.Gdk_Colormap;
76   --  The set of colors the can be displayed on the screen.
77   --  When the screen is not a true-color screen (ie there is only a limited
78   --  number of possible colors, like 256), the colors are in fact indexes
79   --  into a colormap, which gives the components of the color.
80   --  This is the same concept as a palette.
81
82   Null_Colormap : constant Gdk_Colormap;
83
84   Wrong_Color : exception;
85   --  Exception raised when some functions below could not find or allocate
86   --  a color on the user's system.
87
88   function Gdk_Color_Type return Glib.GType;
89   --  Return the internal gtk+ types associated with a color
90
91   function Gdk_Colormap_Type return Glib.GType;
92   --  Return the internal gtk+ types associated with a colormap
93
94   ---------------------------------------------
95   -- Setting/Getting the fields of Gdk_Color --
96   ---------------------------------------------
97
98   procedure Set_Rgb (Color : out Gdk_Color; Red, Green, Blue : Guint16);
99   --  Modify the fields of the color.
100   --  You then have to allocate the color with one of the Alloc* functions
101   --  above.
102
103   procedure Set_Pixel (Color : in out Gdk_Color; Pixel : Guint32);
104   --  This function should almost never be used. Instead, use Alloc_Color.
105
106   function Red (Color : Gdk_Color) return Guint16;
107   --  Return the Red field of Color.
108
109   function Green (Color : Gdk_Color) return Guint16;
110   --  Return the Green field of Color.
111
112   function Blue (Color : Gdk_Color) return Guint16;
113   --  Return the Blue field of Color.
114
115   function Pixel (Color : Gdk_Color) return Guint32;
116   --  Return the Pixel field of Color.
117
118   ------------------------------------
119   -- Creating and Destroying colors --
120   ------------------------------------
121
122   procedure Gdk_New
123     (Colormap     : out Gdk_Colormap;
124      Visual       : Gdk.Visual.Gdk_Visual;
125      Private_Cmap : Boolean);
126   --  Create a new colormap for the visual.
127   --  If Private_Cmap is true, then the
128   --  colormap won't be modifiable outside this scope. This might result in
129   --  some strange colors on the display...
130
131   procedure Ref (Colormap : Gdk_Colormap);
132   --  Increment the ref-count for the color.
133
134   procedure Unref (Colormap : Gdk_Colormap);
135   --  Unref is the only way to destroy a colormap once you no longer need it.
136   --  Note that because gtk+ uses reference counts, the colormap will not
137   --  be actually destroyed while at least one object is using it.
138
139   procedure Change
140     (Colormap : Gdk_Colormap; Ncolors : Gint);
141   --  Change the first Ncolors defined in Colormap.
142
143   procedure Alloc_Colors
144     (Colormap   : Gdk_Colormap;
145      Colors     : in out Gdk_Color_Array;
146      Writeable  : Boolean := False;
147      Best_Match : Boolean := True;
148      Success    : out Boolean_Array;
149      Result     : out Gint);
150   --  Allocate a set of colors.
151   --  The parameters are the same as for Alloc_Color
152   --  Result is the number of colors not successfully allocated.
153   --
154   --  The size of the Boolean_Array is equal to the length of the
155   --  Colors_Array. Usage of an array of a different size will
156   --  probably lead to a Constraint_Error.
157
158   procedure Alloc_Color
159     (Colormap   : Gdk_Colormap;
160      Color      : in out Gdk_Color;
161      Writeable  : Boolean := False;
162      Best_Match : Boolean := True;
163      Success    : out Boolean);
164   --  Allocate a new color.
165   --  The fields RGB should have been set before calling this function.
166   --  If Writeable is True, the color will be allocated read/write, that can
167   --  be changed at any time. Not all visuals support this. On modern systems
168   --  this usage has become less useful than before, since redrawing the
169   --  screen with a new color is about as fast.
170   --  If Best_Match is True, and the exact color can not be allocated, GtkAda
171   --  will find the closest possible match, and modify the fields Red, Green
172   --  and Blue of Color.
173   --  Note that the allocation has more chances to succeed if Writeable is
174   --  False and Best_Match is True.
175   --  When you no longer use a color, you should call Free.
176
177   procedure Free_Colors (Colormap : Gdk_Colormap; Colors : Gdk_Color_Array);
178   --  Free Colors, assuming they are allocated in Colormap.
179
180   procedure Get_Visual
181     (Colormap : Gdk_Colormap;
182      Visual   : out Gdk.Visual.Gdk_Visual);
183   --  Get the visual associated with a colormap.
184   --  The main information you can get from there is the depth of the display.
185
186   procedure Copy (Source : Gdk_Color; Destination : out Gdk_Color);
187   --  Copy the Source color to Destination.
188
189   function Parse (Spec : String) return Gdk_Color;
190   --  Parse the string Spec, and get its Red/Green/Blue components.
191   --  The color is not allocated, and you need to call Alloc_Color.
192   --  If the string could not be parsed to an existing color, Wrong_Color is
193   --  raised.
194   --  The string can be one of :
195   --
196   --  - "RGB:FF/FF/FF" where the "FF" substrings are respectively the value
197   --    of the red, green and blue components. Some other prefixes than RGB
198   --    are defined in the X11 definition, please see some X11 documentation
199   --    (or the man page XParseColor on unix systems).
200   --
201   --  - "color_name" which can be any color name defined in the file rgb.txt
202   --    of the user's system. You should always check that Wrong_Color was not
203   --    raised, in case the color was not known on the user's system. This
204   --    string is case insensitive. Color names are not supported on Windows
205   --    systems.
206
207   function Equal (Colora, Colorb : Gdk_Color) return Boolean;
208   --  True if the Red, Green and Blue components of both colors are equal.
209
210   --  <doc_ignore>
211   --------------------------
212   -- Deprecated functions --
213   --------------------------
214
215   procedure Store (Colormap : Gdk_Colormap; Colors : Gdk_Color_Array);
216   --  Store the Colors in the Colormap.
217
218   procedure Alloc
219     (Colormap   : Gdk_Colormap;
220      Contiguous : Boolean;
221      Planes     : Gulong_Array;
222      Pixels     : Gulong_Array;
223      Succeeded  : out Boolean);
224   --  Allocate some Read/Write color cells.
225   --  Color cells' values can be changed
226   --  dynamically. The pixels allocated are returned in Pixels.
227   --  See XAllocColorCells(3) on Unix systems.
228   --  The Planes parameter can be used to nondestructively overlay one
229   --  set of graphics over another. See the X11 manual for more info.
230   --  Note that this is a low-level function which you should rarely
231   --  have to use.
232
233   procedure Free
234     (Colormap : Gdk_Colormap;
235      Pixels   : Gulong_Array;
236      Planes   : Gulong);
237   --  Free some colors in the colormap.
238   --  See XFreeColors(3) on Unix systems.
239
240   function White (Colormap : Gdk_Colormap) return Gdk_Color;
241   --  Return the default white color for the colormap.
242   --  If this color was not found or could not be allocated, Wrong_Color is
243   --  raised.
244
245   function Black (Colormap : Gdk_Colormap) return Gdk_Color;
246   --  Return the default black colors for the colormap.
247   --  If this color is not found or could not be allocated, Wrong_Color is
248   --  raised.
249
250   procedure Alloc
251     (Colormap  : Gdk_Colormap;
252      Color     : in out Gdk_Color);
253   --  Same function as Alloc_Colors above, but for a single color.
254   --  The color is allocated non-writeable, and the best-match is taken.
255   --  Raises Wrong_Color if the color could not be allocated
256
257   procedure Change
258     (Colormap  : Gdk_Colormap;
259      Color     : in out Gdk_Color;
260      Succeeded : out Boolean);
261   --  Change the Read/Write colormap cell corresponding to Color.
262   --  The new value is the one contained in the Red, Green and Blue
263   --  fields of Color.
264
265   function To_String (Color : Gdk_Color) return String;
266   --  Return the RGB values of Color under the form "#RRGGBB".
267   --  Directly usable by Parse, see above.
268
269   ----------------
270   -- Properties --
271   ----------------
272   --  See the package Glib.Properties for more information on how to
273   --  use properties
274
275   type Property_Gdk_Color is new Glib.Property;
276
277   procedure Set_Property
278     (Object : access Glib.Object.GObject_Record'Class;
279      Name   : Property_Gdk_Color;
280      Value  : Gdk_Color);
281
282   function Get_Property
283     (Object : access Glib.Object.GObject_Record'Class;
284      Name   : Property_Gdk_Color) return Gdk_Color;
285
286   procedure Set_Value (Value : out Glib.Values.GValue; Val : Gdk_Color);
287   function  Get_Value (Value : Glib.Values.GValue) return Gdk_Color;
288   --  Store or retrieve a color from a value
289
290   --  </doc_ignore>
291
292private
293   Null_Colormap : constant Gdk_Colormap := null;
294
295   type Gdk_Color is record
296      Pixel : Guint32;
297      Red   : Guint16;
298      Green : Guint16;
299      Blue  : Guint16;
300   end record;
301   pragma Convention (C, Gdk_Color);
302   --  The fields are to be chosen between 0 and 65535, not 0 and 255!!!
303
304   Null_Color : constant Gdk_Color := (Guint32'Last, 1, 0, 0);
305   --  Note: in the implementation of GtkAda, everytime a color is used, it
306   --  is important to test whether this is Null_Color or not. If it is, then
307   --  System.Null_Address should be passed to C instead of Null_Color'Address
308   --  so that gtk+ can provide a default value for colors.
309
310   pragma Import (C, Gdk_Color_Type, "gdk_color_get_type");
311
312   pragma Inline (Set_Rgb);
313   pragma Inline (Set_Pixel);
314   pragma Inline (Red);
315   pragma Inline (Green);
316   pragma Inline (Blue);
317   pragma Inline (Pixel);
318   pragma Inline (Set_Property);
319   pragma Inline (Get_Property);
320   pragma Import (C, Ref, "gdk_colormap_ref");
321   pragma Import (C, Unref, "gdk_colormap_unref");
322   pragma Import (C, Gdk_Colormap_Type, "gdk_colormap_get_type");
323end Gdk.Color;
324
325--  <example>
326--  --  Here is an example how you can allocate a new color, when you know
327--  --  its red/green/blue components: Note that we allocate white in fact
328--  --  since the maximal value for color components is 65535.
329--     Color   : Gdk_Color;
330--     Success : Boolean;
331--     Set_Rbg (Color, 65535, 65535, 65535);
332--     Alloc_Color (Colormap   => Gtk.Widget.Get_Default_Colormap,
333--                  Color      => Color,
334--                  Writeable  => False,
335--                  Best_Match => True,
336--                  Success    => Success);
337--     if not Success then
338--         ...;  --  allocation failed
339--     end if;
340--  </example>
341--
342--  missing:
343--  gdk_color_get_type
344--  gdk_colormap_get_type
345--  gdk_color_free,  not needed in Ada
346