## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                    Copyright (C) 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_Recent_Manager provides a facility for adding, removing and looking up

31.     --  recently used files. Each recently used file is identified by its URI, and

32.     --  has meta-data associated to it, like the names and command lines of the

33.     --  applications that have registered it, the number of time each application

34.     --  has registered the same file, the mime type of the file and whether the

35.     --  file should be displayed only by the applications that have registered it.

36.     --

37.     --  The Gtk_Recent_Manager acts like a database of all the recently used files.

38.     --  You can create new Gtk_Recent_Manager objects, but it is more efficient to

39.     --  use the standard recent manager for the Gdk_Screen so that information

40.     --  about recently used files is shared with other people using them. In case

41.     --  the default screen is being used, adding a new recently used file is

42.     --  as simple as:

43.     --

44.     --     declare

45.     --        Manager : constant Gtk_Recent_Manager := Get_Default;

46.     --     begin

47.     --        Add_Item (Manager, File_URI);

48.     --     end;

49.     --

50.     --  While looking up a recently used file is as simple as using:

51.     --

52.     --     declare

53.     --        Manager : constant Gtk_Recent_Manager := Get_Default;

54.     --        Info    : Gtk_Recent_Info;

55.     --        Error   : Glib.Error.GError;

56.     --     begin

57.     --        Lookup_Item (Info, Manager, File_URI, Error);

58.     --        if Error /= null then

59.     --           --  Use the info object

60.     --           Unref (Info);

61.     --        else

62.     --           Put_Line

63.     --             ("Could not find the file: " & Glib.Error.Get_Message (Error));

64.     --           Glib.Error.Error_Free (Error);

65.     --        end if;

66.     --     end;

67.     --

68.     --  Recently used files are supported since GTK+ 2.10.

69.     --  </description>

70.     --  <c_version>2.16.6</c_version>

72.     with GNAT.Strings;

74.     with Glib.ErrorTo API docTo specTo body;

75.     with Glib.GlistTo API docTo specTo body;

76.     with Glib.PropertiesTo API docTo specTo body;

77.     with Glib.ObjectTo API docTo specTo body;

78.     with Gdk.PixbufTo API docTo specTo body;

79.     with Gdk.ScreenTo API docTo specTo body;

81.     package Gtk.Recent_ManagerTo API docTo specTo body is

83.        type Gtk_Recent_Manager_RecordTo API docTo body is

84.          new Glib.Object.GObject_RecordTo API docTo specTo body with private;

85.        type Gtk_Recent_Manager is access all Gtk_Recent_Manager_RecordTo API docTo specTo body'Class;

87.        subtype time_t is Long_Integer;

88.        --  Type to interface with C's time_t type.  To convert this to/from

89.        --  an Ada type, look at Ada.Calendar.Conversion_Operations and be

90.        --  sure to pay special attention to the ranges each type is capable

91.        --  of representing.

93.        -----------------

94.        -- Recent_Info --

95.        -----------------

97.        type Gtk_Recent_Info_RecordTo API docTo body is

98.          new Glib.Object.GObject_RecordTo API docTo specTo body with private;

99.        type Gtk_Recent_Info is access all Gtk_Recent_Info_RecordTo API docTo specTo body'Class;

101.        function ConvertTo API docTo body (Widget : Gtk_Recent_InfoTo API docTo spec) return System.Address;

102.        function ConvertTo API docTo body (Widget : System.Address) return Gtk_Recent_InfoTo API docTo spec;

104.        package Gtk_Recent_Info_List is

105.          new Glib.Glist.Generic_ListTo API docTo specTo body (Gtk_Recent_InfoTo API docTo spec);

106.        --  Instantiation of a list of Gtk_Recent_Info objects.

108.        function Get_Type_Recent_InfoTo API docTo body return GTypeTo API docTo spec;

109.        --  Return the internal value associated with a Gtk_Recent_Info widget.

111.        function ExistsTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return Boolean;

112.        --  Checks whether the resource pointed to by Info still exists.  At

113.        --  the moment this check is done only on resources pointing to local

114.        --  files.

116.        function Get_AddedTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return time_tTo API docTo spec;

