## 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-2011, AdaCore                   --

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.     --  The Gtk_About_Dialog offers a simple way to display information about a

32.     --  program like its logo, name, copyright, website and license. It is also

33.     --  possible to give credits to the authors, documenters, translators and

34.     --  artists who have worked on the program. An about dialog is typically opened

35.     --  when the user selects the About option from the Help menu. All parts of the

36.     --  dialog are optional.

37.     --

38.     --  About dialog often contain links and email addresses. Gtk_About_Dialog

39.     --  supports this by offering global hooks, which are called when the user

40.     --  clicks on a link or email address, see Set_Email_Hook and Set_Url_Hook.

41.     --  Email addresses in the authors, documenters and artists properties are

42.     --  recognized by looking for <user@host>, URLs are recognized by looking for

43.     --  http://url, with url extending to the next space, tab or line break.

44.     --

45.     --  To make constructing a Gtk_About_Dialog as convenient as possible, you can

46.     --  use the function gtk_show_about_dialog which constructs and shows a dialog

47.     --  and keeps it around so that it can be shown again.

48.     --

49.     --  </description>

50.     --  <group>Windows</group>

51.     --  <testgtk>create_about.adb</testgtk>

53.     pragma Warnings (Off, "*is already use-visible*");

54.     with GNAT.Strings;         use GNAT.Strings;

55.     with Gdk.PixbufTo API docTo specTo body;           use Gdk.PixbufTo API docTo specTo body;

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

57.     with Glib.PropertiesTo API docTo specTo body;      use Glib.PropertiesTo API docTo specTo body;

58.     with Glib.TypesTo API docTo specTo body;           use Glib.TypesTo API docTo specTo body;

59.     with Gtk.BuildableTo API docTo specTo body;        use Gtk.BuildableTo API docTo specTo body;

60.     with Gtk.DialogTo API docTo specTo body;           use Gtk.DialogTo API docTo specTo body;

61.     with Gtk.WidgetTo API docTo specTo body;           use Gtk.WidgetTo API docTo specTo body;

62.     with Interfaces.C.Strings; use Interfaces.C.Strings;

64.     package Gtk.About_DialogTo API docTo specTo body is

66.        type Gtk_About_Dialog_Record is new Gtk_Dialog_RecordTo API docTo spec with null record;

67.        type Gtk_About_Dialog is access all Gtk_About_Dialog_RecordTo API docTo spec'Class;

69.        type Activate_Link_Func is access procedure

70.          (About : System.Address;

71.           Link  : Interfaces.C.Strings.chars_ptr;

72.           Data  : System.Address);

73.        pragma Convention (C, Activate_Link_FuncTo API docTo spec);

74.        --  A callback called when the user presses an hyper link in the about

75.        --  dialog. This is a low-level function, and you'll need to convert the

76.        --  parameters to more useful types with:

77.        --     Stub : Gtk_About_Dialog_Record;

78.        --     A    : constant Gtk_About_Dialog :=

79.        --       Gtk_About_Dialog (Get_User_Data (About, Stub));

80.        --     L    : constant String := Interfaces.C.Strings.Value (Link);

82.        ------------------

83.        -- Constructors --

84.        ------------------

86.        procedure Gtk_NewTo API docTo body (About : out Gtk_About_DialogTo API docTo spec);

