## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2006-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.     --  Gtk_Icon_Theme provides a facility for looking up icons by name and size.

31.     --  The main reason for using a name rather than simply providing a filename is

32.     --  to allow different icons to be used depending on what icon theme is

33.     --  selecetd by the user. The operation of icon themes on Linux and Unix

34.     --  follows the Icon Theme Specification. There is a default icon theme, named

35.     --  hicolor where applications should install their icons, but more additional

36.     --  application themes can be installed as operating system vendors and users

37.     --  choose.

38.     --

39.     --  Named icons are similar to the Themeable Stock Images(3) facility, and the

40.     --  distinction between the two may be a bit confusing. A few things to keep in

41.     --  mind:

42.     --

43.     --  - Stock images usually are used in conjunction with Stock Items(3)., such

44.     --    as STOCK_OK or STOCK_OPEN. Named icons are easier to set up and

45.     --    therefore are more useful for new icons that an application wants to add,

46.     --    such as application icons or window icons.

47.     --

48.     --  - Stock images can only be loaded at the symbolic sizes defined by the

49.     --    Gtk_Icon_Size enumeration, or by custom sizes defined by

50.     --    Gtk.Icon_Factory.Icon_Size_Register, while named icons are more flexible

51.     --    and any pixel size can be specified.

52.     --

53.     --  - Because stock images are closely tied to stock items, and thus to actions

54.     --    in the user interface, stock images may come in multiple variants for

55.     --    different widget states or writing directions.

56.     --

57.     --  A good rule of thumb is that if there is a stock image for what you want to

58.     --  use, use it, otherwise use a named icon. It turns out that internally stock

59.     --  images are generally defined in terms of one or more named icons. (An

60.     --  example of the more than one case is icons that depend on writing

61.     --  direction; STOCK_GO_FORWARD uses the two themed icons

62.     --  "gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".)

63.     --

64.     --  In many cases, named themes are used indirectly, via Gtk_Image or stock

65.     --  items, rather than directly, but looking up icons directly is also simple.

66.     --  The Gtk_Icon_Theme object acts as a database of all the icons in the

67.     --  current theme. You can create new Gtk_Icon_Theme objects, but its much more

68.     --  efficient to use the standard icon theme for the Gdk_Screen so that the

69.     --  icon information is shared with other people looking up icons. In the case

70.     --  where the default screen is being used, looking up an icon can be as simple

71.     --  as:

72.     --      Theme := Get_Default;

73.     --      Pixbuf := Load_Icon (Theme, "my-icon-name", 48, 0, Error);

74.     --      if Pixbuf = null then

75.     --         Put_Line ("Error " & Get_Message (Error);

76.     --         Error_Free (Error);

77.     --      end if;

78.     --  </description>

79.     --  <c_version>2.16.6</c_version>

80.     --  <group>Display widgets</group>

81.     --  <see>Gtk.Icon_Factory</see>

83.     with Gdk.PixbufTo API docTo specTo body;

84.     with Gdk.RectangleTo API docTo specTo body;

85.     with Gdk.TypesTo API docTo spec;

86.     with Glib.ErrorTo API docTo specTo body;

87.     with Glib.G_IconTo API docTo specTo body;

88.     with Glib.ObjectTo API docTo specTo body;

89.     with Gtk.EnumsTo API docTo specTo body;

90.     with GNAT.Strings;

92.     package Gtk.Icon_ThemeTo API docTo specTo body is

94.        type Gtk_Icon_Theme_Record is new Glib.Object.GObject_RecordTo API docTo specTo body with

95.          null record;

96.        type Gtk_Icon_Theme is access all Gtk_Icon_Theme_RecordTo API docTo spec'Class;

98.        type Gtk_Icon_Lookup_Flags is mod GintTo API docTo spec'Last;

99.        Icon_Lookup_No_Svg      : constant Gtk_Icon_Lookup_FlagsTo API docTo spec := 2 ** 0;

100.        Icon_Lookup_Force_Svg   : constant Gtk_Icon_Lookup_FlagsTo API docTo spec := 2 ** 1;

101.        Icon_Lookup_Use_Builtin : constant Gtk_Icon_Lookup_FlagsTo API docTo spec := 2 ** 2;

102.        --  Used to specify options for Lookup_Icon.

103.        --  No_Svg: never return SVG icons, even if gdk-pixbuf supports them.

104.        --  Force_Svg: return SVG even if gdk-pixbuf doesn't support them.

105.        --  Use_Builtin: including builtin icons as well as files.

107.        ---------------

108.        -- Icon_Info --

109.        ---------------

111.        type Gtk_Icon_Info is new Glib.C_ProxyTo API docTo spec;

113.        function Icon_Info_Get_TypeTo API docTo body return GTypeTo API docTo spec;

115.        function New_For_PixbufTo API docTo body

116.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

117.           Pixbuf     : Gdk.Pixbuf.Gdk_PixbufTo API docTo spec)