117.        --  Gets the timestamp (seconds from system's Epoch) when the resource

118.        --  was added to the recently used resources list.

119.        --

120.        --  Return value: the number of seconds elapsed from system's Epoch when

121.        --  the resource was added to the list, or -1 on failure.

123.        function Get_AgeTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return GintTo API docTo spec;

124.        --  Gets the number of days elapsed since the last update of the resource

125.        --  pointed by Info.

126.        --

127.        --  Return value: a positive integer containing the number of days

128.        --  elapsed since the time this resource was last modified.

130.        type Application_Info_Record is record

131.           Result : Boolean;

132.           --  True if an application with App_Name has registered this resource

133.           --  inside the recently used list, or False otherwise.

135.           App_Exec : String_PtrTo API docTo spec;

136.           --  Pointer to the string containing the command line.  Free using

137.           --  Glib.Free when no longer needed.

139.           Count : GuintTo API docTo spec;

140.           --  The number of times this item was registered.

142.           Time : time_tTo API docTo spec;

143.           --  The timestamp this item was last registered for this application.

144.        end record;

145.        --  Information returned by Get_Application_Info, below.

147.        function Get_Application_InfoTo API docTo body

148.          (Info     : access Gtk_Recent_Info_RecordTo API docTo specTo body;

149.           App_Name : String)

150.           return Application_Info_RecordTo API docTo spec;

151.        --  Gets the data regarding the application that has registered the resource

152.        --  pointed by Info.

153.        --

154.        --  If the command line contains any escape characters defined inside the

155.        --  storage specification, they will be expanded.

157.        function Get_DescriptionTo API docTo body

158.          (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return UTF8_StringTo API docTo spec;

159.           --  Gets the (short) description of the resource.

161.        function Get_Display_NameTo API docTo body

162.          (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return String;

163.        --  Gets the name of the resource.  If none has been defined, the

164.        --  basename of the resource is obtained.

166.        function Get_IconTo API docTo body

167.          (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body;

168.           Size : GintTo API docTo spec)

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

170.        --  Retrieves the icon of size Size (in pixels) associated to the

171.        --  resource MIME type.  Returns a Gdk_Pixbuf containing the icon, or

172.        --  null. Use Glib.Object.Unref when finished using the icon.

174.        function Get_Mime_TypeTo API docTo body

175.          (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return UTF8_StringTo API docTo spec;

176.        --  Gets the MIME type of the resource.

178.        function Get_ModifiedTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return time_tTo API docTo spec;

179.        --  Gets the timestamp (seconds from system's Epoch) when the resource

180.        --  was last modified. Returns -1 on failure.

182.        function Get_Private_HintTo API docTo body

183.          (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return Boolean;

184.        --  Gets the value of the "private" flag.  Resources in the recently used

185.        --  list that have this flag set to True should only be displayed by the

186.        --  applications that have registered them.

188.        function Get_UriTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return UTF8_StringTo API docTo spec;

189.        --  Gets the URI of the resource.

191.        function Get_VisitedTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return time_tTo API docTo spec;

192.        --  Gets the timestamp (seconds from system's Epoch) when the resource

193.        --  was last visited. Returns -1 on failure.

195.        function Has_ApplicationTo API docTo body

196.          (Info     : access Gtk_Recent_Info_RecordTo API docTo specTo body;

197.           App_Name : UTF8_StringTo API docTo spec)

198.           return Boolean;

199.        --  Checks whether an application registered this resource using

200.        --  App_Name.

202.        function Has_GroupTo API docTo body

203.          (Info       : access Gtk_Recent_Info_RecordTo API docTo specTo body;

204.           Group_Name : UTF8_StringTo API docTo spec)

205.           return Boolean;

206.        --  Checks whether Group_Name appears inside the groups registered for

207.        --  the recently used item Info.

209.        function Is_LocalTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return Boolean;

210.        --  Checks whether the resource is local or not by looking at the

211.        --  scheme of its URI.

213.        function MatchTo API docTo body

214.          (Info_A : access Gtk_Recent_Info_RecordTo API docTo specTo body'Class;

215.           Info_B : access Gtk_Recent_Info_RecordTo API docTo specTo body'Class)

216.           return Boolean;

217.        --  Checks whether two Gtk_Recent_Info structures point to the same

218.        --  resource.

220.        function RefTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body) return Gtk_Recent_InfoTo API docTo spec;

221.        --  Increases the reference count of Recent_Info by one.

223.        procedure UnrefTo API docTo body (Info : access Gtk_Recent_Info_RecordTo API docTo specTo body);

224.        --  Decreases the reference count of Info by one.  If the reference

225.        --  count reaches zero, Info is deallocated, and the memory freed.

227.        --------------------

228.        -- Recent_Manager --

229.        --------------------

231.        procedure Gtk_NewTo API docTo body (Widget : out Gtk_Recent_ManagerTo API docTo spec);

232.        procedure InitializeTo API docTo body (Widget : access Gtk_Recent_Manager_RecordTo API docTo specTo body'Class);

233.        --  Creates a new recent manager object.  Recent manager objects are used to

234.        --  handle the list of recently used resources.  A Gtk_Recent_Manager object

235.        --  monitors the recently used resources list, and emits the "changed"

236.        --  signal each time something inside the list changes.

237.        --

238.        --  Gtk_Recent_Manager objects are expensive: be sure to create them only

239.        --  when needed. You should use Gtk.Recent_Manager.Get_Default instead.

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

242.        --  Return the internal value associated with a Gtk_Recent_Manager widget.

244.        function Error_QuarkTo API docTo body return GQuarkTo API docTo spec;

246.        function Add_FullTo API docTo body

247.          (Manager      : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

248.           Uri          : UTF8_StringTo API docTo spec;

249.           Display_Name : UTF8_StringTo API docTo spec := "";

250.           Description  : UTF8_StringTo API docTo spec := "";

251.           Mime_Type    : UTF8_StringTo API docTo spec;

252.           App_Name     : UTF8_StringTo API docTo spec;

253.           App_Exec     : UTF8_StringTo API docTo spec;

254.           Groups       : GNAT.Strings.String_List;

255.           Is_Private   : Boolean)

256.           return Boolean;

257.        --  Manager      : the Gtk_Recent_Manager on which to operate

258.        --  Uri          : pointer to resource

259.        --  Display_Name : a UTF-8 encoded string, containing the name of the

260.        --                 recently used resource to be displayed, or "".

261.        --  Description  : a UTF-8 encoded string, containing a short description

262.        --                 of the resource, or "".

263.        --  Mime_Type    : the MIME type of the resource.

264.        --  App_Name     : the name of the application that is registering this

265.        --                 recently used resource.

266.        --  App_Exec     : command line used to launch this resource; may contain

267.        --                 the "%f" and "%u" escape characters which will be

268.        --                 expanded to the resource file path and URI, respectively,

269.        --                 when the command line is retrieved.

270.        --  Groups       : a vector of strings containing groups names.

271.        --  Is_Private   : whether this resource should be displayed only by the

272.        --                 applications that have registered it or not.

273.        --

274.        --  Adds a new resource, pointed by Uri, into the recently used

275.        --  resources list, using the metadata specified.

276.        --

277.        --  The passed URI will be used to identify this resource inside the

278.        --  list.

279.        --

280.        --  In order to register the new recently used resource, metadata about

281.        --  the resource must be passed as well as the URI.  This metadata must

282.        --  contain the MIME type of the resource pointed by the URI; the name of

283.        --  the application that is registering the item, and a command line to be

284.        --  used when launching the item.

285.        --

286.        --  Optionally, it is possible to specify a UTF-8 string to be used when

287.        --  viewing the item instead of the last component of the URI; a short

288.        --  description of the item; whether the item should be considered private -

289.        --  that is, should be displayed only by the applications that have

290.        --  registered it.

291.        --

292.        --  Returns True if the new item was successfully added to the recently

293.        --  used resources list, False otherwise.

295.        function Add_ItemTo API docTo body

296.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

297.           Uri     : UTF8_StringTo API docTo spec)

298.           return Boolean;

299.        --  Adds a new resource, pointed by Uri, into the recently used

300.        --  resources list.

301.        --

302.        --  This function automatically retrieves some of the needed

303.        --  metadata and setting other metadata to common default values; it

304.        --  then feeds the data to Add_Full.

305.        --

306.        --  See Add_Full if you want to explicitly define the metadata for the

307.        --  resource pointed by Uri.

308.        --

309.        --  Returns True if the new item was successfully added to the recently

310.        --  used resources list

312.        function Get_DefaultTo API docTo body return Gtk_Recent_ManagerTo API docTo spec;

313.        --  Gets a unique instance of Gtk_Recent_Manager that you can share

314.        --  in your application without caring about memory management. The

315.        --  returned instance will be freed when you application terminates.

316.        --

317.        --  Do not ref or unref the returned manager.

319.        function Get_ItemsTo API docTo body

320.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body)

321.           return Gtk_Recent_Info_List.GlistTo API docTo specTo body;

322.        --  Gets the list of recently used resources.  Use Unref on each item

323.        --  inside the list, and then free the list itself using

324.        --  Glib.Object.Object_Simple_List.Free.

326.        function Get_LimitTo API docTo body (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body) return GintTo API docTo spec;

327.        procedure Set_LimitTo API docTo body

328.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

329.           Limit   : GintTo API docTo spec);

330.        --  Maximum number of items that the Get_Items function should return.

331.        --  If Limit is set to -1, then return all the items.

333.        function Has_ItemTo API docTo body

334.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

335.           Uri     : UTF8_StringTo API docTo spec)

336.           return Boolean;

337.        --  Checks whether there is a recently used resource registered

338.        --  with Uri inside the recent manager.

340.        function Lookup_ItemTo API docTo body

341.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

342.           Uri     : UTF8_StringTo API docTo spec;

343.           Error   : Glib.Error.GErrorTo API docTo spec)

344.           return Gtk_Recent_InfoTo API docTo spec;

345.        --  Searches for a URI inside the recently used resources list, and

346.        --  returns a structure containing information about the resource

347.        --  like its MIME type, or its display name.

348.        --

349.        --  Returns null if the URI was not registered in the recently used

350.        --  resources list.  Free with Unref.

352.        function Move_ItemTo API docTo body

353.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

354.           Uri     : UTF8_StringTo API docTo spec;

355.           New_Uri : UTF8_StringTo API docTo spec;

356.           Error   : Glib.Error.GErrorTo API docTo spec)

357.           return Boolean;

358.        --  Changes the location of a recently used resource from Uri to New_Uri.

359.        --  A New_Uri of "" will remove the item pointed to by Uri in the list.

360.        --

361.        --  Please note that this function will not affect the resource pointed

362.        --  by the URIs, but only the URI used in the recently used resources list.

364.        function Purge_ItemsTo API docTo body

365.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

366.           Error   : Glib.Error.GErrorTo API docTo spec)

367.           return GintTo API docTo spec;

368.        --  Purges every item from the recently used resources list.

369.        --

370.        --  Returns the number of items that have been removed from the

371.        --  recently used resources list.

373.        function Remove_ItemTo API docTo body

374.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

375.           Uri     : UTF8_StringTo API docTo spec;

376.           Error   : Glib.Error.GErrorTo API docTo spec)

