use const d everywhere

[kdegraphics.git] / doc / kolourpaint / index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kolourpaint;">
  <!ENTITY Clarence.Dang
"<personname><firstname>Clarence</firstname><surname>Dang</surname></personname>">
  <!ENTITY Clarence.Dang.mail "<email>dang@kde.org</email>">
  <!ENTITY Thurston.Dang
"<personname><firstname>Thurston</firstname><surname>Dang</surname></personname>">
  <!ENTITY Thurston.Dang.mail "<email>thurston_dang@users.sourceforge.net</email>">
  <!ENTITY package "kdegraphics">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

<bookinfo>
<title>The &kolourpaint; Handbook</title>

<authorgroup>
<author>
<personname>
<firstname>Thurston</firstname>
<surname>Dang</surname>
</personname>
&Thurston.Dang.mail;
</author>

<othercredit role="reviewer">
<personname>
<firstname>Clarence</firstname>
<surname>Dang</surname>
</personname>
</othercredit>

<othercredit role="reviewer">
&Lauri.Watts;
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2004</year>
<year>2005</year>
<holder>&Thurston.Dang;</holder>
</copyright>

<legalnotice>
&FDLNotice;
</legalnotice>
<date>2005-12-29</date>
<releaseinfo>1.4_relight</releaseinfo>

<abstract>
<para>
&kolourpaint; is a free, easy-to-use paint program for &kde;.
</para>
</abstract>

<keywordset>
<keyword>kolourpaint</keyword>
<keyword>kdegraphics</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<para>&kolourpaint; is a free, easy-to-use paint program for &kde;. It's
perfect for everyday tasks such as:</para>

<itemizedlist>
<listitem>
<para>Painting - drawing diagrams and <quote>finger painting</quote></para>
</listitem>
<listitem>
<para>Image Manipulation - editing screenshots and photos; applying
effects</para>
</listitem>
<listitem>
<para>Icon Editing - drawing clipart and logos with transparency</para>
</listitem>
</itemizedlist>
</chapter>

<chapter id="using-kolourpaint">
<title>Using &kolourpaint;</title>

<para>Click on the following links to explore &kolourpaint;'s
capabilities:</para>

<itemizedlist>
<listitem>
<para><link linkend="tools-chapter">Tools</link></para>
</listitem>
<listitem>
<para><link linkend="working-with-color">Working with Color</link></para>
</listitem>
<listitem>
<para><link linkend="view-options-chapter">View Options</link></para>
</listitem>
<listitem>
<para><link linkend="image-effects-chapter">Image Effects</link></para>
</listitem>
</itemizedlist>
</chapter>

<chapter id="tools-chapter">
<title>Tools</title>

<sect1 id="tool-reference">
<title>Tool Reference</title>

<para>
A quick way to select a tool in &kolourpaint; is to press the single key shortcut associated with it,
documented below and in the <interface>Tool Box</interface> tooltips. You can also hold
<keycombo action="simul">&Alt;&Shift;</keycombo> while pressing the key, which is necessary when you are
writing text (as the single key shortcuts will be disabled). For example, to select the brush, press
<keycombo action="simul">&Alt;&Shift;<keycap>B</keycap></keycombo> or just B (when not writing text).
</para>

<simplelist>
<member><link linkend="tool-brush"><guiicon>
<inlinemediaobject><imageobject><imagedata fileref="tool_brush.png" format="PNG"/>
</imageobject></inlinemediaobject>
</guiicon></link>
<link linkend="tool-brush">Brush</link> (B)</member>

<member><link linkend="tool-eraser-clr"><guiicon>
<inlinemediaobject><imageobject>
<imagedata fileref="tool_color_washer.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-eraser-clr">Color Eraser</link> (O)</member>

<member><link linkend="tool-color-picker"><guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_color_picker.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-color-picker">Color Picker</link> (C)
</member>

<member>
<link linkend="tool-polystar">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_polyline.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-polystar">Connected Lines</link> (N)</member>

