[kde-doc-english] KDE/kdegames/doc/palapeli

[Stefan Majewsky]

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 (&eg; <action>Move viewport by dragging</action>), and those that can be assigned to the mouse wheel (&eg; <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;