# The &palapeli; Handbook

Stefan
Majewsky

    majewsky@gmx.net

2009, 2010
Stefan Majewsky
&FDLNotice;
2010-05-24
1.1

This is the manual for &palapeli;, a jigsaw puzzle game based on &kde; technology.

KDE
kdegames
game
puzzle game
jigsaw puzzle
palapeli

## Introduction

&palapeli; is a single-player jigsaw puzzle game.

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.

## Browsing the puzzle collection

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 the next section for how to use the puzzle table.

Apart from selecting a puzzle, the puzzle collection can be used for the following actions:

- create new puzzles from images on your disk

- import puzzles made by others

- export puzzles to share them with your friends and the world

- delete puzzles you do not need any more

The following section shows how to perform these tasks with the toolbar buttons.

### Toolbar overview

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.

Create new puzzle

  Opens a dialog which allows you to create a puzzle from an image on your disk. 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.

  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.

Delete

  Any puzzles that you have selected in the puzzle list, will be permanently deleted from your library.

  This action cannot be undone.

Import from file

  When you have received a &palapeli; puzzle file (which can usually be recognized by the file extension `*.puzzle`), you can use this action to import it into your local collection. 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.

Export to file

  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.

## Playing on the puzzle table

The puzzle table (detail)

The object of the game is to assemble the given pieces to an image.

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;.

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.

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.

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.

The movement of the pieces is limited by the puzzle table area. 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;.

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.

### Mouse interactions

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 Game Configuration section for more information on how to configure this.) The following list summarizes all possible mouse actions:

Change size of puzzle table area by dragging its edges

  By default, this action is assigned to the &LMB;.

Move pieces by dragging

  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;.

Move viewport by dragging

  By default, this action is assigned to the &RMB;.

Select multiple pieces at once

  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;.

Select pieces by clicking

  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.

Toggle lock state of the puzzle table area

  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 the configuration dialog.

Scroll viewport horizontally and Scroll viewport vertically

  By default, this action is not assigned to the mouse wheel, but you can enable it from the configuration dialog.

Zoom viewport

  This action is identical to moving the slider (3) on the status bar. This action is assigned to the mouse wheel by default.

### Toolbar overview

Restart puzzle

  Discards the saved progress for this puzzle.

## Interface Overview

&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.

### The Settings Menu

Settings Show statusbar of puzzle table

  Toggle the display of the progress bar and buttons below the puzzle table. This action will change nothing in the puzzle collection.

Settings Configure Shortcuts...

  Open a dialog where you can configure the shortcut keys for &palapeli;

Settings Configure &palapeli;...

  Open a game configuration dialog. See Game Configuration section for more details.

### The Help Menu

&help.menu.documentation;

## Game Configuration

To open the configuration dialog, use the menubar option: Settings Configure &palapeli;...

### General settings

Background

  Lets you choose another background texture for the puzzle table. If you choose a single color instead of a texture, the button besides the selection box can be used to define this single color.

Snapping precision

  Lets you choose how near neighbor pieces must be positioned to each other to snap together. 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.

### Mouse interaction

This page of the configuration dialog allows you to assign the mouse interactions described in the section Playing on the puzzle table to different mouse buttons. The interactions are divided into those that can be assigned to mouse buttons (&eg; Move viewport by dragging), and those that can be assigned to the mouse wheel (&eg; Scroll viewport horizontally).

#### Mouse buttons tab

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.

Instead of clicking, you can also press Space to assign the special No-Button to this interaction. This is only allowed if modifier keys are being held. The No-Button 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.

#### Mouse wheel tab

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.

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.

## Credits and License

&palapeli; aims to bring the unagitated fun and challenge of jigsaw puzzles to your desktop.

The idea was first developed by Bernhard Schiffner, together with Stefan Majewsky, who is the current lead developer of &palapeli;.

Documentation Copyright 2009, 2010 Stefan Majewsky.

&underFDL; &underGPL;

## Installation

&install.intro.documentation;

### Compilation and Installation

&install.compile.documentation;
&documentation.index;