118.           return Gtk_Icon_InfoTo API docTo spec;

119.        --  Creates a Gtk_Icon_Info for a Gtk_Pixbuf.

121.        function CopyTo API docTo body (Icon_Info : Gtk_Icon_InfoTo API docTo spec) return Gtk_Icon_InfoTo API docTo spec;

122.        --  Make a copy of a Icon_Info

124.        procedure FreeTo API docTo body (Icon_Info : Gtk_Icon_InfoTo API docTo spec);

125.        --  Free a Gtk_Icon_Info and associated information

127.        function Get_Attach_PointsTo API docTo body

128.          (Icon_Info : Gtk_Icon_InfoTo API docTo spec) return Gdk.Types.Gdk_Points_ArrayTo API docTo spec;

129.        --  Fetches the set of attach points for an icon. An attach point is a

130.        --  location in the icon that can be used as anchor points for attaching

131.        --  emblems or overlays to the icon.

133.        function Get_Base_SizeTo API docTo body (Icon_Info : Gtk_Icon_InfoTo API docTo spec) return GintTo API docTo spec;

134.        --  Gets the base size for the icon. The base size is a size for the icon

135.        --  that was specified by the icon theme creator. This may be different than

136.        --  the actual size of image; an example of this is small emblem icons that

137.        --  can be attached to a larger icon. These icons will be given the same

138.        --  base size as the larger icons to which they are attached.

139.        --

140.        --  Return value: the base size, or 0, if no base size is known for the

141.        --  icon.

143.        function Get_Builtin_PixbufTo API docTo body

144.          (Icon_Info : Gtk_Icon_InfoTo API docTo spec) return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

145.        --  Gets the built-in image for this icon, if any. To allow GTK+ to use

146.        --  built in icon images, you must pass the %GTK_ICON_LOOKUP_USE_BUILTIN to

147.        --  Gtk.Icon_Theme.Lookup_Icon.

148.        --

149.        --  Return value: the built-in image pixbuf, or null. No extra reference is

150.        --  added to the returned pixbuf, so if you want to keep it around, you must

151.        --  use Ref. The returned image must not be modified.

153.        function Get_Display_NameTo API docTo body (Icon_Info : Gtk_Icon_InfoTo API docTo spec) return String;

154.        --  Gets the display name for an icon. A display name is a string to be used

155.        --  in place of the icon name in a user visible context like a list of

156.        --  icons.

158.        procedure Get_Embedded_RectTo API docTo body

159.          (Icon_Info              : Gtk_Icon_InfoTo API docTo spec;

160.           RectangleTo API docTo body              : in out Gdk.Rectangle.Gdk_RectangleTo API docTo spec;

161.           Has_Embedded_Rectangle : out Boolean);

162.        --  Gets the coordinates of a rectangle within the icon that can be used for

163.        --  display of information such as a preview of the contents of a text file.

164.        --  See Set_Raw_Coordinates for further information about the coordinate

165.        --  system.

166.        --  Rectangle is only set if Has_Embedded_Rectangle is set to True.

