<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 31. Building applications</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Programming with gtkmm 3">
<link rel="up" href="index.html" title="Programming with gtkmm 3">
<link rel="prev" href="sec-using-a-gtkmm-widget.html" title="Using a gtkmm widget">
<link rel="next" href="sec-buildapp-populating-window.html" title="Populating the window">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 31. Building applications</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-using-a-gtkmm-widget.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="sec-buildapp-populating-window.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="chapter-building-applications"></a>Chapter 31. Building applications</h1></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<ul class="toc">
<li><span class="sect1"><a href="chapter-building-applications.html#sec-buildapp-trivial-app">A trivial application</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-populating-window.html">Populating the window</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-opening-files.html">Opening files</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-app-menu.html">An application menu</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-pref-dialog.html">A preference dialog</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-search-bar.html">Adding a search bar</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-side-bar.html">Adding a side bar</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-properties.html">Properties</a></span></li>
<li><span class="sect1"><a href="sec-buildapp-header-bar.html">Header bar</a></span></li>
</ul>
</div>
<p>
This chapter is similar to the "Building applications" chapter in the
<a class="ulink" href="https://developer.gnome.org/gtk3/stable/" target="_top">GTK+ 3 Reference Manual</a>.
The same application is built, but <span class="application">gtkmm</span> is used instead of <span class="application">GTK+</span>.
</p>
<p>
An application consists of a number of files:
</p>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term">The binary file</span></dt>
<dd><p>This gets installed in <code class="filename">/usr/bin</code>.</p></dd>
<dt><span class="term">A desktop file</span></dt>
<dd><p>The desktop file provides important information about the application
to the desktop shell, such as its name, icon, D-Bus name, commandline to launch it,
etc. It is installed in <code class="filename">/usr/share/applications</code>.</p></dd>
<dt><span class="term">An icon</span></dt>
<dd><p>The icon gets installed in <code class="filename">/usr/share/icons/hicolor/48x48/apps</code>,
where it will be found regardless of the current theme.</p></dd>
<dt><span class="term">A settings schema</span></dt>
<dd><p>If the application uses <code class="classname">Gio::Settings</code>,
it will install its schema in <code class="filename">/usr/share/glib-2.0/schemas</code>,
so that tools like dconf-editor can find it.</p></dd>
<dt><span class="term">Other resources</span></dt>
<dd><p>Other files, such as <code class="classname">Gtk::Builder</code> ui files,
are best loaded from resources stored in the application binary itself. This
eliminates the need for most of the files that would traditionally be installed
in an application-specific location in <code class="filename">/usr/share</code>.</p></dd>
</dl></div>
<p>
</p>
<p>
<span class="application">gtkmm</span> includes application support that is built on top of <code class="classname">Gio::Application</code>.
In this chapter we'll build a simple application by starting from scratch, adding more
and more pieces over time. Along the way, we'll learn about <code class="classname">Gtk::Application</code>,
<code class="classname">Gtk::Builder</code>, resources, application menus, settings,
<code class="classname">Gtk::HeaderBar</code>, <code class="classname">Gtk::Stack</code>,
<code class="classname">Gtk::SearchBar</code>, <code class="classname">Gtk::ListBox</code>, and more.
</p>
<p>
The full, buildable sources for these examples can be found in the
<code class="filename">examples/book/buildapp</code> directory of the
<span class="application">gtkmm-documentation</span> source distribution, or online in the
<a class="ulink" href="http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/buildapp" target="_top"><span class="application">gtkmm-documentation</span>
git repository</a>. You can build each example separately by using make with the
<code class="filename">Makefile.example</code> file. For more information, see the
<code class="filename">README</code> included in the <code class="filename">buildapp</code> directory.
</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-buildapp-trivial-app"></a>A trivial application</h2></div></div></div>
<p>
When using <code class="classname">Gtk::Application</code>, the <code class="function">main()</code> function
can be very simple. We just call <code class="methodname">Gio::Application::run()</code> on an
instance of our application class.
</p>
<p>
All the application logic is in the application class, which is a subclass of
<code class="classname">Gtk::Application</code>. Our example does not yet have any interesting
functionality. All it does is open a window when it is activated without arguments,
and open the files it is given, if it is started with arguments. (Or rather, our
application class tries to open the files, but our subclassed application window
does not yet do what it's told to do.)
</p>
<p>
To handle these two cases, we override <code class="methodname">signal_activate()</code>'s
default handler, which gets called when the application is launched without commandline
arguments, and <code class="methodname">signal_open()</code>'s default handler, which gets
called when the application is launched with commandline arguments.
</p>
<p><a class="ulink" href="http://developer.gnome.org/glibmm/2.58/classGio_1_1Application.html" target="_top">Gio::Application Reference</a></p>
<p>
Another important class that is part of the application support in <span class="application">gtkmm</span> is
<code class="classname">Gtk::ApplicationWindow</code>. It is typically subclassed as well.
Our subclass does not do anything yet, so we will just get an empty window.
</p>
<p>
As part of the initial setup of our application, we also create an icon and a desktop file.
Note that @bindir@ in the desktop file needs to be replaced with the actual path
to the binary before this desktop file can be used.
</p>
<p>
Here is what we've achieved so far:
</p>
<div class="figure">
<a name="figure-buildapp-trivial-app"></a><p class="title"><b>Figure 31.1. A trivial application</b></p>
<div class="figure-contents"><div class="screenshot"><div><img src="figures/buildapp_trivial_app.png" alt="A trivial application"></div></div></div>
</div>
<br class="figure-break"><p>
This does not look very impressive yet, but our application is already presenting itself
on the session bus, it has single-instance semantics, and it accepts files as commandline arguments.
</p>
<p><a class="ulink" href="http://git.gnome.org/browse/gtkmm-documentation/tree/examples/book/buildapp/step1?h=gtkmm-3-24" target="_top">Source Code</a></p>
<p>File: <code class="filename">exampleappwindow.h</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEAPPWINDOW_H_
#define GTKMM_EXAMPLEAPPWINDOW_H_
#include <gtkmm.h>
class ExampleAppWindow : public Gtk::ApplicationWindow
{
public:
ExampleAppWindow();
void open_file_view(const Glib::RefPtr<Gio::File>& file);
};
#endif /* GTKMM_EXAMPLEAPPWINDOW_H */
</pre>
<p>File: <code class="filename">exampleapplication.h</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#ifndef GTKMM_EXAMPLEAPPLICATION_H
#define GTKMM_EXAMPLEAPPLICATION_H
#include <gtkmm.h>
class ExampleAppWindow;
class ExampleApplication: public Gtk::Application
{
protected:
ExampleApplication();
public:
static Glib::RefPtr<ExampleApplication> create();
protected:
// Override default signal handlers:
void on_activate() override;
void on_open(const Gio::Application::type_vec_files& files,
const Glib::ustring& hint) override;
private:
ExampleAppWindow* create_appwindow();
void on_hide_window(Gtk::Window* window);
};
#endif /* GTKMM_EXAMPLEAPPLICATION_H */
</pre>
<p>File: <code class="filename">exampleapplication.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "exampleapplication.h"
#include "exampleappwindow.h"
ExampleApplication::ExampleApplication()
: Gtk::Application("org.gtkmm.examples.application", Gio::APPLICATION_HANDLES_OPEN)
{
}
Glib::RefPtr<ExampleApplication> ExampleApplication::create()
{
return Glib::RefPtr<ExampleApplication>(new ExampleApplication());
}
ExampleAppWindow* ExampleApplication::create_appwindow()
{
auto appwindow = new ExampleAppWindow();
// Make sure that the application runs for as long this window is still open.
add_window(*appwindow);
// Gtk::Application::add_window() connects a signal handler to the window's
// signal_hide(). That handler removes the window from the application.
// If it's the last window to be removed, the application stops running.
// Gtk::Window::set_application() does not connect a signal handler, but is
// otherwise equivalent to Gtk::Application::add_window().
// Delete the window when it is hidden.
appwindow->signal_hide().connect(sigc::bind<Gtk::Window*>(sigc::mem_fun(*this,
&ExampleApplication::on_hide_window), appwindow));
return appwindow;
}
void ExampleApplication::on_activate()
{
// The application has been started, so let's show a window.
auto appwindow = create_appwindow();
appwindow->present();
}
void ExampleApplication::on_open(const Gio::Application::type_vec_files& files,
const Glib::ustring& /* hint */)
{
// The application has been asked to open some files,
// so let's open a new view for each one.
ExampleAppWindow* appwindow = nullptr;
auto windows = get_windows();
if (windows.size() > 0)
appwindow = dynamic_cast<ExampleAppWindow*>(windows[0]);
if (!appwindow)
appwindow = create_appwindow();
for (const auto& file : files)
appwindow->open_file_view(file);
appwindow->present();
}
void ExampleApplication::on_hide_window(Gtk::Window* window)
{
delete window;
}
</pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "exampleapplication.h"
int main(int argc, char* argv[])
{
auto application = ExampleApplication::create();
// Start the application, showing the initial window,
// and opening extra views for any files that it is asked to open,
// for instance as a command-line parameter.
// run() will return when the last window has been closed.
return application->run(argc, argv);
}
</pre>
<p>File: <code class="filename">exampleappwindow.cc</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
#include "exampleappwindow.h"
ExampleAppWindow::ExampleAppWindow()
: Gtk::ApplicationWindow()
{
}
void ExampleAppWindow::open_file_view(const Glib::RefPtr<Gio::File>& /* file */)
{
}
</pre>
<p>File: <code class="filename">exampleapp.desktop</code> (For use with gtkmm 3, not gtkmm 2)
</p>
<pre class="programlisting">
[Desktop Entry]
Type=Application
Name=Gtkmm example
GenericName=Example
Comment=From the "Programming with gtkmm 3" tutorial
Icon=exampleapp
StartupNotify=true
Exec=@bindir@/exampleapp %U
Categories=GNOME;GTK;Utility
</pre>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="sec-using-a-gtkmm-widget.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="sec-buildapp-populating-window.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Using a <span class="application">gtkmm</span> widget </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> Populating the window</td>
</tr>
</table>
</div>
</body>
</html>
