[gtkmm-documentation] Avoid a translation problem with <programlisting>
- From: Kjell Ahlstedt <kjellahl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtkmm-documentation] Avoid a translation problem with <programlisting>
- Date: Thu, 7 Jan 2021 11:53:30 +0000 (UTC)
commit 9a80bd05a9e45616e756ad8ac2d7473918234b95
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date: Thu Jan 7 11:02:53 2021 +0100
Avoid a translation problem with <programlisting>
* docs/tutorial/C/index-in.docbook:
Avoid <programlisting> elements within <para> elements.
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. See MR !11
docs/tutorial/C/index-in.docbook | 284 ++++++++++++++-------------------------
1 file changed, 102 insertions(+), 182 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index d26f2b8..f4e602f 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -28,6 +28,15 @@ desired (e.g. boldface, monospace, etc) to make it stand out as the project
name
-->
+<!--
+Avoid <programlisting> elements within <para> elements.
+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>.
+-->
+
<!-- The XSL for developer.gnome.org requires this id. -->
<book id="index" lang="en">
@@ -456,9 +465,9 @@ button click result in an action, we set up a
<emphasis>signal handler</emphasis> to catch the button's "clicked" signal.
</para>
<para>>kmm; uses the libsigc++ library to implement signals. Here is an example line of code that connects
a Gtk::Button's "clicked" signal with a signal handler called "on_button_clicked":
+</para>
<programlisting>m_button1.signal_clicked().connect( sigc::mem_fun(*this,
&HelloWorld::on_button_clicked) );</programlisting>
-</para>
<para>For more detailed information about signals, see the <link
linkend="chapter-signals">appendix</link>.</para>
<para>For information about implementing your own signals rather than
@@ -498,12 +507,11 @@ the <classname>GObject</classname> system.</para>
To use a >kmm; instance with a C function that requires a C
<classname>GObject</classname> instance, use the C++ instance’s
<function>gobj()</function> function to obtain a pointer to the underlying C
-instance. For example:
+instance. For example:</para>
<programlisting>
Gtk::Button button("example");
gtk_button_do_something_that_gtkmm_cannot(button.gobj());
</programlisting>
-</para>
<para>
To obtain a >kmm; instance from a C <classname>GObject</classname> instance,
@@ -2594,8 +2602,8 @@ for (auto row: refModel->children())
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:
-<programlisting>Gtk::TreeModel::Children children = row.children();</programlisting>
</para>
+<programlisting>Gtk::TreeModel::Children children = row.children();</programlisting>
</sect2>
</sect1>
@@ -2614,8 +2622,8 @@ To find out what rows the user has selected, get the
<para>
By default, only single rows can be selected, but you can allow
multiple selection by setting the mode, like so:
-<programlisting>refTreeSelection->set_mode(Gtk::SELECTION_MULTIPLE);</programlisting>
</para>
+<programlisting>refTreeSelection->set_mode(Gtk::SELECTION_MULTIPLE);</programlisting>
</sect2>
<sect2 id="treeview-selected-rows">
@@ -3021,8 +3029,8 @@ You might need to react to every change of selection in the ComboBox, for instan
<sect2 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:
-<programlisting>m_combo.set_entry_text_column(m_columns.m_col_name);</programlisting>
</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>
@@ -3205,8 +3213,8 @@ 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:
-<programlisting>refBuffer->insert_with_tag(iter, "Some text", refTagMatch);</programlisting>
</para>
+<programlisting>refBuffer->insert_with_tag(iter, "Some text", refTagMatch);</programlisting>
<para>
You can apply more than one <classname>Tag</classname> to the same text, by
@@ -4368,13 +4376,12 @@ myContext->set_line_width(2.0);]]>
by different amounts in the X and Y directions. For example, to draw
an ellipse with center at <varname>x</varname>, <varname>y</varname>
and size <varname>width</varname>, <varname>height</varname>:
-
- <programlisting>context->save();
+ </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>
- </para>
<sect2 id="cairo-example-arcs">
<title>Example</title>
<para>
@@ -5043,13 +5050,12 @@ and to access the selected <classname>Gtk::PaperSize</classname>,
<para>You should save the chosen <classname>Gtk::PageSetup</classname>
so you can use it again if the page setup dialog is shown again.</para>
-<para>For instance,
+<para>For instance,</para>
<programlisting>
//Within a class that inherits from Gtk::Window and keeps m_refPageSetup and m_refSettings as members...
auto new_page_setup = Gtk::run_page_setup_dialog(*this, m_refPageSetup, m_refSettings);
m_refPageSetup = new_page_setup;
</programlisting>
-</para>
<para>
<ulink url="&url_refdocs_base_gtk;PageSetup.html">Reference</ulink>
@@ -5108,7 +5114,7 @@ and handle the result or error you need to implement signal handlers for
the <literal>done</literal> and <literal>status_changed</literal> signals:
</para>
-<para>For instance,
+<para>For instance,</para>
<programlisting>
// in class ExampleWindow's method...
auto op = PrintOperation::create();
@@ -5116,9 +5122,9 @@ auto op = PrintOperation::create();
op->signal_done().connect(sigc::bind(sigc::mem_fun(*this, &ExampleWindow::on_printoperation_done), op));
// run the op
</programlisting>
-</para>
<para>Second, check for an error and connect to the <literal>status_changed</literal> signal. For instance:
+</para>
<programlisting>
void ExampleWindow::on_printoperation_done(Gtk::PrintOperationResult result, const
Glib::RefPtr<PrintOperation>& op)
{
@@ -5131,9 +5137,8 @@ void ExampleWindow::on_printoperation_done(Gtk::PrintOperationResult result, con
op->signal_status_changed().connect(sigc::bind(sigc::mem_fun(*this,
&ExampleWindow::on_printoperation_status_changed), op));
}
</programlisting>
-</para>
-<para>Finally, check the status. For instance,
+<para>Finally, check the status. For instance,</para>
<programlisting>
void ExampleWindow::on_printoperation_status_changed(const Glib::RefPtr<PrintOperation>& op)
{
@@ -5145,7 +5150,6 @@ void ExampleWindow::on_printoperation_status_changed(const Glib::RefPtr<Print
//update UI
}
</programlisting>
-</para>
</sect1>
@@ -5153,7 +5157,7 @@ void ExampleWindow::on_printoperation_status_changed(const Glib::RefPtr<Print
<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...
@@ -5161,8 +5165,6 @@ op->set_export_filename("test.pdf");
auto res = op->run(Gtk::PRINT_OPERATION_ACTION_EXPORT);
</programlisting>
-</para>
-
</sect1>
<sect1 id="sec-extending-print-dialog">
@@ -5197,7 +5199,7 @@ previously created, to simplify things you can keep the widgets you expect
to contain some user input as class members. For example, let's say you have
a <classname>Gtk::Entry</classname> called <literal>m_Entry</literal> as
a member of your <classname>CustomPrintOperation</classname> class:
-
+</para>
<programlisting>
Gtk::Widget* CustomPrintOperation::on_create_custom_widget()
{
@@ -5221,8 +5223,6 @@ void CustomPrintOperation::on_custom_widget_apply(Gtk::Widget* /* widget */)
}
</programlisting>
-</para>
-
<para>
The example in examples/book/printing/advanced demonstrates this.
</para>
@@ -5234,7 +5234,7 @@ The example in examples/book/printing/advanced demonstrates this.
<para>
The native GTK print dialog has a preview button, but you may also start
-a preview directly from an application:
+a preview directly from an application:</para>
<programlisting>
// in a class that inherits from Gtk::Window...
@@ -5242,7 +5242,6 @@ auto op = PrintOperation::create();
// ...set up op...
op->run(Gtk::PRINT_OPERATION_ACTION_PREVIEW, *this);
</programlisting>
-</para>
<para>
On Unix, the default preview handler uses an external viewer program.
@@ -5538,6 +5537,7 @@ if (info)
</para>
<para>
Here's a simple example:
+ </para>
<programlisting>
bool on_key_press_or_release_event(GdkEventKey* event)
{
@@ -5557,7 +5557,6 @@ Gtk::Entry m_entry; // in a class definition
m_entry.signal_key_press_event().connect( sigc::ptr_fun(&on_key_press_or_release_event) );
m_entry.signal_key_release_event().connect( sigc::ptr_fun(&on_key_press_or_release_event) );
</programlisting>
- </para>
<sect2 id="keyboardevents-simple-example">
<title>Example</title>
@@ -5663,12 +5662,10 @@ you have several options. Using the following methods you can create a timeout
method that will be called every few milliseconds.
</para>
-<para>
<programlisting>
sigc::connection Glib::SignalTimeout::connect(const sigc::slot<bool()>& slot,
unsigned int interval, int priority = Glib::PRIORITY_DEFAULT);
</programlisting>
-</para>
<para>
The first argument is a <classname>slot</classname> you wish to have called
@@ -5678,12 +5675,9 @@ between calls to that method. You receive a
the connection using its <methodname>disconnect()</methodname> method:
</para>
-<para>
-
<programlisting>
my_connection.disconnect();
</programlisting>
-</para>
<para>
Another way of destroying the connection is your signal handler.
@@ -5691,13 +5685,12 @@ It has to be of the type <classname>sigc::slot<bool()></classname>.
As you see from the definition your signal handler has to return a value of
the type <literal>bool</literal>. A definition of a sample method might
look like this:
+</para>
<programlisting>
bool MyCallback() { std::cout << "Hello World!\n" << std::endl; return true; }
</programlisting>
-</para>
-
<para>
You can stop the timeout method by returning <literal>false</literal> from
your signal handler. Therefore, if you want your
@@ -5722,13 +5715,11 @@ for you. This is especially useful for networking applications. The
following method is used to do this:
</para>
-<para>
<programlisting>
sigc::connection Glib::SignalIO::connect(const sigc::slot<bool(Glib::IOCondition)>& slot,
Glib::PollFD::fd_t fd, Glib::IOCondition condition,
int priority = Glib::PRIORITY_DEFAULT);
</programlisting>
-</para>
<para>
The first argument is a slot you wish to have called when
@@ -5783,11 +5774,9 @@ this file descriptor using its <methodname>disconnect()</methodname> method. The
<parameter>slot</parameter> signal handler should be declared as follows:
</para>
-<para>
<programlisting>
bool input_callback(Glib::IOCondition condition);
</programlisting>
-</para>
<para>
where <parameter>condition</parameter> is as
@@ -5816,12 +5805,10 @@ testfifo</literal>.
If you want to specify a method that gets called when nothing else is happening, use the following:
</para>
-<para>
<programlisting>
sigc::connection Glib::SignalIdle::connect(const sigc::slot<bool()>& slot,
int priority = Glib::PRIORITY_DEFAULT_IDLE);
</programlisting>
-</para>
<para>
This causes >kmm; to call the specified method whenever nothing else is
@@ -5832,11 +5819,9 @@ happening. You can add a priority (lower numbers are higher priorities). There a
as follows:
</para>
-<para>
<programlisting>
bool idleFunc();
</programlisting>
-</para>
<para>
Since this is very similar to the methods above this explanation should
@@ -5900,7 +5885,6 @@ The primary disadvantage of using class scope widgets is revealing
the class implementation rather than the class interface in the class header.
</para>
-<para>
<programlisting>
#include <gtkmm/button.h>
#include <gtkmm/window.h>
@@ -5911,7 +5895,6 @@ private:
// will be destroyed when the Foo object is destroyed
};
</programlisting>
-</para>
</sect3>
<sect3 id="memory-function-scope">
@@ -5921,6 +5904,7 @@ private:
If a programmer does not need a class scope widget, a function scope widget
may also be used. The advantages to function scope over class scope are the
increased data hiding and reduced dependencies.
+</para>
<programlisting>
{
Gtk::Button aButton;
@@ -5929,7 +5913,6 @@ increased data hiding and reduced dependencies.
app->run();
}
</programlisting>
-</para>
</sect3>
<sect3 id="memory-dynamic-allocation">
@@ -5998,7 +5981,6 @@ avoids you having to write <literal>new</literal>, which is discouraged in
modern C++ style, and more clearly expresses intent to create a managed widget.
</para>
-<para>
<programlisting>
MyContainer::MyContainer()
{
@@ -6006,6 +5988,7 @@ MyContainer::MyContainer()
append(*pButton); //add *pButton to MyContainer
}
</programlisting>
+<para>
Now, when objects of type <classname>MyContainer</classname> are destroyed, the
button will also be deleted. It is no longer necessary to delete <varname>pButton</varname>
to free the button's memory; its deletion has been delegated to the
@@ -6047,15 +6030,16 @@ smartpointer, <classname>Cairo::RefPtr<></classname>.
<para>
Objects such as <classname>Gdk::Pixbuf</classname> can only be instantiated
with a <methodname>create()</methodname> function. For instance,
+</para>
<programlisting>
auto pixbuf = Gdk::Pixbuf::create_from_file(filename);
</programlisting>
-</para>
<para>
You have no way of getting a bare <classname>Gdk::Pixbuf</classname>. In the
example, <varname>pixbuf</varname> is a smart pointer, so you can do this, much
like a normal pointer:
+</para>
<programlisting>
auto width = 0;
if(pixbuf)
@@ -6063,7 +6047,6 @@ if(pixbuf)
width = pixbuf->get_width();
}
</programlisting>
-</para>
<para>
When <varname>pixbuf</varname> goes out of scope an
@@ -6139,10 +6122,10 @@ This will instantiate the windows defined in the <filename>.glade</filename> fil
</para>
<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");
</programlisting>
-</para>
</sect1>
@@ -6155,10 +6138,10 @@ the <methodname>get_widget()</methodname> method, providing the widget's name. T
name should be specified in the <application>Glade</application> Properties
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");]]>
</programlisting>
-</para>
<para>
<application>Gtk::Builder</application> checks for a null pointer, and checks
@@ -6211,10 +6194,10 @@ having most of your source just be setting properties and packing in containers.
</para>
<para>Use <methodname>Gtk::Builder::get_widget_derived()</methodname> like so:
+</para>
<programlisting>
<![CDATA[auto pDialog = Gtk::Builder::get_widget_derived<DerivedDialog>(builder, "DialogDerived");]]>
</programlisting>
-</para>
<para>
Your derived class must have a constructor that takes a pointer to the
@@ -6226,18 +6209,19 @@ typedefs <classname>BaseObjectType</classname> as <type>GtkDialog</type>, for in
<para>
You must call the base class's constructor in the initialization list, providing the C pointer. For
instance,
+</para>
<programlisting>
DerivedDialog::DerivedDialog(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
: Gtk::Dialog(cobject)
{
}
</programlisting>
-</para>
<para>
You could then encapsulate the manipulation of the child widgets in the
constructor of the derived class, maybe using <methodname>get_widget()</methodname>
or <methodname>get_widget_derived()</methodname> again. For instance,
+</para>
<programlisting>
<![CDATA[DerivedDialog::DerivedDialog(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
: Gtk::Dialog(cobject),
@@ -6251,7 +6235,6 @@ or <methodname>get_widget_derived()</methodname> again. For instance,
}
}]]>
</programlisting>
-</para>
<para>
It's possible to pass additional arguments from
@@ -6284,6 +6267,7 @@ to create an instance of your derived widget just to have its class registered.
Your derived widget must have a constructor that has the parameters required by
<methodname>get_widget_derived()</methodname> and calls the <classname>Glib::ObjectBase</classname>
constructor to register the <type>GType</type>.
+</para>
<programlisting>
<![CDATA[DerivedButton::DerivedButton(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
: Glib::ObjectBase("MyButton"), // The GType name will be gtkmm__CustomObject_MyButton.
@@ -6294,7 +6278,6 @@ constructor to register the <type>GType</type>.
// ....
}]]>
</programlisting>
-</para>
<para>
When using >kmm; with a version of <application>glibmm</application> from 2.62
onwards, it is possible also to specify properties of derived widgets, declared
@@ -6581,18 +6564,18 @@ desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
number references. To generate such a file named
<literal>my-strings</literal>, execute the following command,
within the source code directory:
-
- <programlisting>xgettext -a -o my-strings --omit-header *.cc *.h</programlisting>
</para>
+ <programlisting>xgettext -a -o my-strings --omit-header *.cc *.h</programlisting>
+
<para>
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.
+ </para>
<programlisting>bindtextdomain(GETTEXT_PACKAGE, PROGRAMNAME_LOCALEDIR);
bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
textdomain(GETTEXT_PACKAGE);</programlisting>
- </para>
<sect2 id="sec-i18n-gettext">
<title>How gettext works</title>
@@ -6637,8 +6620,8 @@ textdomain(GETTEXT_PACKAGE);</programlisting>
translation for a new locale. In order to do that, go to the
<filename>po</filename> subdirectory of your project and
execute the following command:
- <programlisting>intltool-update --pot</programlisting>
</para>
+ <programlisting>intltool-update --pot</programlisting>
<para>
That will create a file named <filename>programname.pot</filename>.
@@ -6747,13 +6730,13 @@ contained non-ASCII characters and the current locale is not UTF-8 encoded, the
result is a corrupted <classname>Glib::ustring</classname>. You can work around
this with a manual conversion. For instance, to retrieve the
<classname>std::string</classname> from a <classname>ostringstream</classname>:
+</para>
<programlisting>std::locale::global(std::locale("")); // Set the global locale to the user's preferred
locale.
// Usually unnecessary here, because Glib::init()
// or Gtk::Application::create() does it for you.
std::ostringstream output;
output << percentage << " % done";
label->set_text(Glib::locale_to_utf8(output.str()));</programlisting>
-</para>
</sect2>
</sect1>
@@ -6812,11 +6795,11 @@ label.set_text(_("Really delete ") + filename + _(" now?"));</programlisting>
So you should either avoid this situation or use
<ulink url="&url_refdocs_base_glib;ustring.html"><function>Glib::ustring::compose()</function></ulink>
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>
-</para>
</sect2>
<sect2 id="i18n-display-size">
@@ -7673,22 +7656,22 @@ Next, we need to connect our settings to the widgets that they are supposed to c
One convenient way to do this is to use <methodname>Gio::Settings::bind()</methodname>
to bind settings keys to object properties, as we do for the transition setting in
<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());]]>
</programlisting>
-</para>
<para>
The code to connect the font setting is a little more involved, since it corresponds to
an object property in a <classname>Gtk::TextTag</classname> that we must first create.
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());]]>
</programlisting>
-</para>
<para>
At this point, the application will already react if you change one of the settings,
@@ -7703,11 +7686,11 @@ a <classname>Gtk::Builder</classname> ui file and settings bindings.
When we've created the <filename>prefs.ui</filename> file and the <classname>ExampleAppPrefs</classname>
class, we revisit the <methodname>ExampleApplication::on_action_preferences()</methodname>
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();]]>
</programlisting>
-</para>
<para>
After all this work, our application can now show a preference dialog like this:
@@ -7742,6 +7725,7 @@ below the header bar. The new widgets are added in the <filename>window.ui</file
Implementing the search needs quite a few code changes that we are not going to completely
go over here. The central piece of the search implementation is a signal handler that
listens for text changes in the search entry, shown here without error handling.
+</para>
<programlisting>
<![CDATA[void ExampleAppWindow::on_search_text_changed()
{
@@ -7761,7 +7745,6 @@ listens for text changes in the search entry, shown here without error handling.
}
}]]>
</programlisting>
-</para>
<para>
With the search bar, our application now looks like this:
@@ -7798,6 +7781,7 @@ the ui file <filename>gears_menu.ui</filename>.
To connect the menu item to the new <literal>show-words</literal> setting, we use a
<classname>Gio::Action</classname> corresponding to the given <classname>Gio::Settings</classname>
key. In <classname>ExampleAppWindow</classname>'s constructor:
+</para>
<programlisting>
<![CDATA[// 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.
@@ -7807,7 +7791,6 @@ 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>
<para>
What our application looks like now:
@@ -7851,12 +7834,12 @@ Since we want both labels to appear and disappear together, we bind the <literal
property of the <literal>lines_label</literal> widget to the same property of the
<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>
-</para>
<para>
We also need a function that counts the lines of the currently active tab, and updates
@@ -7894,11 +7877,11 @@ property is set in the <filename>window.ui</filename> file, to show only the clo
button, and hide the minimize and maximize buttons. We also include an icon in the
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");
set_icon_name("exampleapp");
]]>
</programlisting>
-</para>
<para>
Here is how the application now looks:
@@ -7974,46 +7957,38 @@ 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
instance.
</para>
-<para>
<programlisting>
auto refPixbuf = Gdk::Pixbuf::create_from_file(filename);
auto refPixbuf2 = refPixbuf;
</programlisting>
-</para>
<para>
Of course this means that you can store <classname>RefPtr</classname>s in
standard containers, such as <classname>std::vector</classname> or
<classname>std::list</classname>.</para>
-<para>
<programlisting>
std::list<Glib::RefPtr<Gdk::Pixbuf>> listPixbufs;
auto refPixbuf = Gdk::Pixbuf::create_from_file(filename);
listPixbufs.push_back(refPixbuf);
</programlisting>
-</para>
</sect1>
<sect1 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>
-<para>
<programlisting>
auto refPixbuf = Gdk::Pixbuf::create_from_file(filename);
auto width = refPixbuf->get_width();
</programlisting>
-</para>
<para>You can also use the * operator and the <methodname>get()</methodname> method
to access the underlying instance, but it's usually a bad idea to do so. Unless
you are careful, you can end up with a pointer or a reference which is not included
in the reference count.
</para>
-<para>
<programlisting>
auto refPixbuf = Gdk::Pixbuf::create_from_file(filename);
auto& underlying = *refPixbuf; // Possible, but not recommended
</programlisting>
-</para>
</sect1>
<sect1 id="sec-refptr-casting"><title>Casting</title>
@@ -8021,12 +7996,10 @@ auto& underlying = *refPixbuf; // Possible, but not recommended
You can cast <classname>RefPtr</classname>s to base types, just like normal
pointers.
</para>
-<para>
<programlisting>
auto refStore = Gtk::TreeStore::create(columns);
Glib::RefPtr<Gtk::TreeModel> refModel = refStore;
</programlisting>
-</para>
<para>This means that any method which takes a <type>const
Glib::RefPtr<BaseType>&</type> argument can also take a
<type>const Glib::RefPtr<DerivedType>&</type>. The cast is
@@ -8034,12 +8007,10 @@ implicit, just as it would be for a normal pointer.</para>
<para>You can also cast to a derived type, but the syntax is
a little different than with a normal pointer.
</para>
-<para>
<programlisting>
auto refStore = std::dynamic_pointer_cast<Gtk::TreeStore>(refModel);
auto refStore2 = std::static_pointer_cast<Gtk::TreeStore>(refModel);
</programlisting>
-</para>
</sect1>
<sect1 id="sec-refptr-checking-for-null"><title>Checking for nullptr</title>
@@ -8047,7 +8018,6 @@ auto refStore2 = std::static_pointer_cast<Gtk::TreeStore>(refModel);
Just like normal pointers, you can check whether a
<classname>RefPtr</classname> points to anything.
</para>
-<para>
<programlisting>
auto refModel = m_TreeView.get_model();
if (refModel)
@@ -8056,7 +8026,6 @@ if (refModel)
...
}
</programlisting>
-</para>
<para>
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.
@@ -8107,7 +8076,6 @@ signal handlers are often named callbacks.
Here's an example of a signal handler being connected to a signal:
</para>
-<para>
<programlisting>
#include <gtkmm/button.h>
@@ -8122,7 +8090,6 @@ int main()
button.signal_clicked().connect(sigc::ptr_fun(&on_button_clicked));
}
</programlisting>
-</para>
<para>
There's rather a lot to think about in this (non-functional) code.
@@ -8157,13 +8124,11 @@ When the Button emits its <literal>clicked</literal> signal,
Now let's look at the connection again:
</para>
-<para>
<programlisting>
...
button.signal_clicked().connect(sigc::ptr_fun(&on_button_clicked));
...
</programlisting>
-</para>
<para>
Note that we don't pass a pointer to <methodname>on_button_clicked()</methodname>
@@ -8185,7 +8150,6 @@ known as function objects, or functors.
Here's a slightly larger example of slots in action:
</para>
-<para>
<programlisting>
void on_button_clicked();
@@ -8203,7 +8167,6 @@ int main()
button.signal_clicked().connect( sigc::mem_fun(some_object, &some_class::on_button_clicked) );
}
</programlisting>
-</para>
<para>
The first call to <methodname>connect()</methodname> is just like the one we saw
@@ -8245,11 +8208,9 @@ look it up in the reference documentation or the header file. Here's an example
might see in the >kmm; headers:
</para>
-<para>
<programlisting>
Glib::SignalProxy<bool(Gtk::DirectionType)> signal_focus()
</programlisting>
-</para>
<para>
Other than the signal's name (<literal>focus</literal>), the template arguments are
@@ -8265,11 +8226,9 @@ The same principles apply for signals which have more arguments. Here's one
with three (taken from <filename><gtkmm/textbuffer.h></filename>):
</para>
-<para>
<programlisting>
Glib::SignalProxy<void(TextBuffer::iterator&, const Glib::ustrin&, int)> signal_insert();
</programlisting>
-</para>
<para>
It follows the same form. The first type is <type>void</type>, so that should be
@@ -8278,11 +8237,9 @@ The following three types are the argument types, in order. Our signal
handler's prototype could look like this:
</para>
-<para>
<programlisting>
void on_insert(TextBuffer::iterator& pos, const Glib::ustring& text, int bytes)
</programlisting>
-</para>
</sect1>
<sect1 id="sec-disconnecting-signal-handlers">
@@ -8292,11 +8249,9 @@ void on_insert(TextBuffer::iterator& pos, const Glib::ustring& text, int
Let's take another look at a Signal's <literal>connect</literal> method:
</para>
-<para>
<programlisting>
sigc::connection signal<void(int)>::connect(const sigc::slot<void(int)>&);
</programlisting>
-</para>
<para>
The returned <classname>sigc::connection</classname> can be used to control the
@@ -8336,7 +8291,6 @@ virtual member methods specifically intended to be overridden.
Let's look at an example of overriding:
</para>
-<para>
<programlisting>
#include <gtkmm/button.h>
@@ -8354,7 +8308,6 @@ void OverriddenButton::on_clicked()
Gtk::Button::on_clicked();
}
</programlisting>
-</para>
<para>
Here we define a new class called <classname>OverriddenButton</classname>,
@@ -8441,13 +8394,12 @@ Handling an X event doesn't affect the Widget's other signals. If you handle
</para>
<para>
-Here's a simple example:
+Here's a simple example:</para>
<programlisting>
bool on_button_press(GdkEventButton* event);
Gtk::Button button("label");
button.signal_button_press_event().connect( sigc::ptr_fun(&on_button_press) );
</programlisting>
-</para>
<para>
When the mouse is over the button and a mouse button is pressed,
<methodname>on_button_press()</methodname> will be called.
@@ -8469,10 +8421,10 @@ to stop other signal handlers from being called. To specify that your signal han
should be called before the other signal handlers, so that it will always be called,
you can specify <literal>false</literal> for the optional <literal>after</literal>
parameter. For instance,
+</para>
<programlisting>
button.signal_button_press_event().connect( sigc::ptr_fun(&on_mywindow_button_press), false );
</programlisting>
-</para>
<para>The event is delivered first to the widget the event occurred in. If all
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
@@ -8497,6 +8449,7 @@ use <ulink url="http://www.gnu.org/software/gdb/";>the gdb debugger</ulink>.
<para>
First, let's look at a simple example where an exception is thrown from a normal
function (no signal handler).
+</para>
<programlisting>
// without_signal.cc
#include <gtkmm.h>
@@ -8514,7 +8467,6 @@ int main(int argc, char** argv)
return app->run();
}
</programlisting>
-</para>
<para>
Here is an excerpt from a <application>gdb</application> session. Only the most
interesting parts of the output are shown.
@@ -8534,6 +8486,7 @@ line 6 (<code>throw "Something";</code>).
<para>
Now let's see what happens when an exception is thrown from a signal handler.
Here's the source code.
+</para>
<programlisting>
// with_signal.cc
#include <gtkmm.h>
@@ -8552,7 +8505,6 @@ int main(int argc, char** argv)
return app->run();
}
</programlisting>
-</para>
<para>
And here's an excerpt from a <application>gdb</application> session.
<programlisting>
@@ -8578,6 +8530,7 @@ caught in <application>glibmm</application> or >kmm;, and
<para>
To see where the exception is thrown, you can use the <application>gdb</application>
command <userinput>catch throw</userinput>.
+</para>
<programlisting>
> gdb with_signal
(gdb) catch throw
@@ -8594,7 +8547,6 @@ unhandled exception (type unknown) in signal handler
Program received signal SIGTRAP, Trace/breakpoint trap.
</programlisting>
-</para>
<para>
If there are many caught exceptions before the interesting uncaught one, this
method can be tedious. It can be automated with the following
@@ -8636,14 +8588,15 @@ non-GTK signals, you can create pure C++ signals, using the
For instance, to create a signal that sends 2 parameters, a <type>bool</type>
and an <type>int</type>, just declare a <classname>sigc::signal</classname>,
like so:
+</para>
<programlisting>
sigc::signal<void(bool, int)> signal_something;
</programlisting>
-</para>
<para>
You could just declare that signal as a public member variable, but
some people find that distasteful and prefer to make it available via
an accessor method, like so:
+</para>
<programlisting>
class Server
{
@@ -8661,16 +8614,15 @@ Server::type_signal_something Server::signal_something()
return m_signal_something;
}
</programlisting>
-</para>
<para>
You can then connect to the signal using the same syntax used when
connecting to >kmm; signals. For instance,
+</para>
<programlisting>
server.signal_something().connect(
sigc::mem_fun(client, &Client::on_server_something) );
</programlisting>
-</para>
<sect1 id="chapter-custom-signals-example"><title>Example</title>
@@ -8802,15 +8754,15 @@ practical - and sensible - to subclass a button for that purpose.
The >kmm; module is defined in the
<filename>gnome-suites-core-deps-latest.modules</filename> moduleset. So edit your
<filename>jhbuildrc</filename> file and set your moduleset setting like so:
- <programlisting>moduleset = 'gnome-suites-core-deps-latest'</programlisting>
</para>
+ <programlisting>moduleset = 'gnome-suites-core-deps-latest'</programlisting>
<para>
After setting the correct moduleset, you need to tell
<application>jhbuild</application> which module or modules to build. To
build >kmm; and all of its dependencies, set <varname>modules</varname>
like so:
- <programlisting>modules = [ 'gtkmm' ]</programlisting>
</para>
+ <programlisting>modules = [ 'gtkmm' ]</programlisting>
<para>
You can build several modules by setting the
<varname>modules</varname> variable to a meta-package, e.g.
@@ -8941,11 +8893,11 @@ $ jhbuild sanitycheck</screen>
skeleton source tree</ulink> 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>.
+</para>
<programlisting>
$ git clone https://gitlab.gnome.org/GNOME/mm-common.git
$ cp -a mm-common/skeletonmm libsomethingmm
</programlisting>
-</para>
<para>This provides a directory structure for the source .hg and .ccg files and the hand-written
.h and .cc files, with <filename>meson.build</filename> files that can specify the
various files in use, in terms of Meson variables. The directory structure usually
@@ -9106,10 +9058,10 @@ described in the <link linkend="sec-wrapping-documentation">Documentation</link>
<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,
+</para>
<programlisting>
$ ./h2def.py /usr/include/gtk-4.0/gtk/*.h > gtk_methods.defs
</programlisting>
-</para>
</sect2>
<sect2 id="generating-defs-enums">
@@ -9117,10 +9069,10 @@ $ ./h2def.py /usr/include/gtk-4.0/gtk/*.h > gtk_methods.defs
<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,
+</para>
<programlisting>
$ ./enum.pl /usr/include/gtk-4.0/gtk/*.h > gtk_enums.defs
</programlisting>
-</para>
</sect2>
<sect2 id="generating-defs-signals-properties">
@@ -9129,11 +9081,11 @@ $ ./enum.pl /usr/include/gtk-4.0/gtk/*.h > gtk_enums.defs
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
+</para>
<programlisting>
$ cd tools/extra_defs_gen
$ ./generate_extra_defs > gtk_signals.defs
</programlisting>
-</para>
<para>You must edit the source code of your own <filename>generate_extra_defs</filename> tool
in order to generate the <filename>.defs</filename> for the GObject C types that you wish to
wrap. In the skeleton source tree, the source file is named
@@ -9143,6 +9095,7 @@ $ ./generate_extra_defs > gtk_signals.defs
file should also mention the new source filename.</para>
<para>Then edit the <filename>.cc</filename> file to specify the correct types.
For instance, your <function>main()</function> function might look like this:
+</para>
<programlisting>
#include <glibmm_generate_extra_defs/generate_extra_defs.h>
#include <libsomething.h>
@@ -9157,7 +9110,6 @@ int main(int, char**)
return 0;
}
</programlisting>
-</para>
</sect2>
<sect2 id="writing-defs-vfuncs">
@@ -9185,7 +9137,7 @@ int main(int, char**)
<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, >kmm;'s <filename>button.hg</filename> looks
- roughly like this:
+ roughly like this:</para>
<programlisting>
#include <gtkmm/bin.h>
@@ -9220,7 +9172,6 @@ public:
} // namespace Gtk
</programlisting>
-</para>
<para>The macros in this example do the following:
<variablelist>
<varlistentry>
@@ -9254,11 +9205,11 @@ public:
<para>The .h and .cc files will be generated from the .hg and .ccg files by
processing them with <command>gmmproc</command> like so, though this happens
automatically when using the above build structure:
+</para>
<programlisting>
$ cd gtk/src
$ /usr/lib/glibmm-2.68/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm
</programlisting>
-</para>
<para>Notice that we provided <command>gmmproc</command> with the path to the
.m4 convert files, the path to the .defs file, the name of a .hg file, the
source directory, and the destination directory.</para>
@@ -9278,10 +9229,10 @@ This allows it to call a C function in the implementation of your C++ method,
passing the appropriate parameters to that C functon. For instance, this
tells <command>gmmproc</command> how to convert a <classname>GtkTreeView</classname>
pointer to a <classname>Gtk::TreeView</classname> pointer:
+</para>
<programlisting>
_CONVERSION(`GtkTreeView*',`TreeView*',`Glib::wrap($3)')
</programlisting>
-</para>
<para><literal>$3</literal> will be replaced by the parameter name when this
conversion is used by <command>gmmproc</command>.
@@ -9290,12 +9241,12 @@ conversion is used by <command>gmmproc</command>.
<para>
Some extra macros make this easier and consistent. Look in >kmm;'s .m4 files
for examples. For instance:
+</para>
<programlisting>
_CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P)
_CONVERSION(`const PrintSettings&',`GtkPrintSettings*',__FCR2P)
_CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REFPTR_TO_P($3))
</programlisting>
-</para>
</sect2>
<sect2 id="gmmproc-m4-initializations">
@@ -9315,10 +9266,10 @@ _CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REF
also return the widget, it was desirable to have the C++ method place the
widget in a specified output parameter, an initialization macro such as the
following would be necessary:
+</para>
<programlisting>
_INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
</programlisting>
-</para>
<para>
<literal>$3</literal> will be replaced by the output parameter name of the
@@ -9347,11 +9298,10 @@ _INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
<classname>GObject</classname>, but whose wrapper is not derived from
<classname>Gtk::Object</classname>.</para>
<para><function>_CLASS_GOBJECT( C++ class, C class, C casting macro, C++ base class, C base class
)</function></para>
-<para>For instance, from <filename>accelgroup.hg</filename>:
+<para>For instance, from <filename>accelgroup.hg</filename>:</para>
<programlisting>
_CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-class-gtkobject">
@@ -9359,11 +9309,10 @@ _CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject
<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>
-<para>For instance, from <filename>button.hg</filename>:
+<para>For instance, from <filename>button.hg</filename>:</para>
<programlisting>
_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)
</programlisting>
-</para>
<para>You will typically use this macro when the class already derives from
<classname>Gtk::Object</classname>. For instance, you will use it when wrapping
a GTK Widget, because <classname>Gtk::Widget</classname> derives from
@@ -9383,11 +9332,10 @@ _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, from <classname>Gdk::RGBA</classname>:
+<para>For instance, from <classname>Gdk::RGBA</classname>:</para>
<programlisting>
_CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-class-boxedtype-static">
@@ -9397,11 +9345,10 @@ _CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)
<function>_CLASS_BOXEDTYPE</function>, but the C struct is not allocated
dynamically.</para>
<para><function>_CLASS_BOXEDTYPE_STATIC( C++ class, C class )</function></para>
-<para>For instance, for <classname>Gdk::Rectangle</classname>:
+<para>For instance, for <classname>Gdk::Rectangle</classname>:</para>
<programlisting>
_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-class-opaque-copyable">
@@ -9410,11 +9357,10 @@ _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 <classname>Glib::Checksum</classname>:
+<para>For instance, from <classname>Glib::Checksum</classname>:</para>
<programlisting>
_CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-class-opaque-refcounted">
@@ -9423,11 +9369,10 @@ _CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_fr
C++ wrapper cannot be directly instantiated and can only be used with
<classname>Glib::RefPtr</classname>.</para>
<para><function>_CLASS_OPAQUE_REFCOUNTED( C++ class, C class, new function, ref function, unref function
)</function></para>
-<para>For instance, for <classname>Pango::Coverage</classname>:
+<para>For instance, for <classname>Pango::Coverage</classname>:</para>
<programlisting>
_CLASS_OPAQUE_REFCOUNTED(Coverage, PangoCoverage, pango_coverage_new, pango_coverage_ref,
pango_coverage_unref)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-class-generic">
@@ -9435,11 +9380,10 @@ _CLASS_OPAQUE_REFCOUNTED(Coverage, PangoCoverage, pango_coverage_new, pango_cove
<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>
-<para>For instance, for <classname>Pango::AttrIter</classname>:
+<para>For instance, for <classname>Pango::AttrIter</classname>:</para>
<programlisting>
_CLASS_GENERIC(AttrIter, PangoAttrIterator)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-class-interface">
@@ -9449,18 +9393,16 @@ _CLASS_GENERIC(AttrIter, PangoAttrIterator)
</para>
<para><function>_CLASS_INTERFACE( C++ class, C class, C casting macro, C interface struct, Base C++ class
(optional), Base C class (optional) )</function></para>
<para>
-For instance, from <filename>celleditable.hg</filename>:
+For instance, from <filename>celleditable.hg</filename>:</para>
<programlisting>
_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)
</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 prerequisite.
-For instance, from <filename>loadableicon.hg</filename>:
+For instance, from <filename>loadableicon.hg</filename>:</para>
<programlisting>
_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)
</programlisting>
-</para>
</sect3>
</sect2>
@@ -9481,7 +9423,7 @@ _CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIfac
be protected (rather than public) and each constructor should have a
corresponding <function>_WRAP_CREATE()</function> in the public section.
This prevents the class from being instantiated without using a
- <classname>RefPtr</classname>. For instance:
+ <classname>RefPtr</classname>. For instance:</para>
<programlisting>
class TextMark : public Glib::Object
{
@@ -9493,7 +9435,6 @@ protected:
public:
_WRAP_CREATE(const Glib::ustring& name, bool left_gravity = true)
</programlisting>
-</para>
<sect3 id="gmmproc-ctor-default">
<title>_CTOR_DEFAULT</title>
@@ -9532,14 +9473,13 @@ public:
<function>_CONSTRUCT()</function> macro may be used in the
.ccg file to save some work. The <function>_CONSTRUCT</function> macro takes
a series of property names and values. For instance, from
- <filename>button.ccg</filename>:
+ <filename>button.ccg</filename>:</para>
<programlisting>
Button::Button(const Glib::ustring& label, bool mnemonic)
:
_CONSTRUCT("label", label.c_str(), "use_underline", gboolean(mnemonic))
{}
</programlisting>
-</para>
</sect3>
</sect2>
@@ -9589,7 +9529,7 @@ wrapped C object and the constructor that takes construct_params in
assignment operator in <function>_CLASS_GOBJECT</function> and
<function>_CLASS_GTKOBJECT</function>.
</para>
-<para>For example:
+<para>For example:</para>
<programlisting>
class Derived : public Glib::Object
{
@@ -9603,7 +9543,6 @@ public:
// ...
};
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-custom-wrap-new">
@@ -9638,11 +9577,10 @@ function in <function>_CLASS_GOBJECT</function>, <function>_CLASS_BOXEDTYPE</fun
<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>For instance, from <filename>entry.hg</filename>:</para>
<programlisting>
_WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
</programlisting>
-</para>
<para>The C function (e.g. <function>gtk_entry_set_text</function>) is described
more fully in the .defs file, and the <filename>convert*.m4</filename> files
contain the necessary conversion from the C++ parameter type to the C
@@ -9774,11 +9712,10 @@ _WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
when you must hand-code the method, but you want to use the documentation
that would be generated if the method was generated.</para>
<para><function>_WRAP_METHOD_DOCS_ONLY(C function name)</function></para>
-<para>For instance, from <filename>container.hg</filename>:
+<para>For instance, from <filename>container.hg</filename>:</para>
<programlisting>
_WRAP_METHOD_DOCS_ONLY(gtk_container_add)
</programlisting>
-</para>
<para>There are some optional extra arguments:
<variablelist>
<varlistentry>
@@ -9827,12 +9764,11 @@ _WRAP_METHOD_DOCS_ONLY(gtk_container_add)
_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>
-<para>For instance, from <filename>flowbox.hg</filename>:
+<para>For instance, from <filename>flowbox.hg</filename>:</para>
<programlisting>
_IGNORE(gtk_flow_box_set_filter_func, gtk_flow_box_set_sort_func)
_IGNORE_SIGNAL(activate-cursor-child, toggle-cursor-child, move-cursor)
</programlisting>
-</para>
</sect3>
<sect3 id="gmmproc-wrap-signal">
@@ -9844,11 +9780,10 @@ _IGNORE_SIGNAL(activate-cursor-child, toggle-cursor-child, move-cursor)
types and the .m4 convert files to discover appropriate type
conversions.</para>
<para><function>_WRAP_SIGNAL( C++ signal handler signature, C signal name)</function></para>
-<para>For instance, from <filename>button.hg</filename>:
+<para>For instance, from <filename>button.hg</filename>:</para>
<programlisting>
_WRAP_SIGNAL(void clicked(),"clicked")
</programlisting>
-</para>
<para>Signals usually have function pointers in the GTK struct, with a
corresponding enum value and a <function>g_signal_new()</function> in the
.c file.</para>
@@ -9949,11 +9884,10 @@ _WRAP_SIGNAL(void clicked(),"clicked")
uses the .defs file to discover the C type and the .m4 convert files to
discover appropriate type conversions.</para>
<para><function>_WRAP_PROPERTY(C property name, C++ type)</function></para>
-<para>For instance, from <filename>button.hg</filename>:
+<para>For instance, from <filename>button.hg</filename>:</para>
<programlisting>
_WRAP_PROPERTY("label", Glib::ustring)
</programlisting>
-</para>
<para>There are some optional extra arguments:
<variablelist>
<varlistentry>
@@ -9978,11 +9912,10 @@ _WRAP_PROPERTY("label", Glib::ustring)
<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>For instance, from <filename>widget.hg</filename>:</para>
<programlisting>
_WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)
</programlisting>
-</para>
<para>The C function (e.g. <function>get_request_mode</function>) is described
more fully in the <filename>*_vfuncs.defs</filename> file, and the
<filename>convert*.m4</filename> files contain the necessary conversion from
@@ -10118,11 +10051,10 @@ _WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)
<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>For instance, from <filename>grid.hg</filename>:</para>
<programlisting>
_IMPLEMENTS_INTERFACE(Orientable)
</programlisting>
-</para>
<para>There is one optional extra argument:
<variablelist>
<varlistentry>
@@ -10139,11 +10071,10 @@ _IMPLEMENTS_INTERFACE(Orientable)
<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>For instance, from <filename>enums.hg</filename>:</para>
<programlisting>
_WRAP_ENUM(WindowType, GtkWindowType)
</programlisting>
-</para>
<para>There are some optional extra arguments:
<variablelist>
<varlistentry>
@@ -10157,11 +10088,10 @@ _WRAP_ENUM(WindowType, GtkWindowType)
<para>If you specify <literal>NO_GTYPE</literal>, don't use that enum as the
type in _WRAP_PROPERTY. It would cause a runtime error, when the generated
<methodname>property_*()</methodname> method is called.</para>
- <para>For example, from <filename>icontheme.hg</filename>:
+ <para>For example, from <filename>icontheme.hg</filename>:</para>
<programlisting>
_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)
</programlisting>
- </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -10170,11 +10100,10 @@ _WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)
<para>Specifies the name of the <function>*_get_type()</function> function
for the C enum. Use this parameter if <command>gmmproc</command> can't
deduce the correct function name from the name of the C enum type.</para>
- <para>For example, from <filename>dbusproxy.hg</filename> in glibmm:
+ <para>For example, from <filename>dbusproxy.hg</filename> in glibmm:</para>
<programlisting>
_WRAP_ENUM(ProxyFlags, GDBusProxyFlags, gtype_func g_dbus_proxy_flags_get_type)
</programlisting>
- </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -10183,11 +10112,10 @@ _WRAP_ENUM(ProxyFlags, GDBusProxyFlags, gtype_func g_dbus_proxy_flags_get_type)
<para>"Convertible to int." Generates a plain enum (not an enum class)
within a class. Such an enum is scoped like an enum class, but unlike an
enum class, it can be implicitly converted to <type>int</type>.</para>
- <para>For example, from <filename>dialog.hg</filename>:
+ <para>For example, from <filename>dialog.hg</filename>:</para>
<programlisting>
_WRAP_ENUM(ResponseType, GtkResponseType, CONV_TO_INT)
</programlisting>
- </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -10195,11 +10123,10 @@ _WRAP_ENUM(ResponseType, GtkResponseType, CONV_TO_INT)
<listitem>
<para>Substitutes (part of) the name of one or more enum constants.
You can add any number of substitutions.</para>
- <para>For example, from <filename>iochannel.hg</filename> in glibmm:
+ <para>For example, from <filename>iochannel.hg</filename> in glibmm:</para>
<programlisting>
_WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
</programlisting>
- </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -10240,11 +10167,10 @@ a <type>Code</type> enum and a <methodname>code()</methodname> method. You must
of the corresponding C enum, and the prefix for the C enum values.</para>
<para>This exception can then be thrown by methods which are generated from
_WRAP_METHOD() with the errthrow option.</para>
-<para>For instance, from <filename>pixbuf.hg</filename>:
+<para>For instance, from <filename>pixbuf.hg</filename>:</para>
<programlisting>
_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)
</programlisting>
-</para>
<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>
@@ -10260,8 +10186,8 @@ CONV_TO_INT is ignored because all exception class enums are plain enums within
<para><function>_MEMBER_SET(C++ name, C name, C++ type, C type)</function></para>
<para>
For example, in <filename>rectangle.hg</filename>:
- <programlisting>_MEMBER_GET(x, x, int, int)</programlisting>
</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>
@@ -10273,11 +10199,11 @@ CONV_TO_INT is ignored because all exception class enums are plain enums within
<para><function>_MEMBER_GET_PTR(C++ name, C name, C++ type, C type)</function></para>
<para><function>_MEMBER_SET_PTR(C++ name, C name, C++ type, C type)</function></para>
<para>For example, for <classname>Pango::Analysis</classname> in <filename>item.hg</filename>:
+ </para>
<programlisting>
// _MEMBER_GET_PTR(engine_lang, lang_engine, EngineLang*, PangoEngineLang*)
// It's just a comment. It's difficult to find a real-world example.
</programlisting>
- </para>
</sect3>
<sect3 id="gmmproc-member-get-set-gobject">
<title>_MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT</title>
@@ -10288,11 +10214,10 @@ CONV_TO_INT is ignored because all exception class enums are plain enums within
</para>
<para><function>_MEMBER_GET_GOBJECT(C++ name, C name, C++ type, C type)</function></para>
<para><function>_MEMBER_SET_GOBJECT(C++ name, C name, C++ type, C type)</function></para>
- <para>For example, in Pangomm, <filename>layoutline.hg</filename>:
+ <para>For example, in Pangomm, <filename>layoutline.hg</filename>:</para>
<programlisting>
_MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
</programlisting>
- </para>
</sect3>
</sect2>
@@ -10516,7 +10441,7 @@ _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle',`$3 = Glib::wrap(&($4))
hand-coded <filename>init.h</filename> and <filename>init.cc</filename>
files. This function should initialize your dependencies (such as the C
function, and >kmm;) and call your generated
- <function>wrap_init()</function> function. For instance:
+ <function>wrap_init()</function> function. For instance:</para>
<programlisting>
void init()
{
@@ -10524,7 +10449,6 @@ void init()
wrap_init(); //Tells the Glib::wrap() table about the libsomethingmm classes.
}
</programlisting>
-</para>
<para>The implementation of the <function>wrap_init()</function> method in
<filename>wrap_init.cc</filename> is generated by
<filename>generate_wrap_init.pl</filename>, but the declaration in
@@ -10538,7 +10462,7 @@ void init()
<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">
<title>Unable to predeclare structs</title>
-<para>By convention, structs are declared in glib/GTK-style headers like so:
+<para>By convention, structs are declared in glib/GTK-style headers like so:</para>
<programlisting>
typedef struct _ExampleWidget ExampleWidget;
@@ -10547,7 +10471,6 @@ struct _ExampleWidget
...
};
</programlisting>
-</para>
<para>The extra typedef allows the struct to be used in a header without including
its full definition, simply by predeclaring it, by repeating that typedef.
This means that you don't have to include the C library's header in your C++ header,
@@ -10576,14 +10499,13 @@ example-widget.h:60: error: '_ExampleWidget ExampleWidget' redeclared as differe
more than call <function>g_object_new()</function> and return the result.
The input parameters are supplied to <function>g_object_new()</function>
along with the names of the properties for which they are values. For
- instance,
+ instance,</para>
<programlisting>
GtkWidget* example_widget_new(int something, const char* thing)
{
return g_object_new (EXAMPLE_TYPE_WIDGET, "something", something, "thing", thing, NULL);
}
</programlisting>
-</para>
<para>This allows language bindings to implement their own equivalents (such as
C++ constructors), without using the <function>*_new()</function> function.
This is often necessary so that they can actually instantiate a derived
@@ -10595,7 +10517,7 @@ GtkWidget* example_widget_new(int something, const char* thing)
that is available to us.</para>
<para>Another workaround is to add a <function>*_construct()</function> function
that the C++ constructor can call after instantiating its own type. For
- instance,
+ instance,</para>
<programlisting>
GtkWidget* example_widget_new(int something, const char* thing)
{
@@ -10611,7 +10533,6 @@ void example_widget_construct(ExampleWidget* widget, int something, const char*
do_something(something);
}
</programlisting>
-</para>
<para>Adding properties, and ensuring that they interact properly with each
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
@@ -10634,10 +10555,9 @@ void example_widget_construct(ExampleWidget* widget, int something, const char*
doxygen comments. <command>gmmproc</command> will even try to transform the
documentation to make it more appropriate for a C++ API.</para>
<para>
-For instance,
+For instance,</para>
<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
want to provide hand-written text for a particular method. You can do this
by copying the XML node for the function from your
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
