gtk2/docs/reference/gtk/tmpl/gtkselection.sgml
Owen Taylor ff46954836 Update.
Mon Oct 14 19:16:16 2002  Owen Taylor  <otaylor@redhat.com>

        * gtk/gtk-sections.txt: Update.

        * gdk/tmpl/images.sgml gtk/tmpl/gtkmain.sgml
        gtk/tmpl/gtkselection.sgml: Remove docs that were moved
        the the C files.
2002-10-14 23:22:58 +00:00

314 lines
7.1 KiB
Plaintext

<!-- ##### SECTION Title ##### -->
Selections
<!-- ##### SECTION Short_Description ##### -->
Functions for handling inter-process communication via selections.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkWidget</term>
<listitem><para>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 ::selection_get,
::selection_received, and :selection_clear_event
signals.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GtkTargetEntry ##### -->
<para>
A #GtkTargetEntry structure represents a single type of
data than can be supplied for by a widget for a selection
or for supplied or received during drag-and-drop. It
contains a string representing the drag type, a flags
field (used only for drag and drop - see #GtkTargetFlags),
and an application assigned integer ID. The integer
ID will later be passed as a signal parameter for signals
like "selection_get". It allows the application to identify
the target type without extensive string compares.
</para>
@target:
@flags:
@info:
<!-- ##### STRUCT GtkTargetList ##### -->
<para>
A #GtkTargetList structure is a reference counted list
of #GtkTargetPair. It is used to represent the same
information as a table of #GtkTargetEntry, but in
an efficient form. This structure should be treated as
opaque.
</para>
@list:
@ref_count:
<!-- ##### STRUCT GtkTargetPair ##### -->
<para>
Internally used structure in the drag-and-drop and
selection handling code.
</para>
@target:
@flags:
@info:
<!-- ##### FUNCTION gtk_target_list_new ##### -->
<para>
Creates a new #GtkTargetList from an array of #GtkTargetEntry.
</para>
@targets: Pointer to an array of #GtkTargetEntry
@ntargets: number of entries in @targets.
@Returns: the new #GtkTargetList.
<!-- ##### FUNCTION gtk_target_list_ref ##### -->
<para>
Increases the reference count of a #GtkTargetList by one.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_target_list_unref ##### -->
<para>
Decreases the reference count of a #GtkTargetList by one.
If the resulting reference count is zero, frees the list.
</para>
@list: a #GtkTargetList
<!-- ##### FUNCTION gtk_target_list_add ##### -->
<para>
Adds another target to a #GtkTargetList.
</para>
@list: a #GtkTargetList
@target: the interned atom representing the target
@flags: the flags for this target
@info: an ID that will be passed back to the application
<!-- ##### FUNCTION gtk_target_list_add_table ##### -->
<para>
Adds a table of #GtkTargetEntry into a target list.
</para>
@list: a #GtkTargetList
@targets: the table of #GtkTargetEntry
@ntargets: number of targets in the table
<!-- ##### FUNCTION gtk_target_list_remove ##### -->
<para>
Removes a target from a target list.
</para>
@list: a #GtkTargetList
@target: the interned atom representing the target
<!-- ##### FUNCTION gtk_target_list_find ##### -->
<para>
Looks up a given target in a #GtkTargetList.
</para>
@list: a #GtkTargetList
@target: an interned atom representing the target to search for
@info: a pointer to the location to store application info for target
@Returns: %TRUE if the target was found, otherwise %FALSE
<!-- ##### FUNCTION gtk_selection_owner_set ##### -->
<para>
</para>
@widget:
@selection:
@time:
@Returns:
<!-- ##### FUNCTION gtk_selection_owner_set_for_display ##### -->
<para>
</para>
@display:
@widget:
@selection:
@time:
@Returns:
<!-- ##### FUNCTION gtk_selection_add_target ##### -->
<para>
Adds specified target to the list of supported targets for a
given widget and selection.
</para>
@widget: a #GtkTarget
@selection: the selection
@target: target to add.
@info: A unsigned integer which will be passed back to the application.
<!-- ##### FUNCTION gtk_selection_add_targets ##### -->
<para>
Adds a table of targets to the list of supported targets
for a given widget and selection.
</para>
@widget: a #GtkWidget
@selection: the selection
@targets: a table of targets to add
@ntargets: number of entries in @targets
<!-- ##### FUNCTION gtk_selection_clear_targets ##### -->
<para>
</para>
@widget:
@selection:
<!-- ##### FUNCTION gtk_selection_convert ##### -->
<para>
Requests the contents of a selection. When received,
a "selection_received" signal will be generated.
</para>
@widget: The widget which acts as requestor
@selection: Which selection to get
@target: Form of information desired (e.g., STRING)
@time: Time of request (usually of triggering event)
In emergency, you could use #GDK_CURRENT_TIME
@Returns: %TRUE if requested succeeded. %FALSE if we could not process
request. (e.g., there was already a request in process for
this widget).
<!-- ##### FUNCTION gtk_selection_data_set ##### -->
<para>
Stores new data into a #GtkSelectionData object. Should
<emphasis>only</emphasis> be called from a selection handler callback.
Zero-terminates the stored data.
</para>
@selection_data:
@type: the type of selection data
@format: format (number of bits in a unit)
@data: pointer to the data (will be copied)
@length: length of the data
<!-- ##### FUNCTION gtk_selection_data_set_text ##### -->
<para>
</para>
@selection_data:
@str:
@len:
@Returns:
<!-- ##### FUNCTION gtk_selection_data_get_text ##### -->
<para>
</para>
@selection_data:
@Returns:
<!-- ##### FUNCTION gtk_selection_data_get_targets ##### -->
<para>
</para>
@selection_data:
@targets:
@n_atoms:
@Returns:
<!-- ##### FUNCTION gtk_selection_data_targets_include_text ##### -->
<para>
</para>
@selection_data:
@Returns:
<!-- ##### FUNCTION gtk_selection_remove_all ##### -->
<para>
Removes all handlers and unsets ownership of all
selections for a widget. Called when widget is being
destroyed. This function will not generally be
called by applications.
</para>
@widget: a #GtkWidget
<!-- ##### FUNCTION gtk_selection_clear ##### -->
<para>
</para>
@widget:
@event:
@Returns:
<!-- ##### FUNCTION gtk_selection_data_copy ##### -->
<para>
Makes a copy of a #GtkSelectionData structure and its data.
</para>
@data: a pointer to a #GtkSelectionData structure.
@Returns: a pointer to a copy of @data.
<!-- ##### FUNCTION gtk_selection_data_free ##### -->
<para>
Frees a #GtkSelectionData structure returned from
gtk_selection_data_copy().
</para>
@data: a pointer to a #GtkSelectionData structure.