## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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.     -----------------------------------------------------------------------

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>

53.     with GlibTo API docTo specTo body; use GlibTo API docTo specTo body;

54.     with Glib.ObjectTo API docTo specTo body;

55.     with Glib.ValuesTo API docTo specTo body;

56.     with Gdk.VisualTo API docTo specTo body;

58.     package Gdk.ColorTo API docTo specTo body is

60.        type Gdk_ColorTo API docTo body 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.

67.        type Gdk_Color_Array is array (Natural range <>) of Gdk_ColorTo API docTo specTo body;

68.        --  An array of colors.

70.        Null_ColorTo API docTo body : constant Gdk_ColorTo API docTo specTo body;

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.

75.        subtype Gdk_Colormap is Gdk.Gdk_ColormapTo API docTo spec;

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.

82.        Null_Colormap : constant Gdk_ColormapTo API docTo spec;

84.        Wrong_Color : exception;

85.        --  Exception raised when some functions below could not find or allocate

86.        --  a color on the user's system.

88.        function Gdk_Color_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

89.        --  Return the internal gtk+ types associated with a color

91.        function Gdk_Colormap_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

92.        --  Return the internal gtk+ types associated with a colormap

94.        ---------------------------------------------

95.        -- Setting/Getting the fields of Gdk_Color --

96.        ---------------------------------------------

98.        procedure Set_RgbTo API docTo body (ColorTo API docTo body : out Gdk_ColorTo API docTo specTo body; Red, Green, Blue : Guint16To API docTo spec);

99.        --  Modify the fields of the color.

100.        --  You then have to allocate the color with one of the Alloc* functions

101.        --  above.

103.        procedure Set_PixelTo API docTo body (ColorTo API docTo body : in out Gdk_ColorTo API docTo specTo body; Pixel : Guint32To API docTo spec);

104.        --  This function should almost never be used. Instead, use Alloc_Color.

106.        function RedTo API docTo body (ColorTo API docTo body : Gdk_ColorTo API docTo specTo body) return Guint16To API docTo spec;

107.        --  Return the Red field of Color.

109.        function GreenTo API docTo body (ColorTo API docTo body : Gdk_ColorTo API docTo specTo body) return Guint16To API docTo spec;

110.        --  Return the Green field of Color.

112.        function BlueTo API docTo body (ColorTo API docTo body : Gdk_ColorTo API docTo specTo body) return Guint16To API docTo spec;

113.        --  Return the Blue field of Color.

115.        function PixelTo API docTo body (ColorTo API docTo body : Gdk_ColorTo API docTo specTo body) return Guint32To API docTo spec;

116.        --  Return the Pixel field of Color.

118.        ------------------------------------

119.        -- Creating and Destroying colors --

120.        ------------------------------------

122.        procedure Gdk_NewTo API docTo body

