## 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.     --  G_Key_File lets you parse, edit or create files containing groups of

31.     --  key-value pairs, which we call key files for lack of a better name. Several

32.     --  freedesktop.org specifications use key files now, e.g the Desktop Entry

33.     --  Specification and the Icon Theme Specification.

34.     --

35.     --  The syntax of key files is described in detail in the Desktop Entry

36.     --  Specification, here is a quick summary: Key files consists of groups of

37.     --  key-value pairs, interspersed with comments.

38.     --

39.     --       # this is just an example

40.     --       # there can be comments before the first group

41.     --       [First Group]

42.     --       Name=Key File Example\tthis value shows\nescaping

43.     --       # localized strings are stored in multiple key-value pairs

44.     --       Welcome=Hello

45.     --       Welcome[de]=Hallo

46.     --       Welcome[fr_FR]=Bonjour

47.     --       Welcome[it]=Ciao

48.     --       Welcome[be@latin]=Hello

49.     --       [Another Group]

50.     --       Numbers=2;20;-200;0

51.     --       Booleans=true;false;true;true

52.     --

53.     --  Groups are started by a header line containing the group name enclosed in

54.     --  '[' and ']', and ended implicitly by the start of the next group or the end

55.     --  of the file. Each key-value pair must be contained in a group.

56.     --

57.     --  Key-value pairs generally have the form key=value, with the exception of

58.     --  localized strings, which have the form key[locale]=value, with a locale

59.     --  identifier of the form lang_COUNTRYMODIFIER where COUNTRY and MODIFIER are

60.     --  optional. Space before and after the '=' character are ignored. Newline,

61.     --  tab, carriage return and backslash characters in value are escaped as \n,

62.     --  \t, \r, and \\, respectively. To preserve leading spaces in values, these

63.     --  can also be escaped as \s.

64.     --

65.     --  Key files can store strings (possibly with localized variants), integers,

66.     --  booleans and lists of these. Lists are separated by a separator character,

67.     --  typically ';' or ','. To use the list separator character in a value in a

68.     --  list, it has to be escaped by prefixing it with a backslash.

69.     --

70.     --  This syntax is obviously inspired by the .ini files commonly met on

71.     --  Windows, but there are some important differences:

72.     --

73.     --  .ini files use the ';' character to begin comments, key files use the '#'

74.     --  character.

75.     --

76.     --  Key files do not allow for ungrouped keys meaning only comments can

77.     --  precede the first group.

78.     --

79.     --  Key files are always encoded in UTF-8.

80.     --

81.     --  Key and Group names are case-sensitive, for example a group called [GROUP]

82.     --  is a different group from [group].

83.     --

84.     --  .ini files don't have a strongly typed boolean entry type, they only have

85.     --  GetProfileInt. In G_Key_File only true and false (in lower case) are

86.     --  allowed.

87.     --

88.     --  Note that in contrast to the Desktop Entry Specification, groups in key

89.     --  files may contain the same key multiple times; the last entry wins. Key

90.     --  files may also contain multiple groups with the same name; they are merged

91.     --  together. Another difference is that keys and group names in key files are

92.     --  not restricted to ASCII characters.

93.     --  </description>

94.     --  <c_version>2.16.6</c_version>

96.     with GNAT.Strings;

98.     with Glib.ErrorTo API docTo specTo body;

100.     package Glib.Key_FileTo API docTo specTo body is

102.        type G_Key_File is new Glib.C_ProxyTo API docTo spec;

104.        type G_Key_File_Error is

105.          (Error_Unknown_Encoding,

106.           Error_Parse,

107.           Error_Not_Found,

108.           Error_Key_Not_Found,

109.           Error_Group_Not_Found,

110.           Error_Invalid_Value);

111.        pragma Convention (C, G_Key_File_ErrorTo API docTo spec);

113.        type G_Key_File_Flags is (None, Keep_Comments, Keep_Translations);

114.        pragma Convention (C, G_Key_File_FlagsTo API docTo spec);

116.        --  Constants for handling freedesktop.org Desktop files

117.        Desktop_Group                : constant String := "Desktop Entry";

119.        Desktop_Key_Type             : constant String := "Type";

120.        Desktop_Key_Version          : constant String := "Version";

121.        Desktop_Key_Name             : constant String := "Name";

122.        Desktop_Key_Generic_Name     : constant String := "GenericName";

123.        Desktop_Key_No_Display       : constant String := "NoDisplay";

