GNOME Bugzilla – Bug 655489
Gtk::ComboBox with Entry needs better description in the tutorial
Last modified: 2013-08-16 14:13:59 UTC
Overview: The chapter on combo boxes in the gtkmm tutorial mentions only the signal Gtk::ComboBox::signal_changed() for reacting to a user-initiated change. This signal is fine for a combo box without an Entry widget. For a combo box with an Entry, where the user can type any text, it's not enough. As explained in the chapter "Miscellaneous Widgets" the "changed" signal is emitted for every character the user types, and the "activate" signal is emitted when the user presses the enter key. Both ComboBox and Entry have a "changed" signal, and both of them are emitted for every change of the contents of the entry field. The following comment in http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/combobox/entry_complex/examplewindow.cc is not correct: //Note: to get changes only when the entry has been completed, //instead of on every key press, connect to Entry::signal_changed() //instead of ComboBoxEntry::signal_changed. Both ComboBox and Entry also have an "editing-done" signal, inherited from CellEditable. The documentation at http://developer.gnome.org/gtk3/unstable/GtkCellEditable.html#GtkCellEditable-editing-done says: Implementations of GtkCellEditable are responsible for emitting this signal when they are done editing, e.g. GtkEntry is emitting it when the user presses Enter. That's not true. I've modified the example programs gtkmm_documentation/examples/book/combobox/entry_text and gtk+/tests/testcombo, and connected to some signals. "editing-done" is never emitted. Entry's "activate" signal is emitted, when the enter key is pressed. The "activate" signal is a bit dubious. A comment in entry.hg refers to http://mail.gnome.org/archives/gtk-devel-list/2003-January/msg00108.html, saying Murray Cumming: > So I'd like to know what signals are "keybinding" signals. I thought I > could just check for uses of gtk_binding_entry_add_signal(), but that's > used on GtkEntry's "activate" signal, and I'm told that that's not a > keybinding signal. Owen Taylor: activate is probably about the only exception in that direction The gtk+ documentation of GtkEntry's "activate" signal at http://developer.gnome.org/gtk3/unstable/GtkEntry.html#GtkEntry-activate says: A keybinding signal which gets emitted when the user activates the entry. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control activation programmatically. The default bindings for this signal are all forms of the Enter key. Steps to reproduce: A modified version of example program examples/book/combobox/entry_text will be attached to this bug. Run it, and check what signals are emitted, when you make changes in the combo box. Actual results: Both "changed" signals are emitted every time the entry field is changed, either by typing in it, or by selecting an item in the drop-down list. None of the "editing-done" signals are ever emitted. The "activate" signal is emitted when enter is pressed. Expected results: Not sure. The aim of this bug is to improve the documentation in the gtkmm tutorial. Build date and platform: Ubuntu 11.04, source code of gtkmm, gtk+, etc. built with jhbuild on 2011-07-24. Additional information:
Created attachment 192810 [details] Modified version of examples/book/combobox/entry_text.
(In reply to comment #0) > Both ComboBox and Entry also have an "editing-done" signal, inherited from > CellEditable. The documentation at > http://developer.gnome.org/gtk3/unstable/GtkCellEditable.html#GtkCellEditable-editing-done > says: > > Implementations of GtkCellEditable are responsible for emitting this signal > when they are done editing, e.g. GtkEntry is emitting it when the user > presses Enter. > > That's not true. Can you deal with that GTK+ bug separately then, please, making this one dependent on it?
I've filed gtk+ bug 655500. When I know which signal to use for detecting a pressed enter key, I can make a patch with some small changes to the ComboBox chapter and combobox/entry_text and combobox/entry_complex examples. If it's not acceptable to use the "activate" signal, the section on the Entry widget must also be changed.
We've got an answer in bug 655500 comment 11. My suggestions: We accept the answer, and I close bug 655500. I modify the sections on Entry and ComboBox in the tutorial. Entry's activate signal is still dubious. Since it's explicitly said in the GTK+ documentation that applications shall not connect to it, we had better not mention it in the tutorial. Instead the tutorial shall mention that the key-press-event and focus-out-event signals can be used for detecting that the user has finished editing the text. (See test case in bug 655500 comment 10.) The brand new chapter on keyboard events (bug 661857) comes in handy here.
(In reply to comment #4) > Entry's activate signal is still dubious. Since it's explicitly said in the > GTK+ documentation that applications shall not connect to it, where? We wrap it in gtkmm because they said that we should: //This is a keybinding signal, but it is allowed: // http://mail.gnome.org/archives/gtk-devel-list/2003-January/msg00108.html // "activate is probably about the only exception" _WRAP_SIGNAL(void activate(), "activate") (I have mentioned that in the GTK+ bug.)
(In reply to comment #5) > (In reply to comment #4) > > Entry's activate signal is still dubious. Since it's explicitly said in the > > GTK+ documentation that applications shall not connect to it, > > where? http://developer.gnome.org/gtk3/stable/GtkEntry.html#GtkEntry-activate http://developer.gnome.org/gtk3/unstable/GtkEntry.html#GtkEntry-activate Well, the documentation says "should not" instead of "shall not". I don't know if that makes a significant difference.
[Setting QA Contact of all open gtkmm/documentation tickets to 'gtkmm-forge@' so people interested in following reports' changes via the users watchlist can still follow if the assignee is changed to a real person.]
We don't get a quick reply to bug 655500 comment 12 and 13. One thing that has happened recently is that gmmproc now copies signal descriptions from gtk+ to gtkmm, thanks to the fixes in bug 668918. Now the description of Gtk::Entry::signal_activate() says "A keybinding signal which gets emitted when the user activates the entry. Applications should not connect to it..." http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Entry.html#a8ca968ac536264b82d7f603d5c985c4d I suggest that we accept my conclusions in bug 655500 comment 13, and I change the gtkmm tutorial as described in comment 4, i.e. don't mention Gtk::Entry:: signal_activate() in the tutorial. What about deprecating signal_activate()?
(In reply to comment #8) > Now the description of Gtk::Entry::signal_activate() says > "A keybinding signal which gets emitted when the user activates the entry. > Applications should not connect to it..." > http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Entry.html#a8ca968ac536264b82d7f603d5c985c4d Hmm, yes, that change was made in 2008 by Matthias Clasen: http://git.gnome.org/browse/gtk+/commit/gtk/gtkentry.c?id=d9fc6d8abc0784c83f7e596da0e993ed60a15288 That does directly contradict Owen Taylor's comment in 2003, mentioned in comment #5 (and in the code): http://mail.gnome.org/archives/gtk-devel-list/2003-January/msg00108.html So I guess we should indeed deprecate this, suggesting those other signals that you mention in comment #4, and updating the tutorial.
(In reply to comment #9) > (In reply to comment #8) > > Now the description of Gtk::Entry::signal_activate() says > > "A keybinding signal which gets emitted when the user activates the entry. > > Applications should not connect to it..." > > http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Entry.html#a8ca968ac536264b82d7f603d5c985c4d > > Hmm, yes, that change was made in 2008 by Matthias Clasen: > http://git.gnome.org/browse/gtk+/commit/gtk/gtkentry.c?id=d9fc6d8abc0784c83f7e596da0e993ed60a15288 > > That does directly contradict Owen Taylor's comment in 2003, mentioned in > comment #5 (and in the code): > http://mail.gnome.org/archives/gtk-devel-list/2003-January/msg00108.html > > So I guess we should indeed deprecate this, suggesting those other signals that > you mention in comment #4 I have done that: http://git.gnome.org/browse/gtkmm/commit/?id=7e247e3ab775bc2205d401ce31c1da1270ec4abb which needs this: http://git.gnome.org/browse/glibmm/commit/?id=7a6c0ac34de755cd77f321afde69f60971d372c6 Maybe you would like to update gtkmm-tutorial: others/cellrenderercustom/popupentry.cc: In member function ‘virtual void PopupEntry::start_editing_vfunc(GdkEvent*)’: others/cellrenderercustom/popupentry.cc:139:11: error: ‘class Gtk::Entry’ has no member named ‘signal_activate’ That's using --enable-warnings=fatal with autogen.sh.
I guess that we should also mention Gtk::Entry::set_activates_default() too: http://developer.gnome.org/gtk3/unstable/GtkEntry.html#gtk-entry-set-activates-default because this is often what people want. However, that would then need some discussion of set_can_default(), and maybe grab_default().
I've changed others/cellrenderercustom/popupentry.cc. Now 'make check' works with --enable-warnings=fatal. http://git.gnome.org/browse/gtkmm-documentation/commit/?id=5b9e69bef5a3a00caeb26fbbd0149bb8758095ea I'll change gtkmm-tutorial-in.xml later. I also ought to add signal_key_press_event() and signal_focus_out_event() in at least one of book/combobox/entry_text and entry_complex. I've closed gtk+ bug 655500. Is there a bug in the glibmm commit that makes it possible to deprecate signals? Entry::signal_activate() is not surrounded by GTKMM_DISABLE_DEPRECATED in entry.cc. I see also that all Xxx::property_xxx() methods are surrounded by GTKMM_DISABLE_DEPRECATED in the .cc files, but that happened earlier. I see it in .cc files that gmmproc created on 8 March.
(In reply to comment #12) > Is there a bug in the glibmm commit that makes it possible to deprecate > signals? Entry::signal_activate() is not surrounded by > GTKMM_DISABLE_DEPRECATED in entry.cc. Yes, I was a bit lazy. Feel free to fix that if I don't first. > I see also that all Xxx::property_xxx() methods are surrounded by > GTKMM_DISABLE_DEPRECATED in the .cc files, but that happened earlier. I see > it in .cc files that gmmproc created on 8 March. Oops. That's not right, though it's probably harmless.
I've started working on fixes for the bugs in _WRAP_SIGNAL(...deprecated) and _WRAP_PROPERTY. I can probably push them soon. The description of Gtk::Button::signal_activate() says "Applications should never connect to this signal..." Another signal that should be deprecated? The descriptions of Gdk::Display::set_double_click_time() and set_double_click_distance() say "Applications should <em>not</em> set this, it is a global user-configured setting."
Yes, let's deprecate those too and see what happens. If that is a real problem then we will see in gtkmm-documentation and glom, for instance. If necessary, we can undeprecate them later.
I've pushed glibmm commits that fix _WRAP_PROPERTY() and _WRAP_SIGNAL(), http://git.gnome.org/browse/glibmm/commit/?id=722b9d793b3873d7ecc0c716843953ed2844a84c http://git.gnome.org/browse/glibmm/commit/?id=d38a3dbd7fafdda778cc2e83d2321d91ae870e80 and gtkmm commits that deprecate Gtk::Button::signal_activate() and Gdk::Display::set_double_click_time() and set_double_click_distance(), http://git.gnome.org/browse/gtkmm/commit/?id=4f292cb32a6f05fcb6ce2122ce01bb0b6d12add0 http://git.gnome.org/browse/gtkmm/commit/?id=828af91cf4f04cc54f363970d724806c8dfe3bf5 'make check' in gtkmm and gtkmm-documentation works after these changes. I have not tested glom. I've seen that there are several methods and signals that are deprecated in gtk+ but not in gtkmm. Gtk::Button::signal_enter(), signal_leave(), signal_pressed(), signal_released() Gtk::MenuItem::[set|get]_right_justified() Gtk::Notebook::get_tab_[h|v]border() Gtk::Widget::[set|get]_state(), signal_state_changed() The replacement state-flags-changed signal is not wrapped. I'll leave these deprecation issues now, and try to get on with the changes of the gtkmm tutorial that this bug is really about.
(In reply to comment #16) > I've seen that there are several methods and signals that are deprecated in > gtk+ but not in gtkmm. Fixed: http://git.gnome.org/browse/gtkmm/commit/?id=99fafc8bbb224b2af279149041ef142fe7c36b35 Thanks for mentioning them.
Created attachment 210782 [details] [review] patch: Improve the Entry and ComboBox with Entry sections. (gtkmm-doc) Is this patch good enough? I've not mentioned the editing_done signal that Entry inherits from the CellEditable interface. It confused me at first, because I thought it should be emitted, but as explained in bug 655500 comment 11 it's only relevant when the Entry or ComboBox are used as the editing widget for a cell renderer. I think that it's wise not to mention it in the gtkmm tutorial, because many readers might be more confused by discussions of signals that they shall _not_ use.
I have pushed the patch, but I split it into two commits. The added screenshot files in docs/tutorial/Makefile.am are independent of the other changes. http://git.gnome.org/browse/gtkmm-documentation/commit/?id=217a3420343777130b57ef6125d392044d3a9afc http://git.gnome.org/browse/gtkmm-documentation/commit/?id=43eea25b64623fd00a763d0b8b0c97bbb3f3249d
Now it's OK again for applications to use GtkEntry's activate signal. See bug 655500, comment 15. The first commit in comment 19 should be partly undone. Gtk::Entry:: signal_key_press_event() should be replaced by Gtk::Entry::signal_activate(), but Gtk::Entry::signal_focus_out_event() is still useful. I can make a patch. (Bugzilla won't let me set the bug status to REOPENED, but I suppose it doesn't matter much if it's UNCONFIRMED instead.)
I've pushed a commit that replaces signal_key_press_event() by Entry::signal_activate() where an Enter key press shall be detected in an Entry widget. The commit also changes the "Entry" and "ComboBox with Entry" sections in the tutorial. It undoes the commit mentioned in comment 12 and part of the first commit in comment 19. http://git.gnome.org/browse/gtkmm-documentation/commit/?id=b32c854ae5f2241010870698c1148d7c5e655e1e
Thanks for that. Is that everything now, so we can leave this as fixed?
(In reply to comment #22) > Is that everything now, so we can leave this as fixed? Yes
gtk_docs.xml must be regenerated, but I suppose that will be done anyway before the next stable release of gtkmm. The new description of GtkEntry's activate signal is not yet copied to the description of Gtk::Entry::signal_activate():
I have regenerated that now. Thanks.
*** Bug 705842 has been marked as a duplicate of this bug. ***