X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gdk%2Fgdkselection.c;h=23c2cb42432d21a305a7bd9bc984791cac197d8e;hb=b8b54cdf3d86429e0ddcec6cdc3cb1756294ae97;hp=3a6b29fa014697ab30f798d12c78af4274705386;hpb=5f72921cc19d4a2cc691783330e267d320921acc;p=~andy%2Fgtk diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c index 3a6b29fa0..23c2cb424 100644 --- a/gdk/gdkselection.c +++ b/gdk/gdkselection.c @@ -24,12 +24,62 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ -#include -#include "gdkproperty.h" -#include "gdkdisplay.h" +#include "config.h" + #include "gdkselection.h" -#include "gdkalias.h" +#include "gdkproperty.h" +#include "gdkdisplayprivate.h" + + +/** + * SECTION:selections + * @Short_description: Functions for transfering data via the X selection mechanism + * @Title: Selections + * + * The X selection mechanism provides a way to transfer arbitrary chunks of + * data between programs. A selection is a essentially + * 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 + * PRIMARY and CLIPBOARD. + * + * The contents of a selection can be represented in a number of formats, + * called targets. Each target is identified by an atom. + * A list of all possible targets supported by the selection owner can be + * retrieved by requesting the special target TARGETS. When + * 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). + * See Properties and Atoms + * 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 + * gtkselection.h and programmers should use those functions + * 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 + * X Inter-client Communication Conventions Manual (ICCCM). + */ + +/** + * gdk_selection_owner_set: + * @owner: a #GdkWindow or %NULL to indicate that the + * 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. + */ gboolean gdk_selection_owner_set (GdkWindow *owner, GdkAtom selection, @@ -41,6 +91,21 @@ gdk_selection_owner_set (GdkWindow *owner, time, send_event); } +/** + * gdk_selection_owner_get: + * @selection: an atom indentifying a selection. + * + * Determines the owner of the given selection. + * + * Returns: (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. + */ GdkWindow* gdk_selection_owner_get (GdkAtom selection) { @@ -48,92 +113,222 @@ gdk_selection_owner_get (GdkAtom selection) selection); } +/** + * 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. + */ void -gdk_selection_send_notify (guint32 requestor, - GdkAtom selection, - GdkAtom target, - GdkAtom property, - guint32 time) +gdk_selection_send_notify (GdkWindow *requestor, + GdkAtom selection, + GdkAtom target, + GdkAtom property, + guint32 time) { - gdk_selection_send_notify_for_display (gdk_display_get_default (), + gdk_selection_send_notify_for_display (gdk_window_get_display (requestor), requestor, selection, target, property, time); } +/** + * gdk_selection_owner_set_for_display: + * @display: the #GdkDisplay + * @owner: a #GdkWindow or %NULL to indicate that 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 #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. + * + * Returns: (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. + * + * 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); +} + +/** + * 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, + GdkWindow *requestor, + 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_); +} + +/** + * gdk_selection_property_get: (skip) + * @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. + * + * Return value: the length of the retrieved data. + */ gint -gdk_text_property_to_text_list (GdkAtom encoding, - gint format, - const guchar *text, - gint length, - gchar ***list) +gdk_selection_property_get (GdkWindow *requestor, + guchar **data, + GdkAtom *ret_type, + gint *ret_format) { - return gdk_text_property_to_text_list_for_display (gdk_display_get_default (), - encoding, format, text, length, list); + 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); +} + +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); } /** - * gdk_text_property_to_utf8_list: + * 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 - * @text: the text to convert + * @text: (array length=length): the text to convert * @length: the length of @text, in bytes - * @list: location to store the list of strings or %NULL. The - * list should be freed with g_strfreev(). - * - * Convert a text property in the giving encoding to - * a list of UTF-8 strings. - * - * Return value: the number of strings in the resulting - * list. - **/ -gint -gdk_text_property_to_utf8_list (GdkAtom encoding, - gint format, - const guchar *text, - gint length, - gchar ***list) -{ - return gdk_text_property_to_utf8_list_for_display (gdk_display_get_default (), - encoding, format, text, length, list); -} - + * @list: (out) (array zero-terminated=1): location to store the list + * of strings or %NULL. The list should be freed with + * g_strfreev(). + * + * Converts a text property in the given encoding to + * a list of UTF-8 strings. + * + * Return value: the number of strings in the resulting list + * + * Since: 2.2 + */ gint -gdk_string_to_compound_text (const gchar *str, - GdkAtom *encoding, - gint *format, - guchar **ctext, - gint *length) +gdk_text_property_to_utf8_list_for_display (GdkDisplay *display, + GdkAtom encoding, + gint format, + const guchar *text, + gint length, + gchar ***list) { - return gdk_string_to_compound_text_for_display (gdk_display_get_default (), - str, encoding, format, - ctext, length); + 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_compound_text: - * @str: a UTF-8 string - * @encoding: location to store resulting encoding - * @format: location to store format of the result - * @ctext: location to store the data of the result - * @length: location to store the length of the data - * stored in @ctext - * - * Convert from UTF-8 to compound text. - * - * Return value: %TRUE if the conversion succeeded, otherwise - * false. + * 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. + * + * Return value: 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.) **/ -gboolean -gdk_utf8_to_compound_text (const gchar *str, - GdkAtom *encoding, - gint *format, - guchar **ctext, - gint *length) +gchar * +gdk_utf8_to_string_target (const gchar *str) { - return gdk_utf8_to_compound_text_for_display (gdk_display_get_default (), - str, encoding, format, - ctext, length); -} + GdkDisplay *display = gdk_display_get_default (); -#define __GDK_SELECTION_C__ -#include "gdkaliasdef.c" + return GDK_DISPLAY_GET_CLASS (display)->utf8_to_string_target (display, str); +}