1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. pragma Ada_2005; 
  25.  
  26. pragma Warnings (Off, "*is already use-visible*"); 
  27. with Glib;                    use Glib; 
  28. with Glib.Generic_Properties; use Glib.Generic_Properties; 
  29. with Glib.Object;             use Glib.Object; 
  30. with Pango.Enums;             use Pango.Enums; 
  31. with Pango.Font_Metrics;      use Pango.Font_Metrics; 
  32. with Pango.Language;          use Pango.Language; 
  33.  
  34. package Pango.Font is 
  35.  
  36.    type Pango_Font_Record is new GObject_Record with null record; 
  37.    type Pango_Font is access all Pango_Font_Record'Class; 
  38.  
  39.    type Pango_Font_Description is new Glib.C_Proxy; 
  40.  
  41.    ------------------ 
  42.    -- Constructors -- 
  43.    ------------------ 
  44.  
  45.    function Font_Get_Type return Glib.GType; 
  46.    pragma Import (C, Font_Get_Type, "pango_font_get_type"); 
  47.  
  48.    procedure Gdk_New (Self : out Pango_Font_Description); 
  49.    --  Creates a new font description structure with all fields unset. 
  50.  
  51.    function Pango_Font_Description_New return Pango_Font_Description; 
  52.    --  Creates a new font description structure with all fields unset. 
  53.  
  54.    function Get_Type return Glib.GType; 
  55.    pragma Import (C, Get_Type, "pango_font_description_get_type"); 
  56.  
  57.    ------------- 
  58.    -- Methods -- 
  59.    ------------- 
  60.  
  61.    function Describe 
  62.       (Font : not null access Pango_Font_Record'Class) 
  63.        return Pango_Font_Description; 
  64.    --  Returns a description of the font, with font size set in points. Use 
  65.    --  Pango.Font.Describe_With_Absolute_Size if you want the font size in 
  66.    --  device units. 
  67.  
  68.    function Describe_With_Absolute_Size 
  69.       (Font : not null access Pango_Font_Record'Class) 
  70.        return Pango_Font_Description; 
  71.    --  Returns a description of the font, with absolute font size set (in 
  72.    --  device units). Use Pango.Font.Describe if you want the font size in 
  73.    --  points. 
  74.    --  Since: gtk+ 1.14 
  75.  
  76.    procedure Get_Glyph_Extents 
  77.       (Font         : not null access Pango_Font_Record; 
  78.        Glyph        : Pango_Glyph; 
  79.        Ink_Rect     : out Pango_Rectangle; 
  80.        Logical_Rect : out Pango_Rectangle); 
  81.    --  Gets the logical and ink extents of a glyph within a font. The 
  82.    --  coordinate system for each rectangle has its origin at the base line and 
  83.    --  horizontal origin of the character with increasing coordinates extending 
  84.    --  to the right and down. The macros PANGO_ASCENT, PANGO_DESCENT, 
  85.    --  PANGO_LBEARING, and PANGO_RBEARING can be used to convert from the 
  86.    --  extents rectangle to more traditional font metrics. The units of the 
  87.    --  rectangles are in 1/PANGO_SCALE of a device unit. 
  88.    --  If Font is null, this function gracefully sets some sane values in the 
  89.    --  output variables and returns. 
  90.    --  "glyph": the glyph index 
  91.    --  "ink_rect": rectangle used to store the extents of the glyph as drawn 
  92.    --  or null to indicate that the result is not needed. 
  93.    --  "logical_rect": rectangle used to store the logical extents of the 
  94.    --  glyph or null to indicate that the result is not needed. 
  95.  
  96.    function Get_Metrics 
  97.       (Font     : not null access Pango_Font_Record; 
  98.        Language : Pango.Language.Pango_Language := Pango.Language.Null_Pango_Language) 
  99.        return Pango.Font_Metrics.Pango_Font_Metrics; 
  100.    --  Gets overall metric information for a font. Since the metrics may be 
  101.    --  substantially different for different scripts, a language tag can be 
  102.    --  provided to indicate that the metrics should be retrieved that 
  103.    --  correspond to the script(s) used by that language. 
  104.    --  If Font is null, this function gracefully sets some sane values in the 
  105.    --  output variables and returns. 
  106.    --  "language": language tag used to determine which script to get the 
  107.    --  metrics for, or null to indicate to get the metrics for the entire font. 
  108.  
  109.    function Better_Match 
  110.       (Self      : Pango_Font_Description; 
  111.        Old_Match : Pango_Font_Description; 
  112.        New_Match : Pango_Font_Description) return Boolean; 
  113.    --  Determines if the style attributes of New_Match are a closer match for 
  114.    --  Desc than those of Old_Match are, or if Old_Match is null, determines if 
  115.    --  New_Match is a match at all. Approximate matching is done for weight and 
  116.    --  style; other style attributes must match exactly. Style attributes are 
  117.    --  all attributes other than family and size-related attributes. 
  118.    --  Approximate matching for style considers PANGO_STYLE_OBLIQUE and 
  119.    --  PANGO_STYLE_ITALIC as matches, but not as good a match as when the 
  120.    --  styles are equal. 
  121.    --  Note that Old_Match must match Desc. 
  122.    --  "old_match": a Pango.Font.Pango_Font_Description, or null 
  123.    --  "new_match": a Pango.Font.Pango_Font_Description 
  124.  
  125.    function Copy 
  126.       (Self : Pango_Font_Description) return Pango_Font_Description; 
  127.    pragma Import (C, Copy, "pango_font_description_copy"); 
  128.    --  Make a copy of a Pango.Font.Pango_Font_Description. 
  129.  
  130.    function Copy_Static 
  131.       (Self : Pango_Font_Description) return Pango_Font_Description; 
  132.    pragma Import (C, Copy_Static, "pango_font_description_copy_static"); 
  133.    --  Like Pango.Font.Copy, but only a shallow copy is made of the family 
  134.    --  name and other allocated fields. The result can only be used until Desc 
  135.    --  is modified or freed. This is meant to be used when the copy is only 
  136.    --  needed temporarily. 
  137.  
  138.    function Equal 
  139.       (Self  : Pango_Font_Description; 
  140.        Desc2 : Pango_Font_Description) return Boolean; 
  141.    --  Compares two font descriptions for equality. Two font descriptions are 
  142.    --  considered equal if the fonts they describe are provably identical. This 
  143.    --  means that their masks do not have to match, as long as other fields are 
  144.    --  all the same. (Two font descriptions may result in identical fonts being 
  145.    --  loaded, but still compare False.) 
  146.    --  "desc2": another Pango.Font.Pango_Font_Description 
  147.  
  148.    function Get_Family (Self : Pango_Font_Description) return UTF8_String; 
  149.    --  Gets the family name field of a font description. See 
  150.    --  Pango.Font.Set_Family. 
  151.  
  152.    procedure Set_Family 
  153.       (Self   : Pango_Font_Description; 
  154.        Family : UTF8_String); 
  155.    --  Sets the family name field of a font description. The family name 
  156.    --  represents a family of related font styles, and will resolve to a 
  157.    --  particular Pango.Font_Family.Pango_Font_Family. In some uses of 
  158.    --  Pango.Font.Pango_Font_Description, it is also possible to use a comma 
  159.    --  separated list of family names for this field. 
  160.    --  "family": a string representing the family name. 
  161.  
  162.    function Get_Gravity 
  163.       (Self : Pango_Font_Description) return Pango.Enums.Gravity; 
  164.    pragma Import (C, Get_Gravity, "pango_font_description_get_gravity"); 
  165.    --  Gets the gravity field of a font description. See 
  166.    --  Pango.Font.Set_Gravity. 
  167.    --  Since: gtk+ 1.16 
  168.  
  169.    procedure Set_Gravity 
  170.       (Self    : Pango_Font_Description; 
  171.        Gravity : Pango.Enums.Gravity); 
  172.    pragma Import (C, Set_Gravity, "pango_font_description_set_gravity"); 
  173.    --  Sets the gravity field of a font description. The gravity field 
  174.    --  specifies how the glyphs should be rotated. If Gravity is 
  175.    --  Pango.Enums.Pango_Gravity_Auto, this actually unsets the gravity mask on 
  176.    --  the font description. 
  177.    --  This function is seldom useful to the user. Gravity should normally be 
  178.    --  set on a Pango.Context.Pango_Context. 
  179.    --  Since: gtk+ 1.16 
  180.    --  "gravity": the gravity for the font description. 
  181.  
  182.    function Get_Set_Fields 
  183.       (Self : Pango_Font_Description) return Pango.Enums.Font_Mask; 
  184.    pragma Import (C, Get_Set_Fields, "pango_font_description_get_set_fields"); 
  185.    --  Determines which fields in a font description have been set. 
  186.  
  187.    function Get_Size (Self : Pango_Font_Description) return Gint; 
  188.    pragma Import (C, Get_Size, "pango_font_description_get_size"); 
  189.    --  Gets the size field of a font description. See Pango.Font.Set_Size. 
  190.  
  191.    procedure Set_Size (Self : Pango_Font_Description; Size : Gint); 
  192.    pragma Import (C, Set_Size, "pango_font_description_set_size"); 
  193.    --  Sets the size field of a font description in fractional points. This is 
  194.    --  mutually exclusive with Pango.Font.Set_Absolute_Size. 
  195.    --  "size": the size of the font in points, scaled by PANGO_SCALE. (That 
  196.    --  is, a Size value of 10 * PANGO_SCALE is a 10 point font. The conversion 
  197.    --  factor between points and device units depends on system configuration 
  198.    --  and the output device. For screen display, a logical DPI of 96 is 
  199.    --  common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 
  200.    --  13.3 pixel font. Use Pango.Font.Set_Absolute_Size if you need a 
  201.    --  particular size in device units. 
  202.  
  203.    function Get_Size_Is_Absolute 
  204.       (Self : Pango_Font_Description) return Boolean; 
  205.    --  Determines whether the size of the font is in points (not absolute) or 
  206.    --  device units (absolute). See Pango.Font.Set_Size and 
  207.    --  Pango.Font.Set_Absolute_Size. 
  208.    --  Since: gtk+ 1.8 
  209.  
  210.    function Get_Stretch 
  211.       (Self : Pango_Font_Description) return Pango.Enums.Stretch; 
  212.    pragma Import (C, Get_Stretch, "pango_font_description_get_stretch"); 
  213.    --  Gets the stretch field of a font description. See 
  214.    --  Pango.Font.Set_Stretch. 
  215.  
  216.    procedure Set_Stretch 
  217.       (Self    : Pango_Font_Description; 
  218.        Stretch : Pango.Enums.Stretch); 
  219.    pragma Import (C, Set_Stretch, "pango_font_description_set_stretch"); 
  220.    --  Sets the stretch field of a font description. The stretch field 
  221.    --  specifies how narrow or wide the font should be. 
  222.    --  "stretch": the stretch for the font description 
  223.  
  224.    function Get_Style 
  225.       (Self : Pango_Font_Description) return Pango.Enums.Style; 
  226.    pragma Import (C, Get_Style, "pango_font_description_get_style"); 
  227.    --  Gets the style field of a Pango.Font.Pango_Font_Description. See 
  228.    --  Pango.Font.Set_Style. 
  229.  
  230.    procedure Set_Style 
  231.       (Self  : Pango_Font_Description; 
  232.        Style : Pango.Enums.Style); 
  233.    pragma Import (C, Set_Style, "pango_font_description_set_style"); 
  234.    --  Sets the style field of a Pango.Font.Pango_Font_Description. The 
  235.    --  Pango.Enums.Style enumeration describes whether the font is slanted and 
  236.    --  the manner in which it is slanted; it can be either PANGO_STYLE_NORMAL, 
  237.    --  PANGO_STYLE_ITALIC, or PANGO_STYLE_OBLIQUE. Most fonts will either have 
  238.    --  a italic style or an oblique style, but not both, and font matching in 
  239.    --  Pango will match italic specifications with oblique fonts and vice-versa 
  240.    --  if an exact match is not found. 
  241.    --  "style": the style for the font description 
  242.  
  243.    function Get_Variant 
  244.       (Self : Pango_Font_Description) return Pango.Enums.Variant; 
  245.    pragma Import (C, Get_Variant, "pango_font_description_get_variant"); 
  246.    --  Gets the variant field of a Pango.Font.Pango_Font_Description. See 
  247.    --  Pango.Font.Set_Variant. 
  248.  
  249.    procedure Set_Variant 
  250.       (Self    : Pango_Font_Description; 
  251.        Variant : Pango.Enums.Variant); 
  252.    pragma Import (C, Set_Variant, "pango_font_description_set_variant"); 
  253.    --  Sets the variant field of a font description. The Pango.Enums.Variant 
  254.    --  can either be Pango.Enums.Pango_Variant_Normal or 
  255.    --  Pango.Enums.Pango_Variant_Small_Caps. 
  256.    --  "variant": the variant type for the font description. 
  257.  
  258.    function Get_Weight 
  259.       (Self : Pango_Font_Description) return Pango.Enums.Weight; 
  260.    pragma Import (C, Get_Weight, "pango_font_description_get_weight"); 
  261.    --  Gets the weight field of a font description. See Pango.Font.Set_Weight. 
  262.  
  263.    procedure Set_Weight 
  264.       (Self   : Pango_Font_Description; 
  265.        Weight : Pango.Enums.Weight); 
  266.    pragma Import (C, Set_Weight, "pango_font_description_set_weight"); 
  267.    --  Sets the weight field of a font description. The weight field specifies 
  268.    --  how bold or light the font should be. In addition to the values of the 
  269.    --  Pango.Enums.Weight enumeration, other intermediate numeric values are 
  270.    --  possible. 
  271.    --  "weight": the weight for the font description. 
  272.  
  273.    function Hash (Self : Pango_Font_Description) return Guint; 
  274.    pragma Import (C, Hash, "pango_font_description_hash"); 
  275.    --  Computes a hash of a Pango.Font.Pango_Font_Description structure 
  276.    --  suitable to be used, for example, as an argument to g_hash_table_new. 
  277.    --  The hash value is independent of Desc->mask. 
  278.  
  279.    procedure Merge 
  280.       (Self             : Pango_Font_Description; 
  281.        Desc_To_Merge    : Pango_Font_Description; 
  282.        Replace_Existing : Boolean); 
  283.    --  Merges the fields that are set in Desc_To_Merge into the fields in 
  284.    --  Desc. If Replace_Existing is False, only fields in Desc that are not 
  285.    --  already set are affected. If True, then fields that are already set will 
  286.    --  be replaced as well. 
  287.    --  If Desc_To_Merge is null, this function performs nothing. 
  288.    --  "desc_to_merge": the Pango.Font.Pango_Font_Description to merge from, 
  289.    --  or null 
  290.    --  "replace_existing": if True, replace fields in Desc with the 
  291.    --  corresponding values from Desc_To_Merge, even if they are already exist. 
  292.  
  293.    procedure Merge_Static 
  294.       (Self             : Pango_Font_Description; 
  295.        Desc_To_Merge    : Pango_Font_Description; 
  296.        Replace_Existing : Boolean); 
  297.    --  Like Pango.Font.Merge, but only a shallow copy is made of the family 
  298.    --  name and other allocated fields. Desc can only be used until 
  299.    --  Desc_To_Merge is modified or freed. This is meant to be used when the 
  300.    --  merged font description is only needed temporarily. 
  301.    --  "desc_to_merge": the Pango.Font.Pango_Font_Description to merge from 
  302.    --  "replace_existing": if True, replace fields in Desc with the 
  303.    --  corresponding values from Desc_To_Merge, even if they are already exist. 
  304.  
  305.    procedure Set_Absolute_Size 
  306.       (Self : Pango_Font_Description; 
  307.        Size : Gdouble); 
  308.    pragma Import (C, Set_Absolute_Size, "pango_font_description_set_absolute_size"); 
  309.    --  Sets the size field of a font description, in device units. This is 
  310.    --  mutually exclusive with Pango.Font.Set_Size which sets the font size in 
  311.    --  points. 
  312.    --  Since: gtk+ 1.8 
  313.    --  "size": the new size, in Pango units. There are PANGO_SCALE Pango units 
  314.    --  in one device unit. For an output backend where a device unit is a 
  315.    --  pixel, a Size value of 10 * PANGO_SCALE gives a 10 pixel font. 
  316.  
  317.    procedure Set_Family_Static 
  318.       (Self   : Pango_Font_Description; 
  319.        Family : UTF8_String); 
  320.    --  Like Pango.Font.Set_Family, except that no copy of Family is made. The 
  321.    --  caller must make sure that the string passed in stays around until Desc 
  322.    --  has been freed or the name is set again. This function can be used if 
  323.    --  Family is a static string such as a C string literal, or if Desc is only 
  324.    --  needed temporarily. 
  325.    --  "family": a string representing the family name. 
  326.  
  327.    function To_Filename (Self : Pango_Font_Description) return UTF8_String; 
  328.    --  Creates a filename representation of a font description. The filename 
  329.    --  is identical to the result from calling Pango.Font.To_String, but with 
  330.    --  underscores instead of characters that are untypical in filenames, and 
  331.    --  in lower case only. 
  332.  
  333.    function To_String (Self : Pango_Font_Description) return UTF8_String; 
  334.    --  Creates a string representation of a font description. See 
  335.    --  Pango.Font.From_String for a description of the format of the string 
  336.    --  representation. The family list in the string description will only have 
  337.    --  a terminating comma if the last word of the list is a valid style 
  338.    --  option. 
  339.  
  340.    procedure Unset_Fields 
  341.       (Self     : Pango_Font_Description; 
  342.        To_Unset : Pango.Enums.Font_Mask); 
  343.    pragma Import (C, Unset_Fields, "pango_font_description_unset_fields"); 
  344.    --  Unsets some of the fields in a Pango.Font.Pango_Font_Description. The 
  345.    --  unset fields will get back to their default values. 
  346.    --  "to_unset": bitmask of fields in the Desc to unset. 
  347.  
  348.    ---------------------- 
  349.    -- GtkAda additions -- 
  350.    ---------------------- 
  351.  
  352.    function To_Font_Description 
  353.      (Family_Name : String := ""; 
  354.       Style       : Pango.Enums.Style := Pango.Enums.Pango_Style_Normal; 
  355.       Variant     : Pango.Enums.Variant := Pango.Enums.Pango_Variant_Normal; 
  356.       Weight      : Pango.Enums.Weight := Pango.Enums.Pango_Weight_Normal; 
  357.       Stretch     : Pango.Enums.Stretch := Pango.Enums.Pango_Stretch_Normal; 
  358.       Size        : Gint := 0) return Pango_Font_Description; 
  359.    --  Create a new font decription from the given parameters. 
  360.  
  361.    function To_Address 
  362.      (F : Pango_Font_Description; Add : System.Address) return System.Address; 
  363.    package Desc_Properties is new Generic_Internal_Boxed_Property 
  364.      (Pango_Font_Description, Get_Type, To_Address); 
  365.    type Property_Font_Description is new Desc_Properties.Property; 
  366.  
  367.    procedure Free (Desc : in out Pango_Font_Description); 
  368.    --  Deallocate the given font description. 
  369.  
  370.    --------------- 
  371.    -- Functions -- 
  372.    --------------- 
  373.  
  374.    function From_String (Str : UTF8_String) return Pango_Font_Description; 
  375.    --  Creates a new font description from a string representation in the form 
  376.    --  "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a comma 
  377.    --  separated list of families optionally terminated by a comma, 
  378.    --  STYLE_OPTIONS is a whitespace separated list of words where each WORD 
  379.    --  describes one of style, variant, weight, stretch, or gravity, and SIZE 
  380.    --  is a decimal number (size in points) or optionally followed by the unit 
  381.    --  modifier "px" for absolute size. Any one of the options may be absent. 
  382.    --  If FAMILY-LIST is absent, then the family_name field of the resulting 
  383.    --  font description will be initialized to null. If STYLE-OPTIONS is 
  384.    --  missing, then all style options will be set to the default values. If 
  385.    --  SIZE is missing, the size in the resulting font description will be set 
  386.    --  to 0. 
  387.    --  "str": string representation of a font description. 
  388.  
  389. end Pango.Font;