gtk2/docs/reference/gdk/tmpl/gdk-unused.sgml

<!-- ##### SECTION ./tmpl/color_contexts.sgml:Long_Description ##### -->
<para>
The #GdkColorContext type is used for allocating groups of colors.
</para>
<para>
It is now deprecated in favor of the gdk_colormap_*() functions described in
the <link linkend="gdk-Colormaps-and-Colors">Colormaps and Colors</link>
section.
</para>


<!-- ##### SECTION ./tmpl/color_contexts.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/color_contexts.sgml:Short_Description ##### -->
routines for allocating colors (deprecated).


<!-- ##### SECTION ./tmpl/color_contexts.sgml:Title ##### -->
Color Contexts


<!-- ##### SECTION ./tmpl/colors.sgml:Long_Description ##### -->
<para>
These functions are used to modify colormaps.
A colormap is an object that contains the mapping
between the color values stored in memory and
the RGB values that are used to display color
values. In general, colormaps only contain
significant information for pseudo-color visuals,
but even for other visual types, a colormap object
is required in some circumstances.
</para>

<para>
There are a couple of special colormaps that can
be retrieved. The system colormap (retrieved 
with gdk_colormap_get_system()) is the default
colormap of the system. If you are using GdkRGB,
there is another colormap that is important - the
colormap in which GdkRGB works, retrieved with
gdk_rgb_get_cmap(). However, when using GdkRGB, 
it is not generally necessary to allocate colors
directly.
</para>

<para>
In previous revisions of this interface, a number
of functions that take a #GdkColormap parameter
were replaced with functions whose names began
with "gdk_colormap_". This process will probably
be extended somewhat in the future - 
gdk_color_white(), gdk_color_black(), and 
gdk_color_change() will probably become aliases.
</para>


<!-- ##### SECTION ./tmpl/colors.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/colors.sgml:Short_Description ##### -->
manipulation of colors and colormaps.


<!-- ##### SECTION ./tmpl/colors.sgml:Title ##### -->
Colormaps and Colors


<!-- ##### SECTION ./tmpl/cursors.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/cursors.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/cursors.sgml:Short_Description ##### -->
standard and pixmap cursors.


<!-- ##### SECTION ./tmpl/cursors.sgml:Title ##### -->
Cursors


<!-- ##### SECTION ./tmpl/dnd.sgml:Long_Description ##### -->
<para>
These functions provide a low level interface for drag and drop.
GDK supports both the Xdnd and Motif drag and drop protocols transparently.
</para>
<para>
GTK+ provides a higher level abstraction based on top of these functions,
and so they are not normally needed in GTK+ applications.
See the <link linkend="gtk-Drag-and-Drop">Drag and Drop</link> section of
the GTK+ documentation for more information.
</para>


<!-- ##### SECTION ./tmpl/dnd.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/dnd.sgml:Short_Description ##### -->
functions for controlling drag and drop handling.


<!-- ##### SECTION ./tmpl/dnd.sgml:Title ##### -->
Drag and Drop


<!-- ##### SECTION ./tmpl/drawing.sgml:Long_Description ##### -->
<para>
These functions provide support for drawing points, lines, arcs and text
onto what are called 'drawables'. Drawables, as the name suggests, are things
which support drawing onto them, and are either #GdkWindow or #GdkPixmap
objects.
</para>
<para>
Many of the drawing operations take a #GdkGC argument, which represents a
graphics context. This #GdkGC contains a number of drawing attributes such
as foreground color, background color and line width, and is used to reduce
the number of arguments needed for each drawing operation. See the
<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
more information.
</para>


<!-- ##### SECTION ./tmpl/drawing.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/drawing.sgml:Short_Description ##### -->
functions for drawing points, lines, arcs, and text.


<!-- ##### SECTION ./tmpl/drawing.sgml:Title ##### -->
Drawing Primitives


<!-- ##### SECTION ./tmpl/event_structs.sgml:Long_Description ##### -->
<para>
The event structs contain data specific to each type of event in GDK.
</para>
<note>
<para>
A common mistake is to forget to set the event mask of a widget so that the
required events are received. See gtk_widget_set_events().
</para>
</note>


