path: root/libs/gtkmm2/gtk/gtkmm/toolitem.h

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

#include <glibmm.h>

/* $Id$ */

/* box.h
 * 
 * Copyright (C) 1998-2002 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gtkmm/bin.h>
#include <gtkmm/tooltips.h>


#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _GtkToolItem GtkToolItem;
typedef struct _GtkToolItemClass GtkToolItemClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */


namespace Gtk
{ class ToolItem_Class; } // namespace Gtk
namespace Gtk
{

/** 
 *
 * @ingroup Widgets
 */

class ToolItem : public Bin
{
  public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
  typedef ToolItem CppObjectType;
  typedef ToolItem_Class CppClassType;
  typedef GtkToolItem BaseObjectType;
  typedef GtkToolItemClass BaseClassType;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */

  virtual ~ToolItem();

#ifndef DOXYGEN_SHOULD_SKIP_THIS

private:
  friend class ToolItem_Class;
  static CppClassType toolitem_class_;

  // noncopyable
  ToolItem(const ToolItem&);
  ToolItem& operator=(const ToolItem&);

protected:
  explicit ToolItem(const Glib::ConstructParams& construct_params);
  explicit ToolItem(GtkToolItem* castitem);

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

public:
#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 GtkObject.
  GtkToolItem*       gobj()       { return reinterpret_cast<GtkToolItem*>(gobject_); }

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


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

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

  //Default Signal Handlers::
  virtual bool on_create_menu_proxy();
  virtual void on_toolbar_reconfigured();


private:

public:
  ToolItem();

  
  /** Sets whether @a tool_item  is to be allocated the same size as other
   * homogeneous items. The effect is that all homogeneous items will have
   * the same width as the widest of the items.
   * 
   * Since: 2.4
   * @param homogeneous Whether @a tool_item  is the same size as other homogeneous items.
   */
  void set_homogeneous(bool homogeneous = true);
  
  /** Returns whether @a tool_item  is the same size as other homogeneous
   * items. See set_homogeneous().
   * @return <tt>true</tt> if the item is the same size as other homogeneous
   * item.s
   * 
   * Since: 2.4.
   */
  bool get_homogeneous() const;

  
  /** Sets whether @a tool_item  is allocated extra space when there
   * is more room on the toolbar then needed for the items. The
   * effect is that the item gets bigger when the toolbar gets bigger
   * and smaller when the toolbar gets smaller.
   * 
   * Since: 2.4
   * @param expand Whether @a tool_item  is allocated extra space.
   */
  void set_expand(bool expand = true);
  
  /** Returns whether @a tool_item  is allocated extra space.
   * See set_expand().
   * @return <tt>true</tt> if @a tool_item  is allocated extra space.
   * 
   * Since: 2.4.
   */
  bool get_expand() const;

  
  /** Sets the Gtk::Tooltips object to be used for @a tool_item , the
   * text to be displayed as tooltip on the item and the private text
   * to be used. See Gtk::Tooltips::set_tip().
   * 
   * Since: 2.4
   * @param tooltips The Gtk::Tooltips object to be used.
   * @param tip_text Text to be used as tooltip text for @a tool_item .
   * @param tip_private Text to be used as private tooltip text.
   */
  void set_tooltip(Tooltips& tooltips, const Glib::ustring& tip_text, const Glib::ustring& tip_private = Glib::ustring());
  
  
  /** Sets whether @a toolitem  has a drag window. When <tt>true</tt> the
   * toolitem can be used as a drag source through gtk_drag_source_set().
   * When @a toolitem  has a drag window it will intercept all events,
   * even those that would otherwise be sent to a child of @a toolitem .
   * 
   * Since: 2.4
   * @param use_drag_window Whether @a toolitem  has a drag window.
   */
  void set_use_drag_window(bool use_drag_window = true);
  
  /** Returns whether @a toolitem  has a drag window. See
   * set_use_drag_window().
   * @return <tt>true</tt> if @a toolitem  uses a drag window.
   * 
   * Since: 2.4.
   */
  bool get_use_drag_window() const;

  
  /** Sets whether @a toolitem  is visible when the toolbar is docked horizontally.
   * 
   * Since: 2.4
   * @param visible_horizontal Whether @a toolitem  is visible when in horizontal mode.
   */
  void set_visible_horizontal(bool visible_horizontal = true);
  
