<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its" type="task" style="task"
      id="tools_classic">

  <info>
    <link type="guide" xref="index#tools"/>
    <include xmlns="http://www.w3.org/2001/XInclude" href="legal.xml"/>
    <credit type="author">
      <name>Romain F. T.</name>
      <email its:translate="no">rrroschan@gmail.com</email>
    </credit>
    <desc>Draw with simple tools</desc>
  </info>

  <title>Classic tools</title>

  <p>Draw on the image with the color and options you selected!</p>

  <section>
    <title>Color and size</title>

    <p>The options for the tool you're using are located at the right of the
    bottom bar: there are two colors, the tool size, and a menu (whose content
    changes depending on the tool).</p>
    <p>The color of the left button corresponds to the left click, and is
    labeled "Main color", while the color at the right is the "Secondary color".
    Click on these buttons to change their respective colors:</p>

    <table rules="colgroups">
      <!-- Unusual width because the pics are in a table, side-by-side, with -->
      <!-- different aspect ratios. -->
      <tr>
        <td>
          <media type="image" mime="image/png" width="100%" its:translate="no"
                 src="figures/screenshot_color_palette.png" />
        </td>
        <td>
          <media type="image" mime="image/png" width="60%" its:translate="no"
                 src="figures/screenshot_color_editor.png" />
        </td>
      </tr>
    </table>

    <note style="tip">
      <p>If the exact color you want isn't listed in the palette (picture at the
      left), click the <gui style="button">+</gui> button to use the color
      editor (picture at the right).</p>
    </note>

    <p><em>With compatible tools</em>, you can select at the top of the palette
    the way the color will be applied to the image:</p>
    <list>
      <item>
        <p>Normal: the selected color is added over the existing image. If your
        color is semi-transparent yellow and your image is opaque blue, the
        resulting pixels would be opaque green.</p>
      </item>
      <item>
        <p>Raw source color: the selected color replaces the pixels where it's
        applied. If your color is semi-transparent yellow, the resulting pixels
        would be semi-transparent yellow.</p>
      </item>
      <item>
        <p>Highlight: the selected color is added to the lighter pixels only,
        which highlights dark text on light background.</p>
      </item>
      <item>
        <p>Difference: the resulting color is the difference between the
        selected color and the existing pixels.</p>
      </item>
      <item>
        <p>Photo-oriented mode: these options don't make much sense when you're
        drawing something, but they can help you when editing photos.</p>
        <note style="advanced">
          <p>The idea is to apply <em>only</em> a dimension of the current color
          in the hue-saturation-luminosity representation, and not the other
          ones.</p>
        </note>
        <p>For example, you can draw with a red hue but not affect the
        luminosity of the existing pixels; or draw with a light luminosity but
        not affect the hue of the existing pixels.</p>
        <media type="image" mime="image/png" width="80%" its:translate="no"
               src="figures/screenshot_hsl.png" />
      </item>
      <item>
        <p>Blur: blurs the hovered pixels regardless of the selected color. The
        quality of this blur is far behind the blurring you can get using the
        <link xref="tools_transform#filters">"Filters" tool</link>.</p>
      </item>
      <item>
        <p>Erase: deletes any color where the tool is applied.</p>
        <note style="tip">
          <p>The same result can be achieved used the <link xref="preferences#tools">
          optional</link> <gui style="menuitem">Eraser</gui> tool.</p>
        </note>
      </item>
    </list>
    <note style="warning">
      <p>Not all tools are compatible with these color application modes!</p>
    </note>

    <p>An <link xref="preferences#tools">optional</link> <gui style="button">
    Color Picker</gui> tool can also help you to select a color.
    While the color picker from within the color editor can select a RGB color
    anywhere on the screen, the <gui style="menuitem">Color Picker</gui> tool
    support translucent colors but only works for pixels from the image.</p>
  </section>

  <section>
    <title>Draw things</title>

    <p>Aside of the colors, most options for these tools concern the ends of the
    line: it can be thin, rounded or square. You can also draw dashed lines.</p>
    <list>
      <item>
        <p>Pencil: The pencil draws following the pointer, and according to the
        chosen color.</p>
        <note style="tip">
          <p>Using the "eraser" mode from the color menu, the pencil can delete
          all existing colors. Using the "highlight" mode and a semi-transparent
          color, it can also highlight text. For this reason, the two next tools
          are <link xref="preferences#tools">disabled by default</link>.</p>
        </note>
      </item>
      <item>
        <p>Eraser: Ignore the current color settings and just erase to get fully
        transparent pixels.</p>
      </item>
      <item>
        <p>Highlighter: Ignore some of the color settings, and draw with a
        semi-transparent version of the current color.</p>
        <p>The "highlight" color application mode is used, so the selected color
        is added to the lighter pixels only, which highlights dark text on light
        background. An option can be used to do the opposite (highlight light
        text on dark background).</p>
      </item>
      <item>
        <p>Line: This tool can draw straight lines. Its options also include
        ending the line with an arrow, and using a gradient from the main color
        to the secondary color.</p>
        <note style="tip">
          <p>You can use the "blur" mode from the color menu to hide text!</p>
        </note>
      </item>
      <item>
        <p>Curve: This tool can draw Bézier curves, optionally with an arrow at
        the end. Two clicks are required, if you only click once to draw a
        straight line, that line is drawn temporarily until a second click.</p>
        <media type="image" mime="image/png" width="80%" its:translate="no"
               src="figures/screenshot_arrow.png" />
      </item>
    </list>
  </section>

  <section>
    <title>Insert text</title>

    <p>With the <gui style="menuitem">Text</gui> tool, you can insert text on
    the image. A few formatting options are available in the options menu, such
    as "italic", "bold", or a basic font family selection.</p>

    <p>For better contrast, the text can be displayed on a rectangle background,
    or with a shadow, or with an outline. The color of this background is the
    secondary color you chose.</p>

    <media type="image" mime="image/png" width="80%" its:translate="no"
           src="figures/screenshot_text.png" />

    <note style="tip">
      <p>Don't forget to confirm the insertion using the <gui style="button">
      Insert here</gui> button.</p>
    </note>

    <p>An optional tool named <gui style="menuitem">Points</gui> is designed to
    help you captioning pictures: you can add numbered round dots or crosses to
    elements of the picture.</p>
  </section>

  <section>
    <title>Fill an area</title>

    <p>To paint an area using a given color, several tools can be used:</p>

    <list>
      <item>
        <p>Shapes. Available shapes include rectangle, rounded rectangle, oval,
        circle, polygon, and free shape.</p>
        <p>Polygons and free shapes are drawn in several clicks. To close them,
        do a last click at the position where you began the shape, or use
        the <gui style="menuitem">Close shape</gui> menu item.</p>
        <p>Various filling options are available (using a plain color, or a
        gradient, or nothing), as well as outline options (using a plain
        outline, dashes, or nothing).</p>
      </item>
      <item>
        <p>Paint. This tool tries to paint an area of a given color with a new
        color.</p>
        <note style="warning">
          <p>This tool is disabled by default, because it will not work if the
          shape to paint is too complex.</p>
        </note>
        <p>It can use several possible algorithms: <gui style="menuitem">
        Encircle and fill</gui> is very simplistic and discouraged,
        <gui style="menuitem">Erase and replace</gui> should work better, but
        still fails in a few situations.</p>
        <p>The <gui style="menuitem">Entire image</gui> option paints over the
        the entire image, regardless of what's already drawn.</p>
        <p><gui style="menuitem">Erase color</gui> doesn't paint but erase the
        color you clicked, on the entire image, for example to cut out an image
        from its white background.</p>
      </item>
    </list>
  </section>

  <section>
    <title>See also</title>

    <p>The <link xref="tools_selection">selection tools</link> don't draw, but
    their capabilities are very powerful and useful for any image editing.</p>

    <p>Use these special tools to <link xref="tools_transform">transform the
    canvas or the selected area</link>.</p>
  </section>

</page>

