AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-05 16:20:10 +00:00
Code Issues Projects Releases Wiki Activity

Documented

Browse Source 
Mon Aug 16 6:60:53 1999  Owen Taylor  <otaylor@redhat.com>

	* gdk/tmpl/properties.sgml
	  gdk/tmpl/selections.sgml
	  gdk/tmpl/input_devices.sgml: Documented

	* gdk/gdk-sections.txt: Moved around types for
	  input devices properties and selections, marked
	  a few functions as private.
This commit is contained in:
Owen Taylor 1999-08-16 22:52:53 +00:00 committed by Owen Taylor
parent 6b126f35b1
commit 0072dd5508
6 changed files with 514 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/reference/ChangeLog
View File

@ -0,0 +1,9 @@
Mon Aug 16 6:60:53 1999 Owen Taylor <otaylor@redhat.com>
* gdk/tmpl/properties.sgml
gdk/tmpl/selections.sgml
gdk/tmpl/input_devices.sgml: Documented
* gdk/gdk-sections.txt: Moved around types for
input devices properties and selections, marked
a few functions as private.

18
docs/reference/gdk/gdk-sections.txt
View File

@ -328,6 +328,7 @@ gdk_drawable_set_data
<FILE>selections</FILE>
GdkSelection
GdkSelectionType
GdkTarget
gdk_selection_owner_set
gdk_selection_owner_get
gdk_selection_convert
@ -339,9 +340,6 @@ gdk_selection_send_notify
<TITLE>Properties and Atoms</TITLE>
<FILE>properties</FILE>
GdkAtom
GdkPropertyState
GdkPropMode
GdkTarget
gdk_text_property_to_text_list
gdk_free_text_list
gdk_string_to_compound_text
@ -350,6 +348,7 @@ gdk_atom_intern
gdk_atom_name
gdk_property_get
gdk_property_change
GdkPropMode
gdk_property_delete
</SECTION>
@ -463,13 +462,11 @@ gdk_keyval_to_lower
<TITLE>Input Devices</TITLE>
<FILE>input_devices</FILE>
GDK_CORE_POINTER
GdkExtensionMode
GdkDeviceKey
GdkDeviceInfo
gdk_input_init
gdk_input_exit
gdk_input_list_devices
GdkDeviceInfo
GdkDeviceKey
gdk_input_set_extension_events
GdkExtensionMode
gdk_input_set_source
GdkInputSource
gdk_input_set_mode
@ -480,6 +477,10 @@ gdk_input_set_key
gdk_input_window_get_pointer
gdk_input_motion_events
GdkTimeCoord
<SUBSECTION Private>
gdk_input_init
gdk_input_exit
</SECTION>
<SECTION>
@ -521,6 +522,7 @@ GdkNotifyType
GdkEventFocus
GdkEventConfigure
GdkEventProperty
GdkPropertyState
GdkEventSelection
GdkEventProximity
GdkEventClient

8
docs/reference/gdk/tmpl/event_structs.sgml
View File

@ -193,6 +193,14 @@ Event Structures
@time:
@state:
<!-- ##### ENUM GdkPropertyState ##### -->
<para>
</para>
@GDK_PROPERTY_NEW_VALUE:
@GDK_PROPERTY_DELETE:
<!-- ##### STRUCT GdkEventSelection ##### -->
<para>

323
docs/reference/gdk/tmpl/input_devices.sgml
View File

