## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2002-2005 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 a high-level object that is capable of arranging text

32.     --  in a visually correct manner. It supports international character sets,

33.     --  although all strings should be Utf8, supports left-to-right and

34.     --  right-to-left writing systems, is capable of handling multi-line texts, and

35.     --  properly aligns tab characters in the text.

36.     --

37.     --  This is the base type that is used in the standard gtk+ widget for all the

38.     --  widgets that display some text on the screen.

39.     --

40.     --  Since it works directly with Pango.Font.Pango_Font_Description fonts, it is

41.     --  also much better at handling resizing of text, wrapping,... than direct

42.     --  calls to Gdk.Drawable.Draw_Text.

43.     --

44.     --  The idea is that this widget is used to compute the layout of the

45.     --  characters (ie their screen position). It doesn't do any rendering,

46.     --  however, and should be used in conjonction with Gdk.Drawable.Draw_Layout to

47.     --  actually display something on the screen.

48.     --

49.     --  This widget is independent from any specific drawing systems, and might for

50.     --  instance be used to create postscript documents, for direct access to the

51.     --  win32 API,...

52.     --

53.     --  This widget represents one of the fundamental additions to gtk+ 2.0 over

54.     --  what previously existed in the gtk+ 1.x series. It obsoletes the package

55.     --  Gdk.Font, which should only be used for legacy applications.

56.     --

57.     --  </description>

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

60.     with GlibTo API docTo specTo body;

61.     with Pango.AttributesTo API docTo specTo body;

62.     with Pango.ContextTo API docTo specTo body;

63.     with Pango.FontTo API docTo specTo body;

64.     with Pango.TabsTo API docTo specTo body;

65.     with Glib.ObjectTo API docTo specTo body;

66.     with Gdk.RectangleTo API docTo specTo body;

67.     with Gtkada.TypesTo API docTo specTo body;

69.     package Pango.LayoutTo API docTo specTo body is

71.        type Pango_Layout_RecordTo API docTo body is new Glib.Object.GObject_RecordTo API docTo specTo body with private;

72.        type Pango_Layout is access all Pango_Layout_RecordTo API docTo specTo body'Class;

73.        --  A widget that allows you to easily display text, including handling of

74.        --  internationalization, right-to-left writing,...

75.        --  See the function Gtk.Widget.Create_Pango_Layout for more information on

76.        --  how to create layouts

77.        --  Use Glib.Object.Unref to destroy a Pango_Layout

78.        --  See Gdk.Drawable.Draw_Layout for how to actually display the layout on

79.        --  the screen.

81.        type Pango_Alignment is

82.          (Pango_Align_Left,

83.           Pango_Align_Center,

84.           Pango_Align_Right);

85.        pragma Convention (C, Pango_AlignmentTo API docTo spec);

86.        --  The alignment for each line of the layout

88.        type Pango_Wrap_Mode is

89.          (Pango_Wrap_Word,

90.           Pango_Wrap_Char);

91.        pragma Convention (C, Pango_Wrap_ModeTo API docTo spec);

92.        --  The wrap mode for a layout

94.        type Pango_Ellipsize_Mode is

95.          (Ellipsize_None,

96.           Ellipsize_Start,

97.           Ellipsize_Middle,

98.           Ellipsize_End);

99.        --  This type describes what sort of (if any) ellipsization should be

100.        --  applied to a line of text. In the ellipsization process characters are

101.        --  removed from the text in order to make it fit to a given width and

102.        --  replaced with an ellipsis.

105.        -----------------------

106.        -- Creating a layout --

107.        -----------------------

108.        --  A layout can be created in two ways: either from a widget

109.        --  (Gtk.Widget.Create_Pango_Layout), from which it will inherit the font

110.        --  and various other attributes, or directly from a Pango_Context.

112.        procedure Gdk_NewTo API docTo body

113.          (Layout : out Pango_LayoutTo API docTo spec;

114.           Context : access Pango.Context.Pango_Context_RecordTo API docTo specTo body'Class);

115.        --  Create a new layout, based on context.

117.        --------------

118.        -- Contexts --

119.        --------------

121.        function Get_ContextTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body)

122.           return Pango.Context.Pango_ContextTo API docTo spec;

