Contents

Abstract

This tutorial shows you how to create a pattern for Palapeli, that is: a plugin for the Palapeli libraries that describes an algorithm to split an image into pieces.

The pattern we will be constructing is quite easy: It splits an image into two equally sized pieces. To give an example of configurability, we let the user define whether the image is splitted horizontally or vertically.

Structure

A pattern plugin consists of two classes. The first one (derived from Palapeli::PatternConfiguration) tells Palapeli what features this pattern plugin has and which configuration values it needs. The second one (derived from Palapeli::Pattern) does the actual slicing.

As described above, we have declared two classes deriving from the base classes Palapeli::Pattern and Palapeli::PatternConfiguration. For this simple example, we do only reimplement constructors, destructors and some pure virtual functions.

We will start with the MyPatternConfiguration class, because this is the logical entry point. The pattern configuration class is created when Palapeli is started. (The constructor arguments are necessary for the plugin loader, you will not need to bother with them as long as you pass them to the base class constructor.) Its job is to manage the pattern's settings.

In this case, one is able to configure whether the image should be splitted in horizontal or in vertical direction. A configuration option is described by a property. (These have nothing to do with QObject's property system.) Properties are defined with a data type. Note that property data is always passed as QVariant, the data type does only determine which widgets should be used in the configuration interface for the pattern. Legal data types include String (represented by a KLineEdit) or Integer (through KIntSpinBox). The creation of those widgets is done in the Palapeli::PatternConfiguration class, you do only need to define the properties correctly.

When we define our "splitting" property, we assign the data type String to it (from the Palapeli::PatternConfiguration::DataType enumeration). Also, we give some parameters to this property. It depends on the data type how these parameters are used. In this case, the parameters define a list of valid inputs to this property. Therefore, not a line edit is used in the configuration, but a combo box, which limits the user input to the given strings.

When the user has configured its game (and therefore the pattern), the Palapeli game engine will call the createPattern method to create a Palapeli::Pattern object. If you have added properties, read them and pass them to the constructor of your pattern object.

Now we have a Palapeli::Pattern instance. Its main purpose is the doSlice method which takes a method. In this implementation, we copy the left and the right part (or the upper and the lower part) of the image to get two pieces. To add these pieces to Palapeli's puzzle scene, use the base class' addPiece method. It will properly report it to Palapeli.

After we have added all pieces, we need to define neighbor relations between pieces. Neighbor relations are used to snap pieces together when they're near enough. Consider three pieces in a row: If piece 1 is near piece 3, nothing should snap because they do not have a common edge. If piece 1 is moved near piece 2, these should snap together. Therefore, we define a relation between piece 1 and piece 2 (and piece 2 and piece 3, respectively). The relation is added through the addRelation function. In our case (line 29), we define a relation between the first piece (index 0) and the second piece (index 1). The piece indices are based on the order in which you added the pieces to the scene, and start at zero.

We need to tell the Palapeli library that there is a new plugin out there. We need a desktop entry file like shown here. You can mostly copy everything you see here; as long as you keep the fields X-KDE-Library and X-KDE-PluginInfo-Name in sync with the library name (see next section). You should not change the PatternIdentifier field because that will invalidate saved games created with previous versions. Note also that the name is used in the "New puzzle" dialog to identify this pattern. (It can be translated; for example, a German translation has been added in the above example.)

Everything of this is pretty straightforward if you have previous experience with CMake (and this is what I assume). Make sure you compile everything as a plugin, and install it into the plugin directory. After having installed the plugin, run kbuildsycoca4. This will locate your plugin, and enable Palapeli to use it. Here is how it should look like then: