[gtkmm-documentation] Update appendixes A-G for gtkmm-4.0
- From: Kjell Ahlstedt <kjellahl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtkmm-documentation] Update appendixes A-G for gtkmm-4.0
- Date: Mon, 27 Feb 2017 15:20:57 +0000 (UTC)
commit 25ecb16220a7baee3e8d73da0cb1c355d15eb3a7
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date: Mon Feb 27 16:17:12 2017 +0100
Update appendixes A-G for gtkmm-4.0
A. The RefPtr smartpointer
B. Signals
C. Creating your own signals
D. Comparison with other signalling systems (no change)
E. gtkmm and Win32
F. Working with gtkmm's Source Code
G. Wrapping C Libraries with gmmproc
docs/tutorial/C/index-in.docbook | 285 ++++++++++++++++++--------------------
1 files changed, 138 insertions(+), 147 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 4f97176..08f3a4e 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -8216,7 +8216,7 @@ 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
-<classname>std::auto_ptr<></classname>, <classname>std::unique_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
@@ -8246,7 +8246,7 @@ standard containers, such as <classname>std::vector</classname> or
<classname>std::list</classname>.</para>
<para>
<programlisting>
-std::list< Glib::RefPtr<Gdk::Pixbuf> > listPixbufs;
+std::list<Glib::RefPtr<Gdk::Pixbuf>> listPixbufs;
Glib::RefPtr<Gdk::Pixbuf> refPixbuf = Gdk::Pixbuf::create_from_file(filename);
listPixbufs.push_back(refPixbuf);
</programlisting>
@@ -8509,19 +8509,16 @@ might see in the >kmm; headers:
<para>
<programlisting>
-Glib::SignalProxy1<bool, Gtk::DirectionType> signal_focus()
+Glib::SignalProxy<bool(Gtk::DirectionType)> signal_focus()
</programlisting>
</para>
<para>
-Other than the signal's name (<literal>focus</literal>), two things are
-important to note here: the number following the word
-<classname>SignalProxy</classname> at the beginning (1, in this case), and the
-types in the list (<type>bool</type> and <type>Gtk::DirectionType</type>). The
-number indicates how many arguments the signal handler should have; the first
-type, <type>bool</type>, is the type that the signal handler should return; and
-the next type, <type>Gtk::DirectionType</type>, is the type of this signal's
-first, and only, argument. By looking at the reference documentation, you can
+Other than the signal's name (<literal>focus</literal>), the template arguments are
+important to note here. The first argument, <type>bool</type>, is the type that
+the signal handler should return; and the type within parentheses,
+<type>Gtk::DirectionType</type>, is the type of this signal's first, and only,
+argument. By looking at the reference documentation, you can
see the names of the arguments too.
</para>
@@ -8532,21 +8529,20 @@ with three (taken from <filename><gtkmm/textbuffer.h></filename>):
<para>
<programlisting>
-Glib::SignalProxy3<void, const TextBuffer::iterator&, const Glib::ustrin&, int>
signal_insert();
+Glib::SignalProxy<void(TextBuffer::iterator&, const Glib::ustrin&, int)> signal_insert();
</programlisting>
</para>
<para>
-It follows the same form. The number 3 at the end of the type's name indicates
-that our signal handler will need three arguments. The first type in the type
-list is <type>void</type>, so that should be our signal handler's return type.
+It follows the same form. The first type is <type>void</type>, so that should be
+our signal handler's return type.
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(const TextBuffer::iterator& pos, const Glib::ustring& text, int bytes)
+void on_insert(TextBuffer::iterator& pos, const Glib::ustring& text, int bytes)
</programlisting>
</para>
</sect1>
@@ -8560,17 +8556,14 @@ Let's take another look at a Signal's <literal>connect</literal> method:
<para>
<programlisting>
-sigc::signal<void,int>::iterator signal<void,int>::connect( const
sigc::slot<void,int>& );
+sigc::connection signal<void(int)>::connect(const sigc::slot<void(int)>&);
</programlisting>
</para>
<para>
-Notice that the return value is of type
-<classname>sigc::signal<void,int>::iterator</classname>. This can be
-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>.
+The returned <classname>sigc::connection</classname> can be used to control the
+connection. By keeping a connection object you can disconnect its associated signal
+handler using the <methodname>sigc::connection::disconnect()</methodname> method.
</para>
</sect1>
@@ -8612,15 +8605,15 @@ Let's look at an example of overriding:
class OverriddenButton : public Gtk::Button
{
protected:
- virtual void on_clicked();
+ void on_clicked() override;
}
void OverriddenButton::on_clicked()
{
- std::cout << "Hello World" << std::endl;
+ std::cout << "Hello World" << std::endl;
- // call the base class's version of the method:
- Gtk::Button::on_clicked();
+ // call the base class's version of the method:
+ Gtk::Button::on_clicked();
}
</programlisting>
</para>
@@ -8641,7 +8634,7 @@ You don't always need to call the parent's method; there are times
when you might not want to. Note that we called the parent method
<emphasis>after</emphasis> writing "Hello World", but we could have called it before.
In this simple example, it hardly matters much, but there are times
-when it will. With signals, it's not quite so easy to change details
+when it will. With connected signal handlers, it's not quite so easy to change details
like this, and you can do something here which you can't do at all
with connected signal handlers: you can call the parent method in the <emphasis>middle</emphasis> of
your custom code.
@@ -8658,14 +8651,14 @@ 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.
<programlisting>
-m_button1.signal_clicked().connect( sigc::bind<Glib::ustring>( sigc::mem_fun(*this,
&HelloWorld::on_button_clicked), "button 1") );
+m_button1.signal_clicked().connect(sigc::bind(sigc::mem_fun(*this, &HelloWorld::on_button_clicked),
"button 1"));
</programlisting>
This says that we want the signal to send an extra
<classname>Glib::ustring</classname> argument to the signal handler, and that
the value of that argument should be "button 1". Of course we will need to add
that extra argument to the declaration of our signal handler:
<programlisting>
-virtual void on_button_clicked(Glib::ustring data);
+void on_button_clicked(const Glib::ustring& data);
</programlisting>
Of course, a normal "clicked" signal handler would have no arguments.
</para>
@@ -8786,8 +8779,7 @@ bool throwSomething()
int main(int argc, char** argv)
{
throwSomething();
- Glib::RefPtr<Gtk::Application> app =
- Gtk::Application::create(argc, argv, "org.gtkmm.without_signal");
+ auto app = Gtk::Application::create("org.gtkmm.without_signal");
return app->run();
}
</programlisting>
@@ -8824,8 +8816,7 @@ bool throwSomething()
int main(int argc, char** argv)
{
Glib::signal_timeout().connect(sigc::ptr_fun(throwSomething), 500);
- Glib::RefPtr<Gtk::Application> app =
- Gtk::Application::create(argc, argv, "org.gtkmm.with_signal");
+ auto app = Gtk::Application::create("org.gtkmm.with_signal");
app->hold();
return app->run();
}
@@ -8915,7 +8906,7 @@ 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:
<programlisting>
-sigc::signal<void, bool, int> signal_something;
+sigc::signal<void(bool, int)> signal_something;
</programlisting>
</para>
<para>
@@ -8927,7 +8918,7 @@ class Server
{
public:
//signal accessor:
- typedef sigc::signal<void, bool, int> type_signal_something;
+ using type_signal_something = sigc::signal<void(bool, int)>;
type_signal_something signal_something();
protected:
@@ -8963,8 +8954,6 @@ This is a full working example that defines and uses custom signals.
</appendix>
-
-
<appendix id="sec-signals-comparison">
<title>Comparison with other signalling systems</title>
<para>
@@ -9014,22 +9003,19 @@ practical - and sensible - to subclass a button for that purpose.
</para>
<para>
>kmm; currently works with the <ulink
- url="http://mingw.org/";>MingW/GCC3.4 compiler</ulink> and Microsoft
- Visual C++ 2005 or later (including the freely available express
+ url="http://mingw.org/";>MingW/GCC compiler</ulink> with a compiler version
+ that supports C++14, such as gcc 6.2. It also works with Microsoft
+ Visual C++ 2017 or later (including the freely available express
editions) on the Windows platform. There is an
- <ulink url="ftp://ftp.gnome.org/pub/GNOME/binaries/win32/gtkmm";>
- installer</ulink> available for gtkmm on Microsoft Windows. Refer to
- <ulink url="https://wiki.gnome.org/Projects/gtkmm/MSWindows/";>
- https://wiki.gnome.org/Projects/gtkmm/MSWindows</ulink> for instructions how to
- use it.
+ <ulink url="ftp://ftp.gnome.org/pub/GNOME/binaries/win32/gtkmm";>installer</ulink>
+ available for >kmm; on Microsoft Windows, but as of this writing
+ (February 2017) it has not been updated for a long time.
</para>
- <sect1 id="sec-building-on-win32">
- <title>Building >kmm; on Win32</title>
- <para>Please see <ulink url="https://wiki.gnome.org/Projects/gtkmm/MSWindows/BuildingGtkmm";>
- https://wiki.gnome.org/Projects/gtkmm/MSWindows/BuildingGtkmm</ulink> for instructions on how to build
gtkmm on Windows.
+ <para>
+ Refer to <ulink url="https://wiki.gnome.org/Projects/gtkmm/MSWindows/";>
+ https://wiki.gnome.org/Projects/gtkmm/MSWindows</ulink> for instructions on how to
+ build >kmm; on Windows.
</para>
-
- </sect1>
</appendix>
<appendix id="chapter-working-with-source">
@@ -9075,14 +9061,16 @@ practical - and sensible - to subclass a button for that purpose.
should copy the sample <application>jhbuild</application> configuration
file into your home directory by executing the following command from the
<application>jhbuild</application> directory:
- <screen>$ cp examples/sample.jhbuildrc ~/.jhbuildrc</screen>
+ <screen>$ cp examples/sample.jhbuildrc ~/.config/jhbuildrc</screen>
</para>
<para>
The >kmm; module is defined in the
- <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.12'</programlisting>
+ <filename>gnome-suites-core-deps-x.y.modules</filename> moduleset, but if
+ you are interested in the latest version, it's easier to let <application>jhbuild</application>
+ read from <filename>gnome-world.modules</filename>. It always includes the
+ latest version of other <filename>.modules</filename> files. So edit your
+ <filename>jhbuildrc</filename> file and set your moduleset setting like so:
+ <programlisting>moduleset = 'gnome-world'</programlisting>
</para>
<para>
After setting the correct moduleset, you need to tell
@@ -9204,8 +9192,8 @@ $ jhbuild sanitycheck</screen>
of tools such as <command>gmmproc</command> and
<filename>generate_wrap_init.pl</filename>. In theory you could write your
own build files to use these appropriately, but a much better option is to
- make use of the build infrastructure provided by the mm-common module. To
- get started, it helps a lot to pick an existing binding module as an example
+ make use of the build infrastructure provided by the <application>mm-common</application>
+ module. To 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
libsomething. It provides a <classname>GObject</classname>-based API with
@@ -9217,7 +9205,7 @@ $ jhbuild sanitycheck</screen>
<para>Typically our wrapper library would be called libsomethingmm. We can start by
copying the <ulink url="http://git.gnome.org/browse/mm-common/tree/skeletonmm";>skeleton
- source tree</ulink> from the mm-common module.
+ source tree</ulink> from the <application>mm-common</application> module.
<programlisting>
$ git clone git://git.gnome.org/mm-common
$ cp -a mm-common/skeletonmm libsomethingmm
@@ -9427,7 +9415,7 @@ described in the <link linkend="sec-wrapping-documentation">Documentation</link>
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,
<programlisting>
-$ ./h2def.py /usr/include/gtk-3.0/gtk/*.h > gtk_methods.defs
+$ ./h2def.py /usr/include/gtk-4.0/gtk/*.h > gtk_methods.defs
</programlisting>
</para>
</sect2>
@@ -9438,7 +9426,7 @@ $ ./h2def.py /usr/include/gtk-3.0/gtk/*.h > gtk_methods.defs
values. It is generated by the <filename>enum.pl</filename> script which you can
find in glibmm's <filename>tools</filename> directory. For instance,
<programlisting>
-$ ./enum.pl /usr/include/gtk-3.0/gtk/*.h > gtk_enums.defs
+$ ./enum.pl /usr/include/gtk-4.0/gtk/*.h > gtk_enums.defs
</programlisting>
</para>
</sect2>
@@ -9507,7 +9495,7 @@ int main(int, char**)
<programlisting>
#include <gtkmm/bin.h>
-#include <gtkmm/activatable.h>
+#include <gtkmm/actionable.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/bin_p.h)
@@ -9516,10 +9504,10 @@ namespace Gtk
class Button
: public Bin,
- public Activatable // Activatable is deprecated. Will be replaced at ABI break.
+ public Actionable
{
_CLASS_GTKOBJECT(Button,GtkButton,GTK_BUTTON,Gtk::Bin,GtkBin)
- _IMPLEMENTS_INTERFACE(Activatable)
+ _IMPLEMENTS_INTERFACE(Actionable)
public:
_CTOR_DEFAULT
@@ -9547,7 +9535,7 @@ public:
</varlistentry>
<varlistentry>
<term><function>_PINCLUDE()</function></term>
- <listitem><para>Tells <command>gmmproc</command> to include a header in the generated
private/button_p.h file.</para></listitem>
+ <listitem><para>Tells <command>gmmproc</command> to include a header in the generated
<filename>private/button_p.h</filename> file.</para></listitem>
</varlistentry>
<varlistentry>
<term><function>_CLASS_GTKOBJECT()</function></term>
@@ -9559,13 +9547,12 @@ public:
</varlistentry>
<varlistentry>
<term><function>_CTOR_DEFAULT</function></term>
- <listitem><para>Add a default constructor.</para></listitem>
+ <listitem><para>Adds a default constructor.</para></listitem>
</varlistentry>
<varlistentry>
<term><function>_WRAP_METHOD()</function>,
- <function>_WRAP_SIGNAL()</function>,
- <function>_WRAP_PROPERTY()</function>, and
- <function>_WRAP_CHILD_PROPERTY()</function></term>
+ <function>_WRAP_SIGNAL()</function>, and
+ <function>_WRAP_PROPERTY()</function></term>
<listitem><para>Add methods to wrap parts of the C API.</para></listitem>
</varlistentry>
</variablelist>
@@ -9575,7 +9562,7 @@ public:
automatically when using the above build structure:
<programlisting>
$ cd gtk/src
-$ /usr/lib/glibmm-2.4/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm
+$ /usr/lib/glibmm-2.52/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm
</programlisting>
</para>
<para>Notice that we provided <command>gmmproc</command> with the path to the
@@ -9591,22 +9578,23 @@ $ /usr/lib/glibmm-2.4/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkm
<sect2 id="gmmproc-m4-conversions">
<title>m4 Conversions</title>
<para>The macros that you use in the .hg and .ccg files often need to know how
-to convert a C++ type to a C type, or vice-versa. gmmproc takes this information
-from an .m4 file in your <literal>tools/m4/</literal> directory. 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 gmmproc how to convert a GtkTreeView pointer to a Gtk::TreeView pointer:
+to convert a C++ type to a C type, or vice-versa. <command>gmmproc</command> takes this information
+from an .m4 file in your <literal>tools/m4/</literal> or <literal>codegen/m4/</literal> directory.
+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:
<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 gmmproc.
+conversion is used by <command>gmmproc</command>.
</para>
<para>
-Some extra macros make this easier and consistent. Look in gtkmm's .m4 files
+Some extra macros make this easier and consistent. Look in >kmm;'s .m4 files
for examples. For instance:
<programlisting>
_CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P)
@@ -9623,8 +9611,8 @@ _CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REF
function in what is called an output parameter. In this case, the C++ method
returns <type>void</type> but an output parameter in which to store the value
of the C function is included in the argument list of the C++ method.
- gmmproc allows such functionality, but appropriate initialization macros must
- be included to tell gmmproc how to initialize the C++ parameter from the
+ <command>gmmproc</command> allows such functionality, but appropriate initialization macros must
+ be included to tell <command>gmmproc</command> how to initialize the C++ parameter from the
return of the C function.
</para>
<para>
@@ -9641,7 +9629,7 @@ _INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
<para>
<literal>$3</literal> will be replaced by the output parameter name of the
C++ method and <literal>$4</literal> will be replaced by the return of the C
- function when this initialization is used by gmmproc. For convenience,
+ function when this initialization is used by <command>gmmproc</command>. For convenience,
<literal>$1</literal> will also be replaced by the C++ type without the
ampersand (&) and <literal>$2</literal> will be replaced by the C type.
</para>
@@ -9682,8 +9670,15 @@ _CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject
_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)
</programlisting>
</para>
-<para>You will typically use this macro when the class already derives from Gtk::Object. For instance, you
will use it when wrapping a GTK+ Widget, because Gtk::Widget derives from Gtk::Object.</para>
-<para>You might also derive non-widget classes from Gtk::Object so they can be used without
<classname>Glib::RefPtr</classname>. For instance, they could then be instantiated with
<function>Gtk::manage()</function> or on the stack as a member variable. This is convenient, but you should
use this only when you are sure that true reference-counting is not needed. We consider it useful for
widgets.</para>
+<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
+ <classname>Gtk::Object</classname>.</para>
+<para>You might also derive non-widget classes from <classname>Gtk::Object</classname>
+ so they can be used without <classname>Glib::RefPtr</classname>. For instance,
+ they could then be instantiated with <function>Gtk::manage()</function> or on the stack
+ as a member variable. This is convenient, but you should use this only when you are sure
+ that true reference-counting is not needed. We consider it useful for widgets.</para>
</sect3>
<sect3 id="gmmproc-class-boxedtype">
@@ -9783,7 +9778,7 @@ _CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIfac
as is usually the case, so that it can supply the parameters directly to a
<function>g_object_new()</function> call. These constructors never actually
call the <function>*_new()</function> C functions,
- because gtkmm must actually instantiate derived GTypes, and the
+ because >kmm; must actually instantiate derived GTypes, and the
<function>*_new()</function> C functions are meant only as convenience
functions for C programmers.</para>
<para>When using <function>_CLASS_GOBJECT()</function>, the constructors should
@@ -9824,8 +9819,8 @@ public:
<varlistentry>
<term>errthrow</term>
<listitem>
- <para>This tells gmmproc that the C <function>*_new()</function> has
- a final GError** parameter which should be ignored.</para>
+ <para>This tells <command>gmmproc</command> that the C <function>*_new()</function> has
+ a final <type>GError**</type> parameter which should be ignored.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -10049,8 +10044,7 @@ _WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
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<Gdk::Pixbuf> ></code>.
+ For instance, <code>std::vector<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
@@ -10075,7 +10069,7 @@ _WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
<para><function>_WRAP_METHOD_DOCS_ONLY(C function name)</function></para>
<para>For instance, from <filename>container.hg</filename>:
<programlisting>
-_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)
+_WRAP_METHOD_DOCS_ONLY(gtk_container_add)
</programlisting>
</para>
<para>There are some optional extra arguments:
@@ -10147,7 +10141,8 @@ _WRAP_SIGNAL(void clicked(),"clicked")
method to allow easy overriding of the default signal handler.
Use this when adding a signal with a default signal handler
would break the ABI by increasing the size of the class's
- virtual function table.</para>
+ virtual function table, and when adding a signal without a public
+ C default handler.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -10397,7 +10392,7 @@ _WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)
<sect3 id="gmmproc-wrap-child-property">
<title>_WRAP_CHILD_PROPERTY</title>
-<para>This macro generates the C++ method to wrap a GtkContainer child property.
+<para>This macro generates the C++ method to wrap a <classname>GtkContainer</classname> child property.
(See <ulink url="https://developer.gnome.org/gtk3/stable/GtkContainer.html";>
GtkContainer</ulink> for more information about child properties).
Similarly to _WRAP_PROPERTY, you must specify the property name and the
@@ -10510,8 +10505,8 @@ _WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
<sect3 id="gmmproc-wrap-gerror">
<title>_WRAP_GERROR</title>
-<para>This macro generates a C++ exception class, derived from Glib::Error, with
-a Code enum and a code() method. You must specify the desired C++ name, the name
+<para>This macro generates a C++ exception class, derived from <classname>Glib::Error</classname>, with
+a <type>Code</type> enum and a <methodname>code()</methodname> method. You must specify the desired C++
name, the name
of the corresponding C enum, and the prefix for the C enum values.</para>
<para>This exception can then be thrown by methods which are generated from
_WRAP_METHOD() with the errthrow option.</para>
@@ -10586,28 +10581,28 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
in the C function, virtual function or signal. For example, say that the
following C function were being wrapped as a C++ method for the
<classname>Gtk::Widget</classname> class:
- <programlisting>
- void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device,
- GdkEventMask events);
- </programlisting>
+<programlisting>
+void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device,
+ GdkEventMask events);
+</programlisting>
However, changing the order of the C++ method's two parameters is
necessary. Something like the following would wrap the function as a C++
method with a different order for the two parameters:
- <programlisting>
- _WRAP_METHOD(void set_device_events(Gdk::EventMask events{events},
- const Glib::RefPtr<const Gdk::Device>& device{device}),
- gtk_widget_set_device_events)
- </programlisting>
+<programlisting>
+_WRAP_METHOD(void set_device_events(Gdk::EventMask events{events},
+ const Glib::RefPtr<const Gdk::Device>& device{device}),
+ gtk_widget_set_device_events)
+</programlisting>
The <literal>{c_param_name}</literal> following the method parameter
names tells <command>gmmproc</command> to map the C++ parameter to the
specified C parameter within the <literal>{}</literal>. Since the C++
parameter names correspond to the C ones, the above could be re-written
as:
- <programlisting>
- _WRAP_METHOD(void set_device_events(Gdk::EventMask events{.}, const
- Glib::RefPtr<const Gdk::Device>& device{.}),
- gtk_widget_set_device_events)
- </programlisting>
+<programlisting>
+_WRAP_METHOD(void set_device_events(Gdk::EventMask events{.},
+ const Glib::RefPtr<const Gdk::Device>& device{.}),
+ gtk_widget_set_device_events)
+</programlisting>
</para>
<warning>
<para>
@@ -10631,20 +10626,19 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
specified optional parameter. For example, say that the following
<function>*_new()</function> function were being wrapped as a constructor
in the <classname>Gtk::ToolButton</classname> class:
- <programlisting>
- GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar*
- label);
- </programlisting>
+<programlisting>
+GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar* label);
+</programlisting>
Also, say that the C API allowed NULL for the function's
<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
<literal>{?}</literal> to the parameter name like so:
- <programlisting>
- _WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring&
- label{?}), gtk_tool_button_new)
- </programlisting>
+<programlisting>
+_WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring& label{?}),
+ gtk_tool_button_new)
+</programlisting>
In this case, two constructors would be generated: One with the optional
parameter and one without it.
</para>
@@ -10661,30 +10655,28 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
<literal>{OUT}</literal> to the output parameter name. For example, if
<function>gtk_widget_get_request_mode()</function> is declared as the
following:
- <programlisting>
- GtkSizeRequestMode gtk_widget_get_request_mode(GtkWidget* widget);
- </programlisting>
+<programlisting>
+GtkSizeRequestMode gtk_widget_get_request_mode(GtkWidget* widget);
+</programlisting>
And having the C++ method set an output parameter is desired instead of
returning a <type>SizeRequestMode</type>, something like the following
could be used:
- <programlisting>
- _WRAP_METHOD(void get_request_mode(SizeRequestMode& mode{OUT})
- const, gtk_widget_get_request_mode)
- </programlisting>
+<programlisting>
+_WRAP_METHOD(void get_request_mode(SizeRequestMode& mode{OUT}) const,
+ gtk_widget_get_request_mode)
+</programlisting>
The <literal>{OUT}</literal> appended to the name of the
<parameter>mode</parameter> output parameter tells
<command>gmmproc</command> to place the return of the C function in that
output parameter. In this case, however, a necessary initialization
macro like the following would also have to be specified:
- <programlisting>
- _INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 =
- (SizeRequestMode)($4)')
- </programlisting>
+<programlisting>
+_INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 = (SizeRequestMode)($4)')
+</programlisting>
Which could also be written as:
- <programlisting>
- _INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 =
- ($1)($4)')
- </programlisting>
+<programlisting>
+_INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 = ($1)($4)')
+</programlisting>
</para>
<para>
<function>_WRAP_METHOD()</function> also supports setting C++ output
@@ -10692,18 +10684,18 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
any. Suppose, for example, that we want to wrap the following C function
that returns a value in its C output parameter
<parameter>rect</parameter>:
- <programlisting>
- gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
- GtkTreePath* path, GtkCellRenderer* cell, GdkRectangle* rect);
- </programlisting>
+<programlisting>
+gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
+ GtkTreePath* path, GtkCellRenderer* cell, GdkRectangle* rect);
+</programlisting>
To have <command>gmmproc</command> place the value returned in the C++
<parameter>rect</parameter> output parameter, something like the
- following <function>_WRAP_METHOD()</function> directive could be used:
- <programlisting>
- _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path, const
- CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
- gtk_icon_view_get_cell_rect)
- </programlisting>
+ following <function>_WRAP_METHOD()</function> macro could be used:
+<programlisting>
+_WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path,
+ const CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
+ gtk_icon_view_get_cell_rect)
+</programlisting>
The <literal>{>>}</literal> following the <parameter>rect</parameter>
parameter name indicates that the C++ output parameter should be set from
the value returned in the C parameter from the C function.
@@ -10714,10 +10706,9 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
<function>_INITIALIZATION()</function> describing how to set a
<classname>Gdk::Rectangle&</classname> from a
<classname>GdkRectangle*</classname> such as the following:
- <programlisting>
- _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle', `$3 =
- Glib::wrap(&($4))')
- </programlisting>
+<programlisting>
+_INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle',`$3 = Glib::wrap(&($4))')
+</programlisting>
</para>
</sect3>
@@ -10734,7 +10725,7 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
</para>
<para>
The default conversion in <function>_WRAP_METHOD()</function> and similar
- directives is
+ macros is
<itemizedlist>
<listitem><para>for mandatory parameters (with or without default values):
empty string to empty string,</para></listitem>
@@ -10779,7 +10770,7 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
generated by <command>gmmproc</command> from <filename>.hg</filename> and
<filename>.ccg</filename> files. You can simply place these in your
<filename>libsomething/libsomethingmm</filename> directory and mention them
- in the <filename>Makefile.am</filename> in the
+ in the <filename>filelist.am</filename> in the
<varname>files_extra_h</varname> and <varname>files_extra_cc</varname>
variables.</para>
</sect1>
@@ -10925,9 +10916,9 @@ For instance,
<sect2 id="wrapping-documentation-build-structure">
<title>Documentation build structure</title>
-<para>If you copied the skeleton source tree in mm-common and substituted the
+<para>If you copied the skeleton source tree in <application>mm-common</application> and substituted the
placeholder text, then you will already have suitable <filename>Makefile.am</filename>
- and <filename>Doxyfile.in</filename> files. With the mm-common build setup, the list
+ and <filename>Doxyfile.in</filename> files. With the <application>mm-common</application> build setup, the
list
of Doxygen input files is not defined in the Doxygen configuration file, but passed
along from <command>make</command> to the standard input of <command>doxygen</command>.
The input file list is defined by the <varname>doc_input</varname> variable in the
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
