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. --  <description> 
  25. --  Basic tooltips can be realized simply by using Gtk.Widget.Set_Tooltip_Text 
  26. --  or Gtk.Widget.Set_Tooltip_Markup without any explicit tooltip object. 
  27. -- 
  28. --  When you need a tooltip with a little more fancy contents, like adding an 
  29. --  image, or you want the tooltip to have different contents per 
  30. --  Gtk.Tree_View.Gtk_Tree_View row or cell, you will have to do a little more 
  31. --  work: 
  32. -- 
  33. --     * Set the Gtk.Widget.Gtk_Widget:has-tooltip property to True, this will 
  34. --  make GTK+ monitor the widget for motion and related events which are needed 
  35. --  to determine when and where to show a tooltip. 
  36. -- 
  37. --     * Connect to the Gtk.Widget.Gtk_Widget::query-tooltip signal. This 
  38. --  signal will be emitted when a tooltip is supposed to be shown. One of the 
  39. --  arguments passed to the signal handler is a GtkTooltip object. This is the 
  40. --  object that we are about to display as a tooltip, and can be manipulated in 
  41. --  your callback using functions like Gtk.Tooltip.Set_Icon. There are 
  42. --  functions for setting the tooltip's markup, setting an image from a stock 
  43. --  icon, or even putting in a custom widget. 
  44. -- 
  45. --     * Return True from your query-tooltip handler. This causes the tooltip 
  46. --  to be show. If you return False, it will not be shown. 
  47. -- 
  48. --  In the probably rare case where you want to have even more control over 
  49. --  the tooltip that is about to be shown, you can set your own 
  50. --  Gtk.Window.Gtk_Window which will be used as tooltip window. This works as 
  51. --  follows: 
  52. -- 
  53. --     * Set Gtk.Widget.Gtk_Widget:has-tooltip and connect to 
  54. --  Gtk.Widget.Gtk_Widget::query-tooltip as before. 
  55. -- 
  56. --     * Use Gtk.Widget.Set_Tooltip_Window to set a Gtk.Window.Gtk_Window 
  57. --  created by you as tooltip window. 
  58. -- 
  59. --     * In the Gtk.Widget.Gtk_Widget::query-tooltip callback you can access 
  60. --  your window using Gtk.Widget.Get_Tooltip_Window and manipulate as you wish. 
  61. --  The semantics of the return value are exactly as before, return True to 
  62. --  show the window, False to not show it. 
  63. -- 
  64. -- 
  65. --  </description> 
  66. pragma Ada_2005; 
  67.  
  68. pragma Warnings (Off, "*is already use-visible*"); 
  69. with Gdk.Display;   use Gdk.Display; 
  70. with Gdk.Pixbuf;    use Gdk.Pixbuf; 
  71. with Gdk.Rectangle; use Gdk.Rectangle; 
  72. with Glib;          use Glib; 
  73. with Glib.G_Icon;   use Glib.G_Icon; 
  74. with Glib.Object;   use Glib.Object; 
  75. with Gtk.Enums;     use Gtk.Enums; 
  76. with Gtk.Widget;    use Gtk.Widget; 
  77.  
  78. package Gtk.Tooltip is 
  79.  
  80.    type Gtk_Tooltip_Record is new GObject_Record with null record; 
  81.    type Gtk_Tooltip is access all Gtk_Tooltip_Record'Class; 
  82.  
  83.    ------------------ 
  84.    -- Constructors -- 
  85.    ------------------ 
  86.  
  87.    function Get_Type return Glib.GType; 
  88.    pragma Import (C, Get_Type, "gtk_tooltip_get_type"); 
  89.  
  90.    ------------- 
  91.    -- Methods -- 
  92.    ------------- 
  93.  
  94.    procedure Set_Custom 
  95.       (Self          : not null access Gtk_Tooltip_Record; 
  96.        Custom_Widget : access Gtk.Widget.Gtk_Widget_Record'Class); 
  97.    --  Replaces the widget packed into the tooltip with Custom_Widget. 
  98.    --  Custom_Widget does not get destroyed when the tooltip goes away. By 
  99.    --  default a box with a Gtk.Image.Gtk_Image and Gtk.Label.Gtk_Label is 
  100.    --  embedded in the tooltip, which can be configured using 
  101.    --  Gtk.Tooltip.Set_Markup and Gtk.Tooltip.Set_Icon. 
  102.    --  Since: gtk+ 2.12 
  103.    --  "custom_widget": a Gtk.Widget.Gtk_Widget, or null to unset the old 
  104.    --  custom widget. 
  105.  
  106.    procedure Set_Icon 
  107.       (Self   : not null access Gtk_Tooltip_Record; 
  108.        Pixbuf : access Gdk.Pixbuf.Gdk_Pixbuf_Record'Class); 
  109.    --  Sets the icon of the tooltip (which is in front of the text) to be 
  110.    --  Pixbuf. If Pixbuf is null, the image will be hidden. 
  111.    --  Since: gtk+ 2.12 
  112.    --  "pixbuf": a Gdk.Pixbuf.Gdk_Pixbuf, or null 
  113.  
  114.    procedure Set_Icon_From_Gicon 
  115.       (Self   : not null access Gtk_Tooltip_Record; 
  116.        G_Icon : Glib.G_Icon.G_Icon; 
  117.        Size   : Gtk.Enums.Gtk_Icon_Size); 
  118.    --  Sets the icon of the tooltip (which is in front of the text) to be the 
  119.    --  icon indicated by Gicon with the size indicated by Size. If Gicon is 
  120.    --  null, the image will be hidden. 
  121.    --  Since: gtk+ 2.20 
  122.    --  "gicon": a Glib.G_Icon.G_Icon representing the icon, or null 
  123.    --  "size": a stock icon size 
  124.  
  125.    procedure Set_Icon_From_Icon_Name 
  126.       (Self      : not null access Gtk_Tooltip_Record; 
  127.        Icon_Name : UTF8_String := ""; 
  128.        Size      : Gtk.Enums.Gtk_Icon_Size); 
  129.    --  Sets the icon of the tooltip (which is in front of the text) to be the 
  130.    --  icon indicated by Icon_Name with the size indicated by Size. If 
  131.    --  Icon_Name is null, the image will be hidden. 
  132.    --  Since: gtk+ 2.14 
  133.    --  "icon_name": an icon name, or null 
  134.    --  "size": a stock icon size 
  135.  
  136.    procedure Set_Icon_From_Stock 
  137.       (Self     : not null access Gtk_Tooltip_Record; 
  138.        Stock_Id : UTF8_String := ""; 
  139.        Size     : Gtk.Enums.Gtk_Icon_Size); 
  140.    --  Sets the icon of the tooltip (which is in front of the text) to be the 
  141.    --  stock item indicated by Stock_Id with the size indicated by Size. If 
  142.    --  Stock_Id is null, the image will be hidden. 
  143.    --  Since: gtk+ 2.12 
  144.    --  "stock_id": a stock id, or null 
  145.    --  "size": a stock icon size 
  146.  
  147.    procedure Set_Markup 
  148.       (Self   : not null access Gtk_Tooltip_Record; 
  149.        Markup : UTF8_String := ""); 
  150.    --  Sets the text of the tooltip to be Markup, which is marked up with the 
  151.    --  <link linkend="PangoMarkupFormat">Pango text markup language</link>. If 
  152.    --  Markup is null, the label will be hidden. 
  153.    --  Since: gtk+ 2.12 
  154.    --  "markup": a markup string (see <link linkend="PangoMarkupFormat">Pango 
  155.    --  markup format</link>) or null 
  156.  
  157.    procedure Set_Text 
  158.       (Self : not null access Gtk_Tooltip_Record; 
  159.        Text : UTF8_String := ""); 
  160.    --  Sets the text of the tooltip to be Text. If Text is null, the label 
  161.    --  will be hidden. See also Gtk.Tooltip.Set_Markup. 
  162.    --  Since: gtk+ 2.12 
  163.    --  "text": a text string or null 
  164.  
  165.    procedure Set_Tip_Area 
  166.       (Self : not null access Gtk_Tooltip_Record; 
  167.        Rect : Gdk.Rectangle.Gdk_Rectangle); 
  168.    --  Sets the area of the widget, where the contents of this tooltip apply, 
  169.    --  to be Rect (in widget coordinates). This is especially useful for 
  170.    --  properly setting tooltips on Gtk.Tree_View.Gtk_Tree_View rows and cells, 
  171.    --  Gtk_Icon_Views, etc. 
  172.    --  For setting tooltips on Gtk.Tree_View.Gtk_Tree_View, please refer to 
  173.    --  the convenience functions for this: Gtk.Tree_View.Set_Tooltip_Row and 
  174.    --  Gtk.Tree_View.Set_Tooltip_Cell. 
  175.    --  Since: gtk+ 2.12 
  176.    --  "rect": a Gdk.Rectangle.Gdk_Rectangle 
  177.  
  178.    --------------- 
  179.    -- Functions -- 
  180.    --------------- 
  181.  
  182.    procedure Trigger_Tooltip_Query 
  183.       (Display : not null access Gdk.Display.Gdk_Display_Record'Class); 
  184.    --  Triggers a new tooltip query on Display, in order to update the current 
  185.    --  visible tooltip, or to show/hide the current tooltip. This function is 
  186.    --  useful to call when, for example, the state of the widget changed by a 
  187.    --  key press. 
  188.    --  Since: gtk+ 2.12 
  189.    --  "display": a Gdk.Display.Gdk_Display 
  190.  
  191. end Gtk.Tooltip;