1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
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.
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.
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/>.
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/.
27 #include "gdkselection.h"
29 #include "gdkproperty.h"
30 #include "gdkdisplayprivate.h"
35 * @Short_description: Functions for transfering data via the X selection mechanism
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>.
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.
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).
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.
76 * Sets the owner of the given selection.
78 * Returns: %TRUE if the selection owner was successfully
79 * changed to @owner, otherwise %FALSE.
82 gdk_selection_owner_set (GdkWindow *owner,
87 return gdk_selection_owner_set_for_display (gdk_display_get_default (),
93 * gdk_selection_owner_get:
94 * @selection: an atom indentifying a selection.
96 * Determines the owner of the given selection.
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
108 gdk_selection_owner_get (GdkAtom selection)
110 return gdk_selection_owner_get_for_display (gdk_display_get_default (),
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
124 * Sends a response to SelectionRequest event.
127 gdk_selection_send_notify (GdkWindow *requestor,
133 gdk_selection_send_notify_for_display (gdk_window_get_display (requestor),
134 requestor, selection,
135 target, property, time);
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
150 * Sets the #GdkWindow @owner as the current owner of the selection @selection.
152 * Returns: %TRUE if the selection owner was successfully changed to owner,
158 gdk_selection_owner_set_for_display (GdkDisplay *display,
164 g_return_val_if_fail (GDK_IS_DISPLAY (display), FALSE);
165 g_return_val_if_fail (selection != GDK_NONE, FALSE);
167 return GDK_DISPLAY_GET_CLASS (display)
168 ->set_selection_owner (display, owner, selection, time, send_event);
172 * gdk_selection_owner_get_for_display:
173 * @display: a #GdkDisplay
174 * @selection: an atom indentifying a selection
176 * Determine the owner of the given selection.
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.
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.
189 gdk_selection_owner_get_for_display (GdkDisplay *display,
192 g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
193 g_return_val_if_fail (selection != GDK_NONE, NULL);
195 return GDK_DISPLAY_GET_CLASS (display)->get_selection_owner (display, selection);
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
208 * Send a response to SelectionRequest event.
213 gdk_selection_send_notify_for_display (GdkDisplay *display,
214 GdkWindow *requestor,
220 g_return_if_fail (GDK_IS_DISPLAY (display));
222 GDK_DISPLAY_GET_CLASS (display)
223 ->send_selection_notify (display, requestor, selection,target, property, time_);
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
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
244 * Return value: the length of the retrieved data.
247 gdk_selection_property_get (GdkWindow *requestor,
254 g_return_val_if_fail (GDK_IS_WINDOW (requestor), 0);
256 display = gdk_window_get_display (requestor);
258 return GDK_DISPLAY_GET_CLASS (display)
259 ->get_selection_property (display, requestor, data, ret_type, ret_format);
263 gdk_selection_convert (GdkWindow *requestor,
270 g_return_if_fail (selection != GDK_NONE);
272 display = gdk_window_get_display (requestor);
274 GDK_DISPLAY_GET_CLASS (display)
275 ->convert_selection (display, requestor, selection, target, time);
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
289 * Converts a text property in the given encoding to
290 * a list of UTF-8 strings.
292 * Return value: the number of strings in the resulting list
297 gdk_text_property_to_utf8_list_for_display (GdkDisplay *display,
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);
308 return GDK_DISPLAY_GET_CLASS (display)
309 ->text_property_to_utf8_list (display, encoding, format, text, length, list);
313 * gdk_utf8_to_string_target:
314 * @str: a UTF-8 string
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.
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.)
327 gdk_utf8_to_string_target (const gchar *str)
329 GdkDisplay *display = gdk_display_get_default ();
331 return GDK_DISPLAY_GET_CLASS (display)->utf8_to_string_target (display, str);