123.        --  Return the context of the layout. The returned value is the internal

124.        --  context itself, so you must Glib.Object.Ref it if you need to keep a

125.        --  reference. You shouldn't Unref it.

127.        procedure Set_Font_DescriptionTo API docTo body

128.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

129.           Font   : Pango.Font.Pango_Font_DescriptionTo API docTo spec);

130.        --  Change the font used in the layout.

131.        --  If not font description is set for the layout, the font description from

132.        --  the layout's context is used.

134.        procedure Context_ChangedTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body);

135.        --  Forces recomputation of any state in Layout that might depend

136.        --  on the layout's context. This function should be called if you make

137.        --  changes to the context subsequent to creating the layout.

139.        -----------

140.        -- Lines --

141.        -----------

143.        type Pango_Layout_Line is new Glib.C_ProxyTo API docTo spec;

145.        function Get_LineTo API docTo body

146.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

147.           Line   : Natural) return Pango_Layout_LineTo API docTo spec;

148.        --  Retrieve a particular line from Layout.

149.        --  Line must be between 0 and Get_Line_Count (Layout) - 1. null is returned

150.        --  if the index is out of range.

151.        --  The layout line can be Ref'ed and retained, but will become invalid if

152.        --  changes are made to Layout.

154.        procedure Line_RefTo API docTo body (Line : Pango_Layout_LineTo API docTo spec);

155.        --  Increase the reference count of Line by 1.

157.        procedure Line_UnrefTo API docTo body (Line : Pango_Layout_LineTo API docTo spec);

158.        --  Decrease the reference count of Line by 1. If the result is 0, the line

159.        --  and all associated memory will be destroyed.

161.        function Line_Index_To_XTo API docTo body

162.          (Line     : Pango_Layout_LineTo API docTo spec;

163.           Index    : Integer;

164.           Trailing : Integer) return Glib.GintTo API docTo spec;

165.        --  Convert an index within a line to an X position.

166.        --  Index is the byte offset of a graphem within the layout.

167.        --  Trailing is an integer indicating the edge of the grapheme to retrieve

168.        --  the position of. If 0, the trailing edge of the grapheme, otherwise, the

169.        --  leading of the grapheme.

170.        --  The returned value is in pango units.

172.        ----------------------

173.        -- Getting the size --

174.        ----------------------

175.        --  Pango internally stores its sizes in pango units, which are a number of

176.        --  pixels (device units, when not drawing on the screen) multiplied by

177.        --  Pango_Scale. There are generally equivalent subprograms to get the sizes

178.        --  directly in pixels.

180.        procedure Get_ExtentsTo API docTo body

181.          (Layout       : access Pango_Layout_RecordTo API docTo specTo body;

182.           Ink_RectTo API docTo body     : out Gdk.Rectangle.Gdk_RectangleTo API docTo spec;

183.           Logical_RectTo API docTo body : out Gdk.Rectangle.Gdk_RectangleTo API docTo spec);

184.        --  Compute the logical and ink extents of Layout. Logical extents

185.        --  are usually what you want for positioning things. The extents

186.        --  are given in pango units; layout coordinates begin at the

187.        --  top left corner of the layout.

188.        --  Logical_Rect is the overall size of the layout, ie it includes Ink_Rect

189.        --  (where the text is actually drawn) and a small border around it.

191.        procedure Get_SizeTo API docTo body

192.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

193.           Width  : out Glib.GintTo API docTo spec;

194.           Height : out Glib.GintTo API docTo spec);

195.        --  Return the logical size, in pango units, of the layout. This is a

196.        --  convenience function around Get_Extents.

198.        procedure Get_Pixel_ExtentsTo API docTo body

199.          (Layout       : access Pango_Layout_RecordTo API docTo specTo body;

200.           Ink_RectTo API docTo body     : out Gdk.Rectangle.Gdk_RectangleTo API docTo spec;

201.           Logical_RectTo API docTo body : out Gdk.Rectangle.Gdk_RectangleTo API docTo spec);

202.        --  Same as Get_Extents, but the returned values are in pixels (or device

203.        --  units when not drawing on the screen).

205.        procedure Get_Pixel_SizeTo API docTo body

