libs/gtkmm2/gtk/gtkmm/tooltip.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_TOOLTIP_H
   4 #define _GTKMM_TOOLTIP_H
   5
   6
   7 #include <glibmm.h>
   8
   9 /* Copyright (C) 2007 The gtkmm Development Team
  10  *
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Library General Public
  13  * License as published by the Free Software Foundation; either
  14  * version 2 of the License, or (at your option) any later version.
  15  *
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Library General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Library General Public
  22  * License along with this library; if not, write to the Free
  23  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24  */
  25
  26 #include <glibmm/object.h>
  27 #include <gdkmm/pixbuf.h>
  28 #include <gtkmm/enums.h>
  29 #include <gtkmm/widget.h>
  30
  31
  32 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  33 typedef struct _GtkTooltip GtkTooltip;
  34 typedef struct _GtkTooltipClass GtkTooltipClass;
  35 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  36
  37
  38 namespace Gtk
  39 { class Tooltip_Class; } // namespace Gtk
  40 namespace Gtk
  41 {
  42
  43 /** Add tips to your widgets
  44  *
  45  * Gtk::Tooltip belongs to the new tooltips API that was introduced in GTK+ 2.12
  46  * and which deprecates the old Gtk::Tooltips API.
  47  *
  48  * Basic tooltips can be realized simply by using set_tooltip_text()
  49  * or set_tooltip_markup() without any explicit tooltip object.
  50  *
  51  * When you need a tooltip with a little more fancy contents, like
  52  * adding an image, or you want the tooltip to have different contents
  53  * per Gtk::TreeView row or cell, you will have to do a little more work:
  54  *
  55  * - Call Gtk::Widget:set_has_tooltip(); this will
  56  * make GTK+ monitor the widget for motion and related events
  57  * which are needed to determine when and where to show a tooltip.
  58  *
  59  * - Connect to Gtk::Widget::signal_query_tooltip(). This signal
  60  * will be emitted when a tooltip is supposed to be shown. One
  61  * of the arguments passed to the signal handler is a Gtk::Tooltip
  62  * object. This is the object that we are about to display as a
  63  * tooltip, and can be manipulated in your callback using functions
  64  * like Gtk::Tooltip::set_icon(). There are functions for setting
  65  * the tooltip's markup, setting an image from a stock icon, or
  66  * even putting in a custom widget.
  67  *
  68  * - Return true from your query-tooltip handler. This causes
  69  * the tooltip to be show. If you return false, it will not be shown.
  70  *
  71  * In the probably rare case where you want to have even more control
  72  * over the tooltip that is about to be shown, you can set your own
  73  * Window which will be used as tooltip window. This works as follows:
  74  *
  75  * - Do Gtk::Widget::set_has_tooltip() and connect to
  76  * Gtk::Widget::signal_query_tooltip() as before.
  77  *
  78  * - Use Gtk::Widget::set_tooltip_window() to set a Gtk::Window created
  79  * by you as tooltip window.
  80  *
  81  * - In the query-tooltip callback you can access your window
  82  * using Gtk::Widget::get_tooltip_window() and manipulate it as you
  83  * wish. The semantics of the return value are exactly as before,
  84  * return true to show the window, false to not show it.
  85  *
  86  * @newin2p12
  87  */
  88
  89 class Tooltip : public Glib::Object
  90 {
  91 protected:
  92
  93 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  94
  95 public:
  96   typedef Tooltip CppObjectType;
  97   typedef Tooltip_Class CppClassType;
  98   typedef GtkTooltip BaseObjectType;
  99   typedef GtkTooltipClass BaseClassType;
 100
 101 private:  friend class Tooltip_Class;
 102   static CppClassType tooltip_class_;
 103
 104 private:
 105   // noncopyable
 106   Tooltip(const Tooltip&);
 107   Tooltip& operator=(const Tooltip&);
 108
 109 protected:
 110   explicit Tooltip(const Glib::ConstructParams& construct_params);
 111   explicit Tooltip(GtkTooltip* castitem);
 112
 113 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 114
 115 public:
 116   virtual ~Tooltip();
 117
 118 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 119   static GType get_type()      G_GNUC_CONST;
 120   static GType get_base_type() G_GNUC_CONST;
 121 #endif
 122
 123   ///Provides access to the underlying C GObject.
 124   GtkTooltip*       gobj()       { return reinterpret_cast<GtkTooltip*>(gobject_); }
 125
 126   ///Provides access to the underlying C GObject.
 127   const GtkTooltip* gobj() const { return reinterpret_cast<GtkTooltip*>(gobject_); }
 128
 129   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 130   GtkTooltip* gobj_copy();
 131
 132 private:
 133
 134
 135 public:
 136
 137
 138   /** Sets the text of the tooltip to be @a markup , which is marked up
 139    * with the Pango text markup language.
 140    * If @a markup  is <tt>0</tt>, the label will be hidden.
 141    *
 142    * @newin2p12
 143    * @param markup A markup string (see Pango markup format) or <tt>0</tt>.
 144    */
 145   void set_markup(const Glib::ustring& markup);
 146
 147   /** Sets the text of the tooltip to be @a text . If @a text  is <tt>0</tt>, the label
 148    * will be hidden. See also gtk_tooltip_set_markup().
 149    *
 150    * @newin2p12
 151    * @param text A text string or <tt>0</tt>.
 152    */
 153   void set_text(const Glib::ustring& markup);
 154
 155   /** Sets the icon of the tooltip (which is in front of the text) to be
 156    *  @a pixbuf .  If @a pixbuf  is <tt>0</tt>, the image will be hidden.
 157    *
 158    * @newin2p12
 159    * @param pixbuf A Gdk::Pixbuf, or <tt>0</tt>.
 160    */
 161   void set_icon(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
 162
 163   /** Sets the icon of the tooltip (which is in front of the text) to be
 164    * the stock item indicated by @a stock_id  with the size indicated
 165    * by @a size .  If @a stock_id  is <tt>0</tt>, the image will be hidden.
 166    *
 167    * @newin2p12
 168    * @param stock_id A stock icon name, or <tt>0</tt>.
 169    * @param size A stock icon size.
 170    */
 171   void set_icon_from_stock(const StockID& stock_id, IconSize size);
 172
 173   /** Replaces the widget packed into the tooltip with @a custom_widget .
 174    * By default a box with a Gtk::Image and Gtk::Label is embedded in
 175    * the tooltip, which can be configured using gtk_tooltip_set_markup()
 176    * and gtk_tooltip_set_icon().
 177    *
 178    * @newin2p12
 179    * @param custom_widget A Gtk::Widget.
 180    */
 181   void set_custom(Widget& custom_widget);
 182
 183   /** Sets the area of the widget, where the contents of this tooltip apply,
 184    * to be @a rect  (in widget coordinates).  This is especially useful for
 185    * properly setting tooltips on Gtk::TreeView rows and cells, Gtk::IconViews,
 186    * etc.
 187    *
 188    * For setting tooltips on Gtk::TreeView, please refer to the convenience
 189    * functions for this: Gtk::TreeView::set_tooltip_row() and
 190    * Gtk::TreeView::set_tooltip_cell().
 191    *
 192    * @newin2p12
 193    * @param rect A Gdk::Rectangle.
 194    */
 195   void set_tip_area(const Gdk::Rectangle& rect);
 196
 197
 198   static void trigger_tooltip_query(const Glib::RefPtr<Gdk::Display>& display);
 199
 200
 201 public:
 202
 203 public:
 204   //C++ methods used to invoke GTK+ virtual functions:
 205 #ifdef GLIBMM_VFUNCS_ENABLED
 206 #endif //GLIBMM_VFUNCS_ENABLED
 207
 208 protected:
 209   //GTK+ Virtual Functions (override these to change behaviour):
 210 #ifdef GLIBMM_VFUNCS_ENABLED
 211 #endif //GLIBMM_VFUNCS_ENABLED
 212
 213   //Default Signal Handlers::
 214 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 215 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 216
 217
 218 };
 219
 220 } // namespace Gtk
 221
 222
 223 namespace Glib
 224 {
 225   /** A Glib::wrap() method for this object.
 226    *
 227    * @param object The C instance.
 228    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 229    * @result A C++ instance that wraps this C instance.
 230    *
 231    * @relates Gtk::Tooltip
 232    */
 233   Glib::RefPtr<Gtk::Tooltip> wrap(GtkTooltip* object, bool take_copy = false);
 234 }
 235
 236
 237 #endif /* _GTKMM_TOOLTIP_H */
 238