gdkselection.c 12.2 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GDK - The GIMP Drawing Kit
2
3
4
5
6
7
8
9
10
11
12
13
14
 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16
17
18
19
20
21
22
23
24
 */

/*
 * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
 * file for a list of people on the GTK+ Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
 */

25
#include "config.h"
26
27
28

#include "gdkselection.h"

29
#include "gdkproperty.h"
30
#include "gdkdisplayprivate.h"
31

32

33
34
/**
 * SECTION:selections
35
 * @Short_description: Functions for transferring data between programs
36
37
 * @Title: Selections
 *
38
39
40
 * GDK’s selection functions, based on the [X selection mechanism](
 * https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html),
 * provide a way to transfer arbitrary chunks of
41
 * data between programs. A “selection” is a essentially
42
43
44
 * a named clipboard, identified by a string interned as a #GdkAtom. By
 * claiming ownership of a selection, an application indicates that it will
 * be responsible for supplying its contents. The most common selections are
45
 * `PRIMARY` and `CLIPBOARD`.
46
47
 *
 * The contents of a selection can be represented in a number of formats,
48
 * called “targets”. 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 `TARGETS`. When
51
52
 * a selection is retrieved, the data is accompanied by a type (an atom), and
 * a format (an integer, representing the number of bits per item).
53
 * See [Properties and Atoms][gdk3-Properties-and-Atoms]
54
55
56
57
58
 * for more information.
 *
 * The functions in this section only contain the lowlevel parts of the
 * selection protocol. A considerably more complicated implementation is needed
 * on top of this. GTK+ contains such an implementation in the functions in
59
 * `gtkselection.h` and programmers should use those functions
60
61
 * instead of the ones presented here. If you plan to implement selection
 * handling directly on top of the functions here, you should refer to the
62
63
64
65
66
 * [X Inter-Client Communication Conventions Manual (ICCCM)](
 * https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html).
 *
 * Note that although much of the selection API design is based on that of X,
 * it will work on other GDK backends too.
67
68
69
70
 */

/**
 * gdk_selection_owner_set:
71
 * @owner: (allow-none): a #GdkWindow or %NULL to indicate that the
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 *   the owner for the given should be unset.
 * @selection: an atom identifying a selection.
 * @time_: timestamp to use when setting the selection.
 *   If this is older than the timestamp given last
 *   time the owner was set for the given selection, the
 *   request will be ignored.
 * @send_event: if %TRUE, and the new owner is different
 *   from the current owner, the current owner
 *   will be sent a SelectionClear event.
 *
 * Sets the owner of the given selection.
 *
 * Returns: %TRUE if the selection owner was successfully
 *   changed to @owner, otherwise %FALSE.
 */
87
88
89
90
91
92
gboolean
gdk_selection_owner_set (GdkWindow *owner,
			 GdkAtom    selection,
			 guint32    time,
			 gboolean   send_event)
{
Owen Taylor's avatar
Owen Taylor committed
93
  return gdk_selection_owner_set_for_display (gdk_display_get_default (),
94
95
96
97
					      owner, selection, 
					      time, send_event);
}

98
99
100
101
102
103
/**
 * gdk_selection_owner_get:
 * @selection: an atom indentifying a selection.
 *
 * Determines the owner of the given selection.
 *
104
105
106
107
108
109
 * Returns: (nullable) (transfer none): if there is a selection owner
 *   for this window, and it is a window known to the current process,
 *   the #GdkWindow that owns the selection, otherwise %NULL. Note
 *   that the return value may be owned by a different process if a
 *   foreign window was previously created for that window, but a new
 *   foreign window will never be created by this call.
110
 */
111
112
113
GdkWindow*
gdk_selection_owner_get (GdkAtom selection)
{
Owen Taylor's avatar
Owen Taylor committed
114
  return gdk_selection_owner_get_for_display (gdk_display_get_default (), 
115
116
117
					      selection);
}

