libgtkmm-2.4-dev 1:2.24.4-1.1 / usr / include / gtkmm-2.4 / gtkmm / tooltip.h

// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _GTKMM_TOOLTIP_H
#define _GTKMM_TOOLTIP_H


#include <glibmm.h>

/* Copyright (C) 2007 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <glibmm/object.h>
#include <giomm/icon.h>
#include <gdkmm/pixbuf.h>
#include <gtkmm/enums.h>
#include <gtkmm/widget.h>


#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _GtkTooltip GtkTooltip;
typedef struct _GtkTooltipClass GtkTooltipClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */


namespace Gtk
{ class Tooltip_Class; } // namespace Gtk
namespace Gtk
{

/** Add tips to your widgets
 *
 * Gtk::Tooltip belongs to the new tooltips API that was introduced in GTK+ 2.12
 * and which deprecates the old Gtk::Tooltips API.
 *
 * Basic tooltips can be realized simply by using set_tooltip_text()
 * or set_tooltip_markup() without any explicit tooltip object.
 *
 * When you need a tooltip with a little more fancy contents, like
 * adding an image, or you want the tooltip to have different contents
 * per Gtk::TreeView row or cell, you will have to do a little more work:
 *
 * - Call Gtk::Widget:set_has_tooltip(); this will
 * make GTK+ monitor the widget for motion and related events
 * which are needed to determine when and where to show a tooltip.
 *
 * - Connect to Gtk::Widget::signal_query_tooltip(). This signal
 * will be emitted when a tooltip is supposed to be shown. One
 * of the arguments passed to the signal handler is a Gtk::Tooltip
 * object. This is the object that we are about to display as a
 * tooltip, and can be manipulated in your callback using functions
 * like Gtk::Tooltip::set_icon(). There are functions for setting
 * the tooltip's markup, setting an image from a stock icon, or
 * even putting in a custom widget.
 *
 * - Return true from your query-tooltip handler. This causes
 * the tooltip to be show. If you return false, it will not be shown.
 *
 * In the probably rare case where you want to have even more control
 * over the tooltip that is about to be shown, you can set your own
 * Window which will be used as tooltip window. This works as follows:
 *
 * - Do Gtk::Widget::set_has_tooltip() and connect to
 * Gtk::Widget::signal_query_tooltip() as before.
 *
 * - Use Gtk::Widget::set_tooltip_window() to set a Gtk::Window created
 * by you as tooltip window.
 *
 * - In the query-tooltip callback you can access your window
 * using Gtk::Widget::get_tooltip_window() and manipulate it as you
 * wish. The semantics of the return value are exactly as before,
 * return true to show the window, false to not show it.
 *
 * @newin{2,12}
 */

class Tooltip : public Glib::Object
{
protected:
  
#ifndef DOXYGEN_SHOULD_SKIP_THIS

public:
  typedef Tooltip CppObjectType;
  typedef Tooltip_Class CppClassType;
  typedef GtkTooltip BaseObjectType;
  typedef GtkTooltipClass BaseClassType;

private:  friend class Tooltip_Class;
  static CppClassType tooltip_class_;

private:
  // noncopyable
  Tooltip(const Tooltip&);
  Tooltip& operator=(const Tooltip&);

protected:
  explicit Tooltip(const Glib::ConstructParams& construct_params);
  explicit Tooltip(GtkTooltip* castitem);

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

public:
  virtual ~Tooltip();

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  static GType get_type()      G_GNUC_CONST;


  static GType get_base_type() G_GNUC_CONST;
#endif

  ///Provides access to the underlying C GObject.
  GtkTooltip*       gobj()       { return reinterpret_cast<GtkTooltip*>(gobject_); }

  ///Provides access to the underlying C GObject.
  const GtkTooltip* gobj() const { return reinterpret_cast<GtkTooltip*>(gobject_); }

  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  GtkTooltip* gobj_copy();

private:


public:
  
