## 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-2002 ACT-Europe                 --

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

32.     --  !!! Important note !!!: this package is now considered as deprecated in

33.     --  GtkAda 2.x. You should use the types and subprograms in the Pango

34.     --  hierarchy, which correctly support internationalization, right-to-left

35.     --  writings, easy resizing of fonts, truetype fonts....

36.     --

37.     --  For backward compatibility, a new subprogram From_Description has been

38.     --  added to this package, which gives access to the more advanced font

39.     --  handling.

40.     --

41.     --

42.     --  This is the base package for handling fonts.

43.     --  GtkAda knows about bitmap and vectorial fonts, and can draw both.

44.     --  The list of fonts available to you depends on what is installed on

45.     --  your system.

46.     --

47.     --  The name of the font is indicated in the standard X11 fashion, namely:

48.     --  (example extracted from the Xlib manual):

49.     --

50.     --  -adobe-courier-bold-o-normal--10-100-75-75-m-60-iso8859-1

51.     --  where:

52.     --    - adobe     : foundry

53.     --    - courier   : font family

54.     --    - bold      : weight (e.g. bold, medium)

55.     --    - o         : slant (e.g. roman, italic, oblique)

56.     --    - normal    : set width (e.g. normal, condensed, narrow, double)

57.     --    - 10        : pixels

58.     --    - 100       : points (in tenths of a point)

59.     --    - 75        : horizontal resolution in dpi

60.     --    - 75        : vertical resolution in dpi

61.     --    - m         : spacing (e.g. monospace or proportional)

62.     --    - 60        : average width (in tenths of a pixel)

63.     --    - iso8859-1 : character set

64.     --

65.     --  Any of the fields can have a '*' instead, so that the system will

66.     --  automatically find a font that matches the rest of the string, and won't

67.     --  care about that specific field.

68.     --

69.     --  An easy way to select a font is by using some external programs,

70.     --  for instance xfontsel, xlsfont, gfontsel, or even the font selection

71.     --  dialog example in the testgtk/ directory of the GtkAda distribution.

72.     --

73.     --  But the easiest way to create a font is to use a Pango_Font_Description.

74.     --  See package Pango.Font for more details about this structure.

75.     --

76.     --  Some of the functions below should be used only for wide-character strings.

77.     --  This is needed for languages with more than 256 characters.

78.     --

79.     --  Wide character values between 0 and 127 are always identical in meaning to

80.     --  the ASCII character codes.

81.     --  An alternative to wide characters is multi-byte characters, which extend

82.     --  normal char strings to cope with larger character sets. As the name

83.     --  suggests, multi-byte characters use a different number of bytes to store

84.     --  different character codes. For example codes 0-127 (i.e. the ASCII codes)

85.     --  often use just one byte of memory, while other codes may use 2, 3 or even

86.     --  4 bytes. Multi-byte characters have the advantage that they can often be

87.     --  used in an application with little change, since strings are still

88.     --  represented as arrays of char values. However multi-byte strings are much

89.     --  easier to manipulate since the character are all of the same size.

90.     --

91.     --  On Unix systems, the external utility 'xfd' can be used to display all

92.     --  the characters in a font.

93.     --

94.     --  </description>

95.     --  <c_version>1.3.6</c_version>

96.     --  <screenshot>font</screenshot>

97.     --  <group>Gdk, the low-level API</group>

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

100.     with Gdk.TypesTo API docTo spec;

101.     with Pango.FontTo API docTo specTo body;

103.     package Gdk.FontTo API docTo specTo body is

105.        subtype Gdk_Font is Gdk.Gdk_FontTo API docTo spec;

106.        --  A font used to draw text.

107.        --  This can represent a bitmap font, a scalable (vectorial) font, or

108.        --  a fontset. A fontset is a list of comma-separated fonts, that permits

109.        --  GtkAda to obtain the fonts needed for a variety of locales from a

110.        --  single locale-independent base font name. The single base font name

111.        --  should name a family of fonts whose members are encoded in the various

112.        --  charsets needed by the locales of interest.

113.        --  The algorithm used to select the font is described in the manual page

114.        --  for XCreateFontSet(3X).

116.        Null_Font : constant Gdk_FontTo API docTo spec;

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

119.        --  Return the internal value associated with Gdk_Font.

121.        procedure LoadTo API docTo body (Font : out Gdk_FontTo API docTo spec; Font_Name : String);

122.        --  Load a new font, given its name.

123.        --  This is the first step before using a font.

124.        --  The font is first looked up in the cache, and if it was already

125.        --  loaded, it is not reloaded again. Thus, it does not harm to call

126.        --  this function multiple times with the same Font_Name.

127.        --  Null_Font is returned if the font could not be loaded.

128.        --

129.        --  See From_Description below for another way of creating a Gdk_Font.

131.        procedure Fontset_LoadTo API docTo body (Font : out Gdk_FontTo API docTo spec; Fontset_Name : String);

132.        --  Load a new font set.

133.        --  Fontset_Name is a comma-separated list of fonts that will be loaded

134.        --  as part of the fontset.

136.        function From_DescriptionTo API docTo body

137.          (Font_Desc : Pango.Font.Pango_Font_DescriptionTo API docTo spec) return Gdk.Font.Gdk_FontTo API docTo spec;

138.        --  Create a new Gdk_Font from the given Pango_Font_Description.

139.        --  This is a convenient function to create fonts from, because

140.        --  a Pango_Font_Description is a higher level description of a font

141.        --  attributes.

143.        procedure RefTo API docTo body (Font : Gdk_FontTo API docTo spec);

144.        --  Increment the reference counter for the font.

145.        --  You should not make any assumption of the initial value of the fonts

146.        --  returned by Load or Fontset_Load, since these can be extracted from a