118
119
120
121
122
123
124
125
126
127
128
129
/**
 * gdk_selection_send_notify:
 * @requestor: window to which to deliver response.
 * @selection: selection that was requested.
 * @target: target that was selected.
 * @property: property in which the selection owner stored the
 *   data, or %GDK_NONE to indicate that the request
 *   was rejected.
 * @time_: timestamp.
 *
 * Sends a response to SelectionRequest event.
 */
130
void
131
gdk_selection_send_notify (GdkWindow      *requestor,
132
133
134
135
			   GdkAtom         selection,
			   GdkAtom         target,
			   GdkAtom         property,
			   guint32         time)
136
{
137
  gdk_selection_send_notify_for_display (gdk_window_get_display (requestor),
138
139
140
141
					 requestor, selection, 
					 target, property, time);
}

142
143
144
/**
 * gdk_selection_owner_set_for_display:
 * @display: the #GdkDisplay
145
 * @owner: (nullable): a #GdkWindow or %NULL to indicate that the owner for
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 *         the given should be unset
 * @selection: an atom identifying a selection
 * @time_: timestamp to use when setting the selection
 *         If this is older than the timestamp given last time the owner was
 *         set for the given selection, the request will be ignored
 * @send_event: if %TRUE, and the new owner is different from the current
 *              owner, the current owner will be sent a SelectionClear event
 *
 * Sets the #GdkWindow @owner as the current owner of the selection @selection.
 *
 * Returns: %TRUE if the selection owner was successfully changed to owner,
 *    otherwise %FALSE.
 *
 * Since: 2.2
 */
gboolean
gdk_selection_owner_set_for_display (GdkDisplay *display,
                                     GdkWindow  *owner,
                                     GdkAtom     selection,
                                     guint32     time,
                                     gboolean    send_event)
{
  g_return_val_if_fail (GDK_IS_DISPLAY (display), FALSE);
  g_return_val_if_fail (selection != GDK_NONE, FALSE);

  return GDK_DISPLAY_GET_CLASS (display)
           ->set_selection_owner (display, owner, selection, time, send_event);
}

/**
 * gdk_selection_owner_get_for_display:
 * @display: a #GdkDisplay
 * @selection: an atom indentifying a selection
 *
 * Determine the owner of the given selection.
 *
 * Note that the return value may be owned by a different
 * process if a foreign window was previously created for that
 * window, but a new foreign window will never be created by this call.
 *
186
 * Returns: (nullable) (transfer none): if there is a selection owner
187
188
189
 *    for this window, and it is a window known to the current
 *    process, the #GdkWindow that owns the selection, otherwise
 *    %NULL.
190
191
192
193
194
195
196
197
198
199
200
201
 *
 * Since: 2.2
 */
GdkWindow *
gdk_selection_owner_get_for_display (GdkDisplay *display,
                                     GdkAtom     selection)
{
  g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
  g_return_val_if_fail (selection != GDK_NONE, NULL);

  return GDK_DISPLAY_GET_CLASS (display)->get_selection_owner (display, selection);
}
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

/**
 * gdk_selection_send_notify_for_display:
 * @display: the #GdkDisplay where @requestor is realized
 * @requestor: window to which to deliver response
 * @selection: selection that was requested
 * @target: target that was selected
 * @property: property in which the selection owner stored the data,
 *            or %GDK_NONE to indicate that the request was rejected
 * @time_: timestamp
 *
 * Send a response to SelectionRequest event.
 *
 * Since: 2.2
 */
void
gdk_selection_send_notify_for_display (GdkDisplay       *display,
219
                                       GdkWindow        *requestor,
220
221
222
223
224
225
226
227
228
229
                                       GdkAtom          selection,
                                       GdkAtom          target,
                                       GdkAtom          property,
                                       guint32          time_)
{
  g_return_if_fail (GDK_IS_DISPLAY (display));

  GDK_DISPLAY_GET_CLASS (display)
    ->send_selection_notify (display, requestor, selection,target, property, time_);
}
230
231