@ -2,11 +2,88 @@
Input Devices
<!-- ##### SECTION Short_Description ##### -->
Functions for handling extended input devices.
<!-- ##### SECTION Long_Description ##### -->
<para>
In addition to the normal keyboard and mouse input devices, GTK+ also
contains support for <firstterm>extended input devices</firstterm>. In
particular, this support is targeted at graphics tablets. Graphics
tablets typically return sub-pixel positioning information and possibly
information about the pressure and tilt of the stylus. Under
X, the support for extended devices is done through the
<firstterm>XInput</firstterm> extension.
</para>
<para>
Because handling extended input devices may involve considerable
overhead, they need to be turned on for each #GdkWindow
individually using gdk_input_set_extension_events().
(Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()).
As an additional complication, depending on the support from
the windowing system, its possible that a normal mouse
cursor will not be displayed for a particular extension
device. If an application does not want to deal with displaying
a cursor itself, it can ask only to get extension events
from devices that will display a cursor, by passing the
%GDK_EXTENSION_EVENTS_CURSOR value to
gdk_input_set_extension_events(). Otherwise, the application
must retrieve the device information using gdk_input_list_devices(),
check the <structfield>has_cursor</structfield> field, and,
if it is %FALSE, draw a cursor itself when it receives
motion events.
</para>
<para>
Each pointing device is assigned a unique integer ID; events from a
particular device can be identified by the
<structfield>deviceid</structfield> field in the event structure. The
events generated by pointer devices have also been extended to contain
<structfield>pressure</structfield>, <structfield>xtilt</structfield>
and <structfield>ytilt</structfield> fields which contain the extended
information reported as additional <firstterm>valuators</firstterm>
from the device. The <structfield>pressure</structfield> field is a
a double value ranging from 0.0 to 1.0, while the tilt fields are
double values ranging from -1.0 to 1.0. (With -1.0 representing the
maximum title to the left or up, and 1.0 representing the maximum
tilt to the right or down.)
</para>
<para>
One additional field in each event is the
<structfield>source</structfield> field, which contains an
enumeration value describing the type of device; this currently
can be one of
%GDK_SOURCE_MOUSE,
%GDK_SOURCE_PEN,
%GDK_SOURCE_ERASER,
or %GDK_SOURCE_CURSOR. This field is present to allow simple
applications to (for instance) delete when they detect eraser
devices without having to keep track of complicated per-device
settings.
</para>
<para>
Various aspects of each device may be configured. The easiest way of
creating a GUI to allow the user to conifigure such a device
is to use to use the #GtkInputDialog widget in GTK+.
However, even when using this widget, application writers
will need to directly query and set the configuration parameters
in order to save the state between invocations of the application.
The configuration of devices is queried using gdk_input_list_devices.
Each device must is activated using gdk_input_set_mode(), which
also controls whether the device's range is mapped to the
entire screen or to a single window. The mapping of the valuators of
the device onto the predefined valuator types is set using
gdk_input_set_axes. And the source type for each device
can be set with gdk_input_set_source().
</para>
<para>
Devices may also have associated <firstterm>keys</firstterm>
or macro buttons. Such keys can be globally set to map
into normal X keyboard events. The mapping is set using
gdk_input_set_key().
</para>
<para>
The interfaces in this section will most likely be considerably
modified in the future to accomodate devices that may have different
sets of additional valuators than the pressure xtilt and ytilt.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,183 +93,209 @@ Input Devices
<!-- ##### MACRO GDK_CORE_POINTER ##### -->
<para>
</para>
<!-- ##### ENUM GdkExtensionMode ##### -->
<para>
</para>
@GDK_EXTENSION_EVENTS_NONE:
@GDK_EXTENSION_EVENTS_ALL:
@GDK_EXTENSION_EVENTS_CURSOR:
<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
</para>
@keyval:
@modifiers:
<!-- ##### STRUCT GdkDeviceInfo ##### -->
<para>
</para>
@deviceid:
@name:
@source:
@mode:
@has_cursor:
@num_axes:
@axes:
@num_keys:
@keys:
<!-- ##### FUNCTION gdk_input_init ##### -->
<para>
</para>
<!-- ##### FUNCTION gdk_input_exit ##### -->
<para>
This macro contains an integer value representing
the device ID for the core pointer device.
</para>
<!-- ##### FUNCTION gdk_input_list_devices ##### -->
<para>
Lists all available input devices, along with their
configuration information.
</para>
@Returns:
@Returns: A #GList of #GdkDeviceInfo structures. This list
is internal data of GTK+ and should not be modified
or freed.
<!-- ##### STRUCT GdkDeviceInfo ##### -->
<para>
The #GdkDeviceInfo structure contains information about a
device. It has the following fields:
</para>
@deviceid: a unique integer ID for this device.
@name: the human-readable name for the device.
@source: the type of device.
@mode: a value indicating whether the device is enabled and
how the device coordinates map to the screen.
@has_cursor: if %TRUE, a cursor will be displayed indicating
the current on-screen location to the user. Otherwise,
the application is responsible for drawing a cursor
itself.
@num_axes: the number of axes for this device.
@axes: a pointer to an array of GdkAxisUse values which
give the mapping of axes onto the possible valuators
for a GDK device.
@num_keys: the number of macro buttons.
@keys: a pointer to an array of #GdkDeviceKey structures
which describe what key press events are generated
for each macro button.
<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
The #GdkDeviceKey structure contains information
about the mapping of one device macro button onto
a normal X key event. It has the following fields:
</para>
@keyval: the keyval to generate when the macro button is pressed.
If this is 0, no keypress will be generated.
@modifiers: the modifiers set for the generated key event.
<!-- ##### FUNCTION gdk_input_set_extension_events ##### -->
<para>
Turns extension events on or off for a particular window,
and specifies the event mask for extension events.
</para>
@window:
@mask:
@mode:
@window: a #GdkWindow.
@mask: the event mask
@mode: the type of extension events that are desired.
<!-- ##### ENUM GdkExtensionMode ##### -->
<para>
An enumeration used to specify which extension events
are desired for a particular widget.
</para>
@GDK_EXTENSION_EVENTS_NONE: no extension events are desired.
@GDK_EXTENSION_EVENTS_ALL: all extension events are desired.
@GDK_EXTENSION_EVENTS_CURSOR: extension events are desired only if a cursor
will be displayed for the device.
<!-- ##### FUNCTION gdk_input_set_source ##### -->
<para>
Sets the source type for a device.
</para>
@deviceid:
@source:
@deviceid: the device to configure
@source: the new source type.
<!-- ##### ENUM GdkInputSource ##### -->
<para>
An enumeration describing the type of an input device
in general terms.
</para>
@GDK_SOURCE_MOUSE:
@GDK_SOURCE_PEN:
@GDK_SOURCE_ERASER:
@GDK_SOURCE_CURSOR:
@GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
pointer, even if it is something else, such as a trackball.)
@GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
@GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end
of a stylus on a graphics tablet.
@GDK_SOURCE_CURSOR: the device is a graphics tablet "puck" or similar device.
<!-- ##### FUNCTION gdk_input_set_mode ##### -->
<para>
Enables or disables a device, and determines how the
device maps onto the screen.
</para>
@deviceid:
@mode:
@Returns:
@deviceid: the device to configure.
@mode: the new mode.
@Returns: %TRUE if the device supports the given mode, otherwise
%FALSE and the device's mode is unchanged.
<!-- ##### ENUM GdkInputMode ##### -->
<para>
An enumeration that describes the mode of an input device.
</para>
@GDK_MODE_DISABLED:
@GDK_MODE_SCREEN:
@GDK_MODE_WINDOW:
@GDK_MODE_DISABLED: the device is disabled and will not report any events.
@GDK_MODE_SCREEN: the device is enabled. The device's coordinate space
maps to the entire screen.
@GDK_MODE_WINDOW: the device is enabled. The device's coordinate space
is mapped to a single window. The manner in which this window
is chosen is undefined, but it will typically be the same
way in which the focus window for key events is determined.
<!-- ##### FUNCTION gdk_input_set_axes ##### -->
<para>
Sets the mapping of the axes (valuators) of a device
onto the predefined valuator types that GTK+ understands.
</para>
@deviceid:
@axes:
@deviceid: the device to configure.
@axes: an array of GdkAxisUse. This length of this array
must match the number of axes for the device.
<!-- ##### ENUM GdkAxisUse ##### -->
<para>
An enumeration describing the way in which a device
axis (valuator) maps onto the predefined valuator
types that GTK+ understands.
</para>
@GDK_AXIS_IGNORE:
@GDK_AXIS_X:
@GDK_AXIS_Y:
@GDK_AXIS_PRESSURE:
@GDK_AXIS_XTILT:
@GDK_AXIS_YTILT:
@GDK_AXIS_LAST:
@GDK_AXIS_IGNORE: the axis is ignored.
@GDK_AXIS_X: the axis is used as the x axis.
@GDK_AXIS_Y: the axis is used as the y axis.
@GDK_AXIS_PRESSURE: the axis is used for pressure information.
@GDK_AXIS_XTILT: the axis is used for x tilt information.
@GDK_AXIS_YTILT: the axis is used for x tilt information.
@GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
<!-- ##### FUNCTION gdk_input_set_key ##### -->
<para>
Sets the key event generated when a macro button is pressed.
</para>
@deviceid:
@index:
@keyval:
@modifiers:
@deviceid: the device to configure.
@index: the index of the macro button.
@keyval: the key value for the #GdkKeypressEvent to generate.
(a value of 0 means no event will be generated.)
@modifiers: the modifier field for the generated
#GdkKeyPressEvent.
<!-- ##### FUNCTION gdk_input_window_get_pointer ##### -->
<para>
Returns information about the current position of the pointer
within a window, including extended device information.
Any of the return parameters may be %NULL, in which case,
they will be ignored.
</para>
@window:
@deviceid:
@x:
@y:
@pressure:
@xtilt:
@ytilt:
@mask:
@window: a #GdkWindow.
@deviceid: a device ID.
@x: location to store current x postion.
@y: location to store current y postion.
@pressure: location to store current pressure.
@xtilt: location to store current tilt in the x direction.
@ytilt: location to store current tilt in the y direction.
@mask: location to store the current modifier state.
<!-- ##### FUNCTION gdk_input_motion_events ##### -->
<para>
Retrieves the motion history for a given device/window pair.
</para>
@window:
@deviceid:
@start:
@stop:
@nevents_return:
@Returns:
@window: a #GdkWindow.
@deviceid: the device for which to retrieve motion history.
@start: the start time.
@stop: the stop time.
@nevents_return: location to store the number of events returned.
@Returns: a newly allocated array containing all the events
from @start to @stop. This array should be freed
with g_free() when you are finished using it.
<!-- ##### STRUCT GdkTimeCoord ##### -->
<para>
The #GdkTimeCoord structure stores a single event in a
motion history. It contains the following fields:
</para>
@time:
@x:
@y:
@pressure:
@xtilt:
@ytilt:
@time: The timestamp for this event.
@x: the x position.
@y: the y position.
@pressure: the pressure.
@xtilt: the tilt in the x direction.
@ytilt: the tilt in the y direction.

