GNOME Bugzilla – Bug 339205
Widget:popup-menu and show-help signals need docs for language bindings
Last modified: 2016-11-04 21:28:54 UTC
I suspect that the Widget:popup-menu and Widget:show-help signals are needed by application developers, and should therefore be wrapped by lanuage bindings. However, this needs to be made clearer in the documentation, because we will not risk wrapping API that we suspect to be private (and therefore potentially unstable). See also: http://mail.gnome.org/archives/gtk-devel-list/2006-April/msg00091.html
To be clear, I'm not going to submit a patch to document these as non-private, until I know whether they are non-private.
Any opinions?
It is all about "popup-menu"... I am not a Gtk+ developer, but I use Gtkmm extensively and I need this signal to be wrapped. My opinion, therefore, is to simply wrap it. :) IMHO it is simpler than all this talking about it. No offense. The signal is there for few years now and it does not seem to be going anywhere anytime soon. PyGTK wraps it, people writing in C are using it so I really don't see any problem. Also, I don't see what's wrong with the documentation of this signal. For me it is pretty clear. (But "show-help" is, ekhem, misunderstanding.) Regards
I am now convinced that popup-menu is meant to be used by applications, because it's documentation links to an example of an application doing that: http://library.gnome.org/devel/gtk/unstable/GtkWidget.html#GtkWidget-popup-menu I will attach a bug to make that documentation clearer). However, I still see no statement suggesting that show-help is meant to be used, unlike other G_SIGNAL_ACTION "key-binding" signals.
Created attachment 98555 [details] [review] gtk_popup_menu_docs.patch Permission to commit?
Please.
Not sure the patch add much clarity. Apps are free to use any action signal they want. Maybe you need to make a bit clearer what you mean by "used".
Quoting the email from Owen Taylor mention in #1: http://mail.gnome.org/archives/gtk-devel-list/2006-April/msg00091.html " G_SIGNAL_ACTION just means "this signal can be emitted via g_signal_emit() directly - it doesn't need a wrapper function" It could be: - A keybinding signal handled by the widget internally - there should not be any way of overriding the handler for such a signal or for connecting to them. - A keybinding signal that has to be handled by derived widgets. Overriding these is necessary, connection is often also useful. - Not a keybinding signal at all. Please don't bind all keybinding signals. You are just asking for problems (as you discovered) if you bind them, and, perhaps worse, they pollute the API and confuse users... see for instance, GtkTextView::move-cursor... users think they are change notification and get confused when they don't always get called. I think you have to figure out ad-hoc what signals need to be bound for connection/overriding and when it isn't clear from the docs, file bugs. " So I think I have figured out that this signal is really meant to be used directly and I'd like to document that.
What do you think?
What do I have to do to get an answer? This seems excessive.
Could we please get an official statement about whether we should use this show-help signal?
show-help is handled by GtkWidget to toggle keyboard tooltip mode. There should be very little reason to override the default handler or connect to the signal. Derived widgets set a class handler for popup-menu to implement their context menu. There should be little reason to connect to the signal. You have to figure out for yourself what that means for bindings...
(In reply to comment #11) > Could we please get an official statement about whether we should use this > show-help signal? PyGTK wraps and documents both popup-menu and show-help. Other bindings probably should do the same.. I see no reason for not committing the patch, it doesn't make the docs _more_ confusing in any case. And the question about these signals ought to come up once again when the GObject-Introspection stuff is being finished.
GtkWidget::popup-menu was wrapped in gtkmm long ago. GtkWidget::show-help has been removed from gtk+'s master branch, meaning (I suppose) that it will not be included in gtk+-4.0. Can this bug be closed now?
I guess so. Thanks.