<!-- ##### SECTION ./tmpl/event_structs.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/event_structs.sgml:Short_Description ##### -->
data structures specific to each type of event.


<!-- ##### SECTION ./tmpl/event_structs.sgml:Title ##### -->
Event Structures


<!-- ##### SECTION ./tmpl/events.sgml:Long_Description ##### -->
<para>
This section describes functions dealing with events from the window system.
</para>
<para>
In GTK+ applications the events are handled automatically in
gtk_main_do_event() and passed on to the appropriate widgets, so these
functions are rarely needed. Though some of the fields in the
<link linkend="gdk-Event-Structures">Event Structures</link> are useful.
</para>


<!-- ##### SECTION ./tmpl/events.sgml:See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term><link linkend="gdk-Event-Structures">Event Structures</link></term>
<listitem><para>
The structs used for each type of event.
</para></listitem>
</varlistentry>
</variablelist>
</para>


<!-- ##### SECTION ./tmpl/events.sgml:Short_Description ##### -->
functions for handling events from the window system.


<!-- ##### SECTION ./tmpl/events.sgml:Title ##### -->
Events


<!-- ##### SECTION ./tmpl/fonts.sgml:Long_Description ##### -->
<para>
The GdkFont data type represents a font for drawing on
the screen. These functions provide support for
loading fonts, and also for determining the dimensions
of characters and strings when drawn with a particular
font.
</para>

<para>
Fonts in X are specified by a
<firstterm>X Logical Font Description</firstterm>. 
The following description is considerably simplified.
For definitive information about XLFD's see the 
X reference documentation. A X Logical Font Description (XLFD)
consists of a sequence of fields separated (and surrounded by) '-'
characters. For example, Adobe Helvetica Bold 12 pt, has the
full description: 

<programlisting>
"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
</programlisting>
</para>

<para>
The fields in the XLFD are:

<informaltable pgwide=1 frame="none">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>

<row>
<entry>Foundry</entry>
<entry>the company or organization where the font originated.</entry>
</row>

<row>
<entry>Family</entry>
<entry>the font family (a group of related font designs).</entry>
</row>

<row>
<entry>Weight</entry>
<entry>A name for the font's typographic weight
For example, 'bold' or 'medium').</entry>
</row>

<row>
<entry>Slant</entry>
<entry>The slant of the font. Common values are 'R' for Roman,
'I' for italoc, and 'O' for oblique.</entry>
</row>

<row>
<entry>Set Width</entry>
<entry>A name for the width of the font. For example,
'normal' or 'condensed'.</entry>
</row>

<row>
<entry>Add Style</entry>
<entry>Additional information to distinguish a font from
other fonts of the same family.</entry>
</row>

<row>
<entry>Pixel Size</entry>
<entry>The body size of the font in pixels.</entry>
</row>

<row>
<entry>Point Size</entry>
<entry>The body size of the font in 10ths of a point.
(A <firstterm>point</firstterm> is 1/72.27 inch) </entry>
</row>

<row>
<entry>Resolution X</entry>
<entry>The horizontal resolution that the font was designed for.</entry>
</row>

<row>
<entry>Resolution Y</entry>
<entry>The vertical resolution that the font was designed for .</entry>
</row>

<row>
<entry>Spacing</entry>
<entry>The type of spacing for the font - can be 'p' for proportional,
'm' for monospaced or 'c' for charcell.</entry>
</row>

<row>
<entry>Average Width</entry>
<entry>The average width of a glyph in the font. For monospaced
and charcell fonts, all glyphs in the font have this width</entry>
</row>

<row>
<entry>Charset Registry</entry>
<entry>The registration authority that owns the encoding for
the font. Together with the Charset Encoding field, this
defines the character set for the font.</entry>
</row>

<row>
<entry>Charset Encoding</entry>
<entry>An identifier for the particular character set encoding.</entry>
</row>

</tbody></tgroup></informaltable>
</para>

<para>
When specifying a font via a X logical Font Description,
'*' can be used as a wildcard to match any portion of
the XLFD. For instance, the above example could
also be specified as

