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. -- -- -- -- -- -- -- -- -- -- -- --
  22. ----------------------------------------------------------------------- 
  23.  
  24. --  <description> 
  25. -- 
  26. --  This package provides a high-level object that is capable of arranging text 
  27. --  in a visually correct manner. It supports international character sets, 
  28. --  although all strings should be Utf8, supports left-to-right and 
  29. --  right-to-left writing systems, is capable of handling multi-line texts, and 
  30. --  properly aligns tab characters in the text. 
  31. -- 
  32. --  This is the base type that is used in the standard gtk+ widget for all the 
  33. --  widgets that display some text on the screen. 
  34. -- 
  35. --  Since it works directly with Pango.Font.Pango_Font_Description fonts, it is 
  36. --  also much better at handling resizing of text, wrapping,... than direct 
  37. --  calls to Gdk.Drawable.Draw_Text. 
  38. -- 
  39. --  The idea is that this widget is used to compute the layout of the 
  40. --  characters (ie their screen position). It doesn't do any rendering, 
  41. --  however, and should be used in conjonction with Gdk.Drawable.Draw_Layout to 
  42. --  actually display something on the screen. 
  43. -- 
  44. --  This widget is independent from any specific drawing systems, and might for 
  45. --  instance be used to create postscript documents, for direct access to the 
  46. --  win32 API,... 
  47. -- 
  48. --  This widget represents one of the fundamental additions to gtk+ 2.0 over 
  49. --  what previously existed in the gtk+ 1.x series. It obsoletes the package 
  50. --  Gdk.Font, which should only be used for legacy applications. 
  51. -- 
  52. --  </description> 
  53. --  <group>Pango, font handling</group> 
  54.  
  55. with Glib; 
  56. with Pango.Attributes; 
  57. with Pango.Context; 
  58. with Pango.Font; 
  59. with Pango.Tabs; 
  60. with Glib.Object; 
  61. with Gdk.Rectangle; 
  62. with Gtkada.Types; 
  63.  
  64. package Pango.Layout is 
  65.  
  66.    type Pango_Layout_Record is new Glib.Object.GObject_Record with private; 
  67.    type Pango_Layout is access all Pango_Layout_Record'Class; 
  68.    --  A widget that allows you to easily display text, including handling of 
  69.    --  internationalization, right-to-left writing,... 
  70.    --  See the function Gtk.Widget.Create_Pango_Layout for more information on 
  71.    --  how to create layouts 
  72.    --  Use Glib.Object.Unref to destroy a Pango_Layout 
  73.    --  See Gdk.Drawable.Draw_Layout for how to actually display the layout on 
  74.    --  the screen. 
  75.  
  76.    type Pango_Alignment is 
  77.      (Pango_Align_Left, 
  78.       Pango_Align_Center, 
  79.       Pango_Align_Right); 
  80.    pragma Convention (C, Pango_Alignment); 
  81.    --  The alignment for each line of the layout 
  82.  
  83.    type Pango_Wrap_Mode is 
  84.      (Pango_Wrap_Word, 
  85.       Pango_Wrap_Char); 
  86.    pragma Convention (C, Pango_Wrap_Mode); 
  87.    --  The wrap mode for a layout 
  88.  
  89.    type Pango_Ellipsize_Mode is 
  90.      (Ellipsize_None, 
  91.       Ellipsize_Start, 
  92.       Ellipsize_Middle, 
  93.       Ellipsize_End); 
  94.    --  This type describes what sort of (if any) ellipsization should be 
  95.    --  applied to a line of text. In the ellipsization process characters are 
  96.    --  removed from the text in order to make it fit to a given width and 
  97.    --  replaced with an ellipsis. 
  98.  
  99.  
  100.    ----------------------- 
  101.    -- Creating a layout -- 
  102.    ----------------------- 
  103.    --  A layout can be created in two ways: either from a widget 
  104.    --  (Gtk.Widget.Create_Pango_Layout), from which it will inherit the font 
  105.    --  and various other attributes, or directly from a Pango_Context. 
  106.  
  107.    procedure Gdk_New 
  108.      (Layout : out Pango_Layout; 
  109.       Context : access Pango.Context.Pango_Context_Record'Class); 
  110.    --  Create a new layout, based on context. 
  111.  
  112.    -------------- 
  113.    -- Contexts -- 
  114.    -------------- 
  115.  
  116.    function Get_Context (Layout : access Pango_Layout_Record) 
  117.       return Pango.Context.Pango_Context; 
  118.    --  Return the context of the layout. The returned value is the internal 
  119.    --  context itself, so you must Glib.Object.Ref it if you need to keep a 
  120.    --  reference. You shouldn't Unref it. 
  121.  
  122.    procedure Set_Font_Description 
  123.      (Layout : access Pango_Layout_Record; 
  124.       Font   : Pango.Font.Pango_Font_Description); 
  125.    --  Change the font used in the layout. 
  126.    --  If not font description is set for the layout, the font description from 
  127.    --  the layout's context is used. 
  128.  
  129.    procedure Context_Changed (Layout : access Pango_Layout_Record); 
  130.    --  Forces recomputation of any state in Layout that might depend 
  131.    --  on the layout's context. This function should be called if you make 
  132.    --  changes to the context subsequent to creating the layout. 
  133.  
  134.    ----------- 
  135.    -- Lines -- 
  136.    ----------- 
  137.  
  138.    type Pango_Layout_Line is new Glib.C_Proxy; 
  139.  
  140.    function Get_Line 
  141.      (Layout : access Pango_Layout_Record; 
  142.       Line   : Natural) return Pango_Layout_Line; 
  143.    --  Retrieve a particular line from Layout. 
  144.    --  Line must be between 0 and Get_Line_Count (Layout) - 1. null is returned 
  145.    --  if the index is out of range. 
  146.    --  The layout line can be Ref'ed and retained, but will become invalid if 
  147.    --  changes are made to Layout. 
  148.  
  149.    procedure Line_Ref (Line : Pango_Layout_Line); 
  150.    --  Increase the reference count of Line by 1. 
  151.  
  152.    procedure Line_Unref (Line : Pango_Layout_Line); 
  153.    --  Decrease the reference count of Line by 1. If the result is 0, the line 
  154.    --  and all associated memory will be destroyed. 
  155.  
  156.    function Line_Index_To_X 
  157.      (Line     : Pango_Layout_Line; 
  158.       Index    : Integer; 
  159.       Trailing : Integer) return Glib.Gint; 
  160.    --  Convert an index within a line to an X position. 
  161.    --  Index is the byte offset of a graphem within the layout. 
  162.    --  Trailing is an integer indicating the edge of the grapheme to retrieve 
  163.    --  the position of. If 0, the trailing edge of the grapheme, otherwise, the 
  164.    --  leading of the grapheme. 
  165.    --  The returned value is in pango units. 
  166.  
  167.    ---------------------- 
  168.    -- Getting the size -- 
  169.    ---------------------- 
  170.    --  Pango internally stores its sizes in pango units, which are a number of 
  171.    --  pixels (device units, when not drawing on the screen) multiplied by 
  172.    --  Pango_Scale. There are generally equivalent subprograms to get the sizes 
  173.    --  directly in pixels. 
  174.  
  175.    procedure Get_Extents 
  176.      (Layout       : access Pango_Layout_Record; 
  177.       Ink_Rect     : out Gdk.Rectangle.Gdk_Rectangle; 
  178.       Logical_Rect : out Gdk.Rectangle.Gdk_Rectangle); 
  179.    --  Compute the logical and ink extents of Layout. Logical extents 
  180.    --  are usually what you want for positioning things. The extents 
  181.    --  are given in pango units; layout coordinates begin at the 
  182.    --  top left corner of the layout. 
  183.    --  Logical_Rect is the overall size of the layout, ie it includes Ink_Rect 
  184.    --  (where the text is actually drawn) and a small border around it. 
  185.  
  186.    procedure Get_Size 
  187.      (Layout : access Pango_Layout_Record; 
  188.       Width  : out Glib.Gint; 
  189.       Height : out Glib.Gint); 
  190.    --  Return the logical size, in pango units, of the layout. This is a 
  191.    --  convenience function around Get_Extents. 
  192.  
  193.    procedure Get_Pixel_Extents 
  194.      (Layout       : access Pango_Layout_Record; 
  195.       Ink_Rect     : out Gdk.Rectangle.Gdk_Rectangle; 
  196.       Logical_Rect : out Gdk.Rectangle.Gdk_Rectangle); 
  197.    --  Same as Get_Extents, but the returned values are in pixels (or device 
  198.    --  units when not drawing on the screen). 
  199.  
  200.    procedure Get_Pixel_Size 
  201.      (Layout : access Pango_Layout_Record; 
  202.       Width  : out Glib.Gint; 
  203.       Height : out Glib.Gint); 
  204.    --  Same as Get_Size, but the returned values are in pixels. 
  205.  
  206.    procedure XY_To_Index 
  207.      (Layout           : access Pango_Layout_Record; 
  208.       X_Pango, Y_Pango : Glib.Gint; 
  209.       Byte_Index       : out Integer; 
  210.       Trailing         : out Integer; 
  211.       Exact            : out Boolean); 
  212.    --  Convert from X and Y positions within a layout to the byte index of the 
  213.    --  character at that logical position. 
  214.    --  X and Y are given in pango units, not pixels. 
  215.    --  If the position is not inside the layout, the closest position is 
  216.    --  chosen, and Exact is set to False. 
  217.    --  Trailing is the position in the grapheme where the user clicked. It will 
  218.    --  either be 0 (left side) or the number of characters in the grapheme. In 
  219.    --  some character sets, a given character can be represented by multiple 
  220.    --  signs on the screen, which is what Trailing relates to. 
  221.  
  222.    --------------------------- 
  223.    -- Manipulating the text -- 
  224.    --------------------------- 
  225.    --  When initially created with Gtk.Widget.Create_Pango_Layout, the layout 
  226.    --  contains some text. Of course, this text may also be changed later in 
  227.    --  the life of the layout. 
  228.  
  229.    procedure Set_Text (Layout : access Pango_Layout_Record; Text : String); 
  230.    --  Change the text that the layout displays 
  231.    --  Text must be a valid UTF8 string. See Glib.Convert for useful conversion 
  232.    --  functions. 
  233.  
  234.    function Get_Text (Layout : access Pango_Layout_Record) return String; 
  235.    --  Return the text currently displayed in the layout. 
  236.    --  It is more efficient to use the iterators on the layout than get text if 
  237.    --  you do not need Ada-specific subprograms to act on the text. 
  238.  
  239.    function Get_Text (Layout : access Pango_Layout_Record) 
  240.       return Gtkada.Types.Chars_Ptr; 
  241.    --  Same a Get_Text, but return directly the C string, which is more 
  242.    --  efficient. The returned value should not be freed or modified. 
  243.  
  244.    function Get_Line_Count (Layout : access Pango_Layout_Record) 
  245.       return Glib.Gint; 
  246.    --  Return the number of lines in Layout 
  247.  
  248.    procedure Set_Markup 
  249.      (Layout : access Pango_Layout_Record; 
  250.       Markup : Glib.UTF8_String); 
  251.    --  Change the text that layout displays. 
  252.    --  Markup must be a valid UTF8 String, and might contain markups as 
  253.    --  defined in the pango markup language. 
  254.  
  255.    ------------------------ 
  256.    -- Layouting the text -- 
  257.    ------------------------ 
  258.  
  259.    procedure Set_Justify 
  260.      (Layout : access Pango_Layout_Record; Justify : Boolean); 
  261.    --  Set whether or not each complete line should be stretched to fill the 
  262.    --  entire width of the layout. This stretching is typically done by adding 
  263.    --  whitespace, but for some scripts (such as Arabic), the justification is 
  264.    --  done by extending the characters. 
  265.  
  266.    function Get_Justify (Layout : access Pango_Layout_Record) return Boolean; 
  267.    --  Return True if each complete line should be stretched to fill the entire 
  268.    --  width of the layout. 
  269.  
  270.    procedure Set_Alignment 
  271.      (Layout    : access Pango_Layout_Record'Class; 
  272.       Alignment : Pango_Alignment); 
  273.    --  Set the alignment for the layout (how partial lines are positioned 
  274.    --  within the horizontal space available). 
  275.  
  276.    function Get_Alignment (Layout : access Pango_Layout_Record) 
  277.      return Pango_Alignment; 
  278.    --  Return the alignment for the layout. 
  279.  
  280.    procedure Set_Width 
  281.      (Layout : access Pango_Layout_Record; Width : Glib.Gint); 
  282.    --  Set the width to which the lines of Layout should be wrapped. No 
  283.    --  wrapping will be performed if Width is -1. 
  284.    --  Width is given in pango units. 
  285.  
  286.    function Get_Width (Layout : access Pango_Layout_Record) return Glib.Gint; 
  287.    --  Return the wrapping width of Layout 
  288.  
  289.    procedure Set_Wrap 
  290.      (Layout : access Pango_Layout_Record; Mode : Pango_Wrap_Mode); 
  291.    --  Sets the wrap style; the wrap style only has an effect if a width is set 
  292.    --  on the layout with pango_layout_set_width(). To turn off wrapping, set 
  293.    --  the width to -1. 
  294.  
  295.    function Get_Wrap (Layout : access Pango_Layout_Record) 
  296.       return Pango_Wrap_Mode; 
  297.    --  Return the current wrap style 
  298.  
  299.    procedure Set_Tabs 
  300.      (Layout : access Pango_Layout_Record; 
  301.       Tabs   : Pango.Tabs.Pango_Tab_Array); 
  302.    --  Sets the tabs to use for Layout, overriding the default tabs (by 
  303.    --  default, tabs are every 8 spaces). If Tabs is Null_Tab_Array, the 
  304.    --  default tabs are reinstated. tabs is copied into the layout; you must 
  305.    --  free your copy of Tabs yourself. 
  306.  
  307.    function Get_Tabs 
  308.      (Layout : access Pango_Layout_Record) return Pango.Tabs.Pango_Tab_Array; 
  309.    --  Get the current tab array used by Layout. If no tab array 
  310.    --  has been set, then the default tabs are in use and Null_Tab_Array is 
  311.    --  returned. 
  312.    --  Default tabs are every 8 spaces. The return value should be freed with 
  313.    --  Pango.Tabs.Free. 
  314.  
  315.    ---------------- 
  316.    -- Attributes -- 
  317.    ---------------- 
  318.  
  319.    procedure Set_Attributes 
  320.      (Layout : access Pango_Layout_Record; 
  321.       Attributes : Pango.Attributes.Pango_Attr_List); 
  322.    --  Set the text attributes for a layout object. 
  323.    --  Passing null removes the current list of attributes 
  324.  
  325.    function Get_Attributes (Layout : access Pango_Layout_Record) 
  326.       return Pango.Attributes.Pango_Attr_List; 
  327.    --  Get the text attributes from a layout object 
  328.  
  329. private 
  330.    type Pango_Layout_Record is new Glib.Object.GObject_Record with null record; 
  331.  
  332.    pragma Import (C, Line_Ref, "pango_layout_line_ref"); 
  333.    pragma Import (C, Line_Unref, "pango_layout_line_unref"); 
  334.    pragma Import (C, Line_Index_To_X, "pango_layout_line_index_to_x"); 
  335. end Pango.Layout; 
  336.  
  337. --  missing: 
  338. --  pango_layout_get_context 
  339. --  pango_layout_copy 
  340. --  pango_layout_set_attributes 
  341. --  pango_layout_get_attributes 
  342. --  pango_layout_set_markup_with_accel 
  343. --  pango_layout_set_indent 
  344. --  pango_layout_get_indent 
  345. --  pango_layout_set_spacing 
  346. --  pango_layout_get_spacing 
  347. --  pango_layout_set_single_paragraph_mode 
  348. --  pango_layout_get_single_paragraph_mode 
  349. --  pango_layout_get_log_attrs 
  350. --  pango_layout_index_to_pos 
  351. --  pango_layout_get_cursor_pos 
  352. --  pango_layout_move_cursor_visually 
  353. --  pango_layout_get_lines 
  354. --  pango_layout_line_index_to_x 
  355. --  pango_layout_line_get_x_ranges 
  356. --  pango_layout_line_get_extents 
  357. --  pango_layout_line_get_pixel_extents 
  358. --  pango_layout_get_iter 
  359. --  pango_layout_iter_free 
  360. --  pango_layout_iter_get_index 
  361. --  pango_layout_iter_get_run 
  362. --  pango_layout_iter_get_line 
  363. --  pango_layout_iter_at_last_line 
  364. --  pango_layout_iter_next_char 
  365. --  pango_layout_iter_next_cluster 
  366. --  pango_layout_iter_next_run 
  367. --  pango_layout_iter_next_line 
  368. --  pango_layout_iter_get_char_extents 
  369. --  pango_layout_iter_get_cluster_extents 
  370. --  pango_layout_iter_get_run_extents 
  371. --  pango_layout_iter_get_line_extents 
  372. --  pango_layout_iter_get_line_yrange 
  373. --  pango_layout_iter_get_layout_extents 
  374. --  pango_layout_iter_get_baseline