## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2001-2003 ACT-Europe                 --

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.     --

31.     --  This package provides definitions for string conversions and i18n.

32.     --  See also Glib.Unicode.

33.     --

34.     --  </description>

35.     --  <c_version>1.3.11</c_version>

36.     --  <group>Glib, the general-purpose library</group>

38.     with Glib.ErrorTo API docTo specTo body; use Glib.ErrorTo API docTo specTo body;

39.     with Interfaces.C.Strings; use Interfaces.C.Strings;

41.     package Glib.ConvertTo API docTo specTo body is

42.        pragma Preelaborate;

44.        --  Convert_Error domain for GErrors:

46.        No_Conversion     : constant := 0;

47.        Illegal_Sequence  : constant := 1;

48.        Failed            : constant := 2;

49.        Partial_Input     : constant := 3;

50.        Bad_URI           : constant := 4;

51.        Not_Absolute_Path : constant := 5;

53.        function Convert_Error_DomainTo API docTo body return GQuarkTo API docTo spec;

54.        --  Return the error domain associated with Glib.Convert.

56.        procedure ConvertTo API docTo body

57.          (Str           : String;

58.           To_Codeset    : String;

59.           From_Codeset  : String;

60.           Bytes_Read    : out Natural;

61.           Bytes_Written : out Natural;

62.           Error         : GError_AccessTo API docTo spec := null;

63.           Result        : out String);

64.        --  Convert a string from one character set to another.

65.        --

66.        --  Str:           String to convert

67.        --  Result:        String converted, if no error.

68.        --  To_Codeset:    Name of character set into which to convert Str

69.        --  From_Codeset:  Character set of Str.

70.        --  Bytes_Read:    Number of bytes in the input string that were

71.        --                 successfully converted.

72.        --                 Even if the conversion was successful, this may be

73.        --                 less than Len if there were partial characters

74.        --                 at the end of the input. If the error

75.        --                 Illegal_Sequence occurs, the value

76.        --                 stored will the byte offset after the last valid

77.        --                 input sequence.

78.        --  Bytes_Written: Number of bytes stored in the output buffer.

79.        --  Error:         Location to store the error occuring, ignored if null.

80.        --                 Any of the errors in Convert_Error_Domain may occur.

82.        function ConvertTo API docTo body

83.          (Str           : String;

84.           To_Codeset    : String;

85.           From_Codeset  : String;

86.           Error         : GError_AccessTo API docTo spec := null) return String;

87.        --  Same as above, but return a String directly.

89.        procedure ConvertTo API docTo body

90.          (Str           : chars_ptr;

91.           Len           : Natural;

92.           To_Codeset    : String;

93.           From_Codeset  : String;

94.           Bytes_Read    : out Natural;

95.           Bytes_Written : out Natural;

96.           Error         : GError_AccessTo API docTo spec := null;

97.           Result        : out String);

98.        --  Same as Convert procedure, but take a C string as input.

100.        function ConvertTo API docTo body

101.          (Str           : String;

102.           To_Codeset    : String;

103.           From_Codeset  : String;

104.           Bytes_Read    : access Natural;

105.           Bytes_Written : access Natural;

106.           Error         : GError_AccessTo API docTo spec := null) return chars_ptr;

107.        --  Same as Convert procedure, but return the result as a C string.

109.        function ConvertTo API docTo body

110.          (Str           : chars_ptr;

111.           Len           : Natural;

112.           To_Codeset    : String;

113.           From_Codeset  : String;

114.           Bytes_Read    : access Natural;

115.           Bytes_Written : access Natural;

116.           Error         : GError_AccessTo API docTo spec := null) return chars_ptr;

117.        --  Same as Convert procedure, but take and return the result as a C string.

119.        procedure Locale_To_UTF8To API docTo body

120.          (OS_String     : String;

121.           Bytes_Read    : out Natural;

122.           Bytes_Written : out Natural;

123.           Error         : GError_AccessTo API docTo spec := null;

124.           Result        : out String);

125.        --  Convert a string which is in the encoding used for strings by

126.        --  the C runtime (usually the same as that used by the operating

127.        --  system) in the current locale into a UTF-8 string.

128.        --

129.        --  OS_String:     A string in the encoding of the current locale

130.        --  Bytes_Read:    Number of bytes in the input string that were

131.        --                 successfully converted.

132.        --                 Even if the conversion was successful, this may be

133.        --                 less than Len if there were partial characters

134.        --                 at the end of the input. If the error

135.        --                 Illegal_Sequence occurs, the value

136.        --                 stored will the byte offset after the last valid