<member>
<link linkend="tool-curve">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_curve.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-curve">Curve</link> (V)
</member>

<member>
<link linkend="tool-ellipse">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_ellipse.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-ellipse">Ellipse</link> (E)
</member>

<member>
<link linkend="tool-eraser-std">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_eraser.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-eraser-std">Eraser</link> (A)
</member>

<member>
<link linkend="tool-flood-fill">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_flood_fill.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-flood-fill">Flood Fill</link> (F)
</member>

<member>
<link linkend="tool-line">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_line.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-line">Line</link> (L)
</member>

<member>
<link linkend="tool-pen">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_pen.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-pen">Pen</link> (P)
</member>

<member>
<link linkend="tool-polystar">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_polygon.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-polystar">Polygon</link> (G)
</member>

<member>
<link linkend="tool-rectangles">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_rectangle.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-rectangles">Rectangle</link> (R)
</member>

<member>
<link linkend="tool-rectangles">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_rounded_rectangle.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-rectangles">Rounded Rectangle</link> (U)
</member>

<member>
<link linkend="tool-selections">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_elliptical_selection.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-selections">Selection (Elliptical)</link> (I)
</member>

<member>
<link linkend="tool-selections">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_free_form_selection.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-selections">Selection (Free-Form)</link> (M)
</member>

<member>
<link linkend="tool-selections">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_rect_selection.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-selections">Selection (Rectangular)</link> (S)
</member>

<member>
<link linkend="tool-spraycan">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_spraycan.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-spraycan">Spraycan</link> (Y)
</member>

<member>
<link linkend="tool-text">
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_text.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
</link>
<link linkend="tool-text">Text</link> (T)
</member>
</simplelist>

</sect1>

<sect1 id="tool-brush">
<title>
Brush
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_brush.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>
<para>
Click or click and drag with the brush to draw.
</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata fileref="brush_shapes.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</entry>

<entry>
<para>
Click on one of the shapes to select the brush shape. You can use a
circular, square, slash or backslash brush shape.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color.</para>
</sect1>

<sect1 id="tool-color-picker">
<title>Color Picker <inlinemediaobject>
<imageobject>
<imagedata fileref="tool_color_picker.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>To set the foreground color, <mousebutton>left</mousebutton> click on
a pixel. To set the background color, <mousebutton>right</mousebutton> click on a pixel.
&kolourpaint; will then return to the previously selected tool.</para>

</sect1>

<sect1 id="tool-polystar">
<title>Connected Lines and Polygon
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_polystar.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to draw connected lines. The polygon tool is used in
the same way, however, the start and end points are automatically connected
to form a polygon.</para>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color, and will also reverse the fill color for polygons.</para>

<para>You can <link linkend="tool-options">set the line width</link>. For
polygons, you can also <link linkend="tool-options">set the fill
style</link>.</para>

</sect1>

<sect1 id="tool-curve">
<title>Curve <inlinemediaobject>
<imageobject>
<imagedata fileref="tool_curve.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to draw a line - this sets the start and end
points. You can set up to two control points by dragging. To finish the
curve without using both or any control points, click the other mouse
button. The curve tool draws a Cubic Bezier.</para>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color.</para>

<para>You can also <link linkend="tool-options">set the line
width</link>.</para>

</sect1>

<sect1 id="tool-ellipse">
<title>Ellipse <inlinemediaobject>
<imageobject>
<imagedata fileref="tool_ellipse.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to draw an ellipse.</para>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color, and will reverse the fill color.</para>

<para>You can also <link linkend="tool-options">set the line width and fill
style</link>.</para>

<para>For additional functionality, use the modifier keys:</para>

