## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2001-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.     --

31.     --  This package provides high-level, system-independent handling of fonts. It

32.     --  supercedes the old Gdk.Font package, which should no longer be used.

33.     --

34.     --  Fonts are defined through several attributes, like their family, weight,

35.     --  size, style, ...

36.     --

37.     --  The Pango_Font_Description objects created by this package can either be

38.     --  used directly to draw text through Pango.Layout.Pango_Layout objects (and

39.     --  the associated Gdk.Drawable.Draw_Layout procedure), or by converting them

40.     --  to a Gdk_Font. The first method is the preferred one, and provides

41.     --  high-level handling of multi-line texts or tabs, when you have to handle

42.     --  this yourself in the second case.

43.     --

44.     --  </description>

45.     --  <group>Pango, font handling</group>

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

48.     with Glib.ObjectTo API docTo specTo body;

49.     with Glib.Generic_PropertiesTo API docTo specTo body; use Glib.Generic_PropertiesTo API docTo specTo body;

50.     pragma Elaborate_All (Glib.Generic_PropertiesTo API docTo specTo body);

51.     with Pango.EnumsTo API docTo specTo body;

52.     with System;

54.     package Pango.FontTo API docTo specTo body is

56.        type Pango_Font_Description is new Glib.C_ProxyTo API docTo spec;

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

59.        --  Return the internal gtk+ type associated with font descriptions.

61.        function CopyTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec) return Pango_Font_DescriptionTo API docTo spec;

62.        --  Return a newly allocated font description.

63.        --  This Pango_Font_Description needs to be free'ed after use.

65.        function EqualTo API docTo body

66.          (Desc1 : Pango_Font_DescriptionTo API docTo spec;

67.           Desc2 : Pango_Font_DescriptionTo API docTo spec) return Boolean;

68.        --  Return True if the two font descriptions are identical.

69.        --  Note that two font description may result in identical fonts being

70.        --  loaded, but still compare False.

72.        procedure FreeTo API docTo body (Desc : in out Pango_Font_DescriptionTo API docTo spec);

73.        --  Deallocate the given font description.

75.        function From_StringTo API docTo body (Str : String) return Pango_Font_DescriptionTo API docTo spec;

76.        --  Create a new font description from the given string representation

77.        --  of the given form: "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]". Any one

78.        --  of the options may be omitted.

79.        --    - FAMILY-LIST is a comma separated list (spaces are not allowed)

80.        --      of font families optionally terminated by a comma. If absent,

81.        --      the font family of the font that will be used is unspecified.

82.        --    - STYLE_OPTIONS is a whitespace separated list of words where each

83.        --      word describes either style, variant, weight, or stretch. Any

84.        --      unspecified style option is defaulted to "Normal", which

85.        --      respectively corresponds to Pango_Style_Normal, Pango_Weight_Normal,

86.        --      Pango_Variant_Normal, and Pango_Stretch_Normal.

87.        --    - SIZE is a decimal number describing the size of the font in points.

88.        --      If unspecified, a size of 0 will be used.

90.        function To_Font_DescriptionTo API docTo body

91.          (Family_Name : String := "";

92.           StyleTo API docTo body       : Pango.Enums.StyleTo API docTo spec := Pango.Enums.Pango_Style_Normal;

93.           VariantTo API docTo body     : Pango.Enums.VariantTo API docTo spec := Pango.Enums.Pango_Variant_Normal;

94.           WeightTo API docTo body      : Pango.Enums.WeightTo API docTo spec := Pango.Enums.Pango_Weight_Normal;

95.           StretchTo API docTo body     : Pango.Enums.StretchTo API docTo spec := Pango.Enums.Pango_Stretch_Normal;

96.           Size        : GintTo API docTo spec := 0) return Pango_Font_DescriptionTo API docTo spec;

97.        --  Create a new font decription from the given parameters.

99.        function To_StringTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec) return String;

100.        --  Create a string representation of a font description. The format

101.        --  of the string produced follows the syntax used by From_String.

102.        --  The family-list in the string description will have a terminating

103.        --  comma only if the last word of the list is a valid style option.

105.        function To_FilenameTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec) return String;

106.        --  Create a filename representation of a font description. The filename

107.        --  is identical to the result from calling To_String, but with underscores

108.        --  instead of characters that are untypical in filenames, and in lower

109.        --  case only.

111.        function Get_FamilyTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec) return String;

112.        --  Return the Family_Name of the given Pango_Font_Description.

114.        procedure Set_FamilyTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec; Name : String);

115.        --  Set the Family_Name of the given Pango_Font_Description.

117.        function Get_StyleTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec) return Pango.Enums.StyleTo API docTo spec;

118.        --  Return the Style of the given Pango_Font_Description.

120.        procedure Set_StyleTo API docTo body

121.          (Desc : Pango_Font_DescriptionTo API docTo spec; Style : Pango.Enums.StyleTo API docTo spec);

