[amtk] docs: update intro
- From: Sébastien Wilmet <swilmet src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [amtk] docs: update intro
- Date: Sat, 14 Apr 2018 17:24:39 +0000 (UTC)
commit 0f654f04d0bbce302cb4be4d5464e1c21369a958
Author: Sébastien Wilmet <swilmet gnome org>
Date: Sat Apr 14 18:15:27 2018 +0200
docs: update intro
docs/reference/amtk-intro.xml.in | 152 ++++++++++++++++++++++----------------
1 files changed, 87 insertions(+), 65 deletions(-)
---
diff --git a/docs/reference/amtk-intro.xml.in b/docs/reference/amtk-intro.xml.in
index 0fe815b..056b702 100644
--- a/docs/reference/amtk-intro.xml.in
+++ b/docs/reference/amtk-intro.xml.in
@@ -20,78 +20,100 @@
</refnamediv>
<para>
- Amtk is the acronym for “Actions, Menus and Toolbars Kit”. It is a basic
- <link linkend="GtkUIManager">GtkUIManager</link> replacement based on
- <link linkend="GAction">GAction</link>.
+ 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, without a good replacement for applications that want to keep a
- traditional UI (with a <link linkend="GtkMenuBar">GtkMenuBar</link>, a
+ 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>; in contrast to the new UI
- with a <link linkend="GtkHeaderBar">GtkHeaderBar</link> and a “hamburger
- menu”).
+ <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 “hamburger menu”.
</para>
<para>
- With Amtk, menus and toolbars are created programmatically, but with
- convenient APIs (the support for an XML format will maybe be added in the
- future, contributions welcome). <link linkend="GMenu">GMenu</link> is not
- used, a menubar is created with <link linkend="GtkMenuItem">GtkMenuItem</link>'s,
- although the support for <link linkend="GMenu">GMenu</link> could easily be
- added.
+ 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, contributions welcome.
</para>
-<para>
- There are currently several things that are not possible to do with the
- support of <link linkend="GMenu">GMenu</link> in GTK+, that Amtk solves:
-</para>
-<itemizedlist>
- <listitem>
- <para>
- Primarily, encoding the information about an action only once, to create
- both a menu item and a toolbar item for that action. The information
- needed: a label (i.e. a short description), 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 menu
- and toolbar items.
- </para>
- <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 would not be convenient to duplicate the information.
- </para>
- </listitem>
- <listitem>
- <para>
- 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>
- <listitem>
- <para>
- Additionally, the Amtk infrastructure permits 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.
- </para>
- </listitem>
-</itemizedlist>
+<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>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]