[gtkmm-documentation] Upgrade from DocBook 4.5 to DocBook 5.0
- From: Kjell Ahlstedt <kjellahl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtkmm-documentation] Upgrade from DocBook 4.5 to DocBook 5.0
- Date: Thu, 23 Sep 2021 08:22:58 +0000 (UTC)
commit 86c5f3be36c19a9b33fc864cf1da2069c0ed327a
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date: Thu Sep 23 10:16:34 2021 +0200
Upgrade from DocBook 4.5 to DocBook 5.0
docs/tutorial/C/figures/checkbutton.png | Bin 2888 -> 7846 bytes
docs/tutorial/C/index-in.docbook | 3042 ++++++++++++++++---------------
docs/tutorial/insert_example_code.pl | 6 +-
docs/tutorial/insert_example_code.py | 6 +-
docs/tutorial/meson.build | 8 +-
meson.build | 2 +-
tools/meson_aux/tutorial-custom-cmd.py | 79 +-
7 files changed, 1661 insertions(+), 1482 deletions(-)
---
diff --git a/docs/tutorial/C/figures/checkbutton.png b/docs/tutorial/C/figures/checkbutton.png
index 06645b7..7e62165 100644
Binary files a/docs/tutorial/C/figures/checkbutton.png and b/docs/tutorial/C/figures/checkbutton.png differ
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 9192176..e25a007 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -1,6 +1,5 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book [
<!ENTITY url_refdocs_base_glib_html "http://developer.gnome.org/glibmm/unstable/";>
<!ENTITY url_refdocs_base_glib "&url_refdocs_base_glib_html;classGlib_1_1">
<!ENTITY url_refdocs_base_gio "&url_refdocs_base_glib_html;classGio_1_1">
@@ -11,7 +10,7 @@
<!ENTITY url_examples_branch "master">
<!ENTITY url_examples_base
"https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/&url_examples_branch;/examples/book/";>
<!ENTITY url_gtkmm_base "https://gitlab.gnome.org/GNOME/gtkmm/tree/&url_examples_branch;/";>
- <!ENTITY gtkmm "<application>gtkmm</application>">
+ <!ENTITY gtkmm "<application xmlns='http://docbook.org/ns/docbook'>gtkmm</application>">
<!ENTITY uuml "ü" >
<!ENTITY szlig "ß" >
<!ENTITY verbar "|" >
@@ -34,82 +33,67 @@ In some situations (not quite clear exactly which situations) the translation
tools (itstool and friends) can't create translated index.docbook files if
a <programlisting> element occurs in a <para> element.
<programlisting> can be a direct child of e.g. <chapter>, <sect1>, <sect2>,
-<sect3>, <sect4>, <sect5>.
+<sect3>, <sect4>, <sect5>, <section>.
See https://gitlab.gnome.org/GNOME/gtkmm-documentation/-/merge_requests/11
-->
-<!-- The XSL for developer.gnome.org requires this id. -->
-<book id="index" lang="en">
-
- <bookinfo>
+<book xmlns="http://docbook.org/ns/docbook";
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ version="5.0" xml:id="index" xml:lang="en">
+ <info>
<title>Programming with >kmm; 4</title>
-
<authorgroup>
<author>
- <firstname>Murray</firstname>
- <surname>Cumming</surname>
+ <personname><firstname>Murray</firstname><surname>Cumming</surname></personname>
</author>
<author>
- <firstname>Bernhard</firstname>
- <surname>Rieder</surname>
- <contrib>Chapter on "Timeouts".</contrib>
+ <personname><firstname>Bernhard</firstname><surname>Rieder</surname></personname>
+ <contrib>Chapter on "Timeouts".</contrib>
</author>
<author>
- <firstname>Jonathon</firstname>
- <surname>Jongsma</surname>
- <contrib>Chapter on "Drawing with Cairo".</contrib>
- <contrib>Chapter on "Working with gtkmm's Source Code".</contrib>
- <contrib>Chapter on "Recent Files".</contrib>
+ <personname><firstname>Jonathon</firstname><surname>Jongsma</surname></personname>
+ <contrib>Chapter on "Drawing with Cairo".</contrib>
+ <contrib>Chapter on "Working with gtkmm's Source Code".</contrib>
+ <contrib>Chapter on "Recent Files".</contrib>
</author>
<author>
- <firstname>Ole</firstname>
- <surname>Laursen</surname>
- <contrib>Parts of chapter on "Internationalization".</contrib>
+ <personname><firstname>Ole</firstname><surname>Laursen</surname></personname>
+ <contrib>Parts of chapter on "Internationalization".</contrib>
</author>
<author>
- <firstname>Marko</firstname>
- <surname>Anastasov</surname>
- <contrib>Chapter on "Printing".</contrib>
- <contrib>Parts of chapter on "Internationalization".</contrib>
+ <personname><firstname>Marko</firstname><surname>Anastasov</surname></personname>
+ <contrib>Chapter on "Printing".</contrib>
+ <contrib>Parts of chapter on "Internationalization".</contrib>
</author>
<author>
- <firstname>Daniel</firstname>
- <surname>Elstner</surname>
- <contrib>Section "Build Structure" of chapter
- on "Wrapping C Libraries with gmmproc".</contrib>
+ <personname><firstname>Daniel</firstname><surname>Elstner</surname></personname>
+ <contrib>Section "Build Structure" of chapter on "Wrapping C Libraries with gmmproc".</contrib>
</author>
<author>
- <firstname>Chris</firstname>
- <surname>Vine</surname>
- <contrib>Chapter on "Multi-threaded programs".</contrib>
+ <personname><firstname>Chris</firstname><surname>Vine</surname></personname>
+ <contrib>Chapter on "Multi-threaded programs".</contrib>
</author>
<author>
- <firstname>David</firstname>
- <surname>King</surname>
+ <personname><firstname>David</firstname><surname>King</surname></personname>
<contrib>Section on Gtk::Grid.</contrib>
</author>
<author>
- <firstname>Pedro</firstname>
- <surname>Ferreira</surname>
+ <personname><firstname>Pedro</firstname><surname>Ferreira</surname></personname>
<contrib>Chapter on Keyboard Events.</contrib>
</author>
<author>
- <firstname>Kjell</firstname>
- <surname>Ahlstedt</surname>
+ <personname><firstname>Kjell</firstname><surname>Ahlstedt</surname></personname>
<contrib>Update from gtkmm 3 to gtkmm 4.</contrib>
- <contrib>Chapter on "Building applications".</contrib>
+ <contrib>Chapter on "Building applications".</contrib>
</author>
</authorgroup>
<abstract>
-
<!-- This text is copied from the introduction. -->
<para>This book explains key concepts of the >kmm; C++ API for creating user interfaces. It also
introduces the main user interface elements ("widgets").
</para>
-
</abstract>
-
<copyright>
<year>2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010</year>
<holder>Murray Cumming</holder>
@@ -124,13 +108,12 @@ See https://gitlab.gnome.org/GNOME/gtkmm-documentation/-/merge_requests/11
You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by
visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
</para>
</legalnotice>
+ </info>
- </bookinfo>
-
-<chapter id="chapter-introduction">
+<chapter xml:id="chapter-introduction">
<title>Introduction</title>
-<sect1 id="sec-this-book">
+<section xml:id="sec-this-book">
<title>This book</title>
<para>This book explains key concepts of the >kmm; C++ API for creating user interfaces. It also
introduces the main user interface elements ("widgets"). Although it mentions classes, constructors, and
methods, it does not go into great detail. Therefore, for full API information you should follow the links
into the reference documentation.</para>
@@ -149,13 +132,14 @@ There are paragraphs that describe >kmm; 3 rather than >kmm; 4.
All shown example programs are compatible with >kmm; 4, though.
</para>
</note>
-</sect1>
+</section>
-<sect1 id="sec-gtkmm">
+<section xml:id="sec-gtkmm">
<title>gtkmm</title>
+
<para>
>kmm; is a C++ wrapper for
-<ulink url="http://www.gtk.org/";>GTK</ulink>,
+<link xlink:href="http://www.gtk.org/";>GTK</link>,
a library used to create graphical user
interfaces. It is licensed using the LGPL license, so you can develop
open software, free software, or even commercial non-free software
@@ -165,36 +149,41 @@ using >kmm; without purchasing licenses.
and had a + in the name. However, as -- is not easily indexed by search engines,
the package generally went by the name >kmm;, and that's what we stuck with.</para>
-<sect2 id="why-use-gtkmm">
+<section xml:id="why-use-gtkmm">
<title>Why use >kmm; instead of GTK?</title>
+
<para>>kmm; allows you to write code using normal C++ techniques such as encapsulation, derivation, and
polymorphism. As a C++ programmer you probably already realise that this leads to clearer and better
organized code.</para>
<para>>kmm; is more type-safe, so the compiler can detect errors that would only be detected at run time
when using C. This use of specific types also makes the API clearer because you can see what types should be
used just by looking at a method's declaration.</para>
<para>Inheritance can be used to derive new widgets. The derivation of new widgets in GTK C code is so
complicated and error prone that almost no C coders do it. As a C++ developer you know that derivation is an
essential Object Orientated technique.</para>
<para>Member instances can be used, simplifying memory management. All GTK C widgets are dealt with by use
of pointers. As a C++ coder you know that pointers should be avoided where possible.</para>
<para>>kmm; involves less code compared to GTK, which uses prefixed function names and lots of cast
macros.</para>
-</sect2>
+</section>
-<sect2 id="gtkmm-vs-qt">
+<section xml:id="gtkmm-vs-qt">
<title>>kmm; compared to Qt</title>
+
<para>Trolltech's Qt is the closest competition to >kmm;, so it deserves discussion.</para>
<para>>kmm; developers tend to prefer >kmm; to Qt because >kmm; does things in a more C++ way. Qt
originates from a time when C++ and the standard library were not standardised or well supported by
compilers. It therefore duplicates a lot of stuff that is now in the standard library, such as containers and
type information. Most significantly, Trolltech modified the C++ language to provide signals, so that Qt
classes cannot be used easily with non-Qt classes. >kmm; was able to use standard C++ to provide signals
without changing the C++ language.
-See the <ulink url="https://wiki.gnome.org/Projects/gtkmm/FAQ";>FAQ</ulink> for more detailed
differences.</para>
-</sect2>
+See the <link xlink:href="https://wiki.gnome.org/Projects/gtkmm/FAQ";>FAQ</link> for more detailed
differences.</para>
+</section>
-<sect2 id="gtkmm-is-a-wrapper">
+<section xml:id="gtkmm-is-a-wrapper">
<title>>kmm; is a wrapper</title>
+
<para>
>kmm; is not a native C++ toolkit, but a C++ wrapper of a C toolkit. This separation of interface and
implementation has advantages. The >kmm; developers spend most of their time talking about how >kmm; can
present the clearest API, without awkward compromises due to obscure technical details. We contribute a
little to the underlying GTK code base, but so do the C coders, and the Perl coders and the Python coders,
etc. Therefore GTK benefits from a broader user base than language-specific toolkits - there are more
implementers, more developers, more testers, and more users.</para>
-</sect2>
-</sect1>
+</section>
+</section>
</chapter>
-<chapter id="chapter-installation">
+<chapter xml:id="chapter-installation">
<title>Installation</title>
-<sect1 id="sec-installation-dependencies">
+
+<section xml:id="sec-installation-dependencies">
<title>Dependencies</title>
+
<para>
Before attempting to install >kmm;<application>-4.0</application>,
you might first need to install these other packages.
@@ -218,12 +207,12 @@ applications and libraries:
<listitem><para><application>gdk-pixbuf-2.0</application></para></listitem>
<listitem><para><application>graphene-1.0</application></para></listitem>
</itemizedlist>
-</sect1>
+</section>
-<sect1 id="sec-install-unix-and-linux">
+<section xml:id="sec-install-unix-and-linux">
<title>Unix and Linux</title>
-<sect2 id="sec-linux-install-from-packages">
+<section xml:id="sec-linux-install-from-packages">
<title>Prebuilt Packages</title>
<para>
@@ -249,16 +238,16 @@ surprised, for instance, to find >kmm; 4.8 supplied by Debian's
<application>libgtkmm-4.0-dev</application> package.
</para>
</note>
-</sect2>
+</section>
-<sect2 id="sec-install-from-source">
+<section xml:id="sec-install-from-source">
<title>Installing From Source</title>
<para>
If your distribution does not provide a pre-built >kmm; package, or if you
want to install a different version than the one provided by your distribution,
you can also install >kmm; from source. The source code for >kmm; can
-be downloaded from <ulink url="https://download.gnome.org/sources/gtkmm/";></ulink>.
+be downloaded from <uri xmlns:xlink="http://www.w3.org/1999/xlink";
xlink:href="https://download.gnome.org/sources/gtkmm/";>https://download.gnome.org/sources/gtkmm/</uri>.
</para>
<para>
After you've installed all of the dependencies, download the >kmm; source
@@ -302,26 +291,26 @@ be downloaded from <ulink url="https://download.gnome.org/sources/gtkmm/";></ulin
<para>
If you want to help develop >kmm; or experiment with new features, you can
also install >kmm; from git. Most users will never need to do this, but if
- you're interested in helping with >kmm; development, see the <link
- linkend="chapter-working-with-source">Working with gtkmm's Source Code</link> appendix.
+ you're interested in helping with >kmm; development, see the <link
linkend="chapter-working-with-source">Working with gtkmm's Source Code</link> appendix.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-packages-windows">
+<section xml:id="sec-packages-windows">
<title>Microsoft Windows</title>
+
<para>GTK and >kmm; were designed to work well with Microsoft Windows, and the
developers encourage its use on the win32 platform. However, Windows has no standard
installation system for development libraries. Please see the
-<ulink url="https://wiki.gnome.org/Projects/gtkmm/MSWindows";>Windows Installation</ulink>
+<link xlink:href="https://wiki.gnome.org/Projects/gtkmm/MSWindows";>Windows Installation</link>
page or the <link linkend="sec-windows-installation">>kmm; and Win32</link> appendix
for Windows-specific installation instructions and notes.</para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-basics">
+<chapter xml:id="chapter-basics">
<title>Basics</title>
<para>
@@ -331,7 +320,7 @@ This chapter will introduce some of the most important aspects of >kmm; coding
Your existing knowledge of C++ will help you with >kmm; as it would with any library. Unless we state
otherwise, you can expect >kmm; classes to behave like any other C++ class, and you can expect to use your
existing C++ techniques with >kmm; classes.
</para>
-<sect1 id="sec-basics-simple-example">
+<section xml:id="sec-basics-simple-example">
<title>Simple Example</title>
<para>
@@ -339,7 +328,7 @@ To begin our introduction to >kmm;, we'll start with the simplest
program possible. This program will create an empty 200 x 200 pixel window.
</para>
-<para><ulink url="&url_examples_base;base">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;base">Source Code</link></para>
<para>We will now explain each part of the example</para>
<programlisting>#include <gtkmm.h></programlisting>
@@ -380,7 +369,7 @@ Your <function>main()</function> function will then return with an appropriate s
The <parameter>argc</parameter> and <parameter>argv</parameter> arguments, passed to your application on the
command line,
can be checked when <methodname>make_window_and_run()</methodname> is called, but this simple application
does not use those arguments.
</para>
-<programlisting>return app->make_window_and_run<MyWindow>(argc, argv);</programlisting>
+<programlisting>return app->make_window_and_run<MyWindow>(argc, argv);</programlisting>
<para>
After putting the source code in <literal>simple.cc</literal> you can compile
@@ -395,14 +384,15 @@ Note also that <literal>simple.cc</literal> must come before the <literal>pkg-co
invocation on the command line. <literal>-std=c++17</literal> is necessary only if
your compiler is not C++17 compliant by default.
</para>
-</sect1>
+</section>
-<sect1 id="sec-headers-and-linking">
+<section xml:id="sec-headers-and-linking">
<title>Headers and Linking</title>
+
<note>
<para>
This section describes building with Autotools. The newer
-<ulink url="https://mesonbuild.com/";>Meson build system</ulink> is a good alternative.
+<link xlink:href="https://mesonbuild.com/";>Meson build system</link> is a good alternative.
</para>
</note>
@@ -422,7 +412,7 @@ find them in. Try running it from your shell-prompt to see the results on your s
<para>
However, this is even simpler when using the <function>PKG_CHECK_MODULES()</function> macro in a standard
configure.ac file with autoconf and automake.
For instance:
-<programlisting>PKG_CHECK_MODULES([MYAPP], [gtkmm-4.0 >= 4.8.0])</programlisting>
+<programlisting>PKG_CHECK_MODULES([MYAPP], [gtkmm-4.0 >= 4.8.0])</programlisting>
This checks for the presence of gtkmm and defines MYAPP_LIBS and MYAPP_CFLAGS for use in your Makefile.am
files.
</para>
<para>gtkmm-4.0 is the name of the current stable API. There are older APIs called gtkmm-2.4
@@ -435,18 +425,19 @@ with gtkmm-4.0 without affecting existing applications.
<para>Note that if you mention extra modules in addition to gtkmm-4.0, they should be separated by spaces,
not commas.
</para>
-<para>The GNU site has more information about <ulink
url="https://www.gnu.org/software/autoconf/";>autoconf</ulink>
-and <ulink url="https://www.gnu.org/software/automake/";>automake</ulink>.
+<para>The GNU site has more information about <link
xlink:href="https://www.gnu.org/software/autoconf/";>autoconf</link>
+and <link xlink:href="https://www.gnu.org/software/automake/";>automake</link>.
</para>
<para>If you start by experimenting with a small application that you plan to use just for yourself,
it's easier to start with a Makefile similar to the <filename>Makefile.example</filename> files
in the <link linkend="chapter-building-applications">Building applications</link> chapter.
</para>
-</sect1>
+</section>
-<sect1 id="sec-widgets-overview">
+<section xml:id="sec-widgets-overview">
<title>Widgets</title>
+
<para>>kmm; applications consist of windows containing widgets, such as buttons and text boxes. In some
other systems, widgets are called "controls". For each widget in your application's windows, there is a C++
object in your application's code. So you just need to call a method of the widget's class to affect the
visible widget.</para>
<para>Widgets are arranged inside container widgets such as frames and notebooks, in a hierarchy of widgets
within widgets. Some of these container widgets, such as <classname>Gtk::Grid</classname>, are not visible -
they exist only to arrange other widgets. Here is some example code that adds 2
<classname>Gtk::Button</classname> widgets to a <classname>Gtk::Box</classname> container widget:
<programlisting>m_box.append(m_Button1);
@@ -472,9 +463,9 @@ learn more about >kmm; memory management techniques in the
<link linkend="chapter-memory">Memory Management chapter</link>.
</para>
-</sect1>
+</section>
-<sect1 id="sec-signals-overview">
+<section xml:id="sec-signals-overview">
<title>Signals</title>
<para>
@@ -493,13 +484,14 @@ button click result in an action, we set up a
<para>For information about implementing your own signals rather than
just connecting to the existing >kmm; signals, see the <link
linkend="chapter-custom-signals">appendix</link>.</para>
-</sect1>
+</section>
-<sect1 id="sec-basics-ustring">
+<section xml:id="sec-basics-ustring">
<title>Glib::ustring</title>
+
<para>You might be surprised to learn that >kmm; doesn't use <classname>std::string</classname> in its
interfaces. Instead it uses <classname>Glib::ustring</classname>, which is so similar and unobtrusive that
you could actually pretend that each <classname>Glib::ustring</classname> is a
<classname>std::string</classname> and ignore the rest of this section. But read on if you want to use
languages other than English in your application.</para>
<para>std::string uses 8 bits per character, but 8 bits aren't enough to encode languages such as Arabic,
Chinese, and Japanese.
-Although the encodings for these languages have been specified by the <ulink
url="http://www.unicode.org/";>Unicode Consortium</ulink>,
+Although the encodings for these languages have been specified by the <link
xlink:href="http://www.unicode.org/";>Unicode Consortium</link>,
the C and C++ languages do not yet provide any standardised Unicode support for UTF-8 encoding.
GTK and GNOME chose to implement Unicode using UTF-8, and that's what is wrapped by Glib::ustring.
It provides almost exactly the same interface as std::string, along with automatic conversions to and from
std::string.</para>
@@ -509,14 +501,15 @@ It provides almost exactly the same interface as std::string, along with automat
<para>Unlike the Windows UCS-2 Unicode solution, this does not require any special compiler options to
process string literals, and it does not result in Unicode executables and libraries which are incompatible
with ASCII ones.</para>
-<para><ulink url="&url_refdocs_base_glib;ustring.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_glib;ustring.html">Reference</link></para>
<para>See the <link linkend="chapter-internationalization">Internationalization</link> section for
information about providing the UTF-8 string literals.</para>
-</sect1>
+</section>
-<sect1 id="sec-basics-gobj-and-wrap">
+<section xml:id="sec-basics-gobj-and-wrap">
<title>Mixing C and C++ APIs</title>
+
<para>You can use C APIs which do not yet have convenient C++ interfaces.
It is generally not a problem to use C APIs from C++, and >kmm; helps by
providing access to the underlying C object, and providing an easy way to create
@@ -558,9 +551,9 @@ Don't delete the C++ instance before you want the C instance to die.
to the C instance is dropped. This includes all <function>Glib::wrap()</function>
overloads that return a <classname>Glib::RefPtr</classname>.</para>
-</sect1>
+</section>
-<sect1 id="sec-helloworld">
+<section xml:id="sec-helloworld">
<title>Hello World in >kmm;</title>
<para>
@@ -568,16 +561,16 @@ We've now learned enough to look at a real example. In accordance with an ancien
tradition of computer science, we now introduce Hello World, a la >kmm;:
</para>
-<para><ulink url="&url_examples_base;helloworld">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;helloworld">Source Code</link></para>
<para>
Try to compile and run it before going on. You should see something like this:
</para>
-<figure id="figure-helloworld">
+<figure xml:id="figure-helloworld">
<title>Hello World</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;helloworld.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;helloworld.png"/></imageobject></mediaobject>
</screenshot>
</figure>
@@ -620,7 +613,7 @@ omitted:
<para>
Notice that we've used an initialiser statement to give the <literal>m_button</literal>
-object the label "Hello World".
+object the label "Hello World".
</para>
<para>
@@ -647,7 +640,7 @@ without comments:
<programlisting>int main(int argc, char* argv[])
{
auto app = Gtk::Application::create("org.gtkmm.example");
- return app->make_window_and_run<HelloWorld>(argc, argv);
+ return app->make_window_and_run<HelloWorld>(argc, argv);
}</programlisting>
<para>
@@ -669,20 +662,19 @@ Like the simple example we showed earlier, this Hello World program does not use
the command-line parameters.
</para>
-</sect1>
+</section>
</chapter>
-<chapter id="changes-gtkmm3">
+<chapter xml:id="changes-gtkmm3">
<title>Changes in >kmm; 3</title>
<para>>kmm;-3.0 is an old version of the >kmm; API that installs in parallel with the still older
>kmm;-2.4 API and the new >kmm;-4.0 API. The last version of the >kmm;-2.4 API was >kmm; 2.24.
>kmm; 3 has no major fundamental differences to >kmm; 2 but does make several small changes that were not
possible while maintaining binary compatibility. If you never used the >kmm;-2.4 API then you can safely
ignore this chapter.</para>
<para>>kmm; 3's library is called <literal>libgtkmm-3.0</literal> rather than
<literal>libgtkmm-2.4</literal> and installs its headers in a similarly-versioned directory, so your
pkg-config check should ask for <literal>gtkmm-3.0</literal> rather than <literal>gtkmm-2.4</literal>.</para>
-
<para>>kmm; 3 added some new classes:</para>
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem><simpara><classname>Gtk::AppChooser</classname>, <classname>Gtk::AppChooserButton</classname>,
<classname>Gtk::AppChooserDialog</classname> allow the user to select an installed application to open a
particular type of content.</simpara></listitem>
<listitem><simpara><classname>Gtk::Grid</classname> is a new container widget that will eventually replace
<classname>Gtk::Box</classname> and <classname>Gtk::Table</classname>. It arranges its children according to
properties of those children rather than its own layout details.</simpara></listitem>
<listitem><simpara><classname>Gtk::Switch</classname> displays On/Off states more explictly than
<classname>Gtk::CheckButton</classname>. It may be useful, for instance, when allowing users to activate
hardware.</simpara></listitem>
@@ -691,7 +683,7 @@ the command-line parameters.
<para>>kmm; 3 also made several small changes to the API, which you will probably encounter when porting
code that used >kmm;-2.4. Here is a short list:</para>
<para>
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem><simpara><classname>Gtk::CellLayout</classname>, used by <classname>Gtk::IconView</classname>,
<classname>Gtk::TreeView::Column</classname> and <classname>Gtk::ComboBox</classname>, now has a
<classname>Gtk::CellArea</classname> which can be used to specify more details of how the
<classname>CellRenderer</classname>s are arranged and aligned.</simpara></listitem>
@@ -721,11 +713,11 @@ orientation (vertical or horizontal) to be specified without requiring the use o
<para>All deprecated API was removed in >kmm; 3.0, though there have been new deprecations in later
>kmm; 3.x versions.</para>
-<para>As a first step to porting your source code to >kmm;-3.0 you should probably ensure that your
application builds with the deprecated >kmm;-2.4 API disabled, by defining macro such as
GTKMM_DISABLE_DEPRECATED. There are some autotools macros that can help with this by defining them optionally
at build time. See the <ulink url="https://wiki.gnome.org/Projects/gtkmm/PortingToGtkmm3";>gtkmm 3 porting
wiki page</ulink> for more details.</para>
+<para>As a first step to porting your source code to >kmm;-3.0 you should probably ensure that your
application builds with the deprecated >kmm;-2.4 API disabled, by defining macro such as
GTKMM_DISABLE_DEPRECATED. There are some autotools macros that can help with this by defining them optionally
at build time. See the <link xlink:href="https://wiki.gnome.org/Projects/gtkmm/PortingToGtkmm3";>gtkmm 3
porting wiki page</link> for more details.</para>
</chapter>
-<chapter id="changes-gtkmm4">
+<chapter xml:id="changes-gtkmm4">
<title>Changes in >kmm;-4.0 and <application>glibmm-2.68</application></title>
<para>>kmm;-4.0 is a new version of the >kmm; API that installs in parallel with the
@@ -752,14 +744,14 @@ to set the global locale for you, you should add a call to
<function>Glib::set_init_to_users_preferred_locale(false)</function> before any call to
<function>Glib::init()</function> or <methodname>Gtk::Application::create()</methodname>.
</para>
-<para><ulink url="&url_refdocs_base_glib_html;namespaceGlib.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_glib_html;namespaceGlib.html">Reference</link></para>
<para>There are lots and lots of differences between >kmm;-3.0 and >kmm;-4.0.
The following lists are not complete.</para>
<para>Some new classes were added in >kmm; 4 and <application>glibmm</application> 2.68:</para>
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem><simpara><classname>Glib::ExtraClassInit</classname> and <classname>Gtk::Snapshot</classname>:
These classes are needed only for writing custom widgets. See the
<link linkend="sec-custom-widgets">Custom Widgets</link> section.</simpara></listitem>
@@ -783,7 +775,7 @@ The following lists are not complete.</para>
when porting code that used >kmm;-3.0 and <application>glibmm</application>-2.4. Here is a short
list:</para>
<para>
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem><simpara>A C++17 compiler is required.</simpara></listitem>
<listitem><simpara><classname>Gtk::Button</classname>, <classname>Gtk::ToolButton</classname>,
<classname>Gtk::MenuItem</classname> and <classname>Gtk::Switch</classname>
@@ -836,15 +828,15 @@ that your application builds with the deprecated >kmm;-3.0 and <application>gl
API disabled, by defining the macros GTKMM_DISABLE_DEPRECATED, GDKMM_DISABLE_DEPRECATED,
GLIBMM_DISABLE_DEPRECATED and GIOMM_DISABLE_DEPRECATED. There are some autotools macros
that can help with this by defining them optionally at build time. See the
-<ulink url="https://wiki.gnome.org/Projects/gtkmm/PortingToGtkmm3";>Porting from
-gtkmm-2.4 to gtkmm-3.0</ulink> wiki page for more details.</para>
+<link xlink:href="https://wiki.gnome.org/Projects/gtkmm/PortingToGtkmm3";>Porting from
+gtkmm-2.4 to gtkmm-3.0</link> wiki page for more details.</para>
-<para>See also <ulink url="https://developer.gnome.org/gtk4/unstable/gtk-migrating-3-to-4.html";>
-Migrating from GTK 3.x to GTK 4</ulink>.</para>
+<para>See also <link xlink:href="https://developer.gnome.org/gtk4/unstable/gtk-migrating-3-to-4.html";>
+Migrating from GTK 3.x to GTK 4</link>.</para>
</chapter>
-<chapter id="chapter-button-widget">
+<chapter xml:id="chapter-button-widget">
<title>Buttons</title>
<para>
@@ -857,7 +849,7 @@ Migrating from GTK 3.x to GTK 4</ulink>.</para>
<term>Push buttons</term>
<listitem>
<para>
-<ulink url="&url_refdocs_base_gtk;Button.html"><classname>Gtk::Button</classname></ulink>. Standard buttons,
usually
+<link xlink:href="&url_refdocs_base_gtk;Button.html"><classname>Gtk::Button</classname></link>. Standard
buttons, usually
marked with a label or picture. Pushing one triggers an action. See the <link
linkend="sec-pushbuttons">Button</link> section.
</para>
</listitem>
@@ -866,7 +858,7 @@ marked with a label or picture. Pushing one triggers an action. See the <link li
<term>Toggle buttons</term>
<listitem>
<para>
-<ulink url="&url_refdocs_base_gtk;ToggleButton.html"><classname>Gtk::ToggleButton</classname></ulink>.
+<link xlink:href="&url_refdocs_base_gtk;ToggleButton.html"><classname>Gtk::ToggleButton</classname></link>.
Unlike a normal Button, which springs back up, a ToggleButton stays down until you
press it again. It might be useful as an on/off switch. See the <link
linkend="sec-toggle-buttons">ToggleButton</link> section.
</para>
@@ -876,7 +868,7 @@ press it again. It might be useful as an on/off switch. See the <link linkend="s
<term>Check buttons</term>
<listitem>
<para>
-<ulink url="&url_refdocs_base_gtk;CheckButton.html"><classname>Gtk::CheckButton</classname></ulink>.
+<link xlink:href="&url_refdocs_base_gtk;CheckButton.html"><classname>Gtk::CheckButton</classname></link>.
These act like ToggleButtons, but show their state in small squares,
with their label at the side. They should be used in most situations
which require an on/off setting.
@@ -907,7 +899,7 @@ widgets will vary. In the case of check buttons and radio buttons, they
may vary considerably.
</para>
-<sect1 id="sec-pushbuttons">
+<section xml:id="sec-pushbuttons">
<title>Button</title>
<para>
@@ -931,28 +923,29 @@ The <classname>Gtk::Button</classname> widget has the <literal>clicked</literal>
which is emitted when the button is pressed and released.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Button.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Button.html">Reference</link></para>
-<sect2 id="pushbutton-example"><title>Example</title>
+<section xml:id="pushbutton-example">
+<title>Example</title>
<para>
This example creates a button with a picture and a label.
</para>
-<figure id="figure-buttons">
+<figure xml:id="figure-buttons">
<title>buttons example</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buttons.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buttons.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buttons/button">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;buttons/button">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-toggle-buttons">
+<section xml:id="sec-toggle-buttons">
<title>ToggleButton</title>
<para><classname>ToggleButton</classname>s are like normal <classname>Button</classname>s, but when clicked
they remain activated, or pressed, until clicked again.</para>
@@ -969,11 +962,11 @@ You can use the <methodname>toggled()</methodname> method to toggle the button,
forcing it to be up or down: This switches the button's state, and causes the <literal>toggled</literal>
signal to be emitted.
</para>
-<para><ulink url="&url_refdocs_base_gtk;ToggleButton.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;ToggleButton.html">Reference</link></para>
-</sect1>
+</section>
-<sect1 id="sec-checkbuttons">
+<section xml:id="sec-checkbuttons">
<title>CheckButton</title>
<para>
@@ -984,23 +977,24 @@ appearance. You can check and set a check button using the same
member methods as for <classname>Gtk::ToggleButton</classname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;CheckButton.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;CheckButton.html">Reference</link></para>
-<sect2 id="checkbutton-example"><title>Example</title>
+<section xml:id="checkbutton-example">
+<title>Example</title>
-<figure id="figure-checkbutton">
+<figure xml:id="figure-checkbutton">
<title>CheckButton</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;checkbutton.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;checkbutton.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buttons/checkbutton">Source Code</ulink></para>
-</sect2>
+<para><link xlink:href="&url_examples_base;buttons/checkbutton">Source Code</link></para>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-radio-buttons">
+<section xml:id="sec-radio-buttons">
<title>Radio Button</title>
<para>
@@ -1009,7 +1003,8 @@ act as radio buttons when they form a group. Only one button in a group can be
selected at any one time.
</para>
-<sect2 id="radiobutton-groups"><title>Groups</title>
+<section xml:id="radiobutton-groups">
+<title>Groups</title>
<para>
You create the buttons, and set up their group afterwards. In the following example,
we put 3 radio buttons in a group:
@@ -1030,42 +1025,41 @@ same group by using <methodname>set_group()</methodname> to tell the other
<classname>CheckButton</classname>.
</para>
-</sect2>
+</section>
-<sect2 id="radiobutton-methods"><title>Methods</title>
+<section xml:id="radiobutton-methods">
+<title>Methods</title>
<para>
<classname>CheckButton</classname>s and <classname>ToggleButton</classname>s are "off"
when created; this means that when you first make a group of them, they will all be off.
Don't forget to turn one of them on using <methodname>set_active()</methodname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;RadioButton.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;RadioButton.html">Reference</link></para>
-</sect2>
+</section>
-<sect2 id="radiobutton-example"><title>Example</title>
+<section xml:id="radiobutton-example">
+<title>Example</title>
<para>
The following example demonstrates the use of grouped
<classname>CheckButton</classname>s:
</para>
-<figure id="figure-radiobutton">
+<figure xml:id="figure-radiobutton">
<title>RadioButton</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;radiobuttons.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;radiobuttons.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buttons/radiobutton">Source Code</ulink></para>
-
-</sect2>
-
-</sect1>
+<para><link xlink:href="&url_examples_base;buttons/radiobutton">Source Code</link></para>
+</section>
+</section>
</chapter>
-
-<chapter id="chapter-range-widgets">
+<chapter xml:id="chapter-range-widgets">
<title>Range Widgets</title>
<para>
@@ -1093,9 +1087,9 @@ the <link linkend="chapter-adjustment">Adjustments</link> section for further
details.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Range.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Range.html">Reference</link></para>
-<sect1 id="sec-scrollbar-widgets">
+<section xml:id="sec-scrollbar-widgets">
<title>Scrollbar Widgets</title>
<para>
@@ -1110,11 +1104,11 @@ The orientation of a <classname>Gtk::Scrollbar</classname> can be either
horizontal or vertical.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Scrollbar.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Scrollbar.html">Reference</link></para>
-</sect1>
+</section>
-<sect1 id="sec-scale-widgets">
+<section xml:id="sec-scale-widgets">
<title>Scale Widgets</title>
<para>
@@ -1134,7 +1128,7 @@ horizontal or vertical. The default constructor creates an
<classname>Adjustment</classname> details to get meaningful behaviour.
</para>
-<sect2 id="scale-useful-methods">
+<section xml:id="scale-useful-methods">
<title>Useful methods</title>
<para>
@@ -1155,12 +1149,12 @@ Also, the value can be drawn in different positions relative to the trough,
specified by the <methodname>set_value_pos()</methodname> method.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Scale.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Scale.html">Reference</link></para>
-</sect2>
-</sect1>
+</section>
+</section>
-<sect1 id="sec-range-example">
+<section xml:id="sec-range-example">
<title>Example</title>
<para>
@@ -1171,23 +1165,23 @@ adjustments, so you can see how they affect the way these widgets work
for the user.
</para>
-<figure id="figure-range-widgets">
+<figure xml:id="figure-range-widgets">
<title>Range Widgets</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;range_widgets.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;range_widgets.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;range_widgets">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;range_widgets">Source Code</link></para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-misc-widgets">
+<chapter xml:id="chapter-misc-widgets">
<title>Miscellaneous Widgets</title>
-<sect1 id="sec-labels">
+<section xml:id="sec-labels">
<title>Label</title>
<para>
@@ -1210,15 +1204,16 @@ with <methodname>set_line_wrap()</methodname>.
<para>
Gtk::Label supports some simple formatting, for instance allowing you to make some
text bold, colored, or larger. You can do this by providing a string to
-<methodname>set_markup()</methodname>, using the <ulink
url="http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html";>Pango Markup syntax</ulink>. For
instance,
+<methodname>set_markup()</methodname>, using the <link
xlink:href="http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html";>Pango Markup syntax</link>. For
instance,
<code>
<b>bold text</b> and <s>strikethrough text</s>
</code>
.</para>
-<para><ulink url="&url_refdocs_base_gtk;Label.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Label.html">Reference</link></para>
-<sect2 id="label-example"><title>Example</title>
+<section xml:id="label-example">
+<title>Example</title>
<para>
Below is a short example to illustrate these functions. This example
makes use of the Frame widget to better demonstrate the label styles.
@@ -1227,23 +1222,23 @@ It is possible that the first character in <literal>m_Label_Normal</literal> is
underlined only when you press the <keycap>Alt</keycap> key.
</para>
-<figure id="figure-label">
+<figure xml:id="figure-label">
<title>Label</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;label.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;label.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;label">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;label">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-text-entry">
+<section xml:id="sec-text-entry">
<title>Entry</title>
-<sect2 id="sec-text-entry-simple">
+<section xml:id="sec-text-entry-simple">
<title>Simple Use</title>
<para>
@@ -1288,30 +1283,32 @@ default widget, use <methodname>Gtk::Widget::set_can_default()</methodname> and
<methodname>Gtk::Widget::grab_default()</methodname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Entry.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Entry.html">Reference</link></para>
-<sect3 id="entry-example"><title>Simple Entry Example</title>
+<section xml:id="entry-example">
+<title>Simple Entry Example</title>
<para>
This example uses <classname>Gtk::Entry</classname>. It also has two
<classname>CheckButton</classname>s, with which you can toggle the editable and
visible flags.
</para>
-<figure id="figure-entry-simple">
+<figure xml:id="figure-entry-simple">
<title>Entry</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;entry.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;entry.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;entry/simple">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;entry/simple">Source Code</link></para>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="sec-text-entry-completion">
+<section xml:id="sec-text-entry-completion">
<title>Entry Completion</title>
+
<para>An <classname>Entry</classname> widget can offer a drop-down list of
pre-existing choices based on the first few characters typed by the user. For
instance, a search dialog could suggest text from previous searches.
@@ -1334,9 +1331,10 @@ be specified with <methodname>set_match_func()</methodname>.
This is also useful if you wish to match on a part of the string other
than the start.</para>
-<para><ulink url="&url_refdocs_base_gtk;EntryCompletion.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;EntryCompletion.html">Reference</link></para>
-<sect3 id="entry-completion-example"><title>Entry Completion Example</title>
+<section xml:id="entry-completion-example">
+<title>Entry Completion Example</title>
<para>
This example creates a <classname>Gtk::EntryCompletion</classname> and associates
it with a <classname>Gtk::Entry</classname> widget. The completion uses a
@@ -1344,20 +1342,21 @@ it with a <classname>Gtk::Entry</classname> widget. The completion uses a
actions.
</para>
-<figure id="figure-entry-completion">
+<figure xml:id="figure-entry-completion">
<title>Entry Completion</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;entry_completion.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;entry_completion.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;entry/completion">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;entry/completion">Source Code</link></para>
-</sect3>
-</sect2>
+</section>
+</section>
-<sect2 id="sec-text-entry-icons">
+<section xml:id="sec-text-entry-icons">
<title>Entry Icons</title>
+
<para>An <classname>Entry</classname> widget can show an icon at the start or
end of the text area. The icon can be specifed by methods such as
<methodname>set_icon_from_pixbuf()</methodname> or
@@ -1365,52 +1364,55 @@ end of the text area. The icon can be specifed by methods such as
user pressing the icon by handling the
<methodname>signal_icon_press</methodname> signal.</para>
-<sect3 id="entry-icon-example"><title>Entry Icon Example</title>
+<section xml:id="entry-icon-example">
+<title>Entry Icon Example</title>
<para>
This example shows a <classname>Gtk::Entry</classname> widget with a named
search icon, and prints text to the terminal when the icon is pressed.
</para>
-<figure id="figure-entry-icon">
+<figure xml:id="figure-entry-icon">
<title>Entry with Icon</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;entry_icon.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;entry_icon.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;entry/icon">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;entry/icon">Source Code</link></para>
-</sect3>
-</sect2>
+</section>
+</section>
-<sect2 id="sec-text-entry-progress">
+<section xml:id="sec-text-entry-progress">
<title>Entry Progress</title>
+
<para>An <classname>Entry</classname> widget can show a progress bar inside the
text area, under the entered text. The progress bar will be shown if the
<methodname>set_progress_fraction()</methodname> or
<methodname>set_progress_pulse_step()</methodname> methods are called.</para>
-<sect3 id="entry-progress-example"><title>Entry Progress Example</title>
+<section xml:id="entry-progress-example">
+<title>Entry Progress Example</title>
<para>
This example shows a <classname>Gtk::Entry</classname> widget with a progress
bar.
</para>
-<figure id="figure-entry-progress">
+<figure xml:id="figure-entry-progress">
<title>Entry with Progress Bar</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;entry_progress.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;entry_progress.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;entry/progress">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;entry/progress">Source Code</link></para>
-</sect3>
-</sect2>
+</section>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-spinbutton">
+<section xml:id="sec-spinbutton">
<title>SpinButton</title>
<para>
@@ -1429,8 +1431,7 @@ change more quickly the longer the button is held down.
</para>
<para>
-<classname>SpinButton</classname>s use an <link
- linkend="chapter-adjustment">Adjustment</link> object to hold information about
+<classname>SpinButton</classname>s use an <link linkend="chapter-adjustment">Adjustment</link> object to
hold information about
the range of values. These Adjustment attributes are used by the Spin Button
like so:
<itemizedlist>
@@ -1488,7 +1489,8 @@ The <classname>SpinButton</classname> can create a default
</para>
-<sect2 id="spinbutton-methods"><title>Methods</title>
+<section xml:id="spinbutton-methods">
+<title>Methods</title>
<para>
The number of decimal places can be altered using the
@@ -1522,30 +1524,31 @@ To force it to snap to the nearest <literal>step_increment</literal>,
use <methodname>set_snap_to_ticks()</methodname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;SpinButton.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;SpinButton.html">Reference</link></para>
-</sect2>
+</section>
-<sect2 id="spinbutton-example"><title>Example</title>
+<section xml:id="spinbutton-example">
+<title>Example</title>
<para>
Here's an example of a <classname>SpinButton</classname> in action:
</para>
-<figure id="figure-spinbutton">
+<figure xml:id="figure-spinbutton">
<title>SpinButton</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;spinbutton.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;spinbutton.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;spinbutton">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;spinbutton">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-progressbar">
+<section xml:id="sec-progressbar">
<title>ProgressBar</title>
<para>
@@ -1565,10 +1568,11 @@ but you can change it to a vertical progress bar by using the
<methodname>set_orientation()</methodname> method.
</para>
-<para><ulink url="&url_refdocs_base_gtk;ProgressBar.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;ProgressBar.html">Reference</link></para>
-<sect2 id="progressbar-activity-mode">
+<section xml:id="progressbar-activity-mode">
<title>Activity Mode</title>
+
<para>
Besides indicating the amount of progress that has occured, the
progress bar can also be used to indicate that there is some activity;
@@ -1589,48 +1593,48 @@ intervals. You can also choose the step size, with the
The progress bar can also display a configurable text
string next to the bar, using the <methodname>set_text()</methodname> method.
</para>
-</sect2>
+</section>
-<sect2 id="progressbar-example"><title>Example</title>
+<section xml:id="progressbar-example">
+<title>Example</title>
-<figure id="figure-progressbar">
+<figure xml:id="figure-progressbar">
<title>ProgressBar</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;progressbar.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;progressbar.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;progressbar">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;progressbar">Source Code</link></para>
-</sect2>
-
-</sect1>
+</section>
+</section>
-
-<sect1 id="sec-infobar">
+<section xml:id="sec-infobar">
<title>InfoBar</title>
<para>
An <classname>InfoBar</classname> may show small items of information or ask brief questions. Unlike a
<classname>Dialog</classname>, it appears at the top of the current window instead of opening a new window.
Its API is very similar to the <link linkend="chapter-dialogs">Gtk::Dialog</link> API.</para>
-<para><ulink url="&url_refdocs_base_gtk;InfoBar.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;InfoBar.html">Reference</link></para>
-<sect2 id="infobar-example"><title>Example</title>
+<section xml:id="infobar-example">
+<title>Example</title>
-<figure id="figure-infobar">
+<figure xml:id="figure-infobar">
<title>InfoBar</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;infobar.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;infobar.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;infobar">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;infobar">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-tooltips">
+<section xml:id="sec-tooltips">
<title>Tooltips</title>
<para>
@@ -1642,27 +1646,26 @@ on any <classname>Widget</classname>.
such as showing an image as well as text.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Widget.html">Widget Reference</ulink></para>
-<para><ulink url="&url_refdocs_base_gtk;Tooltip.html">Tooltip Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Widget.html">Widget Reference</link></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Tooltip.html">Tooltip Reference</link></para>
-<sect2 id="tooltip-example"><title>Example</title>
+<section xml:id="tooltip-example">
+<title>Example</title>
-<figure id="figure-tooltip">
+<figure xml:id="figure-tooltip">
<title>Tooltip</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;tooltip.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;tooltip.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;tooltips">Source Code</ulink></para>
-
-</sect2>
-
-</sect1>
+<para><link xlink:href="&url_examples_base;tooltips">Source Code</link></para>
+</section>
+</section>
</chapter>
-<chapter id="chapter-container-widgets">
+<chapter xml:id="chapter-container-widgets">
<title>Container Widgets</title>
<para>
@@ -1672,7 +1675,7 @@ child widgets, so these typically have more complex interfaces. Others, such as
<classname>Gtk::Frame</classname> contain only one child widget.
</para>
-<sect1 id="sec-single-item-containers">
+<section xml:id="sec-single-item-containers">
<title>Single-item Containers</title>
<para>
@@ -1688,7 +1691,7 @@ to divide a window into two separate "panes". This widget actually contains
two child widgets, but the number is fixed so it seems appropriate.
</para>
-<sect2 id="sec-frame">
+<section xml:id="sec-frame">
<title>Frame</title>
<para>
@@ -1698,25 +1701,24 @@ title. For instance, you might place a group of
<classname>Frame</classname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Frame.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Frame.html">Reference</link></para>
-<sect3 id="frame-example"><title>Example</title>
+<section xml:id="frame-example">
+<title>Example</title>
-<figure id="figure-frame">
+<figure xml:id="figure-frame">
<title>Frame</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;frame.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;frame.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;frame">Source Code</ulink></para>
-
-</sect3>
-
-</sect2>
+<para><link xlink:href="&url_examples_base;frame">Source Code</link></para>
+</section>
+</section>
-<sect2 id="sec-paned">
+<section xml:id="sec-paned">
<title>Paned</title>
<para>
@@ -1738,24 +1740,24 @@ You can adjust the position of the divider using the
so.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Paned.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Paned.html">Reference</link></para>
-<sect3 id="paned-example"><title>Example</title>
+<section xml:id="paned-example">
+<title>Example</title>
-<figure id="figure-paned">
+<figure xml:id="figure-paned">
<title>Paned</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;paned.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;paned.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;paned">Source Code</ulink></para>
-
-</sect3>
+<para><link xlink:href="&url_examples_base;paned">Source Code</link></para>
-</sect2>
+</section>
+</section>
-<sect2 id="sec-scrolledwindow">
+<section xml:id="sec-scrolledwindow">
<title>ScrolledWindow</title>
<para>
@@ -1779,28 +1781,28 @@ visible area. <literal>Gtk::PolicyType::ALWAYS</literal> will cause the
scrollbar to be displayed always.
</para>
-<para><ulink url="&url_refdocs_base_gtk;ScrolledWindow.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;ScrolledWindow.html">Reference</link></para>
-<sect3 id="scrolledwindow-example"><title>Example</title>
+<section xml:id="scrolledwindow-example">
+<title>Example</title>
<para>
Here is a simple example that packs 100 toggle buttons into a ScrolledWindow. Try resizing the window to see
the scrollbars react.
</para>
-<figure id="figure-scrolledwindow">
+<figure xml:id="figure-scrolledwindow">
<title>ScrolledWindow</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;scrolledwindow.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;scrolledwindow.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;scrolledwindow">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;scrolledwindow">Source Code</link></para>
-</sect3>
+</section>
+</section>
-</sect2>
-
-<sect2 id="sec-aspectframe">
+<section xml:id="sec-aspectframe">
<title>AspectFrame</title>
<para>
@@ -1812,30 +1814,30 @@ display a photograph without allowing the user to distort it horizontally or
vertically while resizing.
</para>
-<para><ulink url="&url_refdocs_base_gtk;AspectFrame.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;AspectFrame.html">Reference</link></para>
-<sect3 id="aspectframe-example">
+<section xml:id="aspectframe-example">
<title>Example</title>
+
<para>
The following program uses a <classname>Gtk::AspectFrame</classname> to present a
drawing area whose aspect ratio will always be 2:1, no matter how the user
resizes the top-level window.
</para>
-<figure id="figure-aspectframe">
+<figure xml:id="figure-aspectframe">
<title>AspectFrame</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;aspectframe.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;aspectframe.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;aspectframe">Source Code</ulink></para>
-</sect3>
-
-</sect2>
+<para><link xlink:href="&url_examples_base;aspectframe">Source Code</link></para>
+</section>
+</section>
-<sect2 id="sec-other-single-item-containers">
+<section xml:id="sec-other-single-item-containers">
<title>Other Single-item Containers</title>
<para>
@@ -1844,14 +1846,14 @@ complete list. Here are links to some example programs that show containers,
which are not mentioned elsewhere in this tutorial.
</para>
-<para><ulink url="&url_examples_base;expander">Source Code, Expander</ulink></para>
-<para><ulink url="&url_examples_base;popover">Source Code, Popover</ulink></para>
+<para><link xlink:href="&url_examples_base;expander">Source Code, Expander</link></para>
+<para><link xlink:href="&url_examples_base;popover">Source Code, Popover</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-multi-item-containers">
+<section xml:id="sec-multi-item-containers">
<title>Multiple-item Containers </title>
<para>
@@ -1863,8 +1865,9 @@ well as other methods. The <methodname>remove()</methodname> method for multiple
containers takes an argument, specifying which widget to remove.
</para>
-<sect2 id="container-packing">
+<section xml:id="container-packing">
<title>Packing</title>
+
<para>
You've probably noticed that >kmm; windows seem "elastic" - they can usually be stretched in many
different ways. This is due to the <emphasis>widget packing</emphasis>
system.
@@ -1947,23 +1950,23 @@ need to rely on visual form editors quite as much as you might with
other toolkits.
</para>
-</sect2>
+</section>
-<sect2 id="sec-helloworld2">
+<section xml:id="sec-helloworld2">
<title>An improved Hello World</title>
<para>
Let's take a look at a slightly improved <literal>helloworld</literal>, showing what we've learnt.
</para>
-<figure id="figure-helloworld2">
+<figure xml:id="figure-helloworld2">
<title>Hello World 2</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;helloworld2.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;helloworld2.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;helloworld2">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;helloworld2">Source Code</link></para>
<para>
After building and running this program, try resizing the window to see the
@@ -1973,9 +1976,9 @@ behaviour. Also, try playing with <methodname>set_expand()</methodname>,
while reading the <link linkend="sec-boxes">Boxes</link> section.
</para>
-</sect2>
+</section>
-<sect2 id="sec-boxes">
+<section xml:id="sec-boxes">
<title>Boxes</title>
<para>
@@ -1987,8 +1990,10 @@ top to bottom. You may use any combination of boxes inside or beside other
boxes to create the desired effect.
</para>
-<sect3 id="boxes-adding-widgets"><title>Adding widgets</title>
-<sect4 id="per-child-packing-options"><title>Per-child packing options</title>
+<section xml:id="boxes-adding-widgets">
+<title>Adding widgets</title>
+<section xml:id="per-child-packing-options">
+<title>Per-child packing options</title>
<para>
The <methodname>append()</methodname> method places widgets inside these
containers. It will start at the top and work its way down in a
@@ -2016,10 +2021,10 @@ There are basically five
different styles, as shown in this picture:
</para>
-<figure id="figure-box-packing1">
+<figure xml:id="figure-box-packing1">
<title>Box Packing 1</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;box_packing1.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;box_packing1.png"/></imageobject></mediaobject>
</screenshot>
</figure>
@@ -2032,11 +2037,12 @@ several buttons. Each of the buttons on a line is packed into the
methods.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Box.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Box.html">Reference</link></para>
-</sect4>
+</section>
-<sect4 id="per-container-packing-options"><title>Per-container packing options</title>
+<section xml:id="per-container-packing-options">
+<title>Per-container packing options</title>
<para>
Here's the constructor for the <classname>Box</classname> widget,
and methods that set per-container packing options:
@@ -2058,18 +2064,19 @@ figure should make it clearer. The shown margins are the left and right margins
of each button in the row.
</para>
-<figure id="figure-box-packing2">
+<figure xml:id="figure-box-packing2">
<title>Box Packing 2</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;box_packing2.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;box_packing2.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-</sect4>
-</sect3>
+</section>
+</section>
-<sect3 id="boxes-command-line-options">
+<section xml:id="boxes-command-line-options">
<title>Gtk::Application and command-line options</title>
+
<para>The following example program requires a command-line option.
The source code shows two ways of handling command-line options in combination
with <classname>Gtk::Application</classname>.
@@ -2098,19 +2105,20 @@ unless you want your application to exit without showing its main window.
<classname>Gtk::Application</classname>.)
</para></listitem>
</itemizedlist>
-</sect3>
+</section>
-<sect3 id="box-packing-example">
+<section xml:id="box-packing-example">
<title>Example</title>
+
<para>
Here is the source code for the example that produced the screenshots above. When you run this example,
provide a number between 1 and 3 as a command-line option, to see different packing options in use.</para>
-<para><ulink url="&url_examples_base;box">Source Code</ulink></para>
-</sect3>
+<para><link xlink:href="&url_examples_base;box">Source Code</link></para>
+</section>
-</sect2>
+</section>
-<sect2 id="sec-grid">
+<section xml:id="sec-grid">
<title>Grid</title>
<para>
@@ -2129,9 +2137,10 @@ the grid with <methodname>attach_next_to()</methodname>. Individual rows and col
child <classname>Widget</classname>s to control their spacing and their behaviour when the Grid is resized.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Grid.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Grid.html">Reference</link></para>
-<sect3 id="grid-example"><title>Example</title>
+<section xml:id="grid-example">
+<title>Example</title>
<para>
This example creates a window with three buttons in a grid.
The first two buttons are in the upper row, from left to right. A
@@ -2139,20 +2148,19 @@ third button is attached underneath the first button, in a new lower row,
spanning two columns.
</para>
-<figure id="figure-grid">
+<figure xml:id="figure-grid">
<title>Grid</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;grid.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;grid.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;grid">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;grid">Source Code</link></para>
-</sect3>
+</section>
+</section>
-</sect2>
-
-<sect2 id="sec-notebook">
+<section xml:id="sec-notebook">
<title>Notebook</title>
<para>
@@ -2183,24 +2191,25 @@ To programmatically change the selected page, use the
<methodname>set_current_page()</methodname> method.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Notebook.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Notebook.html">Reference</link></para>
-<sect3 id="notebook-example"><title>Example</title>
+<section xml:id="notebook-example">
+<title>Example</title>
-<figure id="figure-notebook">
+<figure xml:id="figure-notebook">
<title>Notebook</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;notebook.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;notebook.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;notebook/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;notebook/">Source Code</link></para>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="sec-assistant">
+<section xml:id="sec-assistant">
<title>Assistant</title>
<para>
@@ -2223,24 +2232,25 @@ To set the title of a page, use the <methodname>set_page_title()</methodname> me
To add widgets to the action area, use the <methodname>add_action_widget()</methodname> method. They will be
packed alongside the default buttons. Use the <methodname>remove_action_widget()</methodname> method to
remove widgets.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Assistant.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Assistant.html">Reference</link></para>
-<sect3 id="assistant-example"><title>Example</title>
+<section xml:id="assistant-example">
+<title>Example</title>
-<figure id="figure-assistant">
+<figure xml:id="figure-assistant">
<title>Assistant</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;assistant.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;assistant.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;assistant/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;assistant/">Source Code</link></para>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="sec-other-multi-item-containers">
+<section xml:id="sec-other-multi-item-containers">
<title>Other Multi-item Containers</title>
<para>
@@ -2249,26 +2259,25 @@ complete list. Here are links to some example programs that show containers,
which are not mentioned elsewhere in this tutorial.
</para>
-<para><ulink url="&url_examples_base;actionbar">Source Code, ActionBar</ulink></para>
-<para><ulink url="&url_examples_base;flowbox">Source Code, FlowBox</ulink></para>
-<para><ulink url="&url_examples_base;iconview">Source Code, IconView</ulink></para>
-
-</sect2>
-
-</sect1>
+<para><link xlink:href="&url_examples_base;actionbar">Source Code, ActionBar</link></para>
+<para><link xlink:href="&url_examples_base;flowbox">Source Code, FlowBox</link></para>
+<para><link xlink:href="&url_examples_base;iconview">Source Code, IconView</link></para>
+</section>
+</section>
</chapter>
-<chapter id="chapter-treeview">
-
+<chapter xml:id="chapter-treeview">
<title>The TreeView widget</title>
+
<para>
The <classname>Gtk::TreeView</classname> widget can contain lists or trees of
data, in columns.
</para>
-<sect1 id="sec-treeview-model">
+<section xml:id="sec-treeview-model">
<title>The Model</title>
+
<para>
Each <classname>Gtk::TreeView</classname> has an associated
<classname>Gtk::TreeModel</classname>, which contains the data displayed by the
@@ -2285,46 +2294,49 @@ either the <classname>ListStore</classname> or <classname>TreeStore</classname>
model classes.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TreeModel.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TreeModel.html">Reference</link></para>
-<sect2 id="treeview-model-liststore">
+<section xml:id="treeview-model-liststore">
<title>ListStore, for rows</title>
+
<para>
The <classname>ListStore</classname> contains simple rows of data, and each row
has no children.
</para>
-<figure id="figure-treeview-liststore-model">
+<figure xml:id="figure-treeview-liststore-model">
<title>TreeView - ListStore</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_list.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_list.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_refdocs_base_gtk;ListStore.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;ListStore.html">Reference</link></para>
-</sect2>
+</section>
-<sect2 id="treeview-model-treestore">
+<section xml:id="treeview-model-treestore">
<title>TreeStore, for a hierarchy</title>
+
<para>
The <classname>TreeStore</classname> contains rows of data, and each row may
have child rows.
</para>
-<figure id="figure-treeview-treestore-model">
+<figure xml:id="figure-treeview-treestore-model">
<title>TreeView - TreeStore</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_tree.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_tree.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_refdocs_base_gtk;TreeStore.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TreeStore.html">Reference</link></para>
-</sect2>
+</section>
-<sect2 id="treeview-model-columns">
+<section xml:id="treeview-model-columns">
<title>Model Columns</title>
+
<para>
The <classname>TreeModelColumnRecord</classname> class is used to keep track
of the columns and their data types. You add
@@ -2364,10 +2376,11 @@ not be static, because it often needs to be instantiated after
to make it a lazily instantiated singleton, so that it will be constructed
on-demand, whenever the first model accesses it.
</para>
-</sect2>
+</section>
-<sect2 id="treeview-adding-rows">
+<section xml:id="treeview-adding-rows">
<title>Adding Rows</title>
+
<para>
Add rows to the model with the <methodname>append()</methodname>,
<methodname>prepend()</methodname>, or <methodname>insert()</methodname> methods.
@@ -2376,7 +2389,8 @@ Add rows to the model with the <methodname>append()</methodname>,
<para>You can dereference the iterator to get the Row:
</para>
<programlisting>auto row = *iter;</programlisting>
-<sect3 id="treeview-adding-child-rows"><title>Adding child rows</title>
+<section xml:id="treeview-adding-child-rows">
+<title>Adding child rows</title>
<para>
<classname>Gtk::TreeStore</classname> models can have child items. Add them
with the <methodname>append()</methodname>, <methodname>prepend()</methodname>, or
@@ -2384,22 +2398,24 @@ with the <methodname>append()</methodname>, <methodname>prepend()</methodname>,
</para>
<programlisting>auto iter_child =
m_refTreeStore->append(row.children());</programlisting>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="treeview-setting-values">
+<section xml:id="treeview-setting-values">
<title>Setting values</title>
+
<para>
You can use the <methodname>operator[]</methodname> overload to set the data for a
particular column in the row, specifying the
<classname>TreeModelColumn</classname> used to create the model.
</para>
<programlisting>row[m_Columns.m_col_text] = "sometext";</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-getting-values">
+<section xml:id="treeview-getting-values">
<title>Getting values</title>
+
<para>
You can use the <methodname>operator[]</methodname> overload to get the data in a
particular column in a row, specifying the
@@ -2413,20 +2429,22 @@ instance, this would generate a compiler error:
</para>
<programlisting>//compiler error - no conversion from ustring to int.
int number = row[m_Columns.m_col_text];</programlisting>
-</sect2>
+</section>
+
+<section xml:id="treeview-hidden-columns">
+<title>"Hidden" Columns</title>
-<sect2 id="treeview-hidden-columns">
-<title>"Hidden" Columns</title>
<para>
You might want to associate extra data with each row. If so, just add
it as a Model column, but don't add it to the View.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-treeview">
+<section xml:id="sec-treeview">
<title>The View</title>
+
<para>
The View is the actual widget (<classname>Gtk::TreeView</classname>) that
displays the model (<classname>Gtk::TreeModel</classname>) data and allows the
@@ -2434,20 +2452,22 @@ user to interact with it. The View can show all of the model's columns, or just
some, and it can show them in various ways.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TreeView.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TreeView.html">Reference</link></para>
-<sect2 id="sec-treeview-using-a-model">
+<section xml:id="sec-treeview-using-a-model">
<title>Using a Model</title>
+
<para>
You can specify a <classname>Gtk::TreeModel</classname> when constructing the
<classname>Gtk::TreeView</classname>, or you can use the
<methodname>set_model()</methodname> method, like so:
</para>
<programlisting>m_TreeView.set_model(m_refListStore);</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-adding-view-columns">
+<section xml:id="treeview-adding-view-columns">
<title>Adding View Columns</title>
+
<para>
You can use the <methodname>append_column()</methodname> method to tell the View
that it should display certain Model columns, in a certain order, with a
@@ -2467,10 +2487,11 @@ your type into a string representation, with
supported by default - You could use (unsigned) int or (unsigned) long as the
column type instead.
</para>
-</sect2>
+</section>
-<sect2 id="treeview-multiple-model-columns-per-view-column">
+<section xml:id="treeview-multiple-model-columns-per-view-column">
<title>More than one Model Column per View Column</title>
+
<para>
To render more than one model column in a view column, you need to create the
<classname>TreeView::Column</classname> widget manually, and use
@@ -2496,10 +2517,11 @@ pColumn->pack_start(m_columns.icon, /* expand= */ false);
pColumn->pack_start(m_columns.iconname);
m_TreeView.append_column(*pColumn);</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-cellrenderer-details">
+<section xml:id="treeview-cellrenderer-details">
<title>Specifying CellRenderer details</title>
+
<para>
The default <classname>CellRenderers</classname> and their default behaviour
will normally suffice, but you might occasionally need finer control. For
@@ -2512,9 +2534,9 @@ data from various model columns through various aspects of its appearance.
auto pColumn = m_TreeView.get_column(cols_count-1);
if(pColumn)
{
- auto pRenderer = static_cast<Gtk::CellRendererToggle*>(pColumn->get_first_cell());
- pColumn->add_attribute(pRenderer->property_visible(), m_columns.visible);
- pColumn->add_attribute(pRenderer->property_activatable(), m_columns.world);</programlisting>
+ auto pRenderer = static_cast<Gtk::CellRendererToggle*>(pColumn->get_first_cell());
+ pColumn->add_attribute(pRenderer->property_visible(), m_columns.visible);
+ pColumn->add_attribute(pRenderer->property_activatable(), m_columns.world);</programlisting>
<para>
You can also connect to <classname>CellRenderer</classname> signals to detect user
@@ -2526,13 +2548,14 @@ pRenderer->signal_toggled().connect(
sigc::bind( sigc::mem_fun(*this,
&Example_TreeView_TreeStore::on_cell_toggled), m_columns.dave)
);</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-editable-cells">
+<section xml:id="treeview-editable-cells">
<title>Editable Cells</title>
-<sect3 id="treeview-editable-cells-automatic">
+<section xml:id="treeview-editable-cells-automatic">
<title>Automatically-stored editable cells.</title>
+
<para>
Cells in a <classname>TreeView</classname> can be edited in-place by the user.
To allow this, use the <classname>Gtk::TreeView</classname>
@@ -2544,10 +2567,11 @@ Model. Note that these methods are templates which can only be instantiated for
simple column types such as <classname>Glib::ustring</classname>, int, and
long.
</para>
-</sect3>
+</section>
-<sect3 id="treeview-editable-cells-custom">
+<section xml:id="treeview-editable-cells-custom">
<title>Implementing custom logic for editable cells.</title>
+
<para>
However, you might not want the new values to be stored
immediately. For instance, maybe you want to restrict the input to
@@ -2583,15 +2607,13 @@ to use <methodname>Gtk::TreeView::get_column()</methodname> and then call
In your signal handler, you should examine the new value and then
store it in the Model if that is appropriate for your application.
</para>
-</sect3>
-
-</sect2>
-
-
-</sect1>
+</section>
+</section>
+</section>
-<sect1 id="sec-iterating-over-model-rows">
+<section xml:id="sec-iterating-over-model-rows">
<title>Iterating over Model Rows</title>
+
<para>
<classname>Gtk::TreeModel</classname> provides a C++ Standard Library-style container of its
children, via the <methodname>children()</methodname> method. You can use the
@@ -2615,20 +2637,22 @@ for (auto row: refModel->children())
//Do something with the row - see above for set/get.
}</programlisting>
-<sect2 id="treeview-row-children">
+<section xml:id="treeview-row-children">
<title>Row children</title>
+
<para>
When using a <classname>Gtk::TreeStore</classname>, the rows can have child
rows, which can have their own children in turn. Use
<methodname>Gtk::TreeModel::Row::children()</methodname> to get the container of child
<classname>Row</classname>s:
</para>
<programlisting>Gtk::TreeModel::Children children = row.children();</programlisting>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-treeview-selection">
+<section xml:id="sec-treeview-selection">
<title>The Selection</title>
+
<para>
To find out what rows the user has selected, get the
<classname>Gtk::TreeView::Selection</classname> object from the
@@ -2636,17 +2660,19 @@ To find out what rows the user has selected, get the
</para>
<programlisting>auto refTreeSelection = m_TreeView.get_selection();</programlisting>
-<sect2 id="treeview-selection-mode">
+<section xml:id="treeview-selection-mode">
<title>Single or multiple selection</title>
+
<para>
By default, only single rows can be selected, but you can allow
multiple selection by setting the mode, like so:
</para>
<programlisting>refTreeSelection->set_mode(Gtk::SELECTION_MULTIPLE);</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-selected-rows">
+<section xml:id="treeview-selected-rows">
<title>The selected rows</title>
+
<para>
For single-selection, you can just call <methodname>get_selected()</methodname>,
like so:
@@ -2675,10 +2701,11 @@ void TheClass::selected_row_callback(
//Do something with the row.
}</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-selection-changed-signal">
+<section xml:id="treeview-selection-changed-signal">
<title>The "changed" signal</title>
+
<para>
To respond to the user clicking on a row or range of rows, connect to the
signal like so:
@@ -2686,10 +2713,11 @@ signal like so:
<programlisting>refTreeSelection->signal_changed().connect(
sigc::mem_fun(*this, &Example_IconTheme::on_selection_changed)
);</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-selection-preventing">
+<section xml:id="treeview-selection-preventing">
<title>Preventing row selection</title>
+
<para>
Maybe the user should not be able to select every item in your list or tree.
For instance, in the gtk-demo, you can select a demo to see the source code,
@@ -2712,10 +2740,11 @@ and then
const auto iter = model->get_iter(path);
return iter->children().empty(); // only allow leaf nodes to be selected
}</programlisting>
-</sect2>
+</section>
-<sect2 id="treeview-selection-changing">
+<section xml:id="treeview-selection-changing">
<title>Changing the selection</title>
+
<para>
To change the selection, specify a
<classname>Gtk::TreeModel::iterator</classname> or
@@ -2730,31 +2759,32 @@ or
<programlisting>auto iter = m_refModel->children().begin()
if(iter)
refTreeSelection->select(iter);</programlisting>
-</sect2>
-
-</sect1>
-
+</section>
+</section>
-<sect1 id="sec-treeview-sort">
+<section xml:id="sec-treeview-sort">
<title>Sorting</title>
+
<para>
The standard tree models (<classname>TreeStore</classname> and <classname>ListStore</classname>) derive from
<classname>TreeSortable</classname>, so they offer sorting functionality. For instance, call
<methodname>set_sort_column()</methodname>, to sort the model by the specified column. Or supply a callback
function to <methodname>set_sort_func()</methodname> to implement a more complicated sorting algorithm.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TreeSortable.html">TreeSortable Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TreeSortable.html">TreeSortable Reference</link></para>
-<sect2 id="treeview-sort-headers">
+<section xml:id="treeview-sort-headers">
<title>Sorting by clicking on columns</title>
+
<para>
So that a user can click on a <classname>TreeView</classname>'s column header to sort the
<classname>TreeView</classname>'s contents, call
<methodname>Gtk::TreeView::Column::set_sort_column()</methodname>, supplying the model column on which model
should be sorted when the header is clicked. For instance:
</para>
<programlisting>auto pColumn = treeview.get_column(0);
if(pColumn)
- pColumn->set_sort_column(m_columns.m_col_id);</programlisting>
-</sect2>
+ pColumn->set_sort_column(m_columns.m_col_id);</programlisting>
+</section>
-<sect2 id="treeview-sort-independent-views">
+<section xml:id="treeview-sort-independent-views">
<title>Independently sorted views of the same model</title>
+
<para>
The <classname>TreeView</classname> already allows you to show the same <classname>TreeModel</classname>
in two <classname>TreeView</classname> widgets. If you need one of these TreeViews to sort the model
@@ -2764,7 +2794,7 @@ for instance, <methodname>Gtk::TreeViewColumn::set_sort_column()</methodname>.
of that model. For instance, you might add a sorted version of a model to a <classname>TreeView</classname>
like so:
</para>
<programlisting>auto sorted_model = Gtk::TreeModelSort::create(model);
-sorted_model->set_sort_column(columns.m_col_name, Gtk::SORT_ASCENDING);
+sorted_model->set_sort_column(columns.m_col_name, Gtk::SORT_ASCENDING);
treeview.set_model(sorted_model);</programlisting>
<para>Note, however, that the TreeView will provide iterators to the sorted model. You must convert them to
iterators to the underlying child model in order to perform actions on that model. For instance:
@@ -2774,22 +2804,23 @@ treeview.set_model(sorted_model);</programlisting>
auto refTreeSelection = m_treeview.get_selection();
if(refTreeSelection)
{
- auto sorted_iter = m_refTreeSelection->get_selected();
+ auto sorted_iter = m_refTreeSelection->get_selected();
if(sorted_iter)
{
- auto iter = m_refModelSort->convert_iter_to_child_iter(sorted_iter);
- m_refModel->erase(iter);
+ auto iter = m_refModelSort->convert_iter_to_child_iter(sorted_iter);
+ m_refModel->erase(iter);
}
}
}</programlisting>
-<para><ulink url="&url_refdocs_base_gtk;TreeModelSort.html">TreeModelSort Reference</ulink></para>
-</sect2>
+<para><link xlink:href="&url_refdocs_base_gtk;TreeModelSort.html">TreeModelSort Reference</link></para>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-treeview-draganddrop">
+<section xml:id="sec-treeview-draganddrop">
<title>Drag and Drop</title>
+
<para>
<classname>Gtk::TreeView</classname> already implements simple drag-and-drop
when used with the <classname>Gtk::ListStore</classname> or
@@ -2798,8 +2829,9 @@ to implement more complex behaviour when items are dragged and dropped, using
the normal <link linkend="chapter-draganddrop">Drag and Drop</link> API.
</para>
-<sect2 id="treeview-reorderable-rows">
+<section xml:id="treeview-reorderable-rows">
<title>Reorderable rows</title>
+
<para>
If you call <methodname>Gtk::TreeView::set_reorderable()</methodname> then your
TreeView's items can be moved within the treeview itself. This is demonstrated
@@ -2813,12 +2845,13 @@ If you need that extra control then you might create a derived <literal>Gtk::Tre
You can examine the <literal>Gtk::TreeModel::Path</literal>s provided and allow or disallow dragging
or dropping by returning <literal>true</literal> or <literal>false</literal>.</para>
<para>This is demonstrated in the drag_and_drop example.</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-treeview-contextmenu">
+<section xml:id="sec-treeview-contextmenu">
<title>Popup Context Menu</title>
+
<para>
Lots of people need to implement right-click context menus for
<classname>TreeView</classname>'s so we will explain how to do that here to
@@ -2827,8 +2860,9 @@ normal context menu, as described in the <link linkend="sec-menus-popup">menus
chapter</link>.
</para>
-<sect2 id="treeview-button-press-event">
+<section xml:id="treeview-button-press-event">
<title>Handling <literal>button_press_event</literal></title>
+
<para>
To detect a click of the right mouse button, you need to handle the
<literal>button_press_event</literal> signal, and check exactly which button
@@ -2840,40 +2874,43 @@ You probably also want to call the default handler before doing anything else,
so that the right-click will cause the row to be selected first.
</para>
<para>This is demonstrated in the Popup Context Menu example.</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-treeview-examples"><title>Examples</title>
+<section xml:id="sec-treeview-examples">
+<title>Examples</title>
<para>Some <classname>TreeView</classname> examples are shown here. There are
-more examples in the <ulink url="&url_examples_base;treeview/">treeview directory</ulink>
+more examples in the <link xlink:href="&url_examples_base;treeview/">treeview directory</link>
in <application>gtkmm-documentation</application>'s examples.</para>
<para>If neither <classname>ListStore</classname> nor <classname>TreeStore</classname>
is suitable for your application, look at the
-<ulink url="&url_examples_base;treeview/custom_treemodel">custom TreeModel</ulink>
+<link xlink:href="&url_examples_base;treeview/custom_treemodel">custom TreeModel</link>
example. It shows how you can make your own implementation of the <classname>TreeModel</classname>
interface.</para>
-<sect2 id="liststore-example"><title>ListStore</title>
+<section xml:id="liststore-example">
+<title>ListStore</title>
<para>
This example has a <classname>Gtk::TreeView</classname> widget, with a
<classname>Gtk::ListStore</classname> model.
</para>
-<figure id="figure-treeview-liststore">
+<figure xml:id="figure-treeview-liststore">
<title>TreeView - ListStore</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_list.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_list.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;treeview/list/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;treeview/list/">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="treestore-example"><title>TreeStore</title>
+<section xml:id="treestore-example">
+<title>TreeStore</title>
<para>
This example is very similar to the <classname>ListStore</classname> example,
@@ -2881,18 +2918,19 @@ but uses a <classname>Gtk::TreeStore</classname> model instead, and adds
children to the rows.
</para>
-<figure id="figure-treeview-treestore">
+<figure xml:id="figure-treeview-treestore">
<title>TreeView - TreeStore</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_tree.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_tree.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;treeview/tree/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;treeview/tree/">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="sec-editable-cells-example"><title>Editable Cells</title>
+<section xml:id="sec-editable-cells-example">
+<title>Editable Cells</title>
<para>
This example is identical to the <classname>ListStore</classname> example, but
@@ -2900,18 +2938,19 @@ it uses <methodname>TreeView::append_column_editable()</methodname> instead of
<methodname>TreeView::append_column()</methodname>.
</para>
-<figure id="figure-treeview-editablecells">
+<figure xml:id="figure-treeview-editablecells">
<title>TreeView - Editable Cells</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_editablecells.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_editablecells.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;treeview/editable_cells/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;treeview/editable_cells/">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="treeview-dnd-example"><title>Drag and Drop</title>
+<section xml:id="treeview-dnd-example">
+<title>Drag and Drop</title>
<para>
This example is much like the <classname>TreeStore</classname> example, but has
@@ -2922,42 +2961,42 @@ described in the <link linkend="sec-treeview-draganddrop">TreeView Drag and
Drop</link> section.
</para>
-<figure id="figure-treeview-draganddrop">
+<figure xml:id="figure-treeview-draganddrop">
<title>TreeView - Drag And Drop</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_draganddrop.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_draganddrop.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;treeview/drag_and_drop/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;treeview/drag_and_drop/">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="treeview-popup-menu-example"><title>Popup Context Menu</title>
+<section xml:id="treeview-popup-menu-example">
+<title>Popup Context Menu</title>
<para>
This example is much like the <classname>ListStore</classname> example, but
derives a custom <classname>TreeView</classname> in order to override the
<literal>button_press_event</literal>, and also to encapsulate the tree model
-code in our derived class. See the <link
- linkend="sec-treeview-contextmenu">TreeView Popup Context Menu</link>
+code in our derived class. See the <link linkend="sec-treeview-contextmenu">TreeView Popup Context
Menu</link>
section.
</para>
-<figure id="figure-treeview-popup">
+<figure xml:id="figure-treeview-popup">
<title>TreeView - Popup Context Menu</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;treeview_popup.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;treeview_popup.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;treeview/popup/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;treeview/popup/">Source Code</link></para>
-</sect2>
-</sect1>
+</section>
+</section>
</chapter>
-<chapter id="chapter-combobox">
+<chapter xml:id="chapter-combobox">
<title>Combo Boxes</title>
<para>The <classname>ComboBox</classname> widget offers a list (or tree) of choices in a dropdown menu. If
appropriate, it can show extra information about each item, such as text, a picture, a check button, or a
progress bar. The <classname>ComboBox</classname> widget usually restricts the user to the available choices,
but it can optionally have an <classname>Entry</classname>, allowing the user to enter arbitrary text if none
of the available choices are suitable.
@@ -2966,10 +3005,11 @@ section.
<para>The list is provided via a <classname>TreeModel</classname>, and columns from this model are added to
the ComboBox's view with the <methodname>ComboBox::pack_start()</methodname> method. This provides
flexibility and compile-time type-safety, but the <classname>ComboBoxText</classname> class provides a
simpler text-based specialization in case that flexibility is not required.
</para>
-<para><ulink url="&url_refdocs_base_gtk;ComboBox.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;ComboBox.html">Reference</link></para>
-<sect1 id="sec-combobox-model">
+<section xml:id="sec-combobox-model">
<title>The model</title>
+
<para>The model for a ComboBox can be defined and filled exactly as for a <classname>TreeView</classname>.
For instance, you might derive a ComboBox class with one integer and one text column, like so:
</para>
<programlisting>class ModelColumns : public Gtk::TreeModel::ColumnRecord
@@ -2985,10 +3025,11 @@ public:
ModelColumns m_columns;</programlisting>
<para>After appending rows to this model, you should provide the model to the
<classname>ComboBox</classname> with the <methodname>set_model()</methodname> method. Then use the
<methodname>pack_start()</methodname> or <methodname>pack_end()</methodname> methods to specify what columns
will be displayed in the ComboBox. As with the TreeView you may either use the default cell renderer by
passing the <classname>TreeModelColumn</classname> to the pack methods, or you may instantiate a specific
<classname>CellRenderer</classname> and specify a particular mapping with either
<methodname>add_attribute()</methodname> or <methodname>set_cell_data_func()</methodname>. Note that these
methods are in the <classname>CellLayout</classname> base class.</para>
-</sect1>
+</section>
-<sect1 id="sec-combobox-get">
+<section xml:id="sec-combobox-get">
<title>The chosen item</title>
+
<para>To discover what item, if any, the user has chosen from the ComboBox, call
<methodname>ComboBox::get_active()</methodname>. This returns a <classname>TreeModel::iterator</classname>
that you can dereference to a <classname>Row</classname> in order to read the values in your columns. For
instance, you might read an integer ID value from the model, even though you have chosen only to show the
human-readable description in the ComboBox. For instance:
</para>
<programlisting>Gtk::TreeModel::iterator iter = m_Combo.get_active();
@@ -3003,66 +3044,72 @@ if(iter)
}
else
set_nothing_chosen(); //Your own function.</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-combobox-changes">
+<section xml:id="sec-combobox-changes">
<title>Responding to changes</title>
+
<para>
You might need to react to every change of selection in the ComboBox, for instance to update other widgets.
To do so, you should handle the <literal>changed</literal> signal. For instance:
</para>
<programlisting>m_combo.signal_changed().connect( sigc::mem_fun(*this,
&ExampleWindow::on_combo_changed) );</programlisting>
-</sect1>
+</section>
-<sect1 id="combobox-example-full"><title>Full Example</title>
+<section xml:id="combobox-example-full">
+<title>Full Example</title>
-<figure id="figure-combobox-complex">
+<figure xml:id="figure-combobox-complex">
<title>ComboBox</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;combobox_complex.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;combobox_complex.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;combobox/complex">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;combobox/complex">Source Code</link></para>
-</sect1>
+</section>
-<sect1 id="combobox-example-simple"><title>Simple Text Example</title>
+<section xml:id="combobox-example-simple">
+<title>Simple Text Example</title>
-<figure id="figure-combobox-text">
+<figure xml:id="figure-combobox-text">
<title>ComboBoxText</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;combobox_text.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;combobox_text.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;combobox/text">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;combobox/text">Source Code</link></para>
-</sect1>
+</section>
-<sect1 id="sec-comboboxentry">
+<section xml:id="sec-comboboxentry">
<title>ComboBox with an Entry</title>
<para>A <classname>ComboBox</classname> may contain an <classname>Entry</classname> widget for entering of
arbitrary text, by specifying <literal>true</literal> for the constructor's <literal>has_entry</literal>
parameter.</para>
-<sect2 id="sec-comboboxentry-text-column">
+<section xml:id="sec-comboboxentry-text-column">
<title>The text column</title>
+
<para>So that the <classname>Entry</classname> can interact with the drop-down list of choices, you must
specify which of your model columns is the text column, with
<methodname>set_entry_text_column()</methodname>. For instance:
</para>
<programlisting>m_combo.set_entry_text_column(m_columns.m_col_name);</programlisting>
<para>
When you select a choice from the drop-down menu, the value from this column will be placed in the
<classname>Entry</classname>.
</para>
-</sect2>
+</section>
-<sect2 id="sec-comboboxentry-model">
+<section xml:id="sec-comboboxentry-model">
<title>The entry</title>
+
<para>Because the user may enter arbitrary text, an active model row isn't enough to tell us what text the
user has entered. Therefore, you should retrieve the <classname>Entry</classname> widget with the
<methodname>ComboBox::get_entry()</methodname> method and call <methodname>get_text()</methodname> on that.
</para>
-</sect2>
+</section>
-<sect2 id="sec-comboboxentry-changes">
+<section xml:id="sec-comboboxentry-changes">
<title>Responding to changes</title>
+
<para>
When the user enters arbitrary text, it may not be enough to connect to the
<literal>changed</literal> signal, which is emitted for every typed character.
@@ -3075,13 +3122,13 @@ entering text. To be notified of these events, connect to the
if (entry)
{
// Alternatively you can connect to m_Combo.signal_changed().
- entry->signal_changed().connect(sigc::mem_fun(*this,
+ entry->signal_changed().connect(sigc::mem_fun(*this,
&ExampleWindow::on_entry_changed) );
- entry->signal_activate().connect(sigc::mem_fun(*this,
+ entry->signal_activate().connect(sigc::mem_fun(*this,
&ExampleWindow::on_entry_activate) );
- entry->signal_focus_out_event().connect(sigc::mem_fun(*this,
+ entry->signal_focus_out_event().connect(sigc::mem_fun(*this,
&ExampleWindow::on_entry_focus_out_event) );
}</programlisting>
The <literal>changed</literal> signals of <classname>ComboBox</classname> and
@@ -3093,44 +3140,42 @@ which one you connect to. But only <classname>Entry</classname>'s
X events are described in more detail in the
<link linkend="sec-xeventsignals">X Event signals</link> section in the appendix.
</para>
-</sect2>
+</section>
-<sect2 id="comboboxentry-example-full"><title>Full Example</title>
+<section xml:id="comboboxentry-example-full">
+<title>Full Example</title>
-<figure id="figure-comboboxentry-complex">
+<figure xml:id="figure-comboboxentry-complex">
<title>ComboBox with Entry</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;comboboxentry_complex.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;comboboxentry_complex.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;combobox/entry_complex">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;combobox/entry_complex">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="comboboxentry-example-simple"><title>Simple Text Example</title>
+<section xml:id="comboboxentry-example-simple">
+<title>Simple Text Example</title>
-<figure id="figure-comboboxentry-text">
+<figure xml:id="figure-comboboxentry-text">
<title>ComboBoxText with Entry</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;comboboxentry_text.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;comboboxentry_text.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;combobox/entry_text">Source Code</ulink></para>
-
-</sect2>
-
+<para><link xlink:href="&url_examples_base;combobox/entry_text">Source Code</link></para>
-
-
-</sect1>
+</section>
+</section>
</chapter>
-
-<chapter id="chapter-textview">
+<chapter xml:id="chapter-textview">
<title>TextView</title>
+
<para>
The <classname>TextView</classname> widget can be used to display and edit
large amounts of formatted text. Like the <classname>TreeView</classname>, it
@@ -3138,8 +3183,9 @@ has a model/view design. In this case the <classname>TextBuffer</classname> is
the model.
</para>
-<sect1 id="sec-textview-buffer">
+<section xml:id="sec-textview-buffer">
<title>The Buffer</title>
+
<para>
<classname>Gtk::TextBuffer</classname> is a model containing the data for the
<classname>Gtk::TextView</classname>, like the
@@ -3156,10 +3202,11 @@ The <classname>TextView</classname> creates its own default
<methodname>get_buffer()</methodname> method.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TextBuffer.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TextBuffer.html">Reference</link></para>
-<sect2 id="textview-iterators">
+<section xml:id="textview-iterators">
<title>Iterators</title>
+
<para>
A <classname>Gtk::TextBuffer::iterator</classname> and a
<classname>Gtk::TextBuffer::const_iterator</classname>
represent a position between two characters in the text buffer. Whenever the buffer
@@ -3167,14 +3214,15 @@ is modified in a way that affects the number of characters in the buffer, all ou
iterators become invalid. Because of this, iterators can't be used to preserve positions
across buffer modifications. To preserve a position, use <classname>Gtk::TextBuffer::Mark</classname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TextIter.html">Reference</ulink></para>
-</sect2>
+<para><link xlink:href="&url_refdocs_base_gtk;TextIter.html">Reference</link></para>
+</section>
-<sect2 id="textview-formatting">
+<section xml:id="textview-formatting">
<title>Tags and Formatting</title>
-<sect3 id="textview-formatting-tags">
+<section xml:id="textview-formatting-tags">
<title>Tags</title>
+
<para>
To specify that some text in the buffer should have specific formatting, you must define a tag to hold that
formatting information, and then apply that tag to the region of text. For instance, to define the tag and
its properties:
</para>
@@ -3189,11 +3237,11 @@ You can specify a name for the <classname>Tag</classname> when using the
The <classname>Tag</classname> class has many other properties.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TextTag.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TextTag.html">Reference</link></para>
-</sect3>
+</section>
-<sect3 id="textview-formatting-tagtable">
+<section xml:id="textview-formatting-tagtable">
<title>TagTable</title>
<para>
@@ -3216,12 +3264,13 @@ the <classname>TextBuffer</classname>'s default <classname>TagTable</classname>
instead of creating one explicitly.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TextTagTable.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TextTagTable.html">Reference</link></para>
-</sect3>
+</section>
-<sect3 id="textview-formatting-applying-tags">
+<section xml:id="textview-formatting-applying-tags">
<title>Applying Tags</title>
+
<para>
If you have created a <classname>Tag</classname> and added it to the
<classname>TagTable</classname>, you may apply that tag to part of the
@@ -3243,11 +3292,12 @@ specify different values for the same properties, but you can resolve these
conflicts by using <methodname>Tag::set_priority()</methodname>.
</para>
-</sect3>
-</sect2>
+</section>
+</section>
-<sect2 id="textview-marks">
+<section xml:id="textview-marks">
<title>Marks</title>
+
<para>
<classname>TextBuffer</classname> iterators are generally invalidated when the
text changes, but you can use a <classname>Gtk::TextBuffer::Mark</classname> to
@@ -3267,12 +3317,13 @@ and <literal>selection_bound</literal>, which you can access with
<methodname>get_selection_bound()</methodname> methods.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TextMark.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TextMark.html">Reference</link></para>
-</sect2>
+</section>
-<sect2 id="textview-view">
+<section xml:id="textview-view">
<title>The View</title>
+
<para>
As mentioned above, each <classname>TextView</classname> has a
<classname>TextBuffer</classname>, and one or more
@@ -3287,10 +3338,11 @@ to allow the user to see and move around the whole text area with
scrollbars.
</para>
-<para><ulink url="&url_refdocs_base_gtk;TextView.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TextView.html">Reference</link></para>
-<sect3 id="textview-default-formatting">
+<section xml:id="textview-default-formatting">
<title>Default formatting</title>
+
<para>
<classname>TextView</classname> has various methods which allow you to change
the presentation of the buffer for this particular view. Some of these may be
@@ -3299,10 +3351,11 @@ specify the same things. For instance, <methodname>set_left_margin()</methodname
<methodname>set_right_margin()</methodname>, <methodname>set_indent()</methodname>,
etc.
</para>
-</sect3>
+</section>
-<sect3 id="textview-scrolling">
+<section xml:id="textview-scrolling">
<title>Scrolling</title>
+
<para>
<classname>Gtk::TextView</classname> has various
<methodname>scroll_to()</methodname> methods. These allow you to ensure that a
@@ -3310,15 +3363,16 @@ particular part of the text buffer is visible. For instance, your application's
Find feature might use <methodname>Gtk::TextView::scroll_to()</methodname> to
show the found text.
</para>
-</sect3>
+</section>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-widgets-and-childanchors">
+<section xml:id="sec-widgets-and-childanchors">
<title>Widgets and ChildAnchors</title>
+
<para>
You can embed widgets, such as <classname>Gtk::Button</classname>s, in the
text. Each such child widget needs a <classname>ChildAnchor</classname>.
@@ -3334,30 +3388,30 @@ Then, to add a widget at that position, use
</para>
<programlisting>m_TextView.add_child_at_anchor(m_Button, refAnchor);</programlisting>
-<para><ulink url="&url_refdocs_base_gtk;TextChildAnchor.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;TextChildAnchor.html">Reference</link></para>
-</sect1>
+</section>
-<sect1 id="sec-textview-examples"><title>Examples</title>
+<section xml:id="sec-textview-examples">
+<title>Examples</title>
-<sect2 id="textview-example-simple"><title>Simple Example</title>
+<section xml:id="textview-example-simple">
+<title>Simple Example</title>
-<figure id="figure-textview">
+<figure xml:id="figure-textview">
<title>TextView</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;textview.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;textview.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;textview/">Source Code</ulink></para>
-
-</sect2>
-
-</sect1>
+<para><link xlink:href="&url_examples_base;textview/">Source Code</link></para>
+</section>
+</section>
</chapter>
-<chapter id="chapter-menus-and-toolbars">
+<chapter xml:id="chapter-menus-and-toolbars">
<title>Menus and Toolbars</title>
<para>
@@ -3375,8 +3429,9 @@ classes, all of which should be instantiated via their <methodname>create()</met
methods, which return <classname>RefPtr</classname>s.
</para>
-<sect1 id="sec-actions">
+<section xml:id="sec-actions">
<title>Actions</title>
+
<para>
First create the <classname>Gio::SimpleAction</classname>s and add them to a
<classname>Gio::SimpleActionGroup</classname>, with
@@ -3396,13 +3451,13 @@ a toolbar button.
<para>For instance:
</para>
<programlisting>
-<![CDATA[m_refActionGroup = Gio::SimpleActionGroup::create();
+m_refActionGroup = Gio::SimpleActionGroup::create();
-m_refActionGroup->add_action("new", sigc::mem_fun(*this, &ExampleWindow::on_action_file_new));
-m_refActionGroup->add_action("open", sigc::mem_fun(*this, &ExampleWindow::on_action_file_open));
-m_refActionGroup->add_action("quit", sigc::mem_fun(*this, &ExampleWindow::on_action_file_quit));
+m_refActionGroup->add_action("new", sigc::mem_fun(*this, &ExampleWindow::on_action_file_new));
+m_refActionGroup->add_action("open", sigc::mem_fun(*this, &ExampleWindow::on_action_file_open));
+m_refActionGroup->add_action("quit", sigc::mem_fun(*this, &ExampleWindow::on_action_file_quit));
-insert_action_group("example", m_refActionGroup);]]>
+insert_action_group("example", m_refActionGroup);
</programlisting>
<para>
@@ -3412,11 +3467,12 @@ create your own action group. <classname>Gio::ActionGroup</classname> and
<classname>Gtk::ApplicationWindow</classname>.
</para>
-</sect1>
+</section>
-<sect1 id="sec-menubar-and-toolbar">
+<section xml:id="sec-menubar-and-toolbar">
<title>Menubar and Toolbar</title>
+
<para>
Next you should create a <classname>Gtk::Builder</classname>. At this point is
also a good idea to tell the application to respond to keyboard shortcuts,
@@ -3426,12 +3482,12 @@ by using <methodname>Gtk::Application::set_accel_for_action()</methodname>.
<para>For instance,
</para>
<programlisting>
-<![CDATA[m_refBuilder = Gtk::Builder::create();
+m_refBuilder = Gtk::Builder::create();
-app->set_accel_for_action("example.new", "<Primary>n");
-app->set_accel_for_action("example.quit", "<Primary>q");
-app->set_accel_for_action("example.copy", "<Primary>c");
-app->set_accel_for_action("example.paste", "<Primary>v");]]>
+app->set_accel_for_action("example.new", "<Primary>n");
+app->set_accel_for_action("example.quit", "<Primary>q");
+app->set_accel_for_action("example.copy", "<Primary>c");
+app->set_accel_for_action("example.paste", "<Primary>v");
</programlisting>
<para>
If your main window is derived from <classname>ApplicationWindow</classname> and
@@ -3443,49 +3499,49 @@ for an example.
<para>
Then, you can define the actual visible layout of the menus and toolbars, and
-add the UI layout to the <classname>Builder</classname>. This "ui
-string" uses an XML format, in which you should mention the names of the
+add the UI layout to the <classname>Builder</classname>. This "ui
+string" uses an XML format, in which you should mention the names of the
actions that you have already created. For instance:
</para>
<programlisting>
-<![CDATA[Glib::ustring ui_info =
- "<interface>"
- " <menu id='menubar'>"
- " <submenu>"
- " <attribute name='label' translatable='yes'>_File</attribute>"
- " <section>"
- " <item>"
- " <attribute name='label' translatable='yes'>_New</attribute>"
- " <attribute name='action'>example.new</attribute>"
- " <attribute name='accel'><Primary>n</attribute>"
- " </item>"
- " </section>"
- " <section>"
- " <item>"
- " <attribute name='label' translatable='yes'>_Quit</attribute>"
- " <attribute name='action'>example.quit</attribute>"
- " <attribute name='accel'><Primary>q</attribute>"
- " </item>"
- " </section>"
- " </submenu>"
- " <submenu>"
- " <attribute name='label' translatable='yes'>_Edit</attribute>"
- " <item>"
- " <attribute name='label' translatable='yes'>_Copy</attribute>"
- " <attribute name='action'>example.copy</attribute>"
- " <attribute name='accel'><Primary>c</attribute>"
- " </item>"
- " <item>"
- " <attribute name='label' translatable='yes'>_Paste</attribute>"
- " <attribute name='action'>example.paste</attribute>"
- " <attribute name='accel'><Primary>v</attribute>"
- " </item>"
- " </submenu>"
- " </menu>"
- "</interface>";
-
-m_refBuilder->add_from_string(ui_info);
-m_refBuilder->add_from_resource("/toolbar/toolbar.glade");]]>
+Glib::ustring ui_info =
+ "<interface>"
+ " <menu id='menubar'>"
+ " <submenu>"
+ " <attribute name='label' translatable='yes'>_File</attribute>"
+ " <section>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>_New</attribute>"
+ " <attribute name='action'>example.new</attribute>"
+ " <attribute name='accel'>&lt;Primary&gt;n</attribute>"
+ " </item>"
+ " </section>"
+ " <section>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>_Quit</attribute>"
+ " <attribute name='action'>example.quit</attribute>"
+ " <attribute name='accel'>&lt;Primary&gt;q</attribute>"
+ " </item>"
+ " </section>"
+ " </submenu>"
+ " <submenu>"
+ " <attribute name='label' translatable='yes'>_Edit</attribute>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>_Copy</attribute>"
+ " <attribute name='action'>example.copy</attribute>"
+ " <attribute name='accel'>&lt;Primary&gt;c</attribute>"
+ " </item>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>_Paste</attribute>"
+ " <attribute name='action'>example.paste</attribute>"
+ " <attribute name='accel'>&lt;Primary&gt;v</attribute>"
+ " </item>"
+ " </submenu>"
+ " </menu>"
+ "</interface>";
+
+m_refBuilder->add_from_string(ui_info);
+m_refBuilder->add_from_resource("/toolbar/toolbar.glade");
</programlisting>
<para>This is where we specify the names of the menu items as they will be seen
@@ -3500,18 +3556,19 @@ the <methodname>Builder::get_object()</methodname> and
to a container. For instance:
</para>
<programlisting>
-<![CDATA[auto gmenu = m_refBuilder->get_object<Gio::Menu>("menubar");
-auto pMenuBar = Gtk::make_managed<Gtk::MenuBar>(gmenu);
+auto gmenu = m_refBuilder->get_object<Gio::Menu>("menubar");
+auto pMenuBar = Gtk::make_managed<Gtk::MenuBar>(gmenu);
m_Box.append(*pMenuBar);
-auto toolbar = m_refBuilder->get_widget<Gtk::Toolbar>("toolbar");
-m_Box.append(*toolbar);]]>
+auto toolbar = m_refBuilder->get_widget<Gtk::Toolbar>("toolbar");
+m_Box.append(*toolbar);
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-menus-popup"><title>Popup Menus</title>
+<section xml:id="sec-menus-popup">
+<title>Popup Menus</title>
<para>
<classname>Menus</classname> are normally just added to a window, but they can
also be displayed temporarily as the result of a mouse button click. For
@@ -3522,30 +3579,30 @@ mouse button.
<para>For instance:
</para>
<programlisting>
-<![CDATA[Glib::ustring ui_info =
- "<interface>"
- " <menu id='menu-examplepopup'>"
- " <section>"
- " <item>"
- " <attribute name='label' translatable='yes'>Edit</attribute>"
- " <attribute name='action'>examplepopup.edit</attribute>"
- " </item>"
- " <item>"
- " <attribute name='label' translatable='yes'>Process</attribute>"
- " <attribute name='action'>examplepopup.process</attribute>"
- " </item>"
- " <item>"
- " <attribute name='label' translatable='yes'>Remove</attribute>"
- " <attribute name='action'>examplepopup.remove</attribute>"
- " </item>"
- " </section>"
- " </menu>"
- "</interface>";
+Glib::ustring ui_info =
+ "<interface>"
+ " <menu id='menu-examplepopup'>"
+ " <section>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>Edit</attribute>"
+ " <attribute name='action'>examplepopup.edit</attribute>"
+ " </item>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>Process</attribute>"
+ " <attribute name='action'>examplepopup.process</attribute>"
+ " </item>"
+ " <item>"
+ " <attribute name='label' translatable='yes'>Remove</attribute>"
+ " <attribute name='action'>examplepopup.remove</attribute>"
+ " </item>"
+ " </section>"
+ " </menu>"
+ "</interface>";
-m_refBuilder->add_from_string(ui_info);
+m_refBuilder->add_from_string(ui_info);
-auto gmenu = m_refBuilder->get_object<Gio::Menu>("menu-examplepopup");
-m_pMenuPopup = std::make_unique<Gtk::Menu>(gmenu);]]>
+auto gmenu = m_refBuilder->get_object<Gio::Menu>("menu-examplepopup");
+m_pMenuPopup = std::make_unique<Gtk::Menu>(gmenu);
</programlisting>
<para>
@@ -3555,32 +3612,32 @@ time of activation, as provided by the <literal>button_press_event</literal>
signal, which you will need to handle anyway. For instance:
</para>
<programlisting>
-<![CDATA[bool ExampleWindow::on_button_press_event(GdkEventButton* event)
+bool ExampleWindow::on_button_press_event(GdkEventButton* event)
{
- if( (event->type == GDK_BUTTON_PRESS) && (event->button == 3) )
+ if( (event->type == GDK_BUTTON_PRESS) && (event->button == 3) )
{
- if(!m_pMenuPopup->get_attach_widget())
- m_pMenuPopup->attach_to_widget(*this);
+ if(!m_pMenuPopup->get_attach_widget())
+ m_pMenuPopup->attach_to_widget(*this);
- m_pMenuPopup->popup(event->button, event->time);
+ m_pMenuPopup->popup(event->button, event->time);
return true; //It has been handled.
}
else
return false;
-}]]>
+}
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-gio-resource">
+<section xml:id="sec-gio-resource">
<title>Gio::Resource and glib-compile-resources</title>
<para>
Applications and libraries often contain binary or textual data that is
really part of the application, rather than user data. For instance
-<classname>Gtk::Builder</classname> <filename class='extension'>.glade</filename> files,
+<classname>Gtk::Builder</classname> <filename class="extension">.glade</filename> files,
splashscreen images, <classname>Gio::Menu</classname> markup xml, CSS files,
-icons, etc. These are often shipped as files in <filename class='directory'>$datadir/appname</filename>,
+icons, etc. These are often shipped as files in <filename class="directory">$datadir/appname</filename>,
or manually included as literal strings in the code.
</para>
<para>
@@ -3593,22 +3650,21 @@ simple (no need to check for things like I/O errors or locate the files in the f
also makes it easier to create relocatable applications.
</para>
<para>
-Resource bundles are created by the <ulink
-url="https://developer.gnome.org/gio/stable/glib-compile-resources.html";>glib-compile-resources</ulink>
+Resource bundles are created by the <link
xlink:href="https://developer.gnome.org/gio/stable/glib-compile-resources.html";>glib-compile-resources</link>
program which takes an xml file that describes the bundle, and a set of files that the xml references.
These are combined into a binary resource bundle.
</para>
-<para><ulink url="&url_refdocs_base_gio;Resource.html">Gio::Resource Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gio;Resource.html">Gio::Resource Reference</link></para>
<para>
An example:
<programlisting>
-<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<gresources>
- <gresource prefix="/toolbar">
- <file preprocess="xml-stripblanks">toolbar.glade</file>
- <file>rain.png</file>
- </gresource>
-</gresources>]]>
+<?xml version="1.0" encoding="UTF-8"?>
+<gresources>
+ <gresource prefix="/toolbar">
+ <file preprocess="xml-stripblanks">toolbar.glade</file>
+ <file>rain.png</file>
+ </gresource>
+</gresources>
</programlisting>
This will create a resource bundle with the files
<itemizedlist>
@@ -3619,7 +3675,7 @@ This will create a resource bundle with the files
<para>
You can then use <application>glib-compile-resources</application> to compile the xml to a binary bundle
that you can load with <methodname>Gio::Resource::create_from_file()</methodname>.
-However, it's more common to use the <parameter class='command'>--generate-source</parameter>
+However, it's more common to use the <parameter class="command">--generate-source</parameter>
argument to create a C source file to link directly into your application. E.g.
<screen>$ glib-compile-resources --target=resources.c --generate-source toolbar.gresource.xml</screen>
</para>
@@ -3639,64 +3695,65 @@ because resource data can be loaded with methods such as
<methodname>Gtk::Image::set_from_resource()</methodname>.
</para>
-</sect1>
+</section>
-<sect1 id="sec-menus-examples">
- <title>Examples</title>
+<section xml:id="sec-menus-examples">
+<title>Examples</title>
-<sect2 id="menu-example-main"><title>Application Menu and Main Menu example</title>
+<section xml:id="menu-example-main">
+<title>Application Menu and Main Menu example</title>
<para>
This program contains an application menu, a menubar and a toolbar.
Classes are derived from <classname>Gtk::Application</classname> and
<classname>Gtk::ApplicationWindow</classname>.
</para>
-<figure id="figure-menus-mainmenu">
+<figure xml:id="figure-menus-mainmenu">
<title>App and Main Menu</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;main_menu.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;main_menu.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;menus/main_menu/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;menus/main_menu/">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="menu-example-main2"><title>Main Menu example</title>
+<section xml:id="menu-example-main2">
+<title>Main Menu example</title>
<para>
This program contains a menubar and a toolbar.
A class is derived from <classname>Gtk::Window</classname>.
</para>
-<figure id="figure-menus-mainmenu2">
+<figure xml:id="figure-menus-mainmenu2">
<title>Main Menu</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;menus_and_toolbars.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;menus_and_toolbars.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;menus_and_toolbars">Source Code</ulink></para> <!-- Insert
toolbar.gresource.xml -->
+<para><link xlink:href="&url_examples_base;menus_and_toolbars">Source Code</link></para> <!-- Insert
toolbar.gresource.xml -->
-</sect2>
+</section>
-<sect2 id="menu-example-popup"><title>Popup Menu example</title>
+<section xml:id="menu-example-popup">
+<title>Popup Menu example</title>
-<figure id="figure-menus-popup">
+<figure xml:id="figure-menus-popup">
<title>Popup Menu</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;menu_popup.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;menu_popup.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;menus/popup/">Source Code</ulink></para>
-
-</sect2>
-
-</sect1>
+<para><link xlink:href="&url_examples_base;menus/popup/">Source Code</link></para>
+</section>
+</section>
</chapter>
-<chapter id="chapter-adjustment">
+<chapter xml:id="chapter-adjustment">
<title>Adjustments</title>
<para>
@@ -3716,7 +3773,7 @@ scrollbar, <classname>Gtk::Adjustment</classname> has a
<methodname>get_value()</methodname> method to discover the new value.
</para>
-<sect1 id="sec-creating-adjustment">
+<section xml:id="sec-creating-adjustment">
<title>Creating an Adjustment</title>
<para>
@@ -3748,9 +3805,9 @@ widget's child.
<!-- TODO: Investigate the upper argument properly. There was some unclear stuff about it not always being
the upper value. -->
</para>
-</sect1>
+</section>
-<sect1 id="sec-adjustments-easy">
+<section xml:id="sec-adjustments-easy">
<title>Using Adjustments the Easy Way</title>
<para>
@@ -3789,9 +3846,9 @@ Gtk::TextView textview;
// uses the newly-created adjustment for the scrollbar as well
Gtk::Scrollbar vscrollbar (textview.get_vadjustment(), Gtk::ORIENTATION_VERTICAL);</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-adjustment-internals">
+<section xml:id="sec-adjustment-internals">
<title>Adjustment Internals</title>
<para>
@@ -3818,12 +3875,12 @@ create a signal handler like this:
</para>
<programlisting>void cb_rotate_picture (MyPicture* picture)
{
- picture->set_rotation(adj->get_value());
+ picture->set_rotation(adj->get_value());
...</programlisting>
<para>
and connect it to the scale widget's adjustment like this:
</para>
-<programlisting>adj->signal_value_changed().connect(sigc::bind<MyPicture*>(sigc::mem_fun(*this,
+<programlisting>adj->signal_value_changed().connect(sigc::bind<MyPicture*>(sigc::mem_fun(*this,
&cb_rotate_picture), picture));</programlisting>
<para>
@@ -3846,13 +3903,13 @@ the difference between the <parameter>lower</parameter> and
You probably won't ever need to attach a handler to this signal, unless you're
writing a new type of range widget.
</para>
-<programlisting>adjustment->signal_changed();</programlisting>
+<programlisting>adjustment->signal_changed();</programlisting>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-dialogs">
+<chapter xml:id="chapter-dialogs">
<title>Dialogs</title>
<para>
@@ -3884,9 +3941,10 @@ closed the dialog by clicking a standard button, or it could be the custom
response value that you specified when using <methodname>add_button()</methodname>.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Dialog.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Dialog.html">Reference</link></para>
-<sect1 id="sec-dialogs-messagedialog"><title>MessageDialog</title>
+<section xml:id="sec-dialogs-messagedialog">
+<title>MessageDialog</title>
<para>
<classname>MessageDialog</classname> is a convenience class, used to create
simple, standard message dialogs, with a message, an icon, and buttons for user
@@ -3895,98 +3953,102 @@ as well as specifying standard buttons via the
<literal>Gtk::ButtonsType</literal> enum.
</para>
-<para><ulink url="&url_refdocs_base_gtk;MessageDialog.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;MessageDialog.html">Reference</link></para>
-<sect2 id="messagedialog-example">
+<section xml:id="messagedialog-example">
<title>Example</title>
-<figure id="figure-dialogs-messagedialog">
+<figure xml:id="figure-dialogs-messagedialog">
<title>MessageDialog</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;dialogs_messagedialog.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;dialogs_messagedialog.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;dialogs/messagedialog">Source Code</ulink></para>
-</sect2>
+<para><link xlink:href="&url_examples_base;dialogs/messagedialog">Source Code</link></para>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-dialogs-filechooserdialog"><title>FileChooserDialog</title>
+<section xml:id="sec-dialogs-filechooserdialog">
+<title>FileChooserDialog</title>
<para>
The <classname>FileChooserDialog</classname> is suitable for use with
-"Open" or "Save" menu items.
+"Open" or "Save" menu items.
</para>
<para>
Most of the useful member methods for this class are actually in the
<classname>Gtk::FileChooser</classname> base class.
</para>
-<para><ulink url="&url_refdocs_base_gtk;FileChooserDialog.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;FileChooserDialog.html">Reference</link></para>
-<sect2 id="filechooserdialog-example">
+<section xml:id="filechooserdialog-example">
<title>Example</title>
-<figure id="figure-dialogs-filechooser">
+<figure xml:id="figure-dialogs-filechooser">
<title>FileChooser</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;dialogs_filechooser.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;dialogs_filechooser.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;dialogs/filechooserdialog">Source Code</ulink></para>
-</sect2>
-</sect1>
+<para><link xlink:href="&url_examples_base;dialogs/filechooserdialog">Source Code</link></para>
+</section>
+</section>
-<sect1 id="sec-color-selection-dialog"><title>ColorChooserDialog</title>
+<section xml:id="sec-color-selection-dialog">
+<title>ColorChooserDialog</title>
<para>
The <classname>ColorChooserDialog</classname> allows the user to choose a
color. The <classname>ColorButton</classname> opens a color selection dialog
when it is clicked.
</para>
-<para><ulink url="&url_refdocs_base_gtk;ColorChooserDialog.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;ColorChooserDialog.html">Reference</link></para>
-<sect2 id="colorchooserdialog-example">
+<section xml:id="colorchooserdialog-example">
<title>Example</title>
-<figure id="figure-dialogs-colorchooserdialog">
+<figure xml:id="figure-dialogs-colorchooserdialog">
<title>ColorChooserDialog</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;dialogs_colorchooserdialog.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;dialogs_colorchooserdialog.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;dialogs/colorchooserdialog">Source Code</ulink></para>
-</sect2>
+<para><link xlink:href="&url_examples_base;dialogs/colorchooserdialog">Source Code</link></para>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-font-chooser-dialog"><title>FontChooserDialog</title>
+<section xml:id="sec-font-chooser-dialog">
+<title>FontChooserDialog</title>
<para>
The <classname>FontChooserDialog</classname> allows the user to choose a
font. The <classname>FontButton</classname> opens a font chooser dialog
when it is clicked.
</para>
-<para><ulink url="&url_refdocs_base_gtk;FontChooserDialog.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;FontChooserDialog.html">Reference</link></para>
-<sect2 id="fontchooserdialog-example">
+<section xml:id="fontchooserdialog-example">
<title>Example</title>
-<figure id="figure-dialogs-fontchooserdialog">
+<figure xml:id="figure-dialogs-fontchooserdialog">
<title>FontChooserDialog</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;dialogs_fontchooserdialog.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;dialogs_fontchooserdialog.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;dialogs/fontchooserdialog">Source Code</ulink></para>
-</sect2>
+<para><link xlink:href="&url_examples_base;dialogs/fontchooserdialog">Source Code</link></para>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-about-dialog"><title>Non-modal AboutDialog</title>
+<section xml:id="sec-about-dialog">
+<title>Non-modal AboutDialog</title>
<para>
The <classname>AboutDialog</classname> offers a simple way to display information
about a program, like its logo, name, copyright, website and license.
@@ -4001,27 +4063,27 @@ dialogs can be useful in other cases. E.g. <application>gedit</application>'s
search-and-replace dialog is non-modal.
</para>
-<para><ulink url="&url_refdocs_base_gtk;AboutDialog.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;AboutDialog.html">Reference</link></para>
-<sect2 id="aboutdialog-example">
+<section xml:id="aboutdialog-example">
<title>Example</title>
-<figure id="figure-dialogs-about">
+<figure xml:id="figure-dialogs-about">
<title>AboutDialog</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;dialogs_about.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;dialogs_about.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;dialogs/aboutdialog">Source Code</ulink></para> <!-- Insert
aboutdialog.gresource.xml -->
-</sect2>
+<para><link xlink:href="&url_examples_base;dialogs/aboutdialog">Source Code</link></para> <!-- Insert
aboutdialog.gresource.xml -->
+</section>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-drawingarea">
- <title>The DrawingArea Widget</title>
+<chapter xml:id="chapter-drawingarea">
+<title>The DrawingArea Widget</title>
<para>
The <classname>DrawingArea</classname> widget is a blank window that gives
you the freedom to create any graphic you desire. Along with that freedom
@@ -4035,8 +4097,8 @@ search-and-replace dialog is non-modal.
</para>
<para>
- GTK uses the <ulink url="http://cairographics.org";>Cairo</ulink> drawing API.
- With >kmm;, you may use the <ulink url="http://www.cairographics.org/cairomm/";>cairomm</ulink> C++
API for cairo.
+ GTK uses the <link xlink:href="http://cairographics.org";>Cairo</link> drawing API.
+ With >kmm;, you may use the <link xlink:href="http://www.cairographics.org/cairomm/";>cairomm</link>
C++ API for cairo.
</para>
<para>
@@ -4061,8 +4123,9 @@ search-and-replace dialog is non-modal.
examples), and then present a simple application that uses Cairo to draw
a custom clock widget.
</para>
- <sect1 id="sec-cairo-drawing-model">
- <title>The Cairo Drawing Model</title>
+
+ <section xml:id="sec-cairo-drawing-model">
+ <title>The Cairo Drawing Model</title>
<para>
The basic concept of drawing in Cairo involves defining 'invisible'
paths and then stroking or filling them to make them visible.
@@ -4090,11 +4153,11 @@ search-and-replace dialog is non-modal.
use this context will use these settings.
</para>
<programlisting>
-<![CDATA[Gtk::DrawingArea myArea;
-auto gdkCairoContext = myArea.get_surface()->create_cairo_context();
-auto myContext = gdkCairoContext->cairo_create();
-myContext->set_source_rgb(1.0, 0.0, 0.0);
-myContext->set_line_width(2.0);]]>
+Gtk::DrawingArea myArea;
+auto gdkCairoContext = myArea.get_surface()->create_cairo_context();
+auto myContext = gdkCairoContext->cairo_create();
+myContext->set_source_rgb(1.0, 0.0, 0.0);
+myContext->set_line_width(2.0);
</programlisting>
<para>
Each <classname>Cairo::Context</classname> is associated with a
@@ -4117,7 +4180,7 @@ myContext->set_line_width(2.0);]]>
<methodname>set_font_face()</methodname> and others).
There are many other settings as well, such as transformation matrices,
fill rules, whether to perform antialiasing, and others. For further
- information, see the <ulink url="http://www.cairographics.org/cairomm/";>cairomm</ulink> API
documentation.
+ information, see the <link xlink:href="http://www.cairographics.org/cairomm/";>cairomm</link> API
documentation.
</para>
<para>
The current state of a <classname>Cairo::Context</classname> can be
@@ -4144,10 +4207,10 @@ myContext->set_line_width(2.0);]]>
</para>
<programlisting>void doSomething(const Cairo::RefPtr<Cairo::Context>& context, int x)
{
- context->save();
+ context->save();
// change graphics state
// perform drawing operations
- context->restore();
+ context->restore();
}</programlisting>
</tip>
</para>
@@ -4157,9 +4220,9 @@ myContext->set_line_width(2.0);]]>
<classname>Gtk::DrawingArea</classname> widget. It is not necessary to
save and restore this Cairo context in the draw function.
</para>
- </sect1>
- <sect1 id="sec-cairo-drawing-lines">
- <title>Drawing Straight Lines</title>
+ </section>
+ <section xml:id="sec-cairo-drawing-lines">
+ <title>Drawing Straight Lines</title>
<para>
Now that we understand the basics of the Cairo graphics library, we're
almost ready to start drawing. We'll start with the simplest of
@@ -4182,7 +4245,8 @@ myContext->set_line_width(2.0);]]>
</tip>
</para>
- <sect2 id="cairo-example-lines"><title>Example</title>
+ <section xml:id="cairo-example-lines">
+ <title>Example</title>
<para>
In this example, we'll construct a small but fully functional >kmm;
program and draw some lines into the window. The lines are drawn by
@@ -4213,14 +4277,14 @@ myContext->set_line_width(2.0);]]>
drawing function.</para>
</tip>
- <figure id="figure-drawingarea-lines">
+ <figure xml:id="figure-drawingarea-lines">
<title>Drawing Area - Lines</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;drawingarea_lines.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drawingarea_lines.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;drawingarea/simple">Source Code</ulink></para>
+ <para><link xlink:href="&url_examples_base;drawingarea/simple">Source Code</link></para>
<para>
This program contains a single class, <classname>MyArea</classname>,
@@ -4246,9 +4310,10 @@ myContext->set_line_width(2.0);]]>
relative coordinates. For a straight line, this is done with the
function <methodname>Cairo::Context::rel_line_to()</methodname>.</para>
</tip>
- </sect2>
- <sect2 id="cairo-line-styles">
- <title>Line styles</title>
+ </section>
+
+ <section xml:id="cairo-line-styles">
+ <title>Line styles</title>
<para>
In addition to drawing basic straight lines, there are a number of
things that you can customize about a line. You've already seen
@@ -4261,10 +4326,10 @@ myContext->set_line_width(2.0);]]>
three different ways to join lines together: Miter, Bevel, and
Round. These are show below:
</para>
- <figure id="figure-cairo-joins">
- <title>Different join types in Cairo</title>
+ <figure xml:id="figure-cairo-joins">
+ <title>Different join types in Cairo</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;cairo_joins.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;cairo_joins.png"/></imageobject></mediaobject>
</screenshot>
</figure>
<para>
@@ -4286,9 +4351,10 @@ myContext->set_line_width(2.0);]]>
creating dashed lines and other things. For more information, see
the Cairo API documentation.
</para>
- </sect2>
- <sect2 id="sec-cairo-thin-lines">
- <title>Drawing thin lines</title>
+ </section>
+
+ <section xml:id="sec-cairo-thin-lines">
+ <title>Drawing thin lines</title>
<para>
If you try to draw one pixel wide lines, you may notice that the line
sometimes comes up blurred and wider than it ought to be.
@@ -4302,22 +4368,22 @@ myContext->set_line_width(2.0);]]>
<para>
The trick is to position in the middle of the pixel where you want the
line to be drawn, and thus guaranteeing you get the desired results.
- See <ulink url="http://cairographics.org/FAQ/#sharp_lines";>Cairo FAQ</ulink>.
+ See <link xlink:href="http://cairographics.org/FAQ/#sharp_lines";>Cairo FAQ</link>.
</para>
- <figure id="figure-drawingarea-thin-lines">
+ <figure xml:id="figure-drawingarea-thin-lines">
<title>Drawing Area - Thin Lines</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;drawingarea_thin_lines.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drawingarea_thin_lines.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;drawingarea/thin_lines">Source Code</ulink></para>
- </sect2>
- </sect1>
+ <para><link xlink:href="&url_examples_base;drawingarea/thin_lines">Source Code</link></para>
+ </section>
+ </section>
- <sect1 id="sec-cairo-curved-lines">
- <title>Drawing Curved Lines</title>
+ <section xml:id="sec-cairo-curved-lines">
+ <title>Drawing Curved Lines</title>
<para>
In addition to drawing straight lines Cairo allows you to easily
draw curved lines (technically a cubic Bézier spline) using the
@@ -4327,20 +4393,21 @@ myContext->set_line_width(2.0);]]>
coordinates for two 'control' points. This is best explained using
an example, so let's dive in.
</para>
- <sect2 id="cairo-example-curves">
- <title>Example</title>
+
+ <section xml:id="cairo-example-curves">
+ <title>Example</title>
<para>
This simple application draws a curve with Cairo and displays
the control points for each end of the curve.
</para>
- <figure id="figure-drawingarea-curve">
- <title>Drawing Area - Lines</title>
+ <figure xml:id="figure-drawingarea-curve">
+ <title>Drawing Area - Lines</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;drawingarea_curve.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drawingarea_curve.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;drawingarea/curve">Source Code</ulink></para>
+ <para><link xlink:href="&url_examples_base;drawingarea/curve">Source Code</link></para>
<para>
The only difference between this example and the straight line
example is in the <methodname>on_draw()</methodname> function,
@@ -4371,10 +4438,11 @@ myContext->set_line_width(2.0);]]>
fourth argument specifying the alpha value of the color (valid
values are between 0 and 1).
</para>
- </sect2>
- </sect1>
- <sect1 id="sec-cairo-drawing-arcs">
- <title>Drawing Arcs and Circles</title>
+ </section>
+ </section>
+
+ <section xml:id="sec-cairo-drawing-arcs">
+ <title>Drawing Arcs and Circles</title>
<para>
With Cairo, the same function is used to draw arcs, circles, or
ellipses: <methodname>Cairo::Context::arc()</methodname>. This function
@@ -4396,26 +4464,26 @@ myContext->set_line_width(2.0);]]>
an ellipse with center at <varname>x</varname>, <varname>y</varname>
and size <varname>width</varname>, <varname>height</varname>:
</para>
- <programlisting>context->save();
-context->translate(x, y);
-context->scale(width / 2.0, height / 2.0);
-context->arc(0.0, 0.0, 1.0, 0.0, 2 * M_PI);
-context->restore();</programlisting>
- <sect2 id="cairo-example-arcs">
- <title>Example</title>
+ <programlisting>context->save();
+context->translate(x, y);
+context->scale(width / 2.0, height / 2.0);
+context->arc(0.0, 0.0, 1.0, 0.0, 2 * M_PI);
+context->restore();</programlisting>
+
+ <section xml:id="cairo-example-arcs">
+ <title>Example</title>
<para>
Here's an example of a simple program that draws an arc, a circle
and an ellipse into a drawing area.
</para>
- <figure id="figure-drawingarea-arc">
- <title>Drawing Area - Arcs</title>
+ <figure xml:id="figure-drawingarea-arc">
+ <title>Drawing Area - Arcs</title>
<screenshot>
- <graphic format="PNG"
- fileref="&url_figures_base;drawingarea_arcs.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drawingarea_arcs.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;drawingarea/arcs">Source Code</ulink></para>
+ <para><link xlink:href="&url_examples_base;drawingarea/arcs">Source Code</link></para>
<para>
There are a couple of things to note about this example code.
@@ -4457,12 +4525,13 @@ context->restore();</programlisting>
</para>
</note>
- </sect2>
- </sect1>
- <sect1 id="sec-drawing-text">
- <title>Drawing Text</title>
- <sect2 id="drawing-text-pango">
- <title>Drawing Text with Pango</title>
+ </section>
+ </section>
+ <section xml:id="sec-drawing-text">
+ <title>Drawing Text</title>
+
+ <section xml:id="drawing-text-pango">
+ <title>Drawing Text with Pango</title>
<para>
Text is drawn via Pango Layouts. The easiest way to create a
<classname>Pango::Layout</classname> is to use
@@ -4472,23 +4541,24 @@ context->restore();</programlisting>
be rendered using the
<methodname>Pango::Layout::show_in_cairo_context()</methodname> method.
</para>
- </sect2>
- <sect2 id="pango-text-example">
- <title>Example</title>
+ </section>
+ <section xml:id="pango-text-example">
+ <title>Example</title>
+
<para>
Here is an example of a program that draws some text, some of it
upside-down. The Printing chapter contains another
<link linkend="sec-printing-example">example</link> of drawing text.
</para>
- <figure id="figure-drawingarea-pango-text">
- <title>Drawing Area - Text</title>
+ <figure xml:id="figure-drawingarea-pango-text">
+ <title>Drawing Area - Text</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;drawingarea_pango_text.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drawingarea_pango_text.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;drawingarea/pango_text">Source Code</ulink></para>
- </sect2>
+ <para><link xlink:href="&url_examples_base;drawingarea/pango_text">Source Code</link></para>
+ </section>
<!--
<sect2 id="drawing-text-cairo">
@@ -4496,9 +4566,10 @@ context->restore();</programlisting>
<warning>TODO: Add Cairo content.</warning>
</sect2>
-->
- </sect1>
- <sect1 id="sec-draw-images">
- <title>Drawing Images</title>
+ </section>
+
+ <section xml:id="sec-draw-images">
+ <title>Drawing Images</title>
<para>
There is a method for drawing from a
<classname>Gdk::Pixbuf</classname> to a <classname>Cairo::Context</classname>.
@@ -4538,27 +4609,27 @@ context->restore();</programlisting>
cr->rectangle(110, 90, image->get_width()-20, image->get_height()-20);
cr->fill();
}</programlisting>
- <sect2 id="cairo-example-image">
- <title>Example</title>
+
+ <section xml:id="cairo-example-image">
+ <title>Example</title>
<para>
Here is an example of a simple program that draws an image.
- The program loads the image from a resource file. See the <link
- linkend="sec-gio-resource">Gio::Resource and glib-compile-resources</link>
+ The program loads the image from a resource file. See the <link
linkend="sec-gio-resource">Gio::Resource and glib-compile-resources</link>
section. Use <application>glib-compile-resources</application> to compile
the resources into a C source file that can be compiled and
linked with the C++ code. E.g.
<screen>$ glib-compile-resources --target=resources.c --generate-source
image.gresource.xml</screen>
</para>
- <figure id="figure-drawingarea-image">
- <title>Drawing Area - Image</title>
+ <figure xml:id="figure-drawingarea-image">
+ <title>Drawing Area - Image</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;drawingarea_image.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drawingarea_image.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;drawingarea/image">Source Code</ulink></para> <!-- Insert
image.gresource.xml -->
- </sect2>
- </sect1>
+ <para><link xlink:href="&url_examples_base;drawingarea/image">Source Code</link></para> <!-- Insert
image.gresource.xml -->
+ </section>
+ </section>
<!--
<sect1 id="sec-drawing-fill">
<title>Gradients and other fill techniques</title>
@@ -4569,8 +4640,9 @@ context->restore();</programlisting>
<warning>TODO: Add content.</warning>
</sect1>
-->
- <sect1 id="sec-drawing-clock-example">
- <title>Example Application: Creating a Clock with Cairo</title>
+ <section xml:id="sec-drawing-clock-example">
+ <title>Example Application: Creating a Clock with Cairo</title>
+
<para>
Now that we've covered the basics of drawing with Cairo, let's try to
put it all together and create a simple application that actually
@@ -4579,10 +4651,9 @@ context->restore();</programlisting>
minute hand, and an hour hand, and updates itself every second.
</para>
<screenshot>
- <graphic format="PNG"
- fileref="&url_figures_base;cairo_clock.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;cairo_clock.png"/></imageobject></mediaobject>
</screenshot>
- <para><ulink url="&url_examples_base;drawingarea/clock">Source Code</ulink></para>
+ <para><link xlink:href="&url_examples_base;drawingarea/clock">Source Code</link></para>
<para>
As before, almost all of the interesting stuff is done in the draw
function <methodname>on_draw()</methodname>. Before we dig
@@ -4623,17 +4694,19 @@ context->restore();</programlisting>
simply involves getting the current values for hours, minutes and
seconds, and drawing the hands at the correct angles.
</para>
- </sect1>
+ </section>
</chapter>
-<chapter id="chapter-draganddrop">
+<chapter xml:id="chapter-draganddrop">
<title>Drag and Drop</title>
+
<para>
<classname>Gtk::Widget</classname> has several methods and signals which are
prefixed with "drag_". These are used for Drag and Drop.
</para>
-<sect1 id="sec-dnd-sources-destinations">
+<section xml:id="sec-dnd-sources-destinations">
<title>Sources and Destinations</title>
+
<para>
Things are dragged from <literal>sources</literal> to be dropped on
<literal>destinations</literal>. Each source and destination has information
@@ -4647,10 +4720,11 @@ signals will then be emitted, telling the signal handlers which format was used.
available <type>GType</type>s and mime types (media types).
</para>
-</sect1>
+</section>
-<sect1 id="sec-dnd-methods">
+<section xml:id="sec-dnd-methods">
<title>Methods</title>
+
<para>
<classname>Widget</classname>s can be identified as sources or destinations
using these <classname>Gtk::Widget</classname> methods:
@@ -4709,10 +4783,11 @@ Examples:
<listitem><para><methodname>drag_dest_add_image_targets()</methodname></para></listitem>
</itemizedlist>
</para>
-</sect1>
+</section>
-<sect1 id="sec-dnd-signals">
+<section xml:id="sec-dnd-signals">
<title>Signals</title>
+
<para>
When a drop destination has accepted a dragged item, certain signals will be
emitted, depending on what action has been selected. For instance, the user
@@ -4723,8 +4798,9 @@ the user can only select the actions which you have specified in your calls to
<methodname>drag_source_set()</methodname>.
</para>
-<sect2 id="sec-dnd-signals-copy">
+<section xml:id="sec-dnd-signals-copy">
<title>Copy</title>
+
<para>
The source widget will emit these signals, in this order:
<itemizedlist>
@@ -4756,16 +4832,17 @@ The destination widget will emit these signals, in this order:
</itemizedlist>
</para>
-</sect2>
+</section>
-<sect2 id="dnd-signal-move">
+<section xml:id="dnd-signal-move">
<title>Move</title>
+
<para>During a <literal>move</literal>, the source widget will also emit this signal:
<itemizedlist>
<listitem><para><literal>drag_data_delete</literal>: Gives the source the opportunity to delete the original
data if that's appropriate.</para></listitem>
</itemizedlist>
</para>
-</sect2>
+</section>
<!--
<sect2 id="dnd-signal-link">
@@ -4773,31 +4850,33 @@ The destination widget will emit these signals, in this order:
<para>TODO: Find an example or documentation.</para>
</sect2>
-->
-</sect1>
+</section>
-<sect1 id="sec-dnd-example">
+<section xml:id="sec-dnd-example">
<title>Example</title>
+
<para>Here is a very simple example, demonstrating a drag and drop <literal>Copy</literal> operation:</para>
-<figure id="figure-drag-and-drop">
+<figure xml:id="figure-drag-and-drop">
<title>Drag and Drop</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;drag_and_drop.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;drag_and_drop.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;drag_and_drop">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;drag_and_drop">Source Code</link></para>
<para>
There is a more complex example in examples/others/dnd.
</para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-clipboard">
+<chapter xml:id="chapter-clipboard">
<title>The Clipboard</title>
+
<para>Simple text copy-paste functionality is provided for free by widgets such as
<classname>Gtk::Entry</classname> and <classname>Gtk::TextView</classname>,
but you might need special code to deal with your own data formats. For instance,
@@ -4817,10 +4896,11 @@ which specify callback methods. When <classname>Gdk::Clipboard</classname> is re
it will call these methods, providing the requested data.
</para>
-<para><ulink url="&url_refdocs_base_gdk;Clipboard.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gdk;Clipboard.html">Reference</link></para>
-<sect1 id="sec-clipboard-formats">
+<section xml:id="sec-clipboard-formats">
<title>Formats</title>
+
<para>
Different applications contain different types of data, and they might make that data available in
a variety of formats. >kmm; calls these data types <literal>format</literal>s.</para>
@@ -4842,10 +4922,11 @@ binary data such as images.
<para>The <link linkend="chapter-draganddrop">Drag and Drop</link> API uses the same mechanism.
You should probably use the same data formats for both Clipboard and Drag and Drop operations.</para>
-</sect1>
+</section>
-<sect1 id="sec-clipboard-copy">
+<section xml:id="sec-clipboard-copy">
<title>Copy</title>
+
<para>
When the user asks to copy some data, you should copy the data to the
<classname>Clipboard</classname>. For instance,
@@ -4855,10 +4936,11 @@ When the user asks to copy some data, you should copy the data to the
get_clipboard()->set_text("example_custom_target");
}</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-clipboard-paste">
+<section xml:id="sec-clipboard-paste">
<title>Paste</title>
+
<para>
When the user asks to paste data from the <classname>Clipboard</classname>, you
should request a specific format and provide a callback method which will be
@@ -4878,21 +4960,24 @@ called with the actual data. For instance:
//Do something with the pasted data.
}</programlisting>
-<sect2 id="sec-clipboard-discovering-formats">
+<section xml:id="sec-clipboard-discovering-formats">
<title>Discovering the available formats</title>
+
<para>
To find out what formats are currently available on the <classname>Clipboard</classname>
for pasting, call the <methodname>get_formats()</methodname> method. Then call a
<classname>Gdk::ContentFormats</classname> method to find out if a format that
your application supports is available.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-clipboard-examples"><title>Examples</title>
+<section xml:id="sec-clipboard-examples">
+<title>Examples</title>
-<sect2 id="sec-clipboard-example-simple"><title>Simple</title>
+<section xml:id="sec-clipboard-example-simple">
+<title>Simple</title>
<para>
This example allows copy and pasting of application-specific data, using the
standard text format. Although this is simple, it's not ideal because it does
@@ -4900,43 +4985,41 @@ not identify the <classname>Clipboard</classname> data as being of a particular
type.
</para>
-<figure id="figure-clipboard-simple">
+<figure xml:id="figure-clipboard-simple">
<title>Clipboard - Simple</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;clipboard_simple.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;clipboard_simple.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;clipboard/simple/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;clipboard/simple/">Source Code</link></para>
-</sect2>
+</section>
-<sect2 id="sec-clipboard-example-ideal"><title>Ideal</title>
+<section xml:id="sec-clipboard-example-ideal">
+<title>Ideal</title>
<para>This is like the simple example, but it
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem><simpara>Defines a custom clipboard target, though the format is still text.</simpara></listitem>
<listitem><simpara>It uses the <methodname>Gdk::ContentFormats::signal_changed()</methodname>
signal and disables the Paste button if it can't use anything on the clipboard.</simpara></listitem>
</orderedlist>
</para>
-<figure id="figure-clipboard-ideal">
+<figure xml:id="figure-clipboard-ideal">
<title>Clipboard - Ideal</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;clipboard_ideal.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;clipboard_ideal.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;clipboard/ideal/">Source Code</ulink></para>
-
-</sect2>
-
-</sect1>
-
+<para><link xlink:href="&url_examples_base;clipboard/ideal/">Source Code</link></para>
+</section>
+</section>
</chapter>
-<chapter id="chapter-printing">
+<chapter xml:id="chapter-printing">
<title>Printing</title>
<para>
@@ -4944,7 +5027,7 @@ At the application development level, >kmm;'s printing API
provides dialogs that are consistent across applications and allows use of Cairo's common drawing API, with
Pango-driven text rendering. In the implementation of this common API, platform-specific backends and
printer-specific drivers are used.
</para>
-<sect1 id="sec-printoperation">
+<section xml:id="sec-printoperation">
<title>PrintOperation</title>
<para>
@@ -4955,7 +5038,7 @@ or inherit from it and override the default virtual signal handlers.
affecting the print loop.
</para>
-<sect2 id="sec-printoperation-signals">
+<section xml:id="sec-printoperation-signals">
<title>Signals</title>
<para>
@@ -5046,14 +5129,14 @@ during which various signals are emitted:
</para>
<para>
-<ulink url="&url_refdocs_base_gtk;PrintOperation.html">Reference</ulink>
+<link xlink:href="&url_refdocs_base_gtk;PrintOperation.html">Reference</link>
</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-page-setup">
+<section xml:id="sec-page-setup">
<title>Page setup</title>
<para>
@@ -5078,7 +5161,7 @@ m_refPageSetup = new_page_setup;
</programlisting>
<para>
-<ulink url="&url_refdocs_base_gtk;PageSetup.html">Reference</ulink>
+<link xlink:href="&url_refdocs_base_gtk;PageSetup.html">Reference</link>
</para>
<para>
@@ -5090,9 +5173,9 @@ method. The default measurement unit is device pixels. To select other units,
use the <methodname>PrintOperation::set_unit()</methodname> method.
</para>
-</sect1>
+</section>
-<sect1 id="sec-printing-rendering-text">
+<section xml:id="sec-printing-rendering-text">
<title>Rendering text</title>
<para>
@@ -5115,9 +5198,9 @@ See <link linkend="sec-printing-example-simple">an example</link>
of exactly how this can be done.
</para>
-</sect1>
+</section>
-<sect1 id="sec-async-printing-ops">
+<section xml:id="sec-async-printing-ops">
<title>Asynchronous operations</title>
<para>
@@ -5139,7 +5222,7 @@ the <literal>done</literal> and <literal>status_changed</literal> signals:
// in class ExampleWindow's method...
auto op = PrintOperation::create();
// ...set up op...
-op->signal_done().connect(sigc::bind(sigc::mem_fun(
+op->signal_done().connect(sigc::bind(sigc::mem_fun(
*this, &ExampleWindow::on_printoperation_done), op));
// run the op
</programlisting>
@@ -5155,8 +5238,8 @@ void ExampleWindow::on_printoperation_done(Gtk::PrintOperationResult result,
else if (result == Gtk::PrintOperation::Result::APPLY)
//Update PrintSettings with the ones used in this PrintOperation
- if (! op->is_finished())
- op->signal_status_changed().connect(sigc::bind(sigc::mem_fun(
+ if (! op->is_finished())
+ op->signal_status_changed().connect(sigc::bind(sigc::mem_fun(
*this, &ExampleWindow::on_printoperation_status_changed), op));
}
</programlisting>
@@ -5165,7 +5248,7 @@ void ExampleWindow::on_printoperation_done(Gtk::PrintOperationResult result,
<programlisting>
void ExampleWindow::on_printoperation_status_changed(const Glib::RefPtr<PrintOperation>& op)
{
- if (op->is_finished())
+ if (op->is_finished())
//the print job is finished
else
//get the status with get_status() or get_status_string()
@@ -5174,23 +5257,24 @@ void ExampleWindow::on_printoperation_status_changed(const Glib::RefPtr<Print
}
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-printing-export-to-pdf">
+<section xml:id="sec-printing-export-to-pdf">
<title>Export to PDF</title>
+
<para>
The 'Print to file' option is available in the print dialog, without the need for extra implementation.
However, it is sometimes useful to generate a pdf file directly from code. For instance,
</para>
<programlisting>
auto op = Gtk::PrintOperation::create();
// ...set up op...
-op->set_export_filename("test.pdf");
+op->set_export_filename("test.pdf");
auto res = op->run(Gtk::PrintOperation::Action::EXPORT);
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-extending-print-dialog">
+<section xml:id="sec-extending-print-dialog">
<title>Extending the print dialog</title>
<para>
@@ -5226,7 +5310,7 @@ a member of your <classname>CustomPrintOperation</classname> class:
<programlisting>
Gtk::Widget* CustomPrintOperation::on_create_custom_widget()
{
- set_custom_tab_label("My custom tab");
+ set_custom_tab_label("My custom tab");
auto hbox = new Gtk::Box(Gtk::Orientation::HORIZONTAL, 8);
hbox->set_margin(6);
@@ -5250,9 +5334,9 @@ void CustomPrintOperation::on_custom_widget_apply(Gtk::Widget* /* widget */)
The example in examples/book/printing/advanced demonstrates this.
</para>
-</sect1>
+</section>
-<sect1 id="sec-printing-preview">
+<section xml:id="sec-printing-preview">
<title>Preview</title>
<para>
@@ -5263,7 +5347,7 @@ a preview directly from an application:</para>
// in a class that inherits from Gtk::Window...
auto op = PrintOperation::create();
// ...set up op...
-op->run(Gtk::PrintOperation::Action::PREVIEW, *this);
+op->run(Gtk::PrintOperation::Action::PREVIEW, *this);
</programlisting>
<para>
@@ -5273,12 +5357,12 @@ override this behaviour and provide a custom preview dialog. See the example
located in /examples/book/printing/advanced.
</para>
-</sect1>
+</section>
-<sect1 id="sec-printing-example">
+<section xml:id="sec-printing-example">
<title>Example</title>
-<sect2 id="sec-printing-example-simple">
+<section xml:id="sec-printing-example-simple">
<title>Simple</title>
<para>
@@ -5288,23 +5372,23 @@ and <literal>on_draw_page</literal>, as well as how to track print status
and update the print settings.
</para>
-<figure id="figure-printing-simple">
+<figure xml:id="figure-printing-simple">
<title>Printing - Simple</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;printing.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;printing.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;printing/simple/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;printing/simple/">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-recent-documents">
- <title>Recently Used Documents</title>
+<chapter xml:id="chapter-recent-documents">
+<title>Recently Used Documents</title>
<para>
>kmm; provides an easy way to manage recently used documents. This functionality
@@ -5317,8 +5401,9 @@ and update the print settings.
application registered it, whether it's private to the registering
application, and several other things.
</para>
- <sect1 id="sec-recentmanager">
- <title>RecentManager</title>
+
+ <section xml:id="sec-recentmanager">
+ <title>RecentManager</title>
<para>
<classname>RecentManager</classname> acts as a database of
recently used files. You use this class to register new files, remove
@@ -5331,21 +5416,22 @@ and update the print settings.
default <classname>RecentManager</classname> with
<methodname>get_default()</methodname>.
</para>
- <sect2 id="recent-files-adding">
- <title>Adding Items to the List of Recent Files</title>
+
+ <section xml:id="recent-files-adding">
+ <title>Adding Items to the List of Recent Files</title>
<para>
To add a new file to the list of recent documents, in the simplest case,
you only need to provide the URI. For example:
</para>
<programlisting>auto recent_manager = Gtk::RecentManager::get_default();
-recent_manager->add_item(uri);</programlisting>
+recent_manager->add_item(uri);</programlisting>
<para>
If you want to register a file with metadata, you can pass a
<classname>RecentManager::Data</classname> parameter to
<methodname>add_item()</methodname>. The metadata that can be set on a
particular file item is as follows:
</para>
- <itemizedlist id="list-file-metadata">
+ <itemizedlist xml:id="list-file-metadata">
<listitem>
<para><varname>app_exec</varname>: The command line to be used to launch
this resource. This string may contain the "f" and "u" escape
@@ -5382,9 +5468,10 @@ recent_manager->add_item(uri);</programlisting>
In addition to adding items to the list, you can also look up items from
the list and modify or remove items.
</para>
- </sect2>
- <sect2 id="recent-files-lookup">
- <title>Looking up Items in the List of Recent Files</title>
+ </section>
+
+ <section xml:id="recent-files-lookup">
+ <title>Looking up Items in the List of Recent Files</title>
<para>
To look up recently used files, <classname>RecentManager</classname>
provides several functions. To look up a specific item by its URI, you
@@ -5427,9 +5514,10 @@ if (info)
<methodname>Gtk::Settings::property_gtk_recent_files_max_age()</methodname>.
Default value: 30 days.
</para>
- </sect2>
- <sect2 id="recent-files-modifying">
- <title>Modifying the List of Recent Files</title>
+ </section>
+
+ <section xml:id="recent-files-modifying">
+ <title>Modifying the List of Recent Files</title>
<para>
There may be times when you need to modify the list of recent files.
For instance, if a file is moved or renamed, you may need to update the
@@ -5452,11 +5540,12 @@ if (info)
files.
</para>
</note>
- </sect2>
- </sect1>
+ </section>
+ </section>
+
+ <section xml:id="sec-filechooser">
+ <title>FileChooser</title>
- <sect1 id="sec-filechooser">
- <title>FileChooser</title>
<para>
<classname>FileChooser</classname> is an interface that can be
implemented by widgets displaying a list of files.
@@ -5473,8 +5562,9 @@ if (info)
<classname>FileChooserDialog</classname>, but you can embed it into your
user interface if you want to.
</para>
- <sect2 id="recentfiles-example">
- <title>Simple FileChooserDialog example</title>
+ <section xml:id="recentfiles-example">
+ <title>Simple FileChooserDialog example</title>
+
<para>
Shown below is a simple example of how to use the
<classname>FileChooserDialog</classname> class in a program.
@@ -5498,18 +5588,18 @@ if (info)
see something similar to the following window.
</para>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;recentfiles.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;recentfiles.png"/></imageobject></mediaobject>
</screenshot>
- <para><ulink url="&url_examples_base;recent_files">Source Code</ulink></para>
+ <para><link xlink:href="&url_examples_base;recent_files">Source Code</link></para>
<para>
The constructor for <classname>ExampleWindow</classname> creates the
- menu and the toolbar using <classname>Builder</classname> (see <xref
- linkend="chapter-menus-and-toolbars"/> for more information). It then adds
+ menu and the toolbar using <classname>Builder</classname> (see <xref
linkend="chapter-menus-and-toolbars"/> for more information). It then adds
the menu and the toolbar to the window.
</para>
- </sect2>
- <sect2 id="recent-files-filtering">
- <title>Filtering Files</title>
+ </section>
+
+ <section xml:id="recent-files-filtering">
+ <title>Filtering Files</title>
<para>
For any of the <classname>FileChooser</classname> classes, if you
don't wish to display all of the items in the list of files, you
@@ -5524,20 +5614,21 @@ if (info)
want, you can apply a filter to a chooser widget with the
<methodname>FileChooser::add_filter()</methodname> function.
</para>
- </sect2>
- </sect1>
+ </section>
+ </section>
</chapter>
-<chapter id="chapter-keyboardevents">
- <title>Keyboard Events</title>
+<chapter xml:id="chapter-keyboardevents">
+<title>Keyboard Events</title>
<para>
X events differ in some ways from other signals. These differences are described
in the <link linkend="sec-xeventsignals">X Event signals</link> section in
the appendix. Here we will use keyboard events to show how X events can be
used in a program.
</para>
- <sect1 id="sec-keyboardevents-overview">
- <title>Overview</title>
+ <section xml:id="sec-keyboardevents-overview">
+ <title>Overview</title>
+
<para>
Whenever you press or release a key, an event is emitted. You can connect
a signal handler to handle such events.
@@ -5564,9 +5655,9 @@ if (info)
<programlisting>
bool on_key_press_or_release_event(GdkEventKey* event)
{
- if (event->type == GDK_KEY_PRESS &&
- event->keyval == GDK_KEY_1 &&
- (event->state & (GDK_SHIFT_MASK | GDK_CONTROL_MASK | GDK_MOD1_MASK)) == GDK_MOD1_MASK)
+ if (event->type == GDK_KEY_PRESS &&
+ event->keyval == GDK_KEY_1 &&
+ (event->state & (GDK_SHIFT_MASK | GDK_CONTROL_MASK | GDK_MOD1_MASK)) == GDK_MOD1_MASK)
{
handle_alt_1_press(); // GDK_MOD1_MASK is normally the Alt key
return true;
@@ -5581,8 +5672,9 @@ m_entry.signal_key_press_event().connect( sigc::ptr_fun(&on_key_press_or_rel
m_entry.signal_key_release_event().connect( sigc::ptr_fun(&on_key_press_or_release_event) );
</programlisting>
- <sect2 id="keyboardevents-simple-example">
+ <section xml:id="keyboardevents-simple-example">
<title>Example</title>
+
<para>
In this example there are three keyboard shortcuts:
<keycap>Alt</keycap>+<keycap>1</keycap> selects the first radio button,
@@ -5593,24 +5685,25 @@ m_entry.signal_key_release_event().connect( sigc::ptr_fun(&on_key_press_or_r
section in the appendix.
</para>
- <figure id="figure-keyboardevents-simple">
+ <figure xml:id="figure-keyboardevents-simple">
<title>Keyboard Events - Simple</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;keyboardevents_simple.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;keyboardevents_simple.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;keyboard_events/simple/">Source Code</ulink></para>
- </sect2>
- </sect1>
+ <para><link xlink:href="&url_examples_base;keyboard_events/simple/">Source Code</link></para>
+ </section>
+ </section>
+
+ <section xml:id="sec-keyboardevents-propagation">
+ <title>Event Propagation</title>
- <sect1 id="sec-keyboardevents-propagation">
- <title>Event Propagation</title>
<para>
Event propagation means that, when an event is emitted on a particular
widget, it can be passed to its parent widget (and that widget can pass
it to its parent, and so on) and, if the parent has an event handler,
- that handler will be called.
+ that handler will be called.
</para>
<para>
Contrary to other events, keyboard events are first sent to the toplevel window
@@ -5630,8 +5723,9 @@ m_entry.signal_key_release_event().connect( sigc::ptr_fun(&on_key_press_or_r
(even if it is from the same widget).
</para>
- <sect2 id="keyboardevents-propagation-example">
+ <section xml:id="keyboardevents-propagation-example">
<title>Example</title>
+
<para>
In this example there are three event handlers that are called after
<classname>Gtk::Window</classname>'s default event handler, one in the
@@ -5661,22 +5755,22 @@ m_entry.signal_key_release_event().connect( sigc::ptr_fun(&on_key_press_or_r
above the <classname>Entry</classname>.
</para>
- <figure id="figure-keyboardevents-propagation">
+ <figure xml:id="figure-keyboardevents-propagation">
<title>Keyboard Events - Event Propagation</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;keyboardevents_propagation.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;keyboardevents_propagation.png"/></imageobject></mediaobject>
</screenshot>
</figure>
- <para><ulink url="&url_examples_base;keyboard_events/propagation/">Source Code</ulink></para>
- </sect2>
- </sect1>
+ <para><link xlink:href="&url_examples_base;keyboard_events/propagation/">Source Code</link></para>
+ </section>
+ </section>
</chapter>
-<chapter id="chapter-chapter-timeouts">
+<chapter xml:id="chapter-chapter-timeouts">
<title>Timeouts, I/O and Idle Functions </title>
-<sect1 id="sec-timeouts">
+<section xml:id="sec-timeouts">
<title>Timeouts</title>
<para>
@@ -5724,11 +5818,11 @@ method to be called repeatedly, it should return <literal>true</literal>.
Here's an example of this technique:
</para>
-<para><ulink url="&url_examples_base;timeout/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;timeout/">Source Code</link></para>
-</sect1>
+</section>
-<sect1 id="sec-monitoring-io">
+<section xml:id="sec-monitoring-io">
<title>Monitoring I/O</title>
<para>
@@ -5812,16 +5906,16 @@ specified above. As usual the slot is created with
A little example follows. To use the example just execute it from a terminal;
it doesn't create a window. It will create a pipe named
<literal>testfifo</literal> in the current directory. Then start another shell
-and execute <literal>echo "Hello" > testfifo</literal>. The example will
-print each line you enter until you execute <literal>echo "Q" >
+and execute <literal>echo "Hello" > testfifo</literal>. The example will
+print each line you enter until you execute <literal>echo "Q" >
testfifo</literal>.
</para>
-<para><ulink url="&url_examples_base;input/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;input/">Source Code</link></para>
-</sect1>
+</section>
-<sect1 id="sec-idle-functions">
+<section xml:id="sec-idle-functions">
<title>Idle Functions</title>
<para>
@@ -5851,7 +5945,7 @@ Since this is very similar to the methods above this explanation should
be sufficient to understand what's going on. However, here's a little example:
</para>
-<para><ulink url="&url_examples_base;idle/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;idle/">Source Code</link></para>
<para>
This example points out the difference of idle and timeout methods a
@@ -5866,17 +5960,17 @@ Try executing the example and increasing the system load. The upper
progress bar will increase steadily; the lower one will slow down.
</para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-memory">
+<chapter xml:id="chapter-memory">
<title>Memory management</title>
-<sect1 id="sec-memory-widgets">
+<section xml:id="sec-memory-widgets">
<title>Widgets</title>
-<sect2 id="memory-normal">
+<section xml:id="memory-normal">
<title>Normal C++ memory management</title>
<para>
@@ -5893,7 +5987,7 @@ management features.
<para>Here are some examples of normal C++ memory management:</para>
-<sect3 id="memory-class-scope">
+<section xml:id="memory-class-scope">
<title>Class Scope widgets</title>
<para>
@@ -5918,9 +6012,9 @@ private:
// will be destroyed when the Foo object is destroyed
};
</programlisting>
-</sect3>
+</section>
-<sect3 id="memory-function-scope">
+<section xml:id="memory-function-scope">
<title>Function scope widgets</title>
<para>
@@ -5936,9 +6030,9 @@ increased data hiding and reduced dependencies.
app->run();
}
</programlisting>
-</sect3>
+</section>
-<sect3 id="memory-dynamic-allocation">
+<section xml:id="memory-dynamic-allocation">
<title>Dynamic allocation with new and delete</title>
<para>
@@ -5958,11 +6052,11 @@ delete pButton;
</programlisting>
Here, the programmer deletes <varname>pButton</varname> to prevent a memory leak.
</para>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="memory-managed-widgets">
+<section xml:id="memory-managed-widgets">
<title>Managed Widgets</title>
<para>
@@ -5974,7 +6068,7 @@ pack it into its container with <methodname>Gtk::Box::append()</methodname> or
a similar method. Now the widget will be destroyed whenever its container is destroyed.
</para>
-<sect3 id="memory-managed-dynamic">
+<section xml:id="memory-managed-dynamic">
<title>Dynamic allocation with make_managed() and append()</title>
<para>
@@ -6033,11 +6127,11 @@ the traditional C++ techniques. For instance, your top-level Window might just
be an instance in your <function>main()</function> function.
</para>
-</sect3>
-</sect2>
-</sect1>
+</section>
+</section>
+</section>
-<sect1 id="sec-memory-shared-resources">
+<section xml:id="sec-memory-shared-resources">
<title>Shared resources</title>
<para>
@@ -6101,12 +6195,13 @@ Nicolai M. Josuttis, "The C++ Standard Library" - section 4.2
</itemizedlist>
</para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-builder">
+<chapter xml:id="chapter-builder">
<title>Glade and Gtk::Builder</title>
+
<para>
Although you can use C++ code to instantiate and arrange widgets, this
can soon become tedious and repetitive. And it requires a recompilation to show
@@ -6119,7 +6214,7 @@ instances.
<para>
This has the following advantages:
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem><simpara>Less C++ code is required.</simpara></listitem>
<listitem><simpara>UI changes can be seen more quickly, so UIs are able to improve.</simpara></listitem>
<listitem><simpara>Designers without programming skills can create and edit UIs.</simpara></listitem>
@@ -6132,14 +6227,15 @@ actions, but using <application>Gtk::Builder</application> for the widget
layout allows you to focus on implementing that functionality.
</para>
-<sect1 id="sec-builder-loading-glade-file">
+<section xml:id="sec-builder-loading-glade-file">
<title>Loading the .glade file</title>
+
<para>
<classname>Gtk::Builder</classname> must be used via a
<classname>Glib::RefPtr</classname>. Like all such classes, you need to use a
<methodname>create()</methodname> method to instantiate it. For instance,
<programlisting>
-auto builder = Gtk::Builder::create_from_file("basic.glade");
+auto builder = Gtk::Builder::create_from_file("basic.glade");
</programlisting>
This will instantiate the windows defined in the <filename>.glade</filename> file.
</para>
@@ -6147,12 +6243,12 @@ This will instantiate the windows defined in the <filename>.glade</filename> fil
<para>To instantiate just one window, or just one of the child widgets, you can specify the name of a widget
as the second parameter. For instance,
</para>
<programlisting>
-auto builder = Gtk::Builder::create_from_file("basic.glade", "treeview_products");
+auto builder = Gtk::Builder::create_from_file("basic.glade", "treeview_products");
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-builder-accessing-widgets">
+<section xml:id="sec-builder-accessing-widgets">
<title>Accessing widgets</title>
<para>
@@ -6163,7 +6259,7 @@ window. If the widget could not be found, or is of the wrong type, then the
pointer will be set to nullptr.
</para>
<programlisting>
-<![CDATA[auto pDialog = builder->get_widget<Gtk::Dialog>("DialogBasic");]]>
+auto pDialog = builder->get_widget<Gtk::Dialog>("DialogBasic");
</programlisting>
<para>
@@ -6191,23 +6287,25 @@ some point. The documentation of <classname>Gtk::Builder</classname> has more to
about the memory management of different kinds of objects.
</para>
-<para><ulink url="&url_refdocs_base_gtk;Builder.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Builder.html">Reference</link></para>
-<sect2 id="builder-example-basic">
+<section xml:id="builder-example-basic">
<title>Example</title>
+
<para>
This simple example shows how to load a <application>Glade</application> file at runtime and access the
widgets with
<application>Gtk::Builder</application>.
</para>
-<para><ulink url="&url_examples_base;builder/basic">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;builder/basic">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-builder-using-derived-widgets">
+<section xml:id="sec-builder-using-derived-widgets">
<title>Using derived widgets</title>
+
<para>
You can use <classname>Gtk::Builder</classname> and
<application>Glade</application> to layout your own custom widgets
@@ -6219,7 +6317,7 @@ having most of your source just be setting properties and packing in containers.
<para>Use <methodname>Gtk::Builder::get_widget_derived()</methodname> like so:
</para>
<programlisting>
-<![CDATA[auto pDialog = Gtk::Builder::get_widget_derived<DerivedDialog>(builder, "DialogDerived");]]>
+auto pDialog = Gtk::Builder::get_widget_derived<DerivedDialog>(builder, "DialogDerived");
</programlisting>
<para>
@@ -6246,17 +6344,17 @@ constructor of the derived class, maybe using <methodname>get_widget()</methodna
or <methodname>get_widget_derived()</methodname> again. For instance,
</para>
<programlisting>
-<![CDATA[DerivedDialog::DerivedDialog(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
+DerivedDialog::DerivedDialog(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
: Gtk::Dialog(cobject),
m_builder(builder),
//Get the Glade-instantiated Button, and connect a signal handler:
- m_pButton(m_builder->get_widget<Gtk::Button>("quit_button"))
+ m_pButton(m_builder->get_widget<Gtk::Button>("quit_button"))
{
if(m_pButton)
{
- m_pButton->signal_clicked().connect( sigc::mem_fun(*this, &DerivedDialog::on_button_quit) );
+ m_pButton->signal_clicked().connect( sigc::mem_fun(*this, &DerivedDialog::on_button_quit) );
}
-}]]>
+}
</programlisting>
<para>
@@ -6264,22 +6362,23 @@ It's possible to pass additional arguments from
<methodname>get_widget_derived()</methodname> to the constructor of the derived
widget. For instance, this call to <methodname>get_widget_derived()</methodname>
<programlisting>
-<![CDATA[auto pDialog = Gtk::Builder::get_widget_derived<DerivedDialog>(builder, "DialogDerived", true);]]>
+auto pDialog = Gtk::Builder::get_widget_derived<DerivedDialog>(builder, "DialogDerived", true);
</programlisting>
can invoke this constructor
<programlisting>
-<![CDATA[DerivedDialog::DerivedDialog(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder,
bool warning)
+DerivedDialog::DerivedDialog(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder,
bool warning)
: Gtk::Dialog(cobject),
m_builder(builder),
- m_pButton(m_builder->get_widget<Gtk::Button>("quit_button"))
+ m_pButton(m_builder->get_widget<Gtk::Button>("quit_button"))
{
// ....
-}]]>
+}
</programlisting>
</para>
-<sect2 id="sec-builder-and-property">
+<section xml:id="sec-builder-and-property">
<title>Gtk::Builder and Glib::Property</title>
+
<para>
If your derived widget uses <classname>Glib::Property</classname>, it becomes slightly
more complicated. A derived widget that contains <classname>Glib::Property</classname>
@@ -6292,14 +6391,14 @@ Your derived widget must have a constructor that has the parameters required by
constructor to register the <type>GType</type>.
</para>
<programlisting>
-<![CDATA[DerivedButton::DerivedButton(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
+DerivedButton::DerivedButton(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
: Glib::ObjectBase("MyButton"), // The GType name will be gtkmm__CustomObject_MyButton.
Gtk::Button(cobject),
prop_ustring(*this, "button-ustring"),
prop_int(*this, "button-int", 10)
{
// ....
-}]]>
+}
</programlisting>
<para>
When using >kmm; with a version of <application>glibmm</application> from 2.62
@@ -6308,27 +6407,28 @@ in C++ using >kmm;, within <filename>.glade</filename> files and load/set
these using <classname>Gtk::Builder</classname>. See the documentation of
<classname>Gtk::Builder</classname> for more details on how to achieve this.
Glade won’t recognise such properties as-is, but it should be able to through
-use of <ulink url="https://developer.gnome.org/gladeui/stable/properties.html";>
-property class definitions</ulink> and a catalog declaring those new properties.
+use of <link xlink:href="https://developer.gnome.org/gladeui/stable/properties.html";>
+property class definitions</link> and a catalog declaring those new properties.
</para>
-</sect2>
+</section>
-<sect2 id="builder-example-derived">
+<section xml:id="builder-example-derived">
<title>Example</title>
+
<para>
This example shows how to load a <application>Glade</application> file at runtime and access the widgets via
derived classes.
</para>
-<para><ulink url="&url_examples_base;builder/derived">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;builder/derived">Source Code</link></para>
-</sect2>
+</section>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-internationalization">
- <title>Internationalization and Localization</title>
+<chapter xml:id="chapter-internationalization">
+<title>Internationalization and Localization</title>
<para>
>kmm; applications can easily support multiple languages, including
@@ -6365,8 +6465,8 @@ This example shows how to load a <application>Glade</application> file at runtim
the translated text at runtime.
</para>
- <sect1 id="sec-internationalization-intro">
- <title>Preparing your project</title>
+ <section xml:id="sec-internationalization-intro">
+ <title>Preparing your project</title>
<note>
<para>
@@ -6384,10 +6484,9 @@ This example shows how to load a <application>Glade</application> file at runtim
We also assume that you are using autotools (e.g.
<application>automake</application> and
<application>autoconf</application>) to build your project, and
- that you are using <ulink
- url="https://gitlab.gnome.org/GNOME/gnome-common/blob/master/autogen.sh";>
+ that you are using <link
xlink:href="https://gitlab.gnome.org/GNOME/gnome-common/blob/master/autogen.sh";>
<literal>./autogen.sh</literal> from
- <application>gnome-common</application></ulink>
+ <application>gnome-common</application></link>
or a similar <literal>autogen.sh</literal> file, which, among other
things, takes care of some <application>intltool</application>
initialization.
@@ -6453,9 +6552,8 @@ src/other.cc</programlisting>
mark strings for translation if they are in source code file. However, if
you use <application>intltool</application>, you can mark strings for
translation in a variety of other file formats, including
- <application>Glade</application> UI files, xml, <ulink
- url="http://standards.freedesktop.org/desktop-entry-spec/latest/";>.desktop
- files</ulink> and several more. So, if you have designed some of the
+ <application>Glade</application> UI files, xml, <link
xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/";>.desktop
+ files</link> and several more. So, if you have designed some of the
application UI in <application>Glade</application> then also add your
<filename>.glade</filename> files to the list in
<literal>POTFILES.in</literal>.
@@ -6550,10 +6648,10 @@ desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
This macro will be used when you initialize <literal>gettext</literal> in
your source code.
</para>
- </sect1>
+ </section>
-<sect1 id="sec-i18n-marking-strings">
- <title>Marking strings for translation</title>
+<section xml:id="sec-i18n-marking-strings">
+<title>Marking strings for translation</title>
<para>
String literals should be typed in the source code in English, but
@@ -6600,8 +6698,8 @@ desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
textdomain(GETTEXT_PACKAGE);</programlisting>
- <sect2 id="sec-i18n-gettext">
- <title>How gettext works</title>
+ <section xml:id="sec-i18n-gettext">
+ <title>How gettext works</title>
<para>
The <application>intltool-update</application> or
@@ -6633,10 +6731,10 @@ textdomain(GETTEXT_PACKAGE);</programlisting>
<literal>gettext</literal> call, it looks for a translation of a
particular string. If none is found, the original string is used.
</para>
- </sect2>
+ </section>
- <sect2 id="sec-i18n-testing">
- <title>Testing and adding translations</title>
+ <section xml:id="sec-i18n-testing">
+ <title>Testing and adding translations</title>
<para>
To convince yourself that you've done well, you may wish to add a
@@ -6664,14 +6762,14 @@ textdomain(GETTEXT_PACKAGE);</programlisting>
<literal>fuzzy</literal> in the <filename>.po</filename> file.
These translations will not substitute the original string. To make
them appear, simply remove the <literal>fuzzy</literal> tag.
- A <literal>Fuzzy</literal> tag appears if a string content changed,
+ A <literal>fuzzy</literal> tag appears if a string content changed,
but the location is still the same.
</para>
</note>
- </sect2>
+ </section>
- <sect2 id="sec-i18n-resources">
- <title>Resources</title>
+ <section xml:id="sec-i18n-resources">
+ <title>Resources</title>
<para>
More information about what lies behind the internationalization and localization process
@@ -6680,48 +6778,49 @@ textdomain(GETTEXT_PACKAGE);</programlisting>
<itemizedlist>
<listitem>
<para>
- <ulink url="https://wiki.gnome.org/TranslationProject/DevGuidelines";>
- L10N Guidelines for Developers</ulink>
+ <link xlink:href="https://wiki.gnome.org/TranslationProject/DevGuidelines";>
+ L10N Guidelines for Developers</link>
</para>
</listitem>
<listitem>
<para>
- <ulink url="http://bazaar.launchpad.net/~intltool/intltool/trunk/view/head:/README";>Intltool
README</ulink>
+ <link
xlink:href="http://bazaar.launchpad.net/~intltool/intltool/trunk/view/head:/README";>Intltool README</link>
</para>
</listitem>
<listitem>
<para>
- <ulink url="https://wiki.gnome.org/TranslationProject/GitHowTo";>How to use Git for GNOME
translators</ulink>
+ <link xlink:href="https://wiki.gnome.org/TranslationProject/GitHowTo";>How to use Git for GNOME
translators</link>
</para>
</listitem>
<listitem>
<para>
- <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html";>gettext manual</ulink>
+ <link xlink:href="http://www.gnu.org/software/gettext/manual/gettext.html";>gettext manual</link>
</para>
</listitem>
<listitem>
<para>
- <ulink url="http://ftp.gnome.org/pub/GNOME/sources/gtkmm_hello/";><literal>gtkmm_hello</literal>
example package</ulink>
+ <link
xlink:href="http://ftp.gnome.org/pub/GNOME/sources/gtkmm_hello/";><literal>gtkmm_hello</literal> example
package</link>
</para>
</listitem>
<listitem>
<para>
- <ulink
url="http://ftp.gnome.org/pub/GNOME/sources/gnomemm_hello/";><literal>gnomemm_hello</literal> example
package</ulink>
+ <link
xlink:href="http://ftp.gnome.org/pub/GNOME/sources/gnomemm_hello/";><literal>gnomemm_hello</literal> example
package</link>
</para>
</listitem>
</itemizedlist>
</para>
- </sect2>
+ </section>
-</sect1>
+</section>
-<sect1 id="sec-i18n-expecting-utf8">
+<section xml:id="sec-i18n-expecting-utf8">
<title>Expecting UTF8</title>
+
<para>
A properly internationalized application will not make assumptions about the
number of bytes in a character. That means that you shouldn't use pointer
@@ -6732,13 +6831,13 @@ as <function>strlen()</function> because they make the same assumption.
<para>
However, you probably already avoid bare char* arrays and pointer arithmetic by
using <classname>std::string</classname>, so you just need to start using
-<classname>Glib::ustring</classname> instead. See the <link
- linkend="sec-basics-ustring">Basics</link> chapter about
+<classname>Glib::ustring</classname> instead. See the <link linkend="sec-basics-ustring">Basics</link>
chapter about
<classname>Glib::ustring</classname>.
</para>
-<sect2 id="i18n-ustring-iostreams">
+<section xml:id="i18n-ustring-iostreams">
<title>Glib::ustring and std::iostreams</title>
+
<!-- <para>TODO: This section is not clear - it needs to spell things out more clearly and obviously.</para>
-->
<para>
Unfortunately, the integration with the standard iostreams is not completely
@@ -6762,17 +6861,17 @@ this with a manual conversion. For instance, to retrieve the
std::ostringstream output;
output << percentage << " % done";
label->set_text(Glib::locale_to_utf8(output.str()));</programlisting>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-i18n-pitfalls">
- <title>Pitfalls</title>
+<section xml:id="sec-i18n-pitfalls">
+<title>Pitfalls</title>
<para>There are a few common mistakes that you would discover eventually yourself. But this section
might help you to avoid them.</para>
-<sect2 id="i18n-string-semantics">
- <title>Same strings, different semantics</title>
+<section xml:id="i18n-string-semantics">
+<title>Same strings, different semantics</title>
<para>Sometimes two English strings are identical but have different meanings in
different contexts, so they would probably not be identical when translated. Since the English strings are
@@ -6797,10 +6896,10 @@ If you use <application>Glib</application>'s support macros, it's easier. Use
</para>
<programlisting>GLib::ustring text(C_("noun", "jumps"));</programlisting>
-</sect2>
+</section>
-<sect2 id="i18n-composition">
- <title>Composition of strings</title>
+<section xml:id="i18n-composition">
+<title>Composition of strings</title>
<para>
C programmers use <function>sprintf()</function> to compose and concatenate
@@ -6818,30 +6917,30 @@ label.set_text(_("Really delete ") + filename + _(" now?"));</programlisting>
<para>
So you should either avoid this situation or use
-<ulink url="&url_refdocs_base_glib;ustring.html"><function>Glib::ustring::compose()</function></ulink>
+<link xlink:href="&url_refdocs_base_glib;ustring.html"><function>Glib::ustring::compose()</function></link>
which supports syntax such as:
</para>
<programlisting>std::cout << Glib::ustring::compose(
_("Current amount: %1 Future: %2"), amount, future) << std::endl;
label.set_text(Glib::ustring::compose(_("Really delete %1 now?"), filename));</programlisting>
-</sect2>
+</section>
-<sect2 id="i18n-display-size">
- <title>Assuming the displayed size of strings</title>
+<section xml:id="i18n-display-size">
+<title>Assuming the displayed size of strings</title>
<para>You never know how much space a string will take on screen when translated. It might very
possibly be twice the size of the original English string. Luckily, most >kmm; widgets will expand at
runtime to the required size.</para>
-</sect2>
+</section>
-<sect2 id="i18n-unusual-words">
- <title>Unusual words</title>
+<section xml:id="i18n-unusual-words">
+<title>Unusual words</title>
<para>You should avoid cryptic abbreviations, slang, or jargon.
They are usually difficult to translate, and are often difficult
-for even native speakers to understand. For instance, prefer "application" to
"app"</para>
-</sect2>
+for even native speakers to understand. For instance, prefer "application" to "app"</para>
+</section>
-<sect2 id="i18n-non-ascii-characters">
+<section xml:id="i18n-non-ascii-characters">
<title>Using non-ASCII characters in strings</title>
<para>
@@ -6854,21 +6953,21 @@ instance, you cannot use the copyright sign (©).
source code just before the string, telling the translators to
use the special character if it is available in their languages. For English, you could then make
an American English
<filename>en_US.po</filename> translation which used that special character.</para>
- </sect2>
- </sect1>
+ </section>
+ </section>
- <sect1 id="sec-i18n-getting-help-with-translations">
- <title>Getting help with translations</title>
+ <section xml:id="sec-i18n-getting-help-with-translations">
+ <title>Getting help with translations</title>
<para>If your program is free software, there is a whole <literal>GNOME</literal>
subproject devoted to helping you make translations, the
- <ulink url="https://wiki.gnome.org/TranslationProject/";><literal>GNOME</literal>
- Translation Project</ulink>.</para>
+ <link xlink:href="https://wiki.gnome.org/TranslationProject/";><literal>GNOME</literal>
+ Translation Project</link>.</para>
<para>The way it works is that you upload your source code to a git
repository where translators can access it, then contact the gnome-i18n
mailing list and ask to have your program added to the
- <ulink url="http://l10n.gnome.org/module/";>list of modules to translate</ulink>.</para>
+ <link xlink:href="http://l10n.gnome.org/module/";>list of modules to translate</link>.</para>
<para>Then you make sure you update the file
<filename>POTFILES.in</filename> in the
@@ -6890,11 +6989,11 @@ instance, you cannot use the copyright sign (©).
project as being really serious (in the sense that it is
polished and being maintained) they may decide to spend their
time on some other project.</para>
- </sect1>
+ </section>
</chapter>
-<chapter id="chapter-customwidgets">
- <title>Custom Widgets</title>
+<chapter xml:id="chapter-customwidgets">
+<title>Custom Widgets</title>
<para>>kmm; makes it very easy to derive new widgets by inheriting from an
existing widget class, either by deriving from a container and adding child
@@ -6902,8 +7001,9 @@ instance, you cannot use the copyright sign (©).
But you might occasionally find that no suitable starting point already exists.
In this case, you can implement a widget from scratch.</para>
- <sect1 id="sec-custom-containers">
+ <section xml:id="sec-custom-containers">
<title>Custom Containers</title>
+
<para>When deriving a custom container widget directly from <classname>Gtk::Widget</classname>,
you should override the following virtual methods:
<itemizedlist>
@@ -6946,26 +7046,28 @@ instance, you cannot use the copyright sign (©).
widgets to fill the space, or you might choose to expand the padding
between your widgets. It's your container, so you decide.</para>
-<sect2 id="custom-container-example"><title>Example</title>
+<section xml:id="custom-container-example">
+<title>Example</title>
<para>This example implements a container with two child widgets, one above
the other. Of course, in this case it would be far simpler just to use
a vertical <classname>Gtk::Box</classname> or <classname>Gtk::Grid</classname>.</para>
-<figure id="figure-custom-container">
+<figure xml:id="figure-custom-container">
<title>Custom Container</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;custom_container.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;custom_container.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;custom/custom_container/">Source Code</ulink></para>
-</sect2>
+<para><link xlink:href="&url_examples_base;custom/custom_container/">Source Code</link></para>
+</section>
- </sect1>
+ </section>
- <sect1 id="sec-custom-widgets">
+ <section xml:id="sec-custom-widgets">
<title>Custom Widgets</title>
+
<para>By deriving directly from <classname>Gtk::Widget</classname> you can
do all the drawing for your widget directly, instead of just arranging
child widgets. For instance, a <classname>Gtk::Label</classname> draws
@@ -6993,7 +7095,7 @@ instance, you cannot use the copyright sign (©).
<link linkend="sec-custom-containers">Custom Containers</link> section.
</para>
-<sect2 id="custom-init-functions">
+<section xml:id="custom-init-functions">
<title>Class Init and Instance Init Functions</title>
<para>Some <application>GTK</application> functions, if called at all, must be
@@ -7002,9 +7104,9 @@ functions, if called, must be called from the instance init function.
If your custom widget must call any of those functions, you can derive a class
from <classname>Glib::ExtraClassInit</classname> and derive your custom class
from that class. The following example shows how that's done.</para>
-</sect2>
+</section>
-<sect2 id="custom-style-information">
+<section xml:id="custom-style-information">
<title>Custom Style Information</title>
<para>Your widget class, whether it's derived directly from
@@ -7017,30 +7119,31 @@ With the methods of <classname>Gtk::StyleContext</classname> you can read the va
of your widget's style information. CSS files are described in the documentation of
<application>GTK</application>. The following example shows a simple use of
<methodname>Gtk::StyleContext::get_padding()</methodname>.</para>
-</sect2>
+</section>
-<sect2 id="custom-widget-example"><title>Example</title>
+<section xml:id="custom-widget-example">
+<title>Example</title>
<para>This example implements a widget which draws Penrose triangles.</para>
-<figure id="figure-custom-widget">
+<figure xml:id="figure-custom-widget">
<title>Custom Widget</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;custom_widget.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;custom_widget.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;custom/custom_widget/">Source Code</ulink></para> <!-- Insert
custom_gtk.css -->
-</sect2>
+<para><link xlink:href="&url_examples_base;custom/custom_widget/">Source Code</link></para> <!-- Insert
custom_gtk.css -->
+</section>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-multi-threaded-programs">
+<chapter xml:id="chapter-multi-threaded-programs">
<title>Multi-threaded programs</title>
-<sect1 id="sec-the-constraints">
+<section xml:id="sec-the-constraints">
<title>The constraints</title>
<para>
@@ -7075,7 +7178,7 @@ connection.
</footnote>
</para>
-<sect2 id="the-rules">
+<section xml:id="the-rules">
<title>The rules</title>
<para>
@@ -7086,7 +7189,7 @@ from <classname>sigc::trackable</classname>, because the effects are
unintuitive (see particularly points 4 and 5 below).
</para>
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>
@@ -7172,11 +7275,11 @@ deriving from <classname>sigc::trackable</classname>.
</orderedlist>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-using-glib-dispatcher">
+<section xml:id="sec-using-glib-dispatcher">
<title>Using Glib::Dispatcher</title>
<para>
@@ -7242,10 +7345,11 @@ to emit, a normal <classname>sigc::signal<void()></classname>
object could of course be used instead.
</para>
-</sect1>
+</section>
-<sect1 id="sec-multithread-example">
+<section xml:id="sec-multithread-example">
<title>Example</title>
+
<para>
This is an example program with two threads, one GUI thread, like in all
>kmm; programs, and one worker thread. The worker thread is created when you
@@ -7270,20 +7374,20 @@ If you build with <application>meson</application>, it handles the multi-threadi
complications for you, if you add <function>dependency('threads')</function>.
</para>
-<figure id="figure-multithread">
+<figure xml:id="figure-multithread">
<title>Multi-Threaded Program</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;multithread.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;multithread.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;multithread">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;multithread">Source Code</link></para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-recommended-techniques">
+<chapter xml:id="chapter-recommended-techniques">
<title>Recommended Techniques</title>
<para>This section is simply a gathering of wisdom, general style guidelines
@@ -7313,8 +7417,8 @@ and hints for creating >kmm; applications.
<classname>sigc::signal</classname>s, as described in the
<application>libsigc++</application> documentation.</para>
-<sect1 id="sec-application-lifetime">
- <title>Application Lifetime</title>
+<section xml:id="sec-application-lifetime">
+<title>Application Lifetime</title>
<para>Most applications will have only one <classname>Window</classname>, or
only one main window. These applications can use the
<methodname>Gtk::Application::run(Gtk::Window& window)</methodname> or
@@ -7325,9 +7429,9 @@ and hints for creating >kmm; applications.
closing the window (for instance, if there are unsaved changes) by
overriding <methodname>Gtk::Window::on_delete_event()</methodname>.</para>
<para>Most of our examples use this technique.</para>
-</sect1>
+</section>
-<sect1 id="sec-using-a-gtkmm-widget">
+<section xml:id="sec-using-a-gtkmm-widget">
<title>Using a >kmm; widget</title>
<para>
@@ -7337,7 +7441,7 @@ and hints for creating >kmm; applications.
<para>
-<orderedlist>
+<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>
Declare a variable of the type of <classname>Widget</classname> you wish to
@@ -7379,15 +7483,15 @@ of its child widgets are also hidden, even if <methodname>hide()</methodname> is
not called on the child widgets.
</para>
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-building-applications">
+<chapter xml:id="chapter-building-applications">
<title>Building applications</title>
<para>
-This chapter is similar to the "Building applications" chapter in the
-<ulink url="https://developer.gnome.org/gtk4/unstable/";>GTK4 Reference Manual</ulink>.
+This chapter is similar to the "Building applications" chapter in the
+<link xlink:href="https://developer.gnome.org/gtk4/unstable/";>GTK4 Reference Manual</link>.
The same application is built, but >kmm; is used instead of <application>GTK</application>.
</para>
<para>
@@ -7437,15 +7541,15 @@ and more pieces over time. Along the way, we'll learn about <classname>Gtk::Appl
The full, buildable sources for these examples can be found in the
<filename>examples/book/buildapp</filename> directory of the
<application>gtkmm-documentation</application> source distribution, or online in the
-<ulink url="&url_examples_base;buildapp"><application>gtkmm-documentation</application>
-git repository</ulink>. You can build each example separately by using <command>meson</command>
+<link xlink:href="&url_examples_base;buildapp"><application>gtkmm-documentation</application>
+git repository</link>. You can build each example separately by using <command>meson</command>
and <command>ninja</command> with the <filename>meson.build</filename> file or by using
<command>make</command> with the <filename>Makefile.example</filename> file. For more
information, see the <filename>README</filename> included in the <filename>buildapp</filename>
directory.
</para>
-<sect1 id="sec-buildapp-trivial-app">
+<section xml:id="sec-buildapp-trivial-app">
<title>A trivial application</title>
<para>
@@ -7470,8 +7574,8 @@ arguments, and <methodname>signal_open()</methodname>'s default handler, which g
called when the application is launched with commandline arguments.
</para>
-<para><ulink url="&url_refdocs_base_gio;Application.html">Gio::Application Reference</ulink></para>
-<para><ulink url="&url_refdocs_base_gtk;Application.html">Gtk::Application Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_gio;Application.html">Gio::Application Reference</link></para>
+<para><link xlink:href="&url_refdocs_base_gtk;Application.html">Gtk::Application Reference</link></para>
<para>
Another important class that is part of the application support in >kmm; is
@@ -7489,10 +7593,10 @@ to the binary before this desktop file can be used.
Here is what we've achieved so far:
</para>
-<figure id="figure-buildapp-trivial-app">
+<figure xml:id="figure-buildapp-trivial-app">
<title>A trivial application</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_trivial_app.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_trivial_app.png"/></imageobject></mediaobject>
</screenshot>
</figure>
@@ -7501,11 +7605,11 @@ This does not look very impressive yet, but our application is already presentin
on the session bus, it has single-instance semantics, and it accepts files as commandline arguments.
</para>
-<para><ulink url="&url_examples_base;buildapp/step1">Source Code</ulink></para> <!-- Insert
exampleapp.desktop.in -->
+<para><link xlink:href="&url_examples_base;buildapp/step1">Source Code</link></para> <!-- Insert
exampleapp.desktop.in -->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-populating-window">
+<section xml:id="sec-buildapp-populating-window">
<title>Populating the window</title>
<para>
@@ -7524,7 +7628,7 @@ To make use of this file in our application, we revisit our
<methodname>Gtk::Builder::create_from_resource()</methodname> and
<methodname>Gtk::Builder::get_widget_derived()</methodname> from the
<methodname>ExampleAppWindow::create()</methodname> method to get an instance of
-our subclassed <classname>Gtk::ApplicationWindow</classname>. See the
+our subclassed <classname>Gtk::ApplicationWindow</classname>. See the
<link linkend="sec-builder-using-derived-widgets">Using derived widgets</link> section
for more information about <methodname>get_widget_derived()</methodname>.
</para>
@@ -7540,26 +7644,26 @@ into the application together with the other source files. To do so, we use the
<screen>$ glib-compile-resources --target=resources.c --generate-source exampleapp.gresource.xml</screen>
The <link linkend="sec-gio-resource">Gio::Resource and glib-compile-resources</link>
section contains more information about resource files. If you build with Meson,
-use the <function>compile_resources()</function> function in Meson's
-<ulink url="https://mesonbuild.com/Gnome-module.html";>GNOME module</ulink>.
+use the <function>compile_resources()</function> function in Meson's
+<link xlink:href="https://mesonbuild.com/Gnome-module.html";>GNOME module</link>.
</para>
<para>
Our application now looks like this:
</para>
-<figure id="figure-buildapp-populating-window">
+<figure xml:id="figure-buildapp-populating-window">
<title>Populating the window</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_populating_window.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_populating_window.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step2">Source Code</ulink></para> <!-- Insert
exampleapp.gresource.xml window.ui -->
+<para><link xlink:href="&url_examples_base;buildapp/step2">Source Code</link></para> <!-- Insert
exampleapp.gresource.xml window.ui -->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-opening-files">
+<section xml:id="sec-buildapp-opening-files">
<title>Opening files</title>
<para>
@@ -7595,18 +7699,18 @@ method.
Our application is beginning to take shape:
</para>
-<figure id="figure-buildapp-opening-files">
+<figure xml:id="figure-buildapp-opening-files">
<title>Opening files</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_opening_files.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_opening_files.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step3">Source Code</ulink></para> <!-- Insert window.ui -->
+<para><link xlink:href="&url_examples_base;buildapp/step3">Source Code</link></para> <!-- Insert window.ui
-->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-menu">
+<section xml:id="sec-buildapp-menu">
<title>A menu</title>
<para>
@@ -7641,18 +7745,18 @@ is added with <methodname>Gtk::Application::set_accel_for_action()</methodname>.
The menu looks like this:
</para>
-<figure id="figure-buildapp-menu">
+<figure xml:id="figure-buildapp-menu">
<title>A menu</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_menu.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_menu.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step4">Source Code</ulink></para> <!-- Insert
exampleapp.gresource.xml gears_menu.ui window.ui -->
+<para><link xlink:href="&url_examples_base;buildapp/step4">Source Code</link></para> <!-- Insert
exampleapp.gresource.xml gears_menu.ui window.ui -->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-pref-dialog">
+<section xml:id="sec-buildapp-pref-dialog">
<title>A preference dialog</title>
<para>
@@ -7671,9 +7775,9 @@ in our case the <filename>org.gtkmm.exampleapp.gschema.xml</filename> file.
Before we can make use of this schema in our application, we need to compile it into
the binary form that <classname>Gio::Settings</classname> expects. GIO provides macros
to do this in autotools-based projects. See the description of
-<ulink url="https://developer.gnome.org/gio/stable/GSettings.html";>GSettings</ulink>.
+<link xlink:href="https://developer.gnome.org/gio/stable/GSettings.html";>GSettings</link>.
Meson provides the <function>compile_schemas()</function> function in the
-<ulink url="https://mesonbuild.com/Gnome-module.html";>GNOME module</ulink>.
+<link xlink:href="https://mesonbuild.com/Gnome-module.html";>GNOME module</link>.
</para>
<para>
@@ -7683,8 +7787,8 @@ to bind settings keys to object properties, as we do for the transition setting
<classname>ExampleAppWindow</classname>'s constructor.
</para>
<programlisting>
-<![CDATA[m_settings = Gio::Settings::create("org.gtkmm.exampleapp");
-m_settings->bind("transition", m_stack->property_transition_type());]]>
+m_settings = Gio::Settings::create("org.gtkmm.exampleapp");
+m_settings->bind("transition", m_stack->property_transition_type());
</programlisting>
<para>
@@ -7693,9 +7797,9 @@ an object property in a <classname>Gtk::TextTag</classname> that we must first c
The code is in <methodname>ExampleAppWindow::open_file_view()</methodname>.
</para>
<programlisting>
-<![CDATA[auto tag = buffer->create_tag();
-m_settings->bind("font", tag->property_font());
-buffer->apply_tag(tag, buffer->begin(), buffer->end());]]>
+auto tag = buffer->create_tag();
+m_settings->bind("font", tag->property_font());
+buffer->apply_tag(tag, buffer->begin(), buffer->end());
</programlisting>
<para>
@@ -7713,26 +7817,26 @@ class, we revisit the <methodname>ExampleApplication::on_action_preferences()</m
method in our application class, and make it open a new preference dialog.
</para>
<programlisting>
-<![CDATA[auto prefs_dialog = ExampleAppPrefs::create(*get_active_window());
-prefs_dialog->present();]]>
+auto prefs_dialog = ExampleAppPrefs::create(*get_active_window());
+prefs_dialog->present();
</programlisting>
<para>
After all this work, our application can now show a preference dialog like this:
</para>
-<figure id="figure-buildapp-pref-dialog">
+<figure xml:id="figure-buildapp-pref-dialog">
<title>An preference dialog</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_pref_dialog.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_pref_dialog.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step5">Source Code</ulink></para> <!-- Insert
exampleapp.gresource.xml prefs.ui org.gtkmm.exampleapp.gschema.xml -->
+<para><link xlink:href="&url_examples_base;buildapp/step5">Source Code</link></para> <!-- Insert
exampleapp.gresource.xml prefs.ui org.gtkmm.exampleapp.gschema.xml -->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-search-bar">
+<section xml:id="sec-buildapp-search-bar">
<title>Adding a search bar</title>
<para>
@@ -7752,41 +7856,41 @@ go over here. The central piece of the search implementation is a signal handler
listens for text changes in the search entry, shown here without error handling.
</para>
<programlisting>
-<![CDATA[void ExampleAppWindow::on_search_text_changed()
+void ExampleAppWindow::on_search_text_changed()
{
- const auto text = m_searchentry->get_text();
- auto tab = dynamic_cast<Gtk::ScrolledWindow*>(m_stack->get_visible_child());
- auto view = dynamic_cast<Gtk::TextView*>(tab->get_child());
+ const auto text = m_searchentry->get_text();
+ auto tab = dynamic_cast<Gtk::ScrolledWindow*>(m_stack->get_visible_child());
+ auto view = dynamic_cast<Gtk::TextView*>(tab->get_child());
// Very simple-minded search implementation.
- auto buffer = view->get_buffer();
+ auto buffer = view->get_buffer();
Gtk::TextIter match_start;
Gtk::TextIter match_end;
- if (buffer->begin().forward_search(text, Gtk::TextSearchFlags::CASE_INSENSITIVE,
+ if (buffer->begin().forward_search(text, Gtk::TextSearchFlags::CASE_INSENSITIVE,
match_start, match_end))
{
- buffer->select_range(match_start, match_end);
- view->scroll_to(match_start);
+ buffer->select_range(match_start, match_end);
+ view->scroll_to(match_start);
}
-}]]>
+}
</programlisting>
<para>
With the search bar, our application now looks like this:
</para>
-<figure id="figure-buildapp-search-bar">
+<figure xml:id="figure-buildapp-search-bar">
<title>Adding a search bar</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_search_bar.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_search_bar.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step6">Source Code</ulink></para> <!-- Insert window.ui -->
+<para><link xlink:href="&url_examples_base;buildapp/step6">Source Code</link></para> <!-- Insert window.ui
-->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-side-bar">
+<section xml:id="sec-buildapp-side-bar">
<title>Adding a side bar</title>
<para>
@@ -7808,32 +7912,31 @@ To connect the menu item to the new <literal>show-words</literal> setting, we us
key. In <classname>ExampleAppWindow</classname>'s constructor:
</para>
<programlisting>
-<![CDATA[// Connect the menu to the MenuButton m_gears, and bind the show-words setting
+// Connect the menu to the MenuButton m_gears, and bind the show-words setting
// to the win.show-words action and the "Words" menu item.
// (The connection between action and menu item is specified in gears_menu.ui.)
auto menu_builder = Gtk::Builder::create_from_resource("/org/gtkmm/exampleapp/gears_menu.ui");
-auto menu = menu_builder->get_object<Gio::MenuModel>("menu");
-m_gears->set_menu_model(menu);
-add_action(m_settings->create_action("show-words"));]]>
+auto menu = menu_builder->get_object<Gio::MenuModel>("menu");
+m_gears->set_menu_model(menu);
+add_action(m_settings->create_action("show-words"));
</programlisting>
<para>
What our application looks like now:
</para>
-<figure id="figure-buildapp-side-bar">
+<figure xml:id="figure-buildapp-side-bar">
<title>Adding a side bar</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_side_bar.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_side_bar.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step7">Source Code</ulink></para> <!-- Insert gears_menu.ui
window.ui org.gtkmm.exampleapp.gschema.xml -->
-
+<para><link xlink:href="&url_examples_base;buildapp/step7">Source Code</link></para> <!-- Insert
gears_menu.ui window.ui org.gtkmm.exampleapp.gschema.xml -->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-properties">
+<section xml:id="sec-buildapp-properties">
<title>Properties</title>
<para>
@@ -7860,10 +7963,10 @@ property of the <literal>lines_label</literal> widget to the same property of th
<literal>lines</literal> widget.
In <classname>ExampleAppWindow</classname>'s constructor:
</para>
-<programlisting><![CDATA[add_action(Gio::PropertyAction::create("show-lines", m_lines->property_visible()));
-m_binding_lines_visible = Glib::Binding::bind_property(m_lines->property_visible(),
- m_lines_label->property_visible());
-]]>
+<programlisting>add_action(Gio::PropertyAction::create("show-lines", m_lines->property_visible()));
+m_binding_lines_visible = Glib::Binding::bind_property(m_lines->property_visible(),
+ m_lines_label->property_visible());
+
</programlisting>
<para>
@@ -7875,18 +7978,18 @@ the <literal>lines</literal> label. See the full source if you are interested in
This brings our example application to this appearance:
</para>
-<figure id="figure-buildapp-properties">
+<figure xml:id="figure-buildapp-properties">
<title>Properties</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_properties.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_properties.png"/></imageobject></mediaobject>
</screenshot>
</figure>
-<para><ulink url="&url_examples_base;buildapp/step8">Source Code</ulink></para> <!-- Insert gears_menu.ui
window.ui -->
+<para><link xlink:href="&url_examples_base;buildapp/step8">Source Code</link></para> <!-- Insert
gears_menu.ui window.ui -->
-</sect1>
+</section>
-<sect1 id="sec-buildapp-header-bar">
+<section xml:id="sec-buildapp-header-bar">
<title>Header bar</title>
<para>
@@ -7903,19 +8006,19 @@ button, and hide the minimize and maximize buttons. We also include an icon in t
resource file, and set up this icon as the window icon.
In <classname>ExampleAppWindow</classname>'s constructor:
</para>
-<programlisting><![CDATA[Gtk::IconTheme::get_for_display(get_display())->add_resource_path("/org/gtkmm/exampleapp");
+<programlisting>Gtk::IconTheme::get_for_display(get_display())->add_resource_path("/org/gtkmm/exampleapp");
set_icon_name("exampleapp");
-]]>
+
</programlisting>
<para>
Here is how the application now looks:
</para>
-<figure id="figure-buildapp-header-bar">
+<figure xml:id="figure-buildapp-header-bar">
<title>Header bar</title>
<screenshot>
- <graphic format="PNG" fileref="&url_figures_base;buildapp_header_bar.png"/>
+ <mediaobject><imageobject><imagedata format="PNG"
fileref="&url_figures_base;buildapp_header_bar.png"/></imageobject></mediaobject>
</screenshot>
</figure>
@@ -7925,13 +8028,13 @@ That's because the stack switcher is a child of type <literal>title</literal>. T
switcher becomes a custom title that hides the title label.
</para>
-<para><ulink url="&url_examples_base;buildapp/step9">Source Code</ulink></para> <!-- Insert
exampleapp.gresource.xml window.ui -->
+<para><link xlink:href="&url_examples_base;buildapp/step9">Source Code</link></para> <!-- Insert
exampleapp.gresource.xml window.ui -->
-</sect1>
+</section>
</chapter>
-<chapter id="chapter-contributing">
+<chapter xml:id="chapter-contributing">
<title>Contributing</title>
<para>
@@ -7941,15 +8044,15 @@ any aspect of >kmm; that does not already have documentation, please
consider contributing to this document.
</para>
<para>
-Ideally, we would like you to <ulink
url="https://gitlab.gnome.org/GNOME/gtkmm-documentation/-/merge_requests";>
-provide a merge request</ulink> to the <filename>docs/tutorial/C/index-in.docbook</filename> file.
+Ideally, we would like you to <link
xlink:href="https://gitlab.gnome.org/GNOME/gtkmm-documentation/-/merge_requests";>
+provide a merge request</link> to the <filename>docs/tutorial/C/index-in.docbook</filename> file.
This file is in the <literal>gtkmm-documentation</literal> module in GNOME git.
</para>
<para>
If you do decide to contribute, please post your contribution to the
->kmm; mailing list at <ulink url="mailto:gtkmm-list gnome org"><gtkmm-list gnome org></ulink>
-or as an issue or merge request to <ulink
url="https://gitlab.gnome.org/GNOME/gtkmm-documentation";>GitLab</ulink>.
+>kmm; mailing list at <link xlink:href="mailto:gtkmm-list gnome org"><gtkmm-list gnome org></link>
+or as an issue or merge request to <link
xlink:href="https://gitlab.gnome.org/GNOME/gtkmm-documentation";>GitLab</link>.
Also, be aware that the entirety of this document is free, and any addition you provide
must also be free. That is, people must be able to use any portion of
your examples in their programs, and copies of this document
@@ -7958,8 +8061,9 @@ your examples in their programs, and copies of this document
</chapter>
-<appendix id="chapter-refptr">
+<appendix xml:id="chapter-refptr">
<title>The RefPtr smartpointer</title>
+
<para>
<classname>Glib::RefPtr</classname> is a smartpointer. Specifically, it is a
reference-counting smartpointer. You might be familiar with
@@ -7971,12 +8075,12 @@ which is reference-counting. <classname>Glib::RefPtr<></classname> was int
long before there was a reference-counting smartpointer in the C++ Standard Library.
</para>
-<para><ulink url="&url_refdocs_base_glib;RefPtr.html">Reference</ulink></para>
+<para><link xlink:href="&url_refdocs_base_glib;RefPtr.html">Reference</link></para>
<para>A smartpointer acts much like a normal pointer. Here are a few examples.</para>
-<sect1 id="sec-refptr-copying">
- <title>Copying</title>
+<section xml:id="sec-refptr-copying">
+<title>Copying</title>
<para>
You can copy <classname>RefPtr</classname>s, just like normal pointers. But
unlike normal pointers, you don't need to worry about deleting the underlying
@@ -7995,9 +8099,10 @@ std::list<Glib::RefPtr<Gdk::Pixbuf>> listPixbufs;
auto refPixbuf = Gdk::Pixbuf::create_from_file(filename);
listPixbufs.push_back(refPixbuf);
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-refptr-dereferencing"><title>Dereferencing</title>
+<section xml:id="sec-refptr-dereferencing">
+<title>Dereferencing</title>
<para>You can dereference a smartpointer with the -> operator, to
call the methods of the underlying instance, just like a normal pointer.
</para>
@@ -8014,9 +8119,10 @@ in the reference count.
auto refPixbuf = Gdk::Pixbuf::create_from_file(filename);
auto& underlying = *refPixbuf; // Possible, but not recommended
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-refptr-casting"><title>Casting</title>
+<section xml:id="sec-refptr-casting">
+<title>Casting</title>
<para>
You can cast <classname>RefPtr</classname>s to base types, just like normal
pointers.
@@ -8036,9 +8142,10 @@ a little different than with a normal pointer.
auto refStore = std::dynamic_pointer_cast<Gtk::TreeStore>(refModel);
auto refStore2 = std::static_pointer_cast<Gtk::TreeStore>(refModel);
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-refptr-checking-for-null"><title>Checking for nullptr</title>
+<section xml:id="sec-refptr-checking-for-null">
+<title>Checking for nullptr</title>
<para>
Just like normal pointers, you can check whether a
<classname>RefPtr</classname> points to anything.
@@ -8055,9 +8162,10 @@ if (refModel)
But unlike normal pointers, <classname>RefPtr</classname>s are automatically
initialized to <literal>nullptr</literal> so you don't need to remember to do that yourself.
</para>
-</sect1>
+</section>
-<sect1 id="sec-refptr-constness"><title>Constness</title>
+<section xml:id="sec-refptr-constness">
+<title>Constness</title>
<para>
The use of the <literal>const</literal> keyword in C++ is not always clear. You
might not realise that <type>const Something*</type> declares a pointer to a
@@ -8077,16 +8185,16 @@ using <classname>const std::string&</classname> instead of
<classname>std::string</classname> for a method parameter to avoid unnecessary
copying.
</para>
-</sect1>
+</section>
</appendix>
-
-<appendix id="chapter-signals">
+<appendix xml:id="chapter-signals">
<title>Signals</title>
-<sect1 id="sec-connecting-signal-handlers">
+<section xml:id="sec-connecting-signal-handlers">
<title>Connecting signal handlers</title>
+
<para>
>kmm; widget classes have signal accessor methods, such as
<methodname>Gtk::Button::signal_clicked()</methodname>, which allow you to connect
@@ -8102,11 +8210,11 @@ Here's an example of a signal handler being connected to a signal:
</para>
<programlisting>
-#include <gtkmm/button.h>
+#include <gtkmm/button.h>
void on_button_clicked()
{
- std::cout << "Hello World" << std::endl;
+ std::cout << "Hello World" << std::endl;
}
int main()
@@ -8222,9 +8330,9 @@ to a signal expecting none (unless you use an adapter, such as
know what type of signal handler you'll be expected to connect to a given
signal.
</para>
-</sect1>
+</section>
-<sect1 id="sec-writing-signal-handlers">
+<section xml:id="sec-writing-signal-handlers">
<title>Writing signal handlers</title>
<para>
@@ -8265,9 +8373,9 @@ handler's prototype could look like this:
<programlisting>
void on_insert(TextBuffer::iterator& pos, const Glib::ustring& text, int bytes)
</programlisting>
-</sect1>
+</section>
-<sect1 id="sec-disconnecting-signal-handlers">
+<section xml:id="sec-disconnecting-signal-handlers">
<title>Disconnecting signal handlers</title>
<para>
@@ -8284,8 +8392,8 @@ connection. By keeping a connection object you can disconnect its associated sig
handler using the <methodname>sigc::connection::disconnect()</methodname> method.
</para>
-</sect1>
-<sect1 id="sec-overriding-default-signal-handlers">
+</section>
+<section xml:id="sec-overriding-default-signal-handlers">
<title>Overriding default signal handlers</title>
<para>
@@ -8317,7 +8425,7 @@ Let's look at an example of overriding:
</para>
<programlisting>
-#include <gtkmm/button.h>
+#include <gtkmm/button.h>
class OverriddenButton : public Gtk::Button
{
@@ -8327,7 +8435,7 @@ protected:
void OverriddenButton::on_clicked()
{
- std::cout << "Hello World" << std::endl;
+ std::cout << "Hello World" << std::endl;
// call the base class's version of the method:
Gtk::Button::on_clicked();
@@ -8356,16 +8464,16 @@ with connected signal handlers: you can call the parent method in the <emphasis>
your custom code.
</para>
-</sect1>
+</section>
-<sect1 id="sec-binding-extra-arguments">
+<section xml:id="sec-binding-extra-arguments">
<title>Binding extra arguments</title>
+
<para>
If you use one signal handler to catch the same signal from several widgets,
you might like that signal handler to receive some extra information. For
instance, you might want to know which button was clicked. You can do this with
-<function>sigc::bind()</function>. Here's some code from the <link
- linkend="sec-helloworld2">helloworld2</link> example.
+<function>sigc::bind()</function>. Here's some code from the <link
linkend="sec-helloworld2">helloworld2</link> example.
<programlisting>
m_button1.signal_clicked().connect(sigc::bind(sigc::mem_fun(*this, &HelloWorld::on_button_clicked),
"button 1"));
</programlisting>
@@ -8387,10 +8495,11 @@ is generally overused in <application>GTK</application> to pass information
that should be stored as member data in a derived widget, but widget derivation
is very difficult in C. We have far less need of this hack in >kmm;.
</para>
-</sect1>
+</section>
-<sect1 id="sec-xeventsignals">
+<section xml:id="sec-xeventsignals">
<title>X Event signals</title>
+
<para>
The <classname>Widget</classname> class has some special signals which
correspond to the underlying X-Windows events. These are suffixed by
@@ -8437,8 +8546,9 @@ pressed. There are several different types of <type>GdkEvent</type> structures
for the various events.
</para>
-<sect2 id="signal-handler-sequence">
+<section xml:id="signal-handler-sequence">
<title>Signal Handler sequence</title>
+
<para>By default, your signal handlers are called after any previously-connected
signal handlers. However, this can be a problem with the X Event signals. For instance,
the existing signal handlers, or the default signal handler, might return <literal>true</literal>
@@ -8454,14 +8564,15 @@ button.signal_button_press_event().connect( sigc::ptr_fun(&on_mywindow_butto
signal handlers in that widget return <literal>false</literal> (indicating that
the event has not been handled), then the signal will be propagated to the parent
widget and emitted there. This continues all the way up to the top-level widget
-if no one handles the event.
+if no one handles the event.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-exceptions-in-signal-handlers">
+<section xml:id="sec-exceptions-in-signal-handlers">
<title>Exceptions in signal handlers</title>
+
<para>
When a program is aborted because of an unhandled C++ exception, it's sometimes
possible to use a debugger to find the location where the exception was thrown.
@@ -8469,7 +8580,7 @@ This is more difficult than usual if the exception was thrown from a signal hand
</para>
<para>
This section describes primarily what you can expect on a Linux system, when you
-use <ulink url="http://www.gnu.org/software/gdb/";>the gdb debugger</ulink>.
+use <link xlink:href="http://www.gnu.org/software/gdb/";>the gdb debugger</link>.
</para>
<para>
First, let's look at a simple example where an exception is thrown from a normal
@@ -8489,7 +8600,7 @@ int main(int argc, char** argv)
{
throwSomething();
auto app = Gtk::Application::create("org.gtkmm.without_signal");
- return app->run();
+ return app->run();
}
</programlisting>
<para>
@@ -8526,8 +8637,8 @@ int main(int argc, char** argv)
{
Glib::signal_timeout().connect(sigc::ptr_fun(throwSomething), 500);
auto app = Gtk::Application::create("org.gtkmm.with_signal");
- app->hold();
- return app->run();
+ app->hold();
+ return app->run();
}
</programlisting>
<para>
@@ -8589,13 +8700,13 @@ These commands will print a backtrace from each <code>throw</code> and continue.
The backtrace from the last (or possibly the last but one) <code>throw</code>
before the program stops, is the interesting one.
</para>
-</sect1>
+</section>
</appendix>
-
-<appendix id="chapter-custom-signals">
+<appendix xml:id="chapter-custom-signals">
<title>Creating your own signals</title>
+
<para>
Now that you've seen signals and signal handlers in >kmm;, you
might like to use the same technique to allow interaction between your
@@ -8649,21 +8760,23 @@ server.signal_something().connect(
sigc::mem_fun(client, &Client::on_server_something) );
</programlisting>
-<sect1 id="chapter-custom-signals-example"><title>Example</title>
+<section xml:id="chapter-custom-signals-example">
+<title>Example</title>
<para>
This is a full working example that defines and uses custom signals.
</para>
-<para><ulink url="&url_examples_base;signals/custom/">Source Code</ulink></para>
+<para><link xlink:href="&url_examples_base;signals/custom/">Source Code</link></para>
-</sect1>
+</section>
</appendix>
-<appendix id="sec-signals-comparison">
+<appendix xml:id="sec-signals-comparison">
<title>Comparison with other signalling systems</title>
+
<para>
<!-- TODO: Rewrite this paragraph and talk about Qt's moc. -->
(An aside: <application>GTK</application> calls this scheme "signalling"; the
@@ -8702,8 +8815,8 @@ practical - and sensible - to subclass a button for that purpose.
</para>
</appendix>
-<appendix id="sec-windows-installation">
- <title>>kmm; and Win32</title>
+<appendix xml:id="sec-windows-installation">
+<title>>kmm; and Win32</title>
<para>
One of the major advantages of >kmm; is that it is crossplatform. >kmm; programs written on other
platforms such as
GNU/Linux can generally be transferred to Windows (and vice
@@ -8711,25 +8824,25 @@ practical - and sensible - to subclass a button for that purpose.
</para>
<para>
>kmm; currently works with the
- <ulink url="http://mingw.org/";>MinGW/GCC compiler</ulink> with a compiler version
+ <link xlink:href="http://mingw.org/";>MinGW/GCC compiler</link> with a compiler version
that supports C++17, such as gcc 7 or 8. It also works with Microsoft
Visual C++ 2017 15.7.x or later (including the freely available express/community
editions) on the Windows platform. There is an
- <ulink url="ftp://ftp.gnome.org/pub/GNOME/binaries/win32/gtkmm";>installer</ulink>
+ <link xlink:href="ftp://ftp.gnome.org/pub/GNOME/binaries/win32/gtkmm";>installer</link>
available for >kmm; on Microsoft Windows, but as of this writing
(October 2020) it has not been updated for a long time.
Please be aware that although normally it is fine to mix builds done with
Visual Studio 2017 and 2019, please do not do so when building
>kmm; with its -mm dependencies.
</para>
- <para>Refer to the <ulink url="&url_gtkmm_base;README.win32">README.win32</ulink>,
- as well as the <ulink url="&url_gtkmm_base;MSVC_NMake/README">README</ulink>
+ <para>Refer to the <link xlink:href="&url_gtkmm_base;README.win32">README.win32</link>,
+ as well as the <link xlink:href="&url_gtkmm_base;MSVC_NMake/README">README</link>
files in the >kmm;, pangomm and glibmm for instructions on how to build >kmm; on Windows.
</para>
</appendix>
-<appendix id="chapter-working-with-source">
- <title>Working with gtkmm's Source Code</title>
+<appendix xml:id="chapter-working-with-source">
+<title>Working with gtkmm's Source Code</title>
<para>
If you are interested in helping out with the development of >kmm;, or
fixing a bug in >kmm;, you'll probably need to build the development
@@ -8738,15 +8851,13 @@ practical - and sensible - to subclass a button for that purpose.
installation, in a separate path.
</para>
<para>
- The easiest way to do this is using <ulink
- url="https://wiki.gnome.org/Projects/Jhbuild";>jhbuild</ulink>.
+ The easiest way to do this is using <link
xlink:href="https://wiki.gnome.org/Projects/Jhbuild";>jhbuild</link>.
<application>jhbuild</application> is a program that makes building GNOME
software much easier by calculating dependencies and building things in the
correct order. This section will give a brief explanation of how to set up
<application>jhbuild</application> to build and install >kmm; from the
source repository (git). For up-to-date information
- on <application>jhbuild</application>, please refer to the <ulink
- url="http://developer.gnome.org/jhbuild/unstable/";>jhbuild manual</ulink>.
+ on <application>jhbuild</application>, please refer to the <link
xlink:href="http://developer.gnome.org/jhbuild/unstable/";>jhbuild manual</link>.
</para>
<note>
<para>
@@ -8760,15 +8871,15 @@ practical - and sensible - to subclass a button for that purpose.
<para>
<application>gnome-build-meta</application> is an alternative to
<application>jhbuild</application>. It is described at the
- <ulink url="https://wiki.gnome.org/Newcomers/BuildSystemComponent";>Building system components</ulink>
+ <link xlink:href="https://wiki.gnome.org/Newcomers/BuildSystemComponent";>Building system
components</link>
wiki page, but here we concentrate on <application>jhbuild</application>.
</para>
- <sect1 id="sec-setting-up-jhbuild">
- <title>Setting up jhbuild</title>
+ <section xml:id="sec-setting-up-jhbuild">
+ <title>Setting up jhbuild</title>
+
<para>
To set up <application>jhbuild</application>, follow the basic
- installation instructions from the <ulink
- url="http://developer.gnome.org/jhbuild/unstable/";>jhbuild manual</ulink>.
+ installation instructions from the <link
xlink:href="http://developer.gnome.org/jhbuild/unstable/";>jhbuild manual</link>.
After you have installed <application>jhbuild</application>, you
should copy the sample <application>jhbuild</application> configuration
file into your home directory by executing the following command from the
@@ -8820,9 +8931,10 @@ practical - and sensible - to subclass a button for that purpose.
If you don't want it, use the <varname>use_local_modulesets</varname>
variable in <filename>.jhbuildrc</filename>.
</para>
- </sect1>
- <sect1 id="sec-installing-jhbuild">
- <title>Installing and Using the git version of >kmm;</title>
+ </section>
+ <section xml:id="sec-installing-jhbuild">
+ <title>Installing and Using the git version of >kmm;</title>
+
<para>
Once you've configured <application>jhbuild</application> as described
above, building >kmm; should be relatively straightforward. The first
@@ -8833,8 +8945,9 @@ practical - and sensible - to subclass a button for that purpose.
<screen>$ jhbuild bootstrap
$ jhbuild sanitycheck</screen>
</para>
- <sect2 id="jhbuild-installing-gtkmm">
- <title>Installing >kmm; with <application>jhbuild</application></title>
+ <section xml:id="jhbuild-installing-gtkmm">
+ <title>Installing >kmm; with <application>jhbuild</application></title>
+
<para>
If everything worked correctly, you should be able to build >kmm; and
all of its dependencies from git by executing <command>jhbuild
@@ -8851,9 +8964,10 @@ $ jhbuild sanitycheck</screen>
itself (without rebuilding all of its dependencies) with the command
<command>jhbuild buildone gtkmm</command>.
</para>
- </sect2>
- <sect2 id="jhbuild-using-gtkmm">
- <title>Using the git version of >kmm;</title>
+ </section>
+ <section xml:id="jhbuild-using-gtkmm">
+ <title>Using the git version of >kmm;</title>
+
<para>
After you've installed the git version of >kmm;, you're ready to start
using and experimenting with it. In order to use the new version of
@@ -8880,12 +8994,13 @@ $ jhbuild sanitycheck</screen>
will return to your previous environment after the program exits.
</para>
- </sect2>
- </sect1>
+ </section>
+ </section>
</appendix>
-<appendix id="chapter-wrapping-c-libraries">
+<appendix xml:id="chapter-wrapping-c-libraries">
<title>Wrapping C Libraries with gmmproc</title>
+
<para>>kmm; uses the <command>gmmproc</command> tool to generate most of its
source code, using .defs files that define the APIs of
<classname>GObject</classname>-based libraries. So it's quite easy to create
@@ -8895,8 +9010,9 @@ $ jhbuild sanitycheck</screen>
they work, and has been used successfully by several
projects.</para>
-<sect1 id="sec-wrapping-build-structure">
+<section xml:id="sec-wrapping-build-structure">
<title>The build structure</title>
+
<para>Generation of the source code for a gtkmm-style wrapper API requires use
of tools such as <command>gmmproc</command> and
<filename>generate_wrap_init.pl</filename>, which are included in
@@ -8910,14 +9026,14 @@ $ jhbuild sanitycheck</screen>
types named, for instance, <classname>SomeWidget</classname> and
<classname>SomeStuff</classname>.</para>
-<sect2 id="copying-skeleton-project">
+<section xml:id="copying-skeleton-project">
<title>Copying the skeleton project</title>
<para>Typically our wrapper library would be called libsomethingmm. We can start by
- copying the <ulink url="https://gitlab.gnome.org/GNOME/mm-common/tree/master/skeletonmm";>
- skeleton source tree</ulink> from the <application>mm-common</application> module.
+ copying the <link xlink:href="https://gitlab.gnome.org/GNOME/mm-common/tree/master/skeletonmm";>
+ skeleton source tree</link> from the <application>mm-common</application> module.
Starting with <application>mm-common</application> 1.0.0 this skeleton application
- is built with the <ulink url="https://mesonbuild.com/";>Meson build system</ulink>.
+ is built with the <link xlink:href="https://mesonbuild.com/";>Meson build system</link>.
</para>
<programlisting>
$ git clone https://gitlab.gnome.org/GNOME/mm-common.git
@@ -8956,9 +9072,9 @@ A number of the skeleton files must still be filled in with project-specific con
replacing some variables with actual values during the configure stage.</para>
<para>Generated files are saved in the build tree, which is separated from the
source tree when <command>meson</command> and <command>ninja</command> are used.</para>
-</sect2>
+</section>
-<sect2 id="modifying-build-files">
+<section xml:id="modifying-build-files">
<title>Modifying build files</title>
<para>Now we edit the files to adapt them to our needs. You might prefer to use a multiple-file
@@ -8973,8 +9089,9 @@ A number of the skeleton files must still be filled in with project-specific con
copyright holder, which is probably you. Do the same for the <varname>joe example com</varname>
email address.</para>
-<sect3 id="modifying-top-meson.build">
+<section xml:id="modifying-top-meson.build">
<title>meson.build in the top-level directory</title>
+
<para>
<itemizedlist>
<listitem><para>It is common for binding modules to track the version number
@@ -8989,10 +9106,11 @@ A number of the skeleton files must still be filled in with project-specific con
(<application>libsomething</application>).</para></listitem>
</itemizedlist>
</para>
-</sect3>
+</section>
-<sect3 id="modifying-other-meson.build">
+<section xml:id="modifying-other-meson.build">
<title>Other meson.build files</title>
+
<para>Next we must adapt the other <filename>meson.build</filename> files:
<itemizedlist>
<listitem><para><filename>skeleton/meson.build</filename>: Perhaps not much
@@ -9019,22 +9137,24 @@ A number of the skeleton files must still be filled in with project-specific con
</listitem>
</itemizedlist>
</para>
-</sect3>
+</section>
-<sect3 id="creating-hg-ccg">
+<section xml:id="creating-hg-ccg">
<title>Creating .hg and .ccg files</title>
+
<para>We should now create our first <filename>.hg</filename> and <filename>.ccg</filename> files,
to wrap one of the objects in the C library. One pair of example source files already exists:
<filename>skeleton.ccg</filename> and <filename>skeleton.hg</filename>. Create copies of these
files as necessary.</para>
<para>In the <link linkend="sec-wrapping-hg-files">.hg and .ccg files</link>
section you can learn about the syntax used in these files.</para>
-</sect3>
-</sect2>
-</sect1>
+</section>
+</section>
+</section>
-<sect1 id="sec-wrapping-defs-files">
+<section xml:id="sec-wrapping-defs-files">
<title>Generating the .defs files.</title>
+
<para>The <filename>.defs</filename> files are text files, in a lisp format, that describe the API
of a C library, including its
<itemizedlist>
@@ -9078,8 +9198,9 @@ generates all <filename>.defs</filename> files and the <filename>*_docs.xml</fil
described in the <link linkend="sec-wrapping-documentation">Documentation</link> section.
</para>
-<sect2 id="generating-defs-methods">
+<section xml:id="generating-defs-methods">
<title>Generating the methods .defs</title>
+
<para>This <filename>.defs</filename> file describes objects and their functions.
It is generated by the <command>h2def.py</command> script which you can find in
glibmm's <filename>tools/defs_gen</filename> directory. For instance,
@@ -9087,10 +9208,11 @@ described in the <link linkend="sec-wrapping-documentation">Documentation</link>
<programlisting>
$ ./h2def.py /usr/include/gtk-4.0/gtk/*.h > gtk_methods.defs
</programlisting>
-</sect2>
+</section>
-<sect2 id="generating-defs-enums">
+<section xml:id="generating-defs-enums">
<title>Generating the enums .defs</title>
+
<para>This <filename>.defs</filename> file describes enum types and their possible
values. It is generated by the <filename>enum.pl</filename> script which you can
find in glibmm's <filename>tools</filename> directory. For instance,
@@ -9098,10 +9220,11 @@ $ ./h2def.py /usr/include/gtk-4.0/gtk/*.h > gtk_methods.defs
<programlisting>
$ ./enum.pl /usr/include/gtk-4.0/gtk/*.h > gtk_enums.defs
</programlisting>
-</sect2>
+</section>
-<sect2 id="generating-defs-signals-properties">
+<section xml:id="generating-defs-signals-properties">
<title>Generating the signals and properties .defs</title>
+
<para>This <filename>.defs</filename> file describes signals and properties. It is
generated by the special <filename>generate_extra_defs</filename> utility that is in every
wrapping project, such as <filename>gtkmm/tools/extra_defs_gen/</filename>.
@@ -9135,22 +9258,23 @@ int main(int, char**)
return 0;
}
</programlisting>
-</sect2>
+</section>
-<sect2 id="writing-defs-vfuncs">
+<section xml:id="writing-defs-vfuncs">
<title>Writing the vfuncs .defs</title>
+
<para>
This <filename>.defs</filename> file describes virtual functions (vfuncs).
It must be written by hand. There is the skeleton file
<filename>skeleton/src/skeleton_vfunc.defs</filename> to start from. You can also look
at >kmm;'s <filename>gtk/src/gtk_vfuncs.defs</filename> file.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
-<sect1 id="sec-wrapping-hg-files">
- <title>The .hg and .ccg files</title>
+<section xml:id="sec-wrapping-hg-files">
+<title>The .hg and .ccg files</title>
<para>The .hg and .ccg source files are very much like
.h and .cc C++ source files, but they contain extra macros, such as
<function>_CLASS_GOBJECT()</function> and
@@ -9245,8 +9369,9 @@ $ /usr/lib/glibmm-2.68/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtk
<para>The macros are explained in more detail in the following sections.</para>
-<sect2 id="gmmproc-m4-conversions">
+<section xml:id="gmmproc-m4-conversions">
<title>m4 Conversions</title>
+
<para>The macros that you use in the .hg and .ccg files often need to know how
to convert a C++ type to a C type, or vice-versa. <command>gmmproc</command> takes this information
from an .m4 file in your <literal>tools/m4/</literal> or <literal>codegen/m4/</literal> directory.
@@ -9272,10 +9397,11 @@ _CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P)
_CONVERSION(`const PrintSettings&',`GtkPrintSettings*',__FCR2P)
_CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REFPTR_TO_P($3))
</programlisting>
-</sect2>
+</section>
-<sect2 id="gmmproc-m4-initializations">
+<section xml:id="gmmproc-m4-initializations">
<title>m4 Initializations</title>
+
<para>
Often when wrapping methods, it is desirable to store the return of the C
function in what is called an output parameter. In this case, the C++ method
@@ -9303,11 +9429,11 @@ _INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
<literal>$1</literal> will also be replaced by the C++ type without the
ampersand (&) and <literal>$2</literal> will be replaced by the C type.
</para>
-</sect2>
-
+</section>
-<sect2 id="gmmproc-class-macros">
+<section xml:id="gmmproc-class-macros">
<title>Class macros</title>
+
<para>The class macro declares the class itself and its relationship with the
underlying C type. It generates some internal constructors, the member
<varname>gobject_</varname>, typedefs, the <function>gobj()</function>
@@ -9317,8 +9443,9 @@ _INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
<function>_WRAP_SIGNAL()</function> may only be used after a call to a
<function>_CLASS_*</function> macro.</para>
-<sect3 id="gmmproc-class-gobject">
+<section xml:id="gmmproc-class-gobject">
<title>_CLASS_GOBJECT</title>
+
<para>This macro declares a wrapper for a type that is derived from
<classname>GObject</classname>, but whose wrapper is not derived from
<classname>Gtk::Object</classname>.</para>
@@ -9327,10 +9454,11 @@ _INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
<programlisting>
_CLASS_GOBJECT(Adjustment, GtkAdjustment, GTK_ADJUSTMENT, Glib::Object, GObject)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-gtkobject">
+<section xml:id="gmmproc-class-gtkobject">
<title>_CLASS_GTKOBJECT</title>
+
<para>This macro declares a wrapper for a type whose wrapper is derived from
<classname>Gtk::Object</classname>, such as a widget or dialog.</para>
<para><function>_CLASS_GTKOBJECT( C++ class, C class, C casting macro, C++ base class, C base class
)</function></para>
@@ -9349,10 +9477,11 @@ _CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Widget, GtkWidget)
as a member variable. This is convenient, but you should use this only when
you are sure that true reference-counting is not needed. We consider it
useful for widgets.</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-boxedtype">
+<section xml:id="gmmproc-class-boxedtype">
<title>_CLASS_BOXEDTYPE</title>
+
<para>This macro declares a wrapper for a non-<classname>GObject</classname>
struct, registered with
<function>g_boxed_type_register_static()</function>.</para>
@@ -9361,10 +9490,11 @@ _CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Widget, GtkWidget)
<programlisting>
_CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-boxedtype-static">
+<section xml:id="gmmproc-class-boxedtype-static">
<title>_CLASS_BOXEDTYPE_STATIC</title>
+
<para>This macro declares a wrapper for a simple assignable struct such as
<classname>GdkRectangle</classname>. It is similar to
<function>_CLASS_BOXEDTYPE</function>, but the C struct is not allocated
@@ -9374,10 +9504,11 @@ _CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)
<programlisting>
_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-opaque-copyable">
+<section xml:id="gmmproc-class-opaque-copyable">
<title>_CLASS_OPAQUE_COPYABLE</title>
+
<para>This macro declares a wrapper for an opaque struct that has copy and free
functions. The new, copy and free functions will be used to instantiate the
default constructor, copy constructor and destructor.</para>
@@ -9386,10 +9517,11 @@ _CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
<programlisting>
_CLASS_OPAQUE_COPYABLE(VariantType, GVariantType, NONE, g_variant_type_copy, g_variant_type_free)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-opaque-refcounted">
+<section xml:id="gmmproc-class-opaque-refcounted">
<title>_CLASS_OPAQUE_REFCOUNTED</title>
+
<para>This macro declares a wrapper for a reference-counted opaque struct. The
C++ wrapper cannot be directly instantiated and can only be used with
<classname>Glib::RefPtr</classname>.</para>
@@ -9398,10 +9530,11 @@ _CLASS_OPAQUE_COPYABLE(VariantType, GVariantType, NONE, g_variant_type_copy, g_v
<programlisting>
_CLASS_OPAQUE_REFCOUNTED(CssSection, GtkCssSection, NONE, gtk_css_section_ref, gtk_css_section_unref)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-generic">
+<section xml:id="gmmproc-class-generic">
<title>_CLASS_GENERIC</title>
+
<para>This macro can be used to wrap structs which don't fit into any
specialized category.</para>
<para><function>_CLASS_GENERIC( C++ class, C class )</function></para>
@@ -9409,10 +9542,11 @@ _CLASS_OPAQUE_REFCOUNTED(CssSection, GtkCssSection, NONE, gtk_css_section_ref, g
<programlisting>
_CLASS_GENERIC(TimeCoord, GdkTimeCoord)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-class-interface">
+<section xml:id="gmmproc-class-interface">
<title>_CLASS_INTERFACE</title>
+
<para>This macro declares a wrapper for a type that is derived from
<classname>GTypeInterface</classname>.
</para>
@@ -9431,12 +9565,13 @@ For instance, from <filename>loadableicon.hg</filename> in glibmm-2.4:</para>
<programlisting>
_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)
</programlisting>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="gmmproc-constructor-macros">
+<section xml:id="gmmproc-constructor-macros">
<title>Constructor macros</title>
+
<para>The <function>_CTOR_DEFAULT()</function> and
<function>_WRAP_CTOR()</function> macros add constructors, wrapping the
specified <function>*_new()</function> C functions. These macros assume that
@@ -9464,14 +9599,16 @@ public:
_WRAP_CREATE(const Glib::ustring& name, bool left_gravity = true)
</programlisting>
-<sect3 id="gmmproc-ctor-default">
+<section xml:id="gmmproc-ctor-default">
<title>_CTOR_DEFAULT</title>
+
<para>This macro creates a default constructor with no arguments.
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-ctor">
+<section xml:id="gmmproc-wrap-ctor">
<title>_WRAP_CTOR</title>
+
<para>This macro creates a constructor with arguments, equivalent to a
<function>*_new()</function> C function. It won't actually call the
<function>*_new()</function> function, but will simply create an equivalent
@@ -9490,10 +9627,11 @@ public:
</varlistentry>
</variablelist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-ctor-manual">
+<section xml:id="gmmproc-ctor-manual">
<title>Hand-coding constructors</title>
+
<para>When a constructor must be partly hand written because, for instance, the
<function>*_new()</function> C function's parameters do not correspond
directly to object properties, or because the <function>*_new()</function> C
@@ -9508,28 +9646,31 @@ Button::Button(const Glib::ustring& label, bool mnemonic)
_CONSTRUCT("label", label.c_str(), "use_underline", gboolean(mnemonic))
{}
</programlisting>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="gmmproc-suppressing-macros">
+<section xml:id="gmmproc-suppressing-macros">
<title>Macros that suppress generation of some code</title>
+
<para>Some macros suppress the generation of some code when they are used after
a <function>_CLASS_*</function> macro. Some suppress the definition in the
generated .cc file, others suppress both the declaration in the .h file and
the definition in the .cc file.
</para>
-<sect3 id="gmmproc-custom-default-ctor">
+<section xml:id="gmmproc-custom-default-ctor">
<title>_CUSTOM_DEFAULT_CTOR</title>
+
<para>Suppresses declaration and definition of default constructor in
<function>_CLASS_BOXEDTYPE</function>, <function>_CLASS_BOXEDTYPE_STATIC</function>
and <function>_CLASS_OPAQUE_COPYABLE</function>.
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-custom-ctor-cast">
+<section xml:id="gmmproc-custom-ctor-cast">
<title>_CUSTOM_CTOR_CAST</title>
+
<para>Suppresses declaration and definition of the constructor that takes a pointer
to the wrapped C object in <function>_CLASS_BOXEDTYPE</function> and
<function>_CLASS_BOXEDTYPE_STATIC</function>.
@@ -9542,17 +9683,19 @@ wrapped C object in <function>_CLASS_INTERFACE</function> and
wrapped C object and the constructor that takes construct_params in
<function>_CLASS_GOBJECT</function> and <function>_CLASS_GTKOBJECT</function>.
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-custom-dtor">
+<section xml:id="gmmproc-custom-dtor">
<title>_CUSTOM_DTOR</title>
+
<para>Suppresses definition of destructor in
<function>_CLASS_GOBJECT</function> and <function>_CLASS_GTKOBJECT</function>.
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-custom-move-operations">
+<section xml:id="gmmproc-custom-move-operations">
<title>_CUSTOM_MOVE_OPERATIONS</title>
+
<para>Suppresses declaration and definition of move constructor and move
assignment operator in <function>_CLASS_GOBJECT</function> and
<function>_CLASS_GTKOBJECT</function>.
@@ -9571,38 +9714,42 @@ public:
// ...
};
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-custom-wrap-new">
+<section xml:id="gmmproc-custom-wrap-new">
<title>_CUSTOM_WRAP_NEW</title>
+
<para>Suppresses definition of <function>Glib::wrap_new()</function> function in
<function>_CLASS_GOBJECT</function>.
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-custom-wrap-function">
+<section xml:id="gmmproc-custom-wrap-function">
<title>_CUSTOM_WRAP_FUNCTION</title>
+
<para>Suppresses definition of <function>Glib::wrap()</function> function in
<function>_CLASS_GOBJECT</function> and <function>_CLASS_GTKOBJECT</function>.
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-no-wrap-function">
+<section xml:id="gmmproc-no-wrap-function">
<title>_NO_WRAP_FUNCTION</title>
+
<para>Suppresses declaration and definition of <function>Glib::wrap()</function>
function in <function>_CLASS_GOBJECT</function>, <function>_CLASS_BOXEDTYPE</function>,
<function>_CLASS_BOXEDTYPE_STATIC</function>, <function>_CLASS_OPAQUE_COPYABLE</function>,
<function>_CLASS_INTERFACE</function> and <function>_CLASS_GTKOBJECT</function>.
</para>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="gmmproc-method-macros">
+<section xml:id="gmmproc-method-macros">
<title>Method macros</title>
-<sect3 id="gmmproc-wrap-method">
+<section xml:id="gmmproc-wrap-method">
<title>_WRAP_METHOD</title>
+
<para>This macro generates the C++ method to wrap a C function.</para>
<para><function>_WRAP_METHOD( C++ method signature, C function name)</function></para>
<para>For instance, from <filename>entry.hg</filename>:</para>
@@ -9731,10 +9878,11 @@ _WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
<programlisting>#m4
_CONVERSION(`GSList*',`std::vector<Widget*>',`Glib::SListHandler<Widget*>::slist_to_vector($3,
Glib::OWNERSHIP_SHALLOW)')</programlisting></para></listitem>
</itemizedlist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-method-docs-only">
+<section xml:id="gmmproc-wrap-method-docs-only">
<title>_WRAP_METHOD_DOCS_ONLY</title>
+
<para>This macro is like <function>_WRAP_METHOD()</function>, but it generates
only the documentation for a C++ method that wraps a C function. Use this
when you must hand-code the method, but you want to use the documentation
@@ -9776,10 +9924,11 @@ _WRAP_METHOD_DOCS_ONLY(gtk_recent_info_get_applications)
</varlistentry>
</variablelist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-ignore">
+<section xml:id="gmmproc-ignore">
<title>_IGNORE, _IGNORE_SIGNAL, _IGNORE_PROPERTY</title>
+
<para><command>gmmproc</command> will warn you on stdout about functions, signals,
properties and child properties that you have forgotten to wrap, helping to
ensure that you are wrapping the complete API. But if you don't want to wrap
@@ -9788,7 +9937,7 @@ _WRAP_METHOD_DOCS_ONLY(gtk_recent_info_get_applications)
or _IGNORE_PROPERTY() macro to make <command>gmmproc</command> stop complaining.
</para>
<para>
-<literallayout><function>_IGNORE(C function name 1, C function name 2, etc)
+<literallayout class="normal"><function>_IGNORE(C function name 1, C function name 2, etc)
_IGNORE_SIGNAL(C signal name 1, C signal name 2, etc)
_IGNORE_PROPERTY(C property name 1, C property name 2, etc)</function></literallayout>
</para>
@@ -9797,10 +9946,11 @@ _IGNORE_PROPERTY(C property name 1, C property name 2, etc)</function></literall
_IGNORE(gtk_flow_box_set_filter_func, gtk_flow_box_set_sort_func)
_IGNORE_SIGNAL(activate-cursor-child, toggle-cursor-child, move-cursor)
</programlisting>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-signal">
+<section xml:id="gmmproc-wrap-signal">
<title>_WRAP_SIGNAL</title>
+
<para>This macro generates the C++ libsigc++-style signal to wrap a C GObject
signal. It actually generates a public accessor method, such as
<function>signal_clicked()</function>, which returns a proxy object.
@@ -9903,10 +10053,11 @@ _WRAP_SIGNAL(void clicked(),"clicked")
</varlistentry>
</variablelist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-property">
+<section xml:id="gmmproc-wrap-property">
<title>_WRAP_PROPERTY</title>
+
<para>This macro generates the C++ method to wrap a C GObject property. You must
specify the property name and the wanted C++ type for the property. <command>gmmproc</command>
uses the .defs file to discover the C type and the .m4 convert files to
@@ -9934,10 +10085,11 @@ _WRAP_PROPERTY("label", Glib::ustring)
</varlistentry>
</variablelist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-vfunc">
+<section xml:id="gmmproc-wrap-vfunc">
<title>_WRAP_VFUNC</title>
+
<para>This macro generates the C++ method to wrap a virtual C function.</para>
<para><function>_WRAP_VFUNC( C++ method signature, C function name)</function></para>
<para>For instance, from <filename>widget.hg</filename>:</para>
@@ -10069,14 +10221,16 @@ _WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)
<classname>Glib::RefPtr<></classname> object. One of the extra
arguments <parameter>refreturn</parameter> or
<parameter>refreturn_ctype</parameter> is required.</para>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="gmmproc-other-macros">
+<section xml:id="gmmproc-other-macros">
<title>Other macros</title>
-<sect3 id="gmmproc-implements-interface">
+
+<section xml:id="gmmproc-implements-interface">
<title>_IMPLEMENTS_INTERFACE</title>
+
<para>This macro generates initialization code for the interface.</para>
<para><function>_IMPLEMENTS_INTERFACE(C++ interface name)</function></para>
<para>For instance, from <filename>grid.hg</filename>:</para>
@@ -10093,10 +10247,11 @@ _IMPLEMENTS_INTERFACE(Orientable)
</varlistentry>
</variablelist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-enum">
+<section xml:id="gmmproc-wrap-enum">
<title>_WRAP_ENUM</title>
+
<para>This macro generates a C++ enum to wrap a C enum. You must specify the desired C++ name and
the name of the underlying C enum.</para>
<para>For instance, from <filename>enums.hg</filename>:</para>
@@ -10173,10 +10328,11 @@ _WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
</varlistentry>
</variablelist>
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-enum-docs-only">
+<section xml:id="gmmproc-wrap-enum-docs-only">
<title>_WRAP_ENUM_DOCS_ONLY</title>
+
<para>This macro just generates a Doxygen documentationn block for the enum.
This is useful for enums that can't be wrapped with
<function>_WRAP_ENUM()</function> because they are complexly defined (maybe
@@ -10186,10 +10342,11 @@ _WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
NO_GTYPE, gtype_func <function_name> and CONV_TO_INT are ignored because
they make no difference when just generating the enum's documentation).
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-wrap-gerror">
+<section xml:id="gmmproc-wrap-gerror">
<title>_WRAP_GERROR</title>
+
<para>This macro generates a C++ exception class, derived from <classname>Glib::Error</classname>, with
a <type>Code</type> enum and a <methodname>code()</methodname> method. You must specify the desired C++
name, the name
of the corresponding C enum, and the prefix for the C enum values.</para>
@@ -10202,10 +10359,10 @@ _WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)
<para>_WRAP_GERROR() accepts the same optional arguments as _WRAP_ENUM() (though
CONV_TO_INT is ignored because all exception class enums are plain enums within a class).
</para>
-</sect3>
+</section>
-<sect3 id="gmmproc-member-set-get">
- <title>_MEMBER_GET / _MEMBER_SET</title>
+<section xml:id="gmmproc-member-set-get">
+<title>_MEMBER_GET / _MEMBER_SET</title>
<para>
Use these macros if you're wrapping a simple struct or boxed type that provides
direct access to its data members, to create getters and setters for the data members.
@@ -10216,9 +10373,10 @@ CONV_TO_INT is ignored because all exception class enums are plain enums within
For example, in <filename>rectangle.hg</filename>:
</para>
<programlisting>_MEMBER_GET(x, x, int, int)</programlisting>
-</sect3>
-<sect3 id="gmmproc-member-get-set-ptr">
- <title>_MEMBER_GET_PTR / _MEMBER_SET_PTR</title>
+</section>
+
+<section xml:id="gmmproc-member-get-set-ptr">
+<title>_MEMBER_GET_PTR / _MEMBER_SET_PTR</title>
<para>
Use these macros to automatically provide getters and setters for a data
member that is a pointer type. For the getter function, it will
@@ -10232,9 +10390,10 @@ CONV_TO_INT is ignored because all exception class enums are plain enums within
// _MEMBER_GET_PTR(engine_lang, lang_engine, EngineLang*, PangoEngineLang*)
// It's just a comment. It's difficult to find a real-world example.
</programlisting>
-</sect3>
-<sect3 id="gmmproc-member-get-set-gobject">
- <title>_MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT</title>
+</section>
+
+<section xml:id="gmmproc-member-get-set-gobject">
+<title>_MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT</title>
<para>
Use these macros to provide getters and setters for a data member that is a
<classname>GObject</classname> type that must be referenced before being
@@ -10246,20 +10405,21 @@ CONV_TO_INT is ignored because all exception class enums are plain enums within
<programlisting>
_MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
</programlisting>
-</sect3>
+</section>
-</sect2>
+</section>
-<sect2 id="gmmproc-parameter-processing">
- <title>gmmproc Parameter Processing</title>
+<section xml:id="gmmproc-parameter-processing">
+<title>gmmproc Parameter Processing</title>
<para><command>gmmproc</command> allows processing the parameters in a method
signature for the macros that process method signatures (like
<function>_WRAP_METHOD()</function>, <function>_WRAP_CTOR()</function> and
<function>_WRAP_CREATE()</function>) in a variety of ways:
</para>
- <sect3 id="gmmproc-parameter-reordering">
- <title>Parameter Reordering</title>
+ <section xml:id="gmmproc-parameter-reordering">
+ <title>Parameter Reordering</title>
+
<para>
For all the macros that process method signatures, it is possible to
specify a different order for the C++ parameters than the existing order
@@ -10299,10 +10459,11 @@ _WRAP_METHOD(void set_device_events(Gdk::EventMask events{.},
It's how the utility is written presently.
</para>
</warning>
- </sect3>
+ </section>
+
+ <section xml:id="gmmproc-optional-parameter-processing">
+ <title>Optional Parameter Processing</title>
- <sect3 id="gmmproc-optional-parameter-processing">
- <title>Optional Parameter Processing</title>
<para>
For all macros processing method signatures except
<function>_WRAP_SIGNAL()</function> and
@@ -10327,10 +10488,11 @@ _WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring& label{?}
In this case, two constructors would be generated: One with the optional
parameter and one without it.
</para>
- </sect3>
+ </section>
+
+ <section xml:id="gmmproc-output-parameter-processing">
+ <title>Output Parameter Processing</title>
- <sect3 id="gmmproc-output-parameter-processing">
- <title>Output Parameter Processing</title>
<para>
With <function>_WRAP_METHOD()</function> it is also possible for the
return of the wrapped C function (if it has one) to be placed in an
@@ -10378,10 +10540,10 @@ gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
following <function>_WRAP_METHOD()</function> macro could be used:
<programlisting>
_WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path,
- const CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
+ const CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
gtk_icon_view_get_cell_rect)
</programlisting>
- The <literal>{>>}</literal> following the <parameter>rect</parameter>
+ The <literal>{>>}</literal> following the <parameter>rect</parameter>
parameter name indicates that the C++ output parameter should be set from
the value returned in the C parameter from the C function.
<command>gmmproc</command> will generate a declaration of a temporary
@@ -10395,10 +10557,11 @@ _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path,
_INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle',`$3 = Glib::wrap(&($4))')
</programlisting>
</para>
- </sect3>
+ </section>
+
+ <section xml:id="gmmproc-string-parameter-processing">
+ <title>String Parameter Processing</title>
- <sect3 id="gmmproc-string-parameter-processing">
- <title>String Parameter Processing</title>
<para>
A string-valued input parameter in a C++ method is usually a
<type>const Glib::ustring&</type> or a <type>const std::string&</type>.
@@ -10423,18 +10586,18 @@ _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle',`$3 = Glib::wrap(&($4))
append both a C parameter name and <literal>NULL</literal>, separate them
with a space: <literal>{c_param_name NULL}</literal>.
</para>
- </sect3>
+ </section>
-</sect2>
+</section>
-<sect2 id="gmmproc-basic-types">
- <title>Basic Types</title>
+<section xml:id="gmmproc-basic-types">
+<title>Basic Types</title>
<para>Some of the basic types that are used in C APIs have better alternatives
in C++. For example, there's no need for a <type>gboolean</type> type since
C++ has <type>bool</type>. The following list shows some commonly-used
types in C APIs and what you might convert them to in a C++ wrapper library.
</para>
- <segmentedlist><title>Basic Type equivalents</title>
+ <segmentedlist>
<?dbhtml list-presentation="table"?>
<segtitle>C type</segtitle>
<segtitle>C++ type</segtitle>
@@ -10445,12 +10608,12 @@ _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle',`$3 = Glib::wrap(&($4))
<seglistitem><seg><type>gunichar</type></seg><seg><type>gunichar</type></seg></seglistitem>
<seglistitem><seg><type>gchar*</type></seg><seg><classname>Glib::ustring</classname> (or
<classname>std::string</classname> for filenames)</seg></seglistitem>
</segmentedlist>
-</sect2>
-</sect1>
+</section>
+</section>
-
-<sect1 id="sec-wrapping-hand-coded-files">
+<section xml:id="sec-wrapping-hand-coded-files">
<title>Hand-coded source files</title>
+
<para>You might want to include additional source files that will not be
generated by <command>gmmproc</command> from <filename>.hg</filename> and
<filename>.ccg</filename> files. You can simply place these in your
@@ -10458,10 +10621,11 @@ _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle',`$3 = Glib::wrap(&($4))
in the <filename>meson.build</filename> in the
<varname>extra_h_files</varname> and <varname>extra_cc_files</varname>
variables.</para>
-</sect1>
+</section>
-<sect1 id="sec-wrapping-initialization">
+<section xml:id="sec-wrapping-initialization">
<title>Initialization</title>
+
<para>Your library must be initialized before it can be used, to register the
new types that it makes available. Also, the C library that you are wrapping
might have its own initialization function that you should call. You can do
@@ -10483,13 +10647,15 @@ void init()
<filename>wrap_init.h</filename> is hand-coded, so you will need to adjust
<filename>wrap_init.h</filename> so that the <function>wrap_init()</function>
function appears in the correct C++ namespace.</para>
-</sect1>
+</section>
-<sect1 id="sec-wrapping-problems">
+<section xml:id="sec-wrapping-problems">
<title>Problems in the C API.</title>
+
<para>You are likely to encounter some problems in the library that you are wrapping, particularly if it is
a new project. Here are some common problems, with solutions.</para>
-<sect2 id="wrapping-predeclare-structs">
+<section xml:id="wrapping-predeclare-structs">
<title>Unable to predeclare structs</title>
+
<para>By convention, structs are declared in glib/GTK-style headers like so:</para>
<programlisting>
typedef struct _ExampleWidget ExampleWidget;
@@ -10518,10 +10684,11 @@ example-widget.h:60: error: '_ExampleWidget ExampleWidget' redeclared as differe
</programlisting>
</para>
<para>This is easy to correct in the C library, so do send a patch to the relevant maintainer.</para>
-</sect2>
+</section>
-<sect2 id="wrapping-no-properties">
+<section xml:id="wrapping-no-properties">
<title>Lack of properties</title>
+
<para>By convention, glib/GTK-style objects have <function>*_new()</function>
functions, such as <function>example_widget_new()</function> that do nothing
more than call <function>g_object_new()</function> and return the result.
@@ -10557,7 +10724,7 @@ GtkWidget* example_widget_new(int something, const char* thing)
void example_widget_construct(ExampleWidget* widget, int something, const char* thing)
{
//Do stuff that uses private API:
- widget->priv->thing = thing;
+ widget->priv->thing = thing;
do_something(something);
}
</programlisting>
@@ -10565,15 +10732,17 @@ void example_widget_construct(ExampleWidget* widget, int something, const char*
other, is relatively difficult to correct in the C library, but it is
possible, so do file a bug and try to send a patch to the relevant
maintainer.</para>
-</sect2>
-</sect1>
+</section>
+</section>
-<sect1 id="sec-wrapping-documentation">
+<section xml:id="sec-wrapping-documentation">
<title>Documentation</title>
+
<para>In general, gtkmm-style projects use Doxygen, which reads specially formatted C++ comments and
generates HTML documentation. You may write these doxygen comments directly in the header files.</para>
-<sect2 id="wrapping-reusing-c-documentation">
+<section xml:id="wrapping-reusing-c-documentation">
<title>Reusing C documentation</title>
+
<para>You might wish to reuse documentation that exists for the C library that
you are wrapping. GTK-style C libraries typically use gtk-doc and therefore
have source code comments formatted for gtk-doc and some extra documentation
@@ -10584,7 +10753,7 @@ void example_widget_construct(ExampleWidget* widget, int something, const char*
documentation to make it more appropriate for a C++ API.</para>
<para>
For instance,</para>
-<programlisting>./docextract_to_xml.py -s ~/checkout/gnome/gtk/gtk/ > gtk_docs.xml
+<programlisting>./docextract_to_xml.py -s ~/checkout/gnome/gtk/gtk/ > gtk_docs.xml
</programlisting>
<para>Because this automatic transformation is not always appropriate, you might
want to provide hand-written text for a particular method. You can do this
@@ -10593,10 +10762,11 @@ For instance,</para>
<filename>something_docs_override.xml</filename> file and changing the
contents. Alternatively you can write your own documentation in the
<filename>.hg</filename> file.</para>
-</sect2>
+</section>
-<sect2 id="wrapping-documentation-build-structure">
+<section xml:id="wrapping-documentation-build-structure">
<title>Documentation build structure</title>
+
<para>If you copied the skeleton source tree in <application>mm-common</application> and substituted the
placeholder text, then you will already have suitable <filename>meson.build</filename>
and <filename>Doxyfile.in</filename> files in the <filename>doc/reference/</filename>
@@ -10606,14 +10776,10 @@ For instance,</para>
of Doxygen input files is not defined in the Doxygen configuration file, but passed
along from <command>meson/ninja</command> to the standard input of <command>doxygen</command>.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
</appendix>
</book>
-
-<!-- some vim settings
- vim:ts=2 sw=2 et
--->
diff --git a/docs/tutorial/insert_example_code.pl b/docs/tutorial/insert_example_code.pl
index 57cbb24..92b6292 100755
--- a/docs/tutorial/insert_example_code.pl
+++ b/docs/tutorial/insert_example_code.pl
@@ -15,14 +15,14 @@ use strict;
while(<FILE>)
{
# Look for
- # <para><ulink url="&url_examples_base;helloworld">Source Code</ulink></para> [<!-- Insert
filenames... -->]
+ # <para><link xlink:href="&url_examples_base;helloworld">Source Code</link></para> [<!-- Insert
filenames... -->]
- if(/<para><ulink url=\"&url_examples_base;([\/\w]+)\">Source
Code<\/ulink><\/para>\s*(?:<!--\s*Insert\s+(.*?)-->)?/)
+ if(/<para><link xlink:href=\"&url_examples_base;([\/\w]+)\">Source
Code<\/link><\/para>\s*(?:<!--\s*Insert\s+(.*?)-->)?/)
{
# Modify the line to remove the trailing comment, if any.
# url_examples_base is assumed to be a GitLab URL. The branch is then
# included in url_examples_base. No need to add it here.
- print "<para><ulink url=\"&url_examples_base;$1\">Source Code</ulink></para>\n";
+ print "<para><link xlink:href=\"&url_examples_base;$1\">Source Code</link></para>\n";
#List all the source files in that directory:
my $directory = $examples_base . $1;
diff --git a/docs/tutorial/insert_example_code.py b/docs/tutorial/insert_example_code.py
index cfe3c15..bba1193 100755
--- a/docs/tutorial/insert_example_code.py
+++ b/docs/tutorial/insert_example_code.py
@@ -11,7 +11,7 @@ import shutil
# Where to insert example code.
source_include_pattern = re.compile(
- r'\s*<para><ulink url="&url_examples_base;([/\w]+)">Source
Code</ulink></para>\s*(?:<!--\s*Insert\s+(.*?)-->)?')
+ r'\s*<para><link xlink:href="&url_examples_base;([/\w]+)">Source
Code</link></para>\s*(?:<!--\s*Insert\s+(.*?)-->)?')
# First line not part of leading comment in a source code file.
# The comment typically consists of copyright and license text.
@@ -47,7 +47,7 @@ def insert_example_code(examples_base_dir, input_xml_files, output_xml_file):
with open(input_xml_file, mode='r', encoding='utf-8', errors='surrogateescape') as infile:
for line in infile:
# Look for
- # <para><ulink url="&url_examples_base;helloworld">Source Code</ulink></para> [<!-- Insert
filenames... -->]
+ # <para><link xlink:href="&url_examples_base;helloworld">Source Code</link></para> [<!-- Insert
filenames... -->]
source_include_match = source_include_pattern.match(line)
if not source_include_match:
# Print the line without changes.
@@ -57,7 +57,7 @@ def insert_example_code(examples_base_dir, input_xml_files, output_xml_file):
# url_examples_base is assumed to be a GitLab URL. The git branch is then
# included in url_examples_base. No need to add it here.
outfile.write(source_include_match.expand(
- '<para><ulink url="&url_examples_base;\\1">Source Code</ulink></para>\n'))
+ '<para><link xlink:href="&url_examples_base;\\1">Source Code</link></para>\n'))
outfile.write('<!-- start inserted example code -->\n')
# List all the source files in the examples directory.
diff --git a/docs/tutorial/meson.build b/docs/tutorial/meson.build
index 42fc010..28c2ff9 100644
--- a/docs/tutorial/meson.build
+++ b/docs/tutorial/meson.build
@@ -17,8 +17,8 @@ build_translations_by_default = get_option('build-translations')
validate = get_option('validation') ? 'true' : 'false'
dblatex = find_program('dblatex', required: false)
-can_build_pdf = dblatex.found() or (xmllint.found() and \
- find_program('docbook2pdf', required: false).found())
+can_build_pdf = dblatex.found() or (xsltproc.found() and \
+ find_program('fop', required: false).found())
build_pdf_by_default = get_option('build-pdf')
# Installation directories are relative to {prefix}.
@@ -167,13 +167,13 @@ endif
if can_build_pdf
# Create a PDF file of the C locale's version of the DocBook.
- # Prefer dblatex, if both dblatex and docbook2pdf are available.
+ # Prefer dblatex, if both dblatex and fop are available.
custom_target('C-pdf',
input: index_docbook,
output: 'programming-with-gtkmm.pdf',
command: [
python3, tutorial_custom_cmd,
- dblatex.found() ? 'dblatex' : 'docbook2pdf',
+ dblatex.found() ? 'dblatex' : 'fop',
'@INPUT@',
meson.current_source_dir() / 'C' / 'figures',
'@OUTPUT@'
diff --git a/meson.build b/meson.build
index e165e35..ec9c35b 100644
--- a/meson.build
+++ b/meson.build
@@ -121,7 +121,7 @@ endif
build_pdf = build_pdf_by_default and can_build_pdf
explain_pdf = ''
if build_pdf_by_default and not build_pdf
- explain_pdf = ' (requires dblatex or (xmllint and docbook2pdf))'
+ explain_pdf = ' (requires dblatex or (xsltproc and fop))'
endif
summary = [
diff --git a/tools/meson_aux/tutorial-custom-cmd.py b/tools/meson_aux/tutorial-custom-cmd.py
index c23ef91..4346293 100755
--- a/tools/meson_aux/tutorial-custom-cmd.py
+++ b/tools/meson_aux/tutorial-custom-cmd.py
@@ -46,16 +46,16 @@ def html():
xslt_params = [
'--param', 'toc.section.depth', '1',
'--stringparam', 'html.stylesheet', 'style.css',
- '--stringparam', 'admon.graphics', '1',
+ '--param', 'admon.graphics', '1',
'--stringparam', 'admon.graphics.path', 'icons/',
'--stringparam', 'admon.graphics.extension', '.png',
'--stringparam', 'chunker.output.indent', 'yes',
'--stringparam', 'chunker.output.encoding', 'UTF-8',
- '--stringparam', 'navig.graphics', 'yes',
+ '--param', 'navig.graphics', '1',
'--stringparam', 'navig.graphics.extension', '.png',
'--stringparam', 'navig.graphics.path', 'icons/',
'--stringparam', 'toc.list.type', 'ul',
- '--stringparam', 'use.id.as.filename', '1',
+ '--param', 'use.id.as.filename', '1',
]
xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl'
@@ -90,6 +90,8 @@ def xmllint():
input_xml_file = sys.argv[3]
stamp_file_path = sys.argv[4]
+ relax_ng_schema = 'http://docbook.org/xml/5.0/rng/docbook.rng'
+
cmd = [
'xmllint',
'--noout',
@@ -97,7 +99,7 @@ def xmllint():
'--xinclude',
]
if validate == 'true':
- cmd += ['--postvalid']
+ cmd += ['--relaxng', relax_ng_schema]
cmd += [input_xml_file]
result = subprocess.run(cmd)
if result.returncode:
@@ -106,6 +108,9 @@ def xmllint():
Path(stamp_file_path).touch(exist_ok=True)
return 0
+# dblatex and xsltproc+fop generate a PDF file.
+# docbook2pdf can generate PDF files from DocBook4 files, but not from DocBook5 files.
+# xsltproc+xmlroff (version 0.6.3) does not seem to work acceptably.
def dblatex():
# argv[2] argv[3] argv[4]
# <input_xml_file> <figures_dir> <output_pdf_file>
@@ -117,8 +122,10 @@ def dblatex():
# For a list of available parameters, see http://dblatex.sourceforge.net/doc/manual/
dblatex_params = [
- '-P', 'toc.section.depth=2',
+ '-P', 'toc.section.depth=1',
'-P', 'paper.type=a4paper',
+ '-P', 'doc.collab.show=1',
+ '-P', 'latex.output.revhistory=0',
]
figures_dir_parent = os.path.dirname(figures_dir)
@@ -127,52 +134,58 @@ def dblatex():
] + dblatex_params + [
'-I', figures_dir_parent,
'-o', output_pdf_file,
- '--pdf', input_xml_file,
+ '--pdf',
+ input_xml_file,
]
return subprocess.run(cmd).returncode
-def docbook2pdf():
+def fop():
# argv[2] argv[3] argv[4]
# <input_xml_file> <figures_dir> <output_pdf_file>
- # Create a PDF file, using docbook2pdf.
+ # Create a PDF file, using fop.
input_xml_file = sys.argv[2]
figures_dir = sys.argv[3]
output_pdf_file = sys.argv[4]
- output_dir = os.path.dirname(output_pdf_file)
- if not output_dir:
- output_dir = '.'
- output_basename = os.path.basename(output_pdf_file)
- if output_basename.endswith('.pdf'):
- output_basename = output_basename[:-4]
- xml_file = os.path.join(output_dir, output_basename + '.xml')
+ fo_file = os.path.splitext(output_pdf_file)[0] + '.fo'
+
+ figures_dir_parent = os.path.dirname(figures_dir)
+ if figures_dir_parent:
+ figures_dir_parent += '/'
+
+ # For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/fo/
+ # For a list of available paper types, see the description of the page.width.portrait parameter.
+ xslt_params = [
+ '--param', 'toc.section.depth', '1',
+ '--stringparam', 'fop1.extensions', '1',
+ '--stringparam', 'page.orientation', 'portrait',
+ '--stringparam', 'paper.type', 'A4',
+ '--param', 'keep.relative.image.uris', '1',
+ '--stringparam', 'img.src.path', figures_dir_parent,
+ ]
+
+ xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl'
- # We need to produce a full examples XML with all of the XIncludes done.
+ # Generate a .fo (formatting object) file.
+ # fop can take an xslt stylesheet parameter, but it can only read local files.
+ # xsltproc is necessary if you want to read the stylesheet from the internet.
cmd = [
- 'xmllint',
+ 'xsltproc',
+ ] + xslt_params + [
+ '-o', fo_file,
'--xinclude',
- '--postvalid',
- '--output', xml_file,
+ xslt_stylesheet,
input_xml_file,
]
result = subprocess.run(cmd)
if result.returncode:
return result.returncode
- # We also need to copy the figures from the source directory, so they
- # can be found from the XML file.
- # By default, shutil.copytree() copies files with shutil.copy2(),
- # which copies timestamps and some other file metadata.
- # The destination directory must not exist when shutil.copytree() is called.
- output_figures_dir = os.path.join(output_dir, os.path.basename(figures_dir))
- shutil.rmtree(output_figures_dir, ignore_errors=True)
- shutil.copytree(figures_dir, output_figures_dir)
-
cmd = [
- 'docbook2pdf',
- '--output', output_dir,
- xml_file,
+ 'fop',
+ '-fo', fo_file,
+ '-pdf', output_pdf_file,
]
return subprocess.run(cmd).returncode
@@ -185,7 +198,7 @@ if subcommand == 'xmllint':
sys.exit(xmllint())
if subcommand == 'dblatex':
sys.exit(dblatex())
-if subcommand == 'docbook2pdf':
- sys.exit(docbook2pdf())
+if subcommand == 'fop':
+ sys.exit(fop())
print(sys.argv[0], ': illegal subcommand,', subcommand)
sys.exit(1)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
