Pileus Git - ~andy/gtk/blob - gdk/gdkselection.c

   1 /* GDK - The GIMP Drawing Kit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  21  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GTK+ Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include "gdkselection.h"
  30
  31 #include "gdkproperty.h"
  32 #include "gdkdisplay.h"
  33
  34
  35 /**
  36  * SECTION:selections
  37  * @Short_description: Functions for transfering data via the X selection mechanism
  38  * @Title: Selections
  39  *
  40  * The X selection mechanism provides a way to transfer arbitrary chunks of
  41  * data between programs. A <firstterm>selection</firstterm> is a essentially
  42  * a named clipboard, identified by a string interned as a #GdkAtom. By
  43  * claiming ownership of a selection, an application indicates that it will
  44  * be responsible for supplying its contents. The most common selections are
  45  * <literal>PRIMARY</literal> and <literal>CLIPBOARD</literal>.
  46  *
  47  * The contents of a selection can be represented in a number of formats,
  48  * called <firstterm>targets</firstterm>. Each target is identified by an atom.
  49  * A list of all possible targets supported by the selection owner can be
  50  * retrieved by requesting the special target <literal>TARGETS</literal>. When
  51  * a selection is retrieved, the data is accompanied by a type (an atom), and
  52  * a format (an integer, representing the number of bits per item).
  53  * See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
  54  * for more information.
  55  *
  56  * The functions in this section only contain the lowlevel parts of the
  57  * selection protocol. A considerably more complicated implementation is needed
  58  * on top of this. GTK+ contains such an implementation in the functions in
  59  * <literal>gtkselection.h</literal> and programmers should use those functions
  60  * instead of the ones presented here. If you plan to implement selection
  61  * handling directly on top of the functions here, you should refer to the
  62  * X Inter-client Communication Conventions Manual (ICCCM).
  63  */
  64
  65 /**
  66  * gdk_selection_owner_set:
  67  * @owner: a #GdkWindow or %NULL to indicate that the
  68  *   the owner for the given should be unset.
  69  * @selection: an atom identifying a selection.
  70  * @time_: timestamp to use when setting the selection.
  71  *   If this is older than the timestamp given last
  72  *   time the owner was set for the given selection, the
  73  *   request will be ignored.
  74  * @send_event: if %TRUE, and the new owner is different
  75  *   from the current owner, the current owner
  76  *   will be sent a SelectionClear event.
  77  *
  78  * Sets the owner of the given selection.
  79  *
  80  * Returns: %TRUE if the selection owner was successfully
  81  *   changed to @owner, otherwise %FALSE.
  82  */
  83 gboolean
  84 gdk_selection_owner_set (GdkWindow *owner,
  85                          GdkAtom    selection,
  86                          guint32    time,
  87                          gboolean   send_event)
  88 {
  89   return gdk_selection_owner_set_for_display (gdk_display_get_default (),
  90                                               owner, selection,
  91                                               time, send_event);
  92 }
  93
  94 /**
  95  * gdk_selection_owner_get:
  96  * @selection: an atom indentifying a selection.
  97  *
  98  * Determines the owner of the given selection.
  99  *
 100  * Returns: if there is a selection owner for this window,
 101  *   and it is a window known to the current process,
 102  *   the #GdkWindow that owns the selection, otherwise
 103  *   %NULL. Note that the return value may be owned
 104  *   by a different process if a foreign window
 105  *   was previously created for that window, but
 106  *   a new foreign window will never be created by
 107  *   this call.
 108  */
 109 GdkWindow*
 110 gdk_selection_owner_get (GdkAtom selection)
 111 {
 112   return gdk_selection_owner_get_for_display (gdk_display_get_default (),
 113                                               selection);
 114 }
 115
 116 /**
 117  * gdk_selection_send_notify:
 118  * @requestor: window to which to deliver response.
 119  * @selection: selection that was requested.
 120  * @target: target that was selected.
 121  * @property: property in which the selection owner stored the
 122  *   data, or %GDK_NONE to indicate that the request
 123  *   was rejected.
 124  * @time_: timestamp.
 125  *
 126  * Sends a response to SelectionRequest event.
 127  */
 128 void
 129 gdk_selection_send_notify (GdkNativeWindow requestor,
 130                            GdkAtom         selection,
 131                            GdkAtom         target,
 132                            GdkAtom         property,
 133                            guint32         time)
 134 {
 135   gdk_selection_send_notify_for_display (gdk_display_get_default (),
 136                                          requestor, selection,
 137                                          target, property, time);
 138 }
 139
 140 /**
 141  * gdk_text_property_to_text_list:
 142  * @encoding: an atom representing the encoding. The most common
 143  *   values for this are <literal>STRING</literal>,
 144  *   or <literal>COMPOUND_TEXT</literal>. This is
 145  *   value used as the type for the property.
 146  * @format: the format of the property.
 147  * @text: the text data.
 148  * @length: the length of the property, in items.
 149  * @list: location to store a terminated array of strings
 150  *   in the encoding of the current locale. This
 151  *   array should be freed using gdk_free_text_list().
 152  *
 153  * Converts a text string from the encoding as it is stored in
 154  * a property into an array of strings in the encoding of
 155  * the current local. (The elements of the array represent
 156  * the nul-separated elements of the original text string.)
 157  *
 158  * Returns: the number of strings stored in @list, or 0,
 159  *   if the conversion failed.
 160  */
 161 gint
 162 gdk_text_property_to_text_list (GdkAtom       encoding,
 163                                 gint          format,
 164                                 const guchar *text,
 165                                 gint          length,
 166                                 gchar      ***list)
 167 {
 168   return gdk_text_property_to_text_list_for_display (gdk_display_get_default (),
 169                                                      encoding, format, text, length, list);
 170 }
 171
 172 /**
 173  * gdk_text_property_to_utf8_list:
 174  * @encoding: an atom representing the encoding of the text
 175  * @format:   the format of the property
 176  * @text:     the text to convert
 177  * @length:   the length of @text, in bytes
 178  * @list: (allow-none):     location to store the list of strings or %NULL. The
 179  *            list should be freed with g_strfreev().
 180  *
 181  * Convert a text property in the giving encoding to
 182  * a list of UTF-8 strings.
 183  *
 184  * Return value: the number of strings in the resulting
 185  *               list.
 186  **/
 187 gint
 188 gdk_text_property_to_utf8_list (GdkAtom        encoding,
 189                                 gint           format,
 190                                 const guchar  *text,
 191                                 gint           length,
 192                                 gchar       ***list)
 193 {
 194   return gdk_text_property_to_utf8_list_for_display (gdk_display_get_default (),
 195                                                      encoding, format, text, length, list);
 196 }
 197
 198 /**
 199  * gdk_string_to_compound_text:
 200  * @str: a nul-terminated string.
 201  * @encoding: location to store the encoding atom (to be used as
 202  *   the type for the property).
 203  * @format: location to store the format for the property.
 204  * @ctext: location to store newly allocated data for the property.
 205  * @length: location to store the length of @ctext in items.
 206  *
 207  * Converts a string from the encoding of the current locale
 208  * into a form suitable for storing in a window property.
 209  *
 210  * Returns: 0 upon sucess, non-zero upon failure.
 211  */
 212 gint
 213 gdk_string_to_compound_text (const gchar *str,
 214                              GdkAtom     *encoding,
 215                              gint        *format,
 216                              guchar     **ctext,
 217                              gint        *length)
 218 {
 219   return gdk_string_to_compound_text_for_display (gdk_display_get_default (),
 220                                                   str, encoding, format,
 221                                                   ctext, length);
 222 }
 223
 224 /**
 225  * gdk_utf8_to_compound_text:
 226  * @str:      a UTF-8 string
 227  * @encoding: location to store resulting encoding
 228  * @format:   location to store format of the result
 229  * @ctext:    location to store the data of the result
 230  * @length:   location to store the length of the data
 231  *            stored in @ctext
 232  *
 233  * Convert from UTF-8 to compound text.
 234  *
 235  * Return value: %TRUE if the conversion succeeded, otherwise
 236  *               false.
 237  **/
 238 gboolean
 239 gdk_utf8_to_compound_text (const gchar *str,
 240                            GdkAtom     *encoding,
 241                            gint        *format,
 242                            guchar     **ctext,
 243                            gint        *length)
 244 {
 245   return gdk_utf8_to_compound_text_for_display (gdk_display_get_default (),
 246                                                 str, encoding, format,
 247                                                 ctext, length);
 248 }