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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
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/.
29 #include "gdkselection.h"
31 #include "gdkproperty.h"
32 #include "gdkdisplayprivate.h"
37 * @Short_description: Functions for transfering data via the X selection mechanism
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>.
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.
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).
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.
78 * Sets the owner of the given selection.
80 * Returns: %TRUE if the selection owner was successfully
81 * changed to @owner, otherwise %FALSE.
84 gdk_selection_owner_set (GdkWindow *owner,
89 return gdk_selection_owner_set_for_display (gdk_display_get_default (),
95 * gdk_selection_owner_get:
96 * @selection: an atom indentifying a selection.
98 * Determines the owner of the given selection.
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
110 gdk_selection_owner_get (GdkAtom selection)
112 return gdk_selection_owner_get_for_display (gdk_display_get_default (),
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
126 * Sends a response to SelectionRequest event.
129 gdk_selection_send_notify (GdkNativeWindow requestor,
135 gdk_selection_send_notify_for_display (gdk_display_get_default (),
136 requestor, selection,
137 target, property, time);
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().
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.)
158 * Returns: the number of strings stored in @list, or 0,
159 * if the conversion failed.
162 gdk_text_property_to_text_list (GdkAtom encoding,
168 return gdk_text_property_to_text_list_for_display (gdk_display_get_default (),
169 encoding, format, text, length, list);
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().
181 * Convert a text property in the giving encoding to
182 * a list of UTF-8 strings.
184 * Return value: the number of strings in the resulting
188 gdk_text_property_to_utf8_list (GdkAtom encoding,
194 return gdk_text_property_to_utf8_list_for_display (gdk_display_get_default (),
195 encoding, format, text, length, list);
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.
207 * Converts a string from the encoding of the current locale
208 * into a form suitable for storing in a window property.
210 * Returns: 0 upon sucess, non-zero upon failure.
213 gdk_string_to_compound_text (const gchar *str,
219 return gdk_string_to_compound_text_for_display (gdk_display_get_default (),
220 str, encoding, format,
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
233 * Convert from UTF-8 to compound text.
235 * Return value: %TRUE if the conversion succeeded, otherwise
239 gdk_utf8_to_compound_text (const gchar *str,
245 return gdk_utf8_to_compound_text_for_display (gdk_display_get_default (),
246 str, encoding, format,
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
262 * Sets the #GdkWindow @owner as the current owner of the selection @selection.
264 * Returns: %TRUE if the selection owner was successfully changed to owner,
270 gdk_selection_owner_set_for_display (GdkDisplay *display,
276 g_return_val_if_fail (GDK_IS_DISPLAY (display), FALSE);
277 g_return_val_if_fail (selection != GDK_NONE, FALSE);
279 return GDK_DISPLAY_GET_CLASS (display)
280 ->set_selection_owner (display, owner, selection, time, send_event);
284 * gdk_selection_owner_get_for_display:
285 * @display: a #GdkDisplay
286 * @selection: an atom indentifying a selection
288 * Determine the owner of the given selection.
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.
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.
301 gdk_selection_owner_get_for_display (GdkDisplay *display,
304 g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
305 g_return_val_if_fail (selection != GDK_NONE, NULL);
307 return GDK_DISPLAY_GET_CLASS (display)->get_selection_owner (display, selection);
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
320 * Send a response to SelectionRequest event.
325 gdk_selection_send_notify_for_display (GdkDisplay *display,
326 GdkNativeWindow requestor,
332 g_return_if_fail (GDK_IS_DISPLAY (display));
334 GDK_DISPLAY_GET_CLASS (display)
335 ->send_selection_notify (display, requestor, selection,target, property, time_);
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
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
356 * Return value: the length of the retrieved data.
359 gdk_selection_property_get (GdkWindow *requestor,
366 g_return_val_if_fail (GDK_IS_WINDOW (requestor), 0);
368 display = gdk_window_get_display (requestor);
370 return GDK_DISPLAY_GET_CLASS (display)
371 ->get_selection_property (display, requestor, data, ret_type, ret_format);
375 gdk_selection_convert (GdkWindow *requestor,
382 g_return_if_fail (selection != GDK_NONE);
384 display = gdk_window_get_display (requestor);
386 GDK_DISPLAY_GET_CLASS (display)
387 ->convert_selection (display, requestor, selection, target, time);