Warning, /games/ktuberling/doc/technical-reference.docbook is written in an unsupported language. File is not indexed.

0001 <chapter id="technical-reference">
0002 <chapterinfo>
0003 
0004 <authorgroup>
0005 <author>
0006 <firstname>√Čric</firstname>
0007 <surname>Bischoff</surname>
0008 </author>
0009 <!-- TRANS:ROLES_OF_TRANSLATORS -->
0010 </authorgroup>
0011 
0012 <date>2021-10-04</date>
0013 <releaseinfo>KDE Gear 21.08</releaseinfo>
0014 
0015 <keywordset>
0016 <keyword>KDE</keyword>
0017 <keyword>KTuberling</keyword>
0018 <keyword>technical reference</keyword>
0019 </keywordset>
0020 </chapterinfo>
0021 
0022 <title>Technical References</title>
0023 
0024 <para>
0025 &ktuberling; offers a gentle and rewarding introduction to &kde; customization
0026 and programming.  The application can be extended.  For example, without any
0027 coding, new playgrounds can be added by changing the graphics files. By
0028 adding appropriate sound files, translators can change the sounds to their
0029 native tongue!
0030 </para>
0031 
0032 <para><!--FIXME email alex ok?-->
0033 If you extend or add to the game please consider sending your additions to the
0034 maintainer <ulink url="mailto:alex@eyeos.org">Alex Fiestas</ulink> for
0035 inclusion in future releases.
0036 </para>
0037 
0038 <sect1 id="for-artists">
0039 <title>For Artists</title>
0040 
0041 <para>
0042 To create a new &ktuberling; playground you have to:
0043 </para>
0044 
0045 <itemizedlist>
0046   <listitem>
0047     <para>Draw the playground in a &SVG; file, there you have to:
0048       <itemizedlist>
0049         <listitem><para>Name the place where items can dragged <quote>background</quote>.</para></listitem>
0050         <listitem><para>Name each of the draggable items with an unique name.</para></listitem>
0051       </itemizedlist>
0052     </para>
0053   </listitem>
0054 
0055   <listitem>
0056     <para>Create a <literal role="extension">.theme</literal> file, it has to follow this schema:</para>
0057 <programlisting>
0058 &lt;playground gameboard="<replaceable>yourSVGFile</replaceable>" name="<replaceable>theDesktopFile</replaceable>"&gt;
0059 &lt;object name="<replaceable>itemName</replaceable>" sound="<replaceable>soundName</replaceable>" scale="<replaceable>someValue</replaceable>" /&gt;
0060 ...
0061 ...
0062 ...
0063 &lt;/playground&gt;
0064 </programlisting>
0065     <itemizedlist>
0066       <listitem><para><replaceable>yourSVGFile</replaceable> is the name of the &SVG; file that has the drawing.</para></listitem>
0067       <listitem><para><replaceable>theDesktopFile</replaceable> is the name of the desktop file that has the
0068       name of the theme.</para></listitem>
0069       <listitem><para>For each object you need a <literal>&lt;object&gt;</literal> entry.
0070       <replaceable>itemName</replaceable> is the unique name you used on the &SVG; file,
0071       <replaceable>soundName</replaceable> is the sound name that will be played when dragging it, see the
0072       <filename>sounds/soundthemes.HOWTO</filename> file from source code for more information.</para></listitem>
0073       <listitem><para><literal>scale</literal> is optional and <replaceable>someValue</replaceable> is the scale
0074       factor that will be used when drawing this object outside the warehouse, if not specified is 1.</para></listitem>
0075     </itemizedlist>
0076   </listitem>
0077 
0078   <listitem>
0079     <para>Create a <literal role="extension">.desktop</literal> file, it has to follow this schema:</para>
0080 <programlisting>
0081 [KTuberlingTheme]
0082 Name=<replaceable>themeName</replaceable>
0083 </programlisting>
0084     <itemizedlist>
0085       <listitem><para><replaceable>themeName</replaceable> is the name that identifies the theme, will be shown in the
0086       Playground menu.</para></listitem>
0087     </itemizedlist>
0088   </listitem>
0089 
0090   <listitem>
0091     <para>If you are adding the theme to &ktuberling; repository, add <literal role="extension">.svg</literal>,
0092         <literal role="extension">.theme</literal>, and <literal role="extension">.desktop</literal> files to
0093         <literal>FILES</literal> section of the <filename>CMakeLists.txt</filename> into the
0094         <filename class="directory">pics/</filename> folder.
0095     </para>
0096   </listitem>
0097 
0098   <listitem>
0099     <para>If you want to install it for yourself, place <literal role="extension">.svg</literal>,
0100     <literal role="extension">.theme</literal>, and <literal role="extension">.desktop</literal> files into
0101     the <filename class="directory">ktuberling/pics</filename> folder in
0102     <userinput><command>qtpaths</command> <option>--paths GenericDataLocation</option></userinput>
0103     </para>
0104   </listitem>
0105 </itemizedlist>
0106 
0107 </sect1>
0108 
0109 <sect1 id="for-translators">
0110 <title>For Translators</title>
0111 
0112 <para>
0113 Besides the usual <literal role="extension">.po</literal> files mechanism for
0114 translating program labels and prompts, the sounds can be localized too.
0115 </para>
0116 
0117 <para>
0118 To create a new &ktuberling; sound theme you have to:
0119 </para>
0120 
0121 <itemizedlist>
0122   <listitem><para>Record the sounds in OGG Vorbis rc3 file format.</para></listitem>
0123   <listitem><para>Create a <filename><replaceable>yourLanguageTwoLetterCode</replaceable>.soundtheme</filename>
0124   file, it has to follow this schema:</para>
0125 <programlisting>
0126 &lt;language code="<replaceable>yourLanguageTwoLetterCode</replaceable>"&gt;
0127 &lt;sound name="<replaceable>soundName</replaceable>" file="<replaceable>relativePath</replaceable>" /&gt;
0128 ...
0129 ...
0130 ...
0131 &lt;/language&gt;
0132 </programlisting>
0133     <itemizedlist>
0134       <listitem><para><replaceable>yourLanguageTwoLetterCode</replaceable> is your language two
0135       letter code, for example gl for Galician.</para></listitem>
0136       <listitem><para>For each sound a <literal>&lt;sound&gt;</literal> entry. <replaceable>soundName</replaceable>
0137       should match with the soundName specified in the playground theme (see the <filename>pics/themes.HOWTO</filename>
0138       from source code). <replaceable>relativePath</replaceable> should be the relative path you are going
0139       to install the file with this sound to, typically it will be
0140       <filename><replaceable>someUniquePath</replaceable>/<replaceable>soundName</replaceable>.<replaceable>format</replaceable></filename>
0141       (<replaceable>someUniquePath</replaceable> can be your language two letter code for example).</para></listitem>
0142     </itemizedlist>
0143   </listitem>
0144 
0145   <listitem><para>If you are adding the sound theme to &ktuberling; in your language folder:</para>
0146     <itemizedlist>
0147       <listitem><para>Add the sound files and the <literal role="extension">.soundtheme</literal>
0148       files into the <filename class="directory">data/kdegames/ktuberling</filename> folder of your
0149       language translations.</para></listitem>
0150       <listitem><para>On that very same dir you need a <filename>CMakeLists.txt</filename> file
0151       describing how to install the files, typically it will be.</para>
0152 <!--FIXME l10n-kf5/*/data/kdegames/ktuberling/CMakeLists.txt has DATA_INSTALL_DIR, has this to be changed?-->
0153 <programlisting>
0154 FILE( GLOB oggfiles *.ogg )
0155 INSTALL( FILES ${oggfiles} DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/<replaceable>yourLanguageTwoLetterCode</replaceable> )
0156 INSTALL( FILES <replaceable>yourLanguageTwoLetterCode</replaceable>.soundtheme DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/ )
0157 </programlisting>
0158       </listitem>
0159     </itemizedlist>
0160   </listitem>
0161 
0162   <listitem><para>If you want to install it for yourself:</para>
0163     <itemizedlist>
0164       <listitem><para>Place <filename><replaceable>yourLanguageTwoLetterCode</replaceable>.soundtheme</filename>
0165       file into the <filename class="directory">ktuberling/sounds</filename> folder in
0166       <userinput><command>qtpaths</command> <option>--paths GenericDataLocation</option></userinput></para></listitem>
0167       <listitem><para>Place your sound files into the
0168       <filename class="directory">ktuberling/sounds/<replaceable>someUniquePath</replaceable></filename> folder in
0169       <userinput><command>qtpaths</command> <option>--paths GenericDataLocation</option></userinput></para></listitem>
0170     </itemizedlist>
0171   </listitem>
0172 </itemizedlist>
0173 
0174 <para>
0175 Information on how to work with the translation mechanisms in &kde; is available
0176 in <ulink url="https://l10n.kde.org/docs/translation-howto/index.html">The
0177 &kde; Translation HOWTO</ulink>.
0178 </para>
0179 
0180 </sect1>
0181 
0182 <sect1 id="for-programmers">
0183 
0184 <title>For Programmers</title>
0185 <para>&ktuberling; isn't really difficult to extend for programmers.</para>
0186 
0187 <sect2 id="classes">
0188 <title>C++ classes</title>
0189 
0190 <variablelist>
0191   <varlistentry>
0192     <term><classname>TopLevel</classname></term>
0193     <listitem><para>Top-level window and basic program management.</para></listitem>
0194   </varlistentry>
0195 
0196   <varlistentry>
0197     <term><classname>PlayGround</classname></term>
0198     <listitem><para>Description of one of the game levels.</para></listitem>
0199   </varlistentry>
0200 
0201   <varlistentry>
0202     <term><classname>ToDraw</classname></term>
0203     <listitem><para>Description of one of the graphical <quote>objects</quote> to be
0204     drawn.</para></listitem>
0205   </varlistentry>
0206 
0207   <varlistentry>
0208     <term><classname>SoundFactory</classname></term>
0209     <listitem><para>Description of one of the languages and its sounds.</para></listitem>
0210   </varlistentry>
0211 
0212   <varlistentry>
0213     <term><classname>Action</classname></term>
0214     <listitem><para>One of the user's manipulation in the undo/redo stack.</para></listitem>
0215   </varlistentry>
0216 </variablelist>
0217 
0218 </sect2>
0219 
0220 </sect1>
0221 </chapter>