[gtkmm-documentation] Entry and ComboBox with Entry sections: key_press_event -> activate.

[Kjell Ahlstedt <kjellahl src gnome org>]

commit b32c854ae5f2241010870698c1148d7c5e655e1e
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu Jun 14 10:00:49 2012 +0200

    Entry and ComboBox with Entry sections: key_press_event -> activate.
    
    * docs/tutorial/C/gtkmm-tutorial-in.xml: Entry::signal_activate() has been
    undeprecated. Describe Entry::signal_activate() instead of
    signal_key_press_event() for detecting a pressed Enter key.
    * examples/book/combobox/entry_complex/examplewindow.[h|cc]:
    * examples/book/combobox/entry_text/examplewindow.[h|cc]:
    * examples/others/cellrenderercustom/popupentry.[h|cc]: Replace
    signal_key_press_event() by Entry::signal_activate() where an Enter key press
    shall be detected. Bug #655489, comment 21.

 ChangeLog                                          |   13 +++++
 docs/tutorial/C/gtkmm-tutorial-in.xml              |   55 +++++--------------
 .../book/combobox/entry_complex/examplewindow.cc   |   21 ++-----
 .../book/combobox/entry_complex/examplewindow.h    |    2 +-
 examples/book/combobox/entry_text/examplewindow.cc |   23 +++------
 examples/book/combobox/entry_text/examplewindow.h  |    2 +-
 examples/others/cellrenderercustom/popupentry.cc   |   18 +++----
 examples/others/cellrenderercustom/popupentry.h    |    1 +
 8 files changed, 52 insertions(+), 83 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 8a05616..9c2275f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2012-06-14  Kjell Ahlstedt <kjell ahlstedt bredband net>
+
+	Entry and ComboBox with Entry sections: key_press_event -> activate.
+
+	* docs/tutorial/C/gtkmm-tutorial-in.xml: Entry::signal_activate() has been
+	undeprecated. Describe Entry::signal_activate() instead of
+	signal_key_press_event() for detecting a pressed Enter key.
+	* examples/book/combobox/entry_complex/examplewindow.[h|cc]:
+	* examples/book/combobox/entry_text/examplewindow.[h|cc]:
+	* examples/others/cellrenderercustom/popupentry.[h|cc]: Replace
+	signal_key_press_event() by Entry::signal_activate() where an Enter key press
+	shall be detected. Bug #655489, comment 21.
+
 2012-06-09  Kjell Ahlstedt <kjell ahlstedt bredband net>
 
 	Add make_screenshots.
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index e72090b..c1da853 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -1221,19 +1221,15 @@ echoed on the screen, calling <methodname>set_visibility()</methodname> with
 
 <para>
 You might want to be notified whenever the user types in a text entry widget.
-<classname>Gtk::Entry</classname> provides the <literal>changed</literal> signal
-for this purpose. It is emitted when the text in the widget changes.
-You can use it, for instance, to validate or filter the text the user types.
-</para>
-
-<para>
-The <literal>changed</literal> signal is not emitted when the user presses the
-Enter key. If a pressed Enter key signals that the user has finished entering text,
-you probably want to be notified. For this purpose, use the
-<literal>key_press_event</literal> signal that <classname>Gtk::Entry</classname>
-inherits from <classname>Gtk::Widget</classname>. Moving the keyboard focus to
-another widget may also signal that the user has finished entering text. The
-<literal>focus_out_event</literal> signal can notify you when that happens.
+<classname>Gtk::Entry</classname> provides two signals,
+<literal>activate</literal> and <literal>changed</literal>, for this purpose.
+<literal>activate</literal> is emitted when the user presses the Enter key in
+a text-entry widget; <literal>changed</literal> is emitted when the text in
+the widget changes. You can use these, for instance, to validate or filter
+the text the user types. Moving the keyboard focus to another widget may also
+signal that the user has finished entering text. The <literal>focus_out_event</literal>
+signal that <classname>Gtk::Entry</classname> inherits from
+<classname>Gtk::Widget</classname> can notify you when that happens.
 The <link linkend="sec-comboboxentry">ComboBox with an Entry</link> section
 contains example programs that use these signals.
 </para>
@@ -3085,22 +3081,20 @@ When the user enters arbitrary text, it may not be enough to connect to the
 It is not emitted when the user presses the Enter key. Pressing the Enter key or
 moving the keyboard focus to another widget may signal that the user has finished
 entering text. To be notified of these events, connect to the