<programlisting>
"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
</programlisting>

It is generally a good idea to use wildcards for any
portion of the XLFD that your program does not care
about specifically, since that will improve the
chances of finding a matching font.
</para>

<para>
A <firstterm>fontset</firstterm> is a list of fonts
that is used for drawing international text that may
contain characters from a number of different character
sets. It is represented by a list of XLFD's. 
</para>

<para>
The font for a given character set is determined by going
through the list of XLFD's in order. For each one, if
the registry and and encoding fields match the desired
character set, then that font is used, otherwise if
the XLFD contains wild-cards for the registry and encoding
fields, the registry and encoding for the desired character
set are subsituted in and a lookup is done. If a match is found
that font is used. Otherwise, processing continues
on to the next font in the list.
</para>

<para>
The functions for determining the metrics of a string
come in several varieties that can take a number
of forms of string input:

<variablelist>
  <varlistentry>
    <term>8-bit string</term>
    <listitem><para>
    When using functions like gdk_string_width() that
    take a <type>gchar *</type>, if the font is of type
    %GDK_FONT_FONT and is an 8-bit font, then each
    <type>gchar</type> indexes the glyphs in the font directly.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>16-bit string</term>
    <listitem><para>
    For functions taking a <type>gchar *</type>, if the
    font is of type %GDK_FONT_FONT, and is a 16-bit
    font, then the <type>gchar *</type> argument is
    interpreted as a <type>guint16 *</type> cast to
    a <type>gchar *</type> and each <type>guint16</type>
    indexes the glyphs in the font directly.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Multibyte string</term>
    <listitem><para>
    For functions taking a <type>gchar *</type>, if the
    font is of type %GDK_FONT_FONTSET, then the input
    string is interpreted as a <firstterm>multibyte</firstterm>
    encoded according to the current locale. (A multibyte
    string is one in which each character may consist
    of one or more bytes, with different lengths for different
    characters in the string). They can be converted to and
    from wide character strings (see below) using
    gdk_wcstombs() and gdk_mbstowcs().) The string will
    be rendered using one or more different fonts from
    the fontset.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>Wide character string</term>
    <listitem><para>
    For a number of the text-measuring functions, GTK+
    provides a variant (such as gdk_text_width_wc()) which
    takes a <type>GdkWChar *</type> instead of a 
    <type>gchar *</type>. The input is then taken to
    be a wide character string in the encoding of the
    current locale. (A wide character string is a string
    in which each character consists of several bytes,
    and the width of each character in the string is 
    constant.)
    </para></listitem>
  </varlistentry>
</variablelist>
</para>

<para>
GDK provides functions to determine a number of different
measurements (metrics) for a given string. (Need diagram
here).

<variablelist>
  <varlistentry>
    <term>ascent</term>
    <listitem><para>
    The vertical distance from the origin of the drawing
    opereration to the top of the drawn character.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>descent</term>
    <listitem><para>
    The vertical distance from the origin of the drawing
    opereration to the bottom of the drawn character.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>left bearing</term>
    <listitem><para>
    The horizontal distance from the origin of the drawing
    operation to the left-most part of the drawn character.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>right bearing</term>
    <listitem><para>
    The horizontal distance from the origin of the drawing
    operation to the right-most part of the drawn character.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term>width bearing</term>
    <listitem><para>
    The horizontal distance from the origin of the drawing
    operation to the correct origin for drawing another
    string to follow the current one. Depending on the
    font, this could be greater than or less than the 
    right bearing.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>


<!-- ##### SECTION ./tmpl/fonts.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/fonts.sgml:Short_Description ##### -->
loading and manipulating fonts


<!-- ##### SECTION ./tmpl/fonts.sgml:Title ##### -->
Fonts


