From dadc34655c3ab961b0b0b94a10eaaba710f0b5e8 Mon Sep 17 00:00:00 2001
From: tpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>
Date: Mon, 4 Jul 2011 22:38:03 +0000
Subject: Added kmymoney

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kmymoney@1239792 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
---
 developer-doc/phb/settings.docbook | 109 +++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 developer-doc/phb/settings.docbook

(limited to 'developer-doc/phb/settings.docbook')

diff --git a/developer-doc/phb/settings.docbook b/developer-doc/phb/settings.docbook
new file mode 100644
index 0000000..7bc592d
--- /dev/null
+++ b/developer-doc/phb/settings.docbook
@@ -0,0 +1,109 @@
+<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_KConfig_XT">http://techbase.kde.org/Development/Tutorials/Using_KConfig_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>
-- 
cgit v1.2.1