168.        function Get_FilenameTo API docTo body (Icon_Info : Gtk_Icon_InfoTo API docTo spec) return String;

169.        --  Gets the filename for the icon. If the %GTK_ICON_LOOKUP_USE_BUILTIN flag

170.        --  was passed to Lookup_Icon, there may be no filename if a builtin icon is

171.        --  returned; in this case, you should use Get_Builtin_Pixbuf.

172.        --  Return value: the filename for the icon, or "" if Get_Builtin_Pixbuf()

173.        --  should be used instead.

175.        function Load_IconTo API docTo body

176.          (Icon_Info : Gtk_Icon_InfoTo API docTo spec;

177.           Error     : Glib.Error.GError_AccessTo API docTo spec := null)

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

179.        --  Renders an icon previously looked up in an icon theme using Lookup_Icon;

180.        --  the size will be based on the size passed to Lookup_Icon. Note that the

181.        --  resulting pixbuf may not be exactly this size; an icon theme may have

182.        --  icons that differ slightly from their nominal sizes, and in addition

183.        --  GTK+ will avoid scaling icons that it considers sufficiently close to

184.        --  the requested size or for which the source image would have to be scaled

185.        --  up too far. (This maintains sharpness.)

186.        --  Return value: the rendered icon; this may be a newly created icon or a

187.        --  new reference to an internal icon, so you must not modify the icon. Use

188.        --  Unref to release your reference to the icon.

190.        procedure Set_Raw_CoordinatesTo API docTo body

191.          (Icon_Info       : Gtk_Icon_InfoTo API docTo spec;

192.           Raw_Coordinates : Boolean);

193.        --  Sets whether the coordinates returned by Get_Embedded_Rect and

194.        --  Get_Attach_Points should be returned in their original form as specified

195.        --  in the icon theme, instead of scaled appropriately for the pixbuf

196.        --  returned by Load_Icon.

197.        --

198.        --  Raw coordinates are somewhat strange; they are specified to be with

199.        --  respect to the unscaled pixmap for PNG and XPM icons, but for SVG icons,

200.        --  they are in a 1000x1000 coordinate space that is scaled to the final

201.        --  size of the icon. You can determine if the icon is an SVG icon by using

202.        --  Get_Filename, and seeing if it is non-empty and ends in '.svg'.

203.        --

204.        --  This function is provided primarily to allow compatibility wrappers

205.        --  for older API's, and is not expected to be useful for applications.

207.        -----------------

208.        -- Search path --

209.        -----------------

211.        Default_Theme_Name : constant String := "hicolor";

213.        procedure Set_Search_PathTo API docTo body

214.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

215.           Path       : GNAT.Strings.String_List);

216.        --  Sets the search path for the icon theme object. When looking for an icon

217.        --  theme, GTK+ will search for a subdirectory of one or more of the

218.        --  directories in Path with the same name as the icon theme. (Themes from

219.        --  multiple of the path elements are combined to allow themes to be

220.        --  extended by adding icons in the user's home directory.)

221.        --

222.        --  In addition if an icon found isn't found either in the current icon

223.        --  theme or the default icon theme, and an image file with the right name

224.        --  is found directly in one of the elements of Path, then that image will

225.        --  be used for the icon name. (This is legacy feature, and new icons should

226.        --  be put into the default icon theme, which is called DEFAULT_THEME_NAME,

227.        --  rather than directly on the icon path.)

229.        procedure Append_Search_PathTo API docTo body

230.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec; Path : String);

231.        procedure Prepend_Search_PathTo API docTo body

232.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

233.           Path       : String);

234.        --  Appends or prepends a directory to the search path.

235.        --  Set_Search_Path.

237.        function Get_Search_PathTo API docTo body

238.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec)

239.           return GNAT.Strings.String_List;

240.        --  Gets the current search path

242.        -----------------

243.        -- Icon themes --

244.        -----------------

246.        procedure Gtk_NewTo API docTo body    (Theme : out Gtk_Icon_ThemeTo API docTo spec);

