<chapter id="technical-reference">
<chapterinfo>

<authorgroup>
<author>
<firstname>Éric</firstname>
<surname>Bischoff</surname>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>2006-05-05</date>
<releaseinfo>0.05.01</releaseinfo>

<keywordset>
<keyword>KDE</keyword>
<keyword>KTuberling</keyword>
<keyword>technical reference</keyword>
</keywordset>
</chapterinfo>

<title>Technical References</title>

<para>
&ktuberling; offers a gentle and rewarding introduction to &kde; customization
and programming.  The application can be extended.  For example, without any
coding, new playgrounds can be added by changing the graphics files. By
adding appropriate sound files, translators can change the sounds to their
native tongue!
</para>

<para>
If you extend or add to the game please consider sending your additions to the
developer <ulink url="mailto:aacid@kde.org">Albert Astals Cid</ulink> for
inclusion in future releases.
</para>

<sect1 id="for-artists">
<title>For Artists</title>

<para>
To create a new KTuberling playground you have to:
</para>

<itemizedlist>

<listitem>
    <para>Draw the playground in a SVG file, there you have to:
        <itemizedlist>
            <listitem><para>Name the place where items can dragged "background".</para></listitem>
            <listitem><para>Name each of the draggable items with an unique name.</para></listitem>
        </itemizedlist>
    </para>
</listitem>

<listitem>
    <para>Create a .theme file, it has to follow this schema:</para>
    <programlisting>
    &lt;playground gameboard="<replaceable>yourSVGFile</replaceable>" name="<replaceable>theDesktopFile</replaceable>"&gt;
    &lt;object name="<replaceable>itemName</replaceable>" sound="<replaceable>soundName</replaceable>" scale="<replaceable>someValue</replaceable>" /&gt;
    ...
    ...
    ...
    &lt;/playground&gt;
    </programlisting>
    <itemizedlist>
        <listitem><para><replaceable>yourSVGFile</replaceable> is the name of the svg file that has the drawing.</para></listitem>
        <listitem><para><replaceable>theDesktopFile</replaceable> is the name of the desktop file that has the name of the theme.</para></listitem>
        <listitem><para>For each object you need a &lt;object&gt; entry. <replaceable>itemName</replaceable> is the unique
                        name you used on the SVG file, <replaceable>soundName</replaceable> is the sound name that will
                        be played when dragging it, see sound themes howto for more information.</para></listitem>
        <listitem><para>scale is optional and <replaceable>someValue</replaceable> is the scale factor that will be used
                        when drawing this object outside the warehouse, if not specified is 1.</para></listitem>
    </itemizedlist>
</listitem>

<listitem>
    <para>Create a .desktop file, it has to follow this schema</para>
    <programlisting>
    [KTuberlingTheme]
    Name=<replaceable>themeName</replaceable>
    </programlisting>
    <itemizedlist>
        <listitem><para><replaceable>themeName</replaceable> is the name that identifies the theme, will be shown in the Playground menu.</para></listitem>
    </itemizedlist>
</listitem>

<listitem>
    <para>If you are adding the theme to KTuberling SVN, add .svg .theme .desktop files to FILES section of the CMakeLists.txt in the pics/ directory
    </para>
</listitem>

<listitem>
    <para>If you want to install it for yourself, place .svg .theme .desktop files in `kde4-config --prefix`/share/apps/ktuberling/pics
    </para>
</listitem>

</itemizedlist>

</sect1>

<sect1 id="for-translators">
<title>For Translators</title>

<para>
Besides the usual <literal role="extension">.po</literal> files mechanism for
translating program labels and prompts, the sounds can be localized too.
</para>

<para>
To create a new KTuberling sound theme you have to:
</para>

<itemizedlist>

<listitem><para>Record the sounds in OGG Vorbis rc3 file format.</para></listitem>

<listitem>
<para>Create a <replaceable>yourLanguageTwoLetterCode</replaceable>.soundtheme file, it has to follow this schema:</para>
<programlisting>
&lt;language code="<replaceable>yourLanguageTwoLetterCode</replaceable>"&gt;
&lt;sound name="<replaceable>soundName</replaceable>" file="<replaceable>relativePath</replaceable>" /&gt;
...
...
...
&lt;/language&gt;
</programlisting>
<itemizedlist>
<listitem><para><replaceable>yourLanguageTwoLetterCode</replaceable> is your language two letter code, for example gl for Galician.</para></listitem>
<listitem><para>For each sound a &lt;sound&gt; entry. <replaceable>soundName</replaceable> should match with the soundName specified
     in the playground theme (see themes HOWTO). <replaceable>relativePath</replaceable> should be the relative path you
     are going to install the file with this sound to, typically it will be 
     someUniquePath/soundName.format (someUniquePath can be your language two letter code for
     example).</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>If you are adding the sound theme to KTuberling SVN:</para>
<itemizedlist>
<listitem><para>Add the sound files and the .soundtheme files to the data/kdegames/ktuberling directory
     of your language translations.</para></listitem>
<listitem><para>On that very same dir you need a CMakeLists.txt describing how to install the files, typically it will be.</para>
<programlisting>
FILE(GLOB datafiles *.ogg)
install( FILES ${datafiles} DESTINATION ${DATA_INSTALL_DIR}/ktuberling/sounds/<replaceable>yourLanguageTwoLetterCode</replaceable> )
install( FILES <replaceable>yourLanguageTwoLetterCode</replaceable>.soundtheme DESTINATION ${DATA_INSTALL_DIR}/ktuberling/sounds/ )
</programlisting>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para>If you want to install it for yourself:</para>
<itemizedlist>
<listitem><para>Place <replaceable>yourLanguageTwoLetterCode</replaceable>.soundtheme file in `kde4-config --prefix`/share/apps/ktuberling/sounds</para></listitem>
<listitem><para>Place yourSoundFiles in `kde4-config --prefix`/share/apps/ktuberling/sounds/someUniquePath</para></listitem>
</itemizedlist>
</listitem>

</itemizedlist>

<para>
Information on how to work with the translation mechanisms in &kde; is available
in <ulink url="http://i18n.kde.org/translation-howto/index.html">The
&kde; Translation HOWTO</ulink>.
</para>

</sect1>

<sect1 id="for-programmers">

<title>For Programmers</title>
<para>&ktuberling; isn't really difficult to extend for programmers.</para>

<sect2 id="classes">
<title>C++ classes</title>

<variablelist>
<varlistentry>
<term><classname>TopLevel</classname></term>
<listitem>
<para>Top-level window and basic program management</para>
</listitem>
</varlistentry>

<varlistentry>
<term><classname>PlayGround</classname></term>
<listitem>
<para>Description of one of the game levels</para> </listitem>
</varlistentry>

<varlistentry>
<term><classname>ToDraw</classname></term>
<listitem>
<para>Description of one of the graphical <quote>objects</quote> to be
drawn</para> </listitem>
</varlistentry>

<varlistentry>
<term><classname>SoundFactory</classname></term>
<listitem>
<para>Description of one of the languages and its sounds</para> </listitem>
</varlistentry>

<varlistentry>
<term><classname>Action</classname></term>
<listitem>
<para>One of the user's manipulation in the undo/redo stack</para> </listitem>
</varlistentry>
</variablelist>

</sect2>

</sect1>
</chapter>