[gtk+] Add appchooser docs

[Matthias Clasen <matthiasc src gnome org>]

commit 7b88b2976325b6f88719cbdd14be0d6fd2ddf981
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Jan 6 02:07:35 2011 -0500

    Add appchooser docs

 docs/reference/gtk/Makefile.am                 |    2 +
 docs/reference/gtk/images/appchooserbutton.png |  Bin 0 -> 5115 bytes
 docs/reference/gtk/images/appchooserdialog.png |  Bin 0 -> 52118 bytes
 docs/reference/gtk/visual_index.xml            |    6 ++++
 docs/tools/widgets.c                           |   35 ++++++++++++++++++++++++
 gtk/gtkappchooser.c                            |   11 +++++++
 gtk/gtkappchooserbutton.c                      |    8 +++++
 gtk/gtkappchooserdialog.c                      |   12 ++++++++
 gtk/gtkappchooserwidget.c                      |   11 +++++++
 9 files changed, 85 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 82355f5..e166f91 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -275,6 +275,8 @@ HTML_IMAGES = \
 	$(top_srcdir)/gtk/stock-icons/24/gtk-page-setup.png		\
 	$(srcdir)/images/aboutdialog.png				\
 	$(srcdir)/images/accel-label.png				\
+	$(srcdir)/images/appchooserbutton.png				\
+	$(srcdir)/images/appchooserdialog.png				\
 	$(srcdir)/images/assistant.png					\
 	$(srcdir)/images/button.png					\
 	$(srcdir)/images/check-button.png				\
diff --git a/docs/reference/gtk/images/appchooserbutton.png b/docs/reference/gtk/images/appchooserbutton.png
new file mode 100644
index 0000000..02b4800
Binary files /dev/null and b/docs/reference/gtk/images/appchooserbutton.png differ
diff --git a/docs/reference/gtk/images/appchooserdialog.png b/docs/reference/gtk/images/appchooserdialog.png
new file mode 100644
index 0000000..fd9aa70
Binary files /dev/null and b/docs/reference/gtk/images/appchooserdialog.png differ
diff --git a/docs/reference/gtk/visual_index.xml b/docs/reference/gtk/visual_index.xml
index 7a11071..b1e1fe1 100644
--- a/docs/reference/gtk/visual_index.xml
+++ b/docs/reference/gtk/visual_index.xml
@@ -30,6 +30,9 @@
   <link linkend="GtkFontButton">
     <inlinegraphic fileref="font-button.png" format="PNG"></inlinegraphic>
   </link>
+  <link linkend="GtkAppChooserButton">
+    <inlinegraphic fileref="appchooserbutton.png" format="PNG"></inlinegraphic>
+  </link>
   <link linkend="GtkFrame">
     <inlinegraphic fileref="frame.png" format="PNG"></inlinegraphic>
   </link>
@@ -123,6 +126,9 @@
   <link linkend="GtkFileChooserDialog">
     <inlinegraphic fileref="filechooser.png" format="PNG"></inlinegraphic>
   </link>
+  <link linkend="GtkAppChooserDialog">
+    <inlinegraphic fileref="appchooserdialog.png" format="PNG"></inlinegraphic>
+  </link>
   <link linkend="GtkSwitch">
     <inlinegraphic fileref="switch.png" format="PNG"></inlinegraphic>
   </link>
diff --git a/docs/tools/widgets.c b/docs/tools/widgets.c
index 7308103..e847442 100644
--- a/docs/tools/widgets.c
+++ b/docs/tools/widgets.c
@@ -1070,6 +1070,39 @@ create_assistant (void)
   return info;
 }
 
+static WidgetInfo *
+create_appchooserbutton (void)
+{
+  GtkWidget *picker;
+  GtkWidget *align, *vbox;
+
+  vbox = gtk_box_new (GTK_ORIENTATION_VERTICAL, 3);
+  align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0);
+  picker = gtk_app_chooser_button_new ("text/plain");
+  gtk_container_add (GTK_CONTAINER (align), picker);
+  gtk_box_pack_start (GTK_BOX (vbox), align, FALSE, FALSE, 0);
+  gtk_box_pack_start (GTK_BOX (vbox),
+                      gtk_label_new ("Application Button"),
+                      FALSE, FALSE, 0);
+
+  return new_widget_info ("appchooserbutton", vbox, SMALL);
+}
+
+static WidgetInfo *
+create_appchooserdialog (void)
+{
+  WidgetInfo *info;
+  GtkWidget *widget;
+
+  widget = gtk_app_chooser_dialog_new_for_content_type (NULL, 0, "image/png");
+  gtk_window_set_default_size (GTK_WINDOW (widget), 200, 300);
+
+  info = new_widget_info ("appchooserdialog", widget, ASIS);
+  info->include_decorations = TRUE;
+
+  return info;
+}
+
 GList *
 get_all_widgets (void)
 {
@@ -1117,6 +1150,8 @@ get_all_widgets (void)
   retval = g_list_prepend (retval, create_print_dialog ());
   retval = g_list_prepend (retval, create_volume_button ());
   retval = g_list_prepend (retval, create_switch ());
+  retval = g_list_prepend (retval, create_appchooserbutton ());
+  retval = g_list_prepend (retval, create_appchooserdialog ());
 
   return retval;
 }
diff --git a/gtk/gtkappchooser.c b/gtk/gtkappchooser.c
index cb630c3..c5b93c8 100644
--- a/gtk/gtkappchooser.c
+++ b/gtk/gtkappchooser.c
@@ -21,6 +21,17 @@
  * Authors: Cosimo Cecchi <ccecchi redhat com>
  */
 
+/**
+ * SECTION:gtkappchooser
+ * @Title: GtkAppChooser
+ * @Short_description: Interface implemented by widgets allowing to chooser applications
+ *
+ * #GtkAppChooser is an interface that can be implemented by widgets which
+ * allow the user to choose an application (typically for the purpose of
+ * opening a file). The main objects that implement this interface are
+ * #GtkAppChooserWidget, #GtkAppChooserDialog and #GtkAppChooserButton.
+ */
+
 #include "config.h"
 
 #include "gtkappchooser.h"
diff --git a/gtk/gtkappchooserbutton.c b/gtk/gtkappchooserbutton.c
index a956a79..586c74d 100644
--- a/gtk/gtkappchooserbutton.c
+++ b/gtk/gtkappchooserbutton.c
@@ -21,6 +21,14 @@
  * Authors: Cosimo Cecchi <ccecchi redhat com>
  */
 
+/**
+ * SECTION:gtkappchooserbutton
+ * @Title: GtkAppChooserButton
+ * @Short_description: A button to launch an application chooser dialog
+ *
+ * The #GtkAppChooserButton is a widget that lets the user select
+ * an application. It implements the #GtkAppChooser interface.
+ */
 #include "config.h"
 
 #include "gtkappchooserbutton.h"
diff --git a/gtk/gtkappchooserdialog.c b/gtk/gtkappchooserdialog.c
index 09f575a..f83eec4 100644
--- a/gtk/gtkappchooserdialog.c
+++ b/gtk/gtkappchooserdialog.c
@@ -24,6 +24,18 @@
  *          Cosimo Cecchi <ccecchi redhat com>
  */
 
+/**
+ * SECTION:gtkappchooserdialog
+ * @Title: GtkAppChooserDialog
+ * @Short_description: An application chooser dialog
+ *
+ * #GtkAppChooserDialog shows a #GtkAppChooserWidget inside a #GtkDialog.
+ *
+ * Note that #GtkAppChooserDialog does not have any interesting methods
+ * of its own. Instead, you should get the embedded #GtkAppChooserWidget
+ * using gtk_file_chooser_dialog_get_widget() and call its methods if
+ * the gneeric #GtkAppChooser interface is not sufficient for your needs.
+ */
 #include "config.h"
 
 #include "gtkappchooserdialog.h"
diff --git a/gtk/gtkappchooserwidget.c b/gtk/gtkappchooserwidget.c
index 5de7c3e..487f921 100644
--- a/gtk/gtkappchooserwidget.c
+++ b/gtk/gtkappchooserwidget.c
@@ -45,6 +45,17 @@
 #include <glib/gi18n-lib.h>
 #include <gio/gio.h>
 
+/**
+ * SECTION:gtkappchooserwidget
+ * @Title: GtkAppChooserWidget
+ * @Short_description: Application chooser widget that can be embedded in other widgets
+ *
+ * #GtkAppChooserWidget is a widget for selecting applications.
+ * It is the main building block for #GtkAppChooserDialog. Most
+ * applications only need to use the latter; but you can use
+ * this widget as part of a larger widget if you have special needs.
+ */
+
 struct _GtkAppChooserWidgetPrivate {
   GAppInfo *selected_app_info;