206.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

207.           Width  : out Glib.GintTo API docTo spec;

208.           Height : out Glib.GintTo API docTo spec);

209.        --  Same as Get_Size, but the returned values are in pixels.

211.        procedure XY_To_IndexTo API docTo body

212.          (Layout           : access Pango_Layout_RecordTo API docTo specTo body;

213.           X_Pango, Y_Pango : Glib.GintTo API docTo spec;

214.           Byte_Index       : out Integer;

215.           Trailing         : out Integer;

216.           Exact            : out Boolean);

217.        --  Convert from X and Y positions within a layout to the byte index of the

218.        --  character at that logical position.

219.        --  X and Y are given in pango units, not pixels.

220.        --  If the position is not inside the layout, the closest position is

221.        --  chosen, and Exact is set to False.

222.        --  Trailing is the position in the grapheme where the user clicked. It will

223.        --  either be 0 (left side) or the number of characters in the grapheme. In

224.        --  some character sets, a given character can be represented by multiple

225.        --  signs on the screen, which is what Trailing relates to.

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

228.        -- Manipulating the text --

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

230.        --  When initially created with Gtk.Widget.Create_Pango_Layout, the layout

231.        --  contains some text. Of course, this text may also be changed later in

232.        --  the life of the layout.

234.        procedure Set_TextTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body; Text : String);

235.        --  Change the text that the layout displays

236.        --  Text must be a valid UTF8 string. See Glib.Convert for useful conversion

237.        --  functions.

239.        function Get_TextTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body) return String;

240.        --  Return the text currently displayed in the layout.

241.        --  It is more efficient to use the iterators on the layout than get text if

242.        --  you do not need Ada-specific subprograms to act on the text.

244.        function Get_TextTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body)

245.           return Gtkada.Types.Chars_PtrTo API docTo spec;

246.        --  Same a Get_Text, but return directly the C string, which is more

247.        --  efficient. The returned value should not be freed or modified.

249.        function Get_Line_CountTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body)

250.           return Glib.GintTo API docTo spec;

251.        --  Return the number of lines in Layout

253.        procedure Set_MarkupTo API docTo body

254.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

255.           Markup : Glib.UTF8_StringTo API docTo spec);

256.        --  Change the text that layout displays.

257.        --  Markup must be a valid UTF8 String, and might contain markups as

258.        --  defined in the pango markup language.

260.        ------------------------

261.        -- Layouting the text --

262.        ------------------------

264.        procedure Set_JustifyTo API docTo body

265.          (Layout : access Pango_Layout_RecordTo API docTo specTo body; Justify : Boolean);

266.        --  Set whether or not each complete line should be stretched to fill the

267.        --  entire width of the layout. This stretching is typically done by adding

268.        --  whitespace, but for some scripts (such as Arabic), the justification is

269.        --  done by extending the characters.

271.        function Get_JustifyTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body) return Boolean;

272.        --  Return True if each complete line should be stretched to fill the entire

273.        --  width of the layout.

275.        procedure Set_AlignmentTo API docTo body

276.          (Layout    : access Pango_Layout_RecordTo API docTo specTo body'Class;

277.           AlignmentTo API docTo body : Pango_AlignmentTo API docTo spec);

278.        --  Set the alignment for the layout (how partial lines are positioned

279.        --  within the horizontal space available).

281.        function Get_AlignmentTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body)

282.          return Pango_AlignmentTo API docTo spec;

283.        --  Return the alignment for the layout.

285.        procedure Set_WidthTo API docTo body

286.          (Layout : access Pango_Layout_RecordTo API docTo specTo body; Width : Glib.GintTo API docTo spec);

287.        --  Set the width to which the lines of Layout should be wrapped. No

288.        --  wrapping will be performed if Width is -1.

289.        --  Width is given in pango units.

291.        function Get_WidthTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body) return Glib.GintTo API docTo spec;

292.        --  Return the wrapping width of Layout

294.        procedure Set_WrapTo API docTo body

295.          (Layout : access Pango_Layout_RecordTo API docTo specTo body; ModeTo API docTo body : Pango_Wrap_ModeTo API docTo spec);

