New chapter with a "Migration Checklist" of things people need to do to be

2004-01-22  Federico Mena Quintero  <federico@ximian.com>

	* gtk/migrating-checklist.sgml: New chapter with a "Migration
	Checklist" of things people need to do to be good citizens in the
	GTK+ world.  This is mainly a way to tell people about interesting
	APIs that they should use instead of hand-hacked approaches.

	* gtk/gtk-docs.sgml: Added migrating-checklist.sgml.

	* gtk/Makefile.am (content_files): Likewise.

4 files changed, 155 insertions, 0 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 8488675ac..21e71de68 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+2004-01-22  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/migrating-checklist.sgml: New chapter with a "Migration
+	Checklist" of things people need to do to be good citizens in the
+	GTK+ world.  This is mainly a way to tell people about interesting
+	APIs that they should use instead of hand-hacked approaches.
+
+	* gtk/gtk-docs.sgml: Added migrating-checklist.sgml.
+
+	* gtk/Makefile.am (content_files): Likewise.
+
 Thu Jan 22 01:46:45 2004  Jonathan Blandford  <jrb@gnome.org>
 
 	* gtk/tmpl/gtktreemodelsort.sgml: new introduction section.
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 0c7534d97..a40008fa1 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -87,6 +87,7 @@ content_files =					\
 	changes-2.0.sgml			\
 	compiling.sgml				\
 	framebuffer.sgml			\
+	migrating-checklist.sgml		\
 	migrating-GtkAction.sgml		\
 	migrating-GtkFileChooser.sgml		\
 	objects_grouped.sgml			\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 2632b9057..5c14e72d6 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -179,6 +179,7 @@
 <!ENTITY gtk-Questions SYSTEM "question_index.sgml">
 <!ENTITY gtk-Changes-1-2 SYSTEM "changes-1.2.sgml">
 <!ENTITY gtk-Changes-2-0 SYSTEM "changes-2.0.sgml">
+<!ENTITY gtk-migrating-checklist SYSTEM "migrating-checklist.sgml">
 <!ENTITY gtk-migrating-GtkFileChooser SYSTEM "migrating-GtkFileChooser.sgml">
 <!ENTITY gtk-migrating-GtkAction SYSTEM "migrating-GtkAction.sgml">
 <!ENTITY version SYSTEM "version.xml">
@@ -541,6 +542,7 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
       </para>
     </partintro>
 
+    &gtk-migrating-checklist;
     &gtk-Changes-1-2;
     &gtk-Changes-2-0;
     &gtk-migrating-GtkFileChooser;
diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml
new file mode 100644
index 000000000..51a1e9b31
--- /dev/null
+++ b/docs/reference/gtk/migrating-checklist.sgml
@@ -0,0 +1,141 @@
+<chapter id="gtk-migrating-checklist">
+  <title>Migration Checklist</title>
+
+  <para>
+    This chapter includes a checklist of things you need to do to
+    ensure that your programs are good citizens in the GTK+ world.  By
+    paying attention to the points in the checklist, you ensure that
+    many automatic features of GTK+ will work correctly in your
+    program.
+  </para>
+
+  <section id="checklist-popup-menu">
+    <title>Implement GtkWidget::popup_menu</title>
+
+    <formalpara>
+      <title>Why</title>
+      <para>
+	By handling this signal, you let widgets have
+	context-sensitive menus that can be invoked with the standard
+	key bindings.
+      </para>
+    </formalpara>
+
+    <para>
+      The <link
+      linkend="GtkWidget-popup-menu">GtkWidget::popup_menu</link>
+      signal instructs the widget for which it is emitted to create a
+      context-sensitive popup menu.  By default, the <link
+      linkend="gtk-bindings">key binding mechanism</link> is set to
+      emit this signal when the
+      <keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
+      or <keycap>Menu</keycap> keys are pressed while a widget has the
+      focus.  If a widget in your application shows a popup menu when
+      you press a mouse button, you can make it work as well through
+      the normal key binding mechanism in the following fahion:
+    </para>
+
+    <orderedlist>
+      <listitem>
+	<para>
+	  Write a function to create and show a popup menu.  This
+	  function needs to know the button number and the event's
+	  time to pass them to gtk_menu_popup().  You can implement
+	  such a function like this:
+	</para>
+
+	<programlisting id="do_popup_menu">
+static void
+do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
+{
+  GtkWidget *menu;
+  int button, event_time;
+
+  menu = gtk_menu_new ();
+  g_signal_connect (menu, "deactivate", 
+                    G_CALLBACK (gtk_widget_destroy), NULL);
+
+  /* ... add menu items ... */
+
+  if (event)
+    {
+      button = event->button;
+      event_time = event->time;
+    }
+  else
+    {
+      button = 0;
+      event_time = gtk_get_current_event_time ();
+    }
+
+  gtk_menu_popup (GTK_MENU (popup), NULL, NULL, NULL, NULL, 
+                  button, event_time);
+}
+	</programlisting>
+      </listitem>
+
+      <listitem>
+	<para>
+	  In your button_press handler, call this function when you
+	  need to pop up a menu:
+	</para>
+
+	<programlisting>
+static gboolean
+my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event)
+{
+  /* Ignore double-clicks and triple-clicks */
+  if (event->button == 3 &amp;&amp; event->type == GDK_BUTTON_PRESS)
+    {
+      do_popup_menu (widget, event);
+      return TRUE;
+    }
+
+  return FALSE;
+}
+	</programlisting>
+      </listitem>
+
+      <listitem>
+	<para>
+	  Implement a handler for the popup_menu signal:
+	</para>
+
+	<programlisting>
+static gboolean
+my_widget_popup_menu_handler (GtkWidget *widget)
+{
+  do_popup_menu (widget, NULL);
+  return TRUE;
+}
+	</programlisting>
+      </listitem>
+    </orderedlist>
+
+    <note>
+      <para>
+	If you do not pass a positioning function to gtk_menu_popup(),
+	it will show the menu at the mouse position by default.  This
+	is what you usually want when the menu is shown as a result of
+	pressing a mouse button.  However, if you press the
+	<keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
+	or <keycap>Menu</keycap> keys while the widget is focused, the
+	mouse cursor may not be near the widget at all.  In the <link
+	linkend="do_popup_menu">example above</link>, you may want to
+	provide your own <link
+	linkend="GtkMenuPositionFunc">menu-positioning function</link>
+	in the case where the <parameter>event</parameter> is
+	<constant>NULL</constant>.  This function should compute the
+	desired position for a menu when it is invoked through the
+	keyboard.
+      </para>
+    </note>
+  </section>
+</chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
+End:
+-->