87.        procedure InitializeTo API docTo body (About : access Gtk_About_Dialog_RecordTo API docTo spec'Class);

88.        --  Creates a new Gtk.About_Dialog.Gtk_About_Dialog.

89.        --  Since: gtk+ 2.6

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

92.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_about_dialog_get_type");

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

95.        -- Methods --

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

98.        function Get_ArtistsTo API docTo body

99.           (About : access Gtk_About_Dialog_RecordTo API docTo spec)

100.            return GNAT.Strings.String_List;

101.        procedure Set_ArtistsTo API docTo body

102.           (About   : access Gtk_About_Dialog_RecordTo API docTo spec;

103.            Artists : GNAT.Strings.String_List);

104.        --  Sets the strings which are displayed in the artists tab of the

105.        --  secondary credits dialog.

106.        --  Since: gtk+ 2.6

107.        --  "artists": a null-terminated array of strings

109.        function Get_AuthorsTo API docTo body

110.           (About : access Gtk_About_Dialog_RecordTo API docTo spec)

111.            return GNAT.Strings.String_List;

112.        procedure Set_AuthorsTo API docTo body

113.           (About   : access Gtk_About_Dialog_RecordTo API docTo spec;

114.            Authors : GNAT.Strings.String_List);

115.        --  Sets the strings which are displayed in the authors tab of the

116.        --  secondary credits dialog.

117.        --  Since: gtk+ 2.6

118.        --  "authors": a null-terminated array of strings

120.        function Get_CommentsTo API docTo body

121.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

122.        procedure Set_CommentsTo API docTo body

123.           (About    : access Gtk_About_Dialog_RecordTo API docTo spec;

124.            Comments : UTF8_StringTo API docTo spec);

125.        --  Sets the comments string to display in the about dialog. This should be

126.        --  a short string of one or two lines.

127.        --  Since: gtk+ 2.6

128.        --  "comments": a comments string

130.        function Get_CopyrightTo API docTo body

131.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

132.        procedure Set_CopyrightTo API docTo body

133.           (About     : access Gtk_About_Dialog_RecordTo API docTo spec;

134.            Copyright : UTF8_StringTo API docTo spec);

135.        --  Sets the copyright string to display in the about dialog. This should

136.        --  be a short string of one or two lines.

137.        --  Since: gtk+ 2.6

138.        --  "copyright": (allow-none) the copyright string

140.        function Get_DocumentersTo API docTo body

141.           (About : access Gtk_About_Dialog_RecordTo API docTo spec)

142.            return GNAT.Strings.String_List;

143.        procedure Set_DocumentersTo API docTo body

144.           (About       : access Gtk_About_Dialog_RecordTo API docTo spec;

145.            Documenters : GNAT.Strings.String_List);

146.        --  Sets the strings which are displayed in the documenters tab of the

147.        --  secondary credits dialog.

148.        --  Since: gtk+ 2.6

149.        --  "documenters": a null-terminated array of strings

151.        function Get_LicenseTo API docTo body

152.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

153.        procedure Set_LicenseTo API docTo body

154.           (About   : access Gtk_About_Dialog_RecordTo API docTo spec;

155.            License : UTF8_StringTo API docTo spec);

156.        --  Sets the license information to be displayed in the secondary license

157.        --  dialog. If License is null, the license button is hidden.

158.        --  Since: gtk+ 2.6

159.        --  "license": the license information or null

161.        function Get_LogoTo API docTo body

162.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

163.        procedure Set_LogoTo API docTo body

164.           (About : access Gtk_About_Dialog_RecordTo API docTo spec;

165.            Logo  : access Gdk.Pixbuf.Gdk_Pixbuf_RecordTo API docTo specTo body'Class);

166.        --  Sets the pixbuf to be displayed as logo in the about dialog. If it is

167.        --  null, the default window icon set with Gtk.Window.Set_Default_Icon will

168.        --  be used.

169.        --  Since: gtk+ 2.6

170.        --  "logo": a Gdk.Pixbuf.Gdk_Pixbuf, or null

172.        function Get_Logo_Icon_NameTo API docTo body

173.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

174.        procedure Set_Logo_Icon_NameTo API docTo body

175.           (About     : access Gtk_About_Dialog_RecordTo API docTo spec;

176.            Icon_Name : UTF8_StringTo API docTo spec);

177.        --  Sets the pixbuf to be displayed as logo in the about dialog. If it is

178.        --  null, the default window icon set with Gtk.Window.Set_Default_Icon will

179.        --  be used.

180.        --  Since: gtk+ 2.6

181.        --  "icon_name": an icon name, or null

183.        function Get_NameTo API docTo body

184.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

185.        pragma Obsolescent (Get_NameTo API docTo specTo body);

186.        procedure Set_NameTo API docTo body

187.           (About : access Gtk_About_Dialog_RecordTo API docTo spec;

188.            Name  : UTF8_StringTo API docTo spec);

189.        pragma Obsolescent (Set_NameTo API docTo specTo body);

190.        --  Sets the name to display in the about dialog. If this is not set, it

191.        --  defaults to g_get_application_name.

192.        --  Since: gtk+ 2.6

193.        --  Deprecated since 2.12, Use Gtk.About_Dialog.Set_Program_Name instead.

194.        --  "name": the program name

196.        function Get_Program_NameTo API docTo body

197.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

198.        procedure Set_Program_NameTo API docTo body

199.           (About : access Gtk_About_Dialog_RecordTo API docTo spec;

200.            Name  : UTF8_StringTo API docTo spec);

201.        --  Sets the name to display in the about dialog. If this is not set, it

202.        --  defaults to g_get_application_name.

203.        --  Since: gtk+ 2.12

204.        --  "name": the program name

206.        function Get_Translator_CreditsTo API docTo body

207.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

208.        procedure Set_Translator_CreditsTo API docTo body

209.           (About              : access Gtk_About_Dialog_RecordTo API docTo spec;

210.            Translator_Credits : UTF8_StringTo API docTo spec);

211.        --  Sets the translator credits string which is displayed in the

212.        --  translators tab of the secondary credits dialog. The intended use for

213.        --  this string is to display the translator of the language which is

214.        --  currently used in the user interface. Using gettext, a simple way to

215.        --  achieve that is to mark the string for translation: |[

216.        --  gtk_about_dialog_set_translator_credits (about,

217.        --  _("translator-credits")); ]| It is a good idea to use the customary

218.        --  msgid "translator-credits" for this purpose, since translators will

219.        --  already know the purpose of that msgid, and since

220.        --  Gtk.About_Dialog.Gtk_About_Dialog will detect if "translator-credits" is

221.        --  untranslated and hide the tab.

222.        --  Since: gtk+ 2.6

223.        --  "translator_credits": the translator credits

225.        function Get_VersionTo API docTo body

226.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

227.        procedure Set_VersionTo API docTo body

228.           (About   : access Gtk_About_Dialog_RecordTo API docTo spec;

229.            Version : UTF8_StringTo API docTo spec);

230.        --  Sets the version string to display in the about dialog.

231.        --  Since: gtk+ 2.6

232.        --  "version": the version string

234.        function Get_WebsiteTo API docTo body

235.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

236.        procedure Set_WebsiteTo API docTo body

237.           (About   : access Gtk_About_Dialog_RecordTo API docTo spec;

238.            Website : UTF8_StringTo API docTo spec);

239.        --  Sets the URL to use for the website link. Note that that the hook

240.        --  functions need to be set up before calling this function.

241.        --  Since: gtk+ 2.6

242.        --  "website": a URL string starting with "http://"

244.        function Get_Website_LabelTo API docTo body

245.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

246.        procedure Set_Website_LabelTo API docTo body

247.           (About         : access Gtk_About_Dialog_RecordTo API docTo spec;

248.            Website_Label : UTF8_StringTo API docTo spec);

249.        --  Sets the label to be used for the website link. It defaults to the

250.        --  website URL.

251.        --  Since: gtk+ 2.6

252.        --  "website_label": the label used for the website link

254.        function Get_Wrap_LicenseTo API docTo body

255.           (About : access Gtk_About_Dialog_RecordTo API docTo spec) return Boolean;

256.        procedure Set_Wrap_LicenseTo API docTo body

257.           (About        : access Gtk_About_Dialog_RecordTo API docTo spec;

258.            Wrap_License : Boolean);

259.        --  Sets whether the license text in About is automatically wrapped.

260.        --  Since: gtk+ 2.8

261.        --  "wrap_license": whether to wrap the license

263.        ---------------

264.        -- Functions --

265.        ---------------

267.        function Set_Email_HookTo API docTo body

268.           (Func    : Activate_Link_FuncTo API docTo spec;

269.            Data    : System.Address;

270.            Destroy : Glib.G_Destroy_Notify_AddressTo API docTo spec) return Activate_Link_FuncTo API docTo spec;

271.        pragma Obsolescent (Set_Email_HookTo API docTo specTo body);

272.        --  Installs a global function to be called whenever the user activates an

273.        --  email link in an about dialog. Since 2.18 there exists a default

274.        --  function which uses gtk_show_uri(). To deactivate it, you can pass null

275.        --  for Func.

276.        --  Since: gtk+ 2.6

277.        --  Deprecated since 2.24, Use the

278.        --  Gtk.About_Dialog.Gtk_About_Dialog::activate-link signal

279.        --  "func": a function to call when an email link is activated.

280.        --  "data": data to pass to Func

281.        --  "destroy": Glib.G_Destroy_Notify_Address for Data

283.        function Set_Url_HookTo API docTo body

284.           (Func    : Activate_Link_FuncTo API docTo spec;

285.            Data    : System.Address;

286.            Destroy : Glib.G_Destroy_Notify_AddressTo API docTo spec) return Activate_Link_FuncTo API docTo spec;

287.        pragma Obsolescent (Set_Url_HookTo API docTo specTo body);

288.        --  Installs a global function to be called whenever the user activates a

289.        --  URL link in an about dialog. Since 2.18 there exists a default function

290.        --  which uses gtk_show_uri(). To deactivate it, you can pass null for Func.

291.        --  Since: gtk+ 2.6

292.        --  Deprecated since 2.24, Use the

293.        --  Gtk.About_Dialog.Gtk_About_Dialog::activate-link signal

294.        --  "func": a function to call when a URL link is activated.

295.        --  "data": data to pass to Func

296.        --  "destroy": Glib.G_Destroy_Notify_Address for Data

298.        ----------------

299.        -- Interfaces --

300.        ----------------

301.        --  This class implements several interfaces. See Glib.Types

302.        --

303.        --  - "Buildable"

305.        package Implements_Buildable is new Glib.Types.ImplementsTo API docTo specTo body

306.          (Gtk.Buildable.Gtk_BuildableTo API docTo spec, Gtk_About_Dialog_RecordTo API docTo spec, Gtk_About_DialogTo API docTo spec);

307.        function "+"

308.          (Widget : access Gtk_About_Dialog_RecordTo API docTo spec'Class)

309.        return Gtk.Buildable.Gtk_BuildableTo API docTo spec

310.        renames Implements_Buildable.To_InterfaceTo API docTo specTo body;

311.        function "-"

312.          (Interf : Gtk.Buildable.Gtk_BuildableTo API docTo spec)

313.        return Gtk_About_DialogTo API docTo spec

314.        renames Implements_Buildable.To_ObjectTo API docTo specTo body;

316.        ----------------

317.        -- Properties --

318.        ----------------

319.        --  The following properties are defined for this widget. See

320.        --  Glib.Properties for more information on properties)

321.        --

322.        --  Name: Comments_Property

323.        --  Type: UTF8_String

324.        --  Flags: read-write

325.        --  Comments about the program. This string is displayed in a label in the

326.        --  main dialog, thus it should be a short explanation of the main purpose

327.        --  of the program, not a detailed list of features.

328.        --

329.        --  Name: Copyright_Property

330.        --  Type: UTF8_String

331.        --  Flags: read-write

332.        --  Copyright information for the program.

333.        --

334.        --  Name: License_Property

335.        --  Type: UTF8_String

336.        --  Flags: read-write

337.        --  The license of the program. This string is displayed in a text view in

338.        --  a secondary dialog, therefore it is fine to use a long multi-paragraph

339.        --  text. Note that the text is only wrapped in the text view if the

340.        --  "wrap-license" property is set to True; otherwise the text itself must

341.        --  contain the intended linebreaks.

342.        --

343.        --  Name: Logo_Property

344.        --  Type: Gdk.Pixbuf.Gdk_Pixbuf

345.        --  Flags: read-write

346.        --  A logo for the about box. If this is not set, it defaults to

347.        --  gtk_window_get_default_icon_list.

348.        --

349.        --  Name: Logo_Icon_Name_Property

350.        --  Type: UTF8_String

351.        --  Flags: read-write

352.        --  A named icon to use as the logo for the about box. This property

353.        --  overrides the Gtk.About_Dialog.Gtk_About_Dialog:logo property.

354.        --

355.        --  Name: Program_Name_Property

356.        --  Type: UTF8_String

357.        --  Flags: read-write

358.        --  The name of the program. If this is not set, it defaults to

359.        --  g_get_application_name.

360.        --

361.        --  Name: Translator_Credits_Property

362.        --  Type: UTF8_String

363.        --  Flags: read-write

364.        --  Credits to the translators. This string should be marked as

365.        --  translatable. The string may contain email addresses and URLs, which

366.        --  will be displayed as links, see the introduction for more details.

367.        --

368.        --  Name: Version_Property

369.        --  Type: UTF8_String

370.        --  Flags: read-write

371.        --  The version of the program.

372.        --

373.        --  Name: Website_Property

374.        --  Type: UTF8_String

375.        --  Flags: read-write

376.        --  The URL for the link to the website of the program. This should be a

377.        --  string starting with "http://.

378.        --

379.        --  Name: Website_Label_Property

380.        --  Type: UTF8_String

381.        --  Flags: read-write

382.        --  The label for the link to the website of the program. If this is not

383.        --  set, it defaults to the URL specified in the

384.        --  Gtk.About_Dialog.Gtk_About_Dialog:website property.

385.        --

386.        --  Name: Wrap_License_Property

387.        --  Type: Boolean

388.        --  Flags: read-write

389.        --  Whether to wrap the text in the license dialog.

391.        Comments_Property : constant Glib.Properties.Property_StringTo API docTo spec;

392.        Copyright_Property : constant Glib.Properties.Property_StringTo API docTo spec;

393.        License_Property : constant Glib.Properties.Property_StringTo API docTo spec;

394.        Logo_Property : constant Glib.Properties.Property_ObjectTo API docTo spec;

395.        Logo_Icon_Name_Property : constant Glib.Properties.Property_StringTo API docTo spec;

396.        Program_Name_Property : constant Glib.Properties.Property_StringTo API docTo spec;

397.        Translator_Credits_Property : constant Glib.Properties.Property_StringTo API docTo spec;

398.        Version_Property : constant Glib.Properties.Property_StringTo API docTo spec;

399.        Website_Property : constant Glib.Properties.Property_StringTo API docTo spec;

400.        Website_Label_Property : constant Glib.Properties.Property_StringTo API docTo spec;

401.        Wrap_License_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

403.        -------------

404.        -- Signals --

405.        -------------

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

407.        --

408.        --  "activate-link"

409.        --     function Handler

410.        --       (Self : access Gtk_About_Dialog_Record'Class;

411.        --        Uri  : UTF8_String) return Boolean;

412.        --    --  "uri": the URI that is activated

413.        --  The signal which gets emitted to activate a URI. Applications may

414.        --  connect to it to override the default behaviour, which is to call

415.        --  gtk_show_uri().

416.        --  Returns True if the link has been activated

418.        Signal_Activate_Link : constant Glib.Signal_NameTo API docTo spec := "activate-link";

420.     private

421.        Comments_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

422.          Glib.Properties.BuildTo API docTo specTo body ("comments");

423.        Copyright_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

424.          Glib.Properties.BuildTo API docTo specTo body ("copyright");

425.        License_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

426.          Glib.Properties.BuildTo API docTo specTo body ("license");

427.        Logo_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

428.          Glib.Properties.BuildTo API docTo specTo body ("logo");

429.        Logo_Icon_Name_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

430.          Glib.Properties.BuildTo API docTo specTo body ("logo-icon-name");

431.        Program_Name_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

432.          Glib.Properties.BuildTo API docTo specTo body ("program-name");

433.        Translator_Credits_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

434.          Glib.Properties.BuildTo API docTo specTo body ("translator-credits");

435.        Version_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

436.          Glib.Properties.BuildTo API docTo specTo body ("version");

437.        Website_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

438.          Glib.Properties.BuildTo API docTo specTo body ("website");

439.        Website_Label_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

440.          Glib.Properties.BuildTo API docTo specTo body ("website-label");

441.        Wrap_License_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

442.          Glib.Properties.BuildTo API docTo specTo body ("wrap-license");

443.     end Gtk.About_DialogTo API docTo specTo body;