/**
232
 * gdk_selection_property_get: (skip)
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 * @requestor: the window on which the data is stored
 * @data: location to store a pointer to the retrieved data.
       If the retrieval failed, %NULL we be stored here, otherwise, it
       will be non-%NULL and the returned data should be freed with g_free()
       when you are finished using it. The length of the
       allocated memory is one more than the length
       of the returned data, and the final byte will always
       be zero, to ensure nul-termination of strings
 * @prop_type: location to store the type of the property
 * @prop_format: location to store the format of the property
 *
 * Retrieves selection data that was stored by the selection
 * data in response to a call to gdk_selection_convert(). This function
 * will not be used by applications, who should use the #GtkClipboard
 * API instead.
 *
249
 * Returns: the length of the retrieved data.
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 */
gint
gdk_selection_property_get (GdkWindow  *requestor,
                            guchar    **data,
                            GdkAtom    *ret_type,
                            gint       *ret_format)
{
  GdkDisplay *display;

  g_return_val_if_fail (GDK_IS_WINDOW (requestor), 0);

  display = gdk_window_get_display (requestor);

  return GDK_DISPLAY_GET_CLASS (display)
           ->get_selection_property (display, requestor, data, ret_type, ret_format);
}
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281

void
gdk_selection_convert (GdkWindow *requestor,
                       GdkAtom    selection,
                       GdkAtom    target,
                       guint32    time)
{
  GdkDisplay *display;

  g_return_if_fail (selection != GDK_NONE);

  display = gdk_window_get_display (requestor);

  GDK_DISPLAY_GET_CLASS (display)
    ->convert_selection (display, requestor, selection, target, time);
}
282
283
284
285
286
287

/**
 * gdk_text_property_to_utf8_list_for_display:
 * @display:  a #GdkDisplay
 * @encoding: an atom representing the encoding of the text
 * @format:   the format of the property
288
 * @text:     (array length=length): the text to convert
289
 * @length:   the length of @text, in bytes
290
291
292
 * @list:     (out) (array zero-terminated=1): location to store the list
 *            of strings or %NULL. The list should be freed with
 *            g_strfreev().
293
294
295
296
 *
 * Converts a text property in the given encoding to
 * a list of UTF-8 strings.
 *
297
 * Returns: the number of strings in the resulting list
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 *
 * Since: 2.2
 */
gint
gdk_text_property_to_utf8_list_for_display (GdkDisplay     *display,
                                            GdkAtom         encoding,
                                            gint            format,
                                            const guchar   *text,
                                            gint            length,
                                            gchar        ***list)
{
  g_return_val_if_fail (text != NULL, 0);
  g_return_val_if_fail (length >= 0, 0);
  g_return_val_if_fail (GDK_IS_DISPLAY (display), 0);

  return GDK_DISPLAY_GET_CLASS (display)
           ->text_property_to_utf8_list (display, encoding, format, text, length, list);
}

/**
 * gdk_utf8_to_string_target:
 * @str: a UTF-8 string
 *
 * Converts an UTF-8 string into the best possible representation
 * as a STRING. The representation of characters not in STRING
 * is not specified; it may be as pseudo-escape sequences
 * \x{ABCD}, or it may be in some other form of approximation.
 *
326
327
328
329
 * Returns: (nullable): the newly-allocated string, or %NULL if the
 *          conversion failed. (It should not fail for any properly
 *          formed UTF-8 string unless system limits like memory or
 *          file descriptors are exceeded.)
330
331
332
333
334
335
336
337
 **/
gchar *
gdk_utf8_to_string_target (const gchar *str)
{
  GdkDisplay *display = gdk_display_get_default ();

  return GDK_DISPLAY_GET_CLASS (display)->utf8_to_string_target (display, str);
}