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