222
docs/reference/gdk/tmpl/properties.sgml
View File

@ -2,11 +2,39 @@
Properties and Atoms
<!-- ##### SECTION Short_Description ##### -->
functions to manipulate properties on windows.
<!-- ##### SECTION Long_Description ##### -->
<para>
Each window under X can have any number of associated
<firstterm>properties</firstterm> attached to it.
Properties are arbitrary chunks of data identified by
<firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
is a numeric index into a string table on the X server. They are used
to transfer strings efficiently between clients without
having to transfer the entire string.) A property
has an associated type, which is also identified
using an atom.
</para>
<para>
A property has an associated <firstterm>format</firstterm>,
an integer describing how many bits are in each unit
of data inside the property. It must be 8, 16, or 32.
When data is transfered between the server and client,
if they are of different endianesses it will be byteswapped
as necessary according to the format of the property.
Note that on the client side, properties of format 32
will be stored with one unit per <emphasis>long</emphasis>,
even if a long integer has more than 32 bits on the platform.
(This decision was apparently made for Xlib to maintain
compatibility with programs that assumed longs were 32
bits, at the expense of programs that knew better.)
</para>
<para>
The functions in this section are used to add, remove
and change properties on windows, to convert atoms
to and from strings and to manipulate some types of
data commonly stored in X window properties.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,137 +44,175 @@ Properties and Atoms
<!-- ##### TYPEDEF GdkAtom ##### -->
<para>
A numeric type representing a string as an index into a table
of strings on the X server.
</para>
<!-- ##### ENUM GdkPropertyState ##### -->
<para>
</para>
@GDK_PROPERTY_NEW_VALUE:
@GDK_PROPERTY_DELETE:
<!-- ##### ENUM GdkPropMode ##### -->
<para>
</para>
@GDK_PROP_MODE_REPLACE:
@GDK_PROP_MODE_PREPEND:
@GDK_PROP_MODE_APPEND:
<!-- ##### ENUM GdkTarget ##### -->
<para>
</para>
@GDK_TARGET_BITMAP:
@GDK_TARGET_COLORMAP:
@GDK_TARGET_DRAWABLE:
@GDK_TARGET_PIXMAP:
@GDK_TARGET_STRING:
<!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
<para>
Convert a text string from the encoding as it is stored in
a property into an array of strings in the encoding of
the current local. (The elements of the array represent
the null-separated elements of the original text string.)
</para>
@encoding:
@format:
@text:
@length:
@list:
@Returns:
@encoding: an atom representing the encoding. The most common
values for this are <literal>STRING</literal>,
or <literal>COMPOUND_TEXT</literal>. This is
value used as the type for the property.
@format: the format of the property.
@text: the text data.
@length: the length of the property, in item.s
@list: location to store a terminated array of strings
in the encoding of the current locale. This
array should be freed using gdk_free_text_list().
@Returns: the number of strings stored in @list, or 0,
if the conversion failed.
<!-- ##### FUNCTION gdk_free_text_list ##### -->
<para>
Free the array of strings created by
gdk_text_property_to_text_list().
</para>
@list:
@list: the value stored in the @list parameter by
a call to gdk_text_property_to_text_list().
<!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
<para>
Convert a string from the encoding of the current locale
into a form suitable for storing in a window property.
</para>
@str:
@encoding:
@format:
@ctext:
@length:
@Returns:
@str: a null-terminated string.
@encoding: location to store the encoding atom (to be used as the type for the property).
@format: location to store the format for the property.
@ctext: location to store newly allocated data for the property.
@length: location to store the length of @ctext in items.
@Returns: 0 upon sucess, non-zero upon failure.
<!-- ##### FUNCTION gdk_free_compound_text ##### -->
<para>
Free the data returned from gdk_string_to_compound_text().
</para>
@ctext:
@ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
<!-- ##### FUNCTION gdk_atom_intern ##### -->
<para>
Find or create an atom corresponding to a given string.
</para>
@atom_name:
@only_if_exists:
@Returns:
@atom_name: a string.
@only_if_exists: if %TRUE, do not create a new atom, but
just return the atom if it already exists.
@Returns: the atom corresponding to @atom_name, or, if
@only_if_exists is false, and an atom does not
already exists for the string, %GDK_NONE.
<!-- ##### FUNCTION gdk_atom_name ##### -->
<para>
Determine the string corresponding to an atom.
</para>
@atom:
@Returns:
@atom: a #GdkAtom.
@Returns: a newly allocated string containing the string
corresponding to @atom. When you are done
with the return value, you should free it
using g_free().
<!-- ##### FUNCTION gdk_property_get ##### -->
<para>
Retrieves a portion of the contents of a property. If the
property does not exist, then the function returns FALSE,
and %GDK_NONE will be stored in @actual_property_type.
Note: the <function>XGetWindowProperty()</function>
function that gdk_property_get()
uses has a very confusing and complicated set of semantics.
Unfortunately, gdk_property_get() makes the situation
worse instead of better (the semantics should be considered
undefined), and also prints warnings to stderr in cases where it
should return a useful error to the program. You are advised to use
<function>XGetWindowProperty()</function>
directly until a replacement function for gdk_property_get()
is provided.
</para>
@window:
@property:
@type:
@offset:
@length:
@pdelete:
@actual_property_type:
@actual_format:
@actual_length:
@data:
@Returns:
@window: a #GdkWindow.
@property: the property to retrieve.
@type: the desired property type, or 0, if any type of data
is acceptable. If this does not match the actual
type, then @actual_format and @actual_length will
be filled in, a warning will be printed to stderr
and no data will be returned.
@offset: the offset into the property at which to begin
retrieving data. (in 4 byte units!)
@length: the length of the data to delete. (in bytes, but
the actual retrieved length will be the next
integer multiple multiple of four greater than
this!)
@pdelete: if %TRUE, delete the property after retrieving the
data.
@actual_property_type: location to store the actual type of
the property.
@actual_format: location to store the actual format of the data.
@actual_length: location to store the length of the retrieved
data, in bytes.
@data: location to store a pointer to the data. The retrieved
data should be freed with g_free() when you are finished
using it.
@Returns: %TRUE if data was sucessfully received and stored
in @data, otherwise %FALSE.
<!-- ##### FUNCTION gdk_property_change ##### -->
<para>
Change the contents of a property on a window.
</para>
@window:
@property:
@type:
@format:
@mode:
@data:
@nelements:
@window: a #GdkWindow.
@property: the property to change.
@type: the new type for the property. If @mode is
%GDK_PROP_MODE_REPLACE or %GDK_PROP_MODE_APPEND, then this
must match the existing type or an error will occur.
@format: the new format for the property. If @mode is
%GDK_PROP_MODE_REPLACE or %GDK_PROP_MODE_APPEND, then this
must match the existing format or an error will occur.
@mode: a value describing how the new data is to be combined
with the current data.
@data: the data
(a <literal>guchar *</literal>
<literal>gushort *</literal>, or
<literal>gulong *</literal>, depending on @format), cast to a
<literal>guchar *</literal>.
@nelements: the number of elements of size determined by the format,
contained in @data.
<!-- ##### ENUM GdkPropMode ##### -->
<para>
Describes how existing data is combined with new data when
using gdk_property_change().
</para>
@GDK_PROP_MODE_REPLACE: the new data replaces the existing data.
@GDK_PROP_MODE_PREPEND: the new data is prepended to the existing data.
@GDK_PROP_MODE_APPEND: the new data is appended to the existing data.
<!-- ##### FUNCTION gdk_property_delete ##### -->
<para>
Delete a property from a window.
</para>
@window:
@property:
@window: a #GdkWindow.
@property: the property to delete.

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

@ -2,11 +2,43 @@
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 <xref
linkend="gdk-Properties-and-Atoms"> 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 ##### -->
@ -16,79 +48,136 @@ Selections
<!-- ##### ENUM GdkSelection ##### -->
<para>
The #GdkSelection enumeration contains predefined
atom values for several common selections.
</para>
@GDK_SELECTION_PRIMARY:
@GDK_SELECTION_SECONDARY:
@GDK_SELECTION_PRIMARY: The primary X selection. Programs
typically claim this selection when the user
selects text and paste its contents in response
to a middle button press.
@GDK_SELECTION_SECONDARY: An additional X selection.
<!-- ##### ENUM GdkSelectionType ##### -->
<para>
The #GdkSelectionType enumeration contains predefined
atom values used to represent the types of data transferred
in response to a request for a target. See the
ICCCM for details about what data should be transferred
for each of these types. Other atoms can be used,
and the recommended practice for GTK+ is to to use mime
types for this purpose. However, supporting these types
may be useful for compatibility with older programs.
</para>
@GDK_SELECTION_TYPE_ATOM:
@GDK_SELECTION_TYPE_BITMAP:
@GDK_SELECTION_TYPE_COLORMAP:
@GDK_SELECTION_TYPE_DRAWABLE:
@GDK_SELECTION_TYPE_INTEGER:
@GDK_SELECTION_TYPE_PIXMAP:
@GDK_SELECTION_TYPE_WINDOW:
@GDK_SELECTION_TYPE_STRING:
@GDK_SELECTION_TYPE_ATOM: An atom. (format 32)
@GDK_SELECTION_TYPE_BITMAP: A bitmap ID. (format 32)
@GDK_SELECTION_TYPE_COLORMAP: A colormap ID. (format 32)
@GDK_SELECTION_TYPE_DRAWABLE: A drawable ID. (format 32)
@GDK_SELECTION_TYPE_INTEGER: An integer. (format 32)
@GDK_SELECTION_TYPE_PIXMAP: A pixmap ID. (format 32)
@GDK_SELECTION_TYPE_WINDOW: A window ID. (format 32)
@GDK_SELECTION_TYPE_STRING: A string encoded
in ISO Latin-1. (With the additional of <symbol>TAB</symbol>
and <symbol>NEWLINE</symbol>.) (format 8)
<!-- ##### ENUM GdkTarget ##### -->
<para>
The #GdkTarget enumeration contains predefined atom values which are
used to describe possible targets for a selection. Other atoms can be
used, and the recommended practice for GTK+ is to to use mime types
for this purpose. However, supporting these types may be useful for
compatibility with older programs.
</para>
@GDK_TARGET_BITMAP: A bitmap ID.
@GDK_TARGET_COLORMAP: A colormap ID.
@GDK_TARGET_DRAWABLE: A drawable ID.
@GDK_TARGET_PIXMAP: A pixmap ID.
@GDK_TARGET_STRING: A string encoded in ISO Latin-1.
(With the additional of <symbol>TAB</symbol>
and <symbol>NEWLINE</symbol>.)
<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
<para>
Set the owner of the given selection.
</para>
@owner:
@selection:
@time:
@send_event:
@Returns:
@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 succesfully
changed to @owner, otherwise %FALSE.
<!-- ##### FUNCTION gdk_selection_owner_get ##### -->
<para>
Determine the owner of the given selection.
</para>
@selection:
@Returns:
@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_convert ##### -->
<para>
Retrieve the contents of a selection in a given
form.
</para>
@requestor:
@selection:
@target:
@time:
@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>
Retrieve selection data that was stored by the selection
data in response to a call to gdk_selection_convert()
</para>
@requestor:
@data:
@prop_type:
@prop_format:
@Returns:
@requestor: the window on which the data is stored
@data: location to store a pointer to the retrieved data.
If the retrieval failed, NULL we be stored here, otherwise, it
will be non-NULL and the returned data should be freed with g_free()
when you are finished using it. The length of the
allocated memory is one more than the the length
of the returned data, and the final byte will always
be zero, to ensure null-termination of strings.
@prop_type: location to store the type of the property.
@prop_format: location to store the format of the property.
@Returns: the length of the retrieved data.
<!-- ##### FUNCTION gdk_selection_send_notify ##### -->
<para>
Send a response to SelectionRequest event.
</para>
@requestor:
@selection:
@target:
@property:
@time:
@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.