247.        procedure InitializeTo API docTo body (Theme : access Gtk_Icon_Theme_RecordTo API docTo spec'Class);

248.        --  Creates a new icon theme object. Icon theme objects are used to lookup

249.        --  up an icon by name in a particular icon theme. Usually, you'll want to

250.        --  use Get_Default or Get_For_Screen rather than creating a new icon theme

251.        --  object for scratch.

253.        function Get_TypeTo API docTo body return GTypeTo API docTo spec;

254.        --  Return the internal type associated with icon themes

256.        procedure Add_Builtin_IconTo API docTo body

257.          (Icon_Name : String;

258.           Size      : GintTo API docTo spec;

259.           Pixbuf    : Gdk.Pixbuf.Gdk_PixbufTo API docTo spec);

260.        --  Registers a built-in icon for icon theme lookups. The idea of built-in

261.        --  icons is to allow an application or library that uses themed icons to

262.        --  function requiring files to be present in the file system. For instance,

263.        --  the default images for all of GTK+'s stock icons are registered as

264.        --  built-icons.

265.        --

266.        --  In general, if you use Add_Builtin_Icon you should also install the icon

267.        --  in the icon theme, so that the icon is generally available.

268.        --

269.        --  This function will generally be used with pixbufs loaded via

270.        --  Gdk.Pixbuf.Gdk_New_From-Inline.

272.        function Choose_IconTo API docTo body

273.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

274.           Icon_Names : GNAT.Strings.String_List;

275.           Size       : GintTo API docTo spec;

276.           Flags      : Gtk_Icon_Lookup_FlagsTo API docTo spec)

277.           return Gtk_Icon_InfoTo API docTo spec;

278.        --  Looks up a named icon and returns a structure containing

279.        --  information such as the filename of the icon.  Returns null if

280.        --  the icon wasn't found.  The returned value can then be rendered

281.        --  into a pixbuf using Load_Icon.  There is also a Load_Icon

282.        --  subprogram that combines these two steps if all you need is the

283.        --  pixbuf.

284.        --

285.        --  If Icon_Names contains more than one name, this function

286.        --  tries them all in the given order before falling back to

287.        --  inherited icon themes.

288.        --

289.        --  Free the returned value with Free.

291.        function Get_DefaultTo API docTo body return Gtk_Icon_ThemeTo API docTo spec;

292.        --  Gets the icon theme for the default screen. See Get_For_Screen. Return

293.        --  value: A unique Gtk_Icon_Theme associated with the default screen. This

294.        --  icon theme is associated with the screen and can be used as long as the

295.        --  screen is open. Do not ref or unref it.

297.        function Get_Example_Icon_NameTo API docTo body

298.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec) return String;

299.        --  Gets the name of an icon that is representative of the current theme

300.        --  (for instance, to use when presenting a list of themes to the user.)

302.        function Get_Icon_SizesTo API docTo body

303.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

304.           Icon_Name  : String) return Glib.Gint_ArrayTo API docTo spec;

305.        --  Returns an array of integers describing the sizes at which the icon is

306.        --  available without scaling. A size of -1 means that the icon is available

307.        --  in a scalable format.

309.        function Has_IconTo API docTo body

310.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

311.           Icon_Name  : String) return Boolean;

312.        --  Checks whether an icon theme includes an icon for a particular name.

314.        function List_IconsTo API docTo body

315.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

316.           Context    : String := "") return Gtk.Enums.String_List.GlistTo API docTo specTo body;

317.        --  Lists the icons in the current icon theme. Only a subset of the icons

318.        --  can be listed by providing a context string. The set of values for the

319.        --  context string is system dependent, but will typically include such

320.        --  values as "Applications" and "MimeTypes".

321.        --  You must free the list with Gtk.Enums.Free_String_List.

323.        function Load_IconTo API docTo body

324.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

325.           Icon_Name  : String;

326.           Size       : Glib.GintTo API docTo spec;

327.           Flags      : Gtk_Icon_Lookup_FlagsTo API docTo spec)

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

329.        --  Looks up an icon in an icon theme, scales it to the given size and

