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, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GTK+ Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 #include "config.h"
  26
  27 #include "gdkselection.h"
  28
  29 #include "gdkproperty.h"
  30 #include "gdkdisplayprivate.h"
  31
  32
  33 /**
  34  * SECTION:selections
  35  * @Short_description: Functions for transfering data via the X selection mechanism
  36  * @Title: Selections
  37  *
  38  * The X selection mechanism provides a way to transfer arbitrary chunks of
  39  * data between programs. A <firstterm>selection</firstterm> is a essentially
  40  * a named clipboard, identified by a string interned as a #GdkAtom. By
  41  * claiming ownership of a selection, an application indicates that it will
  42  * be responsible for supplying its contents. The most common selections are
  43  * <literal>PRIMARY</literal> and <literal>CLIPBOARD</literal>.
  44  *
  45  * The contents of a selection can be represented in a number of formats,
  46  * called <firstterm>targets</firstterm>. Each target is identified by an atom.
  47  * A list of all possible targets supported by the selection owner can be
  48  * retrieved by requesting the special target <literal>TARGETS</literal>. When
  49  * a selection is retrieved, the data is accompanied by a type (an atom), and
  50  * a format (an integer, representing the number of bits per item).
  51  * See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
  52  * for more information.
  53  *
  54  * The functions in this section only contain the lowlevel parts of the
  55  * selection protocol. A considerably more complicated implementation is needed
  56  * on top of this. GTK+ contains such an implementation in the functions in
  57  * <literal>gtkselection.h</literal> and programmers should use those functions
  58  * instead of the ones presented here. If you plan to implement selection
  59  * handling directly on top of the functions here, you should refer to the
  60  * X Inter-client Communication Conventions Manual (ICCCM).
  61  */
  62
  63 /**
  64  * gdk_selection_owner_set:
  65  * @owner: a #GdkWindow or %NULL to indicate that the
  66  *   the owner for the given should be unset.
  67  * @selection: an atom identifying a selection.
  68  * @time_: timestamp to use when setting the selection.
  69  *   If this is older than the timestamp given last
  70  *   time the owner was set for the given selection, the
  71  *   request will be ignored.
  72  * @send_event: if %TRUE, and the new owner is different
  73  *   from the current owner, the current owner
  74  *   will be sent a SelectionClear event.
  75  *
  76  * Sets the owner of the given selection.
  77  *
  78  * Returns: %TRUE if the selection owner was successfully
  79  *   changed to @owner, otherwise %FALSE.
  80  */
  81 gboolean
  82 gdk_selection_owner_set (GdkWindow *owner,
  83                          GdkAtom    selection,
  84                          guint32    time,
  85                          gboolean   send_event)
  86 {
  87   return gdk_selection_owner_set_for_display (gdk_display_get_default (),
  88                                               owner, selection,
  89                                               time, send_event);
  90 }
  91
  92 /**
  93  * gdk_selection_owner_get:
  94  * @selection: an atom indentifying a selection.
  95  *
  96  * Determines the owner of the given selection.
  97  *
  98  * Returns: (transfer none): if there is a selection owner for
  99  *   this window, and it is a window known to the current
 100  *   process, the #GdkWindow that owns the selection, otherwise
 101  *   %NULL. Note that the return value may be owned
 102  *   by a different process if a foreign window
 103  *   was previously created for that window, but
 104  *   a new foreign window will never be created by
 105  *   this call.
 106  */
 107 GdkWindow*
 108 gdk_selection_owner_get (GdkAtom selection)
 109 {
 110   return gdk_selection_owner_get_for_display (gdk_display_get_default (),
 111                                               selection);
 112 }
 113
 114 /**
 115  * gdk_selection_send_notify:
 116  * @requestor: window to which to deliver response.
 117  * @selection: selection that was requested.
 118  * @target: target that was selected.
 119  * @property: property in which the selection owner stored the
 120  *   data, or %GDK_NONE to indicate that the request
 121  *   was rejected.
 122  * @time_: timestamp.
 123  *
 124  * Sends a response to SelectionRequest event.
 125  */
 126 void
 127 gdk_selection_send_notify (GdkWindow      *requestor,
 128                            GdkAtom         selection,
 129                            GdkAtom         target,
 130                            GdkAtom         property,
 131                            guint32         time)
 132 {
 133   gdk_selection_send_notify_for_display (gdk_window_get_display (requestor),
 134                                          requestor, selection,
 135                                          target, property, time);
 136 }
 137
 138 /**
 139  * gdk_selection_owner_set_for_display:
 140  * @display: the #GdkDisplay
 141  * @owner: a #GdkWindow or %NULL to indicate that the owner for
 142  *         the given should be unset
 143  * @selection: an atom identifying a selection
 144  * @time_: timestamp to use when setting the selection
 145  *         If this is older than the timestamp given last time the owner was
 146  *         set for the given selection, the request will be ignored
 147  * @send_event: if %TRUE, and the new owner is different from the current
 148  *              owner, the current owner will be sent a SelectionClear event
 149  *
 150  * Sets the #GdkWindow @owner as the current owner of the selection @selection.
 151  *
 152  * Returns: %TRUE if the selection owner was successfully changed to owner,
 153  *    otherwise %FALSE.
 154  *
 155  * Since: 2.2
 156  */
 157 gboolean
 158 gdk_selection_owner_set_for_display (GdkDisplay *display,
 159                                      GdkWindow  *owner,
 160                                      GdkAtom     selection,
 161                                      guint32     time,
 162                                      gboolean    send_event)
 163 {
 164   g_return_val_if_fail (GDK_IS_DISPLAY (display), FALSE);
 165   g_return_val_if_fail (selection != GDK_NONE, FALSE);
 166
 167   return GDK_DISPLAY_GET_CLASS (display)
 168            ->set_selection_owner (display, owner, selection, time, send_event);
 169 }
 170
 171 /**
 172  * gdk_selection_owner_get_for_display:
 173  * @display: a #GdkDisplay
 174  * @selection: an atom indentifying a selection
 175  *
 176  * Determine the owner of the given selection.
 177  *
 178  * Note that the return value may be owned by a different
 179  * process if a foreign window was previously created for that
 180  * window, but a new foreign window will never be created by this call.
 181  *
 182  * Returns: (transfer none): if there is a selection owner for this window,
 183  *    and it is a window known to the current process, the #GdkWindow that
 184  *    owns the selection, otherwise %NULL.
 185  *
 186  * Since: 2.2
 187  */
 188 GdkWindow *
 189 gdk_selection_owner_get_for_display (GdkDisplay *display,
 190                                      GdkAtom     selection)
 191 {
 192   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 193   g_return_val_if_fail (selection != GDK_NONE, NULL);
 194
 195   return GDK_DISPLAY_GET_CLASS (display)->get_selection_owner (display, selection);
 196 }
 197
 198 /**
 199  * gdk_selection_send_notify_for_display:
 200  * @display: the #GdkDisplay where @requestor is realized
 201  * @requestor: window to which to deliver response
 202  * @selection: selection that was requested
 203  * @target: target that was selected
 204  * @property: property in which the selection owner stored the data,
 205  *            or %GDK_NONE to indicate that the request was rejected
 206  * @time_: timestamp
 207  *
 208  * Send a response to SelectionRequest event.
 209  *
 210  * Since: 2.2
 211  */
 212 void
 213 gdk_selection_send_notify_for_display (GdkDisplay       *display,
 214                                        GdkWindow        *requestor,
 215                                        GdkAtom          selection,
 216                                        GdkAtom          target,
 217                                        GdkAtom          property,
 218                                        guint32          time_)
 219 {
 220   g_return_if_fail (GDK_IS_DISPLAY (display));
 221
 222   GDK_DISPLAY_GET_CLASS (display)
 223     ->send_selection_notify (display, requestor, selection,target, property, time_);
 224 }
 225
 226 /**
 227  * gdk_selection_property_get: (skip)
 228  * @requestor: the window on which the data is stored
 229  * @data: location to store a pointer to the retrieved data.
 230        If the retrieval failed, %NULL we be stored here, otherwise, it
 231        will be non-%NULL and the returned data should be freed with g_free()
 232        when you are finished using it. The length of the
 233        allocated memory is one more than the length
 234        of the returned data, and the final byte will always
 235        be zero, to ensure nul-termination of strings
 236  * @prop_type: location to store the type of the property
 237  * @prop_format: location to store the format of the property
 238  *
 239  * Retrieves selection data that was stored by the selection
 240  * data in response to a call to gdk_selection_convert(). This function
 241  * will not be used by applications, who should use the #GtkClipboard
 242  * API instead.
 243  *
 244  * Return value: the length of the retrieved data.
 245  */
 246 gint
 247 gdk_selection_property_get (GdkWindow  *requestor,
 248                             guchar    **data,
 249                             GdkAtom    *ret_type,
 250                             gint       *ret_format)
 251 {
 252   GdkDisplay *display;
 253
 254   g_return_val_if_fail (GDK_IS_WINDOW (requestor), 0);
 255
 256   display = gdk_window_get_display (requestor);
 257
 258   return GDK_DISPLAY_GET_CLASS (display)
 259            ->get_selection_property (display, requestor, data, ret_type, ret_format);
 260 }
 261
 262 void
 263 gdk_selection_convert (GdkWindow *requestor,
 264                        GdkAtom    selection,
 265                        GdkAtom    target,
 266                        guint32    time)
 267 {
 268   GdkDisplay *display;
 269
 270   g_return_if_fail (selection != GDK_NONE);
 271
 272   display = gdk_window_get_display (requestor);
 273
 274   GDK_DISPLAY_GET_CLASS (display)
 275     ->convert_selection (display, requestor, selection, target, time);
 276 }
 277
 278 /**
 279  * gdk_text_property_to_utf8_list_for_display:
 280  * @display:  a #GdkDisplay
 281  * @encoding: an atom representing the encoding of the text
 282  * @format:   the format of the property
 283  * @text:     (array length=length): the text to convert
 284  * @length:   the length of @text, in bytes
 285  * @list:     (out) (array zero-terminated=1): location to store the list
 286  *            of strings or %NULL. The list should be freed with
 287  *            g_strfreev().
 288  *
 289  * Converts a text property in the given encoding to
 290  * a list of UTF-8 strings.
 291  *
 292  * Return value: the number of strings in the resulting list
 293  *
 294  * Since: 2.2
 295  */
 296 gint
 297 gdk_text_property_to_utf8_list_for_display (GdkDisplay     *display,
 298                                             GdkAtom         encoding,
 299                                             gint            format,
 300                                             const guchar   *text,
 301                                             gint            length,
 302                                             gchar        ***list)
 303 {
 304   g_return_val_if_fail (text != NULL, 0);
 305   g_return_val_if_fail (length >= 0, 0);
 306   g_return_val_if_fail (GDK_IS_DISPLAY (display), 0);
 307
 308   return GDK_DISPLAY_GET_CLASS (display)
 309            ->text_property_to_utf8_list (display, encoding, format, text, length, list);
 310 }
 311
 312 /**
 313  * gdk_utf8_to_string_target:
 314  * @str: a UTF-8 string
 315  *
 316  * Converts an UTF-8 string into the best possible representation
 317  * as a STRING. The representation of characters not in STRING
 318  * is not specified; it may be as pseudo-escape sequences
 319  * \x{ABCD}, or it may be in some other form of approximation.
 320  *
 321  * Return value: the newly-allocated string, or %NULL if the
 322  *               conversion failed. (It should not fail for
 323  *               any properly formed UTF-8 string unless system
 324  *               limits like memory or file descriptors are exceeded.)
 325  **/
 326 gchar *
 327 gdk_utf8_to_string_target (const gchar *str)
 328 {
 329   GdkDisplay *display = gdk_display_get_default ();
 330
 331   return GDK_DISPLAY_GET_CLASS (display)->utf8_to_string_target (display, str);
 332 }