124.        Desktop_Key_Comment          : constant String := "Comment";

125.        Desktop_Key_Icon             : constant String := "Icon";

126.        Desktop_Key_Hidden           : constant String := "Hidden";

127.        Desktop_Key_Only_Show_In     : constant String := "OnlyShowIn";

128.        Desktop_Key_Not_Show_In      : constant String := "NotShowIn";

129.        Desktop_Key_Try_Exec         : constant String := "TryExec";

130.        Desktop_Key_Exec             : constant String := "Exec";

131.        Desktop_Key_Path             : constant String := "Path";

132.        Desktop_Key_Terminal         : constant String := "Terminal";

133.        Desktop_Key_Mime_Type        : constant String := "MimeType";

134.        Desktop_Key_Categories       : constant String := "Categories";

135.        Desktop_Key_Startup_Notify   : constant String := "StartupNotify";

136.        Desktop_Key_Startup_Wm_Class : constant String := "StartupWMClass";

137.        Desktop_Key_Url              : constant String := "URL";

139.        Desktop_Type_Application     : constant String := "Application";

140.        Desktop_Type_Link            : constant String := "Link";

141.        Desktop_Type_Directory       : constant String := "Directory";

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

145.        procedure Gtk_NewTo API docTo body (Key_File : out G_Key_FileTo API docTo spec);

146.        --  Creates a new empty G_Key_File object. Use Load_From_File,

147.        --  Load_From_Data, Load_From_Dirs or Load_From_Data_Dirs to read an

148.        --  existing key file.

150.        procedure FreeTo API docTo body (Key_File : in out G_Key_FileTo API docTo spec);

151.        --  Frees a G_Key_File.

153.        procedure Set_List_SeparatorTo API docTo body

154.          (Key_File  : G_Key_FileTo API docTo spec;

155.           Separator : GcharTo API docTo spec);

156.        --  Sets the character which is used to separate

157.        --  values in lists. Typically ';' or ',' are used

158.        --  as separators. The default list separator is ';'.

160.        function To_DataTo API docTo body (Key_File : G_Key_FileTo API docTo spec) return String;

161.        --  Output Key_File as a String.

163.        ------------

164.        -- Groups --

165.        ------------

167.        function Get_Start_GroupTo API docTo body (Key_File : G_Key_FileTo API docTo spec) return String;

168.        --  Returns the name of the start group of the file.

170.        function Get_GroupsTo API docTo body (Key_File : G_Key_FileTo API docTo spec) return GNAT.Strings.String_List;

171.        --  Returns all groups in the key file loaded with Key_File.

173.        function Has_GroupTo API docTo body

174.          (Key_File   : G_Key_FileTo API docTo spec;

175.           Group_Name : String)

176.           return Boolean;

177.        --  Looks whether the key file has the group Group_Name.

179.        function Remove_GroupTo API docTo body

180.          (Key_File   : G_Key_FileTo API docTo spec;

181.           Group_Name : String;

182.           Error      : Glib.Error.GErrorTo API docTo spec := null)

183.           return Boolean;

184.        --  Removes the specified group, Group_Name, from the key file.

185.        --  Returns True if the group was removed, False otherwise.

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

188.        -- Keys --

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

191.        function Get_KeysTo API docTo body

192.          (Key_File   : G_Key_FileTo API docTo spec;

193.           Group_Name : String;

194.           Error      : Glib.Error.GErrorTo API docTo spec := null)

195.           return GNAT.Strings.String_List;

196.        --  Returns all keys for the group name Group_Name.  In the event that the

197.        --  Group_Name cannot be found, an empty list is returned and Error is set

198.        --  to Error_Group_Not_Found.

200.        function Has_KeyTo API docTo body

201.          (Key_File   : G_Key_FileTo API docTo spec;

202.           Group_Name : String;

203.           Key        : String;

204.           Error      : Glib.Error.GErrorTo API docTo spec := null)

205.           return Boolean;

206.        --  Looks whether the key file has the key Key in the group Group_Name.

208.        function Remove_KeyTo API docTo body

209.          (Key_File   : G_Key_FileTo API docTo spec;

210.           Group_Name : String;

211.           Key        : String;

212.           Error      : Glib.Error.GErrorTo API docTo spec := null)

213.           return Boolean;

214.        --  Removes Key in Group_Name from the key file.

215.        --  Returns True if the key was removed, False otherwise.

217.        --------------

218.        -- Comments --

219.        --------------

221.        function Get_CommentTo API docTo body