-<classname>Entry</classname>'s <literal>key_press_event</literal> and
+<classname>Entry</classname>'s <literal>activate</literal> and
 <literal>focus_out_event</literal> signals, like so
 <programlisting>Gtk::Entry* entry = m_Combo.get_entry();
 if (entry)
 {
-  // The Entry shall receive key-press events and focus-out events.
-  entry->add_events(Gdk::KEY_PRESS_MASK | Gdk::FOCUS_CHANGE_MASK);
+  // The Entry shall receive focus-out events.
+  entry->add_events(Gdk::FOCUS_CHANGE_MASK);
 
   // Alternatively you can connect to m_Combo.signal_changed().
   entry->signal_changed().connect(sigc::mem_fun(*this,
     &amp;ExampleWindow::on_entry_changed) );
 
-  // This signal handler must be called before the default signal handler,
-  // or else it will not be called, if the default signal handler returns true.
-  entry->signal_key_press_event().connect(sigc::mem_fun(*this,
-    &amp;ExampleWindow::on_entry_key_press_event), /* after= */ false );
+  entry->signal_activate().connect(sigc::mem_fun(*this,
+    &amp;ExampleWindow::on_entry_activate) );
 
   entry->signal_focus_out_event().connect(sigc::mem_fun(*this,
     &amp;ExampleWindow::on_entry_focus_out_event) );
@@ -3108,29 +3102,10 @@ if (entry)
 The <literal>changed</literal> signals of <classname>ComboBox</classname> and
 <classname>Entry</classname> are both emitted for every change. It doesn't matter
 which one you connect to. But only <classname>Entry</classname>'s
-<literal>key_press_event</literal> and <literal>focus_out_event</literal> signals
-are useful here.
+<literal>focus_out_event</literal> signal is useful here.
 </para>
 <para>
-In <literal>key_press_event</literal>'s signal handler you must check which key
-has been pressed, e.g. like so
-<programlisting>bool ExampleWindow::on_entry_key_press_event(GdkEventKey* event)
-{
-  Gtk::Entry* entry = m_Combo.get_entry();
-  if (entry)
-  {
-    if (event->keyval == GDK_KEY_Return ||
-        event->keyval == GDK_KEY_ISO_Enter ||
-        event->keyval == GDK_KEY_KP_Enter)
-    {
-      input_finished(); //Your own function.
-      return true;
-    }
-  }
-  return false;
-}</programlisting>
 X events are described in more detail in the
-<link linkend="chapter-keyboardevents">Keyboard Events</link> chapter and the
 <link linkend="sec-xeventsignals">X Event signals</link> section in the appendix.
 </para>
 </sect2>
diff --git a/examples/book/combobox/entry_complex/examplewindow.cc b/examples/book/combobox/entry_complex/examplewindow.cc
index 18b9b85..f2c65a3 100644
--- a/examples/book/combobox/entry_complex/examplewindow.cc
+++ b/examples/book/combobox/entry_complex/examplewindow.cc
@@ -74,15 +74,13 @@ ExampleWindow::ExampleWindow()
   Gtk::Entry* entry = m_Combo.get_entry();
   if (entry)
   {
-    // The Entry shall receive key-press events and focus-out events.
-    entry->add_events(Gdk::KEY_PRESS_MASK | Gdk::FOCUS_CHANGE_MASK);
+    // The Entry shall receive focus-out events.
+    entry->add_events(Gdk::FOCUS_CHANGE_MASK);
     // Alternatively you can connect to m_Combo.signal_changed().
     entry->signal_changed().connect(sigc::mem_fun(*this,
       &ExampleWindow::on_entry_changed) );
-    // This signal handler must be called before the default signal handler,
-    // or else it will not be called, if the default signal handler returns true.
-    entry->signal_key_press_event().connect(sigc::mem_fun(*this,
-      &ExampleWindow::on_entry_key_press_event), false );
+    entry->signal_activate().connect(sigc::mem_fun(*this,
+      &ExampleWindow::on_entry_activate) );
     m_ConnectionFocusOut = entry->signal_focus_out_event().
       connect(sigc::mem_fun(*this, &ExampleWindow::on_entry_focus_out_event) );
   }
@@ -110,21 +108,14 @@ void ExampleWindow::on_entry_changed()
   }
 }
 
-bool ExampleWindow::on_entry_key_press_event(GdkEventKey* event)
+void ExampleWindow::on_entry_activate()
 {
   Gtk::Entry* entry = m_Combo.get_entry();
   if (entry)
   {
-    if (event->keyval == GDK_KEY_Return ||
-        event->keyval == GDK_KEY_ISO_Enter ||
-        event->keyval == GDK_KEY_KP_Enter)
-    {
-      std::cout << "on_entry_key_press_event(): Row=" << m_Combo.get_active_row_number()
+    std::cout << "on_entry_activate(): Row=" << m_Combo.get_active_row_number()
       << ", ID=" << entry->get_text() << std::endl;
-      return true;
-    }
   }
-  return false;
 }
 
 bool ExampleWindow::on_entry_focus_out_event(GdkEventFocus* /* event */)
diff --git a/examples/book/combobox/entry_complex/examplewindow.h b/examples/book/combobox/entry_complex/examplewindow.h
index ca5fcc7..dd9c894 100644
--- a/examples/book/combobox/entry_complex/examplewindow.h
+++ b/examples/book/combobox/entry_complex/examplewindow.h
@@ -32,7 +32,7 @@ public:
 protected:
   //Signal handlers:
   void on_entry_changed();
-  bool on_entry_key_press_event(GdkEventKey* event);
+  void on_entry_activate();
   bool on_entry_focus_out_event(GdkEventFocus* event);
 
   //Signal connection:
