| 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 3 (and removed in GTK 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> |