gtk+ r20929 - in trunk: . docs/reference docs/reference/gdk/tmpl gdk

[matthiasc svn gnome org]

Author: matthiasc
Date: Sat Aug  2 04:12:55 2008
New Revision: 20929
URL: http://svn.gnome.org/viewvc/gtk+?rev=20929&view=rev

Log:
Improve docs


Added:
   trunk/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml
Modified:
   trunk/ChangeLog
   trunk/docs/reference/ChangeLog
   trunk/gdk/gdkapplaunchcontext.c

Added: trunk/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/gdk/tmpl/gdkapplaunchcontext.sgml	Sat Aug  2 04:12:55 2008
@@ -0,0 +1,106 @@
+<!-- ##### SECTION Title ##### -->
+Application launching
+
+<!-- ##### SECTION Short_Description ##### -->
+startup notification for applications
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+GdkAppLaunchContext is an implementation of #GAppLaunchContext that
+handles launching an application in a graphical context. It provides
+startup notification and allows to launch applications on a specific
+screen or workspace.
+</para>
+<example>
+<title>Launching an application</title>
+<programlisting>
+GdkAppLaunchContext *context;
+
+context = gdk_app_launch_context_new (<!-- -->);
+
+gdk_app_launch_context_set_screen (my_screen);
+gdk_app_launch_context_set_timestamp (event-&gt;time);
+
+if (!g_app_info_launch_default_for_uri ("http://www.gtk.org";, context, &amp;error))
+  g_warning ("Launching failed: %s\n", error-&gt;message);
+
+g_object_unref (context);
+</programlisting>
+</example>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### TYPEDEF GdkAppLaunchContext ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_new ##### -->
+<para>
+
+</para>
+
+ Returns: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_display ##### -->
+<para>
+
+</para>
+
+ context: 
+ display: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_screen ##### -->
+<para>
+
+</para>
+
+ context: 
+ screen: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_desktop ##### -->
+<para>
+
+</para>
+
+ context: 
+ desktop: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_timestamp ##### -->
+<para>
+
+</para>
+
+ context: 
+ timestamp: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_icon ##### -->
+<para>
+
+</para>
+
+ context: 
+ icon: 
+
+
+<!-- ##### FUNCTION gdk_app_launch_context_set_icon_name ##### -->
+<para>
+
+</para>
+
+ context: 
+ icon_name: 
+
+

Modified: trunk/gdk/gdkapplaunchcontext.c
==============================================================================
--- trunk/gdk/gdkapplaunchcontext.c	(original)
+++ trunk/gdk/gdkapplaunchcontext.c	Sat Aug  2 04:12:55 2008
@@ -134,7 +134,10 @@
  *
  * Sets the screen on which applications will be launched when
  * using this context. See also gdk_app_launch_context_set_display().
+ *
  * If both @screen and @display are set, the @screen takes priority.
+ * If neither @screen or @display are set, the default screen and
+ * display are used.
  *
  * Since: 2.14
  */
@@ -163,6 +166,10 @@
  * <ulink url="http://www.freedesktop.org/Standards/wm-spec";>Extended 
  * Window Manager Hints</ulink>. 
  *
+ * When the workspace is not specified or @desktop is set to -1, 
+ * it is up to the window manager to pick one, typically it will
+ * be the current workspace.
+ *
  * Since: 2.14
  */
 void
@@ -178,7 +185,12 @@
  * @timestamp: a timestamp
  *
  * Sets the timestamp of @context. The timestamp should ideally
- * be taken from the event that triggered the launch.
+ * be taken from the event that triggered the launch. 
+ *
+ * Window managers can use this information to avoid moving the
+ * focus to the newly launched application when the user is busy
+ * typing in another window. This is also known as 'focus stealing
+ * prevention'.
  *
  * Since: 2.14
  */
@@ -218,11 +230,14 @@
  * @context: a #GdkAppLaunchContext
  * @icon_name: an icon name, or %NULL
  *
- * Sets the icon for applications that are launched with this
- * context. The @icon_name will be interpreted in the same way 
- * as the Icon field in desktop files. 
- * See also gdk_app_launch_context_set_icon(). If both @icon 
- * and @icon_name are set, the @icon_name takes priority.
+ * Sets the icon for applications that are launched with this context. 
+ * The @icon_name will be interpreted in the same way as the Icon field 
+ * in desktop files. See also gdk_app_launch_context_set_icon(). 
+ *
+ * If both @icon and @icon_name are set, the @icon_name takes priority.
+ * If neither @icon or @icon_name is set, the icon is taken from either 
+ * the file that is passed to launched application or from the #GAppInfo 
+ * for the launched application itself.
  * 
  * Since: 2.14
  */