<!-- ##### SECTION ./tmpl/gcs.sgml:Long_Description ##### -->
<para>
All drawing operations in GDK take a 
<firstterm>graphics context</firstterm> (GC) argument. 
A graphics context encapsulates information about
the way things are drawn, such as the foreground
color or line width. By using graphics contexts, 
the number of arguments to each drawing call is
greatly reduced, and communication overhead is
minimized, since identical arguments do not need
to be passed repeatedly.
</para>
<para>
Most values of a graphics context can be set at
creation time by using gdk_gc_new_with_values(),
or can be set one-by-one using functions such
as gdk_gc_set_foreground(). A few of the values
in the GC, such as the dash pattern, can only
be set by the latter method.
</para>


<!-- ##### SECTION ./tmpl/gcs.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/gcs.sgml:Short_Description ##### -->
objects to encapsulate drawing properties.


<!-- ##### SECTION ./tmpl/gcs.sgml:Title ##### -->
Graphics Contexts


<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/gdkkeys.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Title ##### -->
Keyboard Handling


<!-- ##### SECTION ./tmpl/gdkregion.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/gdkregion.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/gdkregion.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/gdkregion.sgml:Title ##### -->
Points, Rectangles and Regions


<!-- ##### SECTION ./tmpl/input.sgml:Long_Description ##### -->
<para>
The functions in this section are used to establish
callbacks when some condition becomes true for
a file descriptor. They are currently just wrappers around
the <link linkend="glib-IO-Channels">IO Channel</link>
facility.
</para>


<!-- ##### SECTION ./tmpl/input.sgml:See_Also ##### -->
<para>
<variablelist>

<varlistentry>
<term><link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link></term>
<listitem><para>The main loop in which input callbacks run.</para></listitem>
</varlistentry>

<varlistentry>
<term><link linkend="glib-IO-Channels">IO Channels</link></term>
<listitem><para>A newer and more flexible way of doing IO
callbacks.</para></listitem>
</varlistentry>

</variablelist>
</para>


<!-- ##### SECTION ./tmpl/input.sgml:Short_Description ##### -->
Callbacks on file descriptors.


<!-- ##### SECTION ./tmpl/input.sgml:Title ##### -->
Input


<!-- ##### SECTION ./tmpl/input_contexts.sgml:Long_Description ##### -->
<para>
A #GdkIC input context is used for each user interface element which supports
internationalized text input. See the
<link linkend="gdk-Input-Methods">Input Methods</link> section for an overview
of how internationalized text input works in GTK+.
</para>


<!-- ##### SECTION ./tmpl/input_contexts.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/input_contexts.sgml:Short_Description ##### -->
internationalized text input properties.


<!-- ##### SECTION ./tmpl/input_contexts.sgml:Title ##### -->
Input Contexts


<!-- ##### SECTION ./tmpl/input_devices.sgml: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 ./tmpl/input_devices.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/input_devices.sgml:Short_Description ##### -->
Functions for handling extended input devices.


<!-- ##### SECTION ./tmpl/input_devices.sgml:Title ##### -->
Input Devices


<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Title ##### -->
Pango Interaction


<!-- ##### SECTION ./tmpl/input_methods.sgml:Long_Description ##### -->
<para>
Input Methods provide a way for complex character sets to be used in GTK+.
Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK)
use a large number of ideographs, making it impossible to support all
characters with a simple keyboard. Instead, text is usually
<emphasis>pre-edited</emphasis> using a phonetic alphabet and then
<emphasis>composed</emphasis> to form the ideographs.
</para>
<para>
GTK+ makes use of the input method mechanism provided by the X Windows
platform. When a GTK+ application is started, it opens a connection to the
input method appropriate for the current locale (if any). 
</para>
<para>
Widgets which handle textual input, such as #GtkEntry, need to do a number of
things to support internationalized text input:
<variablelist>
<varlistentry>
<term>When the widget is realized:</term>
<listitem><para>Check if an input method is being used with gdk_im_ready().
If it is, create a new <link linkend="gdk-Input-Contexts">Input Context</link>
using gdk_ic_new(). Find out which events the
<link linkend="gdk-Input-Contexts">Input Context</link> needs to receive
with gdk_ic_get_events(), and make sure that the widget's window receives
these events using gdk_window_set_events().
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the widget's size, state or cursor position changes:</term>
<listitem><para>
Update the appropriate
<link linkend="gdk-Input-Contexts">Input Context</link> attributes
using gdk_ic_set_attr().
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the keyboard focus enters or leaves the widget:</term>
<listitem><para>
Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the widget receives a key_press event:</term>
<listitem><para>
The <structfield>string</structfield> and <structfield>length</structfield>
fields of the #GdkEventKey struct should be used to insert the composed text
into the widget.
</para></listitem>
</varlistentry>

