## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --              GtkAda - Ada95 binding for Gtk+/Gnome                --

3.     --                                                                   --

4.     --                   Copyright (C) 2004-2010, AdaCore                --

5.     --                                                                   --

6.     -- This library is free software; you can redistribute it and/or     --

7.     -- modify it under the terms of the GNU General Public               --

8.     -- License as published by the Free Software Foundation; either      --

9.     -- version 2 of the License, or (at your option) any later version.  --

10.     --                                                                   --

11.     -- This library is distributed in the hope that it will be useful,   --

12.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

13.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

14.     -- General Public License for more details.                          --

15.     --                                                                   --

16.     -- You should have received a copy of the GNU General Public         --

17.     -- License along with this library; if not, write to the             --

18.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

19.     -- Boston, MA 02111-1307, USA.                                       --

20.     --                                                                   --

21.     -- As a special exception, if other files instantiate generics from  --

22.     -- this unit, or you link this unit with other files to produce an   --

23.     -- executable, this  unit  does not  by itself cause  the resulting  --

24.     -- executable to be covered by the GNU General Public License. This  --

25.     -- exception does not however invalidate any other reasons why the   --

26.     -- executable file  might be covered by the  GNU Public License.     --

27.     -----------------------------------------------------------------------

29.     --  <description>

30.     --  Browse the available stock icons in the list of stock IDs found here. You

31.     --  can also use the gtk-demo application for this purpose.

32.     --

33.     --  An icon factory manages a collection of Gtk_Icon_Set; a Gtk_Icon_Set

34.     --  manages set of variants of a particular icon (i.e. a Gtk_Icon_Set contains

35.     --  variants for different sizes and widget states). Icons in an icon factory

36.     --  are named by a stock ID, which is a simple string identifying the icon.

37.     --  Each Gtk_Style has a list of Gtk_Icon_Factory derived from the current

38.     --  theme; those icon factories are consulted first when searching for an icon.

39.     --  If the theme doesn't set a particular icon, GTK+ looks for the icon in a

40.     --  list of default icon factories, maintained by gtk.icon_factory.add_default

41.     --  and gtk.icon_factory.remove_default. Applications with icons should add

42.     --  default icon factory with their icons, which will allow themes to override

43.     --  the icons for the application.

44.     --

45.     --  To display an icon, always use Lookup_Icon_Set on the widget that

46.     --  will display the icon, or the convenience function Gtk.Widget.Render_Icon.

47.     --  These functions take the theme into account when looking up the icon to use

48.     --  for a given stock ID.

49.     --  </description>

50.     --  <c_version>2.8.17</c_version>

51.     --  <see>Gtk.Icon_Theme</see>

53.     with Glib.ObjectTo API docTo specTo body;

54.     with Gdk.PixbufTo API docTo specTo body;

55.     with Gtk.EnumsTo API docTo specTo body;

56.     with Gtk.SettingsTo API docTo specTo body;

57.     with Gtk.StyleTo API docTo specTo body;

58.     with Gtk.WidgetTo API docTo specTo body;

60.     package Gtk.Icon_FactoryTo API docTo specTo body is

62.        --------------------

63.        -- Icon factories --

64.        --------------------

66.        type Gtk_Icon_Factory_RecordTo API docTo body is new Glib.Object.GObject_RecordTo API docTo specTo body with private;

67.        type Gtk_Icon_Factory is access all Gtk_Icon_Factory_RecordTo API docTo specTo body'Class;

69.        procedure Gtk_NewTo API docTo body (Widget : out Gtk_Icon_FactoryTo API docTo spec);

