Pileus Git - ~andy/gtk/blob - gtk/gtktoolitem.c

   1 /* gtktoolitem.c
   2  *
   3  * Copyright (C) 2002 Anders Carlsson <andersca@gnome.org>
   4  * Copyright (C) 2002 James Henstridge <james@daa.com.au>
   5  * Copyright (C) 2003 Soeren Sandmann <sandmann@daimi.au.dk>
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include "config.h"
  24
  25 #include <string.h>
  26
  27 #undef GTK_DISABLE_DEPRECATED /* GtkTooltips */
  28
  29 #include "gtktoolitem.h"
  30 #include "gtkmarshalers.h"
  31 #include "gtktoolshell.h"
  32 #include "gtkseparatormenuitem.h"
  33 #include "gtkintl.h"
  34 #include "gtkmain.h"
  35 #include "gtkprivate.h"
  36 #include "gtkalias.h"
  37
  38 /**
  39  * SECTION:gtktoolitem
  40  * @short_description: The base class of widgets that can be added to #GtkToolShell
  41  *
  42  * #GtkToolItem<!-- -->s are widgets that can appear on a toolbar. To
  43  * create a toolbar item that contain something else than a button, use
  44  * gtk_tool_item_new(). Use gtk_container_add() to add a child
  45  * widget to the tool item.
  46  *
  47  * For toolbar items that contain buttons, see the #GtkToolButton,
  48  * #GtkToggleToolButton and #GtkRadioToolButton classes.
  49  *
  50  * See the #GtkToolbar class for a description of the toolbar widget, and
  51  * #GtkToolShell for a description of the tool shell interface.
  52  */
  53
  54 /**
  55  * GtkToolItem:
  56  *
  57  * The GtkToolItem struct contains only private data.
  58  * It should only be accessed through the functions described below.
  59  */
  60
  61 enum {
  62   CREATE_MENU_PROXY,
  63   TOOLBAR_RECONFIGURED,
  64   SET_TOOLTIP,
  65   LAST_SIGNAL
  66 };
  67
  68 enum {
  69   PROP_0,
  70   PROP_VISIBLE_HORIZONTAL,
  71   PROP_VISIBLE_VERTICAL,
  72   PROP_IS_IMPORTANT
  73 };
  74
  75 #define GTK_TOOL_ITEM_GET_PRIVATE(o)  (G_TYPE_INSTANCE_GET_PRIVATE ((o), GTK_TYPE_TOOL_ITEM, GtkToolItemPrivate))
  76
  77 struct _GtkToolItemPrivate
  78 {
  79   gchar *tip_text;
  80   gchar *tip_private;
  81
  82   guint visible_horizontal : 1;
  83   guint visible_vertical : 1;
  84   guint homogeneous : 1;
  85   guint expand : 1;
  86   guint use_drag_window : 1;
  87   guint is_important : 1;
  88
  89   GdkWindow *drag_window;
  90
  91   gchar *menu_item_id;
  92   GtkWidget *menu_item;
  93 };
  94
  95 static void gtk_tool_item_finalize    (GObject *object);
  96 static void gtk_tool_item_parent_set   (GtkWidget   *toolitem,
  97                                         GtkWidget   *parent);
  98 static void gtk_tool_item_set_property (GObject         *object,
  99                                         guint            prop_id,
 100                                         const GValue    *value,
 101                                         GParamSpec      *pspec);
 102 static void gtk_tool_item_get_property (GObject         *object,
 103                                         guint            prop_id,
 104                                         GValue          *value,
 105                                         GParamSpec      *pspec);
 106 static void gtk_tool_item_property_notify (GObject      *object,
 107                                            GParamSpec   *pspec);
 108 static void gtk_tool_item_realize       (GtkWidget      *widget);
 109 static void gtk_tool_item_unrealize     (GtkWidget      *widget);
 110 static void gtk_tool_item_map           (GtkWidget      *widget);
 111 static void gtk_tool_item_unmap         (GtkWidget      *widget);
 112 static void gtk_tool_item_size_request  (GtkWidget      *widget,
 113                                          GtkRequisition *requisition);
 114 static void gtk_tool_item_size_allocate (GtkWidget      *widget,
 115                                          GtkAllocation  *allocation);
 116 static gboolean gtk_tool_item_real_set_tooltip (GtkToolItem *tool_item,
 117                                                 GtkTooltips *tooltips,
 118                                                 const gchar *tip_text,
 119                                                 const gchar *tip_private);
 120
 121 static gboolean gtk_tool_item_create_menu_proxy (GtkToolItem *item);
 122
 123
 124 static guint toolitem_signals[LAST_SIGNAL] = { 0 };
 125
 126 G_DEFINE_TYPE (GtkToolItem, gtk_tool_item, GTK_TYPE_BIN)
 127
 128 static void
 129 gtk_tool_item_class_init (GtkToolItemClass *klass)
 130 {
 131   GObjectClass *object_class;
 132   GtkWidgetClass *widget_class;
 133
 134   object_class = (GObjectClass *)klass;
 135   widget_class = (GtkWidgetClass *)klass;
 136
 137   object_class->set_property = gtk_tool_item_set_property;
 138   object_class->get_property = gtk_tool_item_get_property;
 139   object_class->finalize = gtk_tool_item_finalize;
 140   object_class->notify = gtk_tool_item_property_notify;
 141
 142   widget_class->realize       = gtk_tool_item_realize;
 143   widget_class->unrealize     = gtk_tool_item_unrealize;
 144   widget_class->map           = gtk_tool_item_map;
 145   widget_class->unmap         = gtk_tool_item_unmap;
 146   widget_class->size_request  = gtk_tool_item_size_request;
 147   widget_class->size_allocate = gtk_tool_item_size_allocate;
 148   widget_class->parent_set    = gtk_tool_item_parent_set;
 149
 150   klass->create_menu_proxy = gtk_tool_item_create_menu_proxy;
 151   klass->set_tooltip       = gtk_tool_item_real_set_tooltip;
 152
 153   g_object_class_install_property (object_class,
 154                                    PROP_VISIBLE_HORIZONTAL,
 155                                    g_param_spec_boolean ("visible-horizontal",
 156                                                          P_("Visible when horizontal"),
 157                                                          P_("Whether the toolbar item is visible when the toolbar is in a horizontal orientation."),
 158                                                          TRUE,
 159                                                          GTK_PARAM_READWRITE));
 160   g_object_class_install_property (object_class,
 161                                    PROP_VISIBLE_VERTICAL,
 162                                    g_param_spec_boolean ("visible-vertical",
 163                                                          P_("Visible when vertical"),
 164                                                          P_("Whether the toolbar item is visible when the toolbar is in a vertical orientation."),
 165                                                          TRUE,
 166                                                          GTK_PARAM_READWRITE));
 167   g_object_class_install_property (object_class,
 168                                    PROP_IS_IMPORTANT,
 169                                    g_param_spec_boolean ("is-important",
 170                                                          P_("Is important"),
 171                                                          P_("Whether the toolbar item is considered important. When TRUE, toolbar buttons show text in GTK_TOOLBAR_BOTH_HORIZ mode"),
 172                                                          FALSE,
 173                                                          GTK_PARAM_READWRITE));
 174
 175 /**
 176  * GtkToolItem::create-menu-proxy:
 177  * @tool_item: the object the signal was emitted on
 178  *
 179  * This signal is emitted when the toolbar needs information from @tool_item
 180  * about whether the item should appear in the toolbar overflow menu. In
 181  * response the tool item should either
 182  * <itemizedlist>
 183  * <listitem>call gtk_tool_item_set_proxy_menu_item() with a %NULL
 184  * pointer and return %TRUE to indicate that the item should not appear
 185  * in the overflow menu
 186  * </listitem>
 187  * <listitem> call gtk_tool_item_set_proxy_menu_item() with a new menu
 188  * item and return %TRUE, or
 189  * </listitem>
 190  * <listitem> return %FALSE to indicate that the signal was not
 191  * handled by the item. This means that
 192  * the item will not appear in the overflow menu unless a later handler
 193  * installs a menu item.
 194  * </listitem>
 195  * </itemizedlist>
 196  *
 197  * The toolbar may cache the result of this signal. When the tool item changes
 198  * how it will respond to this signal it must call gtk_tool_item_rebuild_menu()
 199  * to invalidate the cache and ensure that the toolbar rebuilds its overflow
 200  * menu.
 201  *
 202  * Return value: %TRUE if the signal was handled, %FALSE if not
 203  **/
 204   toolitem_signals[CREATE_MENU_PROXY] =
 205     g_signal_new (I_("create_menu_proxy"),
 206                   G_OBJECT_CLASS_TYPE (klass),
 207                   G_SIGNAL_RUN_LAST,
 208                   G_STRUCT_OFFSET (GtkToolItemClass, create_menu_proxy),
 209                   _gtk_boolean_handled_accumulator, NULL,
 210                   _gtk_marshal_BOOLEAN__VOID,
 211                   G_TYPE_BOOLEAN, 0);
 212
 213 /**
 214  * GtkToolItem::toolbar-reconfigured:
 215  * @tool_item: the object the signal was emitted on
 216  *
 217  * This signal is emitted when some property of the toolbar that the
 218  * item is a child of changes. For custom subclasses of #GtkToolItem,
 219  * the default handler of this signal use the functions
 220  * <itemizedlist>
 221  * <listitem>gtk_tool_shell_get_orientation()</listitem>
 222  * <listitem>gtk_tool_shell_get_style()</listitem>
 223  * <listitem>gtk_tool_shell_get_icon_size()</listitem>
 224  * <listitem>gtk_tool_shell_get_relief_style()</listitem>
 225  * </itemizedlist>
 226  * to find out what the toolbar should look like and change
 227  * themselves accordingly.
 228  **/
 229   toolitem_signals[TOOLBAR_RECONFIGURED] =
 230     g_signal_new (I_("toolbar_reconfigured"),
 231                   G_OBJECT_CLASS_TYPE (klass),
 232                   G_SIGNAL_RUN_LAST,
 233                   G_STRUCT_OFFSET (GtkToolItemClass, toolbar_reconfigured),
 234                   NULL, NULL,
 235                   _gtk_marshal_VOID__VOID,
 236                   G_TYPE_NONE, 0);
 237 /**
 238  * GtkToolItem::set-tooltip:
 239  * @tool_item: the object the signal was emitted on
 240  * @tooltips: the #GtkTooltips
 241  * @tip_text: the tooltip text
 242  * @tip_private: the tooltip private text
 243  *
 244  * This signal is emitted when the toolitem's tooltip changes.
 245  * Application developers can use gtk_tool_item_set_tooltip() to
 246  * set the item's tooltip.
 247  *
 248  * Return value: %TRUE if the signal was handled, %FALSE if not
 249  *
 250  * Deprecated: 2.12: With the new tooltip API, there is no
 251  *   need to use this signal anymore.
 252  **/
 253   toolitem_signals[SET_TOOLTIP] =
 254     g_signal_new (I_("set_tooltip"),
 255                   G_OBJECT_CLASS_TYPE (klass),
 256                   G_SIGNAL_RUN_LAST,
 257                   G_STRUCT_OFFSET (GtkToolItemClass, set_tooltip),
 258                   _gtk_boolean_handled_accumulator, NULL,
 259                   _gtk_marshal_BOOLEAN__OBJECT_STRING_STRING,
 260                   G_TYPE_BOOLEAN, 3,
 261                   GTK_TYPE_TOOLTIPS,
 262                   G_TYPE_STRING,
 263                   G_TYPE_STRING);
 264
 265   g_type_class_add_private (object_class, sizeof (GtkToolItemPrivate));
 266 }
 267
 268 static void
 269 gtk_tool_item_init (GtkToolItem *toolitem)
 270 {
 271   GTK_WIDGET_UNSET_FLAGS (toolitem, GTK_CAN_FOCUS);
 272
 273   toolitem->priv = GTK_TOOL_ITEM_GET_PRIVATE (toolitem);
 274
 275   toolitem->priv->visible_horizontal = TRUE;
 276   toolitem->priv->visible_vertical = TRUE;
 277   toolitem->priv->homogeneous = FALSE;
 278   toolitem->priv->expand = FALSE;
 279 }
 280
 281 static void
 282 gtk_tool_item_finalize (GObject *object)
 283 {
 284   GtkToolItem *item = GTK_TOOL_ITEM (object);
 285
 286   g_free (item->priv->menu_item_id);
 287
 288   if (item->priv->menu_item)
 289     g_object_unref (item->priv->menu_item);
 290
 291   G_OBJECT_CLASS (gtk_tool_item_parent_class)->finalize (object);
 292 }
 293
 294 static void
 295 gtk_tool_item_parent_set (GtkWidget   *toolitem,
 296                           GtkWidget   *prev_parent)
 297 {
 298   if (GTK_WIDGET (toolitem)->parent != NULL)
 299     gtk_tool_item_toolbar_reconfigured (GTK_TOOL_ITEM (toolitem));
 300 }
 301
 302 static void
 303 gtk_tool_item_set_property (GObject      *object,
 304                             guint         prop_id,
 305                             const GValue *value,
 306                             GParamSpec   *pspec)
 307 {
 308   GtkToolItem *toolitem = GTK_TOOL_ITEM (object);
 309
 310   switch (prop_id)
 311     {
 312     case PROP_VISIBLE_HORIZONTAL:
 313       gtk_tool_item_set_visible_horizontal (toolitem, g_value_get_boolean (value));
 314       break;
 315     case PROP_VISIBLE_VERTICAL:
 316       gtk_tool_item_set_visible_vertical (toolitem, g_value_get_boolean (value));
 317       break;
 318     case PROP_IS_IMPORTANT:
 319       gtk_tool_item_set_is_important (toolitem, g_value_get_boolean (value));
 320       break;
 321     default:
 322       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 323       break;
 324     }
 325 }
 326
 327 static void
 328 gtk_tool_item_get_property (GObject    *object,
 329                             guint       prop_id,
 330                             GValue     *value,
 331                             GParamSpec *pspec)
 332 {
 333   GtkToolItem *toolitem = GTK_TOOL_ITEM (object);
 334
 335   switch (prop_id)
 336     {
 337     case PROP_VISIBLE_HORIZONTAL:
 338       g_value_set_boolean (value, toolitem->priv->visible_horizontal);
 339       break;
 340     case PROP_VISIBLE_VERTICAL:
 341       g_value_set_boolean (value, toolitem->priv->visible_vertical);
 342       break;
 343     case PROP_IS_IMPORTANT:
 344       g_value_set_boolean (value, toolitem->priv->is_important);
 345       break;
 346     default:
 347       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 348       break;
 349     }
 350 }
 351
 352 static void
 353 gtk_tool_item_property_notify (GObject    *object,
 354                                GParamSpec *pspec)
 355 {
 356   GtkToolItem *tool_item = GTK_TOOL_ITEM (object);
 357
 358   if (tool_item->priv->menu_item && strcmp (pspec->name, "sensitive") == 0)
 359     gtk_widget_set_sensitive (tool_item->priv->menu_item,
 360                               GTK_WIDGET_SENSITIVE (tool_item));
 361 }
 362
 363 static void
 364 create_drag_window (GtkToolItem *toolitem)
 365 {
 366   GtkWidget *widget;
 367   GdkWindowAttr attributes;
 368   gint attributes_mask, border_width;
 369
 370   g_return_if_fail (toolitem->priv->use_drag_window == TRUE);
 371
 372   widget = GTK_WIDGET (toolitem);
 373   border_width = GTK_CONTAINER (toolitem)->border_width;
 374
 375   attributes.window_type = GDK_WINDOW_CHILD;
 376   attributes.x = widget->allocation.x + border_width;
 377   attributes.y = widget->allocation.y + border_width;
 378   attributes.width = widget->allocation.width - border_width * 2;
 379   attributes.height = widget->allocation.height - border_width * 2;
 380   attributes.wclass = GDK_INPUT_ONLY;
 381   attributes.event_mask = gtk_widget_get_events (widget);
 382   attributes.event_mask |= (GDK_BUTTON_PRESS_MASK | GDK_BUTTON_RELEASE_MASK);
 383
 384   attributes_mask = GDK_WA_X | GDK_WA_Y;
 385
 386   toolitem->priv->drag_window = gdk_window_new (gtk_widget_get_parent_window (widget),
 387                                           &attributes, attributes_mask);
 388   gdk_window_set_user_data (toolitem->priv->drag_window, toolitem);
 389 }
 390
 391 static void
 392 gtk_tool_item_realize (GtkWidget *widget)
 393 {
 394   GtkToolItem *toolitem;
 395
 396   toolitem = GTK_TOOL_ITEM (widget);
 397   GTK_WIDGET_SET_FLAGS (widget, GTK_REALIZED);
 398
 399   widget->window = gtk_widget_get_parent_window (widget);
 400   g_object_ref (widget->window);
 401
 402   if (toolitem->priv->use_drag_window)
 403     create_drag_window(toolitem);
 404
 405   widget->style = gtk_style_attach (widget->style, widget->window);
 406 }
 407
 408 static void
 409 destroy_drag_window (GtkToolItem *toolitem)
 410 {
 411   if (toolitem->priv->drag_window)
 412     {
 413       gdk_window_set_user_data (toolitem->priv->drag_window, NULL);
 414       gdk_window_destroy (toolitem->priv->drag_window);
 415       toolitem->priv->drag_window = NULL;
 416     }
 417 }
 418
 419 static void
 420 gtk_tool_item_unrealize (GtkWidget *widget)
 421 {
 422   GtkToolItem *toolitem;
 423
 424   toolitem = GTK_TOOL_ITEM (widget);
 425
 426   destroy_drag_window (toolitem);
 427
 428   GTK_WIDGET_CLASS (gtk_tool_item_parent_class)->unrealize (widget);
 429 }
 430
 431 static void
 432 gtk_tool_item_map (GtkWidget *widget)
 433 {
 434   GtkToolItem *toolitem;
 435
 436   toolitem = GTK_TOOL_ITEM (widget);
 437   GTK_WIDGET_CLASS (gtk_tool_item_parent_class)->map (widget);
 438   if (toolitem->priv->drag_window)
 439     gdk_window_show (toolitem->priv->drag_window);
 440 }
 441
 442 static void
 443 gtk_tool_item_unmap (GtkWidget *widget)
 444 {
 445   GtkToolItem *toolitem;
 446
 447   toolitem = GTK_TOOL_ITEM (widget);
 448   if (toolitem->priv->drag_window)
 449     gdk_window_hide (toolitem->priv->drag_window);
 450   GTK_WIDGET_CLASS (gtk_tool_item_parent_class)->unmap (widget);
 451 }
 452
 453 static void
 454 gtk_tool_item_size_request (GtkWidget      *widget,
 455                             GtkRequisition *requisition)
 456 {
 457   GtkWidget *child = GTK_BIN (widget)->child;
 458
 459   if (child && GTK_WIDGET_VISIBLE (child))
 460     {
 461       gtk_widget_size_request (child, requisition);
 462     }
 463   else
 464     {
 465       requisition->height = 0;
 466       requisition->width = 0;
 467     }
 468
 469   requisition->width += (GTK_CONTAINER (widget)->border_width) * 2;
 470   requisition->height += (GTK_CONTAINER (widget)->border_width) * 2;
 471 }
 472
 473 static void
 474 gtk_tool_item_size_allocate (GtkWidget     *widget,
 475                              GtkAllocation *allocation)
 476 {
 477   GtkToolItem *toolitem = GTK_TOOL_ITEM (widget);
 478   GtkAllocation child_allocation;
 479   gint border_width;
 480   GtkWidget *child = GTK_BIN (widget)->child;
 481
 482   widget->allocation = *allocation;
 483   border_width = GTK_CONTAINER (widget)->border_width;
 484
 485   if (toolitem->priv->drag_window)
 486     gdk_window_move_resize (toolitem->priv->drag_window,
 487                             widget->allocation.x + border_width,
 488                             widget->allocation.y + border_width,
 489                             widget->allocation.width - border_width * 2,
 490                             widget->allocation.height - border_width * 2);
 491
 492   if (child && GTK_WIDGET_VISIBLE (child))
 493     {
 494       child_allocation.x = allocation->x + border_width;
 495       child_allocation.y = allocation->y + border_width;
 496       child_allocation.width = allocation->width - 2 * border_width;
 497       child_allocation.height = allocation->height - 2 * border_width;
 498
 499       gtk_widget_size_allocate (child, &child_allocation);
 500     }
 501 }
 502
 503 static gboolean
 504 gtk_tool_item_create_menu_proxy (GtkToolItem *item)
 505 {
 506   return FALSE;
 507 }
 508
 509 /**
 510  * gtk_tool_item_new:
 511  *
 512  * Creates a new #GtkToolItem
 513  *
 514  * Return value: the new #GtkToolItem
 515  *
 516  * Since: 2.4
 517  **/
 518 GtkToolItem *
 519 gtk_tool_item_new (void)
 520 {
 521   GtkToolItem *item;
 522
 523   item = g_object_new (GTK_TYPE_TOOL_ITEM, NULL);
 524
 525   return item;
 526 }
 527
 528 /**
 529  * gtk_tool_item_get_icon_size:
 530  * @tool_item: a #GtkToolItem:
 531  *
 532  * Returns the icon size used for @tool_item. Custom subclasses of
 533  * #GtkToolItem should call this function to find out what size icons
 534  * they should use.
 535  *
 536  * Return value: a #GtkIconSize indicating the icon size used for @tool_item
 537  *
 538  * Since: 2.4
 539  **/
 540 GtkIconSize
 541 gtk_tool_item_get_icon_size (GtkToolItem *tool_item)
 542 {
 543   GtkWidget *parent;
 544
 545   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), GTK_ICON_SIZE_LARGE_TOOLBAR);
 546
 547   parent = GTK_WIDGET (tool_item)->parent;
 548   if (!parent || !GTK_IS_TOOL_SHELL (parent))
 549     return GTK_ICON_SIZE_LARGE_TOOLBAR;
 550
 551   return gtk_tool_shell_get_icon_size (GTK_TOOL_SHELL (parent));
 552 }
 553
 554 /**
 555  * gtk_tool_item_get_orientation:
 556  * @tool_item: a #GtkToolItem:
 557  *
 558  * Returns the orientation used for @tool_item. Custom subclasses of
 559  * #GtkToolItem should call this function to find out what size icons
 560  * they should use.
 561  *
 562  * Return value: a #GtkOrientation indicating the orientation
 563  * used for @tool_item
 564  *
 565  * Since: 2.4
 566  **/
 567 GtkOrientation
 568 gtk_tool_item_get_orientation (GtkToolItem *tool_item)
 569 {
 570   GtkWidget *parent;
 571
 572   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), GTK_ORIENTATION_HORIZONTAL);
 573
 574   parent = GTK_WIDGET (tool_item)->parent;
 575   if (!parent || !GTK_IS_TOOL_SHELL (parent))
 576     return GTK_ORIENTATION_HORIZONTAL;
 577
 578   return gtk_tool_shell_get_orientation (GTK_TOOL_SHELL (parent));
 579 }
 580
 581 /**
 582  * gtk_tool_item_get_toolbar_style:
 583  * @tool_item: a #GtkToolItem:
 584  *
 585  * Returns the toolbar style used for @tool_item. Custom subclasses of
 586  * #GtkToolItem should call this function in the handler of the
 587  * GtkToolItem::toolbar_reconfigured signal to find out in what style
 588  * the toolbar is displayed and change themselves accordingly
 589  *
 590  * Possibilities are:
 591  * <itemizedlist>
 592  * <listitem> GTK_TOOLBAR_BOTH, meaning the tool item should show
 593  * both an icon and a label, stacked vertically </listitem>
 594  * <listitem> GTK_TOOLBAR_ICONS, meaning the toolbar shows
 595  * only icons </listitem>
 596  * <listitem> GTK_TOOLBAR_TEXT, meaning the tool item should only
 597  * show text</listitem>
 598  * <listitem> GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
 599  * both an icon and a label, arranged horizontally (however, note the
 600  * #GtkToolButton::has_text_horizontally that makes tool buttons not
 601  * show labels when the toolbar style is GTK_TOOLBAR_BOTH_HORIZ.
 602  * </listitem>
 603  * </itemizedlist>
 604  *
 605  * Return value: A #GtkToolbarStyle indicating the toolbar style used
 606  * for @tool_item.
 607  *
 608  * Since: 2.4
 609  **/
 610 GtkToolbarStyle
 611 gtk_tool_item_get_toolbar_style (GtkToolItem *tool_item)
 612 {
 613   GtkWidget *parent;
 614
 615   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), GTK_TOOLBAR_ICONS);
 616
 617   parent = GTK_WIDGET (tool_item)->parent;
 618   if (!parent || !GTK_IS_TOOL_SHELL (parent))
 619     return GTK_TOOLBAR_ICONS;
 620
 621   return gtk_tool_shell_get_style (GTK_TOOL_SHELL (parent));
 622 }
 623
 624 /**
 625  * gtk_tool_item_get_relief_style:
 626  * @tool_item: a #GtkToolItem:
 627  *
 628  * Returns the relief style of @tool_item. See gtk_button_set_relief_style().
 629  * Custom subclasses of #GtkToolItem should call this function in the handler
 630  * of the #GtkToolItem::toolbar_reconfigured signal to find out the
 631  * relief style of buttons.
 632  *
 633  * Return value: a #GtkReliefStyle indicating the relief style used
 634  * for @tool_item.
 635  *
 636  * Since: 2.4
 637  **/
 638 GtkReliefStyle
 639 gtk_tool_item_get_relief_style (GtkToolItem *tool_item)
 640 {
 641   GtkWidget *parent;
 642
 643   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), GTK_RELIEF_NONE);
 644
 645   parent = GTK_WIDGET (tool_item)->parent;
 646   if (!parent || !GTK_IS_TOOL_SHELL (parent))
 647     return GTK_RELIEF_NONE;
 648
 649   return gtk_tool_shell_get_relief_style (GTK_TOOL_SHELL (parent));
 650 }
 651
 652 /**
 653  * gtk_tool_item_set_expand:
 654  * @tool_item: a #GtkToolItem:
 655  * @expand: Whether @tool_item is allocated extra space
 656  *
 657  * Sets whether @tool_item is allocated extra space when there
 658  * is more room on the toolbar then needed for the items. The
 659  * effect is that the item gets bigger when the toolbar gets bigger
 660  * and smaller when the toolbar gets smaller.
 661  *
 662  * Since: 2.4
 663  **/
 664 void
 665 gtk_tool_item_set_expand (GtkToolItem *tool_item,
 666                           gboolean     expand)
 667 {
 668   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
 669
 670   expand = expand != FALSE;
 671
 672   if (tool_item->priv->expand != expand)
 673     {
 674       tool_item->priv->expand = expand;
 675       gtk_widget_child_notify (GTK_WIDGET (tool_item), "expand");
 676       gtk_widget_queue_resize (GTK_WIDGET (tool_item));
 677     }
 678 }
 679
 680 /**
 681  * gtk_tool_item_get_expand:
 682  * @tool_item: a #GtkToolItem:
 683  *
 684  * Returns whether @tool_item is allocated extra space.
 685  * See gtk_tool_item_set_expand().
 686  *
 687  * Return value: %TRUE if @tool_item is allocated extra space.
 688  *
 689  * Since: 2.4
 690  **/
 691 gboolean
 692 gtk_tool_item_get_expand (GtkToolItem *tool_item)
 693 {
 694   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), FALSE);
 695
 696   return tool_item->priv->expand;
 697 }
 698
 699 /**
 700  * gtk_tool_item_set_homogeneous:
 701  * @tool_item: a #GtkToolItem:
 702  * @homogeneous: whether @tool_item is the same size as other homogeneous items
 703  *
 704  * Sets whether @tool_item is to be allocated the same size as other
 705  * homogeneous items. The effect is that all homogeneous items will have
 706  * the same width as the widest of the items.
 707  *
 708  * Since: 2.4
 709  **/
 710 void
 711 gtk_tool_item_set_homogeneous (GtkToolItem *tool_item,
 712                                gboolean     homogeneous)
 713 {
 714   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
 715
 716   homogeneous = homogeneous != FALSE;
 717
 718   if (tool_item->priv->homogeneous != homogeneous)
 719     {
 720       tool_item->priv->homogeneous = homogeneous;
 721       gtk_widget_child_notify (GTK_WIDGET (tool_item), "homogeneous");
 722       gtk_widget_queue_resize (GTK_WIDGET (tool_item));
 723     }
 724 }
 725
 726 /**
 727  * gtk_tool_item_get_homogeneous:
 728  * @tool_item: a #GtkToolItem:
 729  *
 730  * Returns whether @tool_item is the same size as other homogeneous
 731  * items. See gtk_tool_item_set_homogeneous().
 732  *
 733  * Return value: %TRUE if the item is the same size as other homogeneous
 734  * item.s
 735  *
 736  * Since: 2.4
 737  **/
 738 gboolean
 739 gtk_tool_item_get_homogeneous (GtkToolItem *tool_item)
 740 {
 741   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), FALSE);
 742
 743   return tool_item->priv->homogeneous;
 744 }
 745
 746 /**
 747  * gtk_tool_item_get_is_important:
 748  * @tool_item: a #GtkToolItem
 749  *
 750  * Returns whether @tool_item is considered important. See
 751  * gtk_tool_item_set_is_important()
 752  *
 753  * Return value: %TRUE if @tool_item is considered important.
 754  *
 755  * Since: 2.4
 756  **/
 757 gboolean
 758 gtk_tool_item_get_is_important (GtkToolItem *tool_item)
 759 {
 760   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), FALSE);
 761
 762   return tool_item->priv->is_important;
 763 }
 764
 765 /**
 766  * gtk_tool_item_set_is_important:
 767  * @tool_item: a #GtkToolItem
 768  * @is_important: whether the tool item should be considered important
 769  *
 770  * Sets whether @tool_item should be considered important. The #GtkToolButton
 771  * class uses this property to determine whether to show or hide its label
 772  * when the toolbar style is %GTK_TOOLBAR_BOTH_HORIZ. The result is that
 773  * only tool buttons with the "is_important" property set have labels, an
 774  * effect known as "priority text"
 775  *
 776  * Since: 2.4
 777  **/
 778 void
 779 gtk_tool_item_set_is_important (GtkToolItem *tool_item, gboolean is_important)
 780 {
 781   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
 782
 783   is_important = is_important != FALSE;
 784
 785   if (is_important != tool_item->priv->is_important)
 786     {
 787       tool_item->priv->is_important = is_important;
 788
 789       gtk_widget_queue_resize (GTK_WIDGET (tool_item));
 790
 791       g_object_notify (G_OBJECT (tool_item), "is-important");
 792     }
 793 }
 794
 795 static gboolean
 796 gtk_tool_item_real_set_tooltip (GtkToolItem *tool_item,
 797                                 GtkTooltips *tooltips,
 798                                 const gchar *tip_text,
 799                                 const gchar *tip_private)
 800 {
 801   GtkWidget *child = GTK_BIN (tool_item)->child;
 802
 803   if (!child)
 804     return FALSE;
 805
 806   gtk_widget_set_tooltip_text (child, tip_text);
 807
 808   return TRUE;
 809 }
 810
 811 /**
 812  * gtk_tool_item_set_tooltip:
 813  * @tool_item: a #GtkToolItem:
 814  * @tooltips: The #GtkTooltips object to be used
 815  * @tip_text: text to be used as tooltip text for @tool_item
 816  * @tip_private: text to be used as private tooltip text
 817  *
 818  * Sets the #GtkTooltips object to be used for @tool_item, the
 819  * text to be displayed as tooltip on the item and the private text
 820  * to be used. See gtk_tooltips_set_tip().
 821  *
 822  * Since: 2.4
 823  *
 824  * Deprecated: 2.12: Use gtk_tool_item_set_tooltip_text() instead.
 825  **/
 826 void
 827 gtk_tool_item_set_tooltip (GtkToolItem *tool_item,
 828                            GtkTooltips *tooltips,
 829                            const gchar *tip_text,
 830                            const gchar *tip_private)
 831 {
 832   gboolean retval;
 833
 834   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
 835
 836   g_signal_emit (tool_item, toolitem_signals[SET_TOOLTIP], 0,
 837                  tooltips, tip_text, tip_private, &retval);
 838 }
 839
 840 /**
 841  * gtk_tool_item_set_tooltip_text:
 842  * @tool_item: a #GtkToolItem:
 843  * @text: text to be used as tooltip for @tool_item
 844  *
 845  * Sets the text to be displayed as tooltip on the item.
 846  * See gtk_widget_set_tooltip_text().
 847  *
 848  * Since: 2.12
 849  **/
 850 void
 851 gtk_tool_item_set_tooltip_text (GtkToolItem *tool_item,
 852                                 const gchar *text)
 853 {
 854   GtkWidget *child;
 855
 856   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
 857
 858   child = GTK_BIN (tool_item)->child;
 859
 860   if (child)
 861     gtk_widget_set_tooltip_text (child, text);
 862 }
 863
 864 /**
 865  * gtk_tool_item_set_tooltip_markup:
 866  * @tool_item: a #GtkToolItem:
 867  * @markup: markup text to be used as tooltip for @tool_item
 868  *
 869  * Sets the markup text to be displayed as tooltip on the item.
 870  * See gtk_widget_set_tooltip_markup().
 871  *
 872  * Since: 2.12
 873  **/
 874 void
 875 gtk_tool_item_set_tooltip_markup (GtkToolItem *tool_item,
 876                                   const gchar *markup)
 877 {
 878   GtkWidget *child;
 879
 880   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
 881
 882   child = GTK_BIN (tool_item)->child;
 883
 884   if (child)
 885     gtk_widget_set_tooltip_markup (child, markup);
 886 }
 887
 888 /**
 889  * gtk_tool_item_set_use_drag_window:
 890  * @tool_item: a #GtkToolItem
 891  * @use_drag_window: Whether @tool_item has a drag window.
 892  *
 893  * Sets whether @tool_item has a drag window. When %TRUE the
 894  * toolitem can be used as a drag source through gtk_drag_source_set().
 895  * When @tool_item has a drag window it will intercept all events,
 896  * even those that would otherwise be sent to a child of @tool_item.
 897  *
 898  * Since: 2.4
 899  **/
 900 void
 901 gtk_tool_item_set_use_drag_window (GtkToolItem *toolitem,
 902                                    gboolean     use_drag_window)
 903 {
 904   g_return_if_fail (GTK_IS_TOOL_ITEM (toolitem));
 905
 906   use_drag_window = use_drag_window != FALSE;
 907
 908   if (toolitem->priv->use_drag_window != use_drag_window)
 909     {
 910       toolitem->priv->use_drag_window = use_drag_window;
 911
 912       if (use_drag_window)
 913         {
 914           if (!toolitem->priv->drag_window && GTK_WIDGET_REALIZED (toolitem))
 915             {
 916               create_drag_window(toolitem);
 917               if (GTK_WIDGET_MAPPED (toolitem))
 918                 gdk_window_show (toolitem->priv->drag_window);
 919             }
 920         }
 921       else
 922         {
 923           destroy_drag_window (toolitem);
 924         }
 925     }
 926 }
 927
 928 /**
 929  * gtk_tool_item_get_use_drag_window:
 930  * @tool_item: a #GtkToolItem
 931  *
 932  * Returns whether @tool_item has a drag window. See
 933  * gtk_tool_item_set_use_drag_window().
 934  *
 935  * Return value: %TRUE if @tool_item uses a drag window.
 936  *
 937  * Since: 2.4
 938  **/
 939 gboolean
 940 gtk_tool_item_get_use_drag_window (GtkToolItem *toolitem)
 941 {
 942   g_return_val_if_fail (GTK_IS_TOOL_ITEM (toolitem), FALSE);
 943
 944   return toolitem->priv->use_drag_window;
 945 }
 946
 947 /**
 948  * gtk_tool_item_set_visible_horizontal:
 949  * @tool_item: a #GtkToolItem
 950  * @visible_horizontal: Whether @tool_item is visible when in horizontal mode
 951  *
 952  * Sets whether @tool_item is visible when the toolbar is docked horizontally.
 953  *
 954  * Since: 2.4
 955  **/
 956 void
 957 gtk_tool_item_set_visible_horizontal (GtkToolItem *toolitem,
 958                                       gboolean     visible_horizontal)
 959 {
 960   g_return_if_fail (GTK_IS_TOOL_ITEM (toolitem));
 961
 962   visible_horizontal = visible_horizontal != FALSE;
 963
 964   if (toolitem->priv->visible_horizontal != visible_horizontal)
 965     {
 966       toolitem->priv->visible_horizontal = visible_horizontal;
 967
 968       g_object_notify (G_OBJECT (toolitem), "visible-horizontal");
 969
 970       gtk_widget_queue_resize (GTK_WIDGET (toolitem));
 971     }
 972 }
 973
 974 /**
 975  * gtk_tool_item_get_visible_horizontal:
 976  * @tool_item: a #GtkToolItem
 977  *
 978  * Returns whether the @tool_item is visible on toolbars that are
 979  * docked horizontally.
 980  *
 981  * Return value: %TRUE if @tool_item is visible on toolbars that are
 982  * docked horizontally.
 983  *
 984  * Since: 2.4
 985  **/
 986 gboolean
 987 gtk_tool_item_get_visible_horizontal (GtkToolItem *toolitem)
 988 {
 989   g_return_val_if_fail (GTK_IS_TOOL_ITEM (toolitem), FALSE);
 990
 991   return toolitem->priv->visible_horizontal;
 992 }
 993
 994 /**
 995  * gtk_tool_item_set_visible_vertical:
 996  * @tool_item: a #GtkToolItem
 997  * @visible_vertical: whether @tool_item is visible when the toolbar
 998  * is in vertical mode
 999  *
1000  * Sets whether @tool_item is visible when the toolbar is docked
1001  * vertically. Some tool items, such as text entries, are too wide to be
1002  * useful on a vertically docked toolbar. If @visible_vertical is %FALSE
1003  * @tool_item will not appear on toolbars that are docked vertically.
1004  *
1005  * Since: 2.4
1006  **/
1007 void
1008 gtk_tool_item_set_visible_vertical (GtkToolItem *toolitem,
1009                                     gboolean     visible_vertical)
1010 {
1011   g_return_if_fail (GTK_IS_TOOL_ITEM (toolitem));
1012
1013   visible_vertical = visible_vertical != FALSE;
1014
1015   if (toolitem->priv->visible_vertical != visible_vertical)
1016     {
1017       toolitem->priv->visible_vertical = visible_vertical;
1018
1019       g_object_notify (G_OBJECT (toolitem), "visible-vertical");
1020
1021       gtk_widget_queue_resize (GTK_WIDGET (toolitem));
1022     }
1023 }
1024
1025 /**
1026  * gtk_tool_item_get_visible_vertical:
1027  * @tool_item: a #GtkToolItem
1028  *
1029  * Returns whether @tool_item is visible when the toolbar is docked vertically.
1030  * See gtk_tool_item_set_visible_vertical().
1031  *
1032  * Return value: Whether @tool_item is visible when the toolbar is docked vertically
1033  *
1034  * Since: 2.4
1035  **/
1036 gboolean
1037 gtk_tool_item_get_visible_vertical (GtkToolItem *toolitem)
1038 {
1039   g_return_val_if_fail (GTK_IS_TOOL_ITEM (toolitem), FALSE);
1040
1041   return toolitem->priv->visible_vertical;
1042 }
1043
1044 /**
1045  * gtk_tool_item_retrieve_proxy_menu_item:
1046  * @tool_item: a #GtkToolItem:
1047  *
1048  * Returns the #GtkMenuItem that was last set by
1049  * gtk_tool_item_set_proxy_menu_item(), ie. the #GtkMenuItem
1050  * that is going to appear in the overflow menu.
1051  *
1052  * Return value: The #GtkMenuItem that is going to appear in the
1053  * overflow menu for @tool_item.
1054  *
1055  * Since: 2.4
1056  **/
1057 GtkWidget *
1058 gtk_tool_item_retrieve_proxy_menu_item (GtkToolItem *tool_item)
1059 {
1060   gboolean retval;
1061
1062   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), NULL);
1063
1064   g_signal_emit (tool_item, toolitem_signals[CREATE_MENU_PROXY], 0,
1065                  &retval);
1066
1067   return tool_item->priv->menu_item;
1068 }
1069
1070 /**
1071  * gtk_tool_item_get_proxy_menu_item:
1072  * @tool_item: a #GtkToolItem:
1073  * @menu_item_id: a string used to identify the menu item
1074  *
1075  * If @menu_item_id matches the string passed to
1076  * gtk_tool_item_set_proxy_menu_item() return the corresponding #GtkMenuItem.
1077  *
1078  * Custom subclasses of #GtkToolItem should use this function to update
1079  * their menu item when the #GtkToolItem changes. That the
1080  * @menu_item_id<!-- -->s must match ensures that a #GtkToolItem will not
1081  * inadvertently change a menu item that they did not create.
1082  *
1083  * Return value: The #GtkMenuItem passed to
1084  * gtk_tool_item_set_proxy_menu_item(), if the @menu_item_id<!-- -->s match.
1085  *
1086  * Since: 2.4
1087  **/
1088 GtkWidget *
1089 gtk_tool_item_get_proxy_menu_item (GtkToolItem *tool_item,
1090                                    const gchar *menu_item_id)
1091 {
1092   g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), NULL);
1093   g_return_val_if_fail (menu_item_id != NULL, NULL);
1094
1095   if (tool_item->priv->menu_item_id && strcmp (tool_item->priv->menu_item_id, menu_item_id) == 0)
1096     return tool_item->priv->menu_item;
1097
1098   return NULL;
1099 }
1100
1101 /**
1102  * gtk_tool_item_rebuild_menu()
1103  * @tool_item: a #GtkToolItem
1104  *
1105  * Calling this function signals to the toolbar that the
1106  * overflow menu item for @tool_item has changed. If the
1107  * overflow menu is visible when this function it called,
1108  * the menu will be rebuilt.
1109  *
1110  * The function must be called when the tool item
1111  * changes what it will do in response to the "create_menu_proxy"
1112  * signal.
1113  *
1114  * Since: 2.6
1115  **/
1116 void
1117 gtk_tool_item_rebuild_menu (GtkToolItem *tool_item)
1118 {
1119   GtkWidget *widget;
1120
1121   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
1122
1123   widget = GTK_WIDGET (tool_item);
1124
1125   if (GTK_IS_TOOL_SHELL (widget->parent))
1126     gtk_tool_shell_rebuild_menu (GTK_TOOL_SHELL (widget->parent));
1127 }
1128
1129 /**
1130  * gtk_tool_item_set_proxy_menu_item:
1131  * @tool_item: a #GtkToolItem:
1132  * @menu_item_id: a string used to identify @menu_item
1133  * @menu_item: a #GtkMenuItem to be used in the overflow menu
1134  *
1135  * Sets the #GtkMenuItem used in the toolbar overflow menu. The
1136  * @menu_item_id is used to identify the caller of this function and
1137  * should also be used with gtk_tool_item_get_proxy_menu_item().
1138  *
1139  * Since: 2.4
1140  **/
1141 void
1142 gtk_tool_item_set_proxy_menu_item (GtkToolItem *tool_item,
1143                                    const gchar *menu_item_id,
1144                                    GtkWidget   *menu_item)
1145 {
1146   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
1147   g_return_if_fail (menu_item == NULL || GTK_IS_MENU_ITEM (menu_item));
1148   g_return_if_fail (menu_item_id != NULL);
1149
1150   g_free (tool_item->priv->menu_item_id);
1151
1152   tool_item->priv->menu_item_id = g_strdup (menu_item_id);
1153
1154   if (tool_item->priv->menu_item != menu_item)
1155     {
1156       if (tool_item->priv->menu_item)
1157         g_object_unref (tool_item->priv->menu_item);
1158
1159       if (menu_item)
1160         {
1161           g_object_ref_sink (menu_item);
1162
1163           gtk_widget_set_sensitive (menu_item,
1164                                     GTK_WIDGET_SENSITIVE (tool_item));
1165         }
1166
1167       tool_item->priv->menu_item = menu_item;
1168     }
1169 }
1170
1171 /**
1172  * gtk_tool_item_toolbar_reconfigured:
1173  * @tool_item: a #GtkToolItem
1174  *
1175  * Emits the signal #GtkToolItem::toolbar_reconfigured on @tool_item.
1176  * #GtkToolbar and other #GtkToolShell implementations use this function
1177  * to notify children, when some aspect of their configuration changes.
1178  *
1179  * Since: 2.14
1180  **/
1181 void
1182 gtk_tool_item_toolbar_reconfigured (GtkToolItem *tool_item)
1183 {
1184   /* The slightely inaccurate name "gtk_tool_item_toolbar_reconfigured" was
1185    * choosen over "gtk_tool_item_tool_shell_reconfigured", since the function
1186    * emits the "toolbar-reconfigured" signal, not "tool-shell-reconfigured".
1187    * Its not possible to rename the signal, and emitting another name than
1188    * indicated by the function name would be quite confusing. That's the
1189    * price of providing stable APIs.
1190    */
1191   g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
1192
1193   g_signal_emit (tool_item, toolitem_signals[TOOLBAR_RECONFIGURED], 0);
1194
1195   if (tool_item->priv->drag_window)
1196     gdk_window_raise (tool_item->priv->drag_window);
1197
1198   gtk_widget_queue_resize (GTK_WIDGET (tool_item));
1199 }
1200
1201 #define __GTK_TOOL_ITEM_C__
1202 #include "gtkaliasdef.c"