122.        --  Set the Style of the given Pango_Font_Description.

124.        function Get_VariantTo API docTo body

125.          (Desc : Pango_Font_DescriptionTo API docTo spec) return Pango.Enums.VariantTo API docTo spec;

126.        --  Return the Variant of the given Pango_Font_Description.

128.        procedure Set_VariantTo API docTo body

129.          (Desc : Pango_Font_DescriptionTo API docTo spec; Variant : Pango.Enums.VariantTo API docTo spec);

130.        --  Set the Variant of the given Pango_Font_Description.

132.        function Get_WeightTo API docTo body

133.          (Desc : Pango_Font_DescriptionTo API docTo spec) return Pango.Enums.WeightTo API docTo spec;

134.        --  Return the Weight of the given Pango_Font_Description.

136.        procedure Set_WeightTo API docTo body

137.          (Desc : Pango_Font_DescriptionTo API docTo spec; Weight : Pango.Enums.WeightTo API docTo spec);

138.        --  Set the Weight of the given Pango_Font_Description.

140.        function Get_StretchTo API docTo body

141.          (Desc : Pango_Font_DescriptionTo API docTo spec) return Pango.Enums.StretchTo API docTo spec;

142.        --  Return the Stretch of the given Pango_Font_Description.

144.        procedure Set_StretchTo API docTo body

145.          (Desc : Pango_Font_DescriptionTo API docTo spec; Stretch : Pango.Enums.StretchTo API docTo spec);

146.        --  Set the Stretch of the given Pango_Font_Description.

148.        function Get_SizeTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec) return GintTo API docTo spec;

149.        --  Return value: the size for the font description in pango units.

150.        --  (PANGO_SCALE pango units equals one point). Returns 0 if Desc hasn't

151.        --  been initialized.

153.        procedure Set_SizeTo API docTo body (Desc : Pango_Font_DescriptionTo API docTo spec; Size : GintTo API docTo spec);

154.        --  Set the size for the font description in pango units.  (PANGO_SCALE

155.        --  pango units equals one point)

157.        ---------------

158.        -- Languages --

159.        ---------------

160.        --  The following section provides types and subprograms to identify a

161.        --  specific script and language inside a font (Not all characters of a font

162.        --  are used for all languages)

164.        type Pango_Language is new Glib.C_ProxyTo API docTo spec;

166.        function Pango_Language_Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

167.        --  Return the internal value used to identify a Pango_Language

169.        function From_StringTo API docTo body (Language : String) return Pango_LanguageTo API docTo spec;

170.        --  Take a RFC-3066 format language tag as a string and convert it to a

171.        --  Pango_Language pointer that can be efficiently copied (copy the pointer)

172.        --  and compared with other language tags (compare the pointer). Language is

173.        --  something like "fr" (french), "ar" (arabic), "en" (english), "ru"

174.        --  (russian), ...

175.        --

176.        --  This function first canonicalizes the string by converting it to

177.        --  lowercase, mapping '_' to '-', and stripping all characters other than

178.        --  letters and '-'.

179.        --

180.        --  The returned value need not be freed, it is stored internally by gtk+ in

181.        --  a hash-table.

183.        -------------

184.        -- Metrics --

185.        -------------

186.        --  The following subprograms can be used to retrieve the metrics associated

187.        --  with the font. Note that such metrics might depend on the specific

188.        --  script/language in use.

190.        type Pango_Font_Metrics is new Glib.C_ProxyTo API docTo spec;

192.        type Pango_Font_Record is new Glib.Object.GObject_RecordTo API docTo specTo body with null record;

193.        type Pango_Font is access all Pango_Font_RecordTo API docTo spec'Class;

194.        --  Created through Pango.Context.Load_Font

196.        function Get_MetricsTo API docTo body

197.          (Font : access Pango_Font_RecordTo API docTo spec'Class;

198.           Language : Pango_LanguageTo API docTo spec := null) return Pango_Font_MetricsTo API docTo spec;

199.        --  Gets overall metric information for a font. Since the metrics may be

200.        --  substantially different for different scripts, a language tag can be

201.        --  provided to indicate that the metrics should be retrieved that

202.        --  correspond to the script(s) used by that language.

203.        --

204.        --  The returned value must be Unref'ed by the caller.

205.        --

206.        --  Language determines which script to get the metrics for, or null to

207.        --  indicate the metrics for the entire font.

209.        procedure RefTo API docTo body (Metrics : Pango_Font_MetricsTo API docTo spec);

210.        procedure UnrefTo API docTo body (Metrics : Pango_Font_MetricsTo API docTo spec);

211.        --  Ref or unref Metrics When the reference counter reaches 0, the memory is

212.        --  deallocated.

214.        function Get_AscentTo API docTo body (Metrics : Pango_Font_MetricsTo API docTo spec) return GintTo API docTo spec;

215.        --  Gets the ascent from a font metrics structure. The ascent is the

