<!--
SPDX-FileCopyrightText: 2003 Stephan Kulow <coolo@kde.org>
SPDX-FileCopyrightText: 2003-2006 Jesper K. Pedersen <jesper.pedersen@kdab.com>
SPDX-FileCopyrightText: 2012 André Marcelo Alvarenga <alvarenga@kde.org>
SPDX-FileCopyrightText: 2012 Miika Turkia <miika.turkia@gmail.com>
SPDX-FileCopyrightText: 2012 Yuri Chornoivan <yurchor@ukr.net>

SPDX-License-Identifier: GFDL-1.2-only
-->

<chapter id="chp-typingIn">
  <title>Annotating your images</title>
  <para>In <xref linkend="fig-empty-browser-window"/> you can see
an example of the window that will greet you once you have started &kphotoalbum;
with your own images.</para>

  <para>At the top of the screen you will find a menu and toolbar, as you
know from any &kde; application. Below the toolbar you see the browser
window. In browser window you can select different categories to limit the images you will be inspecting. In <xref
      linkend="chp-browsing"/> we will get back to the browser, but for
now, simply press the <guibutton>Show Thumbnails</guibutton> item, which will show
you a thumbnail view of all your images.</para>

  <figure id="fig-empty-browser-window">
    <title>Starting &kphotoalbum; with your own images</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="empty-browser-window.png"
          format="PNG"/>
      </imageobject>
    </mediaobject>
  </figure>

    <para>The key feature of &kphotoalbum; is that you can annotate your images. This includes who is on a given image, where it is taken,
&etc; You can do this either one image at a time, or you can annotate a number of images simultaneously (For example, all these
images contain the person <emphasis>Jesper</emphasis>, and is taken in
<emphasis>Copenhagen</emphasis>.)</para>

    <para>To annotate images, select the images in question,
and go to <menuchoice><guimenu>Edit</guimenu>
<guisubmenu>Annotate Individual Items</guisubmenu></menuchoice>. Now you
annotate your selected images one after the other. If you instead choose
<guimenuitem>Annotate Multiple Items at a Time</guimenuitem>, you will
annotate all the selected items as if it was one single item. In other
words, with this option you mass-annotate your image - e.g. saying all
these images were shot in Copenhagen. These two options are also available from a context menu, that you
get by right clicking the mouse in the thumbnail overview or using keyboard shortcut. An example of
this can be seen in <xref linkend="fig-edit-properties-menu"/>.</para>

    <figure id="fig-edit-properties-menu">
      <title>Context menu for editing properties</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="edit-properties-menu.png"
            format="PNG"/>
        </imageobject>
      </mediaobject>
    </figure>

    <para>In <xref linkend="fig-image-config-window"/> below you can see
the window for annotating images and videos. In this window you can specify
the date of the item, the label of the item <footnote><para>The label is
          initialized to the name of the file. The label is used in the
          browser, and when the images are exported to &HTML;
          pages</para></footnote>, a description for the item, and most important
different <emphasis>categories</emphasis> for the item. In the screen shot, these categories are
<literal>People</literal>, <literal>Places</literal>, and
<literal>Keywords</literal>, but as you will see in <xref
        linkend="sec-specifying-categories"/>, these three predefined
categories may be changed to your preferences.
 </para>

    <figure id="fig-image-config-window">
      <title>Annotating images and videos</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="image-config-window.png"
            format="PNG"/>
        </imageobject>
      </mediaobject>
    </figure>

    <para>All these annotations may be used for searching and
browsing, as we will see in <xref linkend="chp-browsing"/>. On request you
may see these annotations when viewing the items in the build-in viewer.</para>




    <sect1 id="sect-specifying-options">
      <title>Categories</title>
      <para>In <xref linkend="fig-image-config-window"/> there are three
list boxes combined with line edits for specifying people, places and
keywords. These widget are a very important part of &kphotoalbum;,
as you will use them over and over again, when specifying information about
your images.</para>

      <para> You can specify a property from a list box, simply by
