<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY palapeli "<application>Palapeli</application>">
<!ENTITY kappname "&palapeli;">
<!ENTITY package "kdegames">
<!ENTITY % English "INCLUDE">
<!ENTITY % addindex "IGNORE">
]>
<book lang="&language;">
<bookinfo>
<title>The &palapeli; Handbook</title>
<authorgroup>
<author>
<firstname>Stefan</firstname>
<surname>Majewsky</surname>
<affiliation><address><email>majewsky@gmx.net</email></address></affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>2009</year>
<holder>Stefan Majewsky</holder>
</copyright>
<!-- <legalnotice>&FDLNotice;</legalnotice> TODO: FIXME -->
<date>2009-11-09</date>
<releaseinfo>1.0</releaseinfo>
<abstract>
<para>This is the manual for &palapeli;, a jigsaw puzzle game based on &kde; technology.</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>kdegames</keyword>
<keyword>game</keyword>
<keyword>puzzle game</keyword>
<keyword>jigsaw puzzle</keyword>
<keyword>palapeli</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>&palapeli; is a single-player jigsaw puzzle game.</para>
<para>The &palapeli; window is separated into two areas, the puzzle collection and the puzzle table. This manual will now continue with describing these two areas.</para>
</chapter>
<chapter id="collection">
<title>Browsing the puzzle collection</title>
<para>When you launch &palapeli; for the first time, your puzzle collection is preloaded with some default puzzles that come with &palapeli;. Click on one of the puzzles to immediately start playing. Playing takes place on the puzzle table; see <link linkend="puzzletable">the next section</link> for how to use the puzzle table.</para>
<para>Apart from selecting a puzzle, the puzzle collection can be used for the following actions:</para>
<itemizedlist>
<listitem><para><emphasis>create</emphasis> new puzzles from images on your disk</para></listitem>
<listitem><para><emphasis>import</emphasis> puzzles made by others</para></listitem>
<listitem><para><emphasis>export</emphasis> puzzles to share them with your friends and the world</para></listitem>
<listitem><para><emphasis>delete</emphasis> puzzles you do not need any more</para></listitem>
</itemizedlist>
<para>The following section shows how to perform these tasks with the toolbar buttons.</para>
<sect1 id="toolbars-collection">
<title>Toolbar overview</title>
<note><para>You can select puzzles in the puzzle list by pressing &Ctrl; and &LMB; together. Pressing the &LMB; or &RMB; without &Ctrl; opens the specific puzzle in the puzzle table.</para></note>
<variablelist>
<varlistentry>
<term><guiicon>Create new puzzle</guiicon></term>
<listitem>
<para><action>Opens a dialog which allows you to create a puzzle from an image on your disk.</action> Be sure to enter the correct metadata for the image: You should give attribution to the author of the image (⪚ the photographer or the painter); please respect the copyright of the image author.</para>
<para>Also, you will have to select the puzzle type. &palapeli; does not restrict you to classic puzzle pieces, other puzzle types can be easily added by third-party developers. Each puzzle type may offer a set of further properties, such as the piece count.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Delete</guiicon></term>
<listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your library. </action></para><warning><para>This action cannot be undone.</para></warning></listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Import from file</guiicon></term>
<listitem><para><action>When you have received a &palapeli; puzzle file (which can usually be recognized by the file extension <literal role="extension">*.puzzle</literal>), you can use this action to import it into your local collection.</action> Puzzle files can also be played by simply clicking on them in the file manager of your choice, but after the import, the puzzle will appear in your local collection, and you can safely delete the downloaded puzzle file.</para></listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Export to file</guiicon></term>
<listitem><para><action>This will export the currently selected puzzles to files, in order to enable you to give them to your friends, publish them on the web, or make backup copies of your collection.</action></para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="puzzletable">
<title>Playing on the puzzle table</title>
<screenshot><mediaobject>
<imageobject><imagedata fileref="puzzletable1.png" format="PNG"/></imageobject>
<textobject><phrase>The puzzle table (detail)</phrase></textobject>
</mediaobject></screenshot>
<para>The object of the game is to assemble the given pieces to an image.</para>
<para>Pieces can be freely moved by clicking on them and dragging them. When you put one piece near a neighboring piece, both pieces will automatically snap together (1). After having snapped together, pieces cannot be torn apart anymore. Unlike in reality, you cannot combine two pieces that are not true neighbors.</para>
<para>The progress bar below the puzzle table indicates your progress (2). &palapeli; will automatically save your progress after every move, so you'll normally not have to bother about saving.</para>
<para>With the mouse wheel, or with the slider at the bottom right (3), you can change the zoom level of the puzzle table view. By left-clicking and dragging a free area of the puzzle table, you can move the puzzle table view. The same is possible with the right mouse button, but the right mouse button will even work if the mouse cursor is above a puzzle piece.</para>
<para>The movement of the pieces is limited by the <emphasis>puzzle table area</emphasis>. This area is represented on the puzzle table's background by a light rectangular shade. When you move pieces to the border (4) of the puzzle table area, the area will automatically expand to give you more space for moving your puzzle pieces. You can also adjust the puzzle table area by clicking and dragging the area's edges (when the mouse cursor changes to a double-headed arrow).</para>
<para>You can lock the puzzle table area with the small button (5) right next to the progress bar. The shade (4) around the puzzle table will darken, and pieces will now stop to move at the edges of the puzzle table area.</para>
<sect1 id="toolbars-puzzletable">
<title>Toolbar overview</title>
<variablelist>
<varlistentry>
<term><guiicon>Restart puzzle</guiicon></term>
<listitem><para><action>Discards the saved progress for this puzzle.</action></para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="interface">
<title>Interface Overview</title>
<para>&palapeli;'s two areas, the puzzle collection and the puzzle table, are embedded into the menubar as tabs. There are also two menus with standard actions which are described below.</para>
<sect1 id="settings-menu">
<title>The <guimenu>Settings</guimenu> Menu</title>
<variablelist>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show statusbar of puzzle table</guimenuitem></menuchoice></term>
<listitem><para><action>Toggle the display of the progress bar and buttons below the puzzle table.</action> This action will change nothing in the puzzle collection.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
<listitem><para><action>Open a dialog where you can configure the shortcut keys</action> for &palapeli;</para></listitem>
</varlistentry>
<varlistentry id="settings-menu-configure">
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &palapeli;...</guimenuitem></menuchoice></term>
<listitem><para>Open a game configuration dialog. See <link linkend="configuration">Game Configuration</link> section for more details.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="help">
<title>The <guimenu>Help</guimenu> Menu</title>
&help.menu.documentation;
</sect1>
</chapter>
<chapter id="configuration">
<title>Game Configuration</title>
<para>To open the configuration dialog, use the menubar option: <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &palapeli;...</guimenuitem></menuchoice></para>
<variablelist>
<varlistentry>
<term><guilabel>Background</guilabel></term>
<listitem><para><action>Lets you choose another background texture for the puzzle table.</action></para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Snapping precision</guilabel></term>
<listitem><para><action>Lets you choose how near neighbor pieces must be positioned to each other to snap together.</action> If you move the slider more to the right, pieces will snap together even if they are not so close. This makes the game a bit simpler to handle.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><guilabel>Dragging with the left mouse button moves viewport</guilabel></term>
<listitem><para>You can move the puzzle table by clicking anywhere on it with the right mouse button and dragging the mouse. <action>Toggle this configuration option if you want the puzzle table to move also when click the left mouse button and drag the mouse.</action> Note that the left mouse button will only work if your cursor is above the puzzle table background. If a puzzle piece is under the cursor, clicking the left mouse button and dragging will move the puzzle piece.</para></listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter id="credits">
<title>Credits and License</title>
<para>&palapeli; aims to bring the unagitated fun and challenge of jigsaw puzzles to your desktop.</para>
<para>The idea was first developed by Bernhard Schiffner, together with Stefan Majewsky, who is the current lead developer of &palapeli;.</para>
<para>Documentation Copyright 2009 Stefan Majewsky.</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
&underGPL;
</chapter>
<appendix id="installation">
<title>Installation</title>
&install.intro.documentation;
<sect1 id="Compilation">
<title>Compilation and Installation</title>
&install.compile.documentation;
</sect1>
</appendix>
&documentation.index;
</book>