222.          (Key_File   : G_Key_FileTo API docTo spec;

223.           Group_Name : String;

224.           Key        : String;

225.           Error      : Glib.Error.GErrorTo API docTo spec := null)

226.           return String;

227.        function Set_CommentTo API docTo body

228.          (Key_File   : G_Key_FileTo API docTo spec;

229.           Group_Name : String := "";

230.           Key        : String := "";

231.           Comment    : String;

232.           Error      : Glib.Error.GErrorTo API docTo spec := null)

233.           return Boolean;

234.        function Remove_CommentTo API docTo body

235.          (Key_File   : G_Key_FileTo API docTo spec;

236.           Group_Name : String := "";

237.           Key        : String := "";

238.           Error      : Glib.Error.GErrorTo API docTo spec := null)

239.           return Boolean;

240.        --  Places a comment above Key from Group_Name.

241.        --  If Key is null then Comment will be removed/written above Group_Name.

242.        --  If both Key and Group_Name are null, then Comment will be

243.        --  removed/written above the first group in the file.

244.        --

245.        --  Returns whether the operation was successful.

247.        -------------

248.        -- Boolean --

249.        -------------

251.        function Get_BooleanTo API docTo body

252.          (Key_File   : G_Key_FileTo API docTo spec;

253.           Group_Name : String;

254.           Key        : String;

255.           Error      : Glib.Error.GErrorTo API docTo spec := null)

256.           return Boolean;

257.        procedure Set_BooleanTo API docTo body

258.          (Key_File   : G_Key_FileTo API docTo spec;

259.           Group_Name : String := "";

260.           Key        : String;

261.           Value      : Boolean);

262.        --  Association of a boolean value with Key under Group_Name.

263.        --

264.        --  Set_Boolean creates a key if Key cannot be found.

265.        --

266.        --  Get_Boolean returns the value associated with Key under Group_Name as a

267.        --  boolean.  If Key cannot be found then False is returned and error is set

268.        --  to Error_Not_Found. Likewise, if the value associated with Key cannot be

269.        --  interpreted as a boolean then False is returned and error is set to

270.        --  Error_Invalid_Value.

272.        type Boolean_List is array (Integer range <>) of Boolean;

274.        function Get_Boolean_ListTo API docTo body

275.          (Key_File   : G_Key_FileTo API docTo spec;

276.           Group_Name : String;

277.           Key        : String;

278.           Error      : Glib.Error.GErrorTo API docTo spec := null)

279.           return Boolean_ListTo API docTo spec;

280.        procedure Set_Boolean_ListTo API docTo body

281.          (Key_File   : G_Key_FileTo API docTo spec;

282.           Group_Name : String := "";

283.           Key        : String;

284.           List       : Boolean_ListTo API docTo spec);

285.        --  Associates a list of boolean values with Key under Group_Name.

286.        --  If Key cannot be found then it is created.

287.        --  If Group_Name is "", the start_group is used.

289.        ----------------------

290.        -- Gdouble (Double) --

291.        ----------------------

293.        function Get_DoubleTo API docTo body

294.          (Key_File   : G_Key_FileTo API docTo spec;

295.           Group_Name : String;

296.           Key        : String;

297.           Error      : Glib.Error.GErrorTo API docTo spec := null)

298.           return GdoubleTo API docTo spec;

299.        procedure Set_DoubleTo API docTo body

300.          (Key_File   : G_Key_FileTo API docTo spec;

301.           Group_Name : String := "";

302.           Key        : String;

303.           Value      : GdoubleTo API docTo spec);

304.        --  Association of a double value with Key under Group_Name.

305.        --

306.        --  Set_Double creates a key if Key cannot be found.

307.        --

308.        --  Get_Double returns the value associated with Key under Group_Name as a

309.        --  double. If Group_Name is "", the start_group is used.

310.        --

311.        --  If Key cannot be found then 0.0 is returned and error is set to

312.        --  Error_Key_Not_Found. Likewise, if the value associated

313.        --  with Key cannot be interpreted as a double then 0.0 is returned

314.        --  and error is set to Error_Invalid_Value.

316.        type Double_List is array (Integer range <>) of GdoubleTo API docTo spec;

317.        pragma Convention (C, Double_ListTo API docTo spec);

319.        function Get_Double_ListTo API docTo body

320.          (Key_File   : G_Key_FileTo API docTo spec;

321.           Group_Name : String;

322.           Key        : String;

323.           Error      : Glib.Error.GErrorTo API docTo spec := null)

324.           return Double_ListTo API docTo spec;

325.        procedure Set_Double_ListTo API docTo body

326.          (Key_File   : G_Key_FileTo API docTo spec;

327.           Group_Name : String := "";

328.           Key        : String;

329.           List       : Double_ListTo API docTo spec);

330.        --  Associates a list of double values with Key under

331.        --  Group_Name.  If Key cannot be found then it is created.

333.        --------------------

334.        -- Gint (Integer) --

335.        --------------------

337.        function Get_IntegerTo API docTo body

338.          (Key_File   : G_Key_FileTo API docTo spec;

339.           Group_Name : String;

340.           Key        : String;

341.           Error      : Glib.Error.GErrorTo API docTo spec := null)

342.           return GintTo API docTo spec;

343.        procedure Set_IntegerTo API docTo body

344.          (Key_File   : G_Key_FileTo API docTo spec;

345.           Group_Name : String := "";

346.           Key        : String;

347.           Value      : GintTo API docTo spec);

348.        --  Association of an integer value with Key under Group_Name.

349.        --

350.        --  Set_Integer creates a key if Key cannot be found.

351.        --

352.        --  If Get_Integer cannot find Key then 0 is returned and Error is set to

353.        --  Error_Key_Not_Found. Likewise, if the value associated

354.        --  with Key cannot be interpreted as an integer then 0 is returned

355.        --  and error is set to Error_Invalid_Value.

357.        type Integer_List is array (Integer range <>) of GintTo API docTo spec;

358.        pragma Convention (C, Integer_ListTo API docTo spec);

360.        function Get_Integer_ListTo API docTo body

361.          (Key_File   : G_Key_FileTo API docTo spec;

362.           Group_Name : String;

363.           Key        : String;

364.           Error      : Glib.Error.GErrorTo API docTo spec := null)

365.           return Integer_ListTo API docTo spec;

366.        procedure Set_Integer_ListTo API docTo body

367.          (Key_File   : G_Key_FileTo API docTo spec;

368.           Group_Name : String := "";

369.           Key        : String;

370.           List       : Integer_ListTo API docTo spec);

371.        --  Associates a list of integer values with Key under Group_Name.

372.        --  If Key cannot be found then it is created.

374.        ------------

375.        -- String --

376.        ------------

378.        function Get_StringTo API docTo body

379.          (Key_File   : G_Key_FileTo API docTo spec;

380.           Group_Name : String;

381.           Key        : String;

382.           Error      : Glib.Error.GErrorTo API docTo spec := null)

383.           return String;

384.        procedure Set_StringTo API docTo body

385.          (Key_File   : G_Key_FileTo API docTo spec;

386.           Group_Name : String := "";

387.           Key        : String;

388.           The_String : String);

389.        --  Associates a new string value with Key under Group_Name.

390.        --  If Key cannot be found then it is created.

391.        --  If Group_Name cannot be found then it is created.

392.        --  Unlike Set_Value, this function handles characters

393.        --  that need escaping, such as newlines.

395.        function Get_String_ListTo API docTo body

396.          (Key_File   : G_Key_FileTo API docTo spec;

397.           Group_Name : String;

398.           Key        : String;

399.           Error      : Glib.Error.GErrorTo API docTo spec := null)

400.           return GNAT.Strings.String_List;

401.        procedure Set_String_ListTo API docTo body

402.          (Key_File   : G_Key_FileTo API docTo spec;

403.           Group_Name : String := "";

404.           Key        : String;

405.           List       : GNAT.Strings.String_List);

406.        --  Associates a list of string values for Key under Group_Name.

407.        --  If Key cannot be found then it is created.

408.        --  If Group_Name cannot be found then it is created.

410.        -----------

411.        -- Value --

412.        -----------

414.        function Get_ValueTo API docTo body

415.          (Key_File   : G_Key_FileTo API docTo spec;

416.           Group_Name : String;

417.           Key        : String;

418.           Error      : Glib.Error.GErrorTo API docTo spec := null)

419.           return String;

420.        procedure Set_ValueTo API docTo body

421.          (Key_File   : G_Key_FileTo API docTo spec;

422.           Group_Name : String := "";

423.           Key        : String;

424.           Value      : String);

425.        --  Associates a new value with Key under Group_Name.

426.        --

427.        --  If Key cannot be found then it is created. If Group_Name cannot

428.        --  be found then it is created. To set an UTF-8 string which may contain

429.        --  characters that need escaping (such as newlines or spaces), use

