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 "gdkdisplayprivate.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: (transfer none): if there is a selection owner for
 101  *   this window, and it is a window known to the current
 102  *   process, 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 }
 249
 250 /**
 251  * gdk_selection_owner_set_for_display:
 252  * @display: the #GdkDisplay
 253  * @owner: a #GdkWindow or %NULL to indicate that the owner for
 254  *         the given should be unset
 255  * @selection: an atom identifying a selection
 256  * @time_: timestamp to use when setting the selection
 257  *         If this is older than the timestamp given last time the owner was
 258  *         set for the given selection, the request will be ignored
 259  * @send_event: if %TRUE, and the new owner is different from the current
 260  *              owner, the current owner will be sent a SelectionClear event
 261  *
 262  * Sets the #GdkWindow @owner as the current owner of the selection @selection.
 263  *
 264  * Returns: %TRUE if the selection owner was successfully changed to owner,
 265  *    otherwise %FALSE.
 266  *
 267  * Since: 2.2
 268  */
 269 gboolean
 270 gdk_selection_owner_set_for_display (GdkDisplay *display,
 271                                      GdkWindow  *owner,
 272                                      GdkAtom     selection,
 273                                      guint32     time,
 274                                      gboolean    send_event)
 275 {
 276   g_return_val_if_fail (GDK_IS_DISPLAY (display), FALSE);
 277   g_return_val_if_fail (selection != GDK_NONE, FALSE);
 278
 279   return GDK_DISPLAY_GET_CLASS (display)
 280            ->set_selection_owner (display, owner, selection, time, send_event);
 281 }
 282
 283 /**
 284  * gdk_selection_owner_get_for_display:
 285  * @display: a #GdkDisplay
 286  * @selection: an atom indentifying a selection
 287  *
 288  * Determine the owner of the given selection.
 289  *
 290  * Note that the return value may be owned by a different
 291  * process if a foreign window was previously created for that
 292  * window, but a new foreign window will never be created by this call.
 293  *
 294  * Returns: (transfer none): if there is a selection owner for this window,
 295  *    and it is a window known to the current process, the #GdkWindow that
 296  *    owns the selection, otherwise %NULL.
 297  *
 298  * Since: 2.2
 299  */
 300 GdkWindow *
 301 gdk_selection_owner_get_for_display (GdkDisplay *display,
 302                                      GdkAtom     selection)
 303 {
 304   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 305   g_return_val_if_fail (selection != GDK_NONE, NULL);
 306
 307   return GDK_DISPLAY_GET_CLASS (display)->get_selection_owner (display, selection);
 308 }
 309
 310 /**
 311  * gdk_selection_send_notify_for_display:
 312  * @display: the #GdkDisplay where @requestor is realized
 313  * @requestor: window to which to deliver response
 314  * @selection: selection that was requested
 315  * @target: target that was selected
 316  * @property: property in which the selection owner stored the data,
 317  *            or %GDK_NONE to indicate that the request was rejected
 318  * @time_: timestamp
 319  *
 320  * Send a response to SelectionRequest event.
 321  *
 322  * Since: 2.2
 323  */
 324 void
 325 gdk_selection_send_notify_for_display (GdkDisplay       *display,
 326                                        GdkNativeWindow  requestor,
 327                                        GdkAtom          selection,
 328                                        GdkAtom          target,
 329                                        GdkAtom          property,
 330                                        guint32          time_)
 331 {
 332   g_return_if_fail (GDK_IS_DISPLAY (display));
 333
 334   GDK_DISPLAY_GET_CLASS (display)
 335     ->send_selection_notify (display, requestor, selection,target, property, time_);
 336 }
 337
 338 /**
 339  * gdk_selection_property_get:
 340  * @requestor: the window on which the data is stored
 341  * @data: location to store a pointer to the retrieved data.
 342        If the retrieval failed, %NULL we be stored here, otherwise, it
 343        will be non-%NULL and the returned data should be freed with g_free()
 344        when you are finished using it. The length of the
 345        allocated memory is one more than the length
 346        of the returned data, and the final byte will always
 347        be zero, to ensure nul-termination of strings
 348  * @prop_type: location to store the type of the property
 349  * @prop_format: location to store the format of the property
 350  *
 351  * Retrieves selection data that was stored by the selection
 352  * data in response to a call to gdk_selection_convert(). This function
 353  * will not be used by applications, who should use the #GtkClipboard
 354  * API instead.
 355  *
 356  * Return value: the length of the retrieved data.
 357  */
 358 gint
 359 gdk_selection_property_get (GdkWindow  *requestor,
 360                             guchar    **data,
 361                             GdkAtom    *ret_type,
 362                             gint       *ret_format)
 363 {
 364   GdkDisplay *display;
 365
 366   g_return_val_if_fail (GDK_IS_WINDOW (requestor), 0);
 367
 368   display = gdk_window_get_display (requestor);
 369
 370   return GDK_DISPLAY_GET_CLASS (display)
 371            ->get_selection_property (display, requestor, data, ret_type, ret_format);
 372 }