1. ----------------------------------------------------------------------- 
  2. --              GtkAda - Ada95 binding for Gtk+/Gnome                -- 
  3. --                                                                   -- 
  4. --                Copyright (C) 2006-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. --  Gtk_Icon_Theme provides a facility for looking up icons by name and size. 
  31. --  The main reason for using a name rather than simply providing a filename is 
  32. --  to allow different icons to be used depending on what icon theme is 
  33. --  selecetd by the user. The operation of icon themes on Linux and Unix 
  34. --  follows the Icon Theme Specification. There is a default icon theme, named 
  35. --  hicolor where applications should install their icons, but more additional 
  36. --  application themes can be installed as operating system vendors and users 
  37. --  choose. 
  38. -- 
  39. --  Named icons are similar to the Themeable Stock Images(3) facility, and the 
  40. --  distinction between the two may be a bit confusing. A few things to keep in 
  41. --  mind: 
  42. -- 
  43. --  - Stock images usually are used in conjunction with Stock Items(3)., such 
  44. --    as STOCK_OK or STOCK_OPEN. Named icons are easier to set up and 
  45. --    therefore are more useful for new icons that an application wants to add, 
  46. --    such as application icons or window icons. 
  47. -- 
  48. --  - Stock images can only be loaded at the symbolic sizes defined by the 
  49. --    Gtk_Icon_Size enumeration, or by custom sizes defined by 
  50. --    Gtk.Icon_Factory.Icon_Size_Register, while named icons are more flexible 
  51. --    and any pixel size can be specified. 
  52. -- 
  53. --  - Because stock images are closely tied to stock items, and thus to actions 
  54. --    in the user interface, stock images may come in multiple variants for 
  55. --    different widget states or writing directions. 
  56. -- 
  57. --  A good rule of thumb is that if there is a stock image for what you want to 
  58. --  use, use it, otherwise use a named icon. It turns out that internally stock 
  59. --  images are generally defined in terms of one or more named icons. (An 
  60. --  example of the more than one case is icons that depend on writing 
  61. --  direction; STOCK_GO_FORWARD uses the two themed icons 
  62. --  "gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".) 
  63. -- 
  64. --  In many cases, named themes are used indirectly, via Gtk_Image or stock 
  65. --  items, rather than directly, but looking up icons directly is also simple. 
  66. --  The Gtk_Icon_Theme object acts as a database of all the icons in the 
  67. --  current theme. You can create new Gtk_Icon_Theme objects, but its much more 
  68. --  efficient to use the standard icon theme for the Gdk_Screen so that the 
  69. --  icon information is shared with other people looking up icons. In the case 
  70. --  where the default screen is being used, looking up an icon can be as simple 
  71. --  as: 
  72. --      Theme := Get_Default; 
  73. --      Pixbuf := Load_Icon (Theme, "my-icon-name", 48, 0, Error); 
  74. --      if Pixbuf = null then 
  75. --         Put_Line ("Error " & Get_Message (Error); 
  76. --         Error_Free (Error); 
  77. --      end if; 
  78. --  </description> 
  79. --  <c_version>2.16.6</c_version> 
  80. --  <group>Display widgets</group> 
  81. --  <see>Gtk.Icon_Factory</see> 
  82.  
  83. with Gdk.Pixbuf; 
  84. with Gdk.Rectangle; 
  85. with Gdk.Types; 
  86. with Glib.Error; 
  87. with Glib.G_Icon; 
  88. with Glib.Object; 
  89. with Gtk.Enums; 
  90. with GNAT.Strings; 
  91.  
  92. package Gtk.Icon_Theme is 
  93.  
  94.    type Gtk_Icon_Theme_Record is new Glib.Object.GObject_Record with 
  95.      null record; 
  96.    type Gtk_Icon_Theme is access all Gtk_Icon_Theme_Record'Class; 
  97.  
  98.    type Gtk_Icon_Lookup_Flags is mod Gint'Last; 
  99.    Icon_Lookup_No_Svg      : constant Gtk_Icon_Lookup_Flags := 2 ** 0; 
  100.    Icon_Lookup_Force_Svg   : constant Gtk_Icon_Lookup_Flags := 2 ** 1; 
  101.    Icon_Lookup_Use_Builtin : constant Gtk_Icon_Lookup_Flags := 2 ** 2; 
  102.    --  Used to specify options for Lookup_Icon. 
  103.    --  No_Svg: never return SVG icons, even if gdk-pixbuf supports them. 
  104.    --  Force_Svg: return SVG even if gdk-pixbuf doesn't support them. 
  105.    --  Use_Builtin: including builtin icons as well as files. 
  106.  
  107.    --------------- 
  108.    -- Icon_Info -- 
  109.    --------------- 
  110.  
  111.    type Gtk_Icon_Info is new Glib.C_Proxy; 
  112.  
  113.    function Icon_Info_Get_Type return GType; 
  114.  
  115.    function New_For_Pixbuf 
  116.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  117.       Pixbuf     : Gdk.Pixbuf.Gdk_Pixbuf) 
  118.       return Gtk_Icon_Info; 
  119.    --  Creates a Gtk_Icon_Info for a Gtk_Pixbuf. 
  120.  
  121.    function Copy (Icon_Info : Gtk_Icon_Info) return Gtk_Icon_Info; 
  122.    --  Make a copy of a Icon_Info 
  123.  
  124.    procedure Free (Icon_Info : Gtk_Icon_Info); 
  125.    --  Free a Gtk_Icon_Info and associated information 
  126.  
  127.    function Get_Attach_Points 
  128.      (Icon_Info : Gtk_Icon_Info) return Gdk.Types.Gdk_Points_Array; 
  129.    --  Fetches the set of attach points for an icon. An attach point is a 
  130.    --  location in the icon that can be used as anchor points for attaching 
  131.    --  emblems or overlays to the icon. 
  132.  
  133.    function Get_Base_Size (Icon_Info : Gtk_Icon_Info) return Gint; 
  134.    --  Gets the base size for the icon. The base size is a size for the icon 
  135.    --  that was specified by the icon theme creator. This may be different than 
  136.    --  the actual size of image; an example of this is small emblem icons that 
  137.    --  can be attached to a larger icon. These icons will be given the same 
  138.    --  base size as the larger icons to which they are attached. 
  139.    -- 
  140.    --  Return value: the base size, or 0, if no base size is known for the 
  141.    --  icon. 
  142.  
  143.    function Get_Builtin_Pixbuf 
  144.      (Icon_Info : Gtk_Icon_Info) return Gdk.Pixbuf.Gdk_Pixbuf; 
  145.    --  Gets the built-in image for this icon, if any. To allow GTK+ to use 
  146.    --  built in icon images, you must pass the %GTK_ICON_LOOKUP_USE_BUILTIN to 
  147.    --  Gtk.Icon_Theme.Lookup_Icon. 
  148.    -- 
  149.    --  Return value: the built-in image pixbuf, or null. No extra reference is 
  150.    --  added to the returned pixbuf, so if you want to keep it around, you must 
  151.    --  use Ref. The returned image must not be modified. 
  152.  
  153.    function Get_Display_Name (Icon_Info : Gtk_Icon_Info) return String; 
  154.    --  Gets the display name for an icon. A display name is a string to be used 
  155.    --  in place of the icon name in a user visible context like a list of 
  156.    --  icons. 
  157.  
  158.    procedure Get_Embedded_Rect 
  159.      (Icon_Info              : Gtk_Icon_Info; 
  160.       Rectangle              : in out Gdk.Rectangle.Gdk_Rectangle; 
  161.       Has_Embedded_Rectangle : out Boolean); 
  162.    --  Gets the coordinates of a rectangle within the icon that can be used for 
  163.    --  display of information such as a preview of the contents of a text file. 
  164.    --  See Set_Raw_Coordinates for further information about the coordinate 
  165.    --  system. 
  166.    --  Rectangle is only set if Has_Embedded_Rectangle is set to True. 
  167.  
  168.    function Get_Filename (Icon_Info : Gtk_Icon_Info) return String; 
  169.    --  Gets the filename for the icon. If the %GTK_ICON_LOOKUP_USE_BUILTIN flag 
  170.    --  was passed to Lookup_Icon, there may be no filename if a builtin icon is 
  171.    --  returned; in this case, you should use Get_Builtin_Pixbuf. 
  172.    --  Return value: the filename for the icon, or "" if Get_Builtin_Pixbuf() 
  173.    --  should be used instead. 
  174.  
  175.    function Load_Icon 
  176.      (Icon_Info : Gtk_Icon_Info; 
  177.       Error     : Glib.Error.GError_Access := null) 
  178.       return Gdk.Pixbuf.Gdk_Pixbuf; 
  179.    --  Renders an icon previously looked up in an icon theme using Lookup_Icon; 
  180.    --  the size will be based on the size passed to Lookup_Icon. Note that the 
  181.    --  resulting pixbuf may not be exactly this size; an icon theme may have 
  182.    --  icons that differ slightly from their nominal sizes, and in addition 
  183.    --  GTK+ will avoid scaling icons that it considers sufficiently close to 
  184.    --  the requested size or for which the source image would have to be scaled 
  185.    --  up too far. (This maintains sharpness.) 
  186.    --  Return value: the rendered icon; this may be a newly created icon or a 
  187.    --  new reference to an internal icon, so you must not modify the icon. Use 
  188.    --  Unref to release your reference to the icon. 
  189.  
  190.    procedure Set_Raw_Coordinates 
  191.      (Icon_Info       : Gtk_Icon_Info; 
  192.       Raw_Coordinates : Boolean); 
  193.    --  Sets whether the coordinates returned by Get_Embedded_Rect and 
  194.    --  Get_Attach_Points should be returned in their original form as specified 
  195.    --  in the icon theme, instead of scaled appropriately for the pixbuf 
  196.    --  returned by Load_Icon. 
  197.    -- 
  198.    --  Raw coordinates are somewhat strange; they are specified to be with 
  199.    --  respect to the unscaled pixmap for PNG and XPM icons, but for SVG icons, 
  200.    --  they are in a 1000x1000 coordinate space that is scaled to the final 
  201.    --  size of the icon. You can determine if the icon is an SVG icon by using 
  202.    --  Get_Filename, and seeing if it is non-empty and ends in '.svg'. 
  203.    -- 
  204.    --  This function is provided primarily to allow compatibility wrappers 
  205.    --  for older API's, and is not expected to be useful for applications. 
  206.  
  207.    ----------------- 
  208.    -- Search path -- 
  209.    ----------------- 
  210.  
  211.    Default_Theme_Name : constant String := "hicolor"; 
  212.  
  213.    procedure Set_Search_Path 
  214.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  215.       Path       : GNAT.Strings.String_List); 
  216.    --  Sets the search path for the icon theme object. When looking for an icon 
  217.    --  theme, GTK+ will search for a subdirectory of one or more of the 
  218.    --  directories in Path with the same name as the icon theme. (Themes from 
  219.    --  multiple of the path elements are combined to allow themes to be 
  220.    --  extended by adding icons in the user's home directory.) 
  221.    -- 
  222.    --  In addition if an icon found isn't found either in the current icon 
  223.    --  theme or the default icon theme, and an image file with the right name 
  224.    --  is found directly in one of the elements of Path, then that image will 
  225.    --  be used for the icon name. (This is legacy feature, and new icons should 
  226.    --  be put into the default icon theme, which is called DEFAULT_THEME_NAME, 
  227.    --  rather than directly on the icon path.) 
  228.  
  229.    procedure Append_Search_Path 
  230.      (Icon_Theme : access Gtk_Icon_Theme_Record; Path : String); 
  231.    procedure Prepend_Search_Path 
  232.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  233.       Path       : String); 
  234.    --  Appends or prepends a directory to the search path. 
  235.    --  Set_Search_Path. 
  236.  
  237.    function Get_Search_Path 
  238.      (Icon_Theme : access Gtk_Icon_Theme_Record) 
  239.       return GNAT.Strings.String_List; 
  240.    --  Gets the current search path 
  241.  
  242.    ----------------- 
  243.    -- Icon themes -- 
  244.    ----------------- 
  245.  
  246.    procedure Gtk_New    (Theme : out Gtk_Icon_Theme); 
  247.    procedure Initialize (Theme : access Gtk_Icon_Theme_Record'Class); 
  248.    --  Creates a new icon theme object. Icon theme objects are used to lookup 
  249.    --  up an icon by name in a particular icon theme. Usually, you'll want to 
  250.    --  use Get_Default or Get_For_Screen rather than creating a new icon theme 
  251.    --  object for scratch. 
  252.  
  253.    function Get_Type return GType; 
  254.    --  Return the internal type associated with icon themes 
  255.  
  256.    procedure Add_Builtin_Icon 
  257.      (Icon_Name : String; 
  258.       Size      : Gint; 
  259.       Pixbuf    : Gdk.Pixbuf.Gdk_Pixbuf); 
  260.    --  Registers a built-in icon for icon theme lookups. The idea of built-in 
  261.    --  icons is to allow an application or library that uses themed icons to 
  262.    --  function requiring files to be present in the file system. For instance, 
  263.    --  the default images for all of GTK+'s stock icons are registered as 
  264.    --  built-icons. 
  265.    -- 
  266.    --  In general, if you use Add_Builtin_Icon you should also install the icon 
  267.    --  in the icon theme, so that the icon is generally available. 
  268.    -- 
  269.    --  This function will generally be used with pixbufs loaded via 
  270.    --  Gdk.Pixbuf.Gdk_New_From-Inline. 
  271.  
  272.    function Choose_Icon 
  273.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  274.       Icon_Names : GNAT.Strings.String_List; 
  275.       Size       : Gint; 
  276.       Flags      : Gtk_Icon_Lookup_Flags) 
  277.       return Gtk_Icon_Info; 
  278.    --  Looks up a named icon and returns a structure containing 
  279.    --  information such as the filename of the icon.  Returns null if 
  280.    --  the icon wasn't found.  The returned value can then be rendered 
  281.    --  into a pixbuf using Load_Icon.  There is also a Load_Icon 
  282.    --  subprogram that combines these two steps if all you need is the 
  283.    --  pixbuf. 
  284.    -- 
  285.    --  If Icon_Names contains more than one name, this function 
  286.    --  tries them all in the given order before falling back to 
  287.    --  inherited icon themes. 
  288.    -- 
  289.    --  Free the returned value with Free. 
  290.  
  291.    function Get_Default return Gtk_Icon_Theme; 
  292.    --  Gets the icon theme for the default screen. See Get_For_Screen. Return 
  293.    --  value: A unique Gtk_Icon_Theme associated with the default screen. This 
  294.    --  icon theme is associated with the screen and can be used as long as the 
  295.    --  screen is open. Do not ref or unref it. 
  296.  
  297.    function Get_Example_Icon_Name 
  298.      (Icon_Theme : access Gtk_Icon_Theme_Record) return String; 
  299.    --  Gets the name of an icon that is representative of the current theme 
  300.    --  (for instance, to use when presenting a list of themes to the user.) 
  301.  
  302.    function Get_Icon_Sizes 
  303.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  304.       Icon_Name  : String) return Glib.Gint_Array; 
  305.    --  Returns an array of integers describing the sizes at which the icon is 
  306.    --  available without scaling. A size of -1 means that the icon is available 
  307.    --  in a scalable format. 
  308.  
  309.    function Has_Icon 
  310.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  311.       Icon_Name  : String) return Boolean; 
  312.    --  Checks whether an icon theme includes an icon for a particular name. 
  313.  
  314.    function List_Icons 
  315.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  316.       Context    : String := "") return Gtk.Enums.String_List.Glist; 
  317.    --  Lists the icons in the current icon theme. Only a subset of the icons 
  318.    --  can be listed by providing a context string. The set of values for the 
  319.    --  context string is system dependent, but will typically include such 
  320.    --  values as "Applications" and "MimeTypes". 
  321.    --  You must free the list with Gtk.Enums.Free_String_List. 
  322.  
  323.    function Load_Icon 
  324.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  325.       Icon_Name  : String; 
  326.       Size       : Glib.Gint; 
  327.       Flags      : Gtk_Icon_Lookup_Flags) 
  328.       return Gdk.Pixbuf.Gdk_Pixbuf; 
  329.    --  Looks up an icon in an icon theme, scales it to the given size and 
  330.    --  renders it into a pixbuf. This is a convenience function; if more 
  331.    --  details about the icon are needed, use Lookup_Icon or Choose_Icon 
  332.    --  followed by Load_Icon. 
  333.    -- 
  334.    --  Note that you probably want to listen for icon theme changes and update 
  335.    --  the icon. This is usually done by connecting to the GtkWidget::style-set 
  336.    --  signal. If for some reason you do not want to update the icon when the 
  337.    --  icon theme changes, you should consider using Gdk.Pixbuf.Copy to make a 
  338.    --  private copy of the pixbuf returned by this function. Otherwise GTK+ may 
  339.    --  need to keep the old icon theme loaded, which would be a waste of 
  340.    --  memory. 
  341.    -- 
  342.    --  Return value: the rendered icon; this may be a newly created icon or a 
  343.    --  new reference to an internal icon, so you must not modify the icon. Use 
  344.    --  Unref to release your reference to the icon. 
  345.  
  346.    function Lookup_By_Gicon 
  347.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  348.       Icon       : Glib.G_Icon.G_Icon; 
  349.       Size       : Gint; 
  350.       Flags      : Gtk_Icon_Lookup_Flags) 
  351.       return Gtk_Icon_Info; 
  352.    --  Looks up an icon and returns a structure containing 
  353.    --  information such as the filename of the icon. 
  354.    --  The icon can then be rendered into a pixbuf using 
  355.    --  Load_Icon.  Returns null if the icon wasn't found. 
  356.    --  Free the returned value with Free. 
  357.  
  358.    function Lookup_Icon 
  359.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  360.       Icon_Name  : String; 
  361.       Size       : Glib.Gint; 
  362.       Flags      : Gtk_Icon_Lookup_Flags) 
  363.       return Gtk_Icon_Info; 
  364.    --  Looks up a named icon and returns a structure containing information 
  365.    --  such as the filename of the icon. The icon can then be rendered into a 
  366.    --  pixbuf using Load_Icon. (Load_Icon combines these two steps if all you 
  367.    --  need is the pixbuf) 
  368.    --  Free the returned value with Free. 
  369.  
  370.    function Rescan_If_Needed 
  371.      (Icon_Theme : access Gtk_Icon_Theme_Record) return Boolean; 
  372.    --  Checks to see if the icon theme has changed; if it has, any 
  373.    --  currently cached information is discarded and will be reloaded 
  374.    --  next time Icon_Theme is accessed. 
  375.  
  376.    procedure Set_Custom_Theme 
  377.      (Icon_Theme : access Gtk_Icon_Theme_Record; 
  378.       Theme_Name : String); 
  379.    --  Sets the name of the icon theme that the Gtk_Icon_Theme object uses 
  380.    --  overriding system configuration. This function cannot be called on the 
  381.    --  icon theme objects returned from Get_Default and Get_For_Screen. 
  382.  
  383.    ------------- 
  384.    -- Signals -- 
  385.    ------------- 
  386.  
  387.    --  <signals> 
  388.    --  The following new signals are defined for this widget: 
  389.    -- 
  390.    --  - "changed" 
  391.    --    procedure Handler (Theme : access Gtk_Icon_Theme_Record'Class); 
  392.    --    Emitted when the current icon theme is switched or GTK+ detects that a 
  393.    --    change has occurred in the contents of the current icon theme. 
  394.    --  </signals> 
  395.  
  396.    Signal_Changed : constant Glib.Signal_Name := "changed"; 
  397.  
  398. private 
  399.    pragma Import (C, Free, "gtk_icon_info_free"); 
  400.    pragma Import (C, Get_Base_Size, "gtk_icon_info_get_base_size"); 
  401.    pragma Import (C, Copy, "gtk_icon_info_copy"); 
  402.    pragma Import (C, Get_Type, "gtk_icon_theme_get_type"); 
  403.    pragma Import (C, Icon_Info_Get_Type, "gtk_icon_info_get_type"); 
  404. end Gtk.Icon_Theme; 
  405.  
  406. --  Binding will be provided later: 
  407. --  No binding: gtk_icon_theme_error_quark 
  408. --  No binding: gtk_icon_theme_get_for_screen 
  409. --  No binding: gtk_icon_theme_set_screen