<itemizedlist>
<listitem>
<para>Hold &Shift; and drag to draw a circle.</para>
</listitem>
<listitem>
<para>To draw an ellipse with a center point of your choice, hold &Ctrl;,
click on the center point, and drag until the ellipse is the correct size
and shape.</para>
</listitem>
<listitem>
<para>To draw a circle with a center point of your choice, hold &Ctrl; and
&Shift;, click on the center point, and drag until the circle is the correct
size.</para>
</listitem>
</itemizedlist>
</sect1>

<sect1 id="tool-erasers">
<!-- This title does not contain the eraser icons because they are present in the
sections; c.f. Connected Lines and Polygon, Rectangles and Selections. -->
<title>Erasers</title>

<sect2 id="tool-eraser-std">
<title>Eraser
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_eraser.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag with the eraser to rub out mistakes.</para>

<note>
<para>Unlike other tools, the erasers draw in the background color. To draw
in the foreground color, use the &RMB;.</para>
</note>

<para>The eraser only has <link linkend="tool-options">square
shapes</link>. To draw with other shapes such as circles use the <link
linkend="tool-brush">Brush</link> and the &RMB;.</para>

<tip>
<para>Double-click on the Eraser icon to clear the entire image. This is
equivalent to using the <link linkend="image-clear">Clear</link> option on
the Image menu.</para>
</tip>

</sect2>

<sect2 id="tool-eraser-clr">
<title>Color Eraser
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_color_washer.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to replace pixels of the foreground color with the
background color. To replace all pixels similar (but not necessarily exactly
equal) to the foreground color, such as in dithered images and photos, use a
<link linkend="color-box">Color Similarity</link> setting other than
Exact.</para>

<note>
<para>Unlike other tools, the erasers draw in the background color. To
replace pixels of the background color with the foreground color, use the
&RMB;.</para>
</note>

<para>You can configure the <link linkend="tool-options">eraser
size</link>.</para>

<tip>
<para>Double-click on the Color Eraser icon to apply it to the entire image.</para>
</tip>
</sect2>

</sect1>

<sect1 id="tool-flood-fill">
<title>Flood Fill
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_flood_fill.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click to fill a region. To fill a dithered region, use a <link
linkend="color-box">Color Similarity</link> setting other than Exact.</para>

<para>The &LMB; fills in the foreground color. The &RMB; fills in the
background color.</para>
</sect1>

<sect1 id="tool-line">
<title>
Line
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_line.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to draw a line.</para>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color.</para>

<para>You can also <link linkend="tool-options">set the line
width</link>.</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="lines_30_deg.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject>
<imagedata fileref="lines_30_45_deg.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject>
<imagedata fileref="lines_45_deg.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<itemizedlist>
<listitem>
<para>Hold &Ctrl; to draw lines angled at the nearest multiple of 30 degrees
- these are the lines in the red diagram.</para>
</listitem>
<listitem>
<para>Hold &Shift; to draw lines angled at the nearest multiple of 45
degrees - these are the lines in the blue diagram.</para>
</listitem>
<listitem>
<para>Hold &Ctrl; and &Shift; to draw lines angled at the nearest multiple
of 30 or 45 degrees - these are the lines in the green diagram.</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="tool-pen">
<title>Pen
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_pen.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click to draw a dot or click and drag to draw a freehand line.</para>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color.  </para>

</sect1>

<sect1 id="tool-rectangles">
<title>Rectangles
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_rectangles.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to draw a rectangle. The Rounded Rectangle is a Rectangle with rounded
corners.</para>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the background color,
and will reverse the fill color.</para>

<para>You can also <link linkend="tool-options">set the line width and fill
style</link>.</para>

<para> For additional functionality, use the modifier keys:</para>

<itemizedlist>
<listitem>
<para>Hold &Shift; and drag to draw a square.</para>
</listitem>
<listitem>
<para>To draw a rectangle with a center point of your choice, hold &Ctrl;,
click on the center point, and drag until the rectangle is the correct size
and shape.</para>
</listitem>
<listitem>
<para>To draw a square with a center point of your choice, hold &Ctrl; and &Shift;,
click on the center point, and drag until the square is the correct size.</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="tool-selections">
<title>Selections
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_selections.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Use the selection tools to draw out the boundary of a
selection.</para>

