Debian Codegraph @

docs/reference/actions-menus-toolbars-intro.xml

raw
1 <?xml version="1.0"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
4 [
5 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
6 <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
7 %gtkdocentities;
8 ]>
9
10 <refentry id="actions-menus-toolbars-intro">
11 <refmeta>
12 <refentrytitle>Actions, Menus and Toolbars - Introduction</refentrytitle>
13 </refmeta>
14
15 <refnamediv>
16 <refname>Actions, Menus and Toolbars - Introduction</refname>
17 <refpurpose>Overview of the Actions, Menus and Toolbars Kit</refpurpose>
18 </refnamediv>
19
20 <para>
21 “Amtk” initially was the acronym for “Actions, Menus and Toolbars Kit”. It
22 provides a basic
23 <link linkend="GtkUIManager">GtkUIManager</link>
24 replacement based on
25 <link linkend="GAction">GAction</link>
26 that is suitable
27 for both a traditional UI or a modern UI with a
28 <link linkend="GtkHeaderBar">GtkHeaderBar</link>.
29 </para>
30
31 <para>
32 <link linkend="GtkUIManager">GtkUIManager</link>
33 has been deprecated in GTK&nbsp;3 (and removed in GTK&nbsp;4), without a good
34 replacement for applications that want to keep a traditional UI (with a
35 <link linkend="GtkMenuBar">GtkMenuBar</link>, a
36 <link linkend="GtkToolbar">GtkToolbar</link> and a
37 <link linkend="GtkStatusbar">GtkStatusbar</link>).
38 libgedit-amtk is also suitable for a new UI with a
39 <link linkend="GtkHeaderBar">GtkHeaderBar</link>
40 and a “sandwich menu”.
41 </para>
42
43 <para>
44 With libgedit-amtk, menus, toolbars or other objects like
45 <link linkend="GtkShortcutsWindow">GtkShortcutsWindow</link> are created
46 programmatically (not with a *.ui file), but with convenient APIs. The support
47 for an XML format will maybe be added in the future.
48 </para>
49
50 <para>
51 Note that the heavy-lifting is still done by GTK of course (and GIO for
52 <link linkend="GAction">GAction</link>). This library is just a small layer on
53 top, providing an alternative way of doing things.
54 </para>
55
56 <refsect1>
57 <title>General advantages</title>
58 <itemizedlist>
59 <listitem>
60 <para>
61 Primarily, encoding the information about an action only once, to create
62 various objects such as a menu item, a toolbar item, a
63 <link linkend="GtkShortcutsShortcut">GtkShortcutsShortcut</link>, etc.
64 The information needed about an action: a label (i.e. a short
65 description), possibly an icon, a tooltip (i.e. a longer description)
66 and keyboard shortcuts. This is implemented by
67 <link linkend="AmtkActionInfo">AmtkActionInfo</link>, with
68 <link linkend="AmtkFactory">AmtkFactory</link> functions to create
69 various objects.
70 </para>
71 <para>
72 This also has the nice benefit that all the information about an action
73 is centralized in only one place, to keep related information close
74 together. This permits to more easily catch inconsistencies.
75 </para>
76 </listitem>
77 <listitem>
78 <para>
79 libgedit-amtk has been designed to be able to share
80 <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s in a library (with
81 translations); this is a bit similar to
82 <link linkend="GtkStockItem">GtkStockItem</link>, to reduce the amount of
83 work that an application (and translators) need to do. As a result the
84 library can provide a higher-level API.
85 </para>
86 </listitem>
87 </itemizedlist>
88 </refsect1>
89
90 <refsect1>
91 <title>Advantages for a traditional UI</title>
92 <itemizedlist>
93 <listitem>
94 <para>
95 When writing an XML file to create a <link linkend="GMenu">GMenu</link>
96 with the format understood by <link linkend="GtkBuilder">GtkBuilder</link>
97 (see the class description of <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>),
98 the information in the XML file can be used only to create a <link linkend="GMenu">GMenu</link>,
99 not a toolbar. It is not a good programming practice to duplicate the
100 information. With libgedit-amtk the information is encoded just once, in
101 <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s, and menu and
102 toolbar items are created with <link linkend="AmtkFactory">AmtkFactory</link>
103 which uses the information provided by the
104 <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s.
105 </para>
106 </listitem>
107 <listitem>
108 <para>
109 Something that is not possible to do with the support of
110 <link linkend="GMenu">GMenu</link> in GTK, that libgedit-amtk solves
111 when using <link linkend="GtkMenuItem">GtkMenuItem</link>'s: when a
112 <link linkend="GtkMenuItem">GtkMenuItem</link> is selected (e.g. when
113 the mouse hovers it), showing a longer description in the
114 <link linkend="GtkStatusbar">GtkStatusbar</link>. This is implemented by
115 <link linkend="AmtkApplicationWindow">AmtkApplicationWindow</link>. It
116 makes the UI better self-discoverable, to improve the usability.
117 </para>
118 </listitem>
119 <listitem>
120 <para>
121 Related to the previous point: having a
122 <link linkend="GtkRecentChooser">GtkRecentChooser</link> menu that shows
123 in a <link linkend="GtkStatusbar">GtkStatusbar</link> the full file path
124 when a menu item is selected. This is implemented by
125 <link linkend="amtk-application-window-connect-recent-chooser-menu-to-statusbar">amtk_application_window_connect_recent_chooser_menu_to_statusbar()</link>.
126 </para>
127 </listitem>
128 </itemizedlist>
129 </refsect1>
130
131 <refsect1>
132 <title>Sanity checks</title>
133 <para>
134 libgedit-amtk has several functions to do various sanity checks. They
135 normally don't impact too much the performances, so it is recommended to
136 always run them, although they could be disabled on production. The
137 functions:
138 </para>
139 <itemizedlist>
140 <listitem>
141 <para>
142 <link linkend="amtk-action-map-add-action-entries-check-dups">amtk_action_map_add_action_entries_check_dups()</link>
143 </para>
144 </listitem>
145 <listitem>
146 <para>
147 <link linkend="amtk-action-info-store-check-all-used">amtk_action_info_store_check_all_used()</link>
148 </para>
149 </listitem>
150 <listitem>
151 <para>
152 Another sanity check, but which cannot be disabled: the
153 <link linkend="AmtkActionInfoCentralStore">AmtkActionInfoCentralStore</link>
154 checks that each <link linkend="AmtkActionInfo">AmtkActionInfo</link>
155 has a unique action name. Which means that
156 <link linkend="AmtkActionInfo">AmtkActionInfo</link>'s provided by a
157 library must be namespaced.
158 </para>
159 </listitem>
160 </itemizedlist>
161 </refsect1>
162 </refentry>