70.        procedure InitializeTo API docTo body (Widget : access Gtk_Icon_Factory_RecordTo API docTo specTo body'Class);

71.        --  Creates or initializes a new Icon_Factory.

73.        function Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

74.        --  Return the internal value associated with a Icon_Factory.

76.        procedure Add_DefaultTo API docTo body (Factory : access Gtk_Icon_Factory_RecordTo API docTo specTo body);

77.        --  Adds an icon factory to the list of icon factories searched by

78.        --  Lookup_Icon_Set. This means that, for example,

79.        --  Gtk.Image.New_From_Stock will be able to find icons in Factory.

80.        --  There will normally be an icon factory added for each library or

81.        --  application that comes with icons. The default icon factories

82.        --  can be overridden by themes.

84.        procedure Remove_DefaultTo API docTo body (Factory : access Gtk_Icon_Factory_RecordTo API docTo specTo body);

85.        --  Removes an icon factory from the list of default icon

86.        --  factories. Not normally used; you might use it for a library that

87.        --  can be unloaded or shut down.

89.        ---------------

90.        -- Icon sets --

91.        ---------------

93.        --  An icon set represents a single icon in various sizes and widget states.

94.        --  It can provide a Gdk_Pixbuf for a given size and state on request, and

95.        --  automatically caches some of the rendered Gdk_Pixbuf objects.

96.        --

97.        --  Normally you would use Gtk.Widget.Render_Icon instead of using icon sets

98.        --  directly. The one case where you'd use an icon set is to create

99.        --  application-specific icon sets to place in an icon factory.

101.        type Gtk_Icon_Set is new Glib.C_ProxyTo API docTo spec;

103.        function Gtk_NewTo API docTo body return Gtk_Icon_SetTo API docTo spec;

104.        --  Create an empty Gtk_Icon_Set.

106.        function Gtk_NewTo API docTo body (Pixbuf : Gdk.Pixbuf.Gdk_PixbufTo API docTo spec) return Gtk_Icon_SetTo API docTo spec;

107.        --  Creates a new icon set with Pixbuf as the default/fallback source

108.        --  image. If you don't add any additional icon sources (see below) to the

109.        --  icon set, all variants of the icon will be created from Pixbuf,

110.        --  using scaling, pixelation, etc. as required to adjust the icon size

111.        --  or make the icon look insensitive/prelighted.

113.        procedure AddTo API docTo body

114.          (Factory  : access Gtk_Icon_Factory_RecordTo API docTo specTo body;

115.           Stock_Id : String;

116.           Set      : Gtk_Icon_SetTo API docTo spec);

117.        --  Adds the given icon set to the icon factory, under the name Stock_Id.

118.        --  Stock_Id should be namespaced for your application, e.g.

119.        --  "myapp-whatever-icon".  Normally applications create an icon factory,

120.        --  then add it to the list of default factories with Add_Default. Then they

121.        --  pass the Stock_Id to widgets such as Gtk_Image to display the icon.

122.        --  Themes can provide an icon with the same name (such as

123.        --  "myapp-whatever-icon") to override your application's default icons. If

124.        --  an icon already existed in Factory for Stock_Id, it is unreferenced and

125.        --  replaced with the new icon set.

127.        function Lookup_Icon_SetTo API docTo body

128.          (Style  : access Gtk.Style.Gtk_Style_RecordTo API docTo spec'Class; Stock_Id : String)

129.           return Gtk_Icon_SetTo API docTo spec;

130.        --  Retrieve an icon set by its name. The icon might exist in various sizes,

131.        --  that can be manipulated through the result set

133.        function LookupTo API docTo body

134.          (Factory  : access Gtk_Icon_Factory_RecordTo API docTo specTo body;

135.           Stock_Id : String) return Gtk_Icon_SetTo API docTo spec;

136.        --  Looks up Stock_Id in the icon factory, returning an icon set if found,

137.        --  otherwise null. For display to the user, you should use

138.        --  Lookup_Icon_Set on the Gtk_Style for the widget that will

139.        --  display the icon, instead of using this function directly, so that

140.        --  themes are taken into account.

142.        function Lookup_DefaultTo API docTo body (Stock_Id : String) return Gtk_Icon_SetTo API docTo spec;

143.        --  Looks for an icon in the list of default icon factories.  For

144.        --  display to the user, you should use Lookup_Icon_Set on

145.        --  the Gtk_Style for the widget that will display the icon, instead of

146.        --  using this function directly, so that themes are taken into

147.        --  account.

149.        function Icon_Set_Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

150.        --  Return the internal type value for Gtk_Icon_Set

152.        function CopyTo API docTo body (Icon_Set : Gtk_Icon_SetTo API docTo spec) return Gtk_Icon_SetTo API docTo spec;

153.        pragma Import (C, CopyTo API docTo spec, "gtk_icon_set_copy");

154.        --  Copies Icon_Set by value.

156.        function Get_SizesTo API docTo body (Icon_Set : Gtk_Icon_SetTo API docTo spec) return Gint_ArrayTo API docTo spec;

157.        --  Obtains a list of icon sizes this icon set can render.

159.        procedure RefTo API docTo body   (Icon_Set : Gtk_Icon_SetTo API docTo spec);

160.        procedure UnrefTo API docTo body (Icon_Set : Gtk_Icon_SetTo API docTo spec);

161.        pragma Import (C, RefTo API docTo spec,   "gtk_icon_set_ref");

162.        pragma Import (C, UnrefTo API docTo spec, "gtk_icon_set_unref");

163.        --  Increase or decrease the reference counting for the icon set. When this

164.        --  reaches 0, the memory is reclaimed

166.        function Render_IconTo API docTo body

167.          (Icon_Set  : Gtk_Icon_SetTo API docTo spec;

168.           Style     : access Gtk.Style.Gtk_Style_RecordTo API docTo spec'Class;

169.           DirectionTo API docTo body : Gtk.Enums.Gtk_Text_DirectionTo API docTo spec;

170.           StateTo API docTo body     : Gtk.Enums.Gtk_State_TypeTo API docTo spec;

171.           Size      : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

172.           Widget    : Gtk.Widget.Gtk_WidgetTo API docTo spec := null;

173.           Detail    : String := "")

174.           return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

175.        --  Renders an icon using Render_Icon below. In most cases, the other

176.        --  version of Render_Icon is better, since it automatically provides most

177.        --  of the arguments from the current widget settings. This function never

178.        --  returns null; if the icon can't be rendered (perhaps because an image

179.        --  file fails to load), a default "missing image" icon will be returned

180.        --  instead.

181.        --  Widget is the widget that will display the icon, or null. This is

182.        --  typically used to determine the screen (and thus the colormap depth).

183.        --  Detail is the string to pass to the theme engine to provide more

184.        --  information. Passing anything but the empty string will disable

185.        --  caching.

187.        ------------------

188.        -- Icon sources --

189.        ------------------

191.        --  An icon source contains a Gdk_Pixbuf (or image filename) that serves as

192.        --  the base image for one or more of the icons in an icon set, along with a

193.        --  specification for which icons in the icon set will be based on that

194.        --  pixbuf or image file. An icon set contains a set of icons that represent

195.        --  "the same" logical concept in different states, different global text

196.        --  directions, and different sizes.

197.        --

198.        --  So for example a web browser's "Back to Previous Page" icon might point

199.        --  in a different direction in Hebrew and in English; it might look

200.        --  different when insensitive; and it might change size depending on

201.        --  toolbar mode (small/large icons). So a single icon set would contain all

202.        --  those variants of the icon. An icon set contains a list of icon sources

203.        --  from which it can derive specific icon variants in the set.

204.        --

205.        --  In the simplest case, an icon set contains one source pixbuf from which

206.        --  it derives all variants.

207.        --

208.        --  If you want to use a different base pixbuf for different icon variants,

209.        --  you create multiple icon sources, mark which variants they'll be used to

210.        --  create, and add them to the icon set with Add_Source (see below).

211.        --

212.        --  By default, the icon source has all parameters wildcarded. That is, the

213.        --  icon source will be used as the base icon for any desired text

214.        --  direction, widget state, or icon size.

216.        type Gtk_Icon_Source is new Glib.C_ProxyTo API docTo spec;

218.        function Gtk_NewTo API docTo body return Gtk_Icon_SourceTo API docTo spec;

219.        --  Create a new icon source.

221.        function Icon_Source_CopyTo API docTo body (Source : Gtk_Icon_SourceTo API docTo spec) return Gtk_Icon_SourceTo API docTo spec;

222.        --  Returns a copy of Gtk_Icon_Source. This function is generally not

223.        --  useful

225.        function Icon_Source_Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

226.        --  Return the internal type used for Gtk_Icon_Source

228.        function Render_IconTo API docTo body

229.          (Style     : access Gtk.Style.Gtk_Style_RecordTo API docTo spec'Class;

230.           Source    : Gtk.Icon_Factory.Gtk_Icon_SourceTo API docTo spec;

231.           DirectionTo API docTo body : Gtk.Enums.Gtk_Text_DirectionTo API docTo spec;

232.           StateTo API docTo body     : Gtk.Enums.Gtk_State_TypeTo API docTo spec;

233.           Size      : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

234.           Widget    : Gtk.Widget.Gtk_WidgetTo API docTo spec := null;

235.           Detail    : String := "")

236.           return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

237.        --  Renders the icon specified by Source at the given Size according to the

238.        --  given parameters and returns the result in pixbuf.

240.        procedure Add_SourceTo API docTo body

241.          (Set    : Gtk_Icon_SetTo API docTo spec;

242.           Source : Gtk_Icon_SourceTo API docTo spec);

243.        --  Icon sets have a list of icon sources, which they use as base

244.        --  icons for rendering icons in different states and sizes. Icons are

245.        --  scaled, made to look insensitive, etc. in Gtk.Icon.Set_Render_Icon,

246.        --  but an icon set needs base images to work with. The base images and

247.        --  when to use them are described by an icon source.

248.        --  This function copies Source, so you can reuse the same source

249.        --  immediately without affecting the icon set.

251.        procedure FreeTo API docTo body (Source : Gtk_Icon_SourceTo API docTo spec);

252.        --  Free memory allocated to Source.

254.        procedure Set_FilenameTo API docTo body

255.          (Source : Gtk_Icon_SourceTo API docTo spec; Filename : String);

256.        function Get_FilenameTo API docTo body (Source : Gtk_Icon_SourceTo API docTo spec) return String;

257.        --  Set the name of an image file to use as a base image when creating

258.        --  icon variants for an icon set. The filename must be absolute.

260.        procedure Set_PixbufTo API docTo body

261.          (Source : Gtk_Icon_SourceTo API docTo spec; Pixbuf : Gdk.Pixbuf.Gdk_PixbufTo API docTo spec);

262.        function Get_PixbufTo API docTo body

263.          (Source : Gtk_Icon_SourceTo API docTo spec) return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

264.        --  Set a pixbuf to use as a base image when creating icon variants

265.        --  for an icon set. If an icon source has both a filename and a pixbuf

266.        --  set, the pixbuf will take priority.

268.        procedure Set_SizeTo API docTo body

269.          (Source : Gtk_Icon_SourceTo API docTo spec; Size : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec);

270.        function Get_SizeTo API docTo body

271.          (Source : Gtk_Icon_SourceTo API docTo spec) return Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

272.        --  Set the icon size this icon source is intended to be used with

274.        procedure Set_Icon_NameTo API docTo body (Source : Gtk_Icon_SourceTo API docTo spec; Icon_Name : String);

275.        function  Get_Icon_NameTo API docTo body (Source : Gtk_Icon_SourceTo API docTo spec) return String;

276.        --  Retrieves the source icon name, or "" if none is set. The icon comes

277.        --  from an icon theme in this case.

279.        procedure Set_Size_WildcardedTo API docTo body

280.          (Source : Gtk_Icon_SourceTo API docTo spec; Wildcarded : Boolean);

281.        function Get_Size_WildcardedTo API docTo body (Source : Gtk_Icon_SourceTo API docTo spec) return Boolean;

282.        --  Change the wilcarded state of the size for the icon source.

283.        --

284.        --  If the icon size is wildcarded, this source can be used as the base

285.        --  image for an icon of any size.  if the size is not wildcarded, then

286.        --  the size the source applies to should be set with Set_Size,

287.        --  and the icon source will only be used with that specific size.

288.        --

289.        --  Gtk prefers non-wildcarded sources (exact matches) over wildcarded

290.        --  sources, and will use an exact match when possible.

291.        --

292.        --  Gtk will normally scale wildcarded source images to produce

293.        --  an appropriate icon at a given size, but will not change the size

294.        --  of source images that match exactly.

296.        procedure Set_Direction_WildcardedTo API docTo body

297.          (Source  : Gtk_Icon_SourceTo API docTo spec;  Setting : Boolean);

298.        function Get_Direction_WildcardedTo API docTo body

299.          (Source : Gtk_Icon_SourceTo API docTo spec) return Boolean;

300.        --  If the text direction is wildcarded, this source can be used as the base

301.        --  image for an icon in any Gtk_Text_Direction.

302.        --  If the text direction is not wildcarded, then the text direction the

303.        --  icon source applies to should be set with Set_Direction(), and the icon

304.        --  source will only be used with that text direction.

305.        --  Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over

306.        --  wildcarded sources, and will use an exact match when possible

308.        procedure Set_DirectionTo API docTo body

309.          (Source : Gtk_Icon_SourceTo API docTo spec; Direction : Gtk.Enums.Gtk_Text_DirectionTo API docTo spec);

310.        function Get_DirectionTo API docTo body

311.          (Source : Gtk_Icon_SourceTo API docTo spec) return Gtk.Enums.Gtk_Text_DirectionTo API docTo spec;

312.        --  Sets the text direction this icon source is intended to be used

313.        --  with.

314.        --  Setting the text direction on an icon source makes no difference if the

315.        --  text direction is wildcarded. Therefore, you should usually call

316.        --  Set_Direction_Wildcarded() to un-wildcard it in addition to calling this

317.        --  function.

319.        procedure Set_State_WildcardedTo API docTo body

320.          (Source  : Gtk_Icon_SourceTo API docTo spec;  Setting : Boolean);

321.        function Get_State_WildcardedTo API docTo body (Source  : Gtk_Icon_SourceTo API docTo spec) return Boolean;

322.        --  If the widget state is wildcarded, this source can be used as the base

323.        --  image for an icon in any Gtk_State_Type. If the widget state is not

324.        --  wildcarded, then the state the source applies to should be set with

325.        --  Set_State and the icon source will only be used with that specific

326.        --  state.

327.        --  Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over

328.        --  wildcarded sources, and will use an exact match when possible.

329.        --  Gtk_Icon_Set will normally transform wildcarded source images to produce

330.        --  an appropriate icon for a given state, for example lightening an image

331.        --  on prelight, but will not modify source images that match exactly.

333.        procedure Set_StateTo API docTo body

334.          (Source : Gtk_Icon_SourceTo API docTo spec; State  : Gtk.Enums.Gtk_State_TypeTo API docTo spec);

335.        function Get_StateTo API docTo body

336.          (Source : Gtk_Icon_SourceTo API docTo spec) return Gtk.Enums.Gtk_State_TypeTo API docTo spec;

337.        --  Sets the widget state this icon source is intended to be used

338.        --  with.

339.        --  Setting the widget state on an icon source makes no difference if the

340.        --  state is wildcarded. Therefore, you should usually call

341.        --  Set_State_Wildcarded to un-wildcard it in addition to calling this

342.        --  function.

344.        ----------------

345.        -- Icon sizes --

346.        ----------------

347.        --  There are a number of predefined icon sizes (see gtk-enums.ads). These

348.        --  are used in the various gtk+ contexts. However, you can also define your

349.        --  own icon sizes to use in your application.

351.        function Icon_Size_From_NameTo API docTo body (Name : String) return Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

352.        --  Looks up the icon size associated with Name.

353.        --  Predefined icon sizes are associated with the following names:

354.        --    Icon_Size_Menu          => "gtk-menu"          (16x16)

355.        --    Icon_Size_Button        => "gtk-button"        (20x20)

356.        --    Icon_Size_Small_Toolbar => "gtk-small-toolbar" (18x18)

357.        --    Icon_Size_Large_Toolbar => "gtk-large-toolbar" (24x24)

358.        --    Icon_Size_Dnd           => "gtk-dnd"           (32x32)

359.        --    Icon_Size_Dialog        => "gtk-dialog"        (48x48)

360.        --  You can also define your own names (see Icon_Size_Register)

362.        function Icon_Size_Get_NameTo API docTo body (Size : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec) return String;

363.        --  Gets the canonical name of the given icon size

365.        procedure Icon_Size_LookupTo API docTo body

366.          (Size          : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

367.           Width, Height : out GintTo API docTo spec);

368.        --  Obtains the pixel size of a semantic icon size, possibly

369.        --  modified by user preferences for the default Gtk_Settings.

370.        --  (See Icon_Size_Lookup_For_Settings).

371.        --  This function isn't normally needed, Render_Icon is the usual way to get

372.        --  an icon for rendering, then just look at the size of the rendered

373.        --  pixbuf. The rendered pixbuf may not even correspond to the width/height

374.        --  returned by Icon_Size_Lookup, because themes are free to render the

375.        --  pixbuf however they like, including changing the usual size.

376.        --  Sizes are set to -1 if Size is invalid.

378.        procedure Icon_Size_Lookup_For_SettingsTo API docTo body

379.          (Settings : access Gtk.Settings.Gtk_Settings_RecordTo API docTo spec'Class;

380.           Size     : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

381.           Width    : out GintTo API docTo spec;

382.           Height   : out GintTo API docTo spec);

383.        --  Obtains the pixel size of a semantic icon size, possibly modified by

384.        --  user preferences for a particular Gtk_Settings.

386.        function Icon_Size_RegisterTo API docTo body

387.          (Name   : String;

388.           Width  : GintTo API docTo spec;

389.           Height : GintTo API docTo spec)

390.           return Gtk.Enums.Gtk_Icon_SizeTo API docTo spec;

391.        --  Registers a new icon size, along the same lines as Icon_Size_Menu,

392.        --  etc. Returns the integer value for the size.

394.        procedure Icon_Size_Register_AliasTo API docTo body

395.          (Alias : String;  Target : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec);

396.        --  Registers Alias as another name for Target.

397.        --  So calling Icon_Size_From_Name with Alias as argument will return Target

399.        -------------

400.        -- Signals --

401.        -------------

403.        --  <signals>

404.        --  The following new signals are defined for this widget:

405.        --  </signals>

407.     private

408.        type Gtk_Icon_Factory_RecordTo API docTo spec is

409.          new Glib.Object.GObject_RecordTo API docTo specTo body with null record;

411.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_icon_factory_get_type");

412.        pragma Import (C, Set_SizeTo API docTo spec, "gtk_icon_source_set_size");

413.        pragma Import (C, Get_SizeTo API docTo spec, "gtk_icon_source_get_size");

414.        pragma Import (C, Icon_Set_Get_TypeTo API docTo spec, "gtk_icon_set_get_type");

415.        pragma Import (C, Icon_Source_Get_TypeTo API docTo spec, "gtk_icon_source_get_type");

416.        pragma Import (C, Set_DirectionTo API docTo spec, "gtk_icon_source_set_direction");

417.        pragma Import (C, Get_DirectionTo API docTo spec, "gtk_icon_source_get_direction");

418.        pragma Import (C, Set_StateTo API docTo spec, "gtk_icon_source_set_state");

419.        pragma Import (C, Get_StateTo API docTo spec, "gtk_icon_source_get_state");

420.        pragma Import (C, Icon_Source_CopyTo API docTo spec, "gtk_icon_source_copy");

422.     end Gtk.Icon_FactoryTo API docTo specTo body;