This information will still be available in the 2.22 docs.
For 3.0, we'll do sortof a clean start.
version.xml \
running.sgml \
building.sgml \
- changes-1.2.sgml \
- changes-2.0.sgml \
compiling.sgml \
directfb.sgml \
drawing-model.xml \
glossary.xml \
migrating-2to3.xml \
migrating-checklist.sgml \
- migrating-ClientSideWindows.sgml \
- migrating-GtkAboutDialog.sgml \
- migrating-GtkAction.sgml \
- migrating-GtkAssistant.sgml \
- migrating-GtkBuilder.sgml \
- migrating-GtkColorButton.sgml \
- migrating-GtkComboBox.sgml \
- migrating-GtkEntry-icons.sgml \
- migrating-GtkFileChooser.sgml \
- migrating-GtkIconView.sgml \
- migrating-GtkLabel-links.sgml \
- migrating-GtkLinkButton.sgml \
- migrating-GtkRecentChooser.sgml \
- migrating-GtkTooltip.sgml \
objects_grouped.sgml \
osx.sgml \
question_index.sgml \
of the tools are already included in the source packages. But
it's useful to know a bit about how packages that use these
tools work. A source package is distributed as a
- <literal>tar.gz</literal> or <literal>tar.bz2</literal> file
+ <literal>tar.gz</literal> or <literal>tar.bz2</literal> file
which you unpack into a directory full of the source files as follows:
</para>
<programlisting>
- tar xvfz gtk+-2.0.0.tar.gz
- tar xvfj gtk+-2.0.0.tar.bz2
+ tar xvfz gtk+-3.0.0.tar.gz
+ tar xvfj gtk+-3.0.0.tar.bz2
</programlisting>
<para>
In the toplevel of the directory that is created, there will be
a search path that <command>pkg-config</command> (see below)
uses when looking for for file describing how to compile
programs using different libraries. If you were installing GTK+
- and it's dependencies into <filename>/opt/gtk</filename>, you
+ and it's dependencies into <filename>/opt/gtk</filename>, you
might want to set these variables as:
</para>
<programlisting>
</para>
<itemizedlist>
<listitem>
- <para>
- <ulink
- url="http://www.freedesktop.org/software/pkgconfig">pkg-config</ulink>
- is a tool for tracking the compilation flags needed for
- libraries that are used by the GTK+ libraries. (For each
- library, a small <literal>.pc</literal> text file is installed
- in a standard location that contains the compilation flags
- needed for that library along with version number information.)
- The version of <command>pkg-config</command> needed to build
- GTK+ is mirrored in the <filename>dependencies</filename> directory
- on the <ulink url="ftp://ftp.gtk.org/pub/gtk/">GTK+ FTP
- site.</ulink>
- </para>
+ <para>
+ <ulink
+ url="http://pkg-config.freedesktop.org">pkg-config</ulink>
+ is a tool for tracking the compilation flags needed for
+ libraries that are used by the GTK+ libraries. (For each
+ library, a small <literal>.pc</literal> text file is installed
+ in a standard location that contains the compilation flags
+ needed for that library along with version number information.)
+ </para>
</listitem>
<listitem>
- <para>
- The GTK+ makefiles will mostly work with different versions
- of <command>make</command>, however, there tends to be
- a few incompatibilities, so the GTK+ team recommends
- installing <ulink url="http://www.gnu.org/software/make">GNU
- make</ulink> if you don't already have it on your system
- and using it. (It may be called <command>gmake</command>
- rather than <command>make</command>.)
- </para>
+ The GTK+ makefiles will mostly work with different versions
+ of <command>make</command>, however, there tends to be
+ a few incompatibilities, so the GTK+ team recommends
+
installing <ulink url="http://www.gnu.org/software/make">GNU
+ make</ulink> if you don't already have it on your system
+ and using it. (It may be called <command>gmake</command>
+ rather than <command>make</command>.)
+ </para>
</listitem>
</itemizedlist>
<para>
</para>
<itemizedlist>
<listitem>
- <para>
- The GLib library provides core non-graphical functionality
- such as high level data types, Unicode manipulation, and
- an object and type system to C programs. It is available
- from the <ulink url="ftp://ftp.gtk.org/pub/glib/">GTK+
- FTP site.</ulink>
- </para>
+ The GLib library provides core non-graphical functionality
+ such as high level data types, Unicode manipulation, and
+ an object and type system to C programs. It is available
+
from the <ulink url="ftp://ftp.gtk.org/pub/glib/">GTK+
+ FTP site.</ulink>
+ </para>
</listitem>
<listitem>
- <para>
- <ulink url="http://www.pango.org">Pango</ulink> is a library
- for internationalized text handling. It is available from
- the <ulink url="ftp://ftp.gtk.org/pub/pango/">GTK+ FTP
- site.</ulink>.
- </para>
+
<ulink url="http://www.pango.org">Pango</ulink> is a library
+ for internationalized text handling. It is available from
+
the <ulink url="ftp://ftp.gtk.org/pub/pango/">GTK+ FTP
+ site.</ulink>.
+ </para>
</listitem>
<listitem>
- <para>
- ATK is the Accessibility Toolkit. It provides a set of generic
- interfaces allowing accessibility technologies such as
- screen readers to interact with a graphical user interface.
- It is available from the <ulink
- url="ftp://ftp.gtk.org/pub/atk/">GTK+ FTP site.</ulink>
- </para>
+ ATK is the Accessibility Toolkit. It provides a set of generic
+ interfaces allowing accessibility technologies such as
+ screen readers to interact with a graphical user interface.
+
It is available from the <ulink
+ url="ftp://ftp.gtk.org/pub/atk/">GTK+ FTP site.</ulink>
+ </para>
</listitem>
<listitem>
- <para>
- The <ulink url="http://www.gnu.org/software/libiconv/">GNU
- libiconv library</ulink> is needed to build GLib if your
- system doesn't have the <function>iconv()</function>
- function for doing conversion between character
- encodings. Most modern systems should have
- <function>iconv()</function>.
- </para>
+
The <ulink url="http://www.gnu.org/software/libiconv/">GNU
+ libiconv library</ulink> is needed to build GLib if your
+ system doesn't have the <function>iconv()</function>
+ function for doing conversion between character
+ encodings. Most modern systems should have
+ <function>iconv()</function>.
+ </para>
</listitem>
<listitem>
- <para>
- The libintl library from the <ulink
- url="http://www.gnu.org/software/gettext/">GNU gettext
- package</ulink> is needed if your system doesn't have the
- <function>gettext()</function> functionality for handling
- message translation databases.
- </para>
+
The libintl library from the <ulink
+ url="http://www.gnu.org/software/gettext/">GNU gettext
+ package</ulink> is needed if your system doesn't have the
+ <function>gettext()</function> functionality for handling
+ message translation databases.
+ </para>
</listitem>
<listitem>
- <para>
- The <ulink
- url="ftp://ftp.uu.net/graphics/jpeg/">JPEG</ulink>,
- <ulink url="http://www.libpng.org">PNG</ulink>, and
- <ulink url="http://www.libtiff.org">TIFF</ulink> image
- loading libraries are needed to compile GTK+. You probably
- already have these libraries installed, but if not, the
- versions you need are available in the
+ <para>
+ The <ulink url="http://en.wikipedia.org/wiki/Libjpeg">JPEG</ulink>,
+ <ulink url="http://www.libpng.org">PNG</ulink>, and
+ <ulink url="http://www.libtiff.org">TIFF</ulink> image
+ loading libraries are needed to compile GTK+. You probably
+ already have these libraries installed, but if not, the
+ versions you need are available in the
<filename>dependencies</filename> directory on the the
- <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.6/dependencies/">GTK+
- FTP site.</ulink>. (Before installing these libraries
- from source, you should check if your operating system
- vendor has prebuilt packages of these libraries that you
- don't have installed.)
- </para>
+ <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.10/dependencies/">GTK+
+ FTP site.</ulink>. (Before installing these libraries
+ from source, you should check if your operating system
+ vendor has prebuilt packages of these libraries that you
+ don't have installed.)
+ </para>
</listitem>
<listitem>
- <para>
- The libraries from the X window system are needed to build
- Pango and GTK+. You should already have these installed on
- your system, but it's possible that you'll need to install
- the development environment for these libraries that your
- operating system vendor provides.
- </para>
+ The libraries from the X window system are needed to build
+ Pango and GTK+. You should already have these installed on
+ your system, but it's possible that you'll need to install
+ the development environment for these libraries that your
+ operating system vendor provides.
+ </para>
</listitem>
<listitem>
- <para>
- The <ulink url="http://www.fontconfig.org">fontconfig</ulink>
- library provides Pango with a standard way of locating
- fonts and matching them against font names.
- </para>
+
The <ulink url="http://www.fontconfig.org">fontconfig</ulink>
+ library provides Pango with a standard way of locating
+ fonts and matching them against font names.
+ </para>
</listitem>
<listitem>
- <para>
- <ulink url="http://www.cairographics.org">Cairo</ulink>
+
<ulink url="http://www.cairographics.org">Cairo</ulink>
is a graphics library that supports vector graphics and image
compositing. Both Pango and GTK+ use cairo for much of their
drawing.
</para>
</listitem>
<listitem>
- <para>
- <ulink url="http://live.gnome.org/GObjectIntrospection">gobject-introspection</ulink>
+
<ulink url="http://live.gnome.org/GObjectIntrospection">gobject-introspection</ulink>
is a framework for making introspection data available to
language bindings.
</para>
</listitem>
<listitem>
<para>
- The <ulink url="http://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
- package is not a hard dependency of GTK+, but it contains definitions
- for mime types that are used by GIO and, indirectly, by GTK+.
- gdk-pixbuf will use GIO for mime type detection if possible. For this
- to work, shared-mime-info needs to be installed and
- <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
+ The <ulink url="http://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
+ package is not a hard dependency of GTK+, but it contains definitions
+ for mime types that are used by GIO and, indirectly, by GTK+.
+ gdk-pixbuf will use GIO for mime type detection if possible. For this
+ to work, shared-mime-info needs to be installed and
+ <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
Otherwise, gdk-pixbuf falls back to its built-in mime type detection.
</para>
</listitem>
First make sure that you have the necessary external
dependencies installed: <command>pkg-config</command>, GNU make,
the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
- libiconv and libintl. To get detailed information about building
+ libiconv and libintl. To get detailed information about building
these packages, see the documentation provided with the
individual packages.
On a Linux system, it's quite likely you'll have all of these
<literal>make install</literal> mentioned above. If you're
lucky, this will all go smoothly, and you'll be ready to
<link linkend="gtk-compiling">start compiling your own GTK+
- applications</link>. You can test your GTK+ installation
+ applications</link>. You can test your GTK+ installation
by running the <command>gtk-demo</command> program that
GTK+ installs.
</para>
<title>Extra Configuration Options</title>
<para>
- In addition to the normal options, the
- <command>configure</command> script for the GTK+ library
- supports a number of additional arguments. (Command line
- arguments for the other GTK+ libraries are described in
- the documentation distributed with the those libraries.)
-
- <cmdsynopsis>
- <command>configure</command>
-
- <group>
- <arg>--disable-modules</arg>
- <arg>--enable-modules</arg>
- </group>
- <group>
- <arg>--with-included-loaders==LOADER1,LOADER2,...</arg>
- </group>
- <group>
- <arg>--with-included-immodules=MODULE1,MODULE2,...</arg>
- </group>
- <group>
- <arg>--enable-debug=[no|minimum|yes]</arg>
- </group>
+ In addition to the normal options, the
+ <command>configure</command> script for the GTK+ library
+ supports a number of additional arguments. (Command line
+ arguments for the other GTK+ libraries are described in
+ the documentation distributed with the those libraries.)
+
+ <cmdsynopsis>
+ <command>configure</command>
+
+ <group>
+ <arg>--disable-modules</arg>
+ <arg>--enable-modules</arg>
+ </group>
+ <group>
+ <arg>--with-included-loaders==LOADER1,LOADER2,...</arg>
+ </group>
<group>
- <arg>--disable-visibility</arg>
- <arg>--enable-visibility</arg>
- </group>
+ <arg>--with-included-immodules=MODULE1,MODULE2,...</arg>
+ </group>
<group>
- <arg>--disable-shm</arg>
- <arg>--enable-shm</arg>
- </group>
+ <arg>--enable-debug=[no|minimum|yes]</arg>
+ </group>
<group>
- <arg>--disable-xim</arg>
- <arg>--enable-xim</arg>
- </group>
+ <arg>--disable-visibility</arg>
+ <arg>--enable-visibility</arg>
+ </group>
<group>
- <arg>--disable-xim-inst</arg>
- <arg>--enable-xim-inst</arg>
- </group>
+ <arg>--disable-shm</arg>
+ <arg>--enable-shm</arg>
+ </group>
<group>
- <arg>--disable-xkb</arg>
- <arg>--enable-xkb</arg>
- </group>
+ <arg>--disable-xim</arg>
+ <arg>--enable-xim</arg>
+ </group>
<group>
- <arg>--disable-xinerama</arg>
- <arg>--enable-xinerama</arg>
- </group>
- <group>
- <arg>--disable-gtk-doc</arg>
- <arg>--enable-gtk-doc</arg>
- </group>
- <group>
- <arg>--disable-cups</arg>
- <arg>--enable-cups</arg>
- </group>
+ <arg>--disable-xim-inst</arg>
+ <arg>--enable-xim-inst</arg>
+ </group>
+ <group>
+ <arg>--disable-xkb</arg>
+ <arg>--enable-xkb</arg>
+ </group>
+ <group>
+ <arg>--disable-xinerama</arg>
+ <arg>--enable-xinerama</arg>
+ </group>
+ <group>
+ <arg>--disable-gtk-doc</arg>
+ <arg>--enable-gtk-doc</arg>
+ </group>
+ <group>
+ <arg>--disable-cups</arg>
+ <arg>--enable-cups</arg>
+ </group>
+ <group>
+ <arg>--disable-papi</arg>
+ <arg>--enable-papi</arg>
+ </group>
<group>
<arg>--with-xinput=[no|yes]</arg>
</group>
- <group>
- <arg>--with-gdktarget=[x11|win32|quartz|directfb]</arg>
- </group>
<group>
- <arg>--disable-introspection</arg>
+ <arg>--with-gdktarget=[x11|win32|quartz|directfb]</arg>
+ </group>
+ <group>
+ <arg>--disable-introspection</arg>
</group>
- </cmdsynopsis>
+ </cmdsynopsis>
</para>
<formalpara>
- <title><systemitem>--disable-modules</systemitem> and
- <systemitem>--enable-modules</systemitem></title>
-
- <para>
- Normally GTK+ will try to build the GdkPixbuf image file
- format loaders as little shared libraries that are loaded on
- demand. The <systemitem>--disable-modules</systemitem>
- argument indicates that they should all be built statically
- into the GTK+ library instead. This is useful for
- people who need to produce statically-linked binaries. If
- neither <systemitem>--disable-modules</systemitem> nor
- <systemitem>--enable-modules</systemitem> is specified, then
- the <command>configure</command> script will try to
- auto-detect whether shared modules work on your system.
- </para>
+ <title><systemitem>--disable-modules</systemitem> and
+ <systemitem>--enable-modules</systemitem></title>
+
+ Normally GTK+ will try to build the GdkPixbuf image file
+ format loaders as little shared libraries that are loaded on
+ demand. The <systemitem>--disable-modules</systemitem>
+ argument indicates that they should all be built statically
+ into the GTK+ library instead. This is useful for
+ people who need to produce statically-linked binaries. If
+ neither <systemitem>--disable-modules</systemitem> nor
+ <systemitem>--enable-modules</systemitem> is specified, then
+ the <command>configure</command> script will try to
+ auto-detect whether shared modules work on your system.
+ </para>
</formalpara>
<formalpara>
- <title><systemitem>--with-included-loaders</systemitem></title>
+ <title><systemitem>--with-included-loaders</systemitem></title>
- <para>
This option allows you to specify which image loaders you
want to include; for example, you might include only the PNG
loader to create a smaller GdkPixbuf binary.
- </para>
+ </para>
</formalpara>
<formalpara>
- <title><systemitem>--with-included-immodules</systemitem></title>
+ <title><systemitem>--with-included-immodules</systemitem></title>
- <para>
This option allows you to specify which input method modules you
- want to include.
- </para>
+ want to include.
+ </para>
</formalpara>
<formalpara>
<title><systemitem>--enable-debug</systemitem></title>
-
+
<para>
- Turns on various amounts of debugging support. Setting this to 'no'
- disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
+ Turns on various amounts of debugging support. Setting this to 'no'
+ disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
all cast checks between different object types. Setting it to 'minimum'
- disables only cast checks. Setting it to 'yes' enables
- <link linkend="GTK-Debug-Options">runtime debugging</link>.
+ disables only cast checks. Setting it to 'yes' enables
+ <link linkend="GTK-Debug-Options">runtime debugging</link>.
The default is 'minimum'.
- Note that 'no' is fast, but dangerous as it tends to destabilize
- even mostly bug-free software by changing the effect of many bugs
- from simple warnings into fatal crashes. Thus
- <option>--enable-debug=no</option> should <emphasis>not</emphasis>
+ Note that 'no' is fast, but dangerous as it tends to destabilize
+ even mostly bug-free software by changing the effect of many bugs
+ from simple warnings into fatal crashes. Thus
+ <option>--enable-debug=no</option> should <emphasis>not</emphasis>
be used for stable releases of GTK+.
</para>
</formalpara>
The option <systemitem>--disable-visibility</systemitem>
turns off the use of ELF visibility attributes for linking
optimizations. This makes sense while changing GTK+ itself,
- since the way in which GTK+ uses visibility attributes
+ since the way in which GTK+ uses visibility attributes
forces a full rebuild of all source files for any header
modification.
</para>
<title><systemitem>--enable-explicit-deps</systemitem> and
<systemitem>--disable-explicit-deps</systemitem></title>
<para>
- If <systemitem>--enable-explicit-deps</systemitem> is
- specified then GTK+ will write the full set of libraries
- that GTK+ depends upon into its <literal>.pc</literal> files to be used when
- programs depending on GTK+ are linked. Otherwise, GTK+
- only will include the GTK+ libraries themselves, and
- will depend on system library dependency facilities to
- bring in the other libraries.
- By default GTK+ will disable explicit dependencies unless
- it detects that they are needed on the system. (If you
- specify <systemitem>--enable-static</systemitem> to force
- building of static libraries, then explicit dependencies
- will be written since library dependencies don't work
- for static libraries.) Specifying
- <systemitem>--enable-explicit-deps</systemitem> or
- <systemitem>--enable-static</systemitem> can cause
- compatibility
- problems when libraries that GTK+ depends upon change
- their versions, and should be avoided if possible.
+ If <systemitem>--enable-explicit-deps</systemitem> is
+ specified then GTK+ will write the full set of libraries
+ that GTK+ depends upon into its <literal>.pc</literal> files to be used when
+ programs depending on GTK+ are linked. Otherwise, GTK+
+ only will include the GTK+ libraries themselves, and
+ will depend on system library dependency facilities to
+ bring in the other libraries.
+ By default GTK+ will disable explicit dependencies unless
+ it detects that they are needed on the system. (If you
+ specify <systemitem>--enable-static</systemitem> to force
+ building of static libraries, then explicit dependencies
+ will be written since library dependencies don't work
+ for static libraries.) Specifying
+ <systemitem>--enable-explicit-deps</systemitem> or
+ <systemitem>--enable-static</systemitem> can cause
+ compatibility
+ problems when libraries that GTK+ depends upon change
+ their versions, and should be avoided if possible.
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-shm</systemitem> and
<systemitem>--enable-shm</systemitem></title>
-
+
<para>
- These options can be used to control whether GTK+ will use shared
+ These options can be used to control whether GTK+ will use shared
memory to communicate with the X server when possible.
The default is 'yes'.
</para>
<formalpara>
<title><systemitem>--disable-xim</systemitem> and
<systemitem>--enable-xim</systemitem></title>
-
+
<para>
- These options can be used to control whether GTK+ will
+ These options can be used to control whether GTK+ will
be compiled with support for XIM. (The X Input Method
- extension, used for Japanese input.) The default is yes.
+ extension, used for Japanese input.) The default is yes.
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-xim-inst</systemitem> and
<systemitem>--enable-xim-inst</systemitem></title>
-
+
<para>
- These options determine whether GTK+ will use the
- XIM instantiate callback.
+ These options determine whether GTK+ will use the
+ XIM instantiate callback.
The default is 'yes', unless the host system is Solaris,
- where <function>XRegisterIMInstantiateCallback()</function>
- seems to cause a segfault.
+ where <function>XRegisterIMInstantiateCallback()</function>
+ seems to cause a segfault.
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-xkb</systemitem> and
<systemitem>--enable-xkb</systemitem></title>
-
+
<para>
- By default the <command>configure</command> script will try
- to auto-detect whether the XKB extension is supported by
+ By default the <command>configure</command> script will try
+ to auto-detect whether the XKB extension is supported by
the X libraries GTK+ is linked with.
These options can be used to explicitly control whether
- GTK+ will support the XKB extension.
+ GTK+ will support the XKB extension.
</para>
</formalpara>
<formalpara>
<title><systemitem>--disable-xinerama</systemitem> and
<systemitem>--enable-xinerama</systemitem></title>
-
+
<para>
By default the <command>configure</command> script will try
to link against the Xinerama libraries if they are found.
</formalpara>
<formalpara>
- <title><systemitem>--disable-gtk-doc</systemitem> and
- <systemitem>--enable-gtk-doc</systemitem></title>
-
- <para>
- The <application>gtk-doc</application> package is
- used to generate the reference documentation included
- with GTK+. By default support for <application>gtk-doc</application>
- is disabled because it requires various extra dependencies
- to be installed. If you have
- <application>gtk-doc</application> installed and
- are modifying GTK+, you may want to enable
- <application>gtk-doc</application> support by passing
- in <systemitem>--enable-gtk-doc</systemitem>. If not
- enabled, pre-generated HTML files distributed with GTK+
- will be installed.
- </para>
+ <title><systemitem>--disable-gtk-doc</systemitem> and
+ <systemitem>--enable-gtk-doc</systemitem></title>
+
+
The <application>gtk-doc</application> package is
+ used to generate the reference documentation included
+ with GTK+. By default support for <application>gtk-doc</application>
+ is disabled because it requires various extra dependencies
+ to be installed. If you have
+
<application>gtk-doc</application> installed and
+ are modifying GTK+, you may want to enable
+
<application>gtk-doc</application> support by passing
+ in <systemitem>--enable-gtk-doc</systemitem>. If not
+ enabled, pre-generated HTML files distributed with GTK+
+ will be installed.
+ </para>
</formalpara>
<formalpara>
- <title><systemitem>--disable-cups</systemitem> and
- <systemitem>--enable-cups</systemitem></title>
+ <title><systemitem>--disable-cups</systemitem> and
+ <systemitem>--enable-cups</systemitem></title>
- <para>
By default the <command>configure</command> script will try
to build the cups print backend if the cups libraries are found.
These options can be used to explicitly control whether
</para>
</formalpara>
+ <formalpara>
+ <title><systemitem>--disable-papi</systemitem> and
+ <systemitem>--enable-papi</systemitem></title>
+
+ <para>
+ By default the <command>configure</command> script will try
+ to build the papi print backend if the papi libraries are found.
+ These options can be used to explicitly control whether
+ the papi print backend should be built.
+ </para>
+ </formalpara>
+
<formalpara>
<title><systemitem>--with-xinput</systemitem></title>
<para>
- Controls whether GTK+ is built with support for the XInput
- extension. The XInput extension provides an interface
- to extended input devices such as graphics tablets.
- When this support is compiled in, specially written
- GTK+ programs can get access to subpixel positions,
- multiple simultaneous input devices, and extra "axes"
- provided by the device such as pressure and tilt
- information. This is only known to work well on XFree86
- systems, though other systems do have this extension.
+ Controls whether GTK+ is built with support for the XInput
+ or XInput2 extension. These extensions provide an extended
+ interface to input devices such as graphics tablets.
+ When this support is compiled in, specially written
+ GTK+ programs can get access to subpixel positions,
+ multiple simultaneous input devices, and extra "axes"
+ provided by the device such as pressure and tilt
+ information.
</para>
</formalpara>
<formalpara>
- <title><systemitem>--with-gdktarget</systemitem></title>
+ <title><systemitem>--with-gdktarget</systemitem></title>
- <para>
- Toggles between the supported backends for GDK.
+ Toggles between the supported backends for GDK.
The default is x11, unless the platform is Windows, in which
- case the default is win32. Other supported backends are
+ case the default is win32. Other supported backends are
the quartz backend for OS X, and the DirectFB backend
for the Linux framebuffer.
- </para>
+ </para>
</formalpara>
<formalpara>
<title><systemitem>--disable-introspection</systemitem></title>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-changes-1-2" revision="1 Jan 2002">
-<refmeta>
-<refentrytitle>Changes from 1.0 to 1.2</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Changes from 1.0 to 1.2</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Changes from 1.0 to 1.2</refname>
-<refpurpose>
-Incompatible changes made between version 1.0 and version 1.2
-</refpurpose>
-</refnamediv>
-
-
-<refsect1>
-<title>Incompatible changes from 1.0 to 1.2</title>
-
-<itemizedlist>
-
-<listitem>
-<para>
-<structname>GtkAcceleratorTable</structname> has been replaced with
-<structname>GtkAccelGroup</structname>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkMenuFactory</structname> has been replaced with
-<structname>GtkItemFactory</structname>, although
-a version of <structname>GtkMenuFactory</structname> is currently still
-provided to ease the migration phase.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structname>GtkTypeInfo</structname> structures used in the
-<function>gtk_*_type_init()</function> functions have
-changed a bit, the old format:
-<programlisting>
- GtkTypeInfo bin_info =
- {
- "GtkBin",
- sizeof (GtkBin),
- sizeof (GtkBinClass),
- (GtkClassInitFunc) gtk_bin_class_init,
- (GtkObjectInitFunc) gtk_bin_init,
- (GtkArgSetFunc) NULL,
- (GtkArgGetFunc) NULL,
- };
-</programlisting>
-
- needs to be converted to:
-
-<programlisting>
- static const GtkTypeInfo bin_info =
- {
- "GtkBin",
- sizeof (GtkBin),
- sizeof (GtkBinClass),
- (GtkClassInitFunc) gtk_bin_class_init,
- (GtkObjectInitFunc) gtk_bin_init,
- /* reserved_1 */ NULL,
- /* reserved_2 */ NULL,
- (GtkClassInitFunc) NULL,
- };
-</programlisting>
-
- the <function>GtkArgSetFunc</function> and <function>GtkArgGetFunc</function>
- functions are not supported from the type system anymore, and you should make
- sure that your code only fills in these fields with <literal>NULL</literal>
- and doesn't use the deprecated function typedefs
- <literal>(GtkArgSetFunc)</literal> and <literal>(GtkArgGetFunc)</literal>
- anymore.
-</para>
-</listitem>
-
-<listitem>
-<para>
-A number of GTK+ functions were renamed. For compatibility,
- <filename>gtkcompat.h</filename> #define's the old 1.0.x function names in
- terms of the new names. To assure your GTK+ program doesn't rely on outdated
- function variants, compile your program with
- <option>-DGTK_DISABLE_COMPAT_H</option> to disable
- the compatibility aliases.
-
- Here is the list of the old names and replacements:
-
-<informaltable>
-<tgroup cols="2">
-<thead>
-<row><entry>Old</entry><entry>Replacement</entry></row>
-</thead>
-<tbody>
-<row><entry><function>gtk_accel_label_accelerator_width</function></entry><entry><function>gtk_accel_label_get_accel_width</function></entry></row>
-<row><entry><function>gtk_check_menu_item_set_state</function></entry><entry><function>gtk_check_menu_item_set_active</function></entry></row>
-<row><entry><function>gtk_container_border_width</function></entry><entry><function>gtk_container_set_border_width</function></entry></row>
-<row><entry><function>gtk_label_set</function></entry><entry><function>gtk_label_set_text</function></entry></row>
-<row><entry><function>gtk_notebook_current_page</function></entry><entry><function>gtk_notebook_get_current_page</function></entry></row>
-<row><entry><function>gtk_packer_configure</function></entry><entry><function>gtk_packer_set_child_packing</function></entry></row>
-<row><entry><function>gtk_paned_gutter_size</function></entry><entry><function>gtk_paned_set_gutter_size</function></entry></row>
-<row><entry><function>gtk_paned_handle_size</function></entry><entry><function>gtk_paned_set_handle_size</function></entry></row>
-<row><entry><function>gtk_scale_value_width</function></entry><entry><function>gtk_scale_get_value_width</function></entry></row>
-<row><entry><function>gtk_style_apply_default_pixmap</function></entry><entry><function>gtk_style_apply_default_background</function></entry></row>
-<row><entry><function>gtk_toggle_button_set_state</function></entry><entry><function>gtk_toggle_button_set_active</function></entry></row>
-<row><entry><function>gtk_window_position</function></entry><entry><function>gtk_window_set_position</function></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-Note that <function>gtk_style_apply_default_background()</function> has an
- additional argument, <literal>set_bg</literal>. This parameter should be
- <literal>FALSE</literal> if the background is being set for a
- <literal>NO_WINDOW</literal> widget, otherwise <literal>TRUE</literal>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-During the development phase of the 1.1.x line of GTK+ certain functions
- were deprecated and later removed. Functions affected are:
-
-<informaltable>
-<tgroup cols="2">
-<thead>
-<row><entry>Removed</entry><entry>Replacement</entry></row>
-</thead>
-<tbody>
-<row><entry><function>gtk_clist_set_border</function></entry><entry><function>gtk_clist_set_shadow_type</function></entry></row>
-<row><entry><function>gtk_container_block_resize</function></entry><entry><function>gtk_container_set_resize_mode</function></entry></row>
-<row><entry><function>gtk_container_unblock_resize</function></entry><entry><function>gtk_container_set_resize_mode</function></entry></row>
-<row><entry><function>gtk_container_need_resize</function></entry><entry><function>gtk_container_check_resize</function></entry></row>
-<row><entry><function>gtk_ctree_show_stub</function></entry><entry><function>gtk_ctree_set_show_stub</function></entry></row>
-<row><entry><function>gtk_ctree_set_reorderable</function></entry><entry><function>gtk_clist_set_reorderable</function></entry></row>
-<row><entry><function>gtk_ctree_set_use_drag_icons</function></entry><entry><function>gtk_clist_set_use_drag_icons</function></entry></row>
-<row><entry><function>gtk_entry_adjust_scroll</function></entry><entry><function>-</function></entry></row>
-<row><entry><function>gtk_object_class_add_user_signal</function></entry><entry><function>gtk_object_class_user_signal_new</function></entry></row>
-<row><entry><function>gtk_preview_put_row</function></entry><entry><function>gtk_preview_put</function></entry></row>
-<row><entry><function>gtk_progress_bar_construct</function></entry><entry><function>gtk_progress_set_adjustment</function></entry></row>
-<row><entry><function>gtk_scrolled_window_construct</function></entry><entry><function>gtk_scrolled_window_set_{h|v}adjustment</function></entry></row>
-<row><entry><function>gtk_spin_button_construct</function></entry><entry><function>gtk_spin_button_configure</function></entry></row>
-<row><entry><function>gtk_widget_thaw_accelerators</function></entry><entry><function>gtk_widget_unlock_accelerators</function></entry></row>
-<row><entry><function>gtk_widget_freeze_accelerators</function></entry><entry><function>gtk_widget_lock_accelerators</function></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-
-Note that <function>gtk_entry_adjust_scroll()</function> is no longer needed
- as <structname>GtkEntry</structname> should automatically keep the scroll
- adjusted properly.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-Additionally, all <function>gtk_*_interp()</function> functions were removed.
- <function>gtk_*_full()</function> versions were provided as of GTK+ 1.0 and
- should be used instead.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkButton</structname> has been changed to derive from
-<structname>GtkBin</structname>.
- To access a button's child, use <literal>GTK_BIN (button)->child</literal>,
- instead of the old <literal>GTK_BUTTON (button)->child</literal>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The selection API has been slightly modified:
-
- <function>gtk_selection_add_handler()</function> and
- <function>gtk_selection_add_handler_full()</function>
- have been removed. To supply the selection, one now registers
- the targets one is interested in with:
-
-<programlisting>
- void gtk_selection_add_target (GtkWidget *widget,
- GdkAtom selection,
- GdkAtom target,
- guint info);
-</programlisting>
-
- or:
-
-<programlisting>
- void gtk_selection_add_targets (GtkWidget *widget,
- GdkAtom selection,
- GtkTargetEntry *targets,
- guint ntargets);
-</programlisting>
-
- When a request for a selection is received, the new "selection_get"
- signal will be called:
-
-<programlisting>
- void "selection_get" (GtkWidget *widget,
- GtkSelectionData *selection_data,
- guint info,
- guint time);
-</programlisting>
-
- A "time" parameter has also been added to the "selection_received"
- signal.
-
-<programlisting>
- void "selection_received" (GtkWidget *widget,
- GtkSelectionData *selection_data,
- guint time);
-</programlisting>
-</para>
-</listitem>
-
-<listitem>
-<para>
-The old drag and drop API has been completely removed and replaced.
- See the reference documentation for details on the new API.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Support for Themes has been added. In general, this does
- not affect application code, however, a few new rules should
- be observed:
-
- <itemizedlist>
- <listitem>
- <para>To set a shape for a window, you must use
- <function>gtk_widget_shape_combine_mask()</function> instead of
- <function>gdk_window_shape_combine_mask()</function>, or the shape will be
- reset when switching themes.
- </para>
- </listitem>
-
- <listitem>
- <para>It is no longer permissable to draw directly on an arbitrary
- widget, or to set an arbitrary widget's background pixmap.
- If you need to do that, use a <structname>GtkDrawingArea</structname> or
- (for a toplevel) a <structname>GtkWindow</structname> where
- <function>gtk_widget_set_app_paintable()</function>
- has been called.
- </para>
- </listitem>
- </itemizedlist>
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structname>GtkScrolledWindow</structname> widget no longer creates a
- <structname>GtkViewport</structname> automatically. Instead, it has been
- generalized to accept any "self-scrolling" widget.
-</para>
-
-<para>
- The self-scrolling widgets in the GTK+ core are
- <structname>GtkViewport</structname>,
- <structname>GtkCList</structname>, <structname>GtkCTree</structname>,
- <structname>GtkText</structname>, and <structname>GtkLayout</structname>.
- All of these widgets can be added to a scrolled window as normal children with
- <function>gtk_container_add()</function> and scrollbars will be set up
- automatically.
-</para>
-
-<para>
- To add scrollbars to a non self-scrolling widget, (such as a
- <structname>GtkList</structname>),
- first add it to a viewport, then add the viewport to a scrolled window.
- The scrolled window code provides a convenience function to do this:
-
-<programlisting>
- void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrollwin,
- GtkWidget *child);
-</programlisting>
-
- This does exactly what it says - it creates a viewport, adds the child
- widget to it, then adds the viewport to the scrolled window.
-</para>
-
-<para>
- The scrollbars have been removed from the <structname>GtkCList</structname>
- and <structname>GtkCTree</structname>, because they are now scrolled by simply
- adding them to a scrolled window. The scrollbar policy is set on the scrolled
- window with <function>gtk_scrolled_window_set_policy()</function> and not on
- the child widgets (e.g. <structname>GtkCList</structname>'s
- <function>gtk_clist_set_policy()</function> was removed).
-</para>
-</listitem>
-
-<listitem>
-<para>
-The "main loop" of GTK+ has been moved to GLib. This should not
- affect existing programs, since compatibility functions have
- been provided. However, you may want to consider migrating
- your code to use the GLib main loop directly.
-</para>
-</listitem>
-
-<listitem>
-<para>
-the <literal>GTK_BASIC</literal> flag was removed, and with it the corresponding
- macro and function <function>GTK_WIDGET_BASIC()</function> and
- <function>gtk_widget_basic()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-All freeze/thaw methods are now recursive - that is, if you
- freeze a widget n times, you must also thaw it n times.
-
- Therefore, if you have code like:
-
-<informalexample><programlisting>
- gboolean frozen;
- frozen = GTK_CLIST_FROZEN (clist);
- gtk_clist_freeze (clist);
- [...]
- if (!frozen)
- gtk_clist_thaw (clist);
-</programlisting></informalexample>
-
- it will not work anymore. It must be, simply:
-
-<informalexample><programlisting>
- gtk_clist_freeze (clist);
- [...]
- gtk_clist_thaw (clist);
-</programlisting></informalexample>
-</para>
-</listitem>
-
-<listitem>
-<para>
-The thread safety in GTK+ 1.2 is slightly different than
- that which appeared in early versions in the 1.1
- development track. The main difference is that it relies on
- the thread primitives in GLib, and on the thread-safe
- GLib main loop.
-</para>
-
-<para>
- This means:
-
-<itemizedlist>
- <listitem>
- <para>You must call <function>g_thread_init()</function> before
- executing any other GTK+ or GDK functions in a threaded GTK+ program.
- </para>
- </listitem>
-
- <listitem>
- <para>Idles, timeouts, and input functions are executed outside
- of the main GTK+ lock. So, if you need to call GTK+
- inside of such a callback, you must surround the callback
- with a <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function>
- pair.
- </para>
-
- <para>However, signals are still executed within the main
- GTK+ lock.
- </para>
-
- <para>In particular, this means, if you are writing widgets
- that might be used in threaded programs, you <emphasis>must</emphasis>
- surround timeouts and idle functions in this matter.
- </para>
-
- <para>As always, you must also surround any calls to GTK+
- not made within a signal handler with a
- <function>gdk_threads_enter()</function>/<function>gdk_threads_leave()</function>
- pair.
- </para>
- </listitem>
-
- <listitem>
- <para>There is no longer a special <option>--with-threads</option>
- <command>configure</command> option for GTK+. To use threads in a GTK+
- program, you must:
-
- <orderedlist>
- <listitem>
- <para>If you want to use the native thread implementation,
- make sure GLib found this in configuration, otherwise,
- call you must provide a thread implementation to
- <function>g_thread_init()</function>.
- </para>
- </listitem>
- <listitem>
- <para>Link with the libraries returned by
- <command>gtk-config --libs gthread</command>
- and use the cflags from
- <command>gtk-config --cflags gthread</command>.
- You can get these <envar>CFLAGS</envar> and <envar>LIBS</envar> by
- passing <literal>gthread</literal> as the fourth parameter to the
- <literal>AM_PATH_GTK</literal> <application>automake</application>
- macro.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </listitem>
- </itemizedlist>
-</para>
-</listitem>
-
-<listitem>
-<para>
-Prior to GTK+ 1.2, there were two conflicting interpretations
- of <literal>widget->requisition</literal>. It was either taken to be
- the size that the widget requested, or that size modified by calls to
- <function>gtk_widget_set_usize()</function>. In GTK+ 1.2,
- it is always interpreted the first way.
-</para>
-
-<para>
- Container widgets are affected in two ways by this:
-
- <orderedlist>
- <listitem>
- <para>Container widgets should not pass
- <literal>widget->requisition</literal> as the second parameter to
- <function>gtk_widget_size_request()</function>.
- Instead they should call it like:
- <programlisting>
- GtkRequisition child_requisition;
- gtk_widget_size_request (widget, &child_requisition);
- </programlisting>
- </para>
- </listitem>
- <listitem>
- <para>Container widgets should not access
- <literal>child->requisition</literal> directly. Either they should use
- the values returned by <function>gtk_widget_size_request()</function>,
- or they should call the new function:
- <programlisting>
- void gtk_widget_get_child_requisition (GtkWidget *widget,
- GtkRequisition *requisition);
- </programlisting>
- which returns the requisition of the given widget, modified
- by calls to <function>gtk_widget_set_usize()</function>.
- </para>
- </listitem>
- </orderedlist>
-</para>
-</listitem>
-
-
-</itemizedlist>
-
-</refsect1>
-
-</refentry>
-
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-changes-2-0" revision="1 Jan 2002">
-<refmeta>
-<refentrytitle>Changes from 1.2 to 2.0</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>Changes from 1.2 to 2.0</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Changes from 1.2 to 2.0</refname>
-<refpurpose>
-Incompatible changes made between version 1.2 and version 2.0
-</refpurpose>
-</refnamediv>
-
-
-<refsect1>
-<title>Incompatible changes from 1.2 to 2.0</title>
-
-<para>
-The <ulink url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0
-porting guide</ulink> on <ulink
-url="http://developer.gnome.org">http://developer.gnome.org</ulink>
-has some more detailed discussion of porting from 1.2 to 2.0.
-See the sections on GLib and GTK+.
-</para>
-
-<para>
-GTK+ changed fairly substantially from version 1.2 to 2.0, much more
-so than from 1.0 to 1.2. Subsequent updates (possibilities are 2.0 to
-2.2, 2.2 to 2.4, then to 3.0) will almost certainly be much, much
-smaller. Nonetheless, most programs written for 1.2 compile against
-2.0 with few changes. The bulk of changes listed below are to obscure
-features or very specialized features, and compatibility interfaces
-exist whenever possible.
-</para>
-
-<itemizedlist>
-
-<listitem>
-<para>
-<function>gtk_container_get_toplevels()</function> was removed and replaced
- with <function>gtk_window_list_toplevels()</function>, which has different
- memory management on the return value
- (<function>gtk_window_list_toplevels()</function> copies the
- <structname>GList</structname> and also references each widget in the list,
- so you have to <function>g_list_free()</function> the list after first
- unref'ing each list member).
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <function>gdk_time*</function> functions have been removed. This
- functionality has been unused since the main loop was moved into GLib
- prior to 1.2.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The signature for <function>GtkPrintFunc</function> (used for
- <function>gtk_item_factory_dump_items()</function>)
- has been changed to take a <type>const gchar *</type> instead of
- <type>gchar *</type>, to match what we do for GLib, and other similar cases.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The detail arguments in the <structname>GtkStyleClass</structname> structure
-are now <type>const gchar *</type>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_paned_set_gutter_size()</function> has been removed, since the
- small handle tab has been changed to include the entire area previously
- occupied by the gutter.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_paned_set_handle_size()</function> has been removed, in favor of
- a style property, since this is an option that only makes sense for themes
- to adjust.
-</para>
-</listitem>
-
-<listitem>
-<para>
-GDK no longer selects OwnerGrabButtonMask for button presses. This means
- that the automatic grab that occurs when the user presses a button
- will have <literal>owner_events = FALSE</literal>, so all events are
- redirected to the grab window, even events that would normally go to
- other windows of the window's owner.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkColorSelectionDialog</structname> has now been moved into it's
- own set of files, <filename>gtkcolorseldialog.c</filename> and
- <filename>gtkcolorseldialog.h</filename>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_widget_shape_combine_mask()</function> now keeps a reference
- count on the mask pixmap that is passed in.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structname>GtkPatternSpec</structname> has been moved to GLib as
- <structname>GPatternSpec</structname>, the pattern
- arguments to <function>gtk_item_factory_dump_items()</function> and
- <function>gtk_item_factory_dump_rc()</function>
- have thusly been changed to take a <structname>GPatternSpec</structname>
- instead of a <structname>GtkPatternSpec</structname>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Type system changes:
-<itemizedlist>
-<listitem>
-<para>
- <literal>GTK_TYPE_OBJECT</literal> is not a fundamental type anymore. Type checks of the
- style <literal>(GTK_FUNDAMENTAL_TYPE (some_type) == GTK_TYPE_OBJECT)</literal>
- will not work anymore. As a replacement, <literal>(GTK_TYPE_IS_OBJECT (some_type))</literal>
- can be used now.
-</para>
-</listitem>
-<listitem>
-<para>
-The following types vanished: <literal>GTK_TYPE_ARGS</literal>, <literal>GTK_TYPE_CALLBACK</literal>,
- <literal>GTK_TYPE_C_CALLBACK</literal>, <literal>GTK_TYPE_FOREIGN</literal>. The corresponding <structname>GtkArg</structname>
- fields and field access macros are also gone.
-</para>
-</listitem>
-<listitem>
-<para>
-The following type aliases vanished: <literal>GTK_TYPE_FLAT_FIRST</literal>,
- <literal>GTK_TYPE_FLAT_LAST</literal>, <literal>GTK_TYPE_STRUCTURED_FIRST</literal>,
- <literal>GTK_TYPE_STRUCTURED_LAST</literal>.
-</para>
-</listitem>
-<listitem>
-<para>
-The type macros <function>GTK_TYPE_MAKE()</function> and <function>GTK_TYPE_SEQNO()</function> vanished, use of
- <function>GTK_FUNDAMENTAL_TYPE()</function> is discouraged. Instead, the corresponding <structname>GType</structname>
- API should be used: <function>G_TYPE_FUNDAMENTAL()</function>, <function>G_TYPE_DERIVE_ID()</function>,
- <function>G_TYPE_BRANCH_SEQNO()</function>. Note that the GLib type system doesn't build new
- type ids based on a global incremental sequential number anymore, but
- numbers new type ids sequentially per fundamental type branch.
-</para>
-</listitem>
-<listitem>
-<para>
-The following type functions vanished/were replaced:
-<informaltable>
-<tgroup cols="2">
-<thead>
-<row><entry>Old Function</entry><entry>Replacement</entry></row>
-</thead>
-<tbody>
-<row><entry><function>gtk_type_query()</function></entry><entry>being investigated</entry></row>
-<row><entry><function>gtk_type_set_varargs_type()</function></entry><entry>-</entry></row>
-<row><entry><function>gtk_type_get_varargs_type()</function></entry><entry>-</entry></row>
-<row><entry><function>gtk_type_check_object_cast()</function></entry><entry><function>g_type_check_instance_cast()</function></entry></row>
-<row><entry><function>gtk_type_check_class_cast()</function></entry><entry><function>g_type_check_class_cast()</function></entry></row>
-<row><entry><function>gtk_type_describe_tree()</function></entry><entry>-</entry></row>
-<row><entry><function>gtk_type_describe_heritage()</function></entry><entry>-</entry></row>
-<row><entry><function>gtk_type_free()</function></entry><entry>-</entry></row>
-<row><entry><function>gtk_type_children_types()</function></entry><entry><function>g_type_children()</function></entry></row>
-<row><entry><function>gtk_type_set_chunk_alloc()</function></entry><entry><structfield>GTypeInfo.n_preallocs</structfield></entry></row>
-<row><entry><function>gtk_type_register_enum()</function></entry><entry><function>g_enum_register_static()</function></entry></row>
-<row><entry><function>gtk_type_register_flags()</function></entry><entry><function>g_flags_register_static()</function></entry></row>
-<row><entry><function>gtk_type_parent_class()</function></entry><entry><function>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
- Use of <function>g_type_class_ref()</function>/<function>g_type_class_unref()</function> and <function>g_type_class_peek()</function>
- is recommended over usage of <function>gtk_type_class()</function>.
- Use of <function>g_type_register_static()</function>/<function>g_type_register_dynamic()</function> is recommended
- over usage of <function>gtk_type_unique()</function>.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-</listitem>
-
-<listitem>
-<para>
-Object system changes:
- <structname>GtkObject</structname> derives from <structname>GObject</structname>, so is not the basic object type anymore.
- This imposes the following source incompatible changes:
-<itemizedlist>
-
-<listitem>
-<para>
-<structname>GtkObject</structname> has no <structfield>klass</structfield> field anymore, an object's class can be retrieved
- with the object's coresponding <literal>GTK_<OBJECT>_GET_CLASS (object)</literal>
- macro.
-</para>
-</listitem>
-<listitem>
-<para>
-<structname>GtkObjectClass</structname> has no <structfield>type</structfield> field anymore, a class's type can be retrived
- with the <literal>GTK_CLASS_TYPE (class)</literal> macro.
-</para>
-</listitem>
-<listitem>
-<para>
-<structname>GtkObjectClass</structname> does not introduce the <function>finalize()</function> and <function>shutdown()</function> methods
- anymore. While <function>shutdown()</function> is intended for GTK+ internal use only, <function>finalize()</function>
- is required by a variety of object implementations. <function>GObjectClass.finalize</function>
- should be overriden here, e.g.:
-<informalexample><programlisting>
- static void gtk_label_finalize (GObject *gobject)
- {
- GtkLabel *label = GTK_LABEL (gobject);
-
- G_OBJECT_CLASS (parent_class)->finalize (object);
- }
- static void gtk_label_class_init (GtkLabelClass *class)
- {
- GObjectClass *gobject_class = G_OBJECT_CLASS (class);
-
- gobject_class->finalize = gtk_label_finalize;
- }
-</programlisting></informalexample>
-</para>
-</listitem>
-
-</itemizedlist>
-</para>
-</listitem>
-
-<listitem>
-<para>
-The GtkObject::destroy signal can now be emitted multiple times on an object.
- ::destroy implementations should check that make sure that they take this
- into account, by checking to make sure that resources are there before
- freeing them. For example:
-<informalexample><programlisting>
- if (object->foo_data)
- {
- g_free (object->foo_data);
- object->foo_data = NULL;
- }
-</programlisting></informalexample>
-
- Also, ::destroy implementations have to release object references that
- the object holds. Code in finalize implementations such as:
-<informalexample><programlisting>
- if (object->adjustment)
- {
- gtk_object_unref (object->adjustment);
- object->adjustment = NULL;
- }
-</programlisting></informalexample>
- have to be moved into the ::destroy implementations. The reason for doing
- this is that all object reference cycles should be broken at destruction
- time.
-
- Because the ::destroy signal can be emitted multiple times, it no longer
- makes sense to check if a widget has been destroyed using the
- <function>GTK_OBJECT_DESTROYED()</function> macro, and this macro has been
- removed. If catching destruction is still needed, it can be done with a
- signal connection to ::destroy.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Signal system changes:
- The GTK+ 2.0 signal system merely proxies the <structname>GSignal</structname>
- system now. For future usage, direct use of the
- <structname>GSignal</structname> API is recommended,
- this avoids significant performance hits where <structname>GtkArg</structname>
- structures have to be converted into <structname>GValue</structname>s. For
- language bindings, <structname>GSignal</structname>+<structname>GClosure</structname>
- provide a much more flexible and convenient mechanism to hook into signal
- emissions or install class default handlers, so the old
- <structname>GtkSignal</structname> API for language bindings is not
- supported anymore.
-</para>
-<para>
- Functions that got removed in the GTK+ signal API:
- <function>gtk_signal_n_emissions()</function>,
- <function>gtk_signal_n_emissions_by_name()</function>,
- <function>gtk_signal_set_funcs()</function>,
- <function>gtk_signal_handler_pending_by_id()</function>,
- <function>gtk_signal_add_emission_hook()</function>,
- <function>gtk_signal_add_emission_hook_full()</function>,
- <function>gtk_signal_remove_emission_hook()</function>,
- <function>gtk_signal_query()</function>.
- Also, the <structname>GtkCallbackMarshal</structname> argument to
- <function>gtk_signal_connect_full()</function> is
- not supported anymore.
- For many of the removed functions, similar variants are available
- in the <function>g_signal_*</function> namespace.
- The <structname>GSignal</structname> system performs emissions in a
- slightly different manner than the old <structname>GtkSignal</structname>
- code. Signal handlers that are connected to signal "foo"
- on object "bar" while "foo" is being emitted, will not be called anymore
- during the emission they were connected within.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Inserting and deleting text in <structname>GtkEntry</structname> though
- functions such as <function>gtk_entry_insert_text()</function> now leave
- the cursor at its original position in the text instead of moving it to
- the location of the insertion/deletion.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structfield>label</structfield> field of <structname>GtkFrame</structname>
- widgets has been removed (as part of a change to allow arbitrary widgets
- in the title position). The text can now be retrieved with the new function
- <function>gtk_frame_get_text()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The 'font' and 'font_set' declarations in RC files are now ignored. There
- is a new 'font_name' field that holds the string form of a Pango font.
-</para>
-</listitem>
-
-<listitem>
-<para>
-A number of types in GDK have become subclasses of
- <structname>GObject</structname>. For the most part, this should not break
- anyone's code. However, it's now possible/encouraged to use
- <function>g_object_ref()</function>/<function>g_object_unref()</function> and
- other <structname>GObject</structname> features with these GDK types. The
- converted types are:
- <structname>GdkWindow</structname>, <structname>GdkDrawable</structname>,
- <structname>GdkPixmap</structname>, <structname>GdkImage</structname>,
- <structname>GdkGC</structname>, <structname>GdkDragContext</structname>,
- <structname>GdkColormap</structname>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-All drawables including pixmaps used to have a type tag, the
- <structname>GdkWindowType</structname> enumeration, which included
- <literal>GDK_WINDOW_PIXMAP</literal>.
- <structname>GdkWindowType</structname> is now a property of
- <structname>GdkWindow</structname> <emphasis>only</emphasis>, and there is
- no <literal>GDK_WINDOW_PIXMAP</literal>. You can use the
- <function>GDK_IS_PIXMAP()</function> macro to see if you have a pixmap, if
- you need to know that.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkStyle</structname> and <structname>GtkRcStyle</structname> are
- now subclasses of <structname>GObject</structname> as well. This
- requires fairly extensive changes to theme engines, but
- shouldn't affect most other code.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structfield>xthickness</structfield> and <structfield>ythickness</structfield> have moved from
- <structname>GtkStyleClass</structname> to <structname>GtkStyle</structname>
- (from class to instance). This gives themes a bit more flexibility
- and is generally more of the Right Thing. You can trivially fix
- your code with <literal>s/style->klass->xthickness/style->xthickness/g</literal> and
- same for <literal>ythickness</literal>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Some <structname>GtkStyle</structname> <function>draw_*</function> methods
- have been removed (cross, oval, ramp)
- and others have been added (expander, layout). This will require
- changes to theme engines.
-</para>
-</listitem>
-
-<listitem>
-<para>
-If you were using private GDK types, they have been rearranged
- significantly. You shouldn't use private types. ;-)
-</para>
-</listitem>
-
-<listitem>
-<para>
-The visual for a widget, and also the default visual is now derived
- from the colormap for the widget and the default colormap.
- <function>gtk_widget_set_visual()</function>,
- <function>gtk_widget_set_default_visual()</function>,
- <function>gtk_widget_push_visual()</function> and
- <function>gtk_widget_pop_visual()</function> now do
- nothing. Since the visual always had to match that of the colormap,
- it is safe to simply delete all references to these functions.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-A number of functions in GDK have been renamed for consistency and
- clarity. #defines to provide backwards compatibility have been
- included, but can be disabled by defining <literal>GDK_DISABLE_DEPRECATED</literal>.
-
-<informaltable>
-<tgroup cols="2">
-<thead>
-<row><entry>Old function</entry><entry>Defined As</entry></row>
-</thead>
-<tbody>
-<row><entry><function>gdk_draw_pixmap</function></entry><entry><function>gdk_draw_drawable</function></entry></row>
- <row><entry><function>gdk_draw_bitmap</function></entry><entry><function>gdk_draw_drawable</function></entry></row>
-<row><entry><function>gdk_window_get_size</function></entry><entry><function>gdk_drawable_get_size</function></entry></row>
-<row><entry><function>gdk_window_get_type</function></entry><entry><function>gdk_window_get_window_type</function></entry></row>
-<row><entry><function>gdk_window_get_colormap</function></entry><entry><function>gdk_drawable_get_colormap</function></entry></row>
-<row><entry><function>gdk_window_set_colormap</function></entry><entry><function>gdk_drawable_set_colormap</function></entry></row>
-<row><entry><function>gdk_window_get_visual</function></entry><entry><function>gdk_drawable_get_visual</function></entry></row>
-<row><entry><function>gdk_window_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
-<row><entry><function>gdk_window_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
-<row><entry><function>gdk_bitmap_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
-<row><entry><function>gdk_bitmap_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
-<row><entry><function>gdk_pixmap_ref</function></entry><entry><function>gdk_drawable_ref</function></entry></row>
-<row><entry><function>gdk_pixmap_unref</function></entry><entry><function>gdk_drawable_unref</function></entry></row>
-<row><entry><function>gdk_gc_destroy</function></entry><entry><function>gdk_gc_unref</function></entry></row>
-<row><entry><function>gdk_image_destroy</function></entry><entry><function>gdk_image_unref</function></entry></row>
-<row><entry><function>gdk_cursor_destroy</function></entry><entry><function>gdk_cursor_unref</function></entry></row>
-<row><entry><function>gdk_window_copy_area(drawable,gc,x,y,source_drawable,source_x,source_y,width,height)</function></entry><entry><function>gdk_draw_pixmap(drawable,gc,source_drawable,source_x,source_y,x,y,width,height)</function></entry></row>
-<row><entry><function>gdk_rgb_get_cmap</function></entry><entry><function>gdk_rgb_get_colormap</function></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
- (Note that <function>g_object_ref()</function> and
- <function>g_object_unref()</function> may be used for all of the above ref
- and unref functions.)
-
- <function>gtk_widget_popup()</function> was removed, it was only usable
- for <structname>GtkWindow</structname>s, and there the same effect can be
- achieved by <function>gtk_window_move()</function> and
- <function>gtk_widget_show()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gdk_pixmap_foreign_new()</function> no longer calls
- <function>XFreePixmap()</function> on the pixmap when the
- <structname>GdkPixmap</structname> is finalized. This change corresponds
- to the behavior of <function>gdk_window_foreign_new()</function>, and fixes
- a lot of problems with code where the pixmap wasn't supposed to be freed.
- If <function>XFreePixmap()</function> is needed, it can be done using the
- destroy-notification facilities of <function>g_object_set_data()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkProgress</structname>/<structname>GtkProgressBar</structname>
- had serious problems in GTK+ 1.2.
-<itemizedlist>
-<listitem>
-<para>
-Only 3 or 4 functions are really needed for 95% of progress interfaces;
- <structname>GtkProgress</structname>/<structname>GtkProgressBar</structname>
- had about 25 functions, and didn't even include these 3 or 4.
-</para>
-</listitem>
-
-<listitem>
-<para>
-In activity mode, the API involves setting the adjustment
- to any random value, just to have the side effect of
- calling the progress bar update function - the adjustment
- is totally ignored in activity mode.
-</para>
-</listitem>
-
-<listitem>
-<para>
-You set the activity step as a pixel value, which means to
- set the activity step you basically need to connect to
- size_allocate.
-</para>
-</listitem>
-
-<listitem>
-<para>
-There are <function>ctree_set_expander_style()</function>-functions, to
- randomly change look-and-feel for no good reason.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The split between <structname>GtkProgress</structname> and
-<structname>GtkProgressBar</structname> makes no sense to me whatsoever.
-</para>
-</listitem>
-
-</itemizedlist>
-
- This was a big wart on GTK+ and made people waste lots of time,
- both learning and using the interface.
- So, we have added what we feel is the correct API, and marked all the
- rest deprecated. However, the changes are 100% backward-compatible and
- should break no existing code.
- The following 5 functions are the new programming interface and you
- should consider changing your code to use them:
-<programlisting>
- void gtk_progress_bar_pulse (GtkProgressBar *pbar);
- void gtk_progress_bar_set_text (GtkProgressBar *pbar,
- const gchar *text);
- void gtk_progress_bar_set_fraction (GtkProgressBar *pbar,
- gfloat fraction);
-
- void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar,
- gfloat fraction);
- void gtk_progress_bar_set_orientation (GtkProgressBar *pbar,
- GtkProgressBarOrientation orientation);
-</programlisting>
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structname>GtkNotebookPage</structname> structure has been removed from
- the public header files;
- this was never meant to be a public structure, and all functionality that
- could be done by accessing the struct fields of this structure should be
- accessible otherwise.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Negative values of the <parameter>position</parameter> parameter to
- <function>gtk_notebook_reorder_child()</function> now cause the page to be appended, not
- inserted at the beginning. (This gives consistency with
- <function>gtk_box_reorder_child()</function>, <function>gtk_menu_reorder_child()</function>.)
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>GtkMenuPositionFunc</function> has a new parameter
- <literal>push_in</literal> which controls how menus placed outside the
- screen is handled. If this is set to <literal>TRUE</literal> and
- part of the menu is outside the screen then GTK+ pushes it into the visible
- area. Otherwise the menu is cut of at the end of the visible screen area.
-</para>
-<para>
- Regardless of what happens to the size of the menu, the result is always
- that the items are placed in the same place as if the menu was placed
- outside the screen, using menu scrolling if necessary.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The "draw" signal and virtual method on <structname>GtkWidget</structname>
- has been removed.
- All drawing should now occur by invalidating a region of the widget
- (call <function>gdk_window_invalidate_rect()</function> or
- <function>gtk_widget_queue_draw()</function> for example to invalidate
- a region). GTK+ merges all invalid regions, and sends expose events to
- the widget in an idle handler for the invalid regions.
- <function>gtk_widget_draw()</function> is deprecated but still works; it
- adds the passed-in area to the invalid region and immediately sends
- expose events for the current invalid region.
- Most widgets will work fine if you just delete their "draw"
- implementation, since they will already have working expose_event
- implementations. The draw method was rarely called in practice
- anyway.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structname>GdkExposeEvent</structname> has a new <structfield>region</structfield>
- field. This can be used instead of the <structfield>area</structfield> field if you
- want a more exact representation of the area to update.
-</para>
-</listitem>
-
-<listitem>
-<para>
-Sending synthetic exposes using <function>gtk_widget_event()</function> is no
- longer allowed. If you just need an expose call you should use
- <function>gdk_window_invalidate_rect()</function> or
- <function>gdk_window_invalidate_region()</function> instead. For the case
- of container widgets that need to propagate expose events to
- <literal>NO_WINDOW</literal> children you can either use
- <function>gtk_container_propagate_expose()</function>, or chain to the
- default container expose handler.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The draw_default and draw_focus methods/signals on
- <structname>GtkWidget</structname> are gone; simply draw things in your
- expose handler. <function>gtk_widget_draw_focus()</function> and
- <function>gtk_widget_draw_default()</function> wrapper
- functions are also gone; just queue a draw on the widget,
- or the part affected by the focus/default anyway.
- Also, <structname>GtkWidget</structname> now has default implementations for
- focus_in_event and focus_out_event. These set/unset
- <literal>GTK_HAS_FOCUS</literal>, and queue a draw. So if your focus in/out
- handler just does that, you can delete it.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkText</structname> and <structname>GtkTree</structname> are
- buggy and broken. We don't recommend using them, and changing old code to
- avoid them is a good idea. The recommended alternatives are
- <structname>GtkTextView</structname> and <structname>GtkTreeView</structname>.
- The broken widgets are not declared in the headers by default; to use
- them, define the symbol <literal>GTK_ENABLE_BROKEN</literal> during
- compilation. In some future release, these widgets will be removed from GTK+.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GdkColorContext</structname> is gone; you probably weren't using
- it anyway. Use <structname>GdkColormap</structname> and the
- <function>gdk_rgb_*</function> functions instead.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkMenuBar</structname> now draws the <structfield>GtkContainer::border_width</structfield>
- space outside the frame, not inside the frame.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-In GTK+ 1.2, if an event handler returned <literal>TRUE</literal> it prevented
- propagation of that event to parent widgets. That is, the
- event signal would not be emitted on parent widgets. In
- GTK+ 2.0, if an event handler returns <literal>TRUE</literal>, the current
- signal emission on the current widget is immediately stopped. That is,
- other callbacks connected to the signal will not be invoked.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_toolbar_new()</function> no longer has arguments. This function
- was broken because the default <literal>GtkToolbarStyle</literal> (icons,
- text, both) is now a user preference, which is overridden when you call
- <function>gtk_toolbar_set_style()</function>. The constructor forced everyone
- to override the preference, which was undesirable. So to port
- your app, decide if you want to force the toolbar style
- or conform to the user's global defaults; if you want to force
- it, call <function>gtk_toolbar_set_style()</function>.
-</para>
-
-<para>
- The orientation arg was removed from <function>gtk_toolbar_new()</function>
- as well, just because it wasn't very useful and we were breaking the function
- anyway so had an opportunity to lose it. Call
- <function>gtk_toolbar_set_orientation()</function> to set toolbar orientation.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-<structname>GtkRange</structname>/<structname>GtkScrollbar</structname>/<structname>GtkScale</structname> were rewritten; this means that most
- theme engines won't draw them properly, and any custom subclasses of
- these widgets will need a rewrite (though if you could figure out
- how to subclass the old version of <structname>GtkRange</structname>, you
- have our respect). Also, <literal>GtkTroughType</literal> is gone.
-</para>
-<para>
- Here are some notable changes:
- <itemizedlist>
- <listitem>
- <para>
- <literal>stepper_size</literal> style property is the height for
- vertical ranges, width for horizontal; the other dimension matches
- the trough size.
- </para>
- </listitem>
- <listitem>
- <para>
- Added the ability to do NeXT-style steppers (and several other styles
- that don't make any sense).
- </para>
- </listitem>
- <listitem>
- <para>
- Added <literal>min_slider_length</literal>,
- <literal>fixed_slider_length</literal> properties to
- <structname>GtkScrollbar</structname>.
- </para>
- </listitem>
- <listitem>
- <para>
- Cleaned some private (or at least useless) functions out of
- <filename>gtkscale.h</filename>, e.g.
- <function>gtk_scale_value_width</function>.
- </para>
- </listitem>
- <listitem>
- <para>
- Moved bindings from subclasses to <structname>GtkScale</structname>,
- even arrow keys, since blind users don't know scale orientation.
- </para>
- </listitem>
- <listitem>
- <para>
- Changed <literal>move_slider</literal> action signal to use new
- <structname>GtkScrollType</structname>, remove
- <structname>GtkTroughType</structname> argument.
- </para>
- </listitem>
- <listitem>
- <para>
- Digits rounds the values a range will input to the given
- number of decimals, but will not try to force adjustment
- values set by other controllers. That is, we no longer
- modify <literal>adjustment->value</literal> inside a
- <literal>value_changed</literal> handler.
- </para>
- </listitem>
- <listitem>
- <para>
- Added getters for <structname>GtkScale</structname> setters.
- </para>
- </listitem>
- <listitem>
- <para>
- Middle-click begins a slider drag.
- </para>
- </listitem>
- </itemizedlist>
-</para>
-</listitem>
-
-<listitem>
-<para>
-The GtkContainer::focus signal/virtual function and
- <function>gtk_container_focus()</function> call were replaced by
- GtkWidget::focus and <function>gtk_widget_child_focus()</function>.
- The semantics are the same, so you should be able to just
- replace <literal>container_class->focus = mywidget_focus</literal> with
- <literal>widget_class->focus = mywidget_focus</literal> and replace
- <function>gtk_container_focus()</function> calls with
- <function>gtk_widget_child_focus()</function> calls.
-</para>
-<para>
- The purpose of this change was to allow non-containers to have
- focusable elements.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_rc_set_image_loader()</function> and
-<function>gtk_rc_load_image()</function> have been removed, now
- that GTK+ includes decent image loading capabilities itself.
-</para>
-</listitem>
-
-<listitem>
-<para>
-An extra <structname>GtkSettings</structname> argument has been added to
- <function>gtk_rc_find_pixmap_in_path()</function>. This function is only
- actually useful from a theme engine during parsing, at which point the
- <structname>GtkSettings</structname> is provided.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The child argument facility in <filename>gtkcontainer.c</filename> has been
- converted to a child property facility using
- <structname>GParamSpec</structname> and other facilities
- for <structname>GObject</structname>.
-</para>
-</listitem>
-
- <listitem>
-<para>
-The <function>set_child_arg()</function> and <function>get_child_arg()</function>
- virtual methods have been replaced with <function>set_child_property()</function>/<function>get_child_property()</function>, which
- work similar to GObject->set_property/get_property.
-</para>
-</listitem>
-
-
- <listitem>
-<para>
-Other removed <structname>GtkContainer</structname> functions with the replacements:
-
-<informaltable>
-<tgroup cols="2">
-<thead>
-<row><entry>Old function</entry><entry>Replacement</entry></row>
-</thead>
-<tbody>
-<row><entry><function>gtk_container_add_child_arg_type</function></entry><entry><function>gtk_container_class_install_child_property</function></entry></row>
-<row><entry><function>gtk_container_query_child_args</function></entry><entry><function>gtk_container_class_list_child_properties</function></entry></row>
-<row><entry><function>gtk_container_child_getv</function></entry><entry><function>gtk_container_child_set_property</function></entry></row>
-<row><entry><function>gtk_container_child_setv</function></entry><entry><function>gtk_container_child_get_property</function></entry></row>
-<row><entry><function>gtk_container_add_with_args</function></entry><entry><function>gtk_container_add_with_properties</function></entry></row>
-<row><entry><function>gtk_container_addv</function></entry><entry><function>gtk_container_add</function>/<function>gtk_container_child_set_property</function></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-<function>gdk_image_get()</function> (or rather its replacement,
- <function>gdk_drawable_get_image()</function>) now handles errors properly
- by returning <literal>NULL</literal>, previously it would crash. Also, a
- window being offscreen is no longer considered an error; instead, the area
- contains undefined contents for the offscreen areas. In most cases, code
- using <function>gdk_image_get()</function> should really be ported to
- <function>gdk_pixbuf_get_from_drawable()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_widget_set_usize()</function> has been renamed to
- <function>gtk_widget_set_size_request()</function>, however the old name
- still exists unless you define <literal>GTK_DISABLE_DEPRECATED</literal>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_widget_set_uposition()</function> is deprecated; use
- <function>gtk_window_move()</function>,
- <function>gtk_fixed_put()</function>, or <function>gtk_layout_put()</function>
- instead.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_window_set_policy()</function> is deprecated. To get the effect of
- "allow_shrink", call
- <literal>gtk_widget_set_size_request (window, 0, 0)</literal>. To get the
- effect of "allow_grow", call
- <literal>gtk_window_set_resizable (window, TRUE)</literal>. You didn't want
- the effect of "auto_shrink", it made no sense. But maybe if you were using
- it you want to use <literal>gtk_window_resize (window, 1, 1)</literal> to
- snap a window back to its minimum size (the 1, 1 will be rounded up to the
- minimum window size).
-</para>
-</listitem>
-
-<listitem>
-<para>
-The core GTK+ now takes care of handling mapping, unmapping and
- realizing the child widgets of containers in
- <function>gtk_widget_set_parent()</function>. In most cases, this allows
- container implementations to be simplified by removing the code in
- <function>add()</function> methods to map and realize children. However,
- there are a couple of things to watch out for here:
-</para>
-</listitem>
-
-
- <listitem>
-<para>
-If the parent is realized before the <function>add()</function> happens,
- <function>gtk_widget_set_parent_window()</function> must be called before
- <function>gtk_widget_set_parent()</function>, since
- <function>gtk_widget_set_parent()</function> will realize the child.
-</para>
-</listitem>
-
- <listitem>
-<para>
-If a container depended on its children not being mapped
- unless it did so itself (for example, <structname>GtkNotebook</structname>
- only mapped the current page), then the new function
- <function>gtk_widget_set_child_visible()</function> must be called to keep
- widgets that should not be mapped not mapped.
-</para>
-
-<para>
- As part of this change, most containers also will no longer need custom
- implementations of the <function>map()</function> and
- <function>unmap()</function> virtual functions. The only cases where this
- is necessary are:
-
-<itemizedlist>
- <listitem>
-<para>
-For <literal>!NO_WINDOW</literal> widgets, if you create children of
- <literal>widget->window</literal>
- and don't map them in <function>realize()</function> then you must map them
- in <function>map()</function>. [ In almost all cases, you can simply map the
- windows in <function>realize()</function>. ]
-</para>
-</listitem>
-
- <listitem>
-<para>
-For <literal>NO_WINDOW</literal> widgets, if you create windows in your
- <function>realize()</function> method, you must map then in
- <function>map()</function> and unmap them in <function>unmap()</function>.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_widget_set_default_style()</function>,
- <function>gtk_widget_push_style()</function>,
- and <function>gtk_widget_pop_style()</function> have been removed, since they
- did not work properly with themes and there were better
- alternatives for modifying the appearance of widgets.
-
- You should generally use <function>gtk_widget_modify_*()</function>
- instead.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-<function>gtk_image_new()</function> now takes no arguments and creates an
- empty <structname>GtkImage</structname> widget. To create a
- <structname>GtkImage</structname> widget from a
- <structname>GdkImage</structname> (the least
- common usage of <structname>GdkImage</structname>), use
- <function>gtk_image_new_from_image()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<literal>GTK_SELECTION_EXTENDED</literal> is now deprecated, and neither the
- <structname>GtkList</structname>/<structname>GtkTree</structname> nor the
- <structname>GtkCList</structname>/<structname>GtkCTree</structname> support
- <literal>GTK_SELECTION_EXTENDED</literal> anymore. However, the old extended
- behavior replaces <literal>MULTIPLE</literal> behavior.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The following variables are no longer exported from GDK. (Other variables
- are also no longer exported; the following are the ones found used
- externally in a large sample of GTK+ code.)
-
-<informaltable>
-<tgroup cols="2">
-<thead>
-<row><entry>Variable</entry><entry>Replacement</entry></row>
-</thead>
-<tbody>
-<row><entry><literal>gdk_null_window_warnings</literal></entry><entry>None - did nothing in GTK+ 1.2</entry></row>
-<row><entry><literal>gdk_leader_window</literal></entry><entry>None - private variable</entry></row>
-<row><entry><literal>gdk_screen</literal></entry><entry><function>gdk_x11_get_default_screen ()</function></entry></row>
-<row><entry><literal>gdk_root_window</literal></entry><entry><function>gdk_x11_get_default_root_xwindow ()</function></entry></row>
-<row><entry><literal>gdk_root_parent</literal></entry><entry><function>gdk_get_default_root_window ()</function></entry></row>
-<row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
-<row><entry><literal>gdk_error_warnings</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
-<row><entry><literal>gdk_display_name</literal></entry><entry><function>gdk_get_display ()</function></entry></row>
-<row><entry><literal>gdk_wm_delete_window</literal></entry><entry><literal>gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)</literal></entry></row>
-<row><entry><literal>gdk_wm_take_focus</literal></entry><entry><literal>gdk_atom_intern ("WM_TAKE_FOCUS", FALSE)</literal></entry></row>
-<row><entry><literal>gdk_wm_protocols</literal></entry><entry><literal>gdk_atom_intern ("WM_PROTOCOLS", FALSE)</literal></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-The handling of colormaps and widgets has been changed:
-
-<itemizedlist>
- <listitem>
-<para>
-The default colormap for widgets is now the <structname>GdkRGB</structname>
- colormap, not the system default colormap. If you try to use resources
- created for a widget (e.g., <literal>widget->style</literal>) with
- a window using the system colormap, errors will result on some machines.
-</para>
-</listitem>
-
-
- <listitem>
-<para>
-<function>gtk_widget_push()</function>/<function>gtk_widget_pop_colormap()</function>
- only cause the colormap to be explicitly set on toplevel widgets, not on
- all widgets. The colormap for other widgets (when not set using
- <function>gtk_widget_set_colormap()</function>), is determined by finding
- the nearest ancestor with a colormap set on it explicitly, or if that
- fails, the default colormap.
-</para>
-</listitem>
-
-</itemizedlist>
-
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-The default selected day for <structname>GtkCalendar</structname> is now the
- current day in the month, not the first day in the month. The current month
- and year were already used.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-GDK is no longer put into threaded mode automatically when
- <function>g_thread_init()</function> has been called. In order to use the
- global GDK thread mutex with <function>gdk_threads_enter()</function> and
- <function>gdk_threads_leave()</function>, you must call
- <function>gdk_threads_init()</function> explicitly.
-
- If you aren't using GDK and GTK+ functions from multiple threads,
- there is no reason to call <function>gdk_threads_init()</function>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The <structname>GtkPreviewInfo</structname> struct has had its visual and
- colormap fields removed. Also, <function>gtk_preview_get_cmap()</function>
- and <function>gtk_preview_get_visual()</function> are deprecated, as
- <structname>GdkRGB</structname> works on any colormap and visual. You no
- longer need to
- <literal>gtk_widget_push_cmap (gtk_preview_get_cmap ())</literal> in
- your code.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-The <structname>GtkBox</structname>, <structname>GtkTable</structname>, and
- <structname>GtkAlignment</structname> widgets now call
- <literal>gtk_widget_set_redraw_on_allocate (widget, FALSE);</literal> on
- themselves. If you want to actually draw contents in a widget derived from
- one of these widgets, you'll probably want to change this
- in your <function>init()</function> function.
-</para>
-</listitem>
-
-
-<listitem>
-<para>
-A number of widgets are now <literal>NO_WINDOW</literal> widgets (most
- importantly <structname>GtkButton</structname>, but also
- <structname>GtkRange</structname> and <structname>GtkNotebook</structname>)
-
- This has a couple of effects:
-
-<itemizedlist>
- <listitem>
-<para>
-If you are deriving from one of these widgets, you need to
- adapt your code appropriately -- for instance, drawing coordinates
- start from <literal>widget->allocation.x, widget->allocation.y</literal>.
-</para>
-</listitem>
-
-
- <listitem>
-<para>
-If you are embedding one of these widgets in a custom widget,
- you must make sure you call <function>gtk_container_propagate_expose()</function>
- correctly, as you must for any <literal>NO_WINDOW</literal> widgets.
-</para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
- <structname>GtkFixed</structname> is a little special; it is now created by
- default as a <literal>NO_WINDOW</literal> widget, but if you do
-
-<programlisting>
- gtk_fixed_set_has_window (fixed, TRUE);
-</programlisting>
-
- after creating a fixed widget, it will create a window and
- handle it properly.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<structname>GtkLayout</structname> no longer has the <structfield>xoffset</structfield>,
- <structfield>yoffset</structfield> fields, which used to store the difference between
- world and window coordinates for <literal>layout->bin_window</literal>.
- These coordinate systems are now always the same.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>gtk_paint_focus()</function>, <function>gtk_draw_focus()</function>
- and <function>GtkStyle::draw_focus()</function>
- have been changed a bit:
-
-<itemizedlist>
- <listitem>
-<para>
-A <literal>GtkStateType</literal> argument has been added to <function>gtk_paint_focus()</function>.
-</para>
-</listitem>
-
- <listitem>
-<para>
-The default implementation of the <function>GtkStyle::draw_focus()</function>
- virtual function now draws a focus rectangle whose width is
- determined by the GtkWidget::focus-width style property.
-</para>
-</listitem>
-
- <listitem>
-<para>
-The rectangle passed in is the bounding box, instead of
- the rectangle used in the <function>gdk_draw_rectangle()</function> call,
- so it is no longer necessary to subtract 1 from the width and height.
-</para>
-</listitem>
-
-</itemizedlist>
-
-</para>
-</listitem>
-
-
-</itemizedlist>
-
-</refsect1>
-
-</refentry>
<title>Compiling GTK+ Applications on UNIX</title>
<para>
-To compile a GTK+ application, you need to tell the compiler where to
+To compile a GTK+ application, you need to tell the compiler where to
find the GTK+ header files and libraries. This is done with the
<literal>pkg-config</literal> utility.
</para>
<para>
The following interactive shell session demonstrates how
-<literal>pkg-config</literal> is used (the actual output on
+<literal>pkg-config</literal> is used (the actual output on
your system may be different):
<programlisting>
-$ pkg-config --cflags gtk+-2.0
- -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/pango-1.0 -I/usr/X11R6/include -I/usr/include/freetype2 -I/usr/include/atk-1.0
-$ pkg-config --libs gtk+-2.0
- -L/usr/lib -L/usr/X11R6/lib -lgtk-x11-2.0 -lgdk-x11-2.0 -lXi -lgdk_pixbuf-2.0 -lm -lpangox -lpangoxft -lXft -lXrender -lXext -lX11 -lfreetype -lpango -latk -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0
+$ pkg-config --cflags gtk+-3.0
+ -pthread -I/usr/include/gtk-3.0 -I/usr/lib64/gtk-3.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12
+$ pkg-config --libs gtk+-3.0
+ -pthread -lgtk-x11-3.0 -lgdk-x11-3.0 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-3.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
</programlisting>
</para>
<para>
The simplest way to compile a program is to use the "backticks"
feature of the shell. If you enclose a command in backticks
(<emphasis>not single quotes</emphasis>), then its output will be
-substituted into the command line before execution. So to compile
+substituted into the command line before execution. So to compile
a GTK+ Hello, World, you would type the following:
<programlisting>
-$ cc `pkg-config --cflags --libs gtk+-2.0` hello.c -o hello
+$ cc `pkg-config --cflags --libs gtk+-3.0` hello.c -o hello
</programlisting>
</para>
<para>
-If you want to make sure that your program doesn't use any deprecated
+If you want to make sure that your program doesn't use any deprecated
functions, you can define the preprocessor symbol GTK_DISABLE_DEPRECATED
by using the command line option <literal>-DGTK_DISABLE_DEPRECATED=1</literal>.
-There are similar symbols GDK_DISABLE_DEPRECATED,
+There are similar symbols GDK_DISABLE_DEPRECATED,
GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and
-GLib.
+GLib.
</para>
<para>
-If you want to make sure that your program doesn't use any functions which
+If you want to make sure that your program doesn't use any functions which
may be problematic in a multihead setting, you can define the preprocessor
-symbol GDK_MULTIHEAD_SAFE by using the command line option
+symbol GDK_MULTIHEAD_SAFE by using the command line option
<literal>-DGTK_MULTIHEAD_SAFE=1</literal>.
</para>
<para>
The recommended way of using GTK+ has always been to only include the
-toplevel headers <filename>gtk.h</filename>, <filename>gdk.h</filename>,
+toplevel headers <filename>gtk.h</filename>, <filename>gdk.h</filename>,
<filename>gdk-pixbuf.h</filename>.
If you want to make sure that your program follows this recommended
practise, you can define the preprocessor symbols GTK_DISABLE_SINGLE_INCLUDES
<link linkend="GtkPrintUnixDialog">GtkPrintUnixDialog</link> API.
</para>
-<para>
-The next major version, GTK+ 3, will remove many implementation details and
-struct members from its public headers. To ensure that your application will
-not have problems with this, you can define the preprocessor symbol
-GSEAL_ENABLE. This will make the compiler catch all uses of direct access to
-struct fields so that you can go through them one by one and replace them with
-a call to an accessor function instead.
-</para>
-
</refsect1>
</refentry>
</para></listitem>
</varlistentry>
+<varlistentry>
+<term>GObject</term>
+<listitem><para>A library that provides a type system, a collection of
+fundamental types including an object type, a signal system.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>GIO</term>
+<listitem><para>A modern, easy-to-use VFS API including abstractions for
+files, drives, volumes, stream IO, as well as network programming and
+DBus communication.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>cairo</term>
+<listitem><para>Cairo is a 2D graphics library with support for multiple
+output devices.
+</para></listitem>
+</varlistentry>
+
<varlistentry>
<term>Pango</term>
<listitem><para>
Pango is a library for internationalized text handling. It centers
-around the #PangoLayout object, representing a paragraph of text.
+around the #PangoLayout object, representing a paragraph of text.
Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
other widgets that display text.
</para></listitem>
<term>GdkPixbuf</term>
<listitem><para>
This is a small library which allows you to create #GdkPixbuf
-("pixel buffer") objects from image data or image files.
+("pixel buffer") objects from image data or image files.
Use a #GdkPixbuf in combination with #GtkImage to display images.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK+</term>
<listitem><para>
-The GTK+ library itself contains <firstterm>widgets</firstterm>,
+The GTK+ library itself contains <firstterm>widgets</firstterm>,
that is, GUI components such as #GtkButton or #GtkTextView.
</para></listitem>
</varlistentry>
</para>
</partintro>
- <xi:include href="migrating-2to3.xml" />
<xi:include href="xml/migrating-checklist.sgml" />
- <xi:include href="changes-1.2.sgml" />
- <xi:include href="changes-2.0.sgml" />
- <xi:include href="xml/migrating-GtkFileChooser.sgml" />
- <xi:include href="xml/migrating-GtkAction.sgml" />
- <xi:include href="xml/migrating-GtkComboBox.sgml" />
- <xi:include href="xml/migrating-GtkIconView.sgml" />
- <xi:include href="xml/migrating-GtkAboutDialog.sgml" />
- <xi:include href="xml/migrating-GtkColorButton.sgml" />
- <xi:include href="xml/migrating-GtkAssistant.sgml" />
- <xi:include href="xml/migrating-GtkRecentChooser.sgml" />
- <xi:include href="xml/migrating-GtkLinkButton.sgml" />
- <xi:include href="xml/migrating-GtkBuilder.sgml" />
- <xi:include href="xml/migrating-GtkTooltip.sgml" />
- <xi:include href="xml/migrating-GtkEntry-icons.sgml" />
- <xi:include href="xml/migrating-GtkLabel-links.sgml" />
- <xi:include href="xml/migrating-ClientSideWindows.sgml" />
+ <xi:include href="migrating-2to3.xml" />
</part>
<part>
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
- <index id="api-index-2-2" role="2.2">
- <title>Index of new symbols in 2.2</title>
- <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-4" role="2.4">
- <title>Index of new symbols in 2.4</title>
- <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-6" role="2.6">
- <title>Index of new symbols in 2.6</title>
- <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-8" role="2.8">
- <title>Index of new symbols in 2.8</title>
- <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-10" role="2.10">
- <title>Index of new symbols in 2.10</title>
- <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-12" role="2.12">
- <title>Index of new symbols in 2.12</title>
- <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-14" role="2.14">
- <title>Index of new symbols in 2.14</title>
- <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-16" role="2.16">
- <title>Index of new symbols in 2.16</title>
- <xi:include href="xml/api-index-2.16.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-18" role="2.18">
- <title>Index of new symbols in 2.18</title>
- <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-20" role="2.20">
- <title>Index of new symbols in 2.20</title>
- <xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
- </index>
- <index id="api-index-2-22" role="2.22">
- <title>Index of new symbols in 2.22</title>
- <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
- </index>
<index id="api-index-3-0" role="3.0">
<title>Index of new symbols in 3.0</title>
<xi:include href="xml/api-index-3.0.xml"><xi:fallback /></xi:include>
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="gtk-migrating-2-to-3">
- <title>Migrating from 2.x to 3.x</title>
+ <title>Migrating from GTK+ 2.x to GTK+ 3</title>
- <refsect1>
+ <para>
+ There are a number of steps that you can take to prepare your GTK+ 2.x
+ application for the switch to GTK+ 3.
+ </para>
+
+ <section>
<title>Only single includes</title>
<para>
Make sure your program only include the toplevel headers:
make CFLAGS+="-DG_DISABLE_SINGLE_INCLUDES -DGDK_PIXBUF_DISABLE_SINGLE_INCLUDES -DGTK_DISABLE_SINGLE_INCLUDES"
</programlisting>
</para>
- </refsect1>
+ </section>
- <refsect1>
+ <section>
<title>Do not use deprecated symbols</title>
<para>
- Make sure your program doesn't use any deprecated functions:
+ Make sure your program doesn't use any functions that have been
+ deprecated in GTK+ 2.x:
<programlisting>
make CFLAGS+="-DG_DISABLE_DEPRECATED -DGDK_PIXBUF_DISABLE_DEPRECATED -DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
</programlisting>
</para>
- </refsect1>
+ </section>
- <refsect1>
- <title>Use accessor funcions instead direc access</title>
+ <section>
+ <title>Use accessor functions instead direct access</title>
<para>
- GTK+ 3 removed many implementation details and struct members from
- its public headers. To ensure that your application will not have problems
- with this, you can define the preprocessor symbol GSEAL_ENABLE. This will
+ GTK+ 3 removes many implementation details and struct members from
+ its public headers. To ensure that your application does not have problems
+ with this, you define the preprocessor symbol GSEAL_ENABLE. This will
make the compiler catch all uses of direct access to struct fields so that
you can go through them one by one and replace them with a call to an
accessor function instead.
make CFLAGS+="-DGSEAL_ENABLE"
</programlisting>
</para>
- </refsect1>
+ </section>
- <refsect1>
+ <section>
<title>GTK+ Modules</title>
<para>
- Some GNOME modules install GTK+ modules. Since GTK+ 3 will be
- parallel-installable with GTK+ 2.x, the two have separate locations for
- their loadable modules. The location for GTK+ 2.x is $libdir/gtk-2.0
- (and its subdirectories), for GTK+ 3, the location is $libdir/gtk-3.0
+ Some software packages install loadable GTK+ modules such as theme engines,
+ gdk-pixbuf loaders or input methods. Since GTK+ 3 is parallel-installable
+ with GTK+ 2.x, the two GTK+ versions have separate locations for their
+ loadable modules. The location for GTK+ 2.x is
+ <filename><replaceable>libdir</replaceable>/gtk-2.0</filename>
+ (and its subdirectories), for GTK+ 3 the location is
+ <filename><replaceable>libdir</replaceable>/gtk-3.0</filename>
(and its subdirectories).
</para>
<para>
- For some kinds of modules, namely im modules and pixbuf loaders,
+ For some kinds of modules, namely input methods and pixbuf loaders,
GTK+ keeps a cache file with extra information about the modules.
- These cache files are located in $sysconfdir/gtk-2.0 for GTK+ 2.x.
- For GTK+ 3, they have been moved to $libdir/gtk-3.0/3.0.0/.
+ For GTK+ 2.x, these cache files are located in
+ <filename><replaceable>sysconfdir</replaceable>/gtk-2.0</filename>.
+ For GTK+ 3, they have been moved to
+ <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/</filename>.
The commands that create these cache files have been renamed with a -3
suffix to make them parallel-installable.
</para>
against libgtk 2.x into an application using GTK+ 3 will lead to
unhappiness and must be avoided.
</para>
- </refsect1>
+ </section>
</chapter>
<formalpara>
<title>Why</title>
<para>
- By handling this signal, you let widgets have
- context-sensitive menus that can be invoked with the standard
- key bindings.
+ By handling this signal, you let widgets have
+ context-sensitive menus that can be invoked with the standard
+ key bindings.
</para>
</formalpara>
<para>
- The #GtkWidget::popup-menu signal instructs the widget for which
- it is emitted to create a context-sensitive popup menu. By default,
+ The #GtkWidget::popup-menu signal instructs the widget for which
+ it is emitted to create a context-sensitive popup menu. By default,
the <link linkend="gtk-bindings">key binding mechanism</link> is set to
emit this signal when the
<keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
<orderedlist>
<listitem>
- <para>
- Write a function to create and show a popup menu. This
- function needs to know the button number and the event's
- time to pass them to gtk_menu_popup(). You can implement
- such a function like this:
- </para>
-
- <programlisting id="do_popup_menu">
+ Write a function to create and show a popup menu. This
+ function needs to know the button number and the event's
+ time to pass them to gtk_menu_popup(). You can implement
+ such a function like this:
+ </para>
+
+
<programlisting id="do_popup_menu">
static void
do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
{
int button, event_time;
menu = gtk_menu_new (<!-- -->);
- g_signal_connect (menu, "deactivate",
+ g_signal_connect (menu, "deactivate",
G_CALLBACK (gtk_widget_destroy), NULL);
/* ... add menu items ... */
}
gtk_menu_attach_to_widget (GTK_MENU (menu), my_widget, NULL);
- gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
+ gtk_menu_popup (GTK_MENU (menu), NULL, NULL, NULL, NULL,
button, event_time);
}
- </programlisting>
+ </programlisting>
</listitem>
<listitem>
- <para>
- In your #GtkWidget::button-press-event handler, call this function
+ In your #GtkWidget::button-press-event handler, call this function
when you need to pop up a menu:
- </para>
+ </para>
- <programlisting>
static gboolean
my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event)
{
return FALSE;
}
- </programlisting>
+ </programlisting>
</listitem>
<listitem>
- <para>
- Implement a handler for the #GtkWidget::popup-menu signal:
- </para>
+ Implement a handler for the #GtkWidget::popup-menu signal:
+ </para>
- <programlisting>
static gboolean
my_widget_popup_menu_handler (GtkWidget *widget)
{
do_popup_menu (widget, NULL);
return TRUE;
}
- </programlisting>
+ </programlisting>
</listitem>
</orderedlist>
<note>
<para>
- If you do not pass a positioning function to gtk_menu_popup(),
- it will show the menu at the mouse position by default. This
- is what you usually want when the menu is shown as a result of
- pressing a mouse button. However, if you press the
- <keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
- or <keycap>Menu</keycap> keys while the widget is focused, the
- mouse cursor may not be near the widget at all. In the <link
- linkend="do_popup_menu">example above</link>, you may want to
- provide your own <link
- linkend="GtkMenuPositionFunc">menu-positioning function</link>
- in the case where the <parameter>event</parameter> is
- %NULL. This function should compute the desired position for
- a menu when it is invoked through the keyboard. For example,
- #GtkEntry aligns the top edge of its popup menu with the bottom
+ If you do not pass a positioning function to gtk_menu_popup(),
+ it will show the menu at the mouse position by default. This
+ is what you usually want when the menu is shown as a result of
+ pressing a mouse button. However, if you press the
+ <keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
+ or <keycap>Menu</keycap> keys while the widget is focused, the
+ mouse cursor may not be near the widget at all. In the <link
+ linkend="do_popup_menu">example above</link>, you may want to
+ provide your own <link
+ linkend="GtkMenuPositionFunc">menu-positioning function</link>
+
in the case where the <parameter>event</parameter> is
+ %NULL. This function should compute the desired position for
+ a menu when it is invoked through the keyboard. For example,
+ #GtkEntry aligns the top edge of its popup menu with the bottom
edge of the entry.
</para>
</note>
<note>
<para>
- For the standard key bindings to work, your widget must be
- able to take the keyboard focus. In general, widgets should
- be fully usable through the keyboard and not just the mouse.
- The very first step of this is to ensure that your widget
- turns on the %GTK_CAN_FOCUS <link linkend="gtkwidgetflags">flag</link>.
+ For the standard key bindings to work, your widget must be
+ able to take the keyboard focus. In general, widgets should
+ be fully usable through the keyboard and not just the mouse.
+ The very first step of this is to ensure that your widget
+ turns on the %GTK_CAN_FOCUS <link linkend="gtkwidgetflags">flag</link>.
</para>
</note>
</section>
<formalpara>
<title>Why</title>
<para>
- The <structfield>region</structfield> field of
- <structname>GdkEventExpose</structname> allows you to redraw
- less than the traditional
- <structfield>GdkEventRegion.area</structfield>.
+ The <structfield>region</structfield> field of
+ <structname>GdkEventExpose</structname> allows you to redraw
+ less than the traditional <structfield>GdkEventRegion.area</structfield>.
</para>
</formalpara>
<para>
- In GTK+ 1.x, the <structname>GdkEventExpose</structname>
+ In early GTK+ versions, the <structname>GdkEventExpose</structname>
structure only had an <structfield>area</structfield> field to
- let you determine the region that you needed to redraw. In GTK+
- 2.x, this field exists for compatibility and as a simple
- interface. However, there is also a
- <structfield>region</structfield> field which contains a
- fine-grained region. The <structfield>area</structfield> field
- is simply the bounding rectangle of the
- <structfield>region</structfield>.
+ let you determine the region that you needed to redraw. In current
+ GTK+, this field still exists for compatibility and as a simple
+ interface. However, there is also a <structfield>region</structfield>
+ field which contains a fine-grained region. The
+ <structfield>area</structfield> field is simply the bounding rectangle
+ of the <structfield>region</structfield>.
</para>
<para>
<para>
Regions have an internal representation that is accessible as a
- list of rectangles. To turn the
+ list of rectangles. To turn the
<structfield>GdkEventExpose.region</structfield> field into such
a list, use gdk_region_get_rectangles():
</para>
for (i = 0; i < n_rects; i++)
{
- /* Repaint rectangle: (rects[i].x, rects[i].y),
+ /* Repaint rectangle: (rects[i].x, rects[i].y),
* (rects[i].width, rects[i].height)
*/
}
<formalpara>
<title>Why</title>
<para>
- With gtk_accelerator_get_default_mod_mask() you can test for
- modifier keys reliably; this way your key event handlers will
- work correctly even if <keycap>NumLock</keycap> or
+ With gtk_accelerator_get_default_mod_mask() you can test for
+ modifier keys reliably; this way your key event handlers will
+ work correctly even if <keycap>NumLock</keycap> or
<keycap>CapsLock</keycap> are activated.
</para>
</formalpara>
<structfield>state</structfield> field is a bit mask which
indicates the modifier state at the time the key was pressed.
Modifiers are keys like <keycap>Control</keycap> and
- <keycap>NumLock</keycap>. When implementing a
- #GtkWidget::key-press-event handler, you should use
+ <keycap>NumLock</keycap>. When implementing a
+ #GtkWidget::key-press-event handler, you should use
gtk_accelerator_get_default_mod_mask() to
test against modifier keys. This function returns a bit mask
which encompasses all the modifiers which the user may be
<formalpara>
<title>Why</title>
<para>
- Named icons automatically adapt to theme changes, giving your
+ Named icons automatically adapt to theme changes, giving your
application a much more integrated appearance.
</para>
</formalpara>
<para>
- Since GTK+ 2.6, named icons can be used for window icons (see
- gtk_window_set_icon_name()) and images (see gtk_image_set_icon_name()).
- In GTK+ 2.8, you can also use named icons for drag-and-drop (see
- gtk_drag_source_set_icon_name()) and in treeview cells (see the
- #GtkCellRendererPixbuf:icon-name property).
+ Named icons can be used for window icons (see gtk_window_set_icon_name())
+ and images (see gtk_image_set_icon_name()). You can also use named icons
+ for drag-and-drop (see gtk_drag_source_set_icon_name()) and in treeview
+ cells (see the #GtkCellRendererPixbuf:icon-name property).
</para>
</section>
</chapter>
<qandaentry>
-<question><para>How do I port from one GTK+
+<question><para>How do I port from one GTK+
version to another?</para></question>
<answer>
<para>
-See the <link linkend="gtk-changes-2-0">list of incompatible changes
-from 1.2 to 2.0</link>. Also, the <ulink
-url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0 porting
-guide</ulink> on <ulink
-url="http://developer.gnome.org">http://developer.gnome.org</ulink>
-has some more detailed discussion of porting from 1.2 to 2.0.
-You may also find useful information in the documentation for
+See <xref linkend="gtk-migrating-2-to-3"/>.
+You may also find useful information in the documentation for
specific widgets and functions.
</para>
projects / ~andy / gtk / commitdiff