296.        --  Sets the wrap style; the wrap style only has an effect if a width is set

297.        --  on the layout with pango_layout_set_width(). To turn off wrapping, set

298.        --  the width to -1.

300.        function Get_WrapTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body)

301.           return Pango_Wrap_ModeTo API docTo spec;

302.        --  Return the current wrap style

304.        procedure Set_TabsTo API docTo body

305.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

306.           Tabs   : Pango.Tabs.Pango_Tab_ArrayTo API docTo spec);

307.        --  Sets the tabs to use for Layout, overriding the default tabs (by

308.        --  default, tabs are every 8 spaces). If Tabs is Null_Tab_Array, the

309.        --  default tabs are reinstated. tabs is copied into the layout; you must

310.        --  free your copy of Tabs yourself.

312.        function Get_TabsTo API docTo body

313.          (Layout : access Pango_Layout_RecordTo API docTo specTo body) return Pango.Tabs.Pango_Tab_ArrayTo API docTo spec;

314.        --  Get the current tab array used by Layout. If no tab array

315.        --  has been set, then the default tabs are in use and Null_Tab_Array is

316.        --  returned.

317.        --  Default tabs are every 8 spaces. The return value should be freed with

318.        --  Pango.Tabs.Free.

320.        ----------------

321.        -- Attributes --

322.        ----------------

324.        procedure Set_AttributesTo API docTo body

325.          (Layout : access Pango_Layout_RecordTo API docTo specTo body;

326.           Attributes : Pango.Attributes.Pango_Attr_ListTo API docTo spec);

327.        --  Set the text attributes for a layout object.

328.        --  Passing null removes the current list of attributes

330.        function Get_AttributesTo API docTo body (Layout : access Pango_Layout_RecordTo API docTo specTo body)

331.           return Pango.Attributes.Pango_Attr_ListTo API docTo spec;

332.        --  Get the text attributes from a layout object

334.     private

335.        type Pango_Layout_RecordTo API docTo spec is new Glib.Object.GObject_RecordTo API docTo specTo body with null record;

337.        pragma Import (C, Line_RefTo API docTo spec, "pango_layout_line_ref");

338.        pragma Import (C, Line_UnrefTo API docTo spec, "pango_layout_line_unref");

339.        pragma Import (C, Line_Index_To_XTo API docTo spec, "pango_layout_line_index_to_x");

340.     end Pango.LayoutTo API docTo specTo body;

342.     --  missing:

343.     --  pango_layout_get_context

344.     --  pango_layout_copy

345.     --  pango_layout_set_attributes

346.     --  pango_layout_get_attributes

347.     --  pango_layout_set_markup_with_accel

348.     --  pango_layout_set_indent

349.     --  pango_layout_get_indent

350.     --  pango_layout_set_spacing

351.     --  pango_layout_get_spacing

352.     --  pango_layout_set_single_paragraph_mode

353.     --  pango_layout_get_single_paragraph_mode

354.     --  pango_layout_get_log_attrs

355.     --  pango_layout_index_to_pos

356.     --  pango_layout_get_cursor_pos

357.     --  pango_layout_move_cursor_visually

358.     --  pango_layout_get_lines

359.     --  pango_layout_line_index_to_x

360.     --  pango_layout_line_get_x_ranges

361.     --  pango_layout_line_get_extents

362.     --  pango_layout_line_get_pixel_extents

363.     --  pango_layout_get_iter

364.     --  pango_layout_iter_free

365.     --  pango_layout_iter_get_index

366.     --  pango_layout_iter_get_run

367.     --  pango_layout_iter_get_line

368.     --  pango_layout_iter_at_last_line

369.     --  pango_layout_iter_next_char

370.     --  pango_layout_iter_next_cluster

371.     --  pango_layout_iter_next_run

372.     --  pango_layout_iter_next_line

373.     --  pango_layout_iter_get_char_extents

374.     --  pango_layout_iter_get_cluster_extents

375.     --  pango_layout_iter_get_run_extents

376.     --  pango_layout_iter_get_line_extents

377.     --  pango_layout_iter_get_line_yrange

378.     --  pango_layout_iter_get_layout_extents

379.     --  pango_layout_iter_get_baseline