callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Move documentation to inline comments: gdkselection

Browse Source
This commit is contained in:
Javier Jardón
2010-11-15 17:20:51 +01:00
parent 6bfdecef7a
commit 2f06ec02be
4 changed files with 185 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gdk/tmpl/.gitignore vendored
View File

@ -12,5 +12,6 @@ keys.sgml
pango_interaction.sgml pango_interaction.sgml
pixbufs.sgml pixbufs.sgml
regions.sgml regions.sgml
selections.sgml
visuals.sgml visuals.sgml
windows.sgml windows.sgml

279
docs/reference/gdk/tmpl/selections.sgml
View File

@ -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_:

75
gdk/gdkselection.c
View File

@ -32,6 +32,54 @@
#include "gdkdisplay.h" #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 gboolean
gdk_selection_owner_set (GdkWindow *owner, gdk_selection_owner_set (GdkWindow *owner,
GdkAtom selection, GdkAtom selection,
@ -43,6 +91,21 @@ gdk_selection_owner_set (GdkWindow *owner,
time, send_event); 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* GdkWindow*
gdk_selection_owner_get (GdkAtom selection) gdk_selection_owner_get (GdkAtom selection)
{ {
@ -50,6 +113,18 @@ gdk_selection_owner_get (GdkAtom selection)
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 void
gdk_selection_send_notify (GdkNativeWindow requestor, gdk_selection_send_notify (GdkNativeWindow requestor,
GdkAtom selection, GdkAtom selection,

109
gdk/gdkselection.h
View File

@ -38,21 +38,116 @@ G_BEGIN_DECLS
/* Predefined atoms relating to selections. In general, one will need to use /* Predefined atoms relating to selections. In general, one will need to use
* gdk_intern_atom * gdk_intern_atom
*/ */
/**
* GDK_SELECTION_PRIMARY:
*
* A #GdkAtom representing the <literal>PRIMARY</literal> selection.
*/
#define GDK_SELECTION_PRIMARY _GDK_MAKE_ATOM (1) #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) #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) #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) #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) #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) #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) #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) #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) #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) #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) #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) #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) #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) #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) #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) #define GDK_SELECTION_TYPE_STRING _GDK_MAKE_ATOM (31)
/* Selections /* Selections
@ -74,6 +169,20 @@ gboolean gdk_selection_owner_set_for_display (GdkDisplay *display,
GdkWindow *gdk_selection_owner_get_for_display (GdkDisplay *display, GdkWindow *gdk_selection_owner_get_for_display (GdkDisplay *display,
GdkAtom selection); 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, void gdk_selection_convert (GdkWindow *requestor,
GdkAtom selection, GdkAtom selection,
GdkAtom target, GdkAtom target,