  /** Returns whether the @a toolitem  is visible on toolbars that are
   * docked horizontally.
   * @return <tt>true</tt> if @a toolitem  is visible on toolbars that are
   * docked horizontally.
   * 
   * Since: 2.4.
   */
  bool get_visible_horizontal() const;

  
  /** Sets whether @a toolitem  is visible when the toolbar is docked
   * vertically. Some tool items, such as text entries, are too wide to be
   * useful on a vertically docked toolbar. If @a visible_vertical  is <tt>false</tt>
   *  @a toolitem  will not appear on toolbars that are docked vertically.
   * 
   * Since: 2.4
   * @param visible_vertical Whether @a toolitem  is visible when the toolbar
   * is in vertical mode.
   */
  void set_visible_vertical(bool visible_vertical = true);
  
  /** Returns whether @a toolitem  is visible when the toolbar is docked vertically.
   * See set_visible_vertical().
   * @return Whether @a toolitem  is visible when the toolbar is docked vertically
   * 
   * Since: 2.4.
   */
  bool get_visible_vertical() const;

  
  /** Returns whether @a tool_item  is considered important. See
   * set_is_important()
   * @return <tt>true</tt> if @a tool_item  is considered important.
   * 
   * Since: 2.4.
   */
  bool get_is_important() const;
  
  /** Sets whether @a tool_item  should be considered important. The Gtk::ToolButton
   * class uses this property to determine whether to show or hide its label
   * when the toolbar style is Gtk::TOOLBAR_BOTH_HORIZ. The result is that
   * only tool buttons with the "is_important" property set have labels, an
   * effect known as "priority text"
   * 
   * Since: 2.4
   * @param is_important Whether the tool item should be considered important.
   */
  void set_is_important(bool is_important = true);

  
  /** Returns the icon size used for @a tool_item . Custom subclasses of
   * Gtk::ToolItem should call this function to find out what size icons
   * they should use.
   * @return A Gtk::IconSize indicating the icon size used for @a tool_item 
   * 
   * Since: 2.4.
   */
  IconSize get_icon_size () const;
  
  /** Returns the orientation used for @a tool_item . Custom subclasses of
   * Gtk::ToolItem should call this function to find out what size icons
   * they should use.
   * @return A Gtk::Orientation indicating the orientation
   * used for @a tool_item 
   * 
   * Since: 2.4.
   */
  Orientation get_orientation() const;
  
  /** Returns the toolbar style used for @a tool_item . Custom subclasses of
   * Gtk::ToolItem should call this function in the handler of the
   * GtkToolItem::toolbar_reconfigured signal to find out in what style
   * the toolbar is displayed and change themselves accordingly 
   * 
   * Possibilities are:
   * &lt;itemizedlist&gt;
   * &lt;listitem&gt; GTK_TOOLBAR_BOTH, meaning the tool item should show
   * both an icon and a label, stacked vertically &lt;/listitem&gt;
   * &lt;listitem&gt; GTK_TOOLBAR_ICONS, meaning the toolbar shows
   * only icons &lt;/listitem&gt;
   * &lt;listitem&gt; GTK_TOOLBAR_TEXT, meaning the tool item should only
   * show text&lt;/listitem&gt;
   * &lt;listitem&gt; GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
   * both an icon and a label, arranged horizontally (however, note the 
   * Gtk::ToolButton::has_text_horizontally that makes tool buttons not
   * show labels when the toolbar style is GTK_TOOLBAR_BOTH_HORIZ.
   * &lt;/listitem&gt;
   * &lt;/itemizedlist&gt;
   * @return A Gtk::ToolbarStyle indicating the toolbar style used
   * for @a tool_item .
   * 
   * Since: 2.4.
   */
  ToolbarStyle get_toolbar_style() const;
  
  /** Returns the relief style of @a tool_item . See gtk_button_set_relief_style().
   * Custom subclasses of Gtk::ToolItem should call this function in the handler
   * of the Gtk::ToolItem::toolbar_reconfigured signal to find out the
   * relief style of buttons.
   * @return A Gtk::ReliefStyle indicating the relief style used
   * for @a tool_item .
   * 
   * Since: 2.4.
   */
  ReliefStyle get_relief_style() const;

  
  /** Returns the Gtk::MenuItem that was last set by
   * set_proxy_menu_item(), ie. the Gtk::MenuItem
   * that is going to appear in the overflow menu.
   * @return The Gtk::MenuItem that is going to appear in the
   * overflow menu for @a tool_item .
   * 
   * Since: 2.4.
   */
  Widget* retrieve_proxy_menu_item();
  