137.        --                 input sequence.

138.        --  Bytes_Written: Number of bytes stored in Result.

139.        --  Error:         Location to store the error occuring, ignored if null.

140.        --                 Any of the errors in Convert_Error_Domain may occur.

142.        function Locale_To_UTF8To API docTo body

143.          (OS_String     : String;

144.           Bytes_Read    : access Natural;

145.           Bytes_Written : access Natural;

146.           Error         : GError_AccessTo API docTo spec := null) return chars_ptr;

147.        --  Same as procedure Locale_To_UTF8, but return the raw C string for

148.        --  efficiency. The caller is responsible for freeing the resulting string.

150.        function Locale_To_UTF8To API docTo body (OS_String : String) return String;

151.        --  Same as procedure Locale_To_UTF8, but return only the String.

153.        procedure Locale_From_UTF8To API docTo body

154.          (UTF8_String   : String;

155.           Bytes_Read    : out Natural;

156.           Bytes_Written : out Natural;

157.           Error         : GError_AccessTo API docTo spec := null;

158.           Result        : out String);

159.        --  Convert a string from UTF-8 to the encoding used for strings by

160.        --  the C runtime (usually the same as that used by the operating

161.        --  system) in the current locale.

162.        --

163.        --  UTF8_String:   A UTF-8 encoded string

164.        --  Bytes_Read:    Number of bytes in the input string that were

165.        --                 successfully converted.

166.        --                 Even if the conversion was successful, this may be

167.        --                 less than Len if there were partial characters

168.        --                 at the end of the input. If the error

169.        --                 Illegal_Sequence occurs, the value

170.        --                 stored will the byte offset after the last valid

171.        --                 input sequence.

172.        --  Bytes_Written: Number of bytes stored in the output buffer.

173.        --  Error:         Location to store the error occuring, ignored if null.

174.        --                 Any of the errors in Convert_Error_Domain may occur.

176.        function Locale_From_UTF8To API docTo body

177.          (UTF8_String   : String;

178.           Bytes_Read    : access Natural;

179.           Bytes_Written : access Natural;

180.           Error         : GError_AccessTo API docTo spec := null) return chars_ptr;

181.        --  Same as procedure Locale_From_UTF8, but return the raw C string for

182.        --  efficiency. The caller is responsible for freeing the resulting string.

183.        --  Use the C "free" function to free this.

185.        function Locale_From_UTF8To API docTo body (UTF8_String : String) return String;

186.        --  Same as procedure Locale_From_UTF8, but return only the String.

188.        function Filename_To_UTF8To API docTo body

189.          (OS_String : String;

190.           Error     : GError_AccessTo API docTo spec := null) return String;

191.        --  Convert a string which is in the encoding used for filenames

192.        --  into a UTF-8 string.

194.        function Filename_From_UTF8To API docTo body

195.          (UTF8_String : String;

196.           Error       : GError_AccessTo API docTo spec := null) return String;

197.        --  Convert a string from UTF-8 to the encoding used for filenames.

199.        function Filename_From_URITo API docTo body

200.          (URI      : String;

201.           Hostname : access chars_ptr;

202.           Error    : GError_AccessTo API docTo spec := null) return String;

203.        --  Convert an escaped UTF-8 encoded URI to a local filename in the

204.        --  encoding used for filenames.

205.        --

206.        --  URI:      A uri describing a filename (escaped, encoded in UTF-8).

207.        --  Hostname: Location to store hostname for the URI.

208.        --            If there is no hostname in the URI, null will be

209.        --            stored in this location.

210.        --  Error:    Location to store the error occuring, ignored if null.

211.        --            Any of the errors in Convert_Error_Domain may occur.

213.        function Filename_To_URITo API docTo body

214.          (Filename : String;

215.           Hostname : String := "";

216.           Error    : GError_AccessTo API docTo spec := null) return String;

217.        --  Convert an absolute filename to an escaped UTF-8 encoded URI.

218.        --

219.        --  Filename: An absolute filename specified in the encoding

220.        --            used for filenames by the operating system.

221.        --  Hostname: A UTF-8 encoded hostname, or "" for none.

222.        --  Error:    Location to store the error occuring, ignored if null.

223.        --            Any of the errors in Convert_Error may occur.

225.        function Escape_TextTo API docTo body (S : String) return String;

226.        --  Escape the text so that it is interpreted as-is by the Pango markup

227.        --  language

229.     private

231.        pragma Import (C, Convert_Error_DomainTo API docTo spec, "g_convert_error_quark");

233.     end Glib.ConvertTo API docTo specTo body;