doc/docbook/GuidePluginsConfig.xml

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