  /** Returns the Gtk::MenuItem that was last set by
   * set_proxy_menu_item(), ie. the Gtk::MenuItem
   * that is going to appear in the overflow menu.
   * @return The Gtk::MenuItem that is going to appear in the
   * overflow menu for @a tool_item .
   * 
   * Since: 2.4.
   */
  const Widget* retrieve_proxy_menu_item() const;
  
  /** If @a menu_item_id  matches the string passed to
   * set_proxy_menu_item() return the corresponding Gtk::MenuItem.
   * 
   * Custom subclasses of Gtk::ToolItem should use this function to update
   * their menu item when the Gtk::ToolItem changes. That the
   *  @a menu_item_id &lt;!-- --&gt;s must match ensures that a Gtk::ToolItem will not
   * inadvertently change a menu item that they did not create.
   * @param menu_item_id A string used to identify the menu item.
   * @return The Gtk::MenuItem passed to
   * set_proxy_menu_item(), if the @a menu_item_id &lt;!-- --&gt;s match.
   * 
   * Since: 2.4.
   */
  Widget* get_proxy_menu_item(const Glib::ustring& menu_item_id);
  
  /** If @a menu_item_id  matches the string passed to
   * set_proxy_menu_item() return the corresponding Gtk::MenuItem.
   * 
   * Custom subclasses of Gtk::ToolItem should use this function to update
   * their menu item when the Gtk::ToolItem changes. That the
   *  @a menu_item_id &lt;!-- --&gt;s must match ensures that a Gtk::ToolItem will not
   * inadvertently change a menu item that they did not create.
   * @param menu_item_id A string used to identify the menu item.
   * @return The Gtk::MenuItem passed to
   * set_proxy_menu_item(), if the @a menu_item_id &lt;!-- --&gt;s match.
   * 
   * Since: 2.4.
   */
  const Widget* get_proxy_menu_item(const Glib::ustring& menu_item_id) const;
  
  /** Sets the Gtk::MenuItem used in the toolbar overflow menu. The
   *  @a menu_item_id  is used to identify the caller of this function and
   * should also be used with get_proxy_menu_item().
   * 
   * Since: 2.4
   * @param menu_item_id A string used to identify @a menu_item .
   * @param menu_item A Gtk::MenuItem to be used in the overflow menu.
   */
  void set_proxy_menu_item(const Glib::ustring& menu_item_id, Widget& menu_item);

  
  /** Calling this function signals to the toolbar that the
   * overflow menu item for @a tool_item  has changed. If the
   * overflow menu is visible when this function it called,
   * the menu will be rebuilt.
   * 
   * The function must be called when the tool item
   * changes what it will do in response to the "create_menu_proxy"
   * signal.
   * 
   * Since: 2.6
   */
  void rebuild_menu();
  
  
  Glib::SignalProxy0< bool > signal_create_menu_proxy();

  
  Glib::SignalProxy0< void > signal_toolbar_reconfigured();


  //We use no_default_handler for this, because we can not add a new vfunc to 2.5 without breaking ABI.
  //TODO: Remove no_default_handler when we do an ABI-break-with-parallel-install.
  

  Glib::SignalProxy3< bool,Tooltips*,const Glib::ustring&,const Glib::ustring& > signal_set_tooltip();

  
  /** Whether the toolbar item is visible when the toolbar is in a horizontal orientation.
   *
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
   * the value of the property changes.
   */
  Glib::PropertyProxy<bool> property_visible_horizontal() ;

/** Whether the toolbar item is visible when the toolbar is in a horizontal orientation.
   *
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
   * the value of the property changes.
   */
  Glib::PropertyProxy_ReadOnly<bool> property_visible_horizontal() const;

  /** Whether the toolbar item is visible when the toolbar is in a vertical orientation.
   *
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
   * the value of the property changes.
   */
  Glib::PropertyProxy<bool> property_visible_vertical() ;

/** Whether the toolbar item is visible when the toolbar is in a vertical orientation.
   *
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
   * the value of the property changes.
   */
  Glib::PropertyProxy_ReadOnly<bool> property_visible_vertical() const;

  /** Whether the toolbar item is considered important. When TRUE
   *
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
   * the value of the property changes.
   */
  Glib::PropertyProxy<bool> property_is_important() ;

/** Whether the toolbar item is considered important. When TRUE
   *
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
   * the value of the property changes.
   */
  Glib::PropertyProxy_ReadOnly<bool> property_is_important() const;


};

} // namespace Gtk


namespace Glib
{
  /** @relates Gtk::ToolItem
   * @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.
   */
  Gtk::ToolItem* wrap(GtkToolItem* object, bool take_copy = false);
}
#endif /* _GTKMM_TOOLITEM_H */