216.        --  distance from the baseline to the logical top of a line of text. (The

217.        --  logical top may be above or below the top of the actual drawn ink. It is

218.        --  necessary to lay out the text to figure where the ink will be).

219.        --

220.        --  The returned value is expressed in pango units, and must be divided by

221.        --  Pango_Scale to get the value in pixels.

223.        function Get_DescentTo API docTo body (Metrics : Pango_Font_MetricsTo API docTo spec) return GintTo API docTo spec;

224.        --  Gets the descent from a font metrics structure. The descent is the

225.        --  distance from the baseline to the logical bottom of a line of text. (The

226.        --  logical bottom may be above or below the bottom of the actual drawn

227.        --  ink. It is necessary to lay out the text to figure where the ink will

228.        --  be.)

229.        --

230.        --  The returned value is expressed in pango units, and must be divided by

231.        --  Pango_Scale to get the value in pixels.

233.        function Get_Approximate_Char_WidthTo API docTo body (Metrics : Pango_Font_MetricsTo API docTo spec)

234.           return GintTo API docTo spec;

235.        --  Gets the approximate character width for a font metrics structure.  This

236.        --  is merely a representative value useful, for example, for determining

237.        --  the initial size for a window. Actual characters in text will be wider

238.        --  and narrower than this.

239.        --

240.        --  The returned value is expressed in pango units, and must be divided by

241.        --  Pango_Scale to get the value in pixels.

243.        function Get_Approximate_Digit_WidthTo API docTo body (Metrics : Pango_Font_MetricsTo API docTo spec)

244.           return GintTo API docTo spec;

245.        --  Gets the approximate digit width for a font metrics structure.  This is

246.        --  merely a representative value useful, for example, for determining the

247.        --  initial size for a window. Actual digits in text can be wider and

248.        --  narrower than this, though this value is generally somewhat more

249.        --  accurate than the result of Get_Approximate_Char_Width.

250.        --

251.        --  The returned value is expressed in pango units, and must be divided by

252.        --  Pango_Scale to get the value in pixels.

254.        function Font_Metrics_Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

255.        --  Return the internal value associated with a Pango_Font_Metrics

257.        ----------------

258.        -- Properties --

259.        ----------------

260.        --  See the package Glib.Properties for more information on how to

261.        --  use properties

263.        pragma Import (C, Get_TypeTo API docTo spec, "pango_font_description_get_type");

265.        function To_AddressTo API docTo body

266.          (F : Pango_Font_DescriptionTo API docTo spec; Add : System.Address) return System.Address;

268.        package Desc_Properties is new Generic_Internal_Boxed_PropertyTo API docTo specTo body

269.          (Pango_Font_DescriptionTo API docTo spec, Get_TypeTo API docTo specTo body, To_AddressTo API docTo specTo body);

271.        type Property_Font_Description is new Desc_Properties.PropertyTo API docTo spec;

273.     private

274.        pragma Import (C, CopyTo API docTo spec, "pango_font_description_copy");

275.        pragma Import (C, Get_SizeTo API docTo spec, "pango_font_description_get_size");

276.        pragma Import (C, Set_SizeTo API docTo spec, "pango_font_description_set_size");

277.        pragma Import (C, Pango_Language_Get_TypeTo API docTo spec, "pango_language_get_type");

278.        pragma Import

279.          (C, Font_Metrics_Get_TypeTo API docTo spec, "pango_font_metrics_get_type");

280.        pragma Import (C, RefTo API docTo spec, "pango_font_metrics_ref");

281.        pragma Import (C, UnrefTo API docTo spec, "pango_font_metrics_unref");

282.        pragma Import (C, Get_AscentTo API docTo spec, "pango_font_metrics_get_ascent");

283.        pragma Import (C, Get_DescentTo API docTo spec, "pango_font_metrics_get_descent");

284.        pragma Import (C, Get_Approximate_Char_WidthTo API docTo spec,

285.                       "pango_font_metrics_get_approximate_char_width");

286.        pragma Import (C, Get_Approximate_Digit_WidthTo API docTo spec,

287.                       "pango_font_metrics_get_approximate_digit_width");

289.        pragma Import (C, Get_StyleTo API docTo spec, "pango_font_description_get_style");

290.        pragma Import (C, Set_StyleTo API docTo spec, "pango_font_description_set_style");

291.        pragma Import (C, Get_VariantTo API docTo spec, "pango_font_description_get_variant");

292.        pragma Import (C, Set_VariantTo API docTo spec, "pango_font_description_set_variant");

293.        pragma Import (C, Get_WeightTo API docTo spec, "pango_font_description_get_weight");

294.        pragma Import (C, Set_WeightTo API docTo spec, "pango_font_description_set_weight");

295.        pragma Import (C, Get_StretchTo API docTo spec, "pango_font_description_get_stretch");

296.        pragma Import (C, Set_StretchTo API docTo spec, "pango_font_description_set_stretch");

297.     end Pango.FontTo API docTo specTo body;

299.     --  Missing:

300.     --  pango_language_matches