selecting it (Select say <literal>Donna</literal> to specify that Donna is
on the given image. Alternatively you may type its name in the line edit.
When you start typing a name in the line edit, &kphotoalbum; will look into the listbox,
and search for the first item matching what you've typed so far, and fill
it out. Thus typing <literal>Do</literal> might be enough to find
<literal>Donna</literal>. Once you have found the item you search for,
simply press enter to select this item in the listbox. The item will now be
moved to the top of the view, so next time you need the given item it is
even easier to find.</para>

      <para>The idea behind moving items to the top when they have been
selected is, that when going to, say a family party, you will get perhaps
50 images all with the same 5-10 people. When typing in information about these
50 images you will have the 5-10 people at the top of the listbox as soon as
you have typed in their name the first time.</para>

     <para>If you prefer to have the list alphabetically sorted instead,
simply press the icon for sorting under the list box.</para>
    </sect1>


    <sect1 id="sect-specifying-properties-for-one-image-at-a-time">
      <title>Annotating one item at a time</title>
      <para>When you specify properties for one image at a time, you may
still of course select a number of images, and say, <emphasis>I want to
annotate these images</emphasis>. In this situation, you will
find a next and previous button under the image in the topmost rightmost
corner. </para>
    </sect1>

    <sect1 id="sect-specifying-properties-for-all-images-simultaneously">
      <title>Annotating multiple items at a time</title>
      <para>If you have several images with, say the same person, then it
might be more convenient to select those images, and specify that this
person is on all images using the <emphasis>Annotate Multiple Items at a Time</emphasis>.</para>
      <para>If you want to annotate a stack of images you can do that
      when the stack is collapsed. You just need to select the top image
      of the stack and annotate multiple images. (If you annotate single
      image, only the selected image, the stack head in this case, is
      being annotated.) Of course expanding the stack and selecting all
      images works as well.</para>

    </sect1>


<sect1 id="sec-member-groups-in-property-editor">
<title>Sub-categories</title>
  <para>Las Vegas, San Francisco, Los Angeles, and California are all
located in USA. Furthermore, San Francisco and Los Angeles are located in
California.</para>

<para>Instead of specifying for each and every image from San Francisco,
that it is in San Francisco, and in California, and in USA, you may instead
tell &kphotoalbum; that San Francisco, and Los Angeles are in California, and that California among
others are in USA. Doing so the browser (see <xref
linkend="chp-browsing"/>) will offer you an item for USA, and an item for
California in addition to all your normal items. Selecting California, you
will see all images from San Francisco, Los Angeles, &etc;</para>

<para>In <xref linkend="fig-usa-as-a-member"/> you can see a browser
window, containing USA as a super category. To indicate to you that this is a
group, a special icon is used.</para>

<figure id="fig-usa-as-a-member">
<title>Browser showing USA as a super category</title>
<mediaobject>
<imageobject>
<imagedata fileref="usa-as-a-member.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>

<para>In the context menu for the annotation dialog it is possible to add
an item to an existing or new super or sub category. In addition you may
simply drag an item to a category to make it a sub category of that
item. Notice this requires that you are currently sorting your categories
alphabetically. See <xref linkend="fig-membergroup-config"/>.</para>

<figure id="fig-membergroup-config">
<title>Categories shown in alphabetical view of the annotation dialog</title>
<mediaobject>
<imageobject>
<imagedata fileref="member-group-setting.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>

</sect1>






  <sect1 id="sect-changing-layout-of-the-property-window">
    <title>Changing layout of the annotation dialog</title>
    <para>It is possible to move the items of the annotation dialog
around, simply from the bar at the top of the frames, and move them around
- you can even make a frame into a top level window on its own.</para>

    <para>Once you have found a layout that works well on your screen,
your usage of &kphotoalbum;, &etc; simply press the <guibutton>Options...</guibutton>
button, that will display a pop-up menu from which you can save the current
window layout.</para>

    <para>You may also choose to hide away a frame, or enable some that
    are not visible by default. You can always
    revert back to the original layout by going through
<guibutton>Options...</guibutton> button, and selecting
<guimenuitem>Reset layout</guimenuitem> from the popup menu. This can be seen in <xref
        linkend="fig-redisplay-frames"/>.</para>


  <figure id="fig-redisplay-frames">
    <title>Showing previously hidden windows.</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="redisplay-frames.png" format="PNG"/>
      </imageobject>
    </mediaobject>
  </figure>

  </sect1>

<sect1>
    <title>Annotating while viewing images</title>
    <para>For a few decades we tagged our images as described above, but in the summer of 2023, it started being possible to tag images while viewing them.
    This facility doesn't support all the features described above, but it offers a much faster workflow to tagging images.</para>
    <para>Missing features when annotating images from the viewer, which you need to come to this dialog for are:</para>
    <itemizedlist>
    <listitem><para>Annotating multiple images at a time</para></listitem>
    <listitem><para>Tagging individual parts of an image (this face is ...)</para></listitem>
    <listitem><para>Setting up tag groups (&ie; specifying that Las Vegas is in USA, so you will see images tagged Las Vegas when watching images from USA)</para></listitem>
    <listitem><para>Setting image dates</para></listitem>
    </itemizedlist>
    <para>
    <link linkend="annotating-from-the-viewer">See the section on annotating from the viewer</link>
    </para>
</sect1>
</chapter>


<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-parent-document: "index.docbook"
End:
-->