<para>To move the selection, click and drag on it. The main view will scroll as required to allow you to move the selection to part of the image that is not currently displayed.</para>

<para>
You can free-form <link linkend="image-resize-scale">Resize</link> the entire image or
<link linkend="image-resize-scale">Smooth Scale</link> the selection using the corresponding handles.
Hold &Shift; while free-form scaling the selection to maintain aspect ratio.
The &RMB; invokes a context menu with common <guimenu>Edit</guimenu> commands and <link linkend="image-effects-section">Image Effects</link>.
</para>

<tip>
<para>You can use the cursor keys while drawing out the boundary of the
selection or while moving it.</para>
</tip>

<para>
If you hold &Ctrl; before moving the selection, then you will move a
copy of it. The selection will be smeared when moving it while &Shift; is held.
</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata fileref="selections_opaque_transparent.png"
format="PNG"/>
</imageobject>
</inlinemediaobject>
</entry>
<entry>
<para>There are two selection modes: Opaque (default) and Transparent. If
you use the Transparent selection mode, all pixels of the background color
will be transparent (background subtraction). This allows you to paste a
selection without the background. To perform background subtraction on a
dithered image, use a <link linkend="color-box">Color Similarity</link>
setting other than Exact.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>You can apply Image Effects to a selection - see the <link
linkend="image-effects-section">Image Effects</link> section for more
information.</para>
</sect1>

<sect1 id="tool-spraycan">
<title>Spraycan
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_spraycan.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>Click and drag to spray graffiti. Hold down the mouse button for a
more concentrated spray.</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata fileref="spraycan_patterns.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</entry>
<entry>
<para>Click on one of the shapes to select the spray size. You can select
from spray sizes of 9x9, 17x17 and 29x29.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>The &LMB; draws in the foreground color. The &RMB; draws in the
background color.</para>

</sect1>

<sect1 id="tool-text">
<title>Text
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_text.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</title>

<para>
Click and drag an area in which to write text. Click and drag
on the border to move it. You can resize the text box by dragging on the
handles or by using the <link linkend="image-resize-scale">Resize</link> dialog.
</para>

<tip>
<para>If you have deselected a text box you can use <guimenuitem>Undo</guimenuitem> to edit the text
again.</para>
</tip>

<sect2 id="tool-text-transparent">
<title>Using the Transparent Color</title>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="fcc_std_text.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para>The left picture shows the example image. The right picture shows the addition of text
with opaque foreground and background colors.
</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="fcc_trans_text.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>The left picture shows the addition of text with opaque foreground
colors and a transparent background color.  The right picture shows the
addition of text with a transparent foreground color and opaque background
color.</para>
</sect2>
</sect1>

<sect1 id="tool-options">
<title>Common Tool Options</title>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata fileref="eraser_shapes.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</entry>
<entry>
<para>Click on one of the squares to select the eraser size. You can select
from squares of side length 2, 3, 5, 9, 17 and 29 pixels.</para>

<para>The eraser size setting affects the <link
linkend="tool-erasers">Erasers</link>.</para>
</entry>
</row>
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata fileref="line_width.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</entry>
<entry>
<para>Click on one of the lines to select the line width. You can select
from line widths of 1, 2, 3, 5 and 8 pixel(s).</para>

<para>The line width setting affects the <link
linkend="tool-polystar">Connected Lines</link>, <link
linkend="tool-curve">Curve</link>, <link
linkend="tool-ellipse">Ellipse</link>, <link
linkend="tool-line">Line</link>, <link
linkend="tool-polystar">Polygon</link>, <link
linkend="tool-rectangles">Rectangle</link> and <link
linkend="tool-rectangles">Rounded Rectangle</link> tools.  </para>
</entry>
</row>
<row>
<entry>
<inlinemediaobject>
<imageobject>
<imagedata fileref="fill_style.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</entry>
<entry>
<para>Click on one of the rectangles to select the fill style. You can
select from No Fill, Fill with Background Color and Fill with Foreground
Color.</para> <para>The fill style setting affects the <link
linkend="tool-ellipse">Ellipse</link>, <link
linkend="tool-polystar">Polygon</link>, <link
linkend="tool-rectangles">Rectangle</link> and <link
linkend="tool-rectangles">Rounded Rectangle</link> tools.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</sect1>
</chapter>

