summaryrefslogtreecommitdiffstats
path: root/kmymoney2/widgets/kmymoneywizard.h
diff options
context:
space:
mode:
authortpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2011-07-04 22:38:03 +0000
committertpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2011-07-04 22:38:03 +0000
commitdadc34655c3ab961b0b0b94a10eaaba710f0b5e8 (patch)
tree99e72842fe687baea16376a147619b6048d7e441 /kmymoney2/widgets/kmymoneywizard.h
downloadkmymoney-dadc34655c3ab961b0b0b94a10eaaba710f0b5e8.tar.gz
kmymoney-dadc34655c3ab961b0b0b94a10eaaba710f0b5e8.zip
Added kmymoney
git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kmymoney@1239792 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kmymoney2/widgets/kmymoneywizard.h')
-rw-r--r--kmymoney2/widgets/kmymoneywizard.h539
1 files changed, 539 insertions, 0 deletions
diff --git a/kmymoney2/widgets/kmymoneywizard.h b/kmymoney2/widgets/kmymoneywizard.h
new file mode 100644
index 0000000..21b57b4
--- /dev/null
+++ b/kmymoney2/widgets/kmymoneywizard.h
@@ -0,0 +1,539 @@
+/***************************************************************************
+ kmymoneywizard.h
+ -------------------
+ copyright : (C) 2006 by Thomas Baumagrt
+ email : ipwizard@users.sourceforge.net
+ ***************************************************************************/
+
+/***************************************************************************
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ ***************************************************************************/
+
+#ifndef KMYMONEYWIZARD_H
+#define KMYMONEYWIZARD_H
+
+// ----------------------------------------------------------------------------
+// QT Includes
+
+#include <qdialog.h>
+#include <qvaluelist.h>
+#include <qpalette.h>
+class QVBoxLayout;
+class QHBoxLayout;
+class QLabel;
+class QFrame;
+
+// ----------------------------------------------------------------------------
+// KDE Includes
+
+class KPushButton;
+
+// ----------------------------------------------------------------------------
+// Project Includes
+
+class KMyMoneyTitleLabel;
+class KMyMoneyWizard;
+class KMyMoneyWizardPagePrivate;
+class kMandatoryFieldGroup;
+
+/**
+ * @author Thomas Baumgart (C) 2006
+ *
+ * @note: the following documentation is somewhat outdated
+ * as of May 2007. Wizards should use a namespace
+ * for the pages and can use the WizardPage<T> template class.
+ * See the NewUserWizard class and NewUserWizardPages namespace
+ * as an example of this setup.
+ *
+ * This class represents the base class for wizard pages for the
+ * KMyMoneyWizard. One cannot create a wizard page directly, but
+ * must derive from it. The KMyMoneyWizardPage class provides the
+ * necessary functionality to work in concert with KMyMoneyWizard.
+ *
+ * Therefore, few steps are necessary to use this class. They seem to
+ * be awkward at some stage, but I wanted to be able to use Qt designer
+ * to actually design the widget for the page. That's why some things
+ * aren't implemented in a more straight fashion than one would
+ * normally do this.
+ *
+ * The first step is to derive a specific base page for the specific wizard.
+ * In this example we use the name NewUser as template for the specific wizard.
+ * This class provides a 'back'-pointer to the actual wizard object
+ * for all pages.
+ *
+ * @code
+ * class KNewUserPage : public KMyMoneyWizardPage
+ * {
+ * public:
+ * KNewUserPage(unsigned int step, QWidget* widget, KNewUserWizard* parent, const char* name);
+ *
+ * protected:
+ * KNewUserWizard* m_wizard;
+ * }
+ * @endcode
+ *
+ * The implementation of this class is rather straight-forward:
+ *
+ * @code
+ * KNewUserPage::KNewUserPage(unsigned int step, QWidget* widget, KNewUserWizard* parent, const char* name) :
+ * KMyMoneyWizardPage(step, widget, name),
+ * m_wizard(parent)
+ * {
+ * }
+ * @endcode
+ *
+ * For each page of the wizard, you will have to create a @p ui file with
+ * Qt designer.
+ * Let's assume we call the first page of the wizard 'General' and go
+ * from there.
+ * We also assume, that the wizard has more than one page.
+ * The ui designer generated class should have the name KNewUserGeneralDecl
+ * as all other dialogs. The class definition of KNewUserGeneral will
+ * look like this:
+ *
+ * @code
+ * class KNewUserGeneral : public KNewUserGeneralDecl, public KNewUserPage
+ * {
+ * Q_OBJECT
+ * public:
+ * KNewUserGeneral(KNewUserWizard* parent, const char* name = 0);
+ * KMyMoneyWizardPage* nextPage(void);
+ * bool isLastPage(void) { return false; }
+ *
+ * protected:
+ * KNewUserWizard* m_wizard;
+ * }
+ * @endcode
+ *
+ * The implementation depends heavily on the logic of your code. If you only
+ * fill some widgets, it could be as simple as:
+ *
+ * @code
+ * KNewUserGeneral::KNewUserGeneral(KNewUserWizard* parent, const char* name) :
+ * KNewUserGeneralDecl(parent),
+ * KNewUserPage(1, this, parent, name)
+ * {
+ * kMandatoryFieldGroup* mandatoryGroup = new kMandatoryFieldGroup(this);
+ * mandatoryGroup->add(m_userName);
+ * connect(m_mandatoryGroup, SIGNAL(stateChanged()), object(), SIGNAL(completeStateChanged()));
+ * }
+ *
+ * KMyMoneyWizardPage* KNewUserGeneral::nextPage(void)
+ * {
+ * return m_wizard->m_personalPage;
+ * }
+ * @endcode
+ *
+ * A note on the first parameter to KNewUserPage in the above example: it ties
+ * this page to be part of step 1 (see KMyMoneyWizard::addStep() for details).
+ *
+ * Depending on the actual logic of the page, you would want to override the
+ * following methods: resetPage, nextPage, isLastPage and isComplete.
+ *
+ * @note The implementation of this class is heavily based on ideas found at
+ * http://doc.trolltech.com/4.1/dialogs-complexwizard.html
+ */
+class KMyMoneyWizardPage
+{
+public:
+ /**
+ * This method is called by the wizard when the page is entered from
+ * the previous page. The default implementation does nothing.
+ */
+ virtual void enterPage(void);
+
+ /**
+ * This method is called by the wizard when the page is left to return to
+ * the previous page. The default implementation does nothing.
+ */
+ virtual void leavePage(void);
+
+ /**
+ * This method is called by the wizard whenever a page is entered
+ * (either in forward or backward direction). The default
+ * implementation does nothing.
+ */
+ virtual void resetPage(void);
+
+ /**
+ * This method returns a pointer to the next page that should be
+ * shown when the user presses the 'Next' button.
+ *
+ * @return pointer to next wizard page
+ */
+ virtual KMyMoneyWizardPage* nextPage(void) const;
+
+ /**
+ * This returns, if the current page is the last page of the wizard.
+ * The default implementation returns @p false if nextPage() returns 0,
+ * @p true otherwise.
+ *
+ * @retval false more pages follow
+ * @retval true this is the last page of the wizard
+ */
+ virtual bool isLastPage(void) const;
+
+ /**
+ * This returns, if all necessary data for this page has been
+ * filled. It is used to enabled the 'Next' or 'Finish' button.
+ * The button is only enabled, if this method returns @p true,
+ * which is the default implementation.
+ *
+ * @retval false more data required from the user before we can proceed
+ * @retval true all data available, we allow to switch to the next page
+ */
+ virtual bool isComplete(void) const;
+
+ /**
+ * This method returns the step to which this page belongs.
+ * It is required by the KMyMoneyWizard and is not intended
+ * to be used by application code.
+ *
+ * @return step of wizard this page belongs to
+ */
+ unsigned int step(void) const { return m_step; }
+
+ /**
+ * This method returns a pointer to the widget of the page.
+ * It is required by the KMyMoneyWizard and is not intended
+ * to be used by application code.
+ *
+ * @return pointer to widget of page
+ */
+ QWidget* widget(void) const { return m_widget; }
+
+ /**
+ * This method returns a pointer to the QObject used for
+ * the signal/slot mechanism.
+ * It is required by the KMyMoneyWizard and can be used
+ * by application code for signal/slot connections as well.
+ * Other use is not foreseen.
+ */
+ QObject* object(void) const;
+
+ /**
+ * This method returns a pointer to the widget which should
+ * receive the focus when the page is opened.
+ *
+ * @return pointer to widget or 0 if none is to be selected
+ * The default implementation returns 0
+ */
+ virtual QWidget* initialFocusWidget(void) const { return 0; }
+
+ virtual KMyMoneyWizard* wizard(void) const = 0;
+
+ /**
+ * This method returns a specific help context for the page shown
+ * The default returns an empty string.
+ */
+ virtual const QString& helpContext(void) const;
+
+ virtual ~KMyMoneyWizardPage() {}
+protected:
+ /**
+ * Constructor (kept protected, so that one cannot create such an object directly)
+ */
+ KMyMoneyWizardPage(unsigned int step, QWidget* widget, const char* name = 0);
+
+ /**
+ * This method must be called by the implementation when the
+ * data in the fields of the wizard change and the state of
+ * completeness changed.
+ *
+ * @note If you do not override isComplete() then there is no need
+ * to call this method.
+ */
+ void completeStateChanged(void) const;
+
+protected:
+ kMandatoryFieldGroup* m_mandatoryGroup;
+
+private:
+ unsigned int m_step;
+ QWidget* m_widget;
+ KMyMoneyWizardPagePrivate* const d;
+};
+
+
+/**
+ * The general base class for wizard pages
+ *
+ * @author Thomas Baumgart
+ */
+template <class T>
+ class WizardPage : public KMyMoneyWizardPage
+{
+public:
+ WizardPage(unsigned int step, QWidget* widget, T* parent, const char* name) :
+ KMyMoneyWizardPage(step, widget, name),
+ m_wizard(parent),
+ m_wizardBase(parent)
+ {
+ }
+ virtual ~WizardPage() {}
+ virtual KMyMoneyWizard* wizard(void) const { return m_wizardBase; }
+
+protected:
+ T* m_wizard;
+ KMyMoneyWizard* m_wizardBase;
+};
+
+
+/**
+ * @author Thomas Baumgart (C) 2006
+ *
+ * This is a base class for implementation of the KMyMoneyWizard. It provides
+ * the following layout of a wizard:
+ *
+ * @code
+ * +-wizardLayout-----------------------------------------------+
+ * | |
+ * +------------------------------------------------------------+
+ * |+-stepLayout--++-------------------------------------------+|
+ * || ||+-pageLayout------------------------------+||
+ * || ||| |||
+ * || ||| |||
+ * || ||| |||
+ * || ||| |||
+ * || ||| |||
+ * || ||| |||
+ * || ||+-----------------------------------------+||
+ * || |||+-buttonLayout--------------------------+|||
+ * || |||| ||||
+ * || |||+---------------------------------------+|||
+ * || ||+-----------------------------------------+||
+ * |+-------------++-------------------------------------------+|
+ * +------------------------------------------------------------+
+ * @endcode
+ *
+ * The top bar is filled with a KMyMoneyTitleLabel as known from
+ * KMyMoney's views. To the left there is an area in the same color
+ * as the title bar showing the steps for this wizard. Each such step
+ * can consist of one or more wizard pages. At the bottom of this area
+ * the text "Step x of y" is shown and updated. To the right of this
+ * part, the actual wizard page is shown. At the bottom of the page
+ * the class inserts a standard button widget consisting of a Help,
+ * Back, Next/Finish and Cancel button.
+ *
+ * The wizard serves as container for the wizard pages. In order to access
+ * the data filled into the pages, one would have to provide getter methods.
+ *
+ * Here is an example how this object could be used. Please also see the
+ * example described with the KMyMoneyWizardPage class.
+ *
+ * @code
+ *
+ * class KNewUserGeneral;
+ * class KNewUserPersonal;
+ *
+ * class KNewUserWizard : public KMyMoneyWizard
+ * {
+ * Q_OBJECT
+ * public:
+ * KNewUserWizard(QWidget* parent = 0, const char* name = 0, bool modal = false, WFlags flags = 0);
+ *
+ * private:
+ * KNewUserGeneral* m_generalPage;
+ * KNewUserPersonal* m_personalPage;
+ * KNewUserFinal* m_finalPage;
+ * // add more pages here
+ *
+ * friend class KNewUserGeneral;
+ * friend class KNewUserPersonal;
+ * friend class KNewUserFinal;
+ * // add more pages here
+ * };
+ * @endcode
+ *
+ * The implementation is also easy and looks like this:
+ *
+ * @code
+ * KNewUserWizard::KNewUserWizard(QWidget* parent, const char* name, bool modal, WFlags flags) :
+ * KMyMoneyWizard(parent, name, modal, flags)
+ * {
+ * setTitle("KMyMoney New User Setup");
+ * addStep("General Data");
+ * addStep("Personal Data");
+ * addStep("Finish");
+ *
+ * m_generalPage = new KNewUserGeneral(this);
+ * m_personalPage = new KNewUserPersonal(this);
+ * m_finalPage = new KNewUserFinal(this);
+ *
+ * setFirstPage(m_testPage1);
+ * }
+ * @endcode
+ *
+ * Don't forget to call setFirstPage() to get things started.
+ *
+ * The code to use this whole structure would then look something like this:
+ *
+ * @code
+ * KNewUserWizard* wizard = new KNewUserWizard(this, "NewUserWizard");
+ * int rc = wizard->exec();
+ * @endcode
+ *
+ * The return code of exec() is either @p QDialog::Accepted or
+ * @p QDialog::Rejected.
+ *
+ * @note The implementation of this class is heavily based on ideas found at
+ * http://doc.trolltech.com/4.1/dialogs-complexwizard.html
+ */
+class KMyMoneyWizard : public QDialog
+{
+ friend class KMyMoneyWizardPage;
+
+ Q_OBJECT
+public:
+ /**
+ * Modify the title of the wizard to be @p txt.
+ *
+ * @param txt The text that should be used as title
+ */
+ void setTitle(const QString& txt);
+
+ /**
+ * Add step @p text to the wizard
+ *
+ * @param text Text to be shown for this step
+ */
+ void addStep(const QString& text);
+
+ QValueList<KMyMoneyWizardPage*> historyPages(void) const { return m_history; }
+
+ /**
+ * This method repeats selection of the current step in the
+ * step frame.
+ * This is used to allow changes made to showing and hiding
+ * pages to immediately to be reflected in the step frame
+ */
+ void reselectStep(void);
+
+ /**
+ * Setup a global help context for the wizard. It will be used whenever
+ * there is no specific help context available for the current page.
+ *
+ * @sa KMyMoneyWizardPage::helpContext()
+ */
+ void setHelpContext(const QString& ctx) { m_helpContext = ctx; }
+
+ virtual ~KMyMoneyWizard(){}
+
+signals:
+ /**
+ * This signal is sent out, when a new payee needs to be created
+ * @sa KMyMoneyCombo::createItem()
+ *
+ * @param txt The name of the payee to be created
+ * @param id A connected slot should store the id of the created object in this variable
+ */
+ void createPayee(const QString& txt, QString& id);
+
+ /**
+ * This signal is sent out, when a new category needs to be created
+ * @sa KMyMoneyCombo::createItem()
+ *
+ * @param txt The name of the category to be created
+ * @param id A connected slot should store the id of the created object in this variable
+ */
+ void createCategory(const QString& txt, QString& id);
+
+protected:
+ /**
+ * Constructor (kept protected, so that one cannot create such an object directly)
+ */
+ KMyMoneyWizard(QWidget *parent = 0, const char *name = 0, bool modal = false, WFlags f = 0);
+
+ /**
+ * This method sets up the first page after creation of the object
+ *
+ * @param page pointer to first page of wizard
+ */
+ void setFirstPage(KMyMoneyWizardPage* page);
+
+ /**
+ * This method allows to hide or show a @p step.
+ *
+ * @param step step to be shown/hidden
+ * @param hidden hide step if true (the default) or show it if false
+ */
+ void setStepHidden(unsigned int step, bool hidden = true);
+
+protected slots:
+ virtual void accept(void);
+ void completeStateChanged(void);
+
+private:
+ void updateStepCount(void);
+
+private slots:
+ void backButtonClicked(void);
+ void nextButtonClicked(void);
+ void helpButtonClicked(void);
+
+protected:
+ /*
+ * The buttons
+ */
+ KPushButton* m_cancelButton;
+ KPushButton* m_backButton;
+ KPushButton* m_nextButton;
+ KPushButton* m_finishButton;
+ KPushButton* m_helpButton;
+
+private:
+ /**
+ * Switch to page which is currently the top of the history stack.
+ * @p oldPage is a pointer to the current page or 0 if no page
+ * is shown.
+ *
+ * @param oldPage pointer to currently displayed page
+ */
+ void switchPage(KMyMoneyWizardPage* oldPage);
+
+ /**
+ * This method selects the step given by @p step.
+ *
+ * @param step step to be selected
+ */
+ void selectStep(unsigned int step);
+
+ /*
+ * The layouts
+ */
+ QVBoxLayout* m_wizardLayout;
+ QVBoxLayout* m_stepLayout;
+ QVBoxLayout* m_pageLayout;
+ QHBoxLayout* m_buttonLayout;
+
+ /*
+ * Some misc. widgets required
+ */
+ QFrame* m_stepFrame;
+ QLabel* m_stepLabel;
+ QPalette m_stepPalette;
+
+ QValueList<QLabel*> m_steps; // the list of step labels
+ int m_step; // the currently selected step
+
+ /*
+ * The title bar
+ */
+ KMyMoneyTitleLabel* m_titleLabel;
+
+ /*
+ * The history stack
+ */
+ QValueList<KMyMoneyWizardPage*> m_history;
+
+ QString m_helpContext;
+};
+
+
+
+#endif