<?xml version="1.0" encoding="utf-8"?>
<section id="GuidePluginsConfig">
  <title id="titleGuidePluginsConfig">Plugins Configuration</title>
  <para />
  <section id="PluginsConfigurationDialog">
    <title>Plugins Configuration Dialog</title>
    <para>
      This dialog allows user to add new plugins or modify the system ones. It is available in the menu
      <menuchoice>
        <guimenu>Edit</guimenu>
        <guimenuitem>Configure Plugins</guimenuitem>
      </menuchoice>
      .
    </para>
    <para>
      The Plugins dialog shows list of all relevant plugins i.e. all installed desktop files that are designated either:
      <itemizedlist spacing="compact">
        >
        <listitem>
          <literal>Categories=Graphics</literal>
        </listitem>
        <listitem>
          <literal>Categories=X-Geeqie</literal>
        </listitem>
      </itemizedlist>
      <para />
      The list has the following columns:
    </para>
    <variablelist spacing="compact">
      <varlistentry>
        <term>
          <guilabel>Disabled</guilabel>
        </term>
        <listitem>
          <para>If the checkbox is ticked, the plugin will not be displayed in Geeqie menus.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>Name</guilabel>
        </term>
        <listitem>
          <para>Plugin name as specified in desktop file, and is the name displayed in menus.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>Hidden</guilabel>
        </term>
        <listitem>
          A plugin can be
          <emphasis>Hidden</emphasis>
          for one of these reasons:
          <itemizedlist>
            <listitem>
              the desktop file contains
              <literal>Hidden=TRUE</literal>
              or
              <literal>NoDisplay=TRUE</literal>
            </listitem>
            <listitem>
              <literal>TryExec</literal>
              binary was not found
            </listitem>
            <listitem>
              <literal>MimeType</literal>
              list does not contain images
            </listitem>
            <listitem>
              <literal>MimeType</literal>
              list is empty and
              <literal>Categories</literal>
              does not contain
              <literal>X-Geeqie</literal>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
    </variablelist>
    <variablelist spacing="compact">
      <varlistentry>
        <term>
          <guilabel>Desktop file</guilabel>
        </term>
        <listitem>
          Name of the desktop file, used as an identifier in
          <link linkend="GuideOptionsKeyboard" endterm="titleGuideOptionsKeyboard" />
          .
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <guilabel>Path</guilabel>
        </term>
        <listitem>Full path to the desktop file. Desktop files in user directories override the system ones with the same name.</listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section id="Addingnewplugin">
    <title>Adding new plugin</title>
    <para>
      <code>
        <guibutton>
          <guiicon>
            <inlinegraphic fileref="document-new.png" />
          </guiicon>
          New
        </guibutton>
      </code>
      opens a text editor with a desktop file template. You must amend the line
      <programlisting>Exec=command %f</programlisting>
      to contain the command you wish to execute. If it is more than a single command, you must create a script file and call that. If the location of the script file is not in your $PATH environment variable, you must include the full pathname.
    </para>
    <para />
  </section>
  <section id="Modifyinganexistingplugin">
    <title>Modifying an existing plugin</title>
    <para>
      <code>
        <guibutton>
          <guiicon>
            <inlinegraphic fileref="gtk-edit.png" />
          </guiicon>
          Edit
        </guibutton>
      </code>
      opens a text editor with existing desktop file. For desktop files that are not writable by user, it allows saving to a Geeqie specific directory, where it overrides the system file (but only for Geeqie).
    </para>
  </section>
  <section id="Deletingaplugin">
    <title>Deleting a plugin</title>
    <para>
      <code>
        <guibutton>
          <guiicon>
            <inlinegraphic fileref="edit-delete.png" />
          </guiicon>
          Delete
        </guibutton>
      </code>
      can delete user writable desktop files. System desktop files can't be deleted directly, but it is possible to edit them and set
      <literal>Hidden=TRUE</literal>
      , see above.
    </para>
  </section>
  <section id="Specialplugins">
    <title>Special plugins</title>
    <para>A desktop file with one of the following names has a special function. It will replace the corresponding internal command.</para>
    <para>
      <programlisting xml:space="preserve">
        geeqie-copy-command.desktop
        geeqie-move-command.desktop
        geeqie-rename-command.desktop
        geeqie-delete-command.desktop
        geeqie-folder-command.desktop
      </programlisting>
    </para>
    <para>This can be used for example for a custom trash command or for manipulation of files under version control.</para>
  </section>
  <section id="Geeqieextensions">
    <title>Geeqie desktop file keys</title>
    <para>
      A desktop file for use only by Geeqie should have the following entries:
      <programlisting>
        Categories=X-Geeqie;
        OnlyShowIn=X-Geeqie;
      </programlisting>
    </para>
    <para>
      A menu path where the plugin will appear, instead of in the default
      <menuchoice>
        <guimenu>Plugins</guimenu>
      </menuchoice>
      , can be set by including:
      <programlisting>X-Geeqie-Menu-Path=&lt;FileMenuPath&gt;</programlisting>
    </para>
    <para>
      Possible vales for
      <emphasis>FileMenuPath</emphasis>
      are:
      <programlisting xml:space="preserve">
        FileMenu
        FileMenu/OpenSection
        FileMenu/SearchSection
        FileMenu/PrintSection
        FileMenu/FileOpsSection
        FileMenu/QuitSection
        GoMenu
        SelectMenu
        SelectMenu/SelectSection
        SelectMenu/ClipboardSection
        SelectMenu/MarksSection
        EditMenu/EditMenu
        EditMenu/EditSection
        EditMenu/OrientationMenu
        EditMenu/RatingMenu
        EditMenu/PropertiesSection
        EditMenu/PreferencesSection
        PluginsMenu
        ViewMenu
        ViewMenu/WindowSection
        ViewMenu/FileDirMenu
        ViewMenu/FileDirMenu/FolderSection
        ViewMenu/FileDirMenu/ListSection
        ViewMenu/DirSection
        ViewMenu/ZoomMenu
        ViewMenu/ZoomMenu/ConnectZoomMenu
        ViewMenu/SplitMenu
        ViewMenu/StereoMenu
        ViewMenu/ColorMenu
        ViewMenu/OverlayMenu
        ViewMenu/ViewSection
        ViewMenu/ToolsSection
        ViewMenu/SlideShowSection
        HelpMenu
        HelpMenu/HelpSection
      </programlisting>
    </para>
    <para>
      If you want a plugin to use a user-definable path, the following entry must be made in the desktop file:
      <programlisting>X-Geeqie-Filter=true</programlisting>
    </para>
    <para>
      Desktop files containing this entry will be displayed in the Folder action list of the
      <link linkend="CopyMoveandLink" endterm="titleGuideSidebarsSortManager" />
      . The path of the bookmark clicked will be used by the desktop file.
      <para />
      If the desktop file is called from the menu, when the plugin is executed you are presented with a dialogue which enables a path to be selected. The path selected, appended by the filename currently being processed, is made available to the shell script either as an environment variable or via a call to geeqie --remote. The following code demonstrates the use of both methods:
      <programlisting xml:space="preserve">
        for file in "$@"
        do
        destination=$(geeqie --remote --get-destination:"$file")
        
        echo "$destination"
        echo $GEEQIE_DESTINATION
        done
      </programlisting>
    </para>
    <para>
      If you want to run a plugin in full-screen mode and wish full-screen to be maintained, include the following entry in the desktop file:
      <programlisting>X-Geeqie-Keep-Fullscreen=true</programlisting>
    </para>
    <para>
      Any terminal output from the plugin command can be displayed with the following command:
      <programlisting>X-Geeqie-Verbose=true</programlisting>
    </para>
    <para>
      The plugin can be restricted to run on only certain file types, for example:
      <programlisting>X-Geeqie-File-Extensions=.jpg; .cr2</programlisting>
      The entries are case insensitive.
    </para>
    <para>
      <programlisting>X-Geeqie-Keep-Verbose-Multi=</programlisting>
      TBD
    </para>
    <para>
      The key or key combination to execute this function can be set with:
      <programlisting>X-Geeqie-Hotkey=</programlisting>
      Key combinations are of the form:

      <programlisting>X-Geeqie-Hotkey=&lt;control&gt;y</programlisting>
      <note>
        This value may conflict with a setting in
        <link linkend="GuideOptionsKeyboard" endterm="titleGuideOptionsKeyboard" />
      </note>
    </para>
  </section>
</section>