147.        --  cache.

149.        procedure UnrefTo API docTo body (Font : Gdk_FontTo API docTo spec);

150.        --  Decrement the reference counter for the font.

151.        --  When this counter reaches 0, the font is deleted from memory.

153.        function IdTo API docTo body (Font : Gdk_FontTo API docTo spec) return GintTo API docTo spec;

154.        --  Return the X font id for the font.

155.        --  This Id will only be needed if you want to call directly X11 functions,

156.        --  you won't need it with GtkAda.

158.        function EqualTo API docTo body (Fonta, Fontb : Gdk_FontTo API docTo spec) return Boolean;

159.        --  Compare two fonts or two fontsets for equality.

160.        --  Two fonts are equal if they have the same font Id.

161.        --  Two fontsets are equal if the name given to Fontset_Load was the same.

163.        function Get_AscentTo API docTo body (Font : Gdk_FontTo API docTo spec) return GintTo API docTo spec;

164.        --  Return the maximal ascent for the font.

165.        --  This is the logical extent above the baseline for spacing between two

166.        --  lines.

168.        function Get_DescentTo API docTo body (Font : Gdk_FontTo API docTo spec) return GintTo API docTo spec;

169.        --  Return the maximal descent for the font.

170.        --  This is the logical extent below the baseline for spacing between two

171.        --  lines.

173.        function String_WidthTo API docTo body (Font : Gdk_FontTo API docTo spec; Str : String) return GintTo API docTo spec;

174.        --  Return the width in pixels that Str will occupy if drawn with Font.

175.        --  The value returned is the distance between the origin of the text and

176.        --  the position at which the next string should be drawn.

178.        function String_WidthTo API docTo body

179.          (Font : Gdk_FontTo API docTo spec; Text : Gdk.Types.Gdk_WStringTo API docTo spec) return GintTo API docTo spec;

180.        --  Return the width in pixels that Text will occupy on the screen.

181.        --  This function should be used with strings that contain Unicode

182.        --  characters

184.        function Char_WidthTo API docTo body (Font : Gdk_FontTo API docTo spec; CharTo API docTo body : Character) return GintTo API docTo spec;

185.        --  Return the width in pixels occupied by a single character on the screen.

186.        --  The value returned is the distance between Char's origin on the screen

187.        --  and the origin of the next character in the string.

189.        function Char_WidthTo API docTo body

190.          (Font : Gdk_FontTo API docTo spec; CharTo API docTo body : Gdk.Types.Gdk_WCharTo API docTo spec) return GintTo API docTo spec;

191.        --  Return the width in pixels occupied by a single wide-character.

193.        function String_MeasureTo API docTo body (Font : Gdk_FontTo API docTo spec; Str : String) return GintTo API docTo spec;

194.        --  Determine the distance from the origin to the rightmost portion of Str.

195.        --  This is not the correct value for determining the origin of the next

196.        --  portion when drawing text in multiple pieces.

197.        --  See String_Width instead.

199.        function Char_MeasureTo API docTo body (Font : Gdk_FontTo API docTo spec; CharTo API docTo body : Character) return GintTo API docTo spec;

200.        --  Return the width in pixels of Char.

201.        --  As opposed to Char_Width, the value returned is not the distance at

202.        --  which the next character should be drawn.

203.        --  This is also called the right bearing of the character.

205.        function String_HeightTo API docTo body (Font : Gdk_FontTo API docTo spec; Str : String) return GintTo API docTo spec;

206.        --  Return the height in pixels of the string.

207.        --  This is the total height, and you can not easily tell how this height

208.        --  is split around the baseline.

210.        function Char_HeightTo API docTo body (Font : Gdk_FontTo API docTo spec; Char : Character) return GintTo API docTo spec;

211.        --  Return the total height in pixels of a single character.

213.        procedure String_ExtentsTo API docTo body

214.          (Font     : Gdk.Font.Gdk_FontTo API docTo spec;

215.           Str      : String;

216.           Lbearing : out GintTo API docTo spec;

217.           Rbearing : out GintTo API docTo spec;

218.           Width    : out GintTo API docTo spec;

219.           Ascent   : out GintTo API docTo spec;

220.           Descent  : out GintTo API docTo spec);

221.        --  Return the metrics for a given text.

222.        --  See the picture for more explanations on all the fields.

223.        --  Lbearing : Origin to left edge of character.

224.        --  Rbearing : Origin to right edge of character.

225.        --  Width    : Advance to next character's origin.

226.        --  Ascent   : Baseline to top edge of character.

227.        --  Descent  : Baseline to bottom edge of character.

229.        procedure String_ExtentsTo API docTo body

230.          (Font        : Gdk_FontTo API docTo spec;

231.           Text        : Gdk.Types.Gdk_WStringTo API docTo spec;

232.           Lbearing    : out GintTo API docTo spec;

233.           Rbearing    : out GintTo API docTo spec;

234.           Width       : out GintTo API docTo spec;

235.           Ascent      : out GintTo API docTo spec;

236.           Descent     : out GintTo API docTo spec);

237.        --  Return all the metrics for a given wide-character string.

238.        --  See the picture for more explanations on the returned values.

240.     private

241.        Null_FontTo API docTo spec : constant Gdk_FontTo API docTo spec := null;

242.        pragma Import (C, Get_TypeTo API docTo spec, "gdk_font_get_type");

243.        pragma Import (C, Char_HeightTo API docTo spec, "gdk_char_height");

244.        pragma Import (C, IdTo API docTo spec, "gdk_font_id");

245.        pragma Import (C, RefTo API docTo spec, "gdk_font_ref");

246.        pragma Import (C, UnrefTo API docTo spec, "gdk_font_unref");

247.     end Gdk.FontTo API docTo specTo body;