AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Remove old migration docs

Browse Source 
This information will still be available in the 2.22 docs.
For 3.0, we'll do sortof a clean start.
This commit is contained in:
Matthias Clasen 2010-06-03 01:09:53 -04:00
parent 6a8a2f7ef3
commit d93b99a273
9 changed files with 397 additions and 2091 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/reference/gtk/Makefile.am
View File

@ -120,28 +120,12 @@ content_files = \
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 \

502
docs/reference/gtk/building.sgml
View File

@ -49,12 +49,12 @@ How to compile GTK+ itself
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
@ -103,7 +103,7 @@ How to compile GTK+ itself
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>
@ -137,30 +137,26 @@ How to compile GTK+ itself
</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>
<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>
@ -170,106 +166,105 @@ How to compile GTK+ itself
</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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<para>
<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>
<para>
<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>
@ -281,7 +276,7 @@ How to compile GTK+ itself
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
@ -294,7 +289,7 @@ How to compile GTK+ itself
<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>
@ -315,123 +310,127 @@ How to compile GTK+ itself
<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.)
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>
<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>
<group>
<arg>--disable-visibility</arg>
<arg>--enable-visibility</arg>
</group>
<arg>--disable-modules</arg>
<arg>--enable-modules</arg>
</group>
<group>
<arg>--disable-shm</arg>
<arg>--enable-shm</arg>
</group>
<arg>--with-included-loaders==LOADER1,LOADER2,...</arg>
</group>
<group>
<arg>--disable-xim</arg>
<arg>--enable-xim</arg>
</group>
<arg>--with-included-immodules=MODULE1,MODULE2,...</arg>
</group>
<group>
<arg>--disable-xim-inst</arg>
<arg>--enable-xim-inst</arg>
</group>
<arg>--enable-debug=[no|minimum|yes]</arg>
</group>
<group>
<arg>--disable-xkb</arg>
<arg>--enable-xkb</arg>
</group>
<arg>--disable-visibility</arg>
<arg>--enable-visibility</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-shm</arg>
<arg>--enable-shm</arg>
</group>
<group>
<arg>--disable-xim</arg>
<arg>--enable-xim</arg>
</group>
<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>
</cmdsynopsis>
<group>
<arg>--disable-introspection</arg>
</group>
</cmdsynopsis>
</para>
<formalpara>
<title><systemitem>--disable-modules</systemitem> and
<systemitem>--enable-modules</systemitem></title>
<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>
<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>
</formalpara>
<formalpara>
<title><systemitem>--with-included-loaders</systemitem></title>
<title><systemitem>--with-included-loaders</systemitem></title>
<para>
<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>
<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>
@ -443,7 +442,7 @@ How to compile GTK+ itself
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>
@ -453,33 +452,33 @@ How to compile GTK+ itself
<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>
@ -488,44 +487,44 @@ How to compile GTK+ itself
<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.
@ -535,29 +534,29 @@ How to compile GTK+ itself
</formalpara>
<formalpara>
<title><systemitem>--disable-gtk-doc</systemitem> and
<systemitem>--enable-gtk-doc</systemitem></title>
<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>
<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>
</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>
<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
@ -565,30 +564,41 @@ How to compile GTK+ itself
</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.
<para>
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>

464
docs/reference/gtk/changes-1.2.sgml
View File

@ -1,464 +0,0 @@
<?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)-&gt;child</literal>,
instead of the old <literal>GTK_BUTTON (button)-&gt;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, &amp;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>

1180
docs/reference/gtk/changes-2.0.sgml
View File

File diff suppressed because it is too large Load Diff

37
docs/reference/gtk/compiling.sgml
View File

@ -20,45 +20,45 @@ How to compile your GTK+ application
<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>
@ -71,7 +71,7 @@ line option <literal>-DGTK_MULTIDEVICE_SAFE=1</literal>.
<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
@ -88,14 +88,5 @@ The same for <filename>gtkunixprint.h</filename> if you use the non-portable
<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>

90
docs/reference/gtk/gtk-docs.sgml
View File

@ -41,11 +41,33 @@ string utilities, file utilities, a main loop abstraction, and so on.
</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>
@ -67,7 +89,7 @@ framework.
<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>
@ -84,7 +106,7 @@ on X11, Windows, and the Linux framebuffer device.
<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>
@ -400,24 +422,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
</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>
@ -437,50 +443,6 @@ that is, GUI components such as #GtkButton or #GtkTextView.
<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>

53
docs/reference/gtk/migrating-2to3.xml
View File

@ -3,9 +3,14 @@
"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:
@ -13,24 +18,25 @@
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.
@ -38,22 +44,27 @@
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>
@ -65,5 +76,5 @@
against libgtk 2.x into an application using GTK+ 3 will lead to
unhappiness and must be avoided.
</para>
</refsect1>
</section>
</chapter>

135
docs/reference/gtk/migrating-checklist.sgml
View File

@ -19,15 +19,15 @@
<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>
@ -39,14 +39,14 @@
<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>
<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">
<programlisting id="do_popup_menu">
static void
do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
{
@ -54,7 +54,7 @@ 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 ... */
@ -71,19 +71,19 @@ do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
}
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
<para>
In your #GtkWidget::button-press-event handler, call this function
when you need to pop up a menu:
</para>
</para>
<programlisting>
<programlisting>
static gboolean
my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event)
{
@ -96,52 +96,52 @@ 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>
<para>
Implement a handler for the #GtkWidget::popup-menu signal:
</para>
<programlisting>
<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>
@ -152,23 +152,21 @@ my_widget_popup_menu_handler (GtkWidget *widget)
<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>
@ -183,7 +181,7 @@ my_widget_popup_menu_handler (GtkWidget *widget)
<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>
@ -200,7 +198,7 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
for (i = 0; i &lt; 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)
*/
}
@ -218,9 +216,9 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
<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>
@ -230,8 +228,8 @@ my_widget_expose_event_handler (GtkWidget *widget, GdkEventExpose *event)
<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
@ -289,17 +287,16 @@ my_widget_key_press_event_handler (GtkWidget *widget, GdkEventKey *event)
<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>

11
docs/reference/gtk/question_index.sgml
View File

@ -63,19 +63,14 @@ See the <link linkend="gtk-resources">documentation on this topic</link>.
<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>