<varlistentry>
<term>When the widget is unrealized:</term>
<listitem><para>
Destroy the <link linkend="gdk-Input-Contexts">Input Context</link>.
</para></listitem>
</varlistentry>
</variablelist>

</para>
<para>
See the XLib reference manual for more detailed information on input methods,
and the #GtkEntry and #GtkText widgets for some example code.
</para>


<!-- ##### SECTION ./tmpl/input_methods.sgml:See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term><link linkend="gdk-Input-Contexts">Input Contexts</link></term>
<listitem><para>
Used for each widget that handles internationalized text input using the
global input method.
</para></listitem>
</varlistentry>
</variablelist>

</para>


<!-- ##### SECTION ./tmpl/input_methods.sgml:Short_Description ##### -->
support for internationalized text input.


<!-- ##### SECTION ./tmpl/input_methods.sgml:Title ##### -->
Input Methods


<!-- ##### SECTION ./tmpl/keys.sgml:Long_Description ##### -->
<para>
Key values are the codes which are sent whenever a key is pressed or released.
They appear in the <structfield>keyval</structfield> field of the
#GdkEventKey structure, which is passed to signal handlers for the
"key-press-event" and "key-release-event" signals.
The complete list of key values can be found in the &lt;gdk/gdkkeysyms.h&gt;
header file.
</para>
<para>
Key values can be converted into a string representation using
gdk_keyval_name(). The reverse function, converting a string to a key value,
is provided by gdk_keyval_from_name().
</para>
<para>
The case of key values can be determined using gdk_keyval_is_upper() and
gdk_keyval_is_lower(). Key values can be converted to upper or lower case
using gdk_keyval_to_upper() and gdk_keyval_to_lower().
</para>


<!-- ##### SECTION ./tmpl/keys.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/keys.sgml:Short_Description ##### -->
functions for manipulating keyboard codes.


<!-- ##### SECTION ./tmpl/keys.sgml:Title ##### -->
Key Values


<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/pango_interaction.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Title ##### -->
Pango Interaction


<!-- ##### SECTION ./tmpl/pixbufs.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/pixbufs.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/pixbufs.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/pixbufs.sgml:Title ##### -->
Pixbufs


<!-- ##### SECTION ./tmpl/properties.sgml: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 ./tmpl/properties.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/properties.sgml:Short_Description ##### -->
functions to manipulate properties on windows.


<!-- ##### SECTION ./tmpl/properties.sgml:Title ##### -->
Properties and Atoms


<!-- ##### SECTION ./tmpl/regions.sgml:Long_Description ##### -->
<para>
GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
for representing pixels and sets of pixels on the screen.
</para>
<para>
#GdkPoint is a simple structure containing an x and y coordinate of a point.
</para>
<para>
#GdkRectangle is a structure holding the position and size of a rectangle.
The intersection of two rectangles can be computed with
gdk_rectangle_intersect(). To find the union of two rectangles use
gdk_rectangle_union().
</para>
<para>
#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
</para>
<para>
#GdkSpan is a structure holding a spanline. A spanline is a horizontal line that
is one pixel wide. It is mainly used when rasterizing other graphics primitives.
It can be intersected to regions by using gdk_region_spans_intersect_foreach().
</para>


<!-- ##### SECTION ./tmpl/regions.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/regions.sgml:Short_Description ##### -->
simple graphical data types.


<!-- ##### SECTION ./tmpl/regions.sgml:Title ##### -->
Points, Rectangles and Regions


