File: pango-layout.ads

package info (click to toggle)
libgtkada2 2.8.1-6lenny3
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,496 kB
  • ctags: 3,886
  • sloc: ada: 103,189; ansic: 45,411; perl: 5,500; sh: 2,812; makefile: 1,169; xml: 19
file content (373 lines) | stat: -rw-r--r-- 15,466 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
-----------------------------------------------------------------------
--               GtkAda - Ada95 binding for Gtk+/Gnome               --
--                                                                   --
--                Copyright (C) 2002-2005 AdaCore                    --
--                                                                   --
-- This library is free software; you can redistribute it and/or     --
-- modify it under the terms of the GNU General Public               --
-- License as published by the Free Software Foundation; either      --
-- version 2 of the License, or (at your option) any later version.  --
--                                                                   --
-- This library is distributed in the hope that it will be useful,   --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --
-- General Public License for more details.                          --
--                                                                   --
-- You should have received a copy of the GNU General Public         --
-- License along with this library; if not, write to the             --
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --
-- Boston, MA 02111-1307, USA.                                       --
--                                                                   --
-----------------------------------------------------------------------

--  <description>
--
--  This package provides a high-level object that is capable of arranging text
--  in a visually correct manner. It supports international character sets,
--  although all strings should be Utf8, supports left-to-right and
--  right-to-left writing systems, is capable of handling multi-line texts, and
--  properly aligns tab characters in the text.
--
--  This is the base type that is used in the standard gtk+ widget for all the
--  widgets that display some text on the screen.
--
--  Since it works directly with Pango.Font.Pango_Font_Description fonts, it is
--  also much better at handling resizing of text, wrapping,... than direct
--  calls to Gdk.Drawable.Draw_Text.
--
--  The idea is that this widget is used to compute the layout of the
--  characters (ie their screen position). It doesn't do any rendering,
--  however, and should be used in conjonction with Gdk.Drawable.Draw_Layout to
--  actually display something on the screen.
--
--  This widget is independent from any specific drawing systems, and might for
--  instance be used to create postscript documents, for direct access to the
--  win32 API,...
--
--  This widget represents one of the fundamental additions to gtk+ 2.0 over
--  what previously existed in the gtk+ 1.x series. It obsoletes the package
--  Gdk.Font, which should only be used for legacy applications.
--
--  </description>
--  <group>Pango, font handling</group>

with Glib;
with Pango.Attributes;
with Pango.Context;
with Pango.Font;
with Pango.Tabs;
with Glib.Object;
with Gdk.Rectangle;
with Gtkada.Types;

