How to popdown a tooltip

["Padraig O'Briain" <Padraig Obriain Sun COM>]

I am wrestling with how to pop down a tooltip which was shown by pressing 
the Ctrl+F1 key. Calum's proposal was that Escape or focus switch should 
cause it to be popped down.

The following text is from a mail on gtk-devel-list whose subject was 
"numeric keypad, tooltips/whatsthis key" from Havoc on May 11th.

======================================================================
The actual gtktooltips changes aren't really right; the tooltip
doesn't pop down in a coherent way. Calum suggests that the tooltip
pop down on Escape or focus switch. This is really painful to
implement, because doing it on Escape requires the tip to grab
keyboard, and doing it on focus switch requires events to go to the
window the tooltip is popped up for. Probably we can't just pop down
on any key event since some may be needed for accessible navigation.

The only implementations I can come up with require hardcoding the
Escape key, because binding sets always absorb the keys they bind, and
here we need to absorb Escape only in this one situation and pass
through otherwise. Solutions involving enable/disable on binding
signals or allowing binding signal emissions to indicate "event
unhandled" seem a bit like overkill, but may be of general use.
=====================================================================

Focus switch _does_ cause the tooltip to be popped down because any event
other that GDK_MOTION_NOTIFY or GDK_EXPOSE received by a widget which has
a tooltip defined causes the tooltip to be popped down; this is what 
gtk_tooltips_event_handler() does.

As for Escape key, I would like to clarify the requirement. 

Should the Escape key cause a tooltip to be popped down, only if the tooltip 
is for the focus widget? 

Do we expect different behavior if the tooltip was displayed because of mouse 
movement or because Ctrl+F1 key was pressed?

What effect should other keys have while the tooltip is showing?

Some widgets define actions to be taken for the Escape key. Some of these
actions are defined in key_press_event_handlers and some by binding a key
and modifier combination to an action signal. In either case, I assume that
the requirement is that the Escape key should pop down the tooltip for the
focus widget if it is showing; in this case I assume that the 
key_press_event_handler or action signal handler should not be called.

I do not see how we can implement the Escape key using key bindings as the
key_press_event_handlers may have been called before the key bindings are
activated.

The best I can come up with is to define a key_press_event_handler for the
toplevel window of the widget while the tooltip is showing. An alternative
could be to use the key snooping functions which I have just noticed in
gtkmain.c to install a GtkKeySnoopFunc function while the tooltip is
showing. This function would listen for Escape key and pop down the tooltip
and remove the GtkKeySnoopFunc function.

Padraig