libs/gtkmm2/gtk/src/tooltip.hg

   1 /* Copyright (C) 2007 The gtkmm Development Team
   2  *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Library General Public
   5  * License as published by the Free Software Foundation; either
   6  * version 2 of the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Library General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Library General Public
  14  * License along with this library; if not, write to the Free
  15  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16  */
  17
  18 #include <glibmm/object.h>
  19 #include <gdkmm/pixbuf.h>
  20 #include <gtkmm/enums.h>
  21 #include <gtkmm/widget.h>
  22
  23 _DEFS(gtkmm,gtk)
  24 _PINCLUDE(glibmm/private/object_p.h)
  25
  26 namespace Gtk
  27 {
  28
  29 /** Add tips to your widgets
  30  *
  31  * Gtk::Tooltip belongs to the new tooltips API that was introduced in GTK+ 2.12
  32  * and which deprecates the old Gtk::Tooltips API.
  33  *
  34  * Basic tooltips can be realized simply by using set_tooltip_text()
  35  * or set_tooltip_markup() without any explicit tooltip object.
  36  *
  37  * When you need a tooltip with a little more fancy contents, like
  38  * adding an image, or you want the tooltip to have different contents
  39  * per Gtk::TreeView row or cell, you will have to do a little more work:
  40  *
  41  * - Call Gtk::Widget:set_has_tooltip(); this will
  42  * make GTK+ monitor the widget for motion and related events
  43  * which are needed to determine when and where to show a tooltip.
  44  *
  45  * - Connect to Gtk::Widget::signal_query_tooltip(). This signal
  46  * will be emitted when a tooltip is supposed to be shown. One
  47  * of the arguments passed to the signal handler is a Gtk::Tooltip
  48  * object. This is the object that we are about to display as a
  49  * tooltip, and can be manipulated in your callback using functions
  50  * like Gtk::Tooltip::set_icon(). There are functions for setting
  51  * the tooltip's markup, setting an image from a stock icon, or
  52  * even putting in a custom widget.
  53  *
  54  * - Return true from your query-tooltip handler. This causes
  55  * the tooltip to be show. If you return false, it will not be shown.
  56  *
  57  * In the probably rare case where you want to have even more control
  58  * over the tooltip that is about to be shown, you can set your own
  59  * Window which will be used as tooltip window. This works as follows:
  60  *
  61  * - Do Gtk::Widget::set_has_tooltip() and connect to
  62  * Gtk::Widget::signal_query_tooltip() as before.
  63  *
  64  * - Use Gtk::Widget::set_tooltip_window() to set a Gtk::Window created
  65  * by you as tooltip window.
  66  *
  67  * - In the query-tooltip callback you can access your window
  68  * using Gtk::Widget::get_tooltip_window() and manipulate it as you
  69  * wish. The semantics of the return value are exactly as before,
  70  * return true to show the window, false to not show it.
  71  *
  72  * @newin2p12
  73  */
  74 class Tooltip : public Glib::Object
  75 {
  76 protected:
  77   _CLASS_GOBJECT(Tooltip, GtkTooltip, GTK_TOOLTIP, Glib::Object, GObject)
  78
  79 public:
  80
  81   _WRAP_METHOD(void set_markup(const Glib::ustring& markup), gtk_tooltip_set_markup)
  82   _WRAP_METHOD(void set_text(const Glib::ustring& markup), gtk_tooltip_set_text)
  83   _WRAP_METHOD(void set_icon(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf), gtk_tooltip_set_icon)
  84   _WRAP_METHOD(void set_icon_from_stock(const StockID& stock_id, IconSize size), gtk_tooltip_set_icon_from_stock)
  85   _WRAP_METHOD(void set_custom(Widget& custom_widget), gtk_tooltip_set_custom)
  86   _WRAP_METHOD(void set_tip_area(const Gdk::Rectangle& rect), gtk_tooltip_set_tip_area)
  87
  88   _IGNORE(gtk_tooltip_trigger_tooltip_query)
  89   static void trigger_tooltip_query(const Glib::RefPtr<Gdk::Display>& display);
  90 };
  91
  92 } // namespace Gtk