<?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="actions-menus-toolbars-intro">
<refmeta>
  <refentrytitle>Actions, Menus and Toolbars - Introduction</refentrytitle>
</refmeta>

<refnamediv>
  <refname>Actions, Menus and Toolbars - Introduction</refname>
  <refpurpose>Overview of the Actions, Menus and Toolbars Kit</refpurpose>
</refnamediv>

<para>
  “Amtk” initially was the acronym for “Actions, Menus and Toolbars Kit”. It
  provides a basic
  <link linkend="GtkUIManager">GtkUIManager</link>
  replacement based on
  <link linkend="GAction">GAction</link>
  that is suitable
  for both a traditional UI or a modern UI with a
  <link linkend="GtkHeaderBar">GtkHeaderBar</link>.
</para>

<para>
  <link linkend="GtkUIManager">GtkUIManager</link>
  has been deprecated in GTK&nbsp;3 (and removed in GTK&nbsp;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>).
  libgedit-amtk is also suitable for a new UI with a
  <link linkend="GtkHeaderBar">GtkHeaderBar</link>
  and a “sandwich menu”.
</para>

<para>
  With libgedit-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>
        libgedit-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 libgedit-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 libgedit-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>
    libgedit-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>
</refentry>
