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 (GdkWindow      *requestor,
 130                            GdkAtom         selection,
 131                            GdkAtom         target,
 132                            GdkAtom         property,
 133                            guint32         time)
 134 {
 135   gdk_selection_send_notify_for_display (gdk_window_get_display (requestor),
 136                                          requestor, selection,
 137                                          target, property, time);
 138 }
 139
 140 /**
 141  * gdk_selection_owner_set_for_display:
 142  * @display: the #GdkDisplay
 143  * @owner: a #GdkWindow or %NULL to indicate that the owner for
 144  *         the given should be unset
 145  * @selection: an atom identifying a selection
 146  * @time_: timestamp to use when setting the selection
 147  *         If this is older than the timestamp given last time the owner was
 148  *         set for the given selection, the request will be ignored
 149  * @send_event: if %TRUE, and the new owner is different from the current
 150  *              owner, the current owner will be sent a SelectionClear event
 151  *
 152  * Sets the #GdkWindow @owner as the current owner of the selection @selection.
 153  *
 154  * Returns: %TRUE if the selection owner was successfully changed to owner,
 155  *    otherwise %FALSE.
 156  *
 157  * Since: 2.2
 158  */
 159 gboolean
 160 gdk_selection_owner_set_for_display (GdkDisplay *display,
 161                                      GdkWindow  *owner,
 162                                      GdkAtom     selection,
 163                                      guint32     time,
 164                                      gboolean    send_event)
 165 {
 166   g_return_val_if_fail (GDK_IS_DISPLAY (display), FALSE);
 167   g_return_val_if_fail (selection != GDK_NONE, FALSE);
 168
 169   return GDK_DISPLAY_GET_CLASS (display)
 170            ->set_selection_owner (display, owner, selection, time, send_event);
 171 }
 172
 173 /**
 174  * gdk_selection_owner_get_for_display:
 175  * @display: a #GdkDisplay
 176  * @selection: an atom indentifying a selection
 177  *
 178  * Determine the owner of the given selection.
 179  *
 180  * Note that the return value may be owned by a different
 181  * process if a foreign window was previously created for that
 182  * window, but a new foreign window will never be created by this call.
 183  *
 184  * Returns: (transfer none): if there is a selection owner for this window,
 185  *    and it is a window known to the current process, the #GdkWindow that
 186  *    owns the selection, otherwise %NULL.
 187  *
 188  * Since: 2.2
 189  */
 190 GdkWindow *
 191 gdk_selection_owner_get_for_display (GdkDisplay *display,
 192                                      GdkAtom     selection)
 193 {
 194   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 195   g_return_val_if_fail (selection != GDK_NONE, NULL);
 196
 197   return GDK_DISPLAY_GET_CLASS (display)->get_selection_owner (display, selection);
 198 }
 199
 200 /**
 201  * gdk_selection_send_notify_for_display:
 202  * @display: the #GdkDisplay where @requestor is realized
 203  * @requestor: window to which to deliver response
 204  * @selection: selection that was requested
 205  * @target: target that was selected
 206  * @property: property in which the selection owner stored the data,
 207  *            or %GDK_NONE to indicate that the request was rejected
 208  * @time_: timestamp
 209  *
 210  * Send a response to SelectionRequest event.
 211  *
 212  * Since: 2.2
 213  */
 214 void
 215 gdk_selection_send_notify_for_display (GdkDisplay       *display,
 216                                        GdkWindow        *requestor,
 217                                        GdkAtom          selection,
 218                                        GdkAtom          target,
 219                                        GdkAtom          property,
 220                                        guint32          time_)
 221 {
 222   g_return_if_fail (GDK_IS_DISPLAY (display));
 223
 224   GDK_DISPLAY_GET_CLASS (display)
 225     ->send_selection_notify (display, requestor, selection,target, property, time_);
 226 }
 227
 228 /**
 229  * gdk_selection_property_get: (skip)
 230  * @requestor: the window on which the data is stored
 231  * @data: location to store a pointer to the retrieved data.
 232        If the retrieval failed, %NULL we be stored here, otherwise, it
 233        will be non-%NULL and the returned data should be freed with g_free()
 234        when you are finished using it. The length of the
 235        allocated memory is one more than the length
 236        of the returned data, and the final byte will always
 237        be zero, to ensure nul-termination of strings
 238  * @prop_type: location to store the type of the property
 239  * @prop_format: location to store the format of the property
 240  *
 241  * Retrieves selection data that was stored by the selection
 242  * data in response to a call to gdk_selection_convert(). This function
 243  * will not be used by applications, who should use the #GtkClipboard
 244  * API instead.
 245  *
 246  * Return value: the length of the retrieved data.
 247  */
 248 gint
 249 gdk_selection_property_get (GdkWindow  *requestor,
 250                             guchar    **data,
 251                             GdkAtom    *ret_type,
 252                             gint       *ret_format)
 253 {
 254   GdkDisplay *display;
 255
 256   g_return_val_if_fail (GDK_IS_WINDOW (requestor), 0);
 257
 258   display = gdk_window_get_display (requestor);
 259
 260   return GDK_DISPLAY_GET_CLASS (display)
 261            ->get_selection_property (display, requestor, data, ret_type, ret_format);
 262 }
 263
 264 void
 265 gdk_selection_convert (GdkWindow *requestor,
 266                        GdkAtom    selection,
 267                        GdkAtom    target,
 268                        guint32    time)
 269 {
 270   GdkDisplay *display;
 271
 272   g_return_if_fail (selection != GDK_NONE);
 273
 274   display = gdk_window_get_display (requestor);
 275
 276   GDK_DISPLAY_GET_CLASS (display)
 277     ->convert_selection (display, requestor, selection, target, time);
 278 }
 279
 280 /**
 281  * gdk_text_property_to_utf8_list_for_display:
 282  * @display:  a #GdkDisplay
 283  * @encoding: an atom representing the encoding of the text
 284  * @format:   the format of the property
 285  * @text:     (array length=length): the text to convert
 286  * @length:   the length of @text, in bytes
 287  * @list:     (out) (array zero-terminated=1): location to store the list
 288  *            of strings or %NULL. The list should be freed with
 289  *            g_strfreev().
 290  *
 291  * Converts a text property in the given encoding to
 292  * a list of UTF-8 strings.
 293  *
 294  * Return value: the number of strings in the resulting list
 295  *
 296  * Since: 2.2
 297  */
 298 gint
 299 gdk_text_property_to_utf8_list_for_display (GdkDisplay     *display,
 300                                             GdkAtom         encoding,
 301                                             gint            format,
 302                                             const guchar   *text,
 303                                             gint            length,
 304                                             gchar        ***list)
 305 {
 306   g_return_val_if_fail (text != NULL, 0);
 307   g_return_val_if_fail (length >= 0, 0);
 308   g_return_val_if_fail (GDK_IS_DISPLAY (display), 0);
 309
 310   return GDK_DISPLAY_GET_CLASS (display)
 311            ->text_property_to_utf8_list (display, encoding, format, text, length, list);
 312 }
 313
 314 /**
 315  * gdk_utf8_to_string_target:
 316  * @str: a UTF-8 string
 317  *
 318  * Converts an UTF-8 string into the best possible representation
 319  * as a STRING. The representation of characters not in STRING
 320  * is not specified; it may be as pseudo-escape sequences
 321  * \x{ABCD}, or it may be in some other form of approximation.
 322  *
 323  * Return value: the newly-allocated string, or %NULL if the
 324  *               conversion failed. (It should not fail for
 325  *               any properly formed UTF-8 string unless system
 326  *               limits like memory or file descriptors are exceeded.)
 327  **/
 328 gchar *
 329 gdk_utf8_to_string_target (const gchar *str)
 330 {
 331   GdkDisplay *display = gdk_display_get_default ();
 332
 333   return GDK_DISPLAY_GET_CLASS (display)->utf8_to_string_target (display, str);
 334 }