doc/docbook/GuidePluginsConfig.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <section id="GuidePluginsConfig">
   3   <title id="titleGuidePluginsConfig">Plugins Configuration</title>
   4   <para />
   5   <section id="PluginsConfigurationDialog">
   6     <title>Plugins Configuration Dialog</title>
   7     <para>
   8       This dialog allows user to add new plugins or modify the system ones. It is available in the menu
   9       <menuchoice>
  10         <guimenu>Edit</guimenu>
  11         <guimenuitem>Configure Plugins</guimenuitem>
  12       </menuchoice>
  13       .
  14     </para>
  15     <para>
  16       The Plugins dialog shows list of all relevant plugins i.e. all installed desktop files that are designated either:
  17       <itemizedlist spacing="compact">
  18         >
  19         <listitem>
  20           <literal>Categories=Graphics</literal>
  21         </listitem>
  22         <listitem>
  23           <literal>Categories=X-Geeqie</literal>
  24         </listitem>
  25       </itemizedlist>
  26       <para />
  27       The list has the following columns:
  28     </para>
  29     <variablelist spacing="compact">
  30       <varlistentry>
  31         <term>
  32           <guilabel>Disabled</guilabel>
  33         </term>
  34         <listitem>
  35           <para>If the checkbox is ticked, the plugin will not be displayed in Geeqie menus.</para>
  36         </listitem>
  37       </varlistentry>
  38       <varlistentry>
  39         <term>
  40           <guilabel>Name</guilabel>
  41         </term>
  42         <listitem>
  43           <para>Plugin name as specified in desktop file, and is the name displayed in menus.</para>
  44         </listitem>
  45       </varlistentry>
  46       <varlistentry>
  47         <term>
  48           <guilabel>Hidden</guilabel>
  49         </term>
  50         <listitem>
  51           A plugin can be
  52           <emphasis>Hidden</emphasis>
  53           for one of these reasons:
  54           <itemizedlist>
  55             <listitem>
  56               the desktop file contains
  57               <literal>Hidden=TRUE</literal>
  58               or
  59               <literal>NoDisplay=TRUE</literal>
  60             </listitem>
  61             <listitem>
  62               <literal>TryExec</literal>
  63               binary was not found
  64             </listitem>
  65             <listitem>
  66               <literal>MimeType</literal>
  67               list does not contain images
  68             </listitem>
  69             <listitem>
  70               <literal>MimeType</literal>
  71               list is empty and
  72               <literal>Categories</literal>
  73               does not contain
  74               <literal>X-Geeqie</literal>
  75             </listitem>
  76           </itemizedlist>
  77         </listitem>
  78       </varlistentry>
  79     </variablelist>
  80     <variablelist spacing="compact">
  81       <varlistentry>
  82         <term>
  83           <guilabel>Desktop file</guilabel>
  84         </term>
  85         <listitem>
  86           Name of the desktop file, used as an identifier in
  87           <link linkend="GuideOptionsKeyboard" endterm="titleGuideOptionsKeyboard" />
  88           .
  89         </listitem>
  90       </varlistentry>
  91       <varlistentry>
  92         <term>
  93           <guilabel>Path</guilabel>
  94         </term>
  95         <listitem>Full path to the desktop file. Desktop files in user directories override the system ones with the same name.</listitem>
  96       </varlistentry>
  97     </variablelist>
  98   </section>
  99   <section id="Addingnewplugin">
 100     <title>Adding new plugin</title>
 101     <para>
 102       <code>
 103         <guibutton>
 104           <guiicon>
 105             <inlinegraphic fileref="document-new.png" />
 106           </guiicon>
 107           New
 108         </guibutton>
 109       </code>
 110       opens a text editor with a desktop file template. You must amend the line
 111       <programlisting>Exec=command %f</programlisting>
 112       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.
 113     </para>
 114     <para />
 115   </section>
 116   <section id="Modifyinganexistingplugin">
 117     <title>Modifying an existing plugin</title>
 118     <para>
 119       <code>
 120         <guibutton>
 121           <guiicon>
 122             <inlinegraphic fileref="gtk-edit.png" />
 123           </guiicon>
 124           Edit
 125         </guibutton>
 126       </code>
 127       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).
 128     </para>
 129   </section>
 130   <section id="Deletingaplugin">
 131     <title>Deleting a plugin</title>
 132     <para>
 133       <code>
 134         <guibutton>
 135           <guiicon>
 136             <inlinegraphic fileref="edit-delete.png" />
 137           </guiicon>
 138           Delete
 139         </guibutton>
 140       </code>
 141       can delete user writable desktop files. System desktop files can't be deleted directly, but it is possible to edit them and set
 142       <literal>Hidden=TRUE</literal>
 143       , see above.
 144     </para>
 145   </section>
 146   <section id="Specialplugins">
 147     <title>Special plugins</title>
 148     <para>A desktop file with one of the following names has a special function. It will replace the corresponding internal command.</para>
 149     <para>
 150       <programlisting xml:space="preserve">
 151         geeqie-copy-command.desktop
 152         geeqie-move-command.desktop
 153         geeqie-rename-command.desktop
 154         geeqie-delete-command.desktop
 155         geeqie-folder-command.desktop
 156       </programlisting>
 157     </para>
 158     <para>This can be used for example for a custom trash command or for manipulation of files under version control.</para>
 159   </section>
 160   <section id="Geeqieextensions">
 161     <title>Geeqie desktop file keys</title>
 162     <para>
 163       A desktop file for use only by Geeqie should have the following entries:
 164       <programlisting>
 165         Categories=X-Geeqie;
 166         OnlyShowIn=X-Geeqie;
 167       </programlisting>
 168     </para>
 169     <para>
 170       A menu path where the plugin will appear, instead of in the default
 171       <menuchoice>
 172         <guimenu>Plugins</guimenu>
 173       </menuchoice>
 174       , can be set by including:
 175       <programlisting>X-Geeqie-Menu-Path=&lt;FileMenuPath&gt;</programlisting>
 176     </para>
 177     <para>
 178       Possible vales for
 179       <emphasis>FileMenuPath</emphasis>
 180       are:
 181       <programlisting xml:space="preserve">
 182         FileMenu
 183         FileMenu/OpenSection
 184         FileMenu/SearchSection
 185         FileMenu/PrintSection
 186         FileMenu/FileOpsSection
 187         FileMenu/QuitSection
 188         GoMenu
 189         SelectMenu
 190         SelectMenu/SelectSection
 191         SelectMenu/ClipboardSection
 192         SelectMenu/MarksSection
 193         EditMenu/EditMenu
 194         EditMenu/EditSection
 195         EditMenu/OrientationMenu
 196         EditMenu/RatingMenu
 197         EditMenu/PropertiesSection
 198         EditMenu/PreferencesSection
 199         PluginsMenu
 200         ViewMenu
 201         ViewMenu/WindowSection
 202         ViewMenu/FileDirMenu
 203         ViewMenu/FileDirMenu/FolderSection
 204         ViewMenu/FileDirMenu/ListSection
 205         ViewMenu/DirSection
 206         ViewMenu/ZoomMenu
 207         ViewMenu/ZoomMenu/ConnectZoomMenu
 208         ViewMenu/SplitMenu
 209         ViewMenu/StereoMenu
 210         ViewMenu/ColorMenu
 211         ViewMenu/OverlayMenu
 212         ViewMenu/ViewSection
 213         ViewMenu/ToolsSection
 214         ViewMenu/SlideShowSection
 215         HelpMenu
 216         HelpMenu/HelpSection
 217       </programlisting>
 218     </para>
 219     <para>
 220       If you want a plugin to use a user-definable path, the following entry must be made in the desktop file:
 221       <programlisting>X-Geeqie-Filter=true</programlisting>
 222     </para>
 223     <para>
 224       Desktop files containing this entry will be displayed in the Folder action list of the
 225       <link linkend="CopyMoveandLink" endterm="titleGuideSidebarsSortManager" />
 226       . The path of the bookmark clicked will be used by the desktop file.
 227       <para />
 228       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:
 229       <programlisting xml:space="preserve">
 230         for file in "$@"
 231         do
 232         destination=$(geeqie --remote --get-destination:"$file")
 233
 234         echo "$destination"
 235         echo $GEEQIE_DESTINATION
 236         done
 237       </programlisting>
 238     </para>
 239     <para>
 240       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:
 241       <programlisting>X-Geeqie-Keep-Fullscreen=true</programlisting>
 242     </para>
 243     <para>
 244       Any terminal output from the plugin command can be displayed with the following command:
 245       <programlisting>X-Geeqie-Verbose=true</programlisting>
 246     </para>
 247     <para>
 248       Any terminal output from the plugin command can be displayed, only when multiple files are selected, with the following command:
 249       <programlisting>X-Geeqie-Verbose-Multi=true</programlisting>
 250     </para>
 251     <para>
 252       The plugin can be restricted to run on only certain file types, for example:
 253       <programlisting>X-Geeqie-File-Extensions=.jpg; .cr2</programlisting>
 254       The entries are case insensitive.
 255     </para>
 256     <para>
 257       The key or key combination to execute this function can be set with:
 258       <programlisting>X-Geeqie-Hotkey=</programlisting>
 259       Key combinations are of the form:
 260
 261       <programlisting>X-Geeqie-Hotkey=&lt;control&gt;y</programlisting>
 262       <note>
 263         This value may conflict with a setting in
 264         <link linkend="GuideOptionsKeyboard" endterm="titleGuideOptionsKeyboard" />
 265       </note>
 266     </para>
 267   </section>
 268 </section>