-----------------------------------------------------------------------
-- 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. --
-- --
-- --
-- --
-- --
-- --
-- --
-- --
-----------------------------------------------------------------------
--
--
-- 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.
--
--
-- Pango, font handling
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