Skip to content

GitLab

Commit 4e5ec499 authored by Antoni Bella Pérez's avatar Antoni Bella Pérez 🚵🏻
Browse files

Documentation updates 

* Update date and version numbers
* Remove final whitespaces
* Identation fixes
* A strong revision
* Suitable tags, punctuation and some improves
* Add tolbar icons
parent e06dfa05
Pipeline #86978 passed with stage
in 1 minute and 4 seconds
Hide whitespace changes
Inline Side-by-side
doc/index.docbook
View file @ 4e5ec499
......@@ -9,847 +9,852 @@
]>
<book id="palapeli" lang="&language;">
<bookinfo>
<title>The &palapeli; Handbook</title>
<authorgroup>
<author>
<firstname>Johannes</firstname>
<surname>L&#xF6;hnert</surname>
<affiliation><address><email>loehnert_kde@gmx.de</email></address></affiliation>
</author>
<author>
<firstname>Stefan</firstname>
<surname>Majewsky</surname>
<affiliation><address><email>majewsky@gmx.net</email></address></affiliation>
</author>
<author>
<firstname>Ian</firstname>
<surname>Wadham</surname>
<affiliation><address><email>iandw.au@gmail.com</email></address></affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<bookinfo>
<title>The &palapeli; Handbook</title>
<authorgroup>
<author>
<firstname>Johannes</firstname>
<surname>L&#xF6;hnert</surname>
<affiliation><address><email>loehnert_kde@gmx.de</email></address></affiliation>
</author>
<author>
<firstname>Stefan</firstname>
<surname>Majewsky</surname>
<affiliation><address><email>majewsky@gmx.net</email></address></affiliation>
</author>
<author>
<firstname>Ian</firstname>
<surname>Wadham</surname>
<affiliation><address><email>iandw.au@gmail.com</email></address></affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>2009, 2010</year>
<holder>Johannes L&#xF6;hnert, Stefan Majewsky</holder>
</copyright>
<copyright>
<year>2014</year>
<holder>Ian Wadham</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>2014-03-09</date>
<releaseinfo>2.0 (&kde; 4.13)</releaseinfo>
<copyright>
<year>2009, 2010</year>
<holder>Johannes L&#xF6;hnert, Stefan Majewsky</holder>
</copyright>
<copyright>
<year>2014</year>
<holder>Ian Wadham</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>2021-10-06</date>
<releaseinfo>2.1 (KDE Gear 21.08)</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>
<abstract>
<para>This is the manual for &palapeli;, a jigsaw puzzle game.</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. With it you can create and play puzzles ranging from 4 to 10,000 pieces. This version includes facilities to assist in solving large puzzles (300 pieces or more) within the size limits of a computer screen.</para>
<para>The main &palapeli; window is separated into two areas, the puzzle collection and the puzzle table.</para>
<para>This manual continues by describing those two areas.</para>
</chapter>
<chapter id="introduction">
<title>Introduction</title>
<para>&palapeli; is a single-player jigsaw puzzle game. With it you can create and play puzzles ranging from 4 to 10,000 pieces. This version includes facilities to assist in solving large puzzles (300 pieces or more) within the size limits of a computer screen.</para>
<para>The main &palapeli; window is separated into two areas, the puzzle collection and the puzzle table.</para>
<para>This manual continues by describing those two areas.</para>
</chapter>
<chapter id="collection">
<title>Browsing the puzzle collection</title>
<sect1 id="play-maintain-collection">
<title>Playing puzzles and updating the collection</title>
<para>When you launch &palapeli; for the first time, your puzzle collection already contains some sample puzzles that come with &palapeli;. Click on one of them to start playing immediately. Later, when you have created some of your own puzzles (see below), you can also click on them to start playing.</para>
<para>Play takes place on the puzzle table; see <link linkend="puzzletable">the section after next</link> for how to use the puzzle table.</para>
<note><para>You can select and highlight puzzles in the puzzle list by pressing &Ctrl; and &LMB; together. Pressing the &LMB; or &RMB; without &Ctrl; opens that puzzle for playing in the puzzle table.</para>
<para>On Apple OS X you need to double-click the &LMB; to begin playing. A single click will just select and highlight one entry in the puzzle list.</para></note>
<para>As well as playing a puzzle, you can use the puzzle collection 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>
<sect1 id="toolbar-collection">
<title>Toolbar overview</title>
<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> See <link linkend="create-puzzles">the next chapter</link> for details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Delete puzzle</guiicon></term>
<listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your collection. </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="collection">
<title>Browsing the puzzle collection</title>
<sect1 id="play-maintain-collection">
<title>Playing puzzles and updating the collection</title>
<para>When you launch &palapeli; for the first time, your puzzle collection already contains some sample puzzles that come with &palapeli;. Click on one of them to start playing immediately. Later, when you have created some of your own puzzles (see below), you can also click on them to start playing.</para>
<para>Play takes place on the puzzle table; see <link linkend="puzzletable">the section after next</link> for how to use the puzzle table.</para>
<note><para>You can select and highlight puzzles in the puzzle list by hold the &Ctrl; key and click with the &LMB;. Pressing the &LMB; or &RMB; without the &Ctrl; key opens that puzzle for playing in the puzzle table.</para>
<para>On &macOS; you need to double-click with the &LMB; to begin playing. A single click will just select and highlight one entry in the puzzle list.</para></note>
<para>As well as playing a puzzle, you can use the puzzle collection 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 icons.</para>
</sect1>
<sect1 id="toolbar-collection">
<title>Toolbar overview</title>
<variablelist>
<varlistentry>
<term><inlinemediaobject><imageobject><imagedata fileref="tools-wizard.png" format="PNG"/></imageobject></inlinemediaobject> <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> See <link linkend="create-puzzles">the next chapter</link> for details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><inlinemediaobject><imageobject><imagedata fileref="edit-delete.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Delete Puzzle</guiicon></term>
<listitem><para><action>Any puzzles that you have selected in the puzzle list, will be permanently deleted from your collection. </action></para><warning><para>This action cannot be undone.</para></warning></listitem>
</varlistentry>
<varlistentry>
<term><inlinemediaobject><imageobject><imagedata fileref="document-import.png" format="PNG"/></imageobject></inlinemediaobject> <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><inlinemediaobject><imageobject><imagedata fileref="document-export.png" format="PNG"/></imageobject></inlinemediaobject> <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="create-puzzles">
<title>Creating new puzzles</title>
<sect1 id="creation-dialog">
<title>The puzzle creation dialog</title>
<para>As described in <link linkend="toolbar-collection">the previous section</link>, you can create new puzzles by clicking on the <guiicon>Create new puzzle</guiicon> button in the puzzle collection window.</para>
<para>Clicking this button opens the puzzle creation dialog, which consists of three pages:</para>
<procedure>
<step><para>On the first page, select an image file which will be sliced into pieces. Be sure to enter the correct metadata for the image: You should give attribution to the author of the image (&eg; the photographer or the painter); please respect the copyright of the image author.</para></step>
<step><para>On the second page, you can select the type of pieces into which the image will be sliced. &palapeli; comes with a collection of slicers preinstalled, but third-party slicers may also be available.</para></step>
<step><para>On the final page of the dialog, the selected slicer can be customized &eg; by choosing a different piece count or by adjusting parameters of the piece shape. The available set of options depends which slicer has been selected.</para></step>
</procedure>
<para>This manual will continue to discuss the slicers which come with &palapeli;. If you have downloaded a third-party slicer plugin for &palapeli;, please refer to the documentation of this plugin if you have trouble installing or using it on your system.</para>
</sect1>
<sect1 id="simple-slicers">
<title>Simple slicers</title>
<para>&palapeli; has two simple slicers, <quote>Classic jigsaw pieces</quote> and <quote>Rectangular pieces</quote>. These slicers create simple rectangular pieces either with or without connecting plugs.</para>
<para>Both slicers allow the piece count and the aspect ratio to be adjusted. Dragging the aspect ratio slider to the left results in tall pieces, adjusting it to the right produces wide pieces. The default selection produces approximately square pieces.</para>
</sect1>
<sect1 id="psc">
<title>The advanced &i18n-psc;</title>
<para>The &i18n-psc; produces realistic jigsaw pieces with various basic patterns:</para>
<variablelist>
<varlistentry>
<term>Rectangular grid</term>
<listitem><para>Contains the well-known rectangular pieces.</para></listitem>
</varlistentry>
<varlistentry>
<term>Cairo grid</term>
<listitem><para>With its pentagonal pieces and unequal edge angles, it's rather hard to puzzle because the pieces fit together in an unfamiliar manner.</para></listitem>
</varlistentry>
<varlistentry>
<term>Hexagonal grid</term>
<listitem><para>Produces hexagonal pieces, arranged like honeycomb cells.</para></listitem>
</varlistentry>
<varlistentry>
<term>Rotrex grid</term>
<listitem><para>Through a special composition of triangular, hexagonal and rectangular pieces, the pieces form a pattern resembling to many intersecting circles.</para></listitem>
</varlistentry>
<varlistentry>
<term>Irregular grid</term>
<listitem><para>This grid is available only if you have installed <application>qvoronoi</application> from the <ulink url="http://www.qhull.org"><application>qhull</application> package</ulink>. <application>qvoronoi</application> is used to calculate irregular piece shapes from randomly placed points.</para></listitem>
</varlistentry>
</variablelist>
<para>The &i18n-psc; has various parameters which control the appearance of the piece edges, especially the plugs on them. Default settings are provided for all of these parameters. An additional preset mode is available which reduces the amount of parameters to a bare minimum. The following parameters are available usually:</para>
<variablelist>
<varlistentry>
<term>Approx. piece count</term>
<listitem><para><!--FIXME add missing description here--></para></listitem>
</varlistentry>
<varlistentry>
<term>Flipped edge percentage</term>
<listitem><para>The probability for each plug to be flipped. A plug is considered flipped if it points in the opposite direction as it would in a fully regular grid. On the rectangular grid, this results in pieces with 3 or 4 plugs pointing inwards resp. outwards. Position the slider at the very left to obtain the normal fully regular grid. In the middle, plug orientation is random. At the right, the grid is fully regular again, but with an <quote>alternate</quote> rule. This does <emphasis>not</emphasis> mean reversal of all plugs: In the alternate regular grid, for instance, each piece has four inward-pointing or four outward-pointing plugs. This setting has no effect in the irregular grid.</para></listitem>
</varlistentry>
<varlistentry>
<term>Edge curviness</term>
<listitem><para>Determines how curvy the edges are, &ie; how strongly the borders dent in or bulge out. Move the slider to the very left to obtain straight edge lines (except for the plugs).</para></listitem>
</varlistentry>
<varlistentry>
<term>Plug size</term>
<listitem><para>Determines the size of the plug part of each edge. The default setting (middle position of the slider) is chosen to look like a real puzzle. The slider ranges from 50% to 150% this size, which already looks obscenely large. The program tries very hard to avoid collisions between plugs. Colliding edges are reshaped multiple times and shrinked in small steps. However there still remain cases where no solution can be found, especially for large plug sizes.</para></listitem>
</varlistentry>
<varlistentry>
<term>Diversity of curviness</term>
<listitem><para>Determines how much the curviness (see above) varies between edges. Move the slider to the left to make the dents and bulges look all the same. At the right, there may occur very curvy and very straight borders.</para></listitem>
</varlistentry>
<varlistentry>
<term>Diversity of plug position</term>
<listitem><para>Determines how much the position of the plug on the edge varies. At the very left, plugs are affixed to the middle of their edge.</para></listitem>
</varlistentry>
<varlistentry>
<term>Diversity of plugs</term>
<listitem><para>Determines how individual the plugs look like. At the very left, plugs look all the same. At the very right, each plug will be a unique piece of art crafted especially for you.</para></listitem>
</varlistentry>
<varlistentry>
<term>Irr.: Diversity of piece size</term>
<listitem><para>Only for irregular grid: Determines how the piece size varies. A very small setting means nearly no variation; crystallite-like structure arise. Higher settings produce very small and very large pieces.</para></listitem>
</varlistentry>
<varlistentry>
<term>Dump grid image</term>
<listitem><para>Save an image of the grid (black edges on white background) at <filename>~/goldberg-slicer-dump.png</filename>. If a previous dump exists, it is overwritten.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="create-puzzles">
<title>Creating new puzzles</title>
<sect1 id="creation-dialog">
<title>The puzzle creation dialog</title>
<para>As described in <link linkend="toolbar-collection">the previous section</link>, you can create new puzzles by clicking on the <inlinemediaobject><imageobject><imagedata fileref="tools-wizard.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Create New Puzzle...</guiicon> icon in the puzzle collection window.</para>
<para>Clicking this icon opens the puzzle creation dialog, which consists of three pages:</para>
<procedure>
<step><para>On the first page, select an image file which will be sliced into pieces. Be sure to enter the correct metadata for the image: You should give attribution to the author of the image (&eg; the photographer or the painter); please respect the copyright of the image author.</para></step>
<step><para>On the second page, you can select the type of pieces into which the image will be sliced. &palapeli; comes with a collection of slicers preinstalled, but third-party slicers may also be available.</para></step>
<step><para>On the final page of the dialog, the selected slicer can be customized &eg; by choosing a different piece count or by adjusting parameters of the piece shape. The available set of options depends which slicer has been selected.</para></step>
</procedure>
<para>This manual will continue to discuss the slicers which come with &palapeli;. If you have downloaded a third-party slicer plugin for &palapeli;, please refer to the documentation of this plugin if you have trouble installing or using it on your system.</para>
</sect1>
<sect1 id="simple-slicers">
<title>Simple slicers</title>
<para>&palapeli; has two simple slicers, <guilabel>Classic jigsaw pieces</guilabel> and <guilabel>Rectangular pieces</guilabel>. These slicers create simple rectangular pieces either with or without connecting plugs.</para>
<para>Both slicers allow the piece count and the aspect ratio to be adjusted. Dragging the <guilabel>Piece aspect ratio:</guilabel> slider to the left results in tall pieces, adjusting it to the right produces wide pieces. The default selection produces approximately square pieces.</para>
</sect1>
<sect1 id="psc">
<title>The advanced &i18n-psc;</title>
<para>The &i18n-psc; produces realistic jigsaw pieces with various basic patterns:</para>
<variablelist>
<varlistentry>
<term><guilabel>Rectangular grid</guilabel></term>
<listitem><para>Contains the well-known rectangular pieces.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Cairo grid</guilabel></term>
<listitem><para>With its pentagonal pieces and unequal edge angles, it's rather hard to puzzle because the pieces fit together in an unfamiliar manner.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Hexagonal grid</guilabel></term>
<listitem><para>Produces hexagonal pieces, arranged like honeycomb cells.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Rotrex grid</guilabel></term>
<listitem><para>Through a special composition of triangular, hexagonal and rectangular pieces, the pieces form a pattern resembling to many intersecting circles.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Irregular grid</guilabel></term>
<listitem><para>This grid is available only if you have installed <application>qvoronoi</application> from the <ulink url="https://www.qhull.org"><application>qhull</application> package</ulink>. <application>qvoronoi</application> is used to calculate irregular piece shapes from randomly placed points.</para></listitem>
</varlistentry>
</variablelist>
<para>The &i18n-psc; has various parameters which control the appearance of the piece edges, especially the plugs on them. Default settings are provided for all of these parameters. An additional preset mode is available which reduces the amount of parameters to a bare minimum. The following parameters are available usually:</para>
<variablelist>
<varlistentry>
<term><guilabel>Piece count:</guilabel></term>
<listitem><para>Here set the exact number in which the image will sliced into pieces. This option only appear if the mathematical logic of the slicer selected allows any number.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Approx. piece count:</guilabel></term>
<listitem><para>Here set the desired number in which the image will sliced into pieces. This option only appears if the mathematical logic of the selected slicer readjust this number.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Flipped edge percentage:</guilabel></term>
<listitem><para>The probability for each plug to be flipped. A plug is considered flipped if it points in the opposite direction as it would in a fully regular grid. On the rectangular grid, this results in pieces with 3 or 4 plugs pointing inwards resp. outwards. Position the slider at the very left to obtain the normal fully regular grid. In the middle, plug orientation is random. At the right, the grid is fully regular again, but with an <quote>alternate</quote> rule. This does <emphasis>not</emphasis> mean reversal of all plugs: In the alternate regular grid, for instance, each piece has four inward-pointing or four outward-pointing plugs. This setting has no effect in the irregular grid.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Edge curviness:</guilabel></term>
<listitem><para>Determines how curvy the edges are, &ie; how strongly the borders dent in or bulge out. Move the slider to the very left to obtain straight edge lines (except for the plugs).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Plug size:</guilabel></term>
<listitem><para>Determines the size of the plug part of each edge. The default setting (middle position of the slider) is chosen to look like a real puzzle. The slider ranges from 50% to 150% this size, which already looks obscenely large. The program tries very hard to avoid collisions between plugs. Colliding edges are reshaped multiple times and shrinked in small steps. However there still remain cases where no solution can be found, especially for large plug sizes.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Diversity of curviness:</guilabel></term>
<listitem><para>Determines how much the curviness (see above) varies between edges. Move the slider to the left to make the dents and bulges look all the same. Position the slider at the right, there may occur very curvy and very straight borders.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Diversity of plug position:</guilabel></term>
<listitem><para>Determines how much the position of the plug on the edge varies. Position the slider at the very left, plugs are affixed to the middle of their edge.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Diversity of plugs:</guilabel></term>
<listitem><para>Determines how individual the plugs look like. Position the slider at the very left, plugs look all the same. At the very right, each plug will be a unique piece of art crafted especially for you.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Diversity of piece size:</guilabel></term>
<listitem><para>Only for irregular grid: Determines how the piece size varies. A very small setting means nearly no variation; crystallite-like structure arise. Higher settings produce very small and very large pieces.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Dump grid image:</guilabel></term>
<listitem><para>Save an image of the grid (black edges on white background) at <filename>~/goldberg-slicer-dump.png</filename>. If a previous dump exists, it is overwritten.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="puzzletable">
<title>Playing on the puzzle table</title>
<chapter id="puzzletable">
<title>Playing on the puzzle table</title>
<sect1 id="puzzletable-moves">
<title>Basic moves</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 into an image.</para>
<para>The floating Preview window shows you what that image should be. Use a toolbar or menu action to show or hide the window. For a detailed description, see <link linkend="puzzletable-preview">The Preview window</link>.</para>
<para>If you wish to attempt a puzzle that has 300 or more pieces, please read the chapter on <link linkend="large-puzzles">Facilities for solving large puzzles</link>, after you have read this chapter.</para>
<para>You can move a single piece by clicking and dragging it with the &LMB;. That will leave the piece selected and highlighted. To move several pieces at once, first select and highlight them, then click and drag just one of the pieces. The rest will follow.</para>
<para>You can select and highlight multiple pieces by holding &Ctrl; and clicking on them, or by dragging a rubberband around them with the &LMB;. You can also use &Ctrl; and &LMB; to increase or decrease the current selection one piece at a time.</para>
<para>To remove selection and highlighting, just click on an empty spot on the puzzle table or on a piece that is not already selected.</para>
<para>When you put one piece near a neighboring piece, both pieces will automatically snap together and become joined (1). After pieces have been snapped together, they cannot be torn apart. Another difference between &palapeli; and a real-world jigsaw puzzle is that you cannot combine two pieces that are not true neighbors.</para>
<para>The progress bar below the puzzle table indicates your progress by counting joined pieces (2). &palapeli; will automatically save your progress after every move, so you do not have to worry about saving.</para>
<para>You can zoom the puzzle table view in or out with the mouse wheel, the slider at the bottom right or the buttons at the bottom right (3).</para>
<para>You can move the puzzle table view in any direction by clicking and dragging with the &RMB;.</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. Near the shaded borders, the mouse cursor changes into a double-headed arrow, indicating that you can adjust the puzzle table area by clicking there and dragging with the &LMB;.</para>
<para>You can lock the puzzle table area with the small button (5) to the right of the progress bar. The shade (4) around the puzzle table will darken, and pieces will now stop moving at the edges of the puzzle table area. It is still possible to adjust the size of the puzzle table area manually.</para>
</sect1>
<sect1 id="puzzletable-moves">
<title>Basic moves</title>
<screenshot><mediaobject>
<imageobject><imagedata fileref="puzzletable1.png" format="PNG"/></imageobject>
<textobject><phrase>The puzzle table (detail)</phrase></textobject>
</mediaobject></screenshot>
<para>The goal of the game is to assemble the given pieces into an image.</para>
<para>The floating Preview window shows you what that image should be. Use a toolbar or menu item to show or hide the window. For a detailed description, see <link linkend="puzzletable-preview">The Preview window</link>.</para>
<para>If you wish to attempt a puzzle that has 300 or more pieces, please read the chapter on <link linkend="large-puzzles">Facilities for solving large puzzles</link>, after you have read this chapter.</para>
<para>You can move a single piece by clicking and dragging it with the &LMB;. That will leave the piece selected and highlighted. To move several pieces at once, first select and highlight them, then click and drag just one of the pieces. The rest will follow.</para>
<para>You can select and highlight multiple pieces by holding &Ctrl; and clicking on them, or by dragging a rubberband around them with the &LMB;. You can also hold the &Ctrl; key and click with the &LMB; to increase or decrease the current selection one piece at a time.</para>
<para>To remove selection and highlighting, just click on an empty spot on the puzzle table or on a piece that is not already selected.</para>
<para>When you put one piece near a neighboring piece, both pieces will automatically snap together and become joined (1). After pieces have been snapped together, they cannot be torn apart. Another difference between &palapeli; and a real-world jigsaw puzzle is that you cannot combine two pieces that are not true neighbors.</para>
<para>The progress bar below the puzzle table indicates your progress by counting joined pieces (2). &palapeli; will automatically save your progress after every move, so you do not have to worry about saving.</para>
<para>You can zoom the puzzle table view in or out with the mouse <mousebutton>wheel</mousebutton>, and at the bottom right (3) with the buttons and the slider.</para>
<para>You can move the puzzle table view in any direction by clicking and dragging with the &RMB;.</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. Near the shaded borders, the mouse cursor changes into a double-headed arrow, indicating that you can adjust the puzzle table area by clicking there and dragging with the &LMB;.</para>
<para>You can lock the puzzle table area with the small icon (5) to the right of the progress bar. The shade (4) around the puzzle table will darken, and pieces will now stop moving at the edges of the puzzle table area. It is still possible to adjust the size of the puzzle table area manually.</para>
</sect1>
<sect1 id="puzzletable-preview">
<title>The Preview window</title>
<para>The Preview is a small window that floats
above or to one side of the puzzle table window. It
contains an image of the completed puzzle: the picture
that would appear on top of the box if this was a
real-world jigsaw puzzle.
</para>
<para>The window can be shown or hidden by using the
<guiicon>Preview</guiicon> toolbar button or the
<menuchoice><guimenu>View</guimenu><guimenuitem>
Preview</guimenuitem></menuchoice> menu item. Its
size, position and visible or not visible setting
are saved and restored between runs of &palapeli;.
</para>
<para>Being a window, it can be freely moved around
the desktop and resized. Its Close button will
hide it and its Maximize button will expand or
contract the picture rapidly.
</para>
<para>The Preview window has a magnification
feature, so it need not take up much space.
If you move the mouse over the window,
it zooms in quickly to reveal a magnified view
of the area under the mouse and the equivalent
of a few pieces around it. This is very useful
for viewing details of the puzzle and identifying
pieces you have found, but it can be tricky to
control, especially near the edges of the picture.
</para>
</sect1>
<sect1 id="puzzletable-preview">
<title>The Preview window</title>
<para>The Preview is a small window that floats
above or to one side of the puzzle table window. It
contains an image of the completed puzzle: the picture
that would appear on top of the box if this was a
real-world jigsaw puzzle.
</para>
<para>The window can be shown or hidden by using the
<inlinemediaobject><imageobject><imagedata fileref="view-preview.png" format="PNG"/>
</imageobject></inlinemediaobject> <guiicon>Preview</guiicon>
toolbar icon or the <menuchoice><guimenu>View</guimenu>
<guimenuitem>Preview</guimenuitem></menuchoice> menu item. Its
size, position and visible or not visible setting
are saved and restored between runs of &palapeli;.
</para>
<para>Being a window, it can be freely moved around
the desktop and resized. Its <guibutton>Close</guibutton>
button will hide it and its <guibutton>Maximize</guibutton>
button will expand or contract the picture rapidly.
</para>
<para>The Preview window has a magnification
feature, so it need not take up much space.
If you move the mouse over the window,
it zooms in quickly to reveal a magnified view
of the area under the mouse and the equivalent
of a few pieces around it. This is very useful
for viewing details of the puzzle and identifying
pieces you have found, but it can be tricky to
control, especially near the edges of the picture.
</para>
</sect1>
<sect1 id="puzzletable-mouseactions">
<title>Mouse interactions</title>
<para>As described in the previous section, there are plenty of ways to interact with &palapeli;'s puzzle table using the mouse. You can configure freely which actions are triggered by which mouse buttons. (See <link linkend="configuration-mouseactions">Game Configuration</link> section for more information on how to configure this.) The following list summarizes all possible mouse actions:</para>
<variablelist>
<varlistentry>
<term><action>Change size of puzzle table area by dragging its edges</action></term>
<listitem><para>By default, this action is assigned to the &LMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Move pieces by dragging</action></term>
<listitem><para>When you click and drag a puzzle piece, this piece will be moved. If multiple pieces have been selected and you click and drag one of these pieces, then all pieces are moved. By default, this action is assigned to the &LMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Move viewport by dragging</action></term>
<listitem><para>This action moves the view of the entire puzzle table in any direction. By default, it is assigned to the &RMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Select several pieces by rubberbanding</action></term>
<listitem><para>When you click on a free area of the puzzle table instead of a puzzle piece, you can drag a rubberband. When you let the mouse button go, all pieces inside the rubberband are selected. All other pieces are deselected. By default, this action is assigned to the &LMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Select several pieces by clicking</action></term>
<listitem><para>When you click on a puzzle piece, it will be selected or, if it was already selected, it will be deselected. It can also be used to adjust a rubberband selection. By default, this action is assigned to the &LMB; and only available when &Ctrl; is pressed.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Clear selections and highlighting</action></term>
<listitem><para>Click on an empty spot in the puzzle table or on a piece that is not already selected.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Zoom the puzzle table view in or out</action></term>
<listitem><para>This action is identical to clicking the buttons either side of the slider (3) on the status bar. It is assigned to the mouse wheel by default.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Switch to close-up or distant view</action></term>
<listitem><para>This action alternates (toggles) between a close-up and distant view, at the position of the mouse pointer. It is intended mainly to provide fast zooming in large puzzles (300 pieces or more). For more detail, see <link linkend="large-puzzle-fast-zooming">Fast zooming between close-up and distant view</link>. By default, the action is assigned to the &MMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Teleport pieces to or from a holder</action></term>
<listitem><para>This action helps you collect, sort and move pieces rapidly in large puzzles (300 pieces or more) without dragging and dropping. You can use it in smaller puzzles if you wish. For more detail, see <link linkend="large-puzzle-holders">Using piece-holders</link>. By default, the action is assigned to the &LMB; and only available when &Shift; is pressed.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Toggle lock state of the puzzle table area</action></term>
<listitem><para>This action is identical to pressing the button (5) on the status bar. By default, this action is not assigned to any mouse button, but you can enable it from <link linkend="configuration-mouseactions">the configuration dialog</link>.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Scroll viewport horizontally</action> and <action>Scroll viewport vertically</action></term>
<listitem><para>By default, this action is not assigned to the mouse wheel, but you can enable it from <link linkend="configuration-mouseactions">the configuration dialog</link>.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="puzzletable-mouseactions">
<title>Mouse interactions</title>
<para>As described in the previous section, there are plenty of ways to interact with &palapeli;'s puzzle table using the mouse. You can configure freely which actions are triggered by which mouse buttons. (See <link linkend="configuration-mouseactions">Game Configuration</link> section for more information on how to configure this.) The following list summarizes all possible mouse actions:</para>
<variablelist>
<varlistentry>
<term><action>Change size of puzzle table area by dragging its edges</action></term>
<listitem><para>By default, this action is assigned to the &LMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Move pieces by dragging</action></term>
<listitem><para>When you click and drag a puzzle piece, this piece will be moved. If multiple pieces have been selected and you click and drag one of these pieces, then all pieces are moved. By default, this action is assigned to the &LMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Move viewport by dragging</action></term>
<listitem><para>This action moves the view of the entire puzzle table in any direction. By default, it is assigned to the &RMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Select several pieces by rubber banding</action></term>
<listitem><para>When you click on a free area of the puzzle table instead of a puzzle piece, you can drag a rubberband. When you let the mouse button go, all pieces inside the rubberband are selected. All other pieces are deselected. By default, this action is assigned to the &LMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Select multiple pieces at once</action></term>
<listitem><para>When you click on a puzzle piece, it will be selected or, if it was already selected, it will be deselected. It can also be used to adjust a rubberband selection. By default, this action is assigned to the &LMB; and only available when &Ctrl; is pressed.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Clear selections and highlighting</action></term>
<listitem><para>Click on an empty spot in the puzzle table or on a piece that is not already selected.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Zoom the puzzle table view in or out</action></term>
<listitem><para>This action is identical to clicking the buttons either side of the slider (3) on the status bar. It is assigned to the mouse <mousebutton>wheel</mousebutton> by default.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Switch to close-up or distant view</action></term>
<listitem><para>This action alternates (toggles) between a close-up and distant view, at the position of the mouse pointer. It is intended mainly to provide fast zooming in large puzzles (300 pieces or more). For more detail, see <link linkend="large-puzzle-fast-zooming">Fast zooming between close-up and distant view</link>. By default, the action is assigned to the &MMB;.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Teleport pieces to or from a holder</action></term>
<listitem><para>This action helps you collect, sort and move pieces rapidly in large puzzles (300 pieces or more) without dragging and dropping. You can use it in smaller puzzles if you wish. For more detail, see <link linkend="large-puzzle-holders">Using piece-holders</link>. By default, the action is assigned to the &LMB; and only available when &Shift; key is pressed.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Toggle lock state of the puzzle table area</action></term>
<listitem><para>This action is identical to pressing the button (5) on the status bar. By default, this action is not assigned to any mouse button, but you can enable it from <link linkend="configuration-mouseactions">the configuration dialog</link>.</para></listitem>
</varlistentry>
<varlistentry>
<term><action>Scroll viewport horizontally</action> and <action>Scroll viewport vertically</action></term>
<listitem><para>By default, this action is not assigned to the mouse <mousebutton>wheel</mousebutton>, but you can enable it from <link linkend="configuration-mouseactions">the configuration dialog</link>.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="toolbars-puzzletable">
<title>Toolbar overview</title>
<variablelist>
<varlistentry>
<term><guiicon>Back to collection</guiicon></term>
<listitem><para><action>Go back to the collection to choose another puzzle.</action> Can be used only when you are solving a puzzle.</para></listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Preview</guiicon></term>
<listitem><para><action>Toggle the display of the preview window with the completed puzzle.</action></para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<sect1 id="toolbars-puzzletable">
<title>Toolbar overview</title>
<variablelist>
<varlistentry>
<term><inlinemediaobject><imageobject><imagedata fileref="go-previous.png" format="PNG"/></imageobject></inlinemediaobject> <guiicon>Back to Collection</guiicon></term>
<listitem><para><action>Go back to the collection to choose another puzzle.</action> Can be used only when you are solving a puzzle.</para></listitem>
</varlistentry>
<varlistentry>