[gtkmm/gtkmm-3-4] ApplicationWindow: Add class documentation.

[Murray Cumming <murrayc src gnome org>]

commit b3623c3d914b88ee35ed032bcd870dadcca791da
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Sep 27 20:13:04 2012 +0200

    ApplicationWindow: Add class documentation.
    
            * gtk/src/applicationwindow.hg: Add class overview documentation
    based on the GTK+ documentation.

 ChangeLog                    |    7 +++++++
 gtk/src/applicationwindow.hg |   40 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index b6b8246..137a5a2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2012-09-27  Murray Cumming  <murrayc murrayc com>
+
+        ApplicationWindow: Add class documentation.
+
+        * gtk/src/applicationwindow.hg: Add class overview documentation
+	based on the GTK+ documentation.
+
 2012-09-18  Kjell Ahlstedt  <kjell ahlstedt bredband net>
 
 	Improve the use of _IGNORE.
diff --git a/gtk/src/applicationwindow.hg b/gtk/src/applicationwindow.hg
index 47c6733..427a35c 100644
--- a/gtk/src/applicationwindow.hg
+++ b/gtk/src/applicationwindow.hg
@@ -27,7 +27,45 @@ _PINCLUDE(gtkmm/private/window_p.h)
 namespace Gtk
 {
 
-/** TODO
+/** A Gtk::Window subclass with Gtk::Application support.
+ *
+ * ApplicationWindow is a Gtk::Window subclass that offers some
+ * extra functionality for better integration with Gtk::Application
+ * features.  Notably, it can handle both the application menu as well
+ * as the menubar. See set_app_menu() and
+ * set_menubar().
+ *
+ * This class derives from Gio::ActionGroup and Gio::ActionMap,
+ * to let you add window-specific actions that will be exported by the
+ * associated Gtk::Application, together with its application-wide
+ * actions.  Window-specific actions are prefixed with the "win."
+ * prefix and application-wide actions are prefixed with the "app."
+ * prefix.  Actions must be addressed with the prefixed name when
+ * referring to them from a Gio::MenuModel.
+ *
+ * Note that widgets that are placed inside a Gtk::ApplicationWindow
+ * can also activate these actions, if they implement the
+ * Gtk::Actionable interface.
+ *
+ * As with Gtk::Application, the GDK lock will be acquired when
+ * processing actions arriving from other processes and should therefore
+ * be held when activating actions locally (if GDK threads are enabled).
+ *
+ * The settings Gtk::Settings::property_gtk_shell_shows_app_menu() and
+ * Gtk::Settings::property_gtk_shell_shows_menubar() tell GTK+ whether the
+ * desktop environment is showing the application menu and menubar
+ * models outside the application as part of the desktop shell.
+ * For instance, on OS X, both menus will be displayed remotely;
+ * on Windows neither will be. gnome-shell (starting with version 3.4)
+ * will display the application menu, but not the menubar.
+ *
+ * If the desktop environment does not display the menubar, then
+ * Gtk::ApplicationWindow will automatically show a Gtk::MenuBar for it.
+ * (see the <a href="http://developer.gnome.org/gtk3/stable/GtkApplication.html#GtkApplication.description";>GtkApplication documentation</a> for some screenshots of how this
+ * looks on different platforms).
+ * This behaviour can be overridden with the Gtk::ApplicationWindow::property_show_menubar()
+ * property. If the desktop environment does not display the application
+ * menu, then it will automatically be included in the menubar.
  */
 class ApplicationWindow
 : public Gtk::Window,