SVN commit 1129843 by majewsky:
Documentation update for Palapeli 1.1
CCMAIL: kde-doc-english at kde.org
If possible, please proof-read the sections describing the new mouse
interaction framework. I'm afraid that this whole stuff is hardly
understandable for non-developers. If you can describe this stuff
better, please go ahead and tear my wording apart. ;-)
M +66 -18 index.docbook
--- trunk/KDE/kdegames/doc/palapeli/index.docbook #1129842:1129843
@@ -20,12 +20,12 @@
</authorgroup>
<copyright>
- <year>2009</year>
+ <year>2009, 2010</year>
<holder>Stefan Majewsky</holder>
</copyright>
-<!-- <legalnotice>&FDLNotice;</legalnotice> TODO: FIXME -->
- <date>2009-11-09</date>
- <releaseinfo>1.0</releaseinfo>
+ <legalnotice>&FDLNotice;</legalnotice>
+ <date>2010-05-24</date>
+ <releaseinfo>1.1</releaseinfo>
<abstract>
<para>This is the manual for &palapeli;, a jigsaw
puzzle game based on &kde; technology.</para>
@@ -91,11 +91,50 @@
<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>Pieces can be freely moved by clicking and dragging them
with the &LMB;. You can select multiple pieces at once by holding &Ctrl; and
clicking on them, or by dragging a rubberband around them with the &LMB;.</para>
+ <para>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>
+ <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 clicking
and dragging with the &RMB;, you can move the puzzle table view.</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) 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.
It is still possible to adjust the size of the puzzle table area
manually.</para>
+ <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 are 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>By default, this action
is assigned to the &RMB;.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><action>Select multiple pieces at
once</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 pieces by
clicking</action></term>
+ <listitem><para>When you click on a
single puzzle piece, it will be selected. If it was already selected, it will
be deselected. By default, this action is assigned to the &LMB; and only
available when &Ctrl; 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>
+ <varlistentry>
+ <term><action>Zoom
viewport</action></term>
+ <listitem><para>This action is
identical to moving the slider (3) on the status bar. This action is assigned
to the mouse wheel by default.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
<sect1 id="toolbars-puzzletable">
<title>Toolbar overview</title>
<variablelist>
@@ -137,31 +176,40 @@
<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>
+ <sect1 id="configuration-general">
+ <title><guilabel>General settings</guilabel></title>
<variablelist>
<varlistentry>
<term><guilabel>Background</guilabel></term>
- <listitem><para><action>Lets you choose another
background texture for the puzzle table.</action></para></listitem>
+ <listitem><para><action>Lets you choose
another background texture for the puzzle table.</action> If you choose a
single color instead of a texture, the button besides the selection box can be
used to define this single color.</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>
+ </sect1>
+ <sect1 id="configuration-mouseactions">
+ <title><guilabel>Mouse interaction</guilabel></title>
+ <para>This page of the configuration dialog allows you
to assign the mouse interactions described in the section <link
linkend="puzzletable-mouseactions">Playing on the puzzle table</link> to
different mouse buttons. The interactions are divided into those that can be
assigned to mouse buttons (⪚ <action>Move viewport by dragging</action>),
and those that can be assigned to the mouse wheel (⪚ <action>Scroll viewport
horizontally</action>).</para>
+ <sect2>
+ <title><guilabel>Mouse buttons</guilabel>
tab</title>
+ <para>Next to the name of each interaction is a
button with a picture of a computer mouse which shows the currently assigned
action. You can configure the interaction by clicking on that button with the
&LMB; and then with the mouse button which you want to assign to this
interaction. If you hold modifier keys while clicking for the second time, the
puzzle table will allow this interaction only while these modifiers are being
held.</para>
+ <tip><para>Instead of clicking, you can also
press <keycap>Space</keycap> to assign the special
<guilabel>No-Button</guilabel> to this interaction. This is only allowed if
modifier keys are being held. The <guilabel>No-Button</guilabel> means that the
modifier keys take the role of the mouse button: The interaction starts when
the modifier keys are pressed, and stops when one of the modifier keys is
released.</para></tip>
+ </sect2>
+ <sect2>
+ <title><guilabel>Mouse wheel</guilabel>
tab</title>
+ <para>This tab works similar to the previous
one. When the button on the right asks for input, you have to turn the mouse
wheel instead of clicking a mouse button. Holding modifier keys is allowed,
too, with the same consequences as in the previous case.</para>
+ <tip><para>If your mouse has a bidirectional
mouse wheel (as most commonly found on notebook touchpads), you can take
advantage of this: The button will recognize whether you turned the mouse wheel
horizontally or vertically.</para></tip>
+ </sect2>
+ </sect1>
</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>
+ <para>Documentation Copyright 2009, 2010 Stefan Majewsky.</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
&underGPL;