<!-- ##### SECTION ./tmpl/regions2.sgml:Long_Description ##### -->
<para>
GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for
representing pixels and sets of pixels on the screen.
</para>
<para>
#GdkPoint is a simple structure containing an x and y coordinate of a point.
</para>
<para>
#GdkRectangle is a structure holding the position and size of a rectangle.
The intersection of two rectangles can be computed with
gdk_rectangle_intersect(). To find the union of two rectangles use
gdk_rectangle_union().
</para>
<para>
#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
</para>


<!-- ##### SECTION ./tmpl/regions2.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/regions2.sgml:Short_Description ##### -->
simple graphical data types.


<!-- ##### SECTION ./tmpl/regions2.sgml:Title ##### -->
Points, Rectangles and Regions


<!-- ##### SECTION ./tmpl/rgb.sgml:Long_Description ##### -->
<para>

GdkRgb converts RGB, grayscale, and colormapped images into the native
window pixel format and displays them. It takes care of colormaps,
visuals, dithering, and management of the temporary buffers.

</para>

<para>
You must call gdk_rgb_init() before using any GdkRgb functionality. If
you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
(including #GtkPreview) call gdk_rgb_init() in their class_init method.
Thus, if you use GdkRgb only indirectly, you don't need to worry
about it.
</para>

<para>
GdkRgb tries to use the system default visual and colormap, but
doesn't always succeed. Thus, you have to be prepared to install the
visual and colormap generated by GdkRgb. The following code sequence
(before any widgets are created) should work in most applications:
</para>

<informalexample>
<programlisting>
  gdk_rgb_init ();

  gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
  gtk_widget_set_default_visual (gdk_rgb_get_visual ());
</programlisting>
</informalexample>

<para>
You can also push the colormap and visual, but in general it doesn't
work unless the push wraps the window creation call. If you wrap the
push around a widget which is embedded in a window without the GdkRgb
colormap and visual, it probably won't work, and is likely to cause
colormap flashing, as well.
</para>

<para>
On 8-bit systems, the colormaps used by Imlib and GdkRgb may
conflict. There is no good general solution to this other than phasing
out the dependence on Imlib.
</para>

<para>
You can set the threshold for installing colormaps with
gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
of this size or larger can be allocated in the default colormap, then
that's done. Otherwise, GdkRgb creates its own private colormap.
Setting it to 0 means that it always tries to use the default
colormap, and setting it to 216 means that it always creates a private
one if it cannot allocate the 6x6x6 colormap in the default. If you
always want a private colormap (to avoid consuming too many colormap
entries for other apps, say), you can use gdk_rgb_set_install(TRUE).
Setting the value greater than 216 exercises a bug in older versions
of GdkRgb. Note, however, that setting it to 0 doesn't let you get
away with ignoring the colormap and visual - a colormap is always
created in grayscale and direct color modes, and the visual is changed
in cases where a "better" visual than the default is available.
</para>

<example>
<title>A simple example program using GdkRGB.</title>
<programlisting>
#include &lt;gtk/gtk.h&gt;

#define IMAGE_WIDTH	256
#define IMAGE_HEIGHT	256

guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];

gboolean on_darea_expose (GtkWidget *widget,
			  GdkEventExpose *event,
			  gpointer user_data);

int
main (int argc, char *argv[])
{
  GtkWidget *window, *darea;
  gint x, y;
  guchar *pos;

  gtk_init (&amp;argc, &amp;argv);
  gdk_rgb_init ();
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  darea = gtk_drawing_area_new ();
  gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
  gtk_container_add (GTK_CONTAINER (window), darea);
  gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
                      GTK_SIGNAL_FUNC (on_darea_expose), NULL);
  gtk_widget_show_all (window);

  /* Set up the RGB buffer. */
  pos = rgbbuf;
  for (y = 0; y < IMAGE_HEIGHT; y++)
    {
      for (x = 0; x < IMAGE_WIDTH; x++)
	{
	  *pos++ = x - x % 32;			/* Red. */
	  *pos++ = (x / 32) * 4 + y - y % 32;	/* Green. */
	  *pos++ = y - y % 32;			/* Blue. */
	}
    }

  gtk_main ();
  return 0;
}


