1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="highlight.min.css">
<script src="highlight.min.js"></script><script>
hljs.configure({languages: ['cpp']});
hljs.highlightAll();
</script><title>Chapter 31. Building applications</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Programming with gtkmm 4">
<link rel="up" href="index.html" title="Programming with gtkmm 4">
<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="section"><a href="chapter-building-applications.html#sec-buildapp-trivial-app">A trivial application</a></span></li>
<li><span class="section"><a href="sec-buildapp-populating-window.html">Populating the window</a></span></li>
<li><span class="section"><a href="sec-buildapp-opening-files.html">Opening files</a></span></li>
<li><span class="section"><a href="sec-buildapp-menu.html">A menu</a></span></li>
<li><span class="section"><a href="sec-buildapp-pref-dialog.html">A preference dialog</a></span></li>
<li><span class="section"><a href="sec-buildapp-search-bar.html">Adding a search bar</a></span></li>
<li><span class="section"><a href="sec-buildapp-side-bar.html">Adding a side bar</a></span></li>
<li><span class="section"><a href="sec-buildapp-properties.html">Properties</a></span></li>
<li><span class="section"><a href="sec-buildapp-header-bar.html">Header bar</a></span></li>
</ul>
</div>
<p>
This chapter is similar to <span class="emphasis"><em>Building applications</em></span> and following sections in the
<a class="ulink" href="https://docs.gtk.org/gtk4/getting_started.html" target="_top">Getting Started</a>
chapter in the GTK documentation.
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, 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="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/buildapp" target="_top"><span class="application">gtkmm-documentation</span>
git repository</a>. You can build each example separately by using <span class="command"><strong>meson</strong></span>
and <span class="command"><strong>ninja</strong></span> with the <code class="filename">meson.build</code> file or by using
<span class="command"><strong>make</strong></span> 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="section">
<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">Gtk::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="https://gnome.pages.gitlab.gnome.org/glibmm/classGio_1_1Application.html" target="_top">Gio::Application Reference</a></p>
<p><a class="ulink" href="https://gnome.pages.gitlab.gnome.org/gtkmm/classGtk_1_1Application.html" target="_top">Gtk::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 class="mediaobject"><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="https://gitlab.gnome.org/GNOME/gtkmm-documentation/tree/master/examples/book/buildapp/step1" target="_top">Source Code</a></p>
<p>File: <code class="filename">exampleapplication.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#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();
};
#endif /* GTKMM_EXAMPLEAPPLICATION_H */
</code></pre>
<p>File: <code class="filename">exampleappwindow.h</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#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 */
</code></pre>
<p>File: <code class="filename">exampleapplication.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "exampleapplication.h"
#include "exampleappwindow.h"
ExampleApplication::ExampleApplication()
: Gtk::Application("org.gtkmm.examples.application", Gio::Application::Flags::HANDLES_OPEN)
{
}
Glib::RefPtr<ExampleApplication> ExampleApplication::create()
{
return Glib::make_refptr_for_instance<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);
// A window can be added to an application with Gtk::Application::add_window()
// or Gtk::Window::set_application(). When all added windows have been hidden
// or removed, the application stops running (Gtk::Application::run() returns()),
// unless Gio::Application::hold() has been called.
// Delete the window when it is hidden.
appwindow->signal_hide().connect([appwindow](){ delete 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();
}
</code></pre>
<p>File: <code class="filename">exampleappwindow.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#include "exampleappwindow.h"
ExampleAppWindow::ExampleAppWindow()
: Gtk::ApplicationWindow()
{
}
void ExampleAppWindow::open_file_view(const Glib::RefPtr<Gio::File>& /* file */)
{
}
</code></pre>
<p>File: <code class="filename">main.cc</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">#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);
}
</code></pre>
<p>File: <code class="filename">exampleapp.desktop.in</code> (For use with gtkmm 4)</p>
<pre class="programlisting"><code class="code">[Desktop Entry]
Type=Application
Name=Gtkmm example
GenericName=Example
Comment=From the "Programming with gtkmm 4" tutorial
Icon=exampleapp
StartupNotify=true
Exec=@bindir@/exampleapp %U
Categories=GNOME;GTK;Utility
</code></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>
|