330.        --  renders it into a pixbuf. This is a convenience function; if more

331.        --  details about the icon are needed, use Lookup_Icon or Choose_Icon

332.        --  followed by Load_Icon.

333.        --

334.        --  Note that you probably want to listen for icon theme changes and update

335.        --  the icon. This is usually done by connecting to the GtkWidget::style-set

336.        --  signal. If for some reason you do not want to update the icon when the

337.        --  icon theme changes, you should consider using Gdk.Pixbuf.Copy to make a

338.        --  private copy of the pixbuf returned by this function. Otherwise GTK+ may

339.        --  need to keep the old icon theme loaded, which would be a waste of

340.        --  memory.

341.        --

342.        --  Return value: the rendered icon; this may be a newly created icon or a

343.        --  new reference to an internal icon, so you must not modify the icon. Use

344.        --  Unref to release your reference to the icon.

346.        function Lookup_By_GiconTo API docTo body

347.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

348.           Icon       : Glib.G_Icon.G_IconTo API docTo spec;

349.           Size       : GintTo API docTo spec;

350.           Flags      : Gtk_Icon_Lookup_FlagsTo API docTo spec)

351.           return Gtk_Icon_InfoTo API docTo spec;

352.        --  Looks up an icon and returns a structure containing

353.        --  information such as the filename of the icon.

354.        --  The icon can then be rendered into a pixbuf using

355.        --  Load_Icon.  Returns null if the icon wasn't found.

356.        --  Free the returned value with Free.

358.        function Lookup_IconTo API docTo body

359.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

360.           Icon_Name  : String;

361.           Size       : Glib.GintTo API docTo spec;

362.           Flags      : Gtk_Icon_Lookup_FlagsTo API docTo spec)

363.           return Gtk_Icon_InfoTo API docTo spec;

364.        --  Looks up a named icon and returns a structure containing information

365.        --  such as the filename of the icon. The icon can then be rendered into a

366.        --  pixbuf using Load_Icon. (Load_Icon combines these two steps if all you

367.        --  need is the pixbuf)

368.        --  Free the returned value with Free.

370.        function Rescan_If_NeededTo API docTo body

371.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec) return Boolean;

372.        --  Checks to see if the icon theme has changed; if it has, any

373.        --  currently cached information is discarded and will be reloaded

374.        --  next time Icon_Theme is accessed.

376.        procedure Set_Custom_ThemeTo API docTo body

377.          (Icon_Theme : access Gtk_Icon_Theme_RecordTo API docTo spec;

378.           Theme_Name : String);

379.        --  Sets the name of the icon theme that the Gtk_Icon_Theme object uses

380.        --  overriding system configuration. This function cannot be called on the

381.        --  icon theme objects returned from Get_Default and Get_For_Screen.

383.        -------------

384.        -- Signals --

385.        -------------

387.        --  <signals>

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

389.        --

390.        --  - "changed"

391.        --    procedure Handler (Theme : access Gtk_Icon_Theme_Record'Class);

392.        --    Emitted when the current icon theme is switched or GTK+ detects that a

393.        --    change has occurred in the contents of the current icon theme.

394.        --  </signals>

396.        Signal_Changed : constant Glib.Signal_NameTo API docTo spec := "changed";

398.     private

399.        pragma Import (C, FreeTo API docTo spec, "gtk_icon_info_free");

400.        pragma Import (C, Get_Base_SizeTo API docTo spec, "gtk_icon_info_get_base_size");

401.        pragma Import (C, CopyTo API docTo spec, "gtk_icon_info_copy");

402.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_icon_theme_get_type");

403.        pragma Import (C, Icon_Info_Get_TypeTo API docTo spec, "gtk_icon_info_get_type");

404.     end Gtk.Icon_ThemeTo API docTo specTo body;

406.     --  Binding will be provided later:

407.     --  No binding: gtk_icon_theme_error_quark

408.     --  No binding: gtk_icon_theme_get_for_screen

409.     --  No binding: gtk_icon_theme_set_screen