* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
/* This file implements most of the work of the ICCCM selection protocol.
* GTK+ at ftp://ftp.gtk.org/pub/gtk/.
*/
+/**
+ * SECTION:gtkselection
+ * @Title: Selections
+ * @Short_description: Functions for handling inter-process communication
+ * via selections
+ * @See_also: #GtkWidget - Much of the operation of selections happens via
+ * signals for #GtkWidget. In particular, if you are using the functions
+ * in this section, you may need to pay attention to
+ * #GtkWidget::selection-get, #GtkWidget::selection-received and
+ * #GtkWidget::selection-clear-event signals
+ *
+ * The selection mechanism provides the basis for different types
+ * of communication between processes. In particular, drag and drop and
+ * #GtkClipboard work via selections. You will very seldom or
+ * never need to use most of the functions in this section directly;
+ * #GtkClipboard provides a nicer interface to the same functionality.
+ *
+ * Some of the datatypes defined this section are used in
+ * the #GtkClipboard and drag-and-drop API's as well. The
+ * #GtkTargetEntry structure and #GtkTargetList objects represent
+ * lists of data types that are supported when sending or
+ * receiving data. The #GtkSelectionData object is used to
+ * store a chunk of data along with the data type and other
+ * associated information.
+ */
+
#include "config.h"
#include "gtkselection.h"
/**
* gtk_target_list_new:
- * @targets: Pointer to an array of #GtkTargetEntry
- * @ntargets: number of entries in @targets.
+ * @targets: (array length=ntargets): Pointer to an array of #GtkTargetEntry
+ * @ntargets: number of entries in @targets.
*
* Creates a new #GtkTargetList from an array of #GtkTargetEntry.
*
- * Return value: the new #GtkTargetList.
+ * Return value: (transfer full): the new #GtkTargetList.
**/
GtkTargetList *
gtk_target_list_new (const GtkTargetEntry *targets,
/**
* gtk_target_list_add_table:
* @list: a #GtkTargetList
- * @targets: the table of #GtkTargetEntry
+ * @targets: (array length=ntargets): the table of #GtkTargetEntry
* @ntargets: number of targets in the table
*
* Prepends a table of #GtkTargetEntry to a target list.
/**
* gtk_target_table_new_from_list:
* @list: a #GtkTargetList
- * @n_targets: return location for the number ot targets in the table
+ * @n_targets: (out): return location for the number ot targets in the table
*
* This function creates an #GtkTargetEntry array that contains the
* same targets as the passed %list. The returned table is newly
* allocated and should be freed using gtk_target_table_free() when no
* longer needed.
*
- * Return value: the new table.
+ * Return value: (array length=n_targets) (transfer full): the new table.
*
* Since: 2.10
**/
/**
* gtk_target_table_free:
- * @targets: a #GtkTargetEntry array
+ * @targets: (array length=n_targets): a #GtkTargetEntry array
* @n_targets: the number of entries in the array
*
* This function frees a target table as returned by
/**
* gtk_selection_owner_set_for_display:
- * @display: the #Gdkdisplay where the selection is set
- * @widget: (allow-none): new selection owner (a #GdkWidget), or %NULL.
+ * @display: the #GdkDisplay where the selection is set
+ * @widget: (allow-none): new selection owner (a #GtkWidget), or %NULL.
* @selection: an interned atom representing the selection to claim.
* @time_: timestamp with which to claim the selection
*
* gtk_selection_add_targets:
* @widget: a #GtkWidget
* @selection: the selection
- * @targets: a table of targets to add
+ * @targets: (array length=ntargets): a table of targets to add
* @ntargets: number of entries in @targets
*
* Prepends a table of targets to the list of supported targets
{
GtkWidget *owner_widget;
gpointer owner_widget_ptr;
- GtkSelectionData selection_data;
+ GtkSelectionData selection_data = {0};
selection_data.selection = selection;
selection_data.target = target;
- selection_data.data = NULL;
selection_data.length = -1;
selection_data.display = display;
*
* Retrieves the selection #GdkAtom of the selection data.
*
- * Returns: the selection #GdkAtom of the selection data.
+ * Returns: (transfer none): the selection #GdkAtom of the selection data.
*
* Since: 2.16
**/
*
* Retrieves the target of the selection.
*
- * Returns: the target of the selection.
+ * Returns: (transfer none): the target of the selection.
*
* Since: 2.14
**/
*
* Retrieves the data type of the selection.
*
- * Returns: the data type of the selection.
+ * Returns: (transfer none): the data type of the selection.
*
* Since: 2.14
**/
}
/**
- * gtk_selection_data_get_data:
+ * gtk_selection_data_get_data: (skip)
* @selection_data: a pointer to a #GtkSelectionData structure.
*
* Retrieves the raw data of the selection.
return selection_data->length;
}
+/**
+ * gtk_selection_data_get_data_with_length:
+ * @selection_data: a pointer to a #GtkSelectionData structure
+ * @length: (out): return location for length of the data segment
+ *
+ * Retrieves the raw data of the selection along with its length.
+ *
+ * Returns: (array length=length): the raw data of the selection
+ *
+ * Rename to: gtk_selection_data_get_data
+ * Since: 3.0
+ */
+const guchar*
+gtk_selection_data_get_data_with_length (const GtkSelectionData *selection_data,
+ gint *length)
+{
+ g_return_val_if_fail (selection_data != NULL, NULL);
+
+ *length = selection_data->length;
+
+ return selection_data->data;
+}
+
/**
* gtk_selection_data_get_display:
* @selection_data: a pointer to a #GtkSelectionData structure.
* @selection_data: a pointer to a #GtkSelectionData structure.
* @type: the type of selection data
* @format: format (number of bits in a unit)
- * @data: (array) (element-type guchar): pointer to the data (will be copied)
+ * @data: (array length=length): pointer to the data (will be copied)
* @length: length of the data
*
* Stores new data into a #GtkSelectionData object. Should
gint format;
gint new_length;
gboolean result = FALSE;
-
- tmp = g_strndup (str, len);
- if (gdk_utf8_to_compound_text_for_display (selection_data->display, tmp,
- &encoding, &format, &text, &new_length))
+
+#ifdef GDK_WINDOWING_X11
+ if (GDK_IS_X11_DISPLAY (selection_data->display))
{
- gtk_selection_data_set (selection_data, encoding, format, text, new_length);
- gdk_free_compound_text (text);
-
- result = TRUE;
- }
+ tmp = g_strndup (str, len);
+ if (gdk_x11_display_utf8_to_compound_text (selection_data->display, tmp,
+ &encoding, &format, &text, &new_length))
+ {
+ gtk_selection_data_set (selection_data, encoding, format, text, new_length);
+ gdk_x11_free_compound_text (text);
- g_free (tmp);
+ result = TRUE;
+ }
+ g_free (tmp);
+ }
+#endif
return result;
}
*
* Gets the contents of the selection data as a UTF-8 string.
*
- * Return value: if the selection data contained a recognized
- * text type and it could be converted to UTF-8, a newly allocated
- * string containing the converted text, otherwise %NULL.
+ * Return value: (type utf8): if the selection data contained a
+ * recognized text type and it could be converted to UTF-8, a newly
+ * allocated string containing the converted text, otherwise %NULL.
* If the result is non-%NULL it must be freed with g_free().
**/
guchar *
/**
* gtk_selection_data_set_uris:
* @selection_data: a #GtkSelectionData
- * @uris: a %NULL-terminated array of strings holding URIs
+ * @uris: (array zero-terminated=1): a %NULL-terminated array of
+ * strings holding URIs
*
* Sets the contents of the selection from a list of URIs.
* The string is converted to the form determined by
/**
* gtk_selection_data_get_targets:
* @selection_data: a #GtkSelectionData object
- * @targets: location to store an array of targets. The result
- * stored here must be freed with g_free().
+ * @targets: (out) (array length=n_atoms) (transfer container):
+ * location to store an array of targets. The result stored
+ * here must be freed with g_free().
* @n_atoms: location to store number of items in @targets.
*
* Gets the contents of @selection_data as an array of targets.
/**
* gtk_targets_include_text:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
* @n_targets: the length of @targets
*
* Determines if any of the targets in @targets can be used to
/**
* gtk_targets_include_rich_text:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
* @n_targets: the length of @targets
* @buffer: a #GtkTextBuffer
*
/**
* gtk_targets_include_image:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
* @n_targets: the length of @targets
* @writable: whether to accept only targets for which GTK+ knows
* how to convert a pixbuf into the format
/**
* gtk_targets_include_uri:
- * @targets: an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
* @n_targets: the length of @targets
*
* Determines if any of the targets in @targets can be used to
info->selection = event->selection;
info->num_incrs = 0;
-
- /* Create GdkWindow structure for the requestor */
-
-#ifdef GDK_WINDOWING_X11
- if (GDK_IS_DISPLAY_X11 (display))
- info->requestor = gdk_x11_window_foreign_new_for_display (display, event->requestor);
- else
-#endif
- info->requestor = NULL;
+ info->requestor = g_object_ref (event->requestor);
/* Determine conversions we need to perform */
if (event->target == gtk_selection_atoms[MULTIPLE])
projects / ~andy / gtk / blobdiff