<chapter id="working-with-color">
<title>Working with Color</title>

<sect1 id="color-box">
<title>The Color Box</title>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="color_box.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Color Box</phrase>
</textobject>
</inlinemediaobject>
</para>

<para>The Color Box has 3 main sections: the Color Tablet, the Color Palette
and the Color Similarity Selector.</para>

<para>The Color Tablet shows the current foreground color as a square on top
of another square representing the current background color. When drawing
with the &LMB;, the foreground color is used, and when drawing with the
&RMB; the background color is used (except for the <link
linkend="tool-erasers">Erasers</link>).  You can click on the double-ended
arrow to swap the foreground and background colors.  </para>

<para>The Color Palette shows a selection of colors for you to choose
from. The translucent pyramid represents the transparent color. Left-click
on a color to set the foreground color and right-click on a color to set the
background color. You can also drag and drop any opaque color into the Color
Tablet squares. To edit a color in the Color Tablet or Palette, double-click
on it. The <link linkend="tool-color-picker">Color Picker</link> tool allows
you to select a color from the image.  </para>

<para>Color Similarity allows you to work more effectively with dithered
images and photos, in a comparable manner to the <quote>Magic Wand</quote> feature of other paint programs. It applies to transparent selections, as well as the
<link linkend="tool-flood-fill">Flood Fill</link>, <link
linkend="tool-eraser-clr">Color Eraser</link> and <link
linkend="image-autocrop">Autocrop / Remove Internal Border</link> tools. Double-click on the Color
Similarity Selector to choose how similar colors must be to be considered
identical. When using selections in Transparent mode, any color in the
selection that is similar to the background color will also be made
transparent.</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="fill_color_similarity.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
The left picture shows the example image. The right pictures demonstrate the use of a flood fill, with Color Similarity settings of 5%, 15% and 30%. In this example, with a Color Similarity setting of <guilabel>Exact</guilabel>, a flood fill at (80, 100) would only fill one pixel, as the surrounding pixels are similar but not identical. As Color Similarity is increased, more pixels that are similar in color are considered identical, hence the fill extends further.
</para>

</sect1>
</chapter>

<chapter id="view-options-chapter">
<title>View Options</title>

<sect1 id="view-options-section">
<title>View Options Reference</title>

<para><link linkend="view-zoom">Zoom incorporating the Grid</link></para>
<para><link linkend="view-thumbnail">Thumbnail</link></para>

</sect1>

<sect1 id="view-zoom">
<title>Zoom incorporating the Grid</title>
<para>Increase the zoom level to edit images with more precision, or reduce it to see more of the image.</para>

<important>
<para>
At zoom levels that aren't multiples of 100%, parts of the image may appear to move when the user interacts with it.  Other minor redraw glitches may also occur at such zoom levels.
</para>
</important>

<para>At zoom levels of 600% or greater that are also multiples of 100%, you can <guimenuitem>Show Grid</guimenuitem> to more accurately edit individual pixels.</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="tool_text.png" format="PNG"/>
</imageobject>
</inlinemediaobject>

<inlinemediaobject>
<imageobject>
<imagedata fileref="text_zoom_grid.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>The first picture shows the <link linkend="tool-text">Text</link> tool icon, while the latter shows it at 600% zoom with the grid on.</para>

<tip>
<para>
Another way of zooming when not drawing is to scroll the <mousebutton>wheel</mousebutton> while holding &Ctrl;.
</para>
</tip>

