doc/docbook/GuideOptionsOSD.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <section id="GuideOptionsOSD">
   3   <title>OverlayScreen Display</title>
   4   <para>This section describes the options presented under the OSD Tab of the preferences dialog.</para>
   5   <section id="OverlayScreenDisplay">
   6     <title>Overlay Screen Display</title>
   7     <para>The contents of the Overlay Screen Display is defined by the Image Overlay Template. This template is easily customised to  display a wide range of data.</para>
   8     <para>
   9       The format of each entry is:
  10       <programlisting>%tag[:max_length][:extra]%</programlisting>
  11     </para>
  12     <table frame="all">
  13       <tgroup cols="2" rowsep="1" colsep="1">
  14         <tbody>
  15           <row>
  16             <entry>
  17               <emphasis role="strong">Tag</emphasis>
  18             </entry>
  19             <entry>
  20               <emphasis role="strong">Replaced by</emphasis>
  21             </entry>
  22           </row>
  23           <row>
  24             <entry>name</entry>
  25             <entry>Filename of the picture</entry>
  26           </row>
  27           <row>
  28             <entry>path</entry>
  29             <entry>Full path, including filename, of the picture</entry>
  30           </row>
  31           <row>
  32             <entry>collection</entry>
  33             <entry>Name of the collection</entry>
  34           </row>
  35           <row>
  36             <entry>number</entry>
  37             <entry>Current number of image in the list</entry>
  38           </row>
  39           <row>
  40             <entry>total</entry>
  41             <entry>Total number of images</entry>
  42           </row>
  43           <row>
  44             <entry>date</entry>
  45             <entry>File date</entry>
  46           </row>
  47           <row>
  48             <entry>size</entry>
  49             <entry>File size</entry>
  50           </row>
  51           <row>
  52             <entry>width</entry>
  53             <entry>Image width</entry>
  54           </row>
  55           <row>
  56             <entry>height</entry>
  57             <entry>Image height</entry>
  58           </row>
  59           <row>
  60             <entry>res</entry>
  61             <entry>Image resolution</entry>
  62           </row>
  63           <row>
  64             <entry>keywords</entry>
  65             <entry>Image keywords from metadata</entry>
  66           </row>
  67           <row>
  68             <entry>comment</entry>
  69             <entry>Image comment from XMP metadata</entry>
  70           </row>
  71           <row>
  72             <entry>imagecomment</entry>
  73             <entry>JPEG image comment</entry>
  74           </row>
  75           <row>
  76             <entry>rating</entry>
  77             <entry>Image rating</entry>
  78           </row>
  79           <row>
  80             <entry>&lt;meta_tag&gt;</entry>
  81             <entry>The Exif, XMP, or IPTC tag from metadata</entry>
  82           </row>
  83           <row>
  84             <entry>lua/&lt;lua_script&gt;/</entry>
  85             <entry>The output of a Lua script file</entry>
  86           </row>
  87           <row>
  88             <entry>lua//&lt;lua_command&gt;</entry>
  89             <entry>The output of a Lua command</entry>
  90           </row>
  91         </tbody>
  92       </tgroup>
  93     </table>
  94     <para>
  95       As an aide, in addition to standard metadata tags, Geeqie provides a number of
  96       <link linkend="formatted_exif">pre-formatted tags</link>
  97       .
  98     </para>
  99     <para>Examples of usage are:</para>
 100     <para>
 101       <programlisting xml:space="preserve">
 102         %keywords%
 103         %Exif.Photo.DateTimeOriginal%
 104         %lua/jpeg_comment.lua/:12%
 105         %lua//return(os.date())%
 106       </programlisting>
 107     </para>
 108     <para>
 109       Refer to
 110       <link linkend="GuideReferenceLua">Lua Extensions</link>
 111       for further information.
 112     </para>
 113     <para>
 114       The length of displayed data can be limited by using the
 115       <emphasis role="italic">:max_length</emphasis>
 116       parameter. The following example will truncate the displayed data to 20 characters and will add 3 dots at the end to denote the truncation.
 117       <programlisting>%formatted.Camera:20%</programlisting>
 118     </para>
 119     <para>
 120       If two or more variables are connected with the
 121       <code>|</code>
 122       character, the variables are displayed with a separator. For example::
 123       <programlisting>%formatted.ShutterSpeed%|%formatted.ISOSpeedRating%|%formatted.FocalLength%</programlisting>
 124       could show:
 125       <programlisting>"1/20s - 400 - 80 mm"</programlisting>
 126       Or, if there is no ISO information in the Exif data:
 127       <programlisting>"1/200 - 80 mm"</programlisting>
 128     </para>
 129     <para>If there is no data for a requested tag, the line is not displayed.</para>
 130     <para>
 131       The
 132       <emphasis role="italic">:extra</emphasis>
 133       parameter may be used to format the output by prepending and appending a text string to the displayed item.
 134     </para>
 135     <para>
 136       The special character
 137       <code>*</code>
 138       is used to mark the position of the Tag data item. If no
 139       <code>*</code>
 140       is present, the extra string is just appended to the standard data displayed. Any "\n" is replaced by a newline on display.
 141       <link linkend="GuideReferenceStandards">Pango mark up</link>
 142       is accepted in both left and right parts. If the data item is empty, nothing will be displayed.
 143     </para>
 144     <para>Examples:</para>
 145     <table>
 146       <tgroup cols="2" rowsep="1" colsep="1">
 147         <tbody>
 148           <row>
 149             <entry>
 150               <emphasis role="strong">Template</emphasis>
 151             </entry>
 152             <entry>
 153               <emphasis role="strong">Example display</emphasis>
 154             </entry>
 155           </row>
 156           <row>
 157             <entry>
 158               %name:
 159               &lt;i&gt;*&lt;/i&gt;\n%
 160             </entry>
 161             <entry>
 162               <emphasis role="italic">filename001.jpg</emphasis>
 163             </entry>
 164           </row>
 165           <row>
 166             <entry>%size:\n%</entry>
 167             <entry>123456</entry>
 168           </row>
 169           <row>
 170             <entry>%formatted.ISOSpeedRating:ISO *%</entry>
 171             <entry>ISO 100</entry>
 172           </row>
 173           <row>
 174             <entry>
 175               %collection:Collection:
 176               &lt;b&gt;*&lt;/b&gt;
 177               \n%
 178             </entry>
 179             <entry>
 180               Collection:
 181               <emphasis role="strong">my_new_collection</emphasis>
 182             </entry>
 183           </row>
 184         </tbody>
 185       </tgroup>
 186     </table>
 187     <para />
 188     <variablelist>
 189       <varlistentry>
 190         <term>
 191           <guibutton>
 192             <guiicon>
 193               <inlinegraphic fileref="preferences-desktop-font.png" />
 194             </guiicon>
 195           </guibutton>
 196           <guilabel>Font</guilabel>
 197           ,
 198           <guibutton>
 199             <guiicon>
 200               <inlinegraphic fileref="gtk-color-picker.png" />
 201             </guiicon>
 202           </guibutton>
 203           <guilabel>Text</guilabel>
 204           ,
 205           <guibutton>
 206             <guiicon>
 207               <inlinegraphic fileref="gtk-color-picker.png" />
 208             </guiicon>
 209           </guibutton>
 210           <guilabel>Background</guilabel>
 211         </term>
 212         <listitem>The font used for the Overlay Screen Display, as well as the font colour and background colour, may be set via these buttons. Colour transparency can also be set.</listitem>
 213       </varlistentry>
 214     </variablelist>
 215     <variablelist>
 216       <varlistentry>
 217         <term>
 218           <guibutton>
 219             <guiicon>
 220               <inlinegraphic fileref="help-contents.png" />
 221             </guiicon>
 222           </guibutton>
 223           <guilabel>Help</guilabel>
 224         </term>
 225         <listitem>
 226           <para>Show syntax help</para>
 227         </listitem>
 228       </varlistentry>
 229     </variablelist>
 230     <variablelist>
 231       <varlistentry>
 232         <term>
 233           <guilabel>Defaults</guilabel>
 234         </term>
 235         <listitem>
 236           <para>Restore default image overlay template</para>
 237         </listitem>
 238       </varlistentry>
 239     </variablelist>
 240   </section>
 241 </section>