move README.linux-fb in here

[~andy/gtk] / gtk / gtkclipboard.c

diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index ae4357f96f900a4aad46092748a6e7f08a540312..4a3f20fd65b36ba21932f8900146d67013a0cc20 100644 (file)
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -88,18 +88,37 @@ static GQuark clipboards_owned_key_id = 0;
 /**
  * gtk_clipboard_get:
  * @selection: a #GdkAtom which identifies the clipboard
- *             to use. A value of %GDK_NONE here is the
- *             same as <literal>gdk_atom_intern ("CLIPBOARD", FALSE)</literal>,
- *             and provides the default clipboard. Another
- *             common value is %GDK_SELECTION_PRIMARY, which
- *             identifies the primary X selection. 
+ *             to use.
  * 
  * Returns the clipboard object for the given selection.
+ * Cut/copy/paste menu items and keyboard shortcuts should use
+ * the default clipboard, returned by passing #GDK_NONE for @selection.
+ * The currently-selected object or text should be provided on the clipboard
+ * identified by #GDK_SELECTION_PRIMARY. Cut/copy/paste menu items
+ * conceptually copy the contents of the #GDK_SELECTION_PRIMARY clipboard
+ * to the default clipboard, i.e. they copy the selection to what the
+ * user sees as the clipboard.
+ *
+ * (Passing #GDK_NONE is the same as using <literal>gdk_atom_intern
+ * ("CLIPBOARD", FALSE)</literal>. See
+ * <ulink url="http://www.freedesktop.org/standards/clipboards.txt">
+ * http://www.freedesktop.org/standards/clipboards.txt</ulink>
+ * for a detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections
+ * under the X window system. On Win32 the #GDK_SELECTION_PRIMARY
+ * clipboard is essentially ignored.)
+ *
+ * It's possible to have arbitrary named clipboards; if you do invent
+ * new clipboards, you should prefix the selection name with an
+ * underscore (because the ICCCM requires that nonstandard atoms are
+ * underscore-prefixed), and namespace it as well. For example,
+ * if your application called "Foo" has a special-purpose
+ * clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD".
  * 
  * Return value: the appropriate clipboard object. If no
  *             clipboard already exists, a new one will
  *             be created. Once a clipboard object has
- *             been created, it is persistent for all time.
+ *             been created, it is persistent for all time and
+ *             cannot be freed.
  **/
 GtkClipboard *
 gtk_clipboard_get (GdkAtom selection)