gboolean
on_darea_expose (GtkWidget *widget,
		 GdkEventExpose *event,
		 gpointer user_data)
{
  gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
		      0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
		      GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
}
</programlisting>
</example>


<!-- ##### SECTION ./tmpl/rgb.sgml:See_Also ##### -->
<para>
<variablelist>

<varlistentry>
<term>#GdkColor</term>
<listitem><para>The underlying Gdk mechanism for allocating
colors.</para></listitem>
</varlistentry>

</variablelist>

</para>


<!-- ##### SECTION ./tmpl/rgb.sgml:Short_Description ##### -->
displays RGB images (as well as grayscale and colormapped) to
the native window.


<!-- ##### SECTION ./tmpl/rgb.sgml:Title ##### -->
GdkRGB


<!-- ##### SECTION ./tmpl/selections.sgml: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 ./tmpl/selections.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/selections.sgml:Short_Description ##### -->
functions for transfering data via the X selection mechanism.


<!-- ##### SECTION ./tmpl/selections.sgml:Title ##### -->
Selections


<!-- ##### SECTION ./tmpl/threads.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/threads.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/threads.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/threads.sgml:Title ##### -->
Threads


<!-- ##### SECTION ./tmpl/visuals.sgml:Long_Description ##### -->
<para>
The way that the data stored on the screen is stored
in memory can vary considerably between different X
servers; some X servers even support multiple formats
used simultaneously. An X <firstterm>visual</firstterm>
represents a particular format for screen data.
It includes information about the number of bits
used for each color, the way the bits are translated
into an RGB value for display, and the way the bits
are stored in memory.
</para>
<para>
There are several standard visuals. The visual returned
by gdk_visual_get_system() is the system's default
visual. gdk_rgb_get_visual() return the visual most
suited to displaying full-color image data. If you
use the calls in GdkRGB, you should create your windows
using this visual (and the colormap returned by
gdk_rgb_get_colormap()).
</para>
<para>
A number of functions are provided for determining
the "best" available visual. For the purposes of
making this determination, higher bit depths are
considered better, and for visuals of the same
bit depth, %GDK_VISUAL_PSEUDO_COLOR is preferred at
8bpp, otherwise, the visual types are ranked in the
order of (highest to lowest) %GDK_VISUAL_DIRECT_COLOR,
%GDK_VISUAL_TRUE_COLOR, %GDK_VISUAL_PSEUDO_COLOR,
%GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE, 
then %GDK_VISUAL_STATIC_GRAY.
</para>


<!-- ##### SECTION ./tmpl/visuals.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/visuals.sgml:Short_Description ##### -->
manipulation of visuals.


<!-- ##### SECTION ./tmpl/visuals.sgml:Title ##### -->
Visuals


<!-- ##### SECTION ./tmpl/windows.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/windows.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/windows.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/windows.sgml:Title ##### -->
Windows


<!-- ##### SECTION ./tmpl/x_interaction.sgml:Long_Description ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/x_interaction.sgml:See_Also ##### -->
<para>

</para>


<!-- ##### SECTION ./tmpl/x_interaction.sgml:Short_Description ##### -->



<!-- ##### SECTION ./tmpl/x_interaction.sgml:Title ##### -->
X Window System Interaction


<!-- ##### MACRO GDK_CORE_POINTER ##### -->
<para>
This macro contains an integer value representing
the device ID for the core pointer device.
</para>


<!-- ##### STRUCT GdkColorContext ##### -->
<para>

</para>

@visual: 
@colormap: 
@num_colors: 
@max_colors: 
@num_allocated: 
@mode: 
@need_to_free_colormap: 
@std_cmap_atom: 
@clut: 
@cmap: 
@color_hash: 
@palette: 
@num_palette: 
@fast_dither: 

<!-- ##### STRUCT GdkColorContextDither ##### -->
<para>

</para>

@fast_rgb: 
@fast_err: 
@fast_erg: 
@fast_erb: 

<!-- ##### ENUM GdkColorContextMode ##### -->
<para>

</para>