package Pango.Layout is

   type Pango_Layout_Record is new Glib.Object.GObject_Record with private;
   type Pango_Layout is access all Pango_Layout_Record'Class;
   --  A widget that allows you to easily display text, including handling of
   --  internationalization, right-to-left writing,...
   --  See the function Gtk.Widget.Create_Pango_Layout for more information on
   --  how to create layouts
   --  Use Glib.Object.Unref to destroy a Pango_Layout
   --  See Gdk.Drawable.Draw_Layout for how to actually display the layout on
   --  the screen.

   type Pango_Alignment is
     (Pango_Align_Left,
      Pango_Align_Center,
      Pango_Align_Right);
   pragma Convention (C, Pango_Alignment);
   --  The alignment for each line of the layout

   type Pango_Wrap_Mode is
     (Pango_Wrap_Word,
      Pango_Wrap_Char);
   pragma Convention (C, Pango_Wrap_Mode);
   --  The wrap mode for a layout

   type Pango_Ellipsize_Mode is
     (Ellipsize_None,
      Ellipsize_Start,
      Ellipsize_Middle,
      Ellipsize_End);
   --  This type describes what sort of (if any) ellipsization should be
   --  applied to a line of text. In the ellipsization process characters are
   --  removed from the text in order to make it fit to a given width and
   --  replaced with an ellipsis.


   -----------------------
   -- Creating a layout --
   -----------------------
   --  A layout can be created in two ways: either from a widget
   --  (Gtk.Widget.Create_Pango_Layout), from which it will inherit the font
   --  and various other attributes, or directly from a Pango_Context.

   procedure Gdk_New
     (Layout : out Pango_Layout;
      Context : access Pango.Context.Pango_Context_Record'Class);
   --  Create a new layout, based on context.

   --------------
   -- Contexts --
   --------------

   function Get_Context (Layout : access Pango_Layout_Record)
      return Pango.Context.Pango_Context;
   --  Return the context of the layout. The returned value is the internal
   --  context itself, so you must Glib.Object.Ref it if you need to keep a
   --  reference. You shouldn't Unref it.

   procedure Set_Font_Description
     (Layout : access Pango_Layout_Record;
      Font   : Pango.Font.Pango_Font_Description);
   --  Change the font used in the layout.
   --  If not font description is set for the layout, the font description from
   --  the layout's context is used.

   procedure Context_Changed (Layout : access Pango_Layout_Record);
   --  Forces recomputation of any state in Layout that might depend
   --  on the layout's context. This function should be called if you make
   --  changes to the context subsequent to creating the layout.

   -----------
   -- Lines --
   -----------

   type Pango_Layout_Line is new Glib.C_Proxy;

   function Get_Line
     (Layout : access Pango_Layout_Record;
      Line   : Natural) return Pango_Layout_Line;
   --  Retrieve a particular line from Layout.
   --  Line must be between 0 and Get_Line_Count (Layout) - 1. null is returned
   --  if the index is out of range.
   --  The layout line can be Ref'ed and retained, but will become invalid if
   --  changes are made to Layout.

   procedure Line_Ref (Line : Pango_Layout_Line);
   --  Increase the reference count of Line by 1.

   procedure Line_Unref (Line : Pango_Layout_Line);
   --  Decrease the reference count of Line by 1. If the result is 0, the line
   --  and all associated memory will be destroyed.

   function Line_Index_To_X
     (Line     : Pango_Layout_Line;
      Index    : Integer;
      Trailing : Integer) return Glib.Gint;
   --  Convert an index within a line to an X position.
   --  Index is the byte offset of a graphem within the layout.
   --  Trailing is an integer indicating the edge of the grapheme to retrieve
   --  the position of. If 0, the trailing edge of the grapheme, otherwise, the
   --  leading of the grapheme.
   --  The returned value is in pango units.

   ----------------------
   -- Getting the size --
   ----------------------
   --  Pango internally stores its sizes in pango units, which are a number of
   --  pixels (device units, when not drawing on the screen) multiplied by
   --  Pango_Scale. There are generally equivalent subprograms to get the sizes
   --  directly in pixels.

   procedure Get_Extents
     (Layout       : access Pango_Layout_Record;
      Ink_Rect     : out Gdk.Rectangle.Gdk_Rectangle;
      Logical_Rect : out Gdk.Rectangle.Gdk_Rectangle);
   --  Compute the logical and ink extents of Layout. Logical extents
   --  are usually what you want for positioning things. The extents
   --  are given in pango units; layout coordinates begin at the
   --  top left corner of the layout.
   --  Logical_Rect is the overall size of the layout, ie it includes Ink_Rect
   --  (where the text is actually drawn) and a small border around it.

   procedure Get_Size
     (Layout : access Pango_Layout_Record;
      Width  : out Glib.Gint;
      Height : out Glib.Gint);
   --  Return the logical size, in pango units, of the layout. This is a
   --  convenience function around Get_Extents.

   procedure Get_Pixel_Extents
     (Layout       : access Pango_Layout_Record;
      Ink_Rect     : out Gdk.Rectangle.Gdk_Rectangle;
      Logical_Rect : out Gdk.Rectangle.Gdk_Rectangle);
   --  Same as Get_Extents, but the returned values are in pixels (or device
   --  units when not drawing on the screen).

   procedure Get_Pixel_Size
     (Layout : access Pango_Layout_Record;
      Width  : out Glib.Gint;
      Height : out Glib.Gint);
   --  Same as Get_Size, but the returned values are in pixels.

   procedure XY_To_Index
     (Layout           : access Pango_Layout_Record;
      X_Pango, Y_Pango : Glib.Gint;
      Byte_Index       : out Integer;
      Trailing         : out Integer;
      Exact            : out Boolean);
   --  Convert from X and Y positions within a layout to the byte index of the
   --  character at that logical position.
   --  X and Y are given in pango units, not pixels.
   --  If the position is not inside the layout, the closest position is
   --  chosen, and Exact is set to False.
   --  Trailing is the position in the grapheme where the user clicked. It will
   --  either be 0 (left side) or the number of characters in the grapheme. In
   --  some character sets, a given character can be represented by multiple
   --  signs on the screen, which is what Trailing relates to.

   ---------------------------
   -- Manipulating the text --
   ---------------------------
   --  When initially created with Gtk.Widget.Create_Pango_Layout, the layout
   --  contains some text. Of course, this text may also be changed later in
   --  the life of the layout.

   procedure Set_Text (Layout : access Pango_Layout_Record; Text : String);
   --  Change the text that the layout displays
   --  Text must be a valid UTF8 string. See Glib.Convert for useful conversion
   --  functions.

   function Get_Text (Layout : access Pango_Layout_Record) return String;
   --  Return the text currently displayed in the layout.
   --  It is more efficient to use the iterators on the layout than get text if
   --  you do not need Ada-specific subprograms to act on the text.

   function Get_Text (Layout : access Pango_Layout_Record)
      return Gtkada.Types.Chars_Ptr;
   --  Same a Get_Text, but return directly the C string, which is more
   --  efficient. The returned value should not be freed or modified.

   function Get_Line_Count (Layout : access Pango_Layout_Record)
      return Glib.Gint;
   --  Return the number of lines in Layout

   procedure Set_Markup
     (Layout : access Pango_Layout_Record;
      Markup : Glib.UTF8_String);
   --  Change the text that layout displays.
   --  Markup must be a valid UTF8 String, and might contain markups as
   --  defined in the pango markup language.

   ------------------------
   -- Layouting the text --
   ------------------------

   procedure Set_Justify
     (Layout : access Pango_Layout_Record; Justify : Boolean);
   --  Set whether or not each complete line should be stretched to fill the
   --  entire width of the layout. This stretching is typically done by adding
   --  whitespace, but for some scripts (such as Arabic), the justification is
   --  done by extending the characters.

   function Get_Justify (Layout : access Pango_Layout_Record) return Boolean;
   --  Return True if each complete line should be stretched to fill the entire
   --  width of the layout.

   procedure Set_Alignment
     (Layout    : access Pango_Layout_Record'Class;
      Alignment : Pango_Alignment);
   --  Set the alignment for the layout (how partial lines are positioned
   --  within the horizontal space available).

   function Get_Alignment (Layout : access Pango_Layout_Record)
     return Pango_Alignment;
   --  Return the alignment for the layout.

   procedure Set_Width
     (Layout : access Pango_Layout_Record; Width : Glib.Gint);
   --  Set the width to which the lines of Layout should be wrapped. No
   --  wrapping will be performed if Width is -1.
   --  Width is given in pango units.

   function Get_Width (Layout : access Pango_Layout_Record) return Glib.Gint;
   --  Return the wrapping width of Layout

   procedure Set_Wrap
     (Layout : access Pango_Layout_Record; Mode : Pango_Wrap_Mode);
   --  Sets the wrap style; the wrap style only has an effect if a width is set
   --  on the layout with pango_layout_set_width(). To turn off wrapping, set
   --  the width to -1.

   function Get_Wrap (Layout : access Pango_Layout_Record)
      return Pango_Wrap_Mode;
   --  Return the current wrap style

   procedure Set_Tabs
     (Layout : access Pango_Layout_Record;
      Tabs   : Pango.Tabs.Pango_Tab_Array);
   --  Sets the tabs to use for Layout, overriding the default tabs (by
   --  default, tabs are every 8 spaces). If Tabs is Null_Tab_Array, the
   --  default tabs are reinstated. tabs is copied into the layout; you must
   --  free your copy of Tabs yourself.

   function Get_Tabs
     (Layout : access Pango_Layout_Record) return Pango.Tabs.Pango_Tab_Array;
   --  Get the current tab array used by Layout. If no tab array
   --  has been set, then the default tabs are in use and Null_Tab_Array is
   --  returned.
   --  Default tabs are every 8 spaces. The return value should be freed with
   --  Pango.Tabs.Free.

   ----------------
   -- Attributes --
   ----------------

   procedure Set_Attributes
     (Layout : access Pango_Layout_Record;
      Attributes : Pango.Attributes.Pango_Attr_List);
   --  Set the text attributes for a layout object.
   --  Passing null removes the current list of attributes

   function Get_Attributes (Layout : access Pango_Layout_Record)
      return Pango.Attributes.Pango_Attr_List;
   --  Get the text attributes from a layout object

private
   type Pango_Layout_Record is new Glib.Object.GObject_Record with null record;

   pragma Import (C, Line_Ref, "pango_layout_line_ref");
   pragma Import (C, Line_Unref, "pango_layout_line_unref");
   pragma Import (C, Line_Index_To_X, "pango_layout_line_index_to_x");
end Pango.Layout;

--  missing:
--  pango_layout_get_context
--  pango_layout_copy
--  pango_layout_set_attributes
--  pango_layout_get_attributes
--  pango_layout_set_markup_with_accel
--  pango_layout_set_indent
--  pango_layout_get_indent
--  pango_layout_set_spacing
--  pango_layout_get_spacing
--  pango_layout_set_single_paragraph_mode
--  pango_layout_get_single_paragraph_mode
--  pango_layout_get_log_attrs
--  pango_layout_index_to_pos
--  pango_layout_get_cursor_pos
--  pango_layout_move_cursor_visually
--  pango_layout_get_lines
--  pango_layout_line_index_to_x
--  pango_layout_line_get_x_ranges
--  pango_layout_line_get_extents
--  pango_layout_line_get_pixel_extents
--  pango_layout_get_iter
--  pango_layout_iter_free
--  pango_layout_iter_get_index
--  pango_layout_iter_get_run
--  pango_layout_iter_get_line
--  pango_layout_iter_at_last_line
--  pango_layout_iter_next_char
--  pango_layout_iter_next_cluster
--  pango_layout_iter_next_run
--  pango_layout_iter_next_line
--  pango_layout_iter_get_char_extents
--  pango_layout_iter_get_cluster_extents
--  pango_layout_iter_get_run_extents
--  pango_layout_iter_get_line_extents
--  pango_layout_iter_get_line_yrange
--  pango_layout_iter_get_layout_extents
--  pango_layout_iter_get_baseline