1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Functions for handling inter-process communication via selections
7 <!-- ##### SECTION Long_Description ##### -->
10 The selection mechanism provides the basis for different types
11 of communication between processes. In particular, drag and drop and
12 #GtkClipboard work via selections. You will very seldom or
13 never need to use most of the functions in this section directly;
14 #GtkClipboard provides a nicer interface to the same functionality.
17 Some of the datatypes defined this section are used in
18 the #GtkClipboard and drag-and-drop API's as well. The
19 #GtkTargetEntry structure and #GtkTargetList objects represent
20 lists of data types that are supported when sending or
21 receiving data. The #GtkSelectionData object is used to
22 store a chunk of data along with the data type and other
23 associated information.
26 <!-- ##### SECTION See_Also ##### -->
31 <term>#GtkWidget</term>
32 <listitem><para>Much of the operation of selections happens via
33 signals for #GtkWidget. In particular, if you are
34 using the functions in this section, you may need
35 to pay attention to ::selection_get,
36 ::selection_received, and :selection_clear_event
37 signals.</para></listitem>
44 <!-- ##### STRUCT GtkTargetEntry ##### -->
46 A #GtkTargetEntry structure represents a single type of
47 data than can be supplied for by a widget for a selection
48 or for supplied or received during drag-and-drop. It
49 contains a string representing the drag type, a flags
50 field (used only for drag and drop - see #GtkTargetFlags),
51 and an application assigned integer ID. The integer
52 ID will later be passed as a signal parameter for signals
53 like "selection_get". It allows the application to identify
54 the target type without extensive string compares.
61 <!-- ##### STRUCT GtkTargetList ##### -->
63 A #GtkTargetList structure is a reference counted list
64 of #GtkTargetPair. It is used to represent the same
65 information as a table of #GtkTargetEntry, but in
66 an efficient form. This structure should be treated as
73 <!-- ##### STRUCT GtkTargetPair ##### -->
75 Internally used structure in the drag-and-drop and
76 selection handling code.
83 <!-- ##### FUNCTION gtk_target_list_new ##### -->
85 Creates a new #GtkTargetList from an array of #GtkTargetEntry.
88 @targets: Pointer to an array of #GtkTargetEntry
89 @ntargets: number of entries in @targets.
90 @Returns: the new #GtkTargetList.
93 <!-- ##### FUNCTION gtk_target_list_ref ##### -->
95 Increases the reference count of a #GtkTargetList by one.
98 @list: a #GtkTargetList
101 <!-- ##### FUNCTION gtk_target_list_unref ##### -->
103 Decreases the reference count of a #GtkTargetList by one.
104 If the resulting reference count is zero, frees the list.
107 @list: a #GtkTargetList
110 <!-- ##### FUNCTION gtk_target_list_add ##### -->
112 Adds another target to a #GtkTargetList.
115 @list: a #GtkTargetList
116 @target: the interned atom representing the target
117 @flags: the flags for this target
118 @info: an ID that will be passed back to the application
121 <!-- ##### FUNCTION gtk_target_list_add_table ##### -->
123 Adds a table of #GtkTargetEntry into a target list.
126 @list: a #GtkTargetList
127 @targets: the table of #GtkTargetEntry
128 @ntargets: number of targets in the table
131 <!-- ##### FUNCTION gtk_target_list_add_text_targets ##### -->
139 <!-- ##### FUNCTION gtk_target_list_remove ##### -->
141 Removes a target from a target list.
144 @list: a #GtkTargetList
145 @target: the interned atom representing the target
148 <!-- ##### FUNCTION gtk_target_list_find ##### -->
150 Looks up a given target in a #GtkTargetList.
153 @list: a #GtkTargetList
154 @target: an interned atom representing the target to search for
155 @info: a pointer to the location to store application info for target
156 @Returns: %TRUE if the target was found, otherwise %FALSE
159 <!-- ##### FUNCTION gtk_selection_owner_set ##### -->
169 <!-- ##### FUNCTION gtk_selection_owner_set_for_display ##### -->
181 <!-- ##### FUNCTION gtk_selection_add_target ##### -->
183 Adds specified target to the list of supported targets for a
184 given widget and selection.
187 @widget: a #GtkTarget
188 @selection: the selection
189 @target: target to add.
190 @info: A unsigned integer which will be passed back to the application.
193 <!-- ##### FUNCTION gtk_selection_add_targets ##### -->
195 Adds a table of targets to the list of supported targets
196 for a given widget and selection.
199 @widget: a #GtkWidget
200 @selection: the selection
201 @targets: a table of targets to add
202 @ntargets: number of entries in @targets
205 <!-- ##### FUNCTION gtk_selection_clear_targets ##### -->
214 <!-- ##### FUNCTION gtk_selection_convert ##### -->
216 Requests the contents of a selection. When received,
217 a "selection_received" signal will be generated.
220 @widget: The widget which acts as requestor
221 @selection: Which selection to get
222 @target: Form of information desired (e.g., STRING)
223 @time_: Time of request (usually of triggering event)
224 In emergency, you could use #GDK_CURRENT_TIME
225 @Returns: %TRUE if requested succeeded. %FALSE if we could not process
226 request. (e.g., there was already a request in process for
230 <!-- ##### FUNCTION gtk_selection_data_set ##### -->
232 Stores new data into a #GtkSelectionData object. Should
233 <emphasis>only</emphasis> be called from a selection handler callback.
234 Zero-terminates the stored data.
238 @type: the type of selection data
239 @format: format (number of bits in a unit)
240 @data: pointer to the data (will be copied)
241 @length: length of the data
244 <!-- ##### FUNCTION gtk_selection_data_set_text ##### -->
255 <!-- ##### FUNCTION gtk_selection_data_get_text ##### -->
264 <!-- ##### FUNCTION gtk_selection_data_get_targets ##### -->
275 <!-- ##### FUNCTION gtk_selection_data_targets_include_text ##### -->
284 <!-- ##### FUNCTION gtk_selection_remove_all ##### -->
286 Removes all handlers and unsets ownership of all
287 selections for a widget. Called when widget is being
288 destroyed. This function will not generally be
289 called by applications.
292 @widget: a #GtkWidget
295 <!-- ##### FUNCTION gtk_selection_clear ##### -->
304 <!-- ##### FUNCTION gtk_selection_data_copy ##### -->
306 Makes a copy of a #GtkSelectionData structure and its data.
309 @data: a pointer to a #GtkSelectionData structure.
310 @Returns: a pointer to a copy of @data.
313 <!-- ##### FUNCTION gtk_selection_data_free ##### -->
315 Frees a #GtkSelectionData structure returned from
316 gtk_selection_data_copy().
319 @data: a pointer to a #GtkSelectionData structure.