  /** Sets the text of the tooltip to be @a markup, which is marked up
   * with the .
   * If @a markup is <tt>0</tt>, the label will be hidden.
   * 
   * @newin{2,12}
   * @param markup A markup string (see ) or <tt>0</tt>.
   */
  void set_markup(const Glib::ustring& markup);
  
  /** Sets the text of the tooltip to be @a text. If @a text is <tt>0</tt>, the label
   * will be hidden. See also set_markup().
   * 
   * @newin{2,12}
   * @param text A text string or <tt>0</tt>.
   */
  void set_text(const Glib::ustring& markup);
  
  /** Sets the icon of the tooltip (which is in front of the text) to be
   *  @a pixbuf.  If @a pixbuf is <tt>0</tt>, the image will be hidden.
   * 
   * @newin{2,12}
   * @param pixbuf A Gdk::Pixbuf, or <tt>0</tt>.
   */
  void set_icon(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
  
  /** Sets the icon of the tooltip (which is in front of the text)
   * to be the icon indicated by @a gicon with the size indicated
   * by @a size. If @a gicon is <tt>0</tt>, the image will be hidden.
   * 
   * @newin{2,20}
   * @param gicon A Icon representing the icon, or <tt>0</tt>.
   * @param size A stock icon size.
   */
  void set_icon(const Glib::RefPtr<Gio::Icon>& icon, IconSize size);

  //TODO: Remove the _from_*() suffixes?
  
  /** Sets the icon of the tooltip (which is in front of the text) to be
   * the stock item indicated by @a stock_id with the size indicated
   * by @a size.  If @a stock_id is <tt>0</tt>, the image will be hidden.
   * 
   * @newin{2,12}
   * @param stock_id A stock id, or <tt>0</tt>.
   * @param size A stock icon size.
   */
  void set_icon_from_stock(const StockID& stock_id, IconSize size);
  
  /** Sets the icon of the tooltip (which is in front of the text) to be
   * the icon indicated by @a icon_name with the size indicated
   * by @a size.  If @a icon_name is <tt>0</tt>, the image will be hidden.
   * 
   * @newin{2,14}
   * @param icon_name An icon name, or <tt>0</tt>.
   * @param size A stock icon size.
   */
  void set_icon_from_icon_name(const Glib::ustring& icon_name, IconSize size);


  /** Replaces the widget packed into the tooltip with
   *  @a custom_widget. @a custom_widget does not get destroyed when the tooltip goes
   * away.
   * By default a box with a Gtk::Image and Gtk::Label is embedded in 
   * the tooltip, which can be configured using set_markup() 
   * and set_icon().
   * 
   * 
   * @newin{2,12}
   * @param custom_widget A Gtk::Widget, or <tt>0</tt> to unset the old custom widget.
   */
  void set_custom(Widget& custom_widget);
  
  /** Sets the area of the widget, where the contents of this tooltip apply,
   * to be @a rect (in widget coordinates).  This is especially useful for
   * properly setting tooltips on Gtk::TreeView rows and cells, Gtk::IconViews,
   * etc.
   * 
   * For setting tooltips on Gtk::TreeView, please refer to the convenience
   * functions for this: Gtk::TreeView::set_tooltip_row() and
   * Gtk::TreeView::set_tooltip_cell().
   * 
   * @newin{2,12}
   * @param rect A Gdk::Rectangle.
   */
  void set_tip_area(const Gdk::Rectangle& rect);

  
  static void trigger_tooltip_query(const Glib::RefPtr<Gdk::Display>& display);


public:

public:
  //C++ methods used to invoke GTK+ virtual functions:

protected:
  //GTK+ Virtual Functions (override these to change behaviour):

  //Default Signal Handlers::


};

} // namespace Gtk


namespace Glib
{
  /** A Glib::wrap() method for this object.
   * 
   * @param object The C instance.
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
   * @result A C++ instance that wraps this C instance.
   *
   * @relates Gtk::Tooltip
   */
  Glib::RefPtr<Gtk::Tooltip> wrap(GtkTooltip* object, bool take_copy = false);
}


#endif /* _GTKMM_TOOLTIP_H */