123.          (Colormap     : out Gdk_ColormapTo API docTo spec;

124.           Visual       : Gdk.Visual.Gdk_VisualTo API docTo spec;

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...

131.        procedure RefTo API docTo body (Colormap : Gdk_ColormapTo API docTo spec);

132.        --  Increment the ref-count for the color.

134.        procedure UnrefTo API docTo body (Colormap : Gdk_ColormapTo API docTo spec);

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.

139.        procedure ChangeTo API docTo body

140.          (Colormap : Gdk_ColormapTo API docTo spec; Ncolors : GintTo API docTo spec);

141.        --  Change the first Ncolors defined in Colormap.

143.        procedure Alloc_ColorsTo API docTo body

144.          (Colormap   : Gdk_ColormapTo API docTo spec;

145.           Colors     : in out Gdk_Color_ArrayTo API docTo spec;

146.           Writeable  : Boolean := False;

147.           Best_Match : Boolean := True;

148.           Success    : out Boolean_ArrayTo API docTo spec;

149.           Result     : out GintTo API docTo spec);

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.

158.        procedure Alloc_ColorTo API docTo body

159.          (Colormap   : Gdk_ColormapTo API docTo spec;

160.           ColorTo API docTo body      : in out Gdk_ColorTo API docTo specTo body;

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.

177.        procedure Free_ColorsTo API docTo body (Colormap : Gdk_ColormapTo API docTo spec; Colors : Gdk_Color_ArrayTo API docTo spec);

178.        --  Free Colors, assuming they are allocated in Colormap.

180.        procedure Get_VisualTo API docTo body

181.          (Colormap : Gdk_ColormapTo API docTo spec;

182.           Visual   : out Gdk.Visual.Gdk_VisualTo API docTo spec);

183.        --  Get the visual associated with a colormap.

184.        --  The main information you can get from there is the depth of the display.

186.        procedure CopyTo API docTo body (SourceTo API docTo body : Gdk_ColorTo API docTo specTo body; DestinationTo API docTo body : out Gdk_ColorTo API docTo specTo body);

187.        --  Copy the Source color to Destination.

189.        function ParseTo API docTo body (Spec : String) return Gdk_ColorTo API docTo specTo body;

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.

207.        function EqualTo API docTo body (ColoraTo API docTo body, ColorbTo API docTo body : Gdk_ColorTo API docTo specTo body) return Boolean;

208.        --  True if the Red, Green and Blue components of both colors are equal.

210.        --  <doc_ignore>

211.        --------------------------

212.        -- Deprecated functions --

213.        --------------------------

215.        procedure StoreTo API docTo body (Colormap : Gdk_ColormapTo API docTo spec; Colors : Gdk_Color_ArrayTo API docTo spec);

216.        --  Store the Colors in the Colormap.

218.        procedure AllocTo API docTo body

219.          (Colormap   : Gdk_ColormapTo API docTo spec;

220.           Contiguous : Boolean;

221.           Planes     : Gulong_ArrayTo API docTo spec;

222.           Pixels     : Gulong_ArrayTo API docTo spec;

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.

233.        procedure FreeTo API docTo body

234.          (Colormap : Gdk_ColormapTo API docTo spec;

235.           Pixels   : Gulong_ArrayTo API docTo spec;

236.           Planes   : GulongTo API docTo spec);

237.        --  Free some colors in the colormap.

238.        --  See XFreeColors(3) on Unix systems.

240.        function WhiteTo API docTo body (Colormap : Gdk_ColormapTo API docTo spec) return Gdk_ColorTo API docTo specTo body;

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.

245.        function BlackTo API docTo body (Colormap : Gdk_ColormapTo API docTo spec) return Gdk_ColorTo API docTo specTo body;

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.

250.        procedure AllocTo API docTo body

251.          (Colormap  : Gdk_ColormapTo API docTo spec;

252.           ColorTo API docTo body     : in out Gdk_ColorTo API docTo specTo body);

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

257.        procedure ChangeTo API docTo body

258.          (Colormap  : Gdk_ColormapTo API docTo spec;

259.           ColorTo API docTo body     : in out Gdk_ColorTo API docTo specTo body;

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.

265.        function To_StringTo API docTo body (ColorTo API docTo body : Gdk_ColorTo API docTo specTo body) return String;

266.        --  Return the RGB values of Color under the form "#RRGGBB".

267.        --  Directly usable by Parse, see above.

269.        ----------------

270.        -- Properties --

271.        ----------------

272.        --  See the package Glib.Properties for more information on how to

273.        --  use properties

275.        type Property_Gdk_Color is new Glib.PropertyTo API docTo spec;

277.        procedure Set_PropertyTo API docTo body

278.          (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

279.           Name   : Property_Gdk_ColorTo API docTo spec;

280.           ValueTo API docTo body  : Gdk_ColorTo API docTo specTo body);

282.        function Get_PropertyTo API docTo body

283.          (Object : access Glib.Object.GObject_RecordTo API docTo specTo body'Class;

284.           Name   : Property_Gdk_ColorTo API docTo spec) return Gdk_ColorTo API docTo specTo body;

286.        procedure Set_ValueTo API docTo body (ValueTo API docTo body : out Glib.Values.GValueTo API docTo specTo body; ValTo API docTo body : Gdk_ColorTo API docTo specTo body);

287.        function  Get_ValueTo API docTo body (ValueTo API docTo body : Glib.Values.GValueTo API docTo specTo body) return Gdk_ColorTo API docTo specTo body;

288.        --  Store or retrieve a color from a value

290.        --  </doc_ignore>

292.     private

293.        Null_ColormapTo API docTo spec : constant Gdk_ColormapTo API docTo spec := null;

295.        type Gdk_ColorTo API docTo spec is record

296.           Pixel : Guint32To API docTo spec;

297.           Red   : Guint16To API docTo spec;

298.           Green : Guint16To API docTo spec;

299.           Blue  : Guint16To API docTo spec;

300.        end record;

301.        pragma Convention (C, Gdk_ColorTo API docTo specTo body);

302.        --  The fields are to be chosen between 0 and 65535, not 0 and 255!!!

304.        Null_ColorTo API docTo spec : constant Gdk_ColorTo API docTo specTo body := (Guint32To API docTo spec'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.

310.        pragma Import (C, Gdk_Color_TypeTo API docTo spec, "gdk_color_get_type");

312.        pragma Inline (Set_RgbTo API docTo specTo body);

313.        pragma Inline (Set_PixelTo API docTo specTo body);

314.        pragma Inline (RedTo API docTo specTo body);

315.        pragma Inline (GreenTo API docTo specTo body);

316.        pragma Inline (BlueTo API docTo specTo body);

317.        pragma Inline (PixelTo API docTo specTo body);

318.        pragma Inline (Set_PropertyTo API docTo specTo body);

319.        pragma Inline (Get_PropertyTo API docTo specTo body);

320.        pragma Import (C, RefTo API docTo spec, "gdk_colormap_ref");

321.        pragma Import (C, UnrefTo API docTo spec, "gdk_colormap_unref");

322.        pragma Import (C, Gdk_Colormap_TypeTo API docTo spec, "gdk_colormap_get_type");

323.     end Gdk.ColorTo API docTo specTo body;

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