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