[gtkmm-documentation] Remove stock items and other deprecated API from the tutorial
- From: Kjell Ahlstedt <kjellahl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtkmm-documentation] Remove stock items and other deprecated API from the tutorial
- Date: Fri, 22 Nov 2013 09:41:52 +0000 (UTC)
commit 901942d3c7e345f9d4cf7b6bf19e0742aa4604e0
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date: Fri Nov 22 10:22:39 2013 +0100
Remove stock items and other deprecated API from the tutorial
* docs/tutorial/C/gtkmm-tutorial-in.xml: Remove deprecated API, mainly
stock items. Many small updates and fixed typos.
docs/tutorial/C/gtkmm-tutorial-in.xml | 328 ++++++++++++++++-----------------
1 files changed, 162 insertions(+), 166 deletions(-)
---
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index d06af01..8d42da6 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -155,7 +155,8 @@ using >kmm; without purchasing licenses.
<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 FAQ for more detailed differences.</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/gtkmm/FAQ";>FAQ</ulink> for more detailed differences.</para>
</sect2>
<sect2 id="gtkmm-is-a-wrapper">
@@ -178,6 +179,7 @@ using >kmm; without purchasing licenses.
<itemizedlist>
<listitem><para><application>libsigc++ 2.0</application></para></listitem>
<listitem><para><application>GTK+ 3.0</application></para></listitem>
+ <listitem><para><application>glibmm</application></para></listitem>
<listitem><para><application>cairomm</application></para></listitem>
<listitem><para><application>pangomm</application></para></listitem>
<listitem><para><application>atkmm</application></para></listitem>
@@ -212,7 +214,7 @@ applications and libraries:
</para>
<para>
The names of the >kmm; packages vary from distribution to distribution
- (e.g. <application>libgtkmm3.0-dev</application> on Debian and Ubuntu or
+ (e.g. <application>libgtkmm-3.0-dev</application> on Debian and Ubuntu or
<application>gtkmm30-devel</application> on Red Hat Fedora), so check with
your distribution's package management program for the correct package name
and install it like you would any other package.
@@ -221,8 +223,8 @@ applications and libraries:
<para>
The package names will not change when new API/ABI-compatible versions of >kmm;
are released. Otherwise they would not be API/ABI-compatible. So don't be
-surprised, for instance, to find >kmm; 3.2 supplied by Debian's
-<application>libgtkmm3.0-dev</application> package.
+surprised, for instance, to find >kmm; 3.8 supplied by Debian's
+<application>libgtkmm-3.0-dev</application> package.
</para>
</note>
</sect2>
@@ -249,7 +251,7 @@ be downloaded from <ulink url="http://www.gtkmm.org/";></ulink>.
<note>
<para>
Remember that on a Unix or Linux operating system, you will probably need to
- be <literal>root</literal> to install software. The <command>su</command>
+ be <literal>root</literal> to install software. The <command>su</command> or <command>sudo</command>
command will allow you to enter the <literal>root</literal> password and have
<literal>root</literal> status temporarily.
</para>
@@ -366,7 +368,7 @@ invocation on the command line.
<sect1 id="sec-headers-and-linking">
<title>Headers and Linking</title>
<para>
-Although we have shown the compilation command for the simple example, you really should use the automake
and autoconf tools, as described in "Autoconf, Automake, Libtool", by G. V. Vaughan et al. The examples used
in this book are included in the >kmm; package, with appropriate build files, so we won't show the build
commands in future. You'll just need to find the appropriate directory and type <literal>make</literal>.
+Although we have shown the compilation command for the simple example, you really should use the automake
and autoconf tools, as described in "Autoconf, Automake, Libtool", by G. V. Vaughan et al. The examples used
in this book are included in the <application>gtkmm-documentation</application> package, with appropriate
build files, so we won't show the build commands in future. You'll just need to find the appropriate
directory and type <literal>make</literal>.
</para>
<para>
To simplify compilation, we use <literal>pkg-config</literal>, which
@@ -381,10 +383,10 @@ 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-3.0 >= 3.0.0])</programlisting>
+<programlisting>PKG_CHECK_MODULES([MYAPP], [gtkmm-3.0 >= 3.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-3.0 is the name of the current stable API. There was an older API called gtkmm-2-4 which
installs in parallel when it is available. There were several versions of gtkmm-2.4, such as gtkmm 2.10 and
there will be several versions of the gtkmm-3.0 API. Note that the API name does not change for every version
because that would be an incompatible API and ABI break. Theoretically, there might be a future gtkmm-4.0 API
which would install in parallel with gtkmm-3.0 without affecting existing applications.
+<para>gtkmm-3.0 is the name of the current stable API. There was an older API called gtkmm-2-4 which
installs in parallel when it is available. There were several versions of gtkmm-2.4, such as gtkmm 2.10 and
there are several versions of the gtkmm-3.0 API. Note that the API name does not change for every version
because that would be an incompatible API and ABI break. Theoretically, there might be a future gtkmm-4.0 API
which would install in parallel with gtkmm-3.0 without affecting existing applications.
</para>
<para>Note that if you mention extra modules in addition to gtkmm-3.0, they should be separated by spaces,
not commas.
@@ -439,7 +441,7 @@ just connecting to the existing >kmm; signals, see the <link linkend="chapter-
<sect1 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 it its
interfaces. Instead it uses <classname>Glib::ustring</classname>, which is so similar and unobtrusive that
you could actually pretend that each Glib::ustring 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>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 bit per character, but 8 bits aren't enough to encode languages such as Arabic,
Chinese, and Japanese. Although the encodings for these languages have now been specified by the Unicode
Consortium, the C and C++ languages do not yet provide any standardised Unicode support. 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>
<para>One of the benefits of UTF-8 is that you don't need to use it unless you want to, so you don't need to
retrofit all of your code at once. <classname>std::string</classname> will still work for 7-bit ASCII
strings. But when you try to localize your application for languages like Chinese, for instance, you will
start to see strange errors, and possible crashes. Then all you need to do is start using
<classname>Glib::ustring</classname> instead.</para>
<para>Note that UTF-8 isn't compatible with 8-bit encodings like ISO-8859-1. For instance, German umlauts
are not in the ASCII range and need more than 1 byte in the UTF-8 encoding. If your code contains 8-bit
string literals, you have to convert them to UTF-8 (e.g. the Bavarian greeting "Grüß Gott" would
be "Gr\xC3\xBC\xC3\x9F Gott").</para>
@@ -598,7 +600,7 @@ it wants, and leaves you the rest, as we described earlier.
<para>
Next we make an object of our <classname>HelloWorld</classname> class, whose constructor
-takes no arguments, but it isn't visible yet. When we call<methodname>Gtk::Application::run()</methodname>,
giving it the helloworld Window, it shows the Window and starts the >kmm; <emphasis>event loop</emphasis>.
During the event loop >kmm; idles, waiting for actions from the user, and responding appropriately. When
the user closes the Window, run() will return, causing the final line of our main() function be to executed.
The application will then finish.
+takes no arguments, but it isn't visible yet. When we call <methodname>Gtk::Application::run()</methodname>,
giving it the helloworld Window, it shows the Window and starts the >kmm; <emphasis>event loop</emphasis>.
During the event loop >kmm; idles, waiting for actions from the user, and responding appropriately. When
the user closes the Window, run() will return, causing the final line of our main() function be to executed.
The application will then finish.
</para>
</sect1>
@@ -615,10 +617,8 @@ takes no arguments, but it isn't visible yet. When we call<methodname>Gtk::Appli
<para>>kmm; 3 added some new classes:</para>
<orderedlist>
-<!-- TODO: The AppChooser content-type is not documented properly:
https://bugzilla.gnome.org/show_bug.cgi?id=650012 -->
<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>. It arranges its children according to properties of those children rather
than its own layout details.</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::CheckBox</classname>. It may be useful, for instance, when allowing users to activate
hardware.</simpara></listitem>
</orderedlist>
@@ -655,7 +655,7 @@ orientation (vertical or horizontal) to be specified without requiring the use o
<para>All deprecated API was removed in >kmm; 3.0, though there will be new deprecations in future
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
GTK_DISABLE_DEPRECATED. There are some autotools macros that can help with this by defining them optionally
at build time. See the <ulink url="https://live.gnome.org/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 <ulink url="https://live.gnome.org/gtkmm/PortingToGtkmm3";>gtkmm 3 porting wiki
page</ulink> for more details.</para>
</chapter>
@@ -695,7 +695,7 @@ press it again. It might be useful as an on/off switch. See the <link linkend="s
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.
-See the <link linkend="sec-checkboxes">CheckBox</link> section.
+See the <link linkend="sec-checkboxes">CheckButton</link> section.
</para>
</listitem>
</varlistentry>
@@ -738,9 +738,10 @@ or set it later with <methodname>set_label()</methodname>.
<programlisting>Gtk::Button* pButton = new Gtk::Button("_Something", true);</programlisting>
<para>
-Wherever possible you should use Stock items, to ensure consistency with other applications, and to improve
the appearance of your applications by using icons. For instance,
-<programlisting>Gtk::Button* pButton = new Gtk::Button(Gtk::Stock::OK);</programlisting>
-This will use standard text, in all languages, with standard keyboard accelerators, with a standard icon.
+Stock items have been recommended for use in buttons. From >kmm;-3.10 they are deprecated.
+They should not be used in newly-written code. However, the documentation of
+<ulink url="&url_refdocs_base_gtk_namespace;Stock.html">namespace Gtk::Stock</ulink>
+shows recommended labels and named icons to show in buttons.
</para>
<para>
@@ -1190,6 +1191,8 @@ text bold, colored, or larger. You can do this by providing a string to
Below is a short example to illustrate these functions. This example
makes use of the Frame widget to better demonstrate the label styles.
(The Frame widget is explained in the <link linkend="sec-frame">Frame</link> section.)
+It is possible that the first character in <literal>m_Label_Normal</literal> is shown
+underlined only when you press the <keycap>Alt</keycap> key.
</para>
<figure id="figure-label">
@@ -1326,13 +1329,13 @@ actions.
<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
-<methodname>set_icon_from_stock()</methodname>. An application can respond to the
+<methodname>set_icon_from_icon_name()</methodname>. An application can respond to the
user pressing the icon by handling the
<methodname>signal_icon_press</methodname> signal.</para>
<sect3 id="entry-icon-example"><title>Entry Icon Example</title>
<para>
-This example shows a <classname>Gtk::Entry</classname> widget with a stock
+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>
@@ -1380,7 +1383,7 @@ bar.
<para>
A <classname>SpinButton</classname> allows the user to select a value from a
-range of numeric values. It has an Entry widget with up and down arrow buttons
+range of numeric values. It has an <classname>Entry</classname> widget with increment and decrement buttons
at the side. Clicking the buttons causes the value to 'spin' up and down across
the range of possible values. The <classname>Entry</classname> widget may also
be used to enter a value directly.
@@ -1389,8 +1392,8 @@ be used to enter a value directly.
<para>
The value can have an adjustable number of decimal places, and the step size is
configurable. <classname>SpinButton</classname>s have an 'auto-repeat' feature
-as well: holding down one of the arrows can optionally cause the value to
-change more quickly the longer the arrow is held down.
+as well: holding down the increment or decrement button can optionally cause the value to
+change more quickly the longer the button is held down.
</para>
<para>
@@ -1467,7 +1470,7 @@ method, and retrieve it with <methodname>get_value()</methodname>.
<para>
The <methodname>spin()</methodname> method 'spins' the
-<classname>SpinButton</classname>, as if one of its arrows had been clicked.
+<classname>SpinButton</classname>, as if its increment or decrement button had been clicked.
You need to specify a <classname>Gtk::SpinType</classname> to specify the
direction or new position.
</para>
@@ -1533,16 +1536,11 @@ been completed.
<para>
To change the value shown, use the <methodname>set_fraction()</methodname> method,
-passing a double between 0 and 1 to provide the new percentage.
+passing a <type>double</type> between 0.0 and 1.0 to provide the new percentage.
</para>
<para>
-where <literal>percentage</literal> is a number, from 0 to 1, indicating what
-fraction of the bar should be filled.
-</para>
-
-<para>
-A <classname>ProgressBar</classname>is horizontal and left-to-right by default,
+A <classname>ProgressBar</classname> is horizontal and left-to-right by default,
but you can change it to a vertical progress bar by using the
<methodname>set_orientation()</methodname> method.
</para>
@@ -1568,7 +1566,7 @@ intervals. You can also choose the step size, with the
</para>
<para>
-When in continuous mode, the progress bar can also display a configurable text
+The progress bar can also display a configurable text
string within its trough, using the <methodname>set_text()</methodname> method.
</para>
</sect2>
@@ -1909,7 +1907,7 @@ Changing the layout of a window "on the fly", to make some extra widgets appear,
<para>
>kmm; uses the packing system to solve these problems. Rather than specifying the position and size of
each widget in the window,
you can arrange your widgets in rows, columns,
-and/or tables. >kmm; can size your window automatically, based on the
+and/or grids. >kmm; can size your window automatically, based on the
sizes of the widgets it contains. And the sizes of the widgets are, in turn, determined by the amount of
text they contain, or the minimum and maximum sizes that you specify, and/or how you have requested that the
available space should be shared between sets of widgets.
You can perfect your layout by
specifying padding distance and centering values for each of your widgets. >kmm; then uses
@@ -2454,7 +2452,7 @@ with the <methodname>append()</methodname>, <methodname>prepend()</methodname>,
<methodname>insert()</methodname> methods, like so:
</para>
<programlisting>Gtk::TreeModel::iterator iter_child =
- m_refListStore->append(row.children());</programlisting>
+ m_refTreeStore->append(row.children());</programlisting>
</sect3>
</sect2>
@@ -2550,23 +2548,23 @@ To render more than one model column in a view column, you need to create the
<para>
Then use <methodname>append_column()</methodname> to add the view Column to the
-View. Notice that <methodname>Gtk::View::append_column()</methodname> is overridden
-to accept either a prebuilt <classname>Gtk::View::Column</classname> widget, or
+View. Notice that <methodname>Gtk::TreeView::append_column()</methodname> is overridden
+to accept either a prebuilt <classname>Gtk::TreeView::Column</classname> widget, or
just the <classname>TreeModelColumn</classname> from which it generates an
-appropriate <classname>Gtk::View::Column</classname> widget.
+appropriate <classname>Gtk::TreeView::Column</classname> widget.
</para>
<para>
Here is some example code from
-<filename>demos/gtk-demo/example_stockbrowser.cc</filename>, which has a pixbuf
+<filename>gtkmm/demos/gtk-demo/example_icontheme.cc</filename>, which has a pixbuf
icon and a text name in the same column:
</para>
<programlisting>Gtk::TreeView::Column* pColumn =
- Gtk::manage( new Gtk::TreeView::Column("Symbol") );
+ Gtk::manage(new Gtk::TreeView::Column("Icon Name"));
-// m_columns.icon and m_columns.symbol are columns in the model.
+// m_columns.icon and m_columns.iconname are columns in the model.
// pColumn is the column in the TreeView:
-pColumn->pack_start(m_columns.icon, false); //false = don't expand.
-pColumn->pack_start(m_columns.symbol);
+pColumn->pack_start(m_columns.icon, /* expand= */ false);
+pColumn->pack_start(m_columns.iconname);
m_TreeView.append_column(*pColumn);</programlisting>
</sect2>
@@ -2577,22 +2575,18 @@ m_TreeView.append_column(*pColumn);</programlisting>
The default <classname>CellRenderers</classname> and their default behaviour
will normally suffice, but you might occasionally need finer control. For
instance, this example code from
-<filename>demos/gtk-demo/example_treestore.cc</filename>, manually constructs a
+<filename>gtkmm/demos/gtk-demo/example_treeview_treestore.cc</filename>, appends a
<classname>Gtk::CellRenderer</classname> widget and instructs it to render the
data from various model columns through various aspects of its appearance.
</para>
-<programlisting>Gtk::CellRendererToggle* pRenderer =
- Gtk::manage( new Gtk::CellRendererToggle() );
-int cols_count = m_TreeView.append_column("Alex", *pRenderer);
+<programlisting>int cols_count = m_TreeView.append_column_editable("Alex", m_columns.alex);
Gtk::TreeViewColumn* pColumn = m_TreeView.get_column(cols_count-1);
if(pColumn)
{
- pColumn->add_attribute(pRenderer->property_active(),
- m_columns.alex);
- pColumn->add_attribute(pRenderer->property_visible(),
- m_columns.visible);
- pColumn->add_attribute(pRenderer->property_activatable(),
- m_columns.world);</programlisting>
+ Gtk::CellRendererToggle* 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
@@ -2754,7 +2748,7 @@ To respond to the user clicking on a row or range of rows, connect to the
signal like so:
</para>
<programlisting>refTreeSelection->signal_changed().connect(
- sigc::mem_fun(*this, &Example_StockBrowser::on_selection_changed)
+ sigc::mem_fun(*this, &Example_IconTheme::on_selection_changed)
);</programlisting>
</sect2>
@@ -2816,7 +2810,7 @@ The standard tree models (<classname>TreeStore</classname> and <classname>ListSt
<sect2 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::TreeViewModel::set_sort_column()</methodname>, supplying the model column on which model
should be sorted when the header is clicked. For instance:
+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>Gtk::TreeView::Column* pColumn = treeview.get_column(0);
if(pColumn)
@@ -2860,7 +2854,7 @@ treeview.set_model(sorted_model);</programlisting>
<sect1 id="sec-treeview-draganddrop">
<title>Drag and Drop</title>
<para>
-<classname>Gtk::TreeView</classname> already implments simple drag-and-drop
+<classname>Gtk::TreeView</classname> already implements simple drag-and-drop
when used with the <classname>Gtk::ListStore</classname> or
<classname>Gtk::TreeStore</classname> models. If necessary, it also allows you
to implement more complex behaviour when items are dragged and dropped, using
@@ -2898,11 +2892,11 @@ To detect a click of the right mouse button, you need to handle the
was pressed. Because the <classname>TreeView</classname> normally handles this
signal completely, you need to either override the default signal handler in a
derived <classname>TreeView</classname> class, or use
-<methodname>connect_nofify()</methodname> instead of <methodname>connect()</methodname>.
+<methodname>connect_notify()</methodname> instead of <methodname>connect()</methodname>.
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 Custom Menu example.</para>
+<para>This is demonstrated in the Popup Context Menu example.</para>
</sect2>
</sect1>
@@ -3044,7 +3038,7 @@ ModelColumns m_columns;</programlisting>
<sect1 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 Combo. For instance:
+<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();
if(iter)
@@ -3287,7 +3281,7 @@ formatting. You define the start and end of the range of text by specifying
<programlisting>refBuffer->apply_tag(refTagMatch, iterRangeStart, iterRangeStop);</programlisting>
<para>
Or you could specify the tag when first inserting the text:
-refBuffer->insert_with_tag(iter, "Some text", refTagMatch);
+<programlisting>refBuffer->insert_with_tag(iter, "Some text", refTagMatch);</programlisting>
</para>
<para>
@@ -3318,7 +3312,7 @@ iterator for the <classname>Mark</classname>'s new position.
<para>
There are two built-in <classname>Mark</classname>s - <literal>insert</literal>
-and <literal>select_bound</literal>, which you can access with
+and <literal>selection_bound</literal>, which you can access with
<classname>TextBuffer</classname>'s <methodname>get_insert()</methodname> and
<methodname>get_selection_bound()</methodname> methods.
</para>
@@ -3332,7 +3326,7 @@ and <literal>select_bound</literal>, which you can access with
<para>
As mentioned above, each <classname>TextView</classname> has a
<classname>TextBuffer</classname>, and one or more
-<classname>TextView</classname> can share the same
+<classname>TextView</classname>s can share the same
<classname>TextBuffer</classname>.
</para>
@@ -3443,9 +3437,7 @@ First create the <classname>Action</classname>s and add them to an
<para>
The arguments to <methodname>Action::create()</methodname> specify the action's
-name and how it will appear in menus and toolbars. Use stock items where
-possible so that you don't need to specify the label, accelerator, icon, and
-tooltips, and so you can use pre-existing translations.
+name and how it will appear in menus and toolbars.
</para>
<para>
You can also specify a signal handler when calling
@@ -3459,14 +3451,14 @@ when the action is activated via either a menu item or a toolbar button.
<programlisting>m_refActionGroup = Gtk::ActionGroup::create();
m_refActionGroup->add( Gtk::Action::create("MenuFile", "_File") );
-m_refActionGroup->add( Gtk::Action::create("New", Gtk::Stock::NEW),
+m_refActionGroup->add( Gtk::Action::create("New", "_New"),
sigc::mem_fun(*this, &ExampleWindow::on_action_file_new) );
m_refActionGroup->add( Gtk::Action::create("ExportData", "Export Data"),
sigc::mem_fun(*this, &ExampleWindow::on_action_file_open) );
-m_refActionGroup->add( Gtk::Action::create("Quit", Gtk::Stock::QUIT),
+m_refActionGroup->add( Gtk::Action::create("Quit", "_Quit"),
sigc::mem_fun(*this, &ExampleWindow::on_action_file_quit) );</programlisting>
-<para>Note that this is where we specify the names of the actions as they will be seen by users in menus and
toolbars. Therefore, this is where you should make strings translatable, by putting them inside the _()
macro. When we use the Gtk::Stock items, of course, translations are automatically available.</para>
+<para>Note that this is where we specify the names of the actions as they will be seen by users in menus and
toolbars. Therefore, this is where you should make strings translatable, by putting them inside the _()
macro.</para>
</sect1>
@@ -3608,7 +3600,7 @@ signal, which you will need to handle anyway. For instance:
<para>A <classname>ToolPalette</classname> is similar to a <classname>Toolbar</classname> but can contain a
grid of items, categorized into groups. The user may hide or expand each group. As in a toolbar, the items
may be displayed as only icons, as only text, or as icons with text.
</para>
<para>The <classname>ToolPalette</classname>'s items might be dragged or simply activated. For instance, the
user might drag objects to a canvas to create new items there. Or the user might click an item to activate a
certain brush size in a drawing application.</para>
-<para><classname>ToolItemGroup</classname>s should be added to the tool pallete via the base class's
<function>Gtk::Container::add()</function> method, for instance like so:
+<para><classname>ToolItemGroup</classname>s should be added to the tool palette via the base class's
<function>Gtk::Container::add()</function> method, for instance like so:
</para>
<para>
<programlisting>
@@ -3635,7 +3627,7 @@ group_brushes->insert(*button);
<sect1 id="toolpallete-dranganddrop">
<title>Drag and Drop</title>
-<para>Call <methodname>add_drag_dest()</methodname> to allow items or groups to be dragged from the tool
palette to a particular destination widget. You can then use <methodname>get_drag_item()</methodname> to
discover which ToolItem or ToolItemGroup is being dragged. You can use <literal>dynamic_cast</literal> to
discover whether is it an item or a group. For instance, you might use this in your
<literal>drag_data_received</literal> signal handler, to add a dropped item, or to show a suitable icon while
dragging.</para>
+<para>Call <methodname>add_drag_dest()</methodname> to allow items or groups to be dragged from the tool
palette to a particular destination widget. You can then use <methodname>get_drag_item()</methodname> to
discover which ToolItem or ToolItemGroup is being dragged. You can use <literal>dynamic_cast</literal> to
discover whether it is an item or a group. For instance, you might use this in your
<literal>drag_data_received</literal> signal handler, to add a dropped item, or to show a suitable icon while
dragging.</para>
<para>See the <link linkend="chapter-draganddrop">Drag and Drop</link> chapter for general advice about Drag
and Drop with gtkmm.</para>
</sect1>
@@ -3672,36 +3664,38 @@ their API.
<para>
So that applications can react to changes, for instance when a user moves a
scrollbar, <classname>Gtk::Adjustment</classname> has a
-<literal>changed</literal> signal. You can then use the
-<methodname>get_changed()</methodname> method to discover the new value.
+<literal>value_changed</literal> signal. You can then use the
+<methodname>get_value()</methodname> method to discover the new value.
</para>
<sect1 id="sec-creating-adjustment">
<title>Creating an Adjustment</title>
<para>
-The <classname>Gtk::Adjustment</classname> constructor is as follows:
+The <classname>Gtk::Adjustment</classname> is created by its
+<methodname>create()</methodname> method which is as follows:
</para>
-<programlisting>Gtk::Adjustment(float value,
- float lower,
- float upper,
- float step_increment = 1,
- float page_increment = 10,
- float page_size = 0);</programlisting>
+<programlisting>Glib::RefPtr<Gtk::Adjustment> Gtk::Adjustment::create(
+ double value,
+ double lower,
+ double upper,
+ double step_increment = 1,
+ double page_increment = 10,
+ double page_size = 0);</programlisting>
<para>
The <parameter>value</parameter> argument is the initial value of the
adjustment, usually corresponding to the topmost or leftmost position of an
adjustable widget. The <parameter>lower</parameter> and
-<parameter>upper</parameter> arguments specifies the possible range of values
+<parameter>upper</parameter> arguments specify the possible range of values
which the adjustment can hold. The
<parameter>step_increment</parameter> argument specifies the smaller of
the two increments by which the user can change the value, while the
<parameter>page_increment</parameter> is the larger one. The
<parameter>page_size</parameter> argument usually corresponds somehow to
the visible area of a panning widget. The <parameter>upper</parameter> argument
-is used to represent the bottom most or right most coordinate in a panning
+is used to represent the bottommost or rightmost coordinate in a panning
widget's child.
<!-- TODO: Investigate the upper argument properly. There was some unclear stuff about it not always being
the upper value. -->
</para>
@@ -3774,14 +3768,14 @@ So, for example, if you have a <classname>Scale</classname> widget, and you
want to change the rotation of a picture whenever its value changes, you would
create a signal handler like this:
</para>
-<programlisting>void cb_rotate_picture (Gtk::Widget *picture)
+<programlisting>void cb_rotate_picture (MyPicture* picture)
{
- picture->set_rotation (adj->value);
+ picture->set_rotation(adj->get_value());
...</programlisting>
<para>
and connect it to the scale widget's adjustment like this:
</para>
-<programlisting>adj.value_changed.connect(sigc::bind<Widget*>(sigc::mem_fun(*this,
+<programlisting>adj->signal_value_changed().connect(sigc::bind<MyPicture*>(sigc::mem_fun(*this,
&cb_rotate_picture), picture));</programlisting>
<para>
@@ -3804,7 +3798,7 @@ 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->changed();</programlisting>
+<programlisting>adjustment->signal_changed();</programlisting>
</sect1>
@@ -4094,7 +4088,7 @@ search-and-replace dialog is non-modal.
<para>
GTK+ uses the <ulink url="http://cairographics.org";>Cairo</ulink> drawing API.
- With gtkmm, you may use the <ulink url="http://www.cairographics.org/cairomm/";>cairomm</ulink> C++ API
for cairo.
+ With >kmm;, you may use the <ulink url="http://www.cairographics.org/cairomm/";>cairomm</ulink> C++
API for cairo.
</para>
<para>
@@ -4413,7 +4407,7 @@ myContext->set_line_width(2.0);</programlisting>
of coordinates define the control point for the end of the curve,
and the last set of coordinates define the destination point. To
make the concept of control points a bit easier to visualize, a
- line has been draw from each control point to the end-point on the
+ line has been drawn from each control point to the end-point on the
curve that it is associated with. Note that these control point
lines are both translucent. This is achieved with a variant of
<methodname>set_source_rgb()</methodname> called
@@ -4658,7 +4652,7 @@ context->restore();</programlisting>
outline, fill it with white, and then stroke the outline in black.
Notice that both of these actions use the
<methodname>_preserve</methodname> variant to preserve the current path,
- and then this same path is clipped to make sure than our next lines
+ and then this same path is clipped to make sure that our next lines
don't go outside the outline of the clock.
</para>
<para>
@@ -4703,20 +4697,17 @@ emitted, telling the signal handlers which
<sect1 id="sec-dnd-methods">
<title>Methods</title>
<para>
-<classname>Widgets</classname> can be identified as sources or destinations
+<classname>Widget</classname>s can be identified as sources or destinations
using these <classname>Gtk::Widget</classname> methods:
</para>
-<programlisting>void drag_source_set(const ArrayHandle_TargetEntry& targets,
- GdkModifierType start_button_mask, GdkDragAction actions);</programlisting>
+<programlisting>void drag_source_set(const std::vector<Gtk::TargetEntry>& targets,
+ Gdk::ModifierType start_button_mask, Gdk::DragAction actions);</programlisting>
<itemizedlist>
<listitem>
<para>
- <literal>targets</literal> is a container of
- <classname>Gtk::TargetEntry</classname>
- (<classname>std::list<Gtk::TargetEntry></classname> or
- <classname>std::vector<Gtk::TargetEntry></classname>, for
- instance) elements.
+ <literal>targets</literal> is a vector of
+ <classname>Gtk::TargetEntry</classname> elements.
</para>
</listitem>
<listitem>
@@ -4738,8 +4729,8 @@ using these <classname>Gtk::Widget</classname> methods:
</listitem>
</itemizedlist>
-<programlisting>void drag_dest_set(const ArrayHandle_TargetEntry& targets,
- GtkDestDefaults flags, GdkDragAction actions);</programlisting>
+<programlisting>void drag_dest_set(const std::vector<Gtk::TargetEntry>& targets,
+ Gtk::DestDefaults flags, Gdk::DragAction actions);</programlisting>
<itemizedlist>
<listitem>
@@ -4776,19 +4767,19 @@ The source widget will emit these signals, in this order:
<itemizedlist>
<listitem><para><literal>drag_begin</literal>: Provides DragContext.</para></listitem>
<listitem><para><literal>drag_motion</literal>: Provides DragContext and coordinates. You can call the
drag_status() method of the DragContext to indicate which target will be accepted.</para></listitem>
-<listitem><para><literal>drag_get</literal>: Provides <literal>info</literal> about the dragged data format,
and a <literal>GtkSelectionData</literal> structure, in which you should put the requested
data.</para></listitem>
+<listitem><para><literal>drag_data_get</literal>: Provides <literal>info</literal> about the dragged data
format, and a <literal>Gtk::SelectionData</literal> structure, in which you should put the requested
data.</para></listitem>
<listitem><para><literal>drag_drop</literal>: Provides DragContext and coordinates.</para></listitem>
<listitem><para><literal>drag_end</literal>: Provides DragContext.</para></listitem>
</itemizedlist>
</para>
<para>
-The destination widget will emit this signal, after the source destination has emitted the
<literal>drag_get</literal> signal:
+The destination widget will emit this signal, after the source widget has emitted the
<literal>drag_data_get</literal> signal:
<itemizedlist>
<listitem>
<para>
<literal>drag_data_received</literal>: Provides <literal>info</literal>
about the dragged data format, and a
- <literal>GtkSelectionData</literal> structure which contains the
+ <literal>Gtk::SelectionData</literal> structure which contains the
dropped data. You should call the <methodname>drag_finish()</methodname>
method of the <literal>DragContext</literal> to indicate whether the
operation was successful.
@@ -4803,7 +4794,7 @@ The destination widget will emit this signal, after the source destination has e
<title>Move</title>
<para>During a <literal>move</literal>, the source widget will also emit this signal:
<itemizedlist>
-<listitem><para><literal>drag_delete</literal>: Gives the source the opportunity to delete the original data
if that's appropriate.</para></listitem>
+<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>
@@ -5040,7 +5031,7 @@ type.
<para>
At the application development level, >kmm;'s printing API
-provides dialogs that are consistent across applications and allows us 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.
+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">
@@ -5966,7 +5957,8 @@ method that will be called every few milliseconds.
<para>
<programlisting>
-sigc::connection Glib::SignalTimeout::connect(const sigc::slot<bool>& slot, unsigned int interval,
int priority = Glib::PRIORITY_DEFAULT);
+sigc::connection Glib::SignalTimeout::connect(const sigc::slot<bool>& slot,
+ unsigned int interval, int priority = Glib::PRIORITY_DEFAULT);
</programlisting>
</para>
@@ -6024,14 +6016,14 @@ following method is used to do this:
<para>
<programlisting>
-sigc::connection Glib::SignalInput::connect(const sigc::slot<bool,Glib::IOCondition>& slot,
- int fd, Glib::IOCondition condition,
- int priority = Glib::PRIORITY_DEFAULT);
+sigc::connection Glib::SignalIO::connect(const sigc::slot<bool,Glib::IOCondition>& slot,
+ int fd, Glib::IOCondition condition,
+ int priority = Glib::PRIORITY_DEFAULT);
</programlisting>
</para>
<para>
-The first argument is a slot you wish to have called when then
+The first argument is a slot you wish to have called when
the specified event (see argument 3) occurs on the file descriptor you specify
using argument two. Argument three may be one or more (using
<literal>|</literal>) of:
@@ -6092,7 +6084,7 @@ bool input_callback(Glib::IOCondition condition);
<para>
where <parameter>condition</parameter> is as
specified above. As usual the slot is created with
-<function>sigc::mem_fun()</function> (for a member method of an object.), or
+<function>sigc::mem_fun()</function> (for a member method of an object), or
<function>sigc::ptr_fun()</function> (for a function).
</para>
@@ -6118,7 +6110,8 @@ If you want to specify a method that gets called when nothing else is happening,
<para>
<programlisting>
-sigc::connection Glib::SignalIdle::connect(const sigc::slot<bool>& slot, int priority =
Glib::PRIORITY_DEFAULT_IDLE);
+sigc::connection Glib::SignalIdle::connect(const sigc::slot<bool>& slot,
+ int priority = Glib::PRIORITY_DEFAULT_IDLE);
</programlisting>
</para>
@@ -6359,7 +6352,7 @@ If you wish to learn more about smartpointers, you might look in these
books:
<itemizedlist>
<listitem><para>
-Bjarne Stroustrup, "The C++ Programming Language" - section 14.4.2
+Bjarne Stroustrup, "The C++ Programming Language" Forth Edition - section 34.3
</para></listitem>
<listitem><para>
Nicolai M. Josuttis, "The C++ Standard Library" - section 4.2
@@ -6778,7 +6771,7 @@ AC_SUBST(PROGRAMNAME_LOCALEDIR)</programlisting>
</para>
<para>
- Finally, to let you program use the translation for the current locale,
+ Finally, to let your program use the translation for the current locale,
add this code to the beginning of your <filename>main.cc</filename> file, to initialize gettext.
<programlisting>bindtextdomain(GETTEXT_PACKAGE, PROGRAMNAME_LOCALEDIR);
@@ -7639,10 +7632,12 @@ your examples in their programs, and copies of this document
<para>
<classname>Glib::RefPtr</classname> is a smartpointer. Specifically, it is a
reference-counting smartpointer. You might be familiar with
-<literal>std::auto_ptr<></literal>, which is also a smartpointer, but
-<literal>Glib::RefPtr<></literal> is much simpler, and more useful. We
-expect a future version of the C++ Standard Library to contain a
-reference-counting shared smartpointer, and a future version of >kmm; might possibly use that
instead.</para>
+<classname>std::auto_ptr<></classname>, <classname>std::unique_ptr<></classname>
+and <classname>std::shared_ptr<></classname>, which are also smartpointers.
+<classname>Glib::RefPtr<></classname> is similar to <classname>std::shared_ptr<></classname>,
+which is also reference-counting. <classname>Glib::RefPtr<></classname> was introduced
+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>
@@ -7697,7 +7692,7 @@ Gdk::Pixbuf& underlying = *refPixbuf; //Syntax error - will not compile.
<sect1 id="sec-refptr-casting"><title>Casting</title>
<para>
-You can cast <classname>RefPtrs</classname> to base types, just like normal
+You can cast <classname>RefPtr</classname>s to base types, just like normal
pointers.
</para>
<para>
@@ -7948,13 +7943,12 @@ see the names of the arguments too.
<para>
The same principles apply for signals which have more arguments. Here's one
-with three (taken from <filename><gtkmm/editable.h></filename>):
+with three (taken from <filename><gtkmm/textbuffer.h></filename>):
</para>
<para>
<programlisting>
-Glib::SignalProxy3<void, const Glib::ustring&, int, int*> signal_insert_text()
-
+Glib::SignalProxy3<void, const TextBuffer::iterator&, const Glib::ustrin&, int>
signal_insert();
</programlisting>
</para>
@@ -7968,7 +7962,7 @@ handler's prototype could look like this:
<para>
<programlisting>
-void on_insert_text(const Glib::ustring& text, int length, int* position);
+void on_insert(const TextBuffer::iterator& pos, const Glib::ustring& text, int bytes)
</programlisting>
</para>
</sect1>
@@ -7989,7 +7983,7 @@ sigc::signal<void,int>::iterator signal<void,int>::connect( const si
<para>
Notice that the return value is of type
<classname>sigc::signal<void,int>::iterator</classname>. This can be
-implicitely converted into a <classname>sigc::connection</classname> which in
+implicitly converted into a <classname>sigc::connection</classname> which in
turn can be used to control the connection. By keeping a connection object you
can disconnect its associated signal handler using the method
<methodname>sigc::connection::disconnect()</methodname>.
@@ -8078,8 +8072,7 @@ 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, which you will
-encounter later.
+ linkend="sec-helloworld2">helloworld2</link> example.
<programlisting>
m_button1.signal_clicked().connect( sigc::bind<Glib::ustring>( sigc::mem_fun(*this,
&HelloWorld::on_button_clicked), "button 1") );
</programlisting>
@@ -8109,14 +8102,14 @@ is very difficult in C. We have far less need of this hack in >kmm;.
The <classname>Widget</classname> class has some special signals which
correspond to the underlying X-Windows events. These are suffixed by
<literal>_event</literal>; for instance,
-<methodname>Widget::signal_button_pressed_event()</methodname>.
+<methodname>Widget::signal_button_press_event()</methodname>.
</para>
<para>
You might occasionally find it useful to handle X events when there's something
you can't accomplish with normal signals. <classname>Gtk::Button</classname>,
for example, does not send mouse-pointer coordinates with its
<literal>clicked</literal> signal, but you could handle
-<literal>button_pressed_event</literal> if you needed this
+<literal>button_press_event</literal> if you needed this
information. X events are also often used to handle key-presses.
</para>
@@ -8127,7 +8120,7 @@ the event. If the value is <literal>false</literal> then >kmm; will pass the e
<para>
Handling an X event doesn't affect the Widget's other signals. If you handle
-<literal>button_pressed_event</literal> for
+<literal>button_press_event</literal> for
<classname>Gtk::Button</classname>, you'll still be able to get the
<literal>clicked</literal> signal. They are emitted at (nearly) the same time.
</para>
@@ -8465,7 +8458,7 @@ practical - and sensible - to subclass a button for that purpose.
</para>
<para>
The easiest way to do this is using <ulink
- url="http://developer.gnome.org/jhbuild/unstable/";>jhbuild</ulink>.
+ url="https://wiki.gnome.org/Jhbuild";>jhbuild</ulink>.
<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
@@ -8480,7 +8473,7 @@ practical - and sensible - to subclass a button for that purpose.
</para>
<note>
<para>
- Note that to build >kmm; from git, you'll often need to build all of its
+ Note that to build >kmm; from git, you'll often need to build many of its
dependencies from git as well. <application>jhbuild</application> makes
this easier than it would normally be, but it will take quite a while to
build and install them all. You will probably encounter build problems,
@@ -8504,7 +8497,7 @@ practical - and sensible - to subclass a button for that purpose.
<filename>gnome-suites-core-deps-3.x.modules</filename> moduleset, so edit your
<filename>.jhbuildrc</filename> file and set your moduleset setting to the
latest version e.g. like so:
- <programlisting>moduleset = 'gnome-suites-core-deps-3.4'</programlisting>
+ <programlisting>moduleset = 'gnome-suites-core-deps-3.12'</programlisting>
</para>
<para>
After setting the correct moduleset, you need to tell
@@ -8630,9 +8623,9 @@ $ jhbuild sanitycheck</screen>
get started, it helps a lot to pick an existing binding module as an example
to look at.</para>
<para>For instance, let's pretend that we are wrapping a C library called
- libexample. It provides a <classname>GObject</classname>-based API with
- types named, for instance, <classname>ExampleThing</classname> and
- <classname>ExampleStuff</classname>.</para>
+ libsomething. It provides a <classname>GObject</classname>-based API with
+ types named, for instance, <classname>SomeWidget</classname> and
+ <classname>SomeStuff</classname>.</para>
<sect2 id="copying-skeleton-project">
<title>Copying the skeleton project</title>
@@ -8712,7 +8705,7 @@ A number of the skeleton files must still be filled in with project-specific con
generate two or more configuration header files. The first header file
in the list contains all configuration macros which are set during the
configure run. The remaining headers in the list contain only a subset
- of configuration macros and their corresponding <filename>configh.h.in</filename>
+ of configuration macros and their corresponding <filename>config.h.in</filename>
file will not be autogenerated. The reason for this separation is that
the namespaced configuration headers are installed with your library and
define publically visible macros.</para></listitem>
@@ -8838,6 +8831,10 @@ A number of the skeleton files must still be filled in with project-specific con
</varlistentry>
</variablelist>
</para>
+<para>The <filename>skeletonmm/codegen/generate_defs_and_docs.sh</filename> script
+generates all <filename>.defs</filename> files and the <filename>*_docs.xml</filename> file,
+described in the <link linkend="sec-wrapping-documentation">Documentation</link> section.
+</para>
<sect2 id="generating-defs-methods">
<title>Generating the methods .defs</title>
@@ -8864,7 +8861,7 @@ $ ./enum.pl /usr/include/gtk-3.0/gtk/*.h > gtk_enums.defs
<sect2 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>extra_defs</filename> utility that is in every
+ 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>.
For instance
<programlisting>
@@ -8888,8 +8885,8 @@ int main(int, char**)
{
something_init();
- std::cout << get_defs(EXAMPLE_TYPE_SOMETHING)
- << get_defs(EXAMPLE_TYPE_THING);
+ std::cout << get_defs(SOME_TYPE_WIDGET)
+ << get_defs(SOME_TYPE_STUFF);
return 0;
}
</programlisting>
@@ -8900,7 +8897,8 @@ int main(int, char**)
<title>Writing the vfuncs .defs</title>
<para>
This <filename>.defs</filename> file describes virtual functions (vfuncs).
- It must be written by hand. There is no skeleton to start from. You can look
+ 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>
@@ -8919,13 +8917,12 @@ int main(int, char**)
.h or .cc file.</para>
<para>A .hg file will typically include some headers
and then declare a class, using some macros to add API or behaviour to
- this class. For instance, gtkmm's <filename>button.hg</filename> looks
+ this class. For instance, >kmm;'s <filename>button.hg</filename> looks
roughly like this:
<programlisting>
#include <gtkmm/bin.h>
#include <gtkmm/activatable.h>
-#include <gtkmm/stockid.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/bin_p.h)
@@ -8942,7 +8939,6 @@ public:
_CTOR_DEFAULT
explicit Button(const Glib::ustring& label, bool mnemonic = false);
- explicit Button(const StockID& stock_id);
_WRAP_METHOD(void set_label(const Glib::ustring& label), gtk_button_set_label)
@@ -8966,7 +8962,7 @@ public:
</varlistentry>
<varlistentry>
<term><function>_PINCLUDE()</function></term>
- <listitem><para>Tells <command>gmmproc</command> to include a header from the generated
private/button_p.h file.</para></listitem>
+ <listitem><para>Tells <command>gmmproc</command> to include a header in the generated
private/button_p.h file.</para></listitem>
</varlistentry>
<varlistentry>
<term><function>_CLASS_GTKOBJECT()</function></term>
@@ -9110,9 +9106,9 @@ _CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)
struct, registered with
<function>g_boxed_type_register_static()</function>.</para>
<para><function>_CLASS_BOXEDTYPE( C++ class, C class, new function, copy function, free function
)</function></para>
-<para>For instance, for <classname>Gdk::Color</classname>:
+<para>For instance, from <classname>Gdk::RGBA</classname>:
<programlisting>
-_CLASS_BOXEDTYPE(Color, GdkColor, NONE, gdk_color_copy, gdk_color_free)
+_CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)
</programlisting>
</para>
</sect3>
@@ -9137,9 +9133,9 @@ _CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
functions. The new, copy and free functions will be used to instantiate the
default constructor, copy constructor and destructor.</para>
<para><function>_CLASS_OPAQUE_COPYABLE( C++ class, C class, new function, copy function, free function
)</function></para>
-<para>For instance, from <filename>stockitem.hg</filename>:
+<para>For instance, from <classname>Glib::Checksum</classname>:
<programlisting>
-_CLASS_OPAQUE_COPYABLE(StockItem, GtkStockItem, NONE, gtk_stock_item_copy, gtk_stock_item_free)
+_CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)
</programlisting>
</para>
</sect3>
@@ -9182,7 +9178,7 @@ _CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditab
</programlisting>
</para>
<para>Two extra parameters are optional, for the case that the interface derives from another interface,
-which should be the case when the GInterface has another GInterface as a prerequisitite.
+which should be the case when the GInterface has another GInterface as a prerequisite.
For instance, from <filename>loadableicon.hg</filename>:
<programlisting>
_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)
@@ -9210,15 +9206,15 @@ _CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIfac
This prevents the class from being instantiated without using a
<classname>RefPtr</classname>. For instance:
<programlisting>
-class ActionGroup : public Glib::Object
+class TextMark : public Glib::Object
{
- _CLASS_GOBJECT(ActionGroup, GtkActionGroup, GTK_ACTION_GROUP, Glib::Object, GObject)
+ _CLASS_GOBJECT(TextMark, GtkTextMark, GTK_TEXT_MARK, Glib::Object, GObject)
protected:
- _WRAP_CTOR(ActionGroup(const Glib::ustring& name = Glib::ustring()), gtk_action_group_new)
+ _WRAP_CTOR(TextMark(const Glib::ustring& name, bool left_gravity = true), gtk_text_mark_new)
public:
- _WRAP_CREATE(const Glib::ustring& name = Glib::ustring())
+ _WRAP_CREATE(const Glib::ustring& name, bool left_gravity = true)
</programlisting>
</para>
@@ -9301,7 +9297,7 @@ _WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
<varlistentry>
<term>errthrow</term>
<listitem>
- <para>Use the last GError* parameter of the C function to
+ <para>Use the last GError** parameter of the C function to
throw an exception.</para>
</listitem>
</varlistentry>
@@ -9366,20 +9362,20 @@ _WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
<itemizedlist>
<listitem><para>Objects used via <classname>RefPtr</classname>: Pass the
<classname>RefPtr</classname> as a const reference. For instance,
- <code>const Glib::RefPtr<Gtk::Action>&
- action</code>.</para></listitem>
+ <code>const Glib::RefPtr<Gtk::FileFilter>&
+ filter</code>.</para></listitem>
<listitem><para>Const Objects used via <classname>RefPtr</classname>: If the
object should not be changed by the function, then make sure that
the object is const, even if the <classname>RefPtr</classname> is
already const. For instance, <code>const Glib::RefPtr<const
- Gtk::Action>& action</code>.</para></listitem>
+ Gtk::FileFilter>& filter</code>.</para></listitem>
<listitem><para>Wrapping <classname>GList*</classname> and
<classname>GSList*</classname> parameters: First, you need to discover
what objects are contained in the list's data field for each item,
usually by reading the documentation for the C function. The list can
then be wrapped by a <classname>std::vector</classname> type.
For instance, <code>std::vector<
- Glib::RefPtr<Action> ></code>.
+ Glib::RefPtr<Gdk::Pixbuf> ></code>.
You may need to define a Traits type to specify how the C
and C++ types should be converted.</para></listitem>
<listitem><para>Wrapping <classname>GList*</classname> and
@@ -9537,7 +9533,7 @@ _WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)
<varlistentry>
<term>errthrow</term>
<listitem>
- <para>Use the last GError* parameter of the C virtual function (if
+ <para>Use the last GError** parameter of the C virtual function (if
there is one) to throw an exception.</para>
</listitem>
</varlistentry>
@@ -9633,9 +9629,9 @@ _IMPLEMENTS_INTERFACE(Activatable)
<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>widget.hg</filename>:
+<para>For instance, from <filename>enums.hg</filename>:
<programlisting>
-_WRAP_ENUM(WindowType, GdkWindowType)
+_WRAP_ENUM(WindowType, GtkWindowType)
</programlisting>
</para>
<para>If the enum is not a <classname>GType</classname>, you must pass a third parameter NO_GTYPE.
@@ -9657,7 +9653,7 @@ _WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)
using C macros) but including the generated enum documentation is still
desired. It is used with the same syntax as
<function>_WRAP_ENUM()</function> and also process the same options (though
- NO_GTYPE is just ignored because it makes no differene when just generating
+ NO_GTYPE is just ignored because it makes no difference when just generating
the enum's documentation).
</para>
</sect3>
@@ -9725,7 +9721,7 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
<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>_WRP_CTOR()</function> and
+ <function>_WRAP_METHOD()</function>, <function>_WRAP_CTOR()</function> and
<function>_WRAP_CREATE()</function>) in a variety of ways:
</para>
@@ -9762,10 +9758,10 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
</para>
<warning>
<para>
- Please note that when reording parameters for a
+ Please note that when reordering parameters for a
<function>_WRAP_SIGNAL()</function> method signature, the C parameter
names would always be <literal>p0</literal>, <literal>p1</literal>,
- etc. because the <filename>extra_defs</filename> utility uses those
+ etc. because the <filename>generate_extra_defs</filename> utility uses those
parameter names no matter what the C API's parameter names may be.
It's how the utility is written presently.
</para>
@@ -9787,7 +9783,7 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
label);
</programlisting>
Also, say that the C API allowed NULL for the function's
- <parameter>label</parameter> paramter so that that parameter is optional.
+ <parameter>label</parameter> parameter so that that parameter is optional.
It would be possible to have <command>gmmproc</command> generate the
original constructor (with all the parameters) along with an additional
constructor without that optional parameter by appending a
@@ -9806,7 +9802,7 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
<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
- output paramter of the C++ method instead of having the C++ method also
+ output parameter of the C++ method instead of having the C++ method also
return a value like the C function does. To do that, simply include the
output parameter in the C++ method parameter list appending a
<literal>{OUT}</literal> to the output parameter name. For example, if
@@ -9929,7 +9925,7 @@ void init()
<filename>wrap_init.cc</filename> is generated by
<filename>generate_wrap_init.pl</filename>, but the declaration in
<filename>wrap_init.h</filename> is hand-coded, so you will need to adjust
- <filename>wrap_init.h</filename> so that the <function>init()</function>
+ <filename>wrap_init.h</filename> so that the <function>wrap_init()</function>
function appears in the correct C++ namespace.</para>
</sect1>
@@ -10035,7 +10031,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,
-<programlisting>./docextract_to_xml.py -s ~/checkout/gnome/gtk+/gtk/ -s
~/checkout/gnome/gtk+/docs/reference/gtk/ > gtk_docs.xml
+<programlisting>./docextract_to_xml.py -s ~/checkout/gnome/gtk+/gtk/ > gtk_docs.xml
</programlisting>
</para>
<para>Because this automatic transformation is not always appropriate, you might
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