diff --git a/examples/book/combobox/entry_text/examplewindow.cc b/examples/book/combobox/entry_text/examplewindow.cc
index d137833..6b156fb 100644
--- a/examples/book/combobox/entry_text/examplewindow.cc
+++ b/examples/book/combobox/entry_text/examplewindow.cc
@@ -40,12 +40,10 @@ ExampleWindow::ExampleWindow()
     &ExampleWindow::on_combo_changed) );
   if (entry)
   {
-    // The Entry shall receive key-press events and focus-out events.
-    entry->add_events(Gdk::KEY_PRESS_MASK | Gdk::FOCUS_CHANGE_MASK);
-    // This signal handler must be called before the default signal handler,
-    // or else it will not be called, if the default signal handler returns true.
-    entry->signal_key_press_event().connect(sigc::mem_fun(*this,
-      &ExampleWindow::on_entry_key_press_event), false );
+    // The Entry shall receive focus-out events.
+    entry->add_events(Gdk::FOCUS_CHANGE_MASK);
+    entry->signal_activate().connect(sigc::mem_fun(*this,
+      &ExampleWindow::on_entry_activate) );
     m_ConnectionFocusOut = entry->signal_focus_out_event().
       connect(sigc::mem_fun(*this, &ExampleWindow::on_entry_focus_out_event) );
   }
@@ -70,17 +68,10 @@ void ExampleWindow::on_combo_changed()
     << ", Text=" << m_Combo.get_active_text() << std::endl;
 }
 
-bool ExampleWindow::on_entry_key_press_event(GdkEventKey* event)
+void ExampleWindow::on_entry_activate()
 {
-  if (event->keyval == GDK_KEY_Return ||
-      event->keyval == GDK_KEY_ISO_Enter ||
-      event->keyval == GDK_KEY_KP_Enter)
-  {
-    std::cout << "on_entry_key_press_event(): Row=" << m_Combo.get_active_row_number()
-      << ", Text=" << m_Combo.get_active_text() << std::endl;
-    return true;
-  }
-  return false;
+  std::cout << "on_entry_activate(): Row=" << m_Combo.get_active_row_number()
+    << ", Text=" << m_Combo.get_active_text() << std::endl;
 }
 
 bool ExampleWindow::on_entry_focus_out_event(GdkEventFocus* /* event */)
diff --git a/examples/book/combobox/entry_text/examplewindow.h b/examples/book/combobox/entry_text/examplewindow.h
index a3cda62..baf7e02 100644
--- a/examples/book/combobox/entry_text/examplewindow.h
+++ b/examples/book/combobox/entry_text/examplewindow.h
@@ -31,7 +31,7 @@ public:
 protected:
   //Signal handlers:
   void on_combo_changed();
-  bool on_entry_key_press_event(GdkEventKey* event);
+  void on_entry_activate();
   bool on_entry_focus_out_event(GdkEventFocus* event);
 
   //Signal connection:
diff --git a/examples/others/cellrenderercustom/popupentry.cc b/examples/others/cellrenderercustom/popupentry.cc
index 537820b..42b76e8 100644
--- a/examples/others/cellrenderercustom/popupentry.cc
+++ b/examples/others/cellrenderercustom/popupentry.cc
@@ -134,6 +134,8 @@ void PopupEntry::start_editing_vfunc(GdkEvent*)
 {
   entry_->select_region(0, -1);
 
+  // Although this is a key-binding signal, it's acceptable to use it in applications.
+  entry_->signal_activate().connect(sigc::mem_fun(*this, &Self::on_entry_activate));
   entry_->signal_key_press_event().connect(sigc::mem_fun(*this, &Self::on_entry_key_press_event), false);
 
   //TODO: Doesn't this mean that we have multiple connection, because this is never disconnected?
@@ -145,18 +147,14 @@ void PopupEntry::on_button_clicked()
   signal_arrow_clicked_.emit();
 }
 
-bool PopupEntry::on_entry_key_press_event(GdkEventKey* event)
+void PopupEntry::on_entry_activate()
 {
-  if(event->keyval == GDK_KEY_Return ||
-     event->keyval == GDK_KEY_ISO_Enter ||
-     event->keyval == GDK_KEY_KP_Enter)
-  {
-    editing_done();
-    //remove_widget(); // TODO: this line causes the widget to be removed twice -- dunno why
-
-    return true;
-  }
+  editing_done();
+  //remove_widget(); // TODO: this line causes the widget to be removed twice -- dunno why
+}
 
+bool PopupEntry::on_entry_key_press_event(GdkEventKey* event)
+{
   if(event->keyval == GDK_KEY_Escape)
   {
     editing_canceled_ = true;
diff --git a/examples/others/cellrenderercustom/popupentry.h b/examples/others/cellrenderercustom/popupentry.h
index 4118b94..8dbdcf8 100644
--- a/examples/others/cellrenderercustom/popupentry.h
+++ b/examples/others/cellrenderercustom/popupentry.h
@@ -50,6 +50,7 @@ protected:
 private:
   typedef PopupEntry Self;
 
+  void on_entry_activate();
   bool on_entry_key_press_event(GdkEventKey* event);
   void on_button_clicked();