Created attachment 32210 [details]
Brief Demonstration

Comment out gtk_tool_item_set_tooltip or gtk_tooltips_set_tip to see that one
works and the other does not.

I don't read the documentation as implying that gtk_tooltips_set_tip) would work
on toolitems. It will work if you call it on the child of the tool item, which is
what gtk_tool_item_set_tooltip() does. Please reopen if you have a proposal for
clarifying the docs.

tooltips_set_tip takes a GtkWidget argument.  Toolitem inherits from GtkWidget.
 If we're going to have certain GtkWidgets excluded, that should definitely be
noted.  Since I don't actually know which GtkWidgets work with
gtk_tooltips_set_tip, I can't make this modification myself.

void gtk_tooltips_set_tip (GtkTooltips *tooltips,
                           GtkWidget *widget,
                           const gchar *tip_text,
                           const gchar *tip_private);

GObject
 +----GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBin
                         +----GtkToolItem

Matthias,

If you look at the test case, you will see that gtk_tooltips_set_tip() does NOT,
as you suggest, work with "the child of the tool item", if by that you mean
something which derives from GtkToolItem.  It does not work with tool buttons,
which was the point of the bug report.

the child of the tool item is GTK_BIN(tool_item)->child

So, where 'button' is a pointer to a GtkButton object, this works:

  gtk_tooltips_set_tip(tips, GTK_WIDGET(button), "tooltips_set_tip",
                       "tooltips_set_tip");

Where 'button' is a pointer to a GtkToolButton object it does not.

However, where 'button' is a pointer to a GtkToolButton object, this works:

  gtk_tooltips_set_tip(tips, GTK_WIDGET(GTK_BIN(button)->child),
                       "tooltips_set_tip", "tooltips_set_tip");

As it happens, both GtkButton and GtkToolItem derive directly from GtkBin.  If
this is intended behaviour, it seems to me that the original poster is correct,
and this un-OO like behaviour should be documented for gtk_tooltips_set_tip().

However, it would be better for gtk_tooltips_set_tip() to work with any object
deriving from GtkWidget, since that is the argument it takes.  This would
presumably mean gtk_tooltips_set_tip() specialising itself when passed something
derived from GtkToolItem.  Is there anything else deriving from GtkWidget which
does not work with gtk_tooltips_set_tip()?  If correcting the documentation (or
correcting the implementation of gtk_tooltips_set_tip()) it would be best to be
complete.

I have to add that this very strange behavior puzzled me until I found this post. It's not clear according to the docs (or argument types) as to why you have to use a different function in order to set the tooltips for this special kind of button.
I considered this a bug, not really a design "feature", since there's not logical argument of why you would handle this case in a different way.

This bug should probably be marked as notabug, since GtkToolTips API docs clearly state (for more than a decade) that widgets with no GdkWindow cannot have tooltip set.

Commit that added that piece of information to API docs: http://git.gnome.org/browse/gtk+/commit/docs/reference/gtk/tmpl/gtktooltips.sgml?h=gtk-2-24&id=e809560d6af9a3ba7410a7123d090cf65a110183

this bug should be marked as obsolete, since GtkTooltips has been deprecated for years in gtk2, and we have new API to set tooltips on widgets. GtkTooltips is also not available in gtk3.