430.        --  Set_String.

432.        -------------

433.        -- Loading --

434.        -------------

436.        function Load_From_DataTo API docTo body

437.          (Key_File : G_Key_FileTo API docTo spec;

438.           Data     : String;

439.           FlagsTo API docTo body    : G_Key_File_FlagsTo API docTo spec;

440.           Error    : Glib.Error.GErrorTo API docTo spec := null)

441.           return Boolean;

442.        --  Loads Data (which holds the contents of a key file) into an empty

443.        --  G_Key_File structure.  If the object cannot be created then Error

444.        --  is set to a G_Key_File_Error.

445.        --

446.        --  Returns True if a key file could be loaded, False otherwise

448.        function Load_From_Data_DirsTo API docTo body

449.          (Key_File : G_Key_FileTo API docTo spec;

450.           File     : String;

451.           FlagsTo API docTo body    : G_Key_File_FlagsTo API docTo spec;

452.           Error    : Glib.Error.GErrorTo API docTo spec := null)

453.           return Boolean;

454.        --  This function looks for a key file named File in the paths

455.        --  returned from g_get_user_data_dir() and g_get_system_data_dirs()

456.        --  and loads the file into Key_File.  If the file could not be loaded

457.        --  then Error is set to either a G_File_Error or G_Key_File_Error.

458.        --

459.        --  Returns True if a key file could be loaded, False otherwise

461.        function Load_From_DirsTo API docTo body

462.          (Key_File    : G_Key_FileTo API docTo spec;

463.           File        : String;

464.           Search_Dirs : GNAT.Strings.String_List;

465.           FlagsTo API docTo body       : G_Key_File_FlagsTo API docTo spec;

466.           Error       : Glib.Error.GErrorTo API docTo spec := null)

467.           return Boolean;

468.        --  This function looks for a key file named File in the paths specified

469.        --  in Search_Dirs and loads the file into Key_File.  If the file could not

470.        --  be loaded then an Error is set to either a G_File_Error or

471.        --  G_Key_File_Error.

472.        --

473.        --  Returns True if a key file could be loaded, False otherwise

475.        function Load_From_FileTo API docTo body

476.          (Key_File : G_Key_FileTo API docTo spec;

477.           File     : String;

478.           FlagsTo API docTo body    : G_Key_File_FlagsTo API docTo spec;

479.           Error    : Glib.Error.GErrorTo API docTo spec := null)

480.           return Boolean;

481.        --  Loads a key file into an empty G_Key_File structure.

482.        --  If the file could not be loaded then Error is set to

483.        --  either a G_File_Error or G_Key_File_Error.

484.        --

485.        --  Returns True if a key file could be loaded, False otherwise

487.        -------------

488.        -- Locales --

489.        -------------

491.        function Get_Locale_StringTo API docTo body

492.          (Key_File   : G_Key_FileTo API docTo spec;

493.           Group_Name : String;

494.           Key        : String;

495.           Locale     : String)

496.           return String;

497.        procedure Set_Locale_StringTo API docTo body

498.          (Key_File   : G_Key_FileTo API docTo spec;

499.           Group_Name : String := "";

500.           Key        : String;

501.           Locale     : String;

502.           The_String : String);

503.        --  Associates a string value for Key and Locale under Group_Name.

504.        --  If the translation for Key cannot be found then it is created.

506.        function Get_Locale_String_ListTo API docTo body

507.          (Key_File   : G_Key_FileTo API docTo spec;

508.           Group_Name : String;

509.           Key        : String;

510.           Locale     : String;

511.           Error      : Glib.Error.GErrorTo API docTo spec := null)

512.           return GNAT.Strings.String_List;

513.        procedure Set_Locale_String_ListTo API docTo body

514.          (Key_File   : G_Key_FileTo API docTo spec;

515.           Group_Name : String := "";

516.           Key        : String;

517.           Locale     : String;

518.           List       : GNAT.Strings.String_List);

519.        --  Associates a list of string values for Key and Locale under

520.        --  Group_Name.  If the translation for Key cannot be found then

521.        --  it is created.

523.     private

525.        pragma Import (C, Error_QuarkTo API docTo spec, "g_key_file_error_quark");

526.        pragma Import (C, FreeTo API docTo spec, "g_key_file_free");

527.        pragma Import (C, Set_List_SeparatorTo API docTo spec, "g_key_file_set_list_separator");

529.     end Glib.Key_FileTo API docTo specTo body;