forked from AuroraMiddleware/gtk
docs: Move documentation to inline comments: gdkselection
This commit is contained in:
Javier Jardón
parent
6bfdecef7a
commit
2f06ec02be
1
docs/reference/gdk/tmpl/.gitignore
vendored
1
docs/reference/gdk/tmpl/.gitignore
vendored
@ -12,5 +12,6 @@ keys.sgml
|
||||
pango_interaction.sgml
|
||||
pixbufs.sgml
|
||||
regions.sgml
|
||||
selections.sgml
|
||||
visuals.sgml
|
||||
windows.sgml
|
||||
|
||||
@ -1,279 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
Selections
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
Functions for transfering data via the X selection mechanism
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
The X selection mechanism provides a way to transfer
|
||||
arbitrary chunks of data between programs.
|
||||
A <firstterm>selection</firstterm> 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 <literal>PRIMARY</literal> and
|
||||
<literal>CLIPBOARD</literal>.
|
||||
</para>
|
||||
<para>
|
||||
The contents of a selection can be represented in
|
||||
a number of formats, called <firstterm>targets</firstterm>.
|
||||
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
|
||||
<literal>TARGETS</literal>. 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 <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
|
||||
for more information.
|
||||
</para>
|
||||
<para>
|
||||
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 <literal>gtkselection.h</literal> 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).
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### SECTION Image ##### -->
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_PRIMARY ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>PRIMARY</literal> selection.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_SECONDARY ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>SECONDARY</literal> selection.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_CLIPBOARD ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_TARGET_BITMAP ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>BITMAP</literal> selection target.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_TARGET_COLORMAP ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_TARGET_DRAWABLE ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_TARGET_PIXMAP ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_TARGET_STRING ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>STRING</literal> selection target.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_ATOM ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>ATOM</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_BITMAP ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>BITMAP</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_COLORMAP ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_DRAWABLE ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_INTEGER ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>INTEGER</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_PIXMAP ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_WINDOW ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>WINDOW</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### MACRO GDK_SELECTION_TYPE_STRING ##### -->
|
||||
<para>
|
||||
A #GdkAtom representing the <literal>STRING</literal> selection type.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
|
||||
<para>
|
||||
Sets the owner of the given selection.
|
||||
</para>
|
||||
|
||||
@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.
|
||||
@Returns: %TRUE if the selection owner was successfully
|
||||
changed to @owner, otherwise %FALSE.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_owner_set_for_display ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@display:
|
||||
@owner:
|
||||
@selection:
|
||||
@time_:
|
||||
@send_event:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_owner_get ##### -->
|
||||
<para>
|
||||
Determines the owner of the given selection.
|
||||
</para>
|
||||
|
||||
@selection: an atom indentifying a selection.
|
||||
@Returns: 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.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_owner_get_for_display ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@display:
|
||||
@selection:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_convert ##### -->
|
||||
<para>
|
||||
Retrieves the contents of a selection in a given
|
||||
form.
|
||||
</para>
|
||||
|
||||
@requestor: a #GdkWindow.
|
||||
@selection: an atom identifying the selection to get the
|
||||
contents of.
|
||||
@target: the form in which to retrieve the selection.
|
||||
@time_: the timestamp to use when retrieving the
|
||||
selection. The selection owner may refuse the
|
||||
request if it did not own the selection at
|
||||
the time indicated by the timestamp.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_property_get ##### -->
|
||||
<para>
|
||||
</para>
|
||||
|
||||
@requestor:
|
||||
@data:
|
||||
@prop_type:
|
||||
@prop_format:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_send_notify ##### -->
|
||||
<para>
|
||||
Sends a response to SelectionRequest event.
|
||||
</para>
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gdk_selection_send_notify_for_display ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@display:
|
||||
@requestor:
|
||||
@selection:
|
||||
@target:
|
||||
@property:
|
||||
@time_:
|
||||
|
||||
|
||||
@ -32,6 +32,54 @@
|
||||
#include "gdkdisplay.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 <firstterm>selection</firstterm> 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
|
||||
* <literal>PRIMARY</literal> and <literal>CLIPBOARD</literal>.
|
||||
*
|
||||
* The contents of a selection can be represented in a number of formats,
|
||||
* called <firstterm>targets</firstterm>. 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 <literal>TARGETS</literal>. 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 <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
|
||||
* 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
|
||||
* <literal>gtkselection.h</literal> 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,
|
||||
@ -43,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: 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)
|
||||
{
|
||||
@ -50,6 +113,18 @@ 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 (GdkNativeWindow requestor,
|
||||
GdkAtom selection,
|
||||
|
||||
@ -38,21 +38,116 @@ G_BEGIN_DECLS
|
||||
/* Predefined atoms relating to selections. In general, one will need to use
|
||||
* gdk_intern_atom
|
||||
*/
|
||||
/**
|
||||
* GDK_SELECTION_PRIMARY:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>PRIMARY</literal> selection.
|
||||
*/
|
||||
#define GDK_SELECTION_PRIMARY _GDK_MAKE_ATOM (1)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_SECONDARY:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>SECONDARY</literal> selection.
|
||||
*/
|
||||
#define GDK_SELECTION_SECONDARY _GDK_MAKE_ATOM (2)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_CLIPBOARD:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
|
||||
*/
|
||||
#define GDK_SELECTION_CLIPBOARD _GDK_MAKE_ATOM (69)
|
||||
|
||||
/**
|
||||
* GDK_TARGET_BITMAP:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>BITMAP</literal> selection target.
|
||||
*/
|
||||
#define GDK_TARGET_BITMAP _GDK_MAKE_ATOM (5)
|
||||
|
||||
/**
|
||||
* GDK_TARGET_COLORMAP:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
|
||||
*/
|
||||
#define GDK_TARGET_COLORMAP _GDK_MAKE_ATOM (7)
|
||||
|
||||
/**
|
||||
* GDK_TARGET_DRAWABLE:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
|
||||
*/
|
||||
#define GDK_TARGET_DRAWABLE _GDK_MAKE_ATOM (17)
|
||||
|
||||
/**
|
||||
* GDK_TARGET_PIXMAP:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
|
||||
*/
|
||||
#define GDK_TARGET_PIXMAP _GDK_MAKE_ATOM (20)
|
||||
|
||||
/**
|
||||
* GDK_TARGET_STRING:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>STRING</literal> selection target.
|
||||
*/
|
||||
#define GDK_TARGET_STRING _GDK_MAKE_ATOM (31)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_ATOM:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>ATOM</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_ATOM _GDK_MAKE_ATOM (4)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_BITMAP:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>BITMAP</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_BITMAP _GDK_MAKE_ATOM (5)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_COLORMAP:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_COLORMAP _GDK_MAKE_ATOM (7)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_DRAWABLE:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_DRAWABLE _GDK_MAKE_ATOM (17)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_INTEGER:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>INTEGER</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_INTEGER _GDK_MAKE_ATOM (19)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_PIXMAP:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_PIXMAP _GDK_MAKE_ATOM (20)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_WINDOW:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>WINDOW</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_WINDOW _GDK_MAKE_ATOM (33)
|
||||
|
||||
/**
|
||||
* GDK_SELECTION_TYPE_STRING:
|
||||
*
|
||||
* A #GdkAtom representing the <literal>STRING</literal> selection type.
|
||||
*/
|
||||
#define GDK_SELECTION_TYPE_STRING _GDK_MAKE_ATOM (31)
|
||||
|
||||
/* Selections
|
||||
@ -74,6 +169,20 @@ gboolean gdk_selection_owner_set_for_display (GdkDisplay *display,
|
||||
GdkWindow *gdk_selection_owner_get_for_display (GdkDisplay *display,
|
||||
GdkAtom selection);
|
||||
|
||||
/**
|
||||
* gdk_selection_convert:
|
||||
* @requestor: a #GdkWindow.
|
||||
* @selection: an atom identifying the selection to get the
|
||||
* contents of.
|
||||
* @target: the form in which to retrieve the selection.
|
||||
* @time_: the timestamp to use when retrieving the
|
||||
* selection. The selection owner may refuse the
|
||||
* request if it did not own the selection at
|
||||
* the time indicated by the timestamp.
|
||||
*
|
||||
* Retrieves the contents of a selection in a given
|
||||
* form.
|
||||
*/
|
||||
void gdk_selection_convert (GdkWindow *requestor,
|
||||
GdkAtom selection,
|
||||
GdkAtom target,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user