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. ----------------------------------------------------------------------- 
  28.  
  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> 
  59.  
  60. with Glib; 
  61. with Pango.Attributes; 
  62. with Pango.Context; 
  63. with Pango.Font; 
  64. with Pango.Tabs; 
  65. with Glib.Object; 
  66. with Gdk.Rectangle; 
  67. with Gtkada.Types; 
  68.  
  69. package Pango.Layout is 
  70.  
  71.    type Pango_Layout_Record is new Glib.Object.GObject_Record with private; 
  72.    type Pango_Layout is access all Pango_Layout_Record'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. 
  80.  
  81.    type Pango_Alignment is 
  82.      (Pango_Align_Left, 
  83.       Pango_Align_Center, 
  84.       Pango_Align_Right); 
  85.    pragma Convention (C, Pango_Alignment); 
  86.    --  The alignment for each line of the layout 
  87.  
  88.    type Pango_Wrap_Mode is 
  89.      (Pango_Wrap_Word, 
  90.       Pango_Wrap_Char); 
  91.    pragma Convention (C, Pango_Wrap_Mode); 
  92.    --  The wrap mode for a layout 
  93.  
  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. 
  103.  
  104.  
  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. 
  111.  
  112.    procedure Gdk_New 
  113.      (Layout : out Pango_Layout; 
  114.       Context : access Pango.Context.Pango_Context_Record'Class); 
  115.    --  Create a new layout, based on context. 
  116.  
  117.    -------------- 
  118.    -- Contexts -- 
  119.    -------------- 
  120.  
  121.    function Get_Context (Layout : access Pango_Layout_Record) 
  122.       return Pango.Context.Pango_Context; 
  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. 
  126.  
  127.    procedure Set_Font_Description 
  128.      (Layout : access Pango_Layout_Record; 
  129.       Font   : Pango.Font.Pango_Font_Description); 
  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. 
  133.  
  134.    procedure Context_Changed (Layout : access Pango_Layout_Record); 
  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. 
  138.  
  139.    ----------- 
  140.    -- Lines -- 
  141.    ----------- 
  142.  
  143.    type Pango_Layout_Line is new Glib.C_Proxy; 
  144.  
  145.    function Get_Line 
  146.      (Layout : access Pango_Layout_Record; 
  147.       Line   : Natural) return Pango_Layout_Line; 
  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. 
  153.  
  154.    procedure Line_Ref (Line : Pango_Layout_Line); 
  155.    --  Increase the reference count of Line by 1. 
  156.  
  157.    procedure Line_Unref (Line : Pango_Layout_Line); 
  158.    --  Decrease the reference count of Line by 1. If the result is 0, the line 
  159.    --  and all associated memory will be destroyed. 
  160.  
  161.    function Line_Index_To_X 
  162.      (Line     : Pango_Layout_Line; 
  163.       Index    : Integer; 
  164.       Trailing : Integer) return Glib.Gint; 
  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. 
  171.  
  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. 
  179.  
  180.    procedure Get_Extents 
  181.      (Layout       : access Pango_Layout_Record; 
  182.       Ink_Rect     : out Gdk.Rectangle.Gdk_Rectangle; 
  183.       Logical_Rect : out Gdk.Rectangle.Gdk_Rectangle); 
  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. 
  190.  
  191.    procedure Get_Size 
  192.      (Layout : access Pango_Layout_Record; 
  193.       Width  : out Glib.Gint; 
  194.       Height : out Glib.Gint); 
  195.    --  Return the logical size, in pango units, of the layout. This is a 
  196.    --  convenience function around Get_Extents. 
  197.  
  198.    procedure Get_Pixel_Extents 
  199.      (Layout       : access Pango_Layout_Record; 
  200.       Ink_Rect     : out Gdk.Rectangle.Gdk_Rectangle; 
  201.       Logical_Rect : out Gdk.Rectangle.Gdk_Rectangle); 
  202.    --  Same as Get_Extents, but the returned values are in pixels (or device 
  203.    --  units when not drawing on the screen). 
  204.  
  205.    procedure Get_Pixel_Size 
  206.      (Layout : access Pango_Layout_Record; 
  207.       Width  : out Glib.Gint; 
  208.       Height : out Glib.Gint); 
  209.    --  Same as Get_Size, but the returned values are in pixels. 
  210.  
  211.    procedure XY_To_Index 
  212.      (Layout           : access Pango_Layout_Record; 
  213.       X_Pango, Y_Pango : Glib.Gint; 
  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. 
  226.  
  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. 
  233.  
  234.    procedure Set_Text (Layout : access Pango_Layout_Record; 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. 
  238.  
  239.    function Get_Text (Layout : access Pango_Layout_Record) 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. 
  243.  
  244.    function Get_Text (Layout : access Pango_Layout_Record) 
  245.       return Gtkada.Types.Chars_Ptr; 
  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. 
  248.  
  249.    function Get_Line_Count (Layout : access Pango_Layout_Record) 
  250.       return Glib.Gint; 
  251.    --  Return the number of lines in Layout 
  252.  
  253.    procedure Set_Markup 
  254.      (Layout : access Pango_Layout_Record; 
  255.       Markup : Glib.UTF8_String); 
  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. 
  259.  
  260.    ------------------------ 
  261.    -- Layouting the text -- 
  262.    ------------------------ 
  263.  
  264.    procedure Set_Justify 
  265.      (Layout : access Pango_Layout_Record; 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. 
  270.  
  271.    function Get_Justify (Layout : access Pango_Layout_Record) return Boolean; 
  272.    --  Return True if each complete line should be stretched to fill the entire 
  273.    --  width of the layout. 
  274.  
  275.    procedure Set_Alignment 
  276.      (Layout    : access Pango_Layout_Record'Class; 
  277.       Alignment : Pango_Alignment); 
  278.    --  Set the alignment for the layout (how partial lines are positioned 
  279.    --  within the horizontal space available). 
  280.  
  281.    function Get_Alignment (Layout : access Pango_Layout_Record) 
  282.      return Pango_Alignment; 
  283.    --  Return the alignment for the layout. 
  284.  
  285.    procedure Set_Width 
  286.      (Layout : access Pango_Layout_Record; Width : Glib.Gint); 
  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. 
  290.  
  291.    function Get_Width (Layout : access Pango_Layout_Record) return Glib.Gint; 
  292.    --  Return the wrapping width of Layout 
  293.  
  294.    procedure Set_Wrap 
  295.      (Layout : access Pango_Layout_Record; Mode : Pango_Wrap_Mode); 
  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. 
  299.  
  300.    function Get_Wrap (Layout : access Pango_Layout_Record) 
  301.       return Pango_Wrap_Mode; 
  302.    --  Return the current wrap style 
  303.  
  304.    procedure Set_Tabs 
  305.      (Layout : access Pango_Layout_Record; 
  306.       Tabs   : Pango.Tabs.Pango_Tab_Array); 
  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. 
  311.  
  312.    function Get_Tabs 
  313.      (Layout : access Pango_Layout_Record) return Pango.Tabs.Pango_Tab_Array; 
  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. 
  319.  
  320.    ---------------- 
  321.    -- Attributes -- 
  322.    ---------------- 
  323.  
  324.    procedure Set_Attributes 
  325.      (Layout : access Pango_Layout_Record; 
  326.       Attributes : Pango.Attributes.Pango_Attr_List); 
  327.    --  Set the text attributes for a layout object. 
  328.    --  Passing null removes the current list of attributes 
  329.  
  330.    function Get_Attributes (Layout : access Pango_Layout_Record) 
  331.       return Pango.Attributes.Pango_Attr_List; 
  332.    --  Get the text attributes from a layout object 
  333.  
  334. private 
  335.    type Pango_Layout_Record is new Glib.Object.GObject_Record with null record; 
  336.  
  337.    pragma Import (C, Line_Ref, "pango_layout_line_ref"); 
  338.    pragma Import (C, Line_Unref, "pango_layout_line_unref"); 
  339.    pragma Import (C, Line_Index_To_X, "pango_layout_line_index_to_x"); 
  340. end Pango.Layout; 
  341.  
  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