377.           return Boolean;

378.        --  Removes a resource pointed by Uri from the recently used resources

379.        --  list handled by a recent manager.

381.        -----------------

382.        -- Obsolescent --

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

385.        function Get_For_ScreenTo API docTo body

386.          (Screen : access Gdk.Screen.Gdk_Screen_RecordTo API docTo spec) return Gtk_Recent_ManagerTo API docTo spec;

387.        pragma Obsolescent;  --  Get_For_Screen

388.        --  Gets the recent manager object associated with Screen; if this

389.        --  function has not previously been called for the given screen,

390.        --  a new recent manager object will be created and associated with

391.        --  the screen. Recent manager objects are fairly expensive to create,

392.        --  so using this function is usually a better choice than calling

393.        --  New and setting the screen yourself; by using this function a single

394.        --  recent manager object will be shared between users.

395.        --

396.        --  Return value: A unique Gtk_Recent_Manager associated with the given

397.        --  screen. This recent manager is associated to the with the screen

398.        --  and can be used as long as the screen is open. Do not ref or

399.        --  unref it.

400.        --

401.        --  Deprecated: 2.12: This function has been deprecated and should

402.        --  not be used in newly written code. Calling this function is

403.        --  equivalent to calling Get_Default.

405.        procedure Set_ScreenTo API docTo body

406.          (Manager : access Gtk_Recent_Manager_RecordTo API docTo specTo body;

407.           Screen  : access Gdk.Screen.Gdk_Screen_RecordTo API docTo spec'Class);

408.        pragma Obsolescent;  --  Set_Screen

409.        --  Sets the screen for a recent manager; the screen is used to

410.        --  track the user's currently configured recently used documents

411.        --  storage.

412.        --

413.        --  Deprecated: 2.12: This function has been deprecated and should

414.        --  not be used in newly written code. Calling this function has

415.        --  no effect.

417.        ----------------

418.        -- Properties --

419.        ----------------

421.        --  <properties>

422.        --  Name:  Filename_Property

423.        --  Type:  String

424.        --  Descr: The full path to the file to be used to store and read the list

425.        --

426.        --  Name:  Limit_Property

427.        --  Type:  Int

428.        --  Descr: The maximum number of items to be returned by

429.        --         Gtk.Recent_Manager.Get_Items

430.        --

431.        --  Name:  Size_Property

432.        --  Type:  Int

433.        --  Descr: The size of the recently used resources list

434.        --

435.        --  </properties>

437.        Filename_Property : constant Glib.Properties.Property_StringTo API docTo spec;

438.        Limit_Property    : constant Glib.Properties.Property_IntTo API docTo spec;

439.        Size_Property     : constant Glib.Properties.Property_IntTo API docTo spec;

441.     private

443.        type Gtk_Recent_Manager_RecordTo API docTo spec is

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

446.        type Gtk_Recent_Info_RecordTo API docTo spec is

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

449.        Filename_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

450.          Glib.Properties.BuildTo API docTo specTo body ("filename");

451.        Limit_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

452.          Glib.Properties.BuildTo API docTo specTo body ("limit");

453.        Size_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

454.          Glib.Properties.BuildTo API docTo specTo body ("size");

456.        pragma Import (C, Error_QuarkTo API docTo spec, "gtk_recent_manager_error_quark");

457.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_recent_manager_get_type");

458.        pragma Import (C, Get_Type_Recent_InfoTo API docTo spec, "gtk_recent_info_get_type");

460.     end Gtk.Recent_ManagerTo API docTo specTo body;