<?xml version="1.0" encoding="utf-8"?>
<section id="GuideOptionsOSD">
  <title>OverlayScreen Display</title>
  <para>This section describes the options presented under the OSD Tab of the preferences dialog.</para>
  <section id="OverlayScreenDisplay">
    <title>Overlay Screen Display</title>
    <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>
    <para>
      The format of each entry is:
      <programlisting>%tag[:max_length][:extra]%</programlisting>
    </para>
    <table frame="all">
      <tgroup cols="2" rowsep="1" colsep="1">
        <tbody>
          <row>
            <entry>
              <emphasis role="strong">Tag</emphasis>
            </entry>
            <entry>
              <emphasis role="strong">Replaced by</emphasis>
            </entry>
          </row>
          <row>
            <entry>name</entry>
            <entry>Filename of the picture</entry>
          </row>
          <row>
            <entry>path</entry>
            <entry>Full path, including filename, of the picture</entry>
          </row>
          <row>
            <entry>collection</entry>
            <entry>Name of the collection</entry>
          </row>
          <row>
            <entry>number</entry>
            <entry>Current number of image in the list</entry>
          </row>
          <row>
            <entry>total</entry>
            <entry>Total number of images</entry>
          </row>
          <row>
            <entry>date</entry>
            <entry>File date</entry>
          </row>
          <row>
            <entry>size</entry>
            <entry>File size</entry>
          </row>
          <row>
            <entry>width</entry>
            <entry>Image width</entry>
          </row>
          <row>
            <entry>height</entry>
            <entry>Image height</entry>
          </row>
          <row>
            <entry>res</entry>
            <entry>Image resolution</entry>
          </row>
          <row>
            <entry>keywords</entry>
            <entry>Image keywords from metadata</entry>
          </row>
          <row>
            <entry>comment</entry>
            <entry>Image comment from XMP metadata</entry>
          </row>
          <row>
            <entry>imagecomment</entry>
            <entry>JPEG image comment</entry>
          </row>
          <row>
            <entry>rating</entry>
            <entry>Image rating</entry>
          </row>
          <row>
            <entry>&lt;meta_tag&gt;</entry>
            <entry>The Exif, XMP, or IPTC tag from metadata</entry>
          </row>
          <row>
            <entry>lua/&lt;lua_script&gt;/</entry>
            <entry>The output of a Lua script file</entry>
          </row>
          <row>
            <entry>lua//&lt;lua_command&gt;</entry>
            <entry>The output of a Lua command</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>
      As an aide, in addition to standard metadata tags, Geeqie provides a number of
      <link linkend="formatted_exif">pre-formatted tags</link>
      .
    </para>
    <para>Examples of usage are:</para>
    <para>
      <programlisting xml:space="preserve">
        %keywords%
        %Exif.Photo.DateTimeOriginal%
        %lua/jpeg_comment.lua/:12%
        %lua//return(os.date())%
      </programlisting>
    </para>
    <para>
      Refer to
      <link linkend="GuideReferenceLua">Lua Extensions</link>
      for further information.
    </para>
    <para>
      The length of displayed data can be limited by using the
      <emphasis role="italic">:max_length</emphasis>
      parameter. The following example will truncate the displayed data to 20 characters and will add 3 dots at the end to denote the truncation.
      <programlisting>%formatted.Camera:20%</programlisting>
    </para>
    <para>
      If two or more variables are connected with the
      <code>|</code>
      character, the variables are displayed with a separator. For example::
      <programlisting>%formatted.ShutterSpeed%|%formatted.ISOSpeedRating%|%formatted.FocalLength%</programlisting>
      could show:
      <programlisting>"1/20s - 400 - 80 mm"</programlisting>
      Or, if there is no ISO information in the Exif data:
      <programlisting>"1/200 - 80 mm"</programlisting>
    </para>
    <para>If there is no data for a requested tag, the line is not displayed.</para>
    <para>
      The
      <emphasis role="italic">:extra</emphasis>
      parameter may be used to format the output by prepending and appending a text string to the displayed item.
    </para>
    <para>
      The special character
      <code>*</code>
      is used to mark the position of the Tag data item. If no
      <code>*</code>
      is present, the extra string is just appended to the standard data displayed. Any "\n" is replaced by a newline on display.
      <link linkend="GuideReferenceStandards">Pango mark up</link>
      is accepted in both left and right parts. If the data item is empty, nothing will be displayed.
    </para>
    <para>Examples:</para>
    <table>
      <tgroup cols="2" rowsep="1" colsep="1">
        <tbody>
          <row>
            <entry>
              <emphasis role="strong">Template</emphasis>
            </entry>
            <entry>
              <emphasis role="strong">Example display</emphasis>
            </entry>
          </row>
          <row>
            <entry>
              %name:
              &lt;i&gt;*&lt;/i&gt;\n%
            </entry>
            <entry>
              <emphasis role="italic">filename001.jpg</emphasis>
            </entry>
          </row>
          <row>
            <entry>%size:\n%</entry>
            <entry>123456</entry>
          </row>
          <row>
            <entry>%formatted.ISOSpeedRating:ISO *%</entry>
            <entry>ISO 100</entry>
          </row>
          <row>
            <entry>
              %collection:Collection:
              &lt;b&gt;*&lt;/b&gt;
              \n%
            </entry>
            <entry>
              Collection:
              <emphasis role="strong">my_new_collection</emphasis>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para />
    <variablelist>
      <varlistentry>
        <term>
          <guibutton>
            <guiicon>
              <inlinegraphic fileref="preferences-desktop-font.png" />
            </guiicon>
          </guibutton>
          <guilabel>Font</guilabel>
          ,
          <guibutton>
            <guiicon>
              <inlinegraphic fileref="gtk-color-picker.png" />
            </guiicon>
          </guibutton>
          <guilabel>Text</guilabel>
          ,
          <guibutton>
            <guiicon>
              <inlinegraphic fileref="gtk-color-picker.png" />
            </guiicon>
          </guibutton>
          <guilabel>Background</guilabel>
        </term>
        <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>
      </varlistentry>
    </variablelist>
    <variablelist>
      <varlistentry>
        <term>
          <guibutton>
            <guiicon>
              <inlinegraphic fileref="help-contents.png" />
            </guiicon>
          </guibutton>
          <guilabel>Help</guilabel>
        </term>
        <listitem>
          <para>Show syntax help</para>
        </listitem>
      </varlistentry>
    </variablelist>
    <variablelist>
      <varlistentry>
        <term>
          <guilabel>Defaults</guilabel>
        </term>
        <listitem>
          <para>Restore default image overlay template</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
</section>
