kmymoney/developer-doc/phb/settings.docbook

<chapter id="settings">
<chapterinfo>
<authorgroup>
<author>
        <firstname>Alvaro</firstname>
        <surname>Soliverez</surname>
        <affiliation>
                <address><email>asoliverez@gmail.com</email></address>
        </affiliation>
</author>
</authorgroup>
</chapterinfo>
<title>Settings</title>

<sect1 id="settings-page">
<title>How to create a settings page</title>

<itemizedlist>
<listitem>
<para>
Create the view using designer, name it XxxDecl and store it in <filename>kmymoney2/dialogs/settings/xxxdecl.ui</filename>. See more information about naming the items further down
</para>
</listitem>
<listitem>
<para>
Create the class that contains the logic for the settings page, name it Xxx and store it in <filename>kmymoney2/dialogs/settings/xxx.[cpp|h]</filename>.
</para>
<para>
Don't forget the Q_OBJECT macro at the beginning of the class declaration in the .h file and make the class a public derivative of XxxDecl 
</para>
</listitem>
<listitem>
<para>
Add the xxxdecl.ui and xxx.cpp filename to the libsettings_a_SOURCES label in <filename>kmymoney2/dialogs/settings/Makefile.am</filename>
</para>
</listitem>
<listitem>
<para>
Add the xxxdecl.ui filename to the EXTRA_DIST label in <filename>kmymoney2/dialogs/settings/Makefile.am</filename>
</para>
</listitem>
<listitem>
<para>
Add the xxxdecl.cpp and xxxdecl.h filename to the DISTCLEANFILES label in <filename>kmymoney2/dialogs/settings/Makefile.am</filename>
</para>
</listitem>
<listitem>
<para>
Add the xxx.h filename to the noinst_HEADERS label in <filename>kmymoney2/dialogs/settings/Makefile.am</filename>
</para>
</listitem>
<listitem>
<para>
Add the construction code to KMyMoney2App::slotSettings() as
</para>
<screen>
Xxx* xxxPage = new Xxx();
dlg->addPage(xxxPage, i18n("text"), "icon-name");
</screen>
<para>
where you replace "text" with a short text that shows up under the icon in the settings view and "icon-name" with the name of the icon for that settings page
</para>
</listitem>
<listitem>
<para>
Make sure to include xxx.h in <filename>kmymoney/kmymoney2.cpp</filename>
</para>
</listitem>
</itemizedlist>
</sect1>

<sect1 id="settings-items">
<title>How to add the setting items</title>

<para>
For auto-generation of setter/getter code of your options, you have to follow certain rules. For each setting item you need an entry in <filename>kmymoney2/kmymoney2.kcfg</filename>. This is an XML formatted file. The contents of the 'name' attribute will be used as method for the C++-code, eg. a name of "AutoSavePeriod" for an integer parameter results in a setter and getter named
</para>
<screen>
void KMyMoneySettings::setAutoSavePeriod(int)
int KMyMoneySettings::autoSavePeriod(void)
</screen>
<para>
You should not access those functions directly from within your code but rather use the KMyMoneyGlobalSettings class which contains the same interface as KMyMoneySettings with some additional functionality.
</para>

<para>
When you name the GUI widget that controls the setting for this parameter make sure to name it "kcfg_AutoSavePeriod", that is "kcfg_" prepended with the name used in <filename>kmymoney2/kmymoney2.kcfg</filename>.
</para>

<para>
That should be it.
</para>
</sect1>

<sect1 id="settings-reference">
<title>References</title>

<para>
A more complete - but generic version - can be found on <ulink url="http://techbase.kde.org/Development/Tutorials/Using_TDEConfig_XT">http://techbase.kde.org/Development/Tutorials/Using_TDEConfig_XT</ulink> . Currently, &app; does not use the <filename>CMakeLists.txt</filename> file but the above mentioned <filename>Makefile.am</filename> approach. You can safely skip the section about CMakeLists.txt.
</para>
</sect1>

<sect1 id="settings-hints">
<title>Hints</title>
<para>
If you run a make 'too early' it could be, that certain entries for the Makefile are not setup correctly and the compiler will complain. In this case, try to run a 'make -f Makefile.dist' followed by './configure' and see if the problem goes away.
</para>
</sect1>
</chapter>