1. ----------------------------------------------------------------------- 
  2. --              GtkAda - Ada95 binding for Gtk+/Gnome                -- 
  3. --                                                                   -- 
  4. --                   Copyright (C) 2004-2013, 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. --  Browse the available stock icons in the list of stock IDs found here. You 
  31. --  can also use the gtk-demo application for this purpose. 
  32. -- 
  33. --  An icon factory manages a collection of Gtk_Icon_Set; a Gtk_Icon_Set 
  34. --  manages set of variants of a particular icon (i.e. a Gtk_Icon_Set contains 
  35. --  variants for different sizes and widget states). Icons in an icon factory 
  36. --  are named by a stock ID, which is a simple string identifying the icon. 
  37. --  Each Gtk_Style has a list of Gtk_Icon_Factory derived from the current 
  38. --  theme; those icon factories are consulted first when searching for an icon. 
  39. --  If the theme doesn't set a particular icon, GTK+ looks for the icon in a 
  40. --  list of default icon factories, maintained by gtk.icon_factory.add_default 
  41. --  and gtk.icon_factory.remove_default. Applications with icons should add 
  42. --  default icon factory with their icons, which will allow themes to override 
  43. --  the icons for the application. 
  44. -- 
  45. --  To display an icon, always use Lookup_Icon_Set on the widget that 
  46. --  will display the icon, or the convenience function Gtk.Widget.Render_Icon. 
  47. --  These functions take the theme into account when looking up the icon to use 
  48. --  for a given stock ID. 
  49. --  </description> 
  50. --  <c_version>2.8.17</c_version> 
  51. --  <see>Gtk.Icon_Theme</see> 
  52.  
  53. with Glib.Object; 
  54. with Gdk.Pixbuf; 
  55. with Gtk.Enums; 
  56. with Gtk.Settings; 
  57. with Gtk.Style; 
  58. with Gtk.Widget; 
  59.  
  60. package Gtk.Icon_Factory is 
  61.  
  62.    -------------------- 
  63.    -- Icon factories -- 
  64.    -------------------- 
  65.  
  66.    type Gtk_Icon_Factory_Record is new Glib.Object.GObject_Record with private; 
  67.    type Gtk_Icon_Factory is access all Gtk_Icon_Factory_Record'Class; 
  68.  
  69.    procedure Gtk_New (Widget : out Gtk_Icon_Factory); 
  70.    procedure Initialize (Widget : access Gtk_Icon_Factory_Record'Class); 
  71.    --  Creates or initializes a new Icon_Factory. 
  72.  
  73.    function Get_Type return Glib.GType; 
  74.    --  Return the internal value associated with a Icon_Factory. 
  75.  
  76.    procedure Add_Default (Factory : access Gtk_Icon_Factory_Record); 
  77.    --  Adds an icon factory to the list of icon factories searched by 
  78.    --  Lookup_Icon_Set. This means that, for example, 
  79.    --  Gtk.Image.New_From_Stock will be able to find icons in Factory. 
  80.    --  There will normally be an icon factory added for each library or 
  81.    --  application that comes with icons. The default icon factories 
  82.    --  can be overridden by themes. 
  83.  
  84.    procedure Remove_Default (Factory : access Gtk_Icon_Factory_Record); 
  85.    --  Removes an icon factory from the list of default icon 
  86.    --  factories. Not normally used; you might use it for a library that 
  87.    --  can be unloaded or shut down. 
  88.  
  89.    --------------- 
  90.    -- Icon sets -- 
  91.    --------------- 
  92.  
  93.    --  An icon set represents a single icon in various sizes and widget states. 
  94.    --  It can provide a Gdk_Pixbuf for a given size and state on request, and 
  95.    --  automatically caches some of the rendered Gdk_Pixbuf objects. 
  96.    -- 
  97.    --  Normally you would use Gtk.Widget.Render_Icon instead of using icon sets 
  98.    --  directly. The one case where you'd use an icon set is to create 
  99.    --  application-specific icon sets to place in an icon factory. 
  100.  
  101.    type Gtk_Icon_Set is new Glib.C_Proxy; 
  102.  
  103.    function Gtk_New return Gtk_Icon_Set; 
  104.    --  Create an empty Gtk_Icon_Set. 
  105.  
  106.    function Gtk_New (Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf) return Gtk_Icon_Set; 
  107.    --  Creates a new icon set with Pixbuf as the default/fallback source 
  108.    --  image. If you don't add any additional icon sources (see below) to the 
  109.    --  icon set, all variants of the icon will be created from Pixbuf, 
  110.    --  using scaling, pixelation, etc. as required to adjust the icon size 
  111.    --  or make the icon look insensitive/prelighted. 
  112.  
  113.    procedure Add 
  114.      (Factory  : access Gtk_Icon_Factory_Record; 
  115.       Stock_Id : String; 
  116.       Set      : Gtk_Icon_Set); 
  117.    --  Adds the given icon set to the icon factory, under the name Stock_Id. 
  118.    --  Stock_Id should be namespaced for your application, e.g. 
  119.    --  "myapp-whatever-icon".  Normally applications create an icon factory, 
  120.    --  then add it to the list of default factories with Add_Default. Then they 
  121.    --  pass the Stock_Id to widgets such as Gtk_Image to display the icon. 
  122.    --  Themes can provide an icon with the same name (such as 
  123.    --  "myapp-whatever-icon") to override your application's default icons. If 
  124.    --  an icon already existed in Factory for Stock_Id, it is unreferenced and 
  125.    --  replaced with the new icon set. 
  126.  
  127.    function Lookup_Icon_Set 
  128.      (Style  : access Gtk.Style.Gtk_Style_Record'Class; Stock_Id : String) 
  129.       return Gtk_Icon_Set; 
  130.    --  Retrieve an icon set by its name. The icon might exist in various sizes, 
  131.    --  that can be manipulated through the result set 
  132.  
  133.    function Lookup 
  134.      (Factory  : access Gtk_Icon_Factory_Record; 
  135.       Stock_Id : String) return Gtk_Icon_Set; 
  136.    --  Looks up Stock_Id in the icon factory, returning an icon set if found, 
  137.    --  otherwise null. For display to the user, you should use 
  138.    --  Lookup_Icon_Set on the Gtk_Style for the widget that will 
  139.    --  display the icon, instead of using this function directly, so that 
  140.    --  themes are taken into account. 
  141.  
  142.    function Lookup_Default (Stock_Id : String) return Gtk_Icon_Set; 
  143.    --  Looks for an icon in the list of default icon factories.  For 
  144.    --  display to the user, you should use Lookup_Icon_Set on 
  145.    --  the Gtk_Style for the widget that will display the icon, instead of 
  146.    --  using this function directly, so that themes are taken into 
  147.    --  account. 
  148.  
  149.    function Icon_Set_Get_Type return Glib.GType; 
  150.    --  Return the internal type value for Gtk_Icon_Set 
  151.  
  152.    function Copy (Icon_Set : Gtk_Icon_Set) return Gtk_Icon_Set; 
  153.    pragma Import (C, Copy, "gtk_icon_set_copy"); 
  154.    --  Copies Icon_Set by value. 
  155.  
  156.    function Get_Sizes (Icon_Set : Gtk_Icon_Set) return Gint_Array; 
  157.    --  Obtains a list of icon sizes this icon set can render. 
  158.  
  159.    procedure Ref   (Icon_Set : Gtk_Icon_Set); 
  160.    procedure Unref (Icon_Set : Gtk_Icon_Set); 
  161.    pragma Import (C, Ref,   "gtk_icon_set_ref"); 
  162.    pragma Import (C, Unref, "gtk_icon_set_unref"); 
  163.    --  Increase or decrease the reference counting for the icon set. When this 
  164.    --  reaches 0, the memory is reclaimed 
  165.  
  166.    function Render_Icon 
  167.      (Icon_Set  : Gtk_Icon_Set; 
  168.       Style     : access Gtk.Style.Gtk_Style_Record'Class; 
  169.       Direction : Gtk.Enums.Gtk_Text_Direction; 
  170.       State     : Gtk.Enums.Gtk_State_Type; 
  171.       Size      : Gtk.Enums.Gtk_Icon_Size; 
  172.       Widget    : Gtk.Widget.Gtk_Widget := null; 
  173.       Detail    : String := "") 
  174.       return Gdk.Pixbuf.Gdk_Pixbuf; 
  175.    --  Renders an icon using Render_Icon below. In most cases, the other 
  176.    --  version of Render_Icon is better, since it automatically provides most 
  177.    --  of the arguments from the current widget settings. This function never 
  178.    --  returns null; if the icon can't be rendered (perhaps because an image 
  179.    --  file fails to load), a default "missing image" icon will be returned 
  180.    --  instead. 
  181.    --  Widget is the widget that will display the icon, or null. This is 
  182.    --  typically used to determine the screen (and thus the colormap depth). 
  183.    --  Detail is the string to pass to the theme engine to provide more 
  184.    --  information. Passing anything but the empty string will disable 
  185.    --  caching. 
  186.  
  187.    ------------------ 
  188.    -- Icon sources -- 
  189.    ------------------ 
  190.  
  191.    --  An icon source contains a Gdk_Pixbuf (or image filename) that serves as 
  192.    --  the base image for one or more of the icons in an icon set, along with a 
  193.    --  specification for which icons in the icon set will be based on that 
  194.    --  pixbuf or image file. An icon set contains a set of icons that represent 
  195.    --  "the same" logical concept in different states, different global text 
  196.    --  directions, and different sizes. 
  197.    -- 
  198.    --  So for example a web browser's "Back to Previous Page" icon might point 
  199.    --  in a different direction in Hebrew and in English; it might look 
  200.    --  different when insensitive; and it might change size depending on 
  201.    --  toolbar mode (small/large icons). So a single icon set would contain all 
  202.    --  those variants of the icon. An icon set contains a list of icon sources 
  203.    --  from which it can derive specific icon variants in the set. 
  204.    -- 
  205.    --  In the simplest case, an icon set contains one source pixbuf from which 
  206.    --  it derives all variants. 
  207.    -- 
  208.    --  If you want to use a different base pixbuf for different icon variants, 
  209.    --  you create multiple icon sources, mark which variants they'll be used to 
  210.    --  create, and add them to the icon set with Add_Source (see below). 
  211.    -- 
  212.    --  By default, the icon source has all parameters wildcarded. That is, the 
  213.    --  icon source will be used as the base icon for any desired text 
  214.    --  direction, widget state, or icon size. 
  215.  
  216.    type Gtk_Icon_Source is new Glib.C_Proxy; 
  217.  
  218.    function Gtk_New return Gtk_Icon_Source; 
  219.    --  Create a new icon source. 
  220.  
  221.    function Icon_Source_Copy (Source : Gtk_Icon_Source) return Gtk_Icon_Source; 
  222.    --  Returns a copy of Gtk_Icon_Source. This function is generally not 
  223.    --  useful 
  224.  
  225.    function Icon_Source_Get_Type return Glib.GType; 
  226.    --  Return the internal type used for Gtk_Icon_Source 
  227.  
  228.    function Render_Icon 
  229.      (Style     : access Gtk.Style.Gtk_Style_Record'Class; 
  230.       Source    : Gtk.Icon_Factory.Gtk_Icon_Source; 
  231.       Direction : Gtk.Enums.Gtk_Text_Direction; 
  232.       State     : Gtk.Enums.Gtk_State_Type; 
  233.       Size      : Gtk.Enums.Gtk_Icon_Size; 
  234.       Widget    : Gtk.Widget.Gtk_Widget := null; 
  235.       Detail    : String := "") 
  236.       return Gdk.Pixbuf.Gdk_Pixbuf; 
  237.    --  Renders the icon specified by Source at the given Size according to the 
  238.    --  given parameters and returns the result in pixbuf. 
  239.  
  240.    procedure Add_Source 
  241.      (Set    : Gtk_Icon_Set; 
  242.       Source : Gtk_Icon_Source); 
  243.    --  Icon sets have a list of icon sources, which they use as base 
  244.    --  icons for rendering icons in different states and sizes. Icons are 
  245.    --  scaled, made to look insensitive, etc. in Gtk.Icon.Set_Render_Icon, 
  246.    --  but an icon set needs base images to work with. The base images and 
  247.    --  when to use them are described by an icon source. 
  248.    --  This function copies Source, so you can reuse the same source 
  249.    --  immediately without affecting the icon set. 
  250.  
  251.    procedure Free (Source : Gtk_Icon_Source); 
  252.    --  Free memory allocated to Source. 
  253.  
  254.    procedure Set_Filename 
  255.      (Source : Gtk_Icon_Source; Filename : String); 
  256.    function Get_Filename (Source : Gtk_Icon_Source) return String; 
  257.    --  Set the name of an image file to use as a base image when creating 
  258.    --  icon variants for an icon set. The filename must be absolute. 
  259.  
  260.    procedure Set_Pixbuf 
  261.      (Source : Gtk_Icon_Source; Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf); 
  262.    function Get_Pixbuf 
  263.      (Source : Gtk_Icon_Source) return Gdk.Pixbuf.Gdk_Pixbuf; 
  264.    --  Set a pixbuf to use as a base image when creating icon variants 
  265.    --  for an icon set. If an icon source has both a filename and a pixbuf 
  266.    --  set, the pixbuf will take priority. 
  267.  
  268.    procedure Set_Size 
  269.      (Source : Gtk_Icon_Source; Size : Gtk.Enums.Gtk_Icon_Size); 
  270.    function Get_Size 
  271.      (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_Icon_Size; 
  272.    --  Set the icon size this icon source is intended to be used with 
  273.  
  274.    procedure Set_Icon_Name (Source : Gtk_Icon_Source; Icon_Name : String); 
  275.    function  Get_Icon_Name (Source : Gtk_Icon_Source) return String; 
  276.    --  Retrieves the source icon name, or "" if none is set. The icon comes 
  277.    --  from an icon theme in this case. 
  278.  
  279.    procedure Set_Size_Wildcarded 
  280.      (Source : Gtk_Icon_Source; Wildcarded : Boolean); 
  281.    function Get_Size_Wildcarded (Source : Gtk_Icon_Source) return Boolean; 
  282.    --  Change the wilcarded state of the size for the icon source. 
  283.    -- 
  284.    --  If the icon size is wildcarded, this source can be used as the base 
  285.    --  image for an icon of any size.  if the size is not wildcarded, then 
  286.    --  the size the source applies to should be set with Set_Size, 
  287.    --  and the icon source will only be used with that specific size. 
  288.    -- 
  289.    --  Gtk prefers non-wildcarded sources (exact matches) over wildcarded 
  290.    --  sources, and will use an exact match when possible. 
  291.    -- 
  292.    --  Gtk will normally scale wildcarded source images to produce 
  293.    --  an appropriate icon at a given size, but will not change the size 
  294.    --  of source images that match exactly. 
  295.  
  296.    procedure Set_Direction_Wildcarded 
  297.      (Source  : Gtk_Icon_Source;  Setting : Boolean); 
  298.    function Get_Direction_Wildcarded 
  299.      (Source : Gtk_Icon_Source) return Boolean; 
  300.    --  If the text direction is wildcarded, this source can be used as the base 
  301.    --  image for an icon in any Gtk_Text_Direction. 
  302.    --  If the text direction is not wildcarded, then the text direction the 
  303.    --  icon source applies to should be set with Set_Direction(), and the icon 
  304.    --  source will only be used with that text direction. 
  305.    --  Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over 
  306.    --  wildcarded sources, and will use an exact match when possible 
  307.  
  308.    procedure Set_Direction 
  309.      (Source : Gtk_Icon_Source; Direction : Gtk.Enums.Gtk_Text_Direction); 
  310.    function Get_Direction 
  311.      (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_Text_Direction; 
  312.    --  Sets the text direction this icon source is intended to be used 
  313.    --  with. 
  314.    --  Setting the text direction on an icon source makes no difference if the 
  315.    --  text direction is wildcarded. Therefore, you should usually call 
  316.    --  Set_Direction_Wildcarded() to un-wildcard it in addition to calling this 
  317.    --  function. 
  318.  
  319.    procedure Set_State_Wildcarded 
  320.      (Source  : Gtk_Icon_Source;  Setting : Boolean); 
  321.    function Get_State_Wildcarded (Source  : Gtk_Icon_Source) return Boolean; 
  322.    --  If the widget state is wildcarded, this source can be used as the base 
  323.    --  image for an icon in any Gtk_State_Type. If the widget state is not 
  324.    --  wildcarded, then the state the source applies to should be set with 
  325.    --  Set_State and the icon source will only be used with that specific 
  326.    --  state. 
  327.    --  Gtk_Icon_Set prefers non-wildcarded sources (exact matches) over 
  328.    --  wildcarded sources, and will use an exact match when possible. 
  329.    --  Gtk_Icon_Set will normally transform wildcarded source images to produce 
  330.    --  an appropriate icon for a given state, for example lightening an image 
  331.    --  on prelight, but will not modify source images that match exactly. 
  332.  
  333.    procedure Set_State 
  334.      (Source : Gtk_Icon_Source; State  : Gtk.Enums.Gtk_State_Type); 
  335.    function Get_State 
  336.      (Source : Gtk_Icon_Source) return Gtk.Enums.Gtk_State_Type; 
  337.    --  Sets the widget state this icon source is intended to be used 
  338.    --  with. 
  339.    --  Setting the widget state on an icon source makes no difference if the 
  340.    --  state is wildcarded. Therefore, you should usually call 
  341.    --  Set_State_Wildcarded to un-wildcard it in addition to calling this 
  342.    --  function. 
  343.  
  344.    ---------------- 
  345.    -- Icon sizes -- 
  346.    ---------------- 
  347.    --  There are a number of predefined icon sizes (see gtk-enums.ads). These 
  348.    --  are used in the various gtk+ contexts. However, you can also define your 
  349.    --  own icon sizes to use in your application. 
  350.  
  351.    function Icon_Size_From_Name (Name : String) return Gtk.Enums.Gtk_Icon_Size; 
  352.    --  Looks up the icon size associated with Name. 
  353.    --  Predefined icon sizes are associated with the following names: 
  354.    --    Icon_Size_Menu          => "gtk-menu"          (16x16) 
  355.    --    Icon_Size_Button        => "gtk-button"        (20x20) 
  356.    --    Icon_Size_Small_Toolbar => "gtk-small-toolbar" (18x18) 
  357.    --    Icon_Size_Large_Toolbar => "gtk-large-toolbar" (24x24) 
  358.    --    Icon_Size_Dnd           => "gtk-dnd"           (32x32) 
  359.    --    Icon_Size_Dialog        => "gtk-dialog"        (48x48) 
  360.    --  You can also define your own names (see Icon_Size_Register) 
  361.  
  362.    function Icon_Size_Get_Name (Size : Gtk.Enums.Gtk_Icon_Size) return String; 
  363.    --  Gets the canonical name of the given icon size 
  364.  
  365.    procedure Icon_Size_Lookup 
  366.      (Size          : Gtk.Enums.Gtk_Icon_Size; 
  367.       Width, Height : out Gint); 
  368.    --  Obtains the pixel size of a semantic icon size, possibly 
  369.    --  modified by user preferences for the default Gtk_Settings. 
  370.    --  (See Icon_Size_Lookup_For_Settings). 
  371.    --  This function isn't normally needed, Render_Icon is the usual way to get 
  372.    --  an icon for rendering, then just look at the size of the rendered 
  373.    --  pixbuf. The rendered pixbuf may not even correspond to the width/height 
  374.    --  returned by Icon_Size_Lookup, because themes are free to render the 
  375.    --  pixbuf however they like, including changing the usual size. 
  376.    --  Sizes are set to -1 if Size is invalid. 
  377.  
  378.    procedure Icon_Size_Lookup_For_Settings 
  379.      (Settings : access Gtk.Settings.Gtk_Settings_Record'Class; 
  380.       Size     : Gtk.Enums.Gtk_Icon_Size; 
  381.       Width    : out Gint; 
  382.       Height   : out Gint); 
  383.    --  Obtains the pixel size of a semantic icon size, possibly modified by 
  384.    --  user preferences for a particular Gtk_Settings. 
  385.  
  386.    function Icon_Size_Register 
  387.      (Name   : String; 
  388.       Width  : Gint; 
  389.       Height : Gint) 
  390.       return Gtk.Enums.Gtk_Icon_Size; 
  391.    --  Registers a new icon size, along the same lines as Icon_Size_Menu, 
  392.    --  etc. Returns the integer value for the size. 
  393.  
  394.    procedure Icon_Size_Register_Alias 
  395.      (Alias : String;  Target : Gtk.Enums.Gtk_Icon_Size); 
  396.    --  Registers Alias as another name for Target. 
  397.    --  So calling Icon_Size_From_Name with Alias as argument will return Target 
  398.  
  399.    ------------- 
  400.    -- Signals -- 
  401.    ------------- 
  402.  
  403.    --  <signals> 
  404.    --  The following new signals are defined for this widget: 
  405.    --  </signals> 
  406.  
  407. private 
  408.    type Gtk_Icon_Factory_Record is 
  409.      new Glib.Object.GObject_Record with null record; 
  410.  
  411.    pragma Import (C, Get_Type, "gtk_icon_factory_get_type"); 
  412.    pragma Import (C, Set_Size, "gtk_icon_source_set_size"); 
  413.    pragma Import (C, Get_Size, "gtk_icon_source_get_size"); 
  414.    pragma Import (C, Icon_Set_Get_Type, "gtk_icon_set_get_type"); 
  415.    pragma Import (C, Icon_Source_Get_Type, "gtk_icon_source_get_type"); 
  416.    pragma Import (C, Set_Direction, "gtk_icon_source_set_direction"); 
  417.    pragma Import (C, Get_Direction, "gtk_icon_source_get_direction"); 
  418.    pragma Import (C, Set_State, "gtk_icon_source_set_state"); 
  419.    pragma Import (C, Get_State, "gtk_icon_source_get_state"); 
  420.    pragma Import (C, Icon_Source_Copy, "gtk_icon_source_copy"); 
  421.  
  422. end Gtk.Icon_Factory;