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
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
<refentry id="amtk-intro">
<refmeta>
<refentrytitle>Amtk Introduction</refentrytitle>
</refmeta>
<refnamediv>
<refname>Amtk Introduction</refname>
<refpurpose>
Introduction to the Actions, Menus and Toolbars Kit for GTK applications.
</refpurpose>
</refnamediv>
<para>
Amtk is the acronym for “Actions, Menus and Toolbars Kit”. Amtk has been
initially created as a basic <link linkend="GtkUIManager">GtkUIManager</link>
replacement based on <link linkend="GAction">GAction</link>.
<link linkend="GtkUIManager">GtkUIManager</link> has been deprecated in
GTK 3 (and removed in GTK 4), without a good replacement for
applications that want to keep a traditional UI (with a
<link linkend="GtkMenuBar">GtkMenuBar</link>, a
<link linkend="GtkToolbar">GtkToolbar</link> and a
<link linkend="GtkStatusbar">GtkStatusbar</link>). Amtk is now suitable for
both a traditional UI and for a new UI with a
<link linkend="GtkHeaderBar">GtkHeaderBar</link> and a “sandwich menu”.
</para>
<para>
With Amtk, menus, toolbars or other objects like
<link linkend="GtkShortcutsWindow">GtkShortcutsWindow</link> are created
programmatically (not with a *.ui file), but with convenient APIs. The support
for an XML format will maybe be added in the future.
</para>
<para>
Note that the heavy-lifting is still done by GTK of course (and GIO for
<link linkend="GAction">GAction</link>), this library is just a small layer on
top, providing an alternative way of doing things.
</para>
<refsect1>
<title>General advantages</title>
<itemizedlist>
<listitem>
<para>
Primarily, encoding the information about an action only once, to create
various objects such as a menu item, a toolbar item, a
<link linkend="GtkShortcutsShortcut">GtkShortcutsShortcut</link>, etc.
The information needed about an action: a label (i.e. a short
description), possibly an icon, a tooltip (i.e. a longer description)
and keyboard shortcuts. This is implemented by
<link linkend="AmtkActionInfo">AmtkActionInfo</link>, with
<link linkend="AmtkFactory">AmtkFactory</link> functions to create
various objects.
</para>
<para>
This also has the nice benefit that all the information about an action
is centralized in only one place, to keep related information close
together. This permits to more easily catch inconsistencies.
</para>
</listitem>
<listitem>
<para>
Amtk has been designed to be able to share
<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s in a library (with
translations); this is a bit similar to
<link linkend="GtkStockItem">GtkStockItem</link>, to reduce the amount of
work that an application (and translators) need to do. As a result the
library can provide a higher-level API.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Advantages for a traditional UI</title>
<itemizedlist>
<listitem>
<para>
When writing an XML file to create a <link linkend="GMenu">GMenu</link>
with the format understood by <link linkend="GtkBuilder">GtkBuilder</link>
(see the class description of <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>),
the information in the XML file can be used only to create a <link linkend="GMenu">GMenu</link>,
not a toolbar. It is not a good programming practice to duplicate the
information. With Amtk the information is encoded just once, in
<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s, and menu and
toolbar items are created with <link linkend="AmtkFactory">AmtkFactory</link>
which uses the information provided by the
<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s.
</para>
</listitem>
<listitem>
<para>
Something that is not possible to do with the support of
<link linkend="GMenu">GMenu</link> in GTK, that Amtk solves when using
<link linkend="GtkMenuItem">GtkMenuItem</link>'s: when a
<link linkend="GtkMenuItem">GtkMenuItem</link> is selected (e.g. when
the mouse hovers it), showing a longer description in the
<link linkend="GtkStatusbar">GtkStatusbar</link>. This is implemented by
<link linkend="AmtkApplicationWindow">AmtkApplicationWindow</link>. It
makes the UI better self-discoverable, to improve the usability.
</para>
</listitem>
<listitem>
<para>
Related to the previous point: having a
<link linkend="GtkRecentChooser">GtkRecentChooser</link> menu that shows
in a <link linkend="GtkStatusbar">GtkStatusbar</link> the full file path
when a menu item is selected. This is implemented by
<link linkend="amtk-application-window-connect-recent-chooser-menu-to-statusbar">amtk_application_window_connect_recent_chooser_menu_to_statusbar()</link>.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Sanity checks</title>
<para>
Amtk has several functions to do various sanity checks. They normally don't
impact too much the performances, so it is recommended to always run them,
although they could be disabled on production. The functions:
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="amtk-action-map-add-action-entries-check-dups">amtk_action_map_add_action_entries_check_dups()</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="amtk-action-info-store-check-all-used">amtk_action_info_store_check_all_used()</link>
</para>
</listitem>
<listitem>
<para>
Another sanity check, but which cannot be disabled: the
<link linkend="AmtkActionInfoCentralStore">AmtkActionInfoCentralStore</link>
checks that each <link linkend="AmtkActionInfo">AmtkActionInfo</link>
has a unique action name. Which means that
<link linkend="AmtkActionInfo">AmtkActionInfo</link>'s provided by a
library must be namespaced.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>GTK dependency</title>
<para>
Amtk &package_api_version; depends on GTK 3.
</para>
</refsect1>
<refsect1>
<title>pkg-config name</title>
<para>
For Amtk &package_api_version;, the pkg-config name is:
<code>amtk-&package_api_version;</code>
</para>
<para>
To compile a program that uses Amtk &package_api_version;, you can for
example use the following command:
</para>
<para>
<code>$ gcc hello.c `pkg-config --cflags --libs amtk-&package_api_version;` -o hello</code>
</para>
</refsect1>
</refentry>
|