@GDK_CC_MODE_UNDEFINED: 
@GDK_CC_MODE_BW: 
@GDK_CC_MODE_STD_CMAP: 
@GDK_CC_MODE_TRUE: 
@GDK_CC_MODE_MY_GRAY: 
@GDK_CC_MODE_PALETTE: 

<!-- ##### 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.

<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
<para>

</para>

@GDK_PIXBUF_ALPHA_BILEVEL: 
@GDK_PIXBUF_ALPHA_FULL: 

<!-- ##### FUNCTION gdk_color_context_add_palette ##### -->
<para>

</para>

@cc: 
@palette: 
@num_palette: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_free ##### -->
<para>

</para>

@cc: 

<!-- ##### FUNCTION gdk_color_context_free_dither ##### -->
<para>

</para>

@cc: 

<!-- ##### FUNCTION gdk_color_context_get_index_from_palette ##### -->
<para>

</para>

@cc: 
@red: 
@green: 
@blue: 
@failed: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_get_pixel ##### -->
<para>

</para>

@cc: 
@red: 
@green: 
@blue: 
@failed: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_get_pixel_from_palette ##### -->
<para>

</para>

@cc: 
@red: 
@green: 
@blue: 
@failed: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_get_pixels ##### -->
<para>

</para>

@cc: 
@reds: 
@greens: 
@blues: 
@ncolors: 
@colors: 
@nallocated: 

<!-- ##### FUNCTION gdk_color_context_get_pixels_incremental ##### -->
<para>

</para>

@cc: 
@reds: 
@greens: 
@blues: 
@ncolors: 
@used: 
@colors: 
@nallocated: 

<!-- ##### FUNCTION gdk_color_context_init_dither ##### -->
<para>

</para>

@cc: 

<!-- ##### FUNCTION gdk_color_context_new ##### -->
<para>

</para>

@visual: 
@colormap: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_new_mono ##### -->
<para>

</para>

@visual: 
@colormap: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_query_color ##### -->
<para>

</para>

@cc: 
@color: 
@Returns: 

<!-- ##### FUNCTION gdk_color_context_query_colors ##### -->
<para>

</para>

@cc: 
@colors: 
@num_colors: 
@Returns: 

<!-- ##### FUNCTION gdk_input_list_devices ##### -->
<para>
Lists all available input devices, along with their
configuration information.
</para>

@Returns: A #GList of #GdkDeviceInfo structures. This list
          is internal data of GTK+ and should not be modified 
          or freed.

<!-- ##### FUNCTION gdk_input_motion_events ##### -->
<para>
Retrieves the motion history for a given device/window pair.
</para>

@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.

<!-- ##### 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: the device to configure.
@axes: an array of GdkAxisUse. This length of this array
       must match the number of axes for the device.

<!-- ##### FUNCTION gdk_input_set_key ##### -->
<para>
Sets the key event generated when a macro button is pressed.
</para>

@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_set_mode ##### -->
<para>
Enables or disables a device, and determines how the
device maps onto the screen.
</para>

@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.

<!-- ##### FUNCTION gdk_input_set_source ##### -->
<para>
Sets the source type for a device.
</para>

@deviceid: the device to configure
@source: the new source type.

<!-- ##### 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: 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_regions_intersect ##### -->
<para>
Returns the intersection of two regions.
</para>

@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the intersection of @source1 and @source2.

<!-- ##### FUNCTION gdk_regions_subtract ##### -->
<para>
Subtracts one region from another.
The result is a region containing all the pixels which are in @source1, but
which are not in @source2.
</para>

@source1: a #GdkRegion.
@source2: a #GdkRegion to subtract from @source1.
@Returns: @source1 - @source2.

<!-- ##### FUNCTION gdk_regions_union ##### -->
<para>
Returns the union of two regions.
This is all pixels in either of @source1 or @source2.
</para>

@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the union of @source1 and @source2.

<!-- ##### FUNCTION gdk_regions_xor ##### -->
<para>
Returns the difference between the union and the intersection of two regions.
This is a region containing the pixels that are in one of the source regions,
but which are not in both.
</para>

@source1: a #GdkRegion.
@source2: a #GdkRegion.
@Returns: the difference between the union and the intersection of @source1
and @source2.