</sect1>

<sect1 id="view-thumbnail">
<title>Thumbnail</title>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="view_thumbnails.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para>
If <guimenuitem>Zoomed Thumbnail Mode</guimenuitem> is selected, the entire image is displayed, scaled as required to fit the thumbnail window (top-right picture).
</para>
<para>
Otherwise, the thumbnail displays as much of the image as possible, starting from the top-left of the main view (bottom-right picture).
</para>
</sect1>

</chapter>

<chapter id="image-effects-chapter">
<title>Image Effects</title>

<sect1 id="image-effects-section">
<title>Image Effects Reference</title>
<para><link linkend="image-autocrop">Autocrop / Remove Internal Border</link></para>
<para><link linkend="image-balance">Balance</link></para>
<para><link linkend="image-clear">Clear</link></para>
<para><link linkend="image-emboss">Emboss</link></para>
<para><link linkend="image-flatten">Flatten</link></para>
<para><link linkend="image-flip">Flip</link></para>
<para><link linkend="image-invert">Invert</link></para>
<para><link linkend="image-reduce-colors">Reduce Colors</link></para>
<para><link linkend="image-grayscale">Reduce to Grayscale</link></para>
<para><link linkend="image-monochrome">Reduce to Monochrome (Dithered)</link></para>
<para><link linkend="image-resize-scale">Resize / Scale</link></para>
<para><link linkend="image-rotate">Rotate</link></para>
<para><link linkend="image-set-as-image">Set as Image (Crop)</link></para>
<para><link linkend="image-skew">Skew</link></para>
<para><link linkend="image-soften-sharpen">Soften &amp; Sharpen</link></para>
<para><link linkend="image-more-effects">More Effects</link></para>
<para><link linkend="image-notes">Notes</link></para>
</sect1>

<sect1 id="image-autocrop">
<title>Autocrop / Remove Internal Border</title>

<para>This automatically removes the border of an image or selection. Use
Autocrop if you have a figure that does not fill the entire image or selection and you
wish to remove the excess whitespace. To use this feature with a dithered
image border, you will also need to use <link linkend="color-box">Color
Similarity</link>.</para>

</sect1>

<sect1 id="image-balance">
<title>Balance</title>

<para>
This feature is accessible from the <link linkend="image-more-effects">More Effects</link> dialog.
</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_balance.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>This allows you to set the brightness, contrast and gamma of the image or selection.
</para>

<note>
<para>
The more common measure of gamma (a decimal from 0.10 to 10.00) is located between the
<guilabel>Gamma</guilabel> spinbox and the <guibutton>Reset</guibutton> button.
</para>
</note>
</sect1>

<sect1 id="image-clear">
<title>Clear</title>

<para>This fills the entire image or selection with the background
color.</para>

<tip>
<para>Double-click on the <link linkend="tool-eraser-std">Eraser</link>
icon to clear the entire image.</para>
</tip>

</sect1>

<sect1 id="image-emboss">
<title>Emboss</title>

<para>
This feature is accessible from the <link linkend="image-more-effects">More Effects</link> dialog.
</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_emboss.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
Check <guilabel>Enable</guilabel> to apply the Emboss effect. This emphasises the edges and gives the
image or selection an &quot;engraved look&quot;.
</para>
</sect1>

<sect1 id="image-flatten">
<title>Flatten</title>

<para>
This feature is accessible from the <link linkend="image-more-effects">More Effects</link> dialog.
</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_flatten.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
This recolors the image with varying shades of the two selected colors.
</para>
</sect1>

<sect1 id="image-flip">
<title>Flip</title>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_flip.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>This flips the entire image or selection horizontally or
vertically.</para>

</sect1>

<sect1 id="image-invert">
<title>Invert</title>

<para>
This feature is accessible from the <link linkend="image-more-effects">More Effects</link> dialog.
</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_invert.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>This allows you to invert one or more RGB channels in the image or selection. Select <guilabel>All</guilabel> to change a photo into a negative and vice versa. This generally looks quite funny.</para>

<tip>
<para>To quickly invert all channels, you do not need to use this dialog. You can instead
access the <guimenuitem>Invert Colors</guimenuitem> item in the <guimenu>Image</guimenu> or
<guimenu>Selection</guimenu> menu.
</para>
</tip>

</sect1>

<sect1 id="image-reduce-colors">
<title>Reduce Colors</title>

<para>
This feature is accessible from the <link linkend="image-more-effects">More Effects</link> dialog.
</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_reduce_colors.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
This reduces the number of colors used by the image or selection, with or without dithering.
</para>

<para>
Dithering generally provides better quality results, however, you may wish to disable it for artistic effects;
<abbrev>e.g.</abbrev> using <guilabel>Monochrome</guilabel> instead of
<guilabel>Monochrome (Dithered)</guilabel> gives a silhouette effect.
</para>

<para>
Another important distinction is that while <guilabel>Monochrome (Dithered)</guilabel> will always reduce the entire image or selection to black and white, <guilabel>Monochrome</guilabel> will do this only if the image or selection contains more than 2 colors.
</para>

<tip>
<para>For a quick, dithered monochrome image or selection, use the <link linkend="image-monochrome">Reduce to Monochrome (Dithered)</link> item of the <guimenu>Image</guimenu> or <guimenu>Selection</guimenu> menu.
</para>
</tip>

<note>
<para>
Changing the number of colors here has no effect on the color depth of the file format. If you want to
change the color depth, you should select it in the file saving dialogs. Note that, confusingly, changing
the color depth also changes the number of colors.
</para>
</note>
</sect1>

<sect1 id="image-grayscale">
<title>Reduce to Grayscale</title>

<para> This reduces the entire image or selection to grayscale.</para>

</sect1>

<sect1 id="image-monochrome">
<title>Reduce to Monochrome (Dithered)</title>

<para>This reduces the entire image or selection to black and white.</para>

<tip>
<para>
If you do not want the image or selection to be dithered, use the <link linkend="image-reduce-colors">
Reduce Colors</link> dialog.
</para>
</tip>
</sect1>

<sect1 id="image-resize-scale">
<title>Resize / Scale</title>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_resize_scale.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>Resizing the image changes the dimensions of the image without
applying a transformation to the existing contents. Scaling the image will
stretch the existing contents to the new dimensions. <guibutton>Smooth Scale</guibutton>
generally provides better quality results than Scaling, by blending neighbouring colors.</para>

<para>You can express the new dimensions in pixels, or as a percentage of
the original size. If you select <guilabel>Keep aspect ratio</guilabel>, the
width and height will be scaled by the same percentage.</para>

<tip>
<para>
You can free-form <guibutton>Resize</guibutton> the entire image or <guibutton>Smooth Scale</guibutton> the selection using the corresponding handles.
</para>
</tip>

<note>
<para>Only scaling is supported for selections, and only resizing is
supported for text boxes. See <link linkend="image-notes">Notes</link> for
additional details about applying these effects.</para>
</note>
</sect1>

<sect1 id="image-rotate">
<title>Rotate</title>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_rotate.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>This rotates the image. You can specify the angle and direction of
rotation.</para>

<tip>
<para>You can reverse the direction of rotation by specifying a negative
custom angle.</para>
</tip>

<note>
<para>See <link linkend="image-notes">Notes</link> for details about
applying this effect to a selection.
</para>
</note>
</sect1>

<sect1 id="image-set-as-image">
<title>Set as Image (Crop)</title>

<para>This will set the selection as the image.</para>

<note>
<para>This is only available when you have an active selection.</para>
</note>
</sect1>

<sect1 id="image-skew">
<title>Skew</title>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_skew.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>This skews the entire image or selection horizontally and/or
vertically.</para>

<note>
<para>See <link linkend="image-notes">Notes</link> for details about
applying this effect to a selection.</para>
</note>
</sect1>

<sect1 id="image-soften-sharpen">
<title>Soften &amp; Sharpen</title>

<para>
This feature is accessible from the <link linkend="image-more-effects">More Effects</link> dialog.
</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image_soften_sharpen.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
Use this effect to soften or sharpen the image.
</para>
</sect1>

<sect1 id="image-more-effects">
<!-- More Effects is left at the end because it is not part of the Image Effects Reference - if a
user selects the next page, the next page should be Autocrop / Remove Internal Border. -->
<title>More Effects</title>

<para>
This dialog contains the <link linkend="image-balance">Balance</link>,
<link linkend="image-emboss">Emboss</link>, <link linkend="image-flatten">Flatten</link>,
<link linkend="image-invert">Invert</link>, <link linkend="image-reduce-colors">Reduce Colors</link>
and <link linkend="image-soften-sharpen">Soften &amp; Sharpen</link> features.
</para>
</sect1>

<sect1 id="image-notes">
<title>Notes</title>

<para><link linkend="image-resize-scale">Resizing / Scaling</link>, <link
linkend="image-rotate">Rotating</link> and <link
linkend="image-skew">Skewing</link> may change the dimensions of the
image. You can view the new dimensions in the dialog.</para>

<para>If you apply these effects to an image, the image will be resized if
necessary. However, if you apply these effects to a selection, the image
will not be resized, even if the transformed selection does not fit.</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="rotate_image_30.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
The left image has been rotated 30 degrees clockwise to form the right image. &kolourpaint; has
automatically enlarged the image to accommodate the larger contents.
</para>

<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="rotate_selection_30.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>

<para>
The left <emphasis>selection</emphasis> has been rotated 30 degrees clockwise to form the right
selection. The image size has remained the same, hence parts of the selection will not be visible
without <link linkend="image-resize-scale">Resizing</link> the <emphasis>image</emphasis>.
</para>
</sect1>

</chapter>

<chapter id="credits">
<title>Credits and License</title>
<epigraph>
<attribution>Carl Tucker</attribution>
<para>
It might not be concise documentation; it might not be complete documentation; but it is
honest documentation.
</para>
</epigraph>

<para>
&kolourpaint;
</para>
<para>Program Copyright &copy; 2003, 2004, 2005 &Clarence.Dang; &Clarence.Dang.mail;</para>

<para>
&kolourpaint;-specific icons Copyright &copy; 2004, 2005
Kristof Borrey <email>borrey@kde.org</email>,
Nuno Pinheiro <email>nf.pinheiro@gmail.com</email>,
&Danny.Allen; <email>dannya40uk@yahoo.co.uk</email>
</para>

<para>Documentation and additional documentation artwork Copyright &copy; 2004, 2005
&Thurston.Dang; &Thurston.Dang.mail;</para>

<para>Portions reproduced with permission from <ulink
url="http://kolourpaint.sourceforge.net/"></ulink>.</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;

<para>This program is licensed as follows:</para>

<para>Copyright &copy; 2003, 2004, 2005 &Clarence.Dang; &Clarence.Dang.mail;</para>

<literallayout>
All rights reserved.


Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.


THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS&apos;&apos; AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</literallayout>
</chapter>

<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-kapp">
<title>How to obtain &kolourpaint;</title>

&install.intro.documentation;

<para>More frequent releases with support for previous versions of &kde; are
available at <ulink
url="http://kolourpaint.sourceforge.net/">http://kolourpaint.sourceforge.net/</ulink>.</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para> &kolourpaint; 1.4_relight requires &kde; 3.5.</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<note>
<para>
If you are reading this help in the &khelpcenter;, then &kolourpaint; has already been
installed on this system and you do not need to follow these generic instructions.
</para>
</note>

&install.compile.documentation;

</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>&kolourpaint; should run without any additional configuration.</para>
</sect1>

</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
-->