summaryrefslogtreecommitdiffstats
path: root/kdeui/ktip.h
diff options
context:
space:
mode:
Diffstat (limited to 'kdeui/ktip.h')
-rw-r--r--kdeui/ktip.h192
1 files changed, 192 insertions, 0 deletions
diff --git a/kdeui/ktip.h b/kdeui/ktip.h
new file mode 100644
index 000000000..f11978343
--- /dev/null
+++ b/kdeui/ktip.h
@@ -0,0 +1,192 @@
+/*****************************************************************
+
+Copyright (c) 2000-2003 Matthias Hoelzer-Kluepfel <mhk@kde.org>
+ Tobias Koenig <tokoe@kde.org>
+ Daniel Molkentin <molkentin@kde.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+******************************************************************/
+
+#ifndef __K_TIP_H__
+#define __K_TIP_H__
+
+#include <qstringlist.h>
+
+#include <kdialog.h>
+
+class QCheckBox;
+
+class KTextBrowser;
+
+/**
+ * A database for tips-of-the-day.
+ *
+ * This class provides convenient access to a database containing
+ * tips of the day. The database is stored in a XML file and parsed
+ * when a KTipDatabase object is created.
+ *
+ * Once the file is read in, you can access the tips to display
+ * them in the tip of the day dialog.
+ *
+ * The state of the tipdialog is saved to the applications's config file
+ * in the group "TipOfDay" with a bool entry "RunOnStart". Check this value
+ * if you want to allow the user to enable/disable the tipdialog in the
+ * application's configuration dialog.
+ *
+ * @author Matthias Hoelzer-Kluepfel <mhk@kde.org>
+ *
+ */
+class KDEUI_EXPORT KTipDatabase
+{
+public:
+ /**
+ * This constructor reads in the tips from a file with the given name. If
+ * no name is given, a file called 'application-name/tips' will be loaded.
+ *
+ * @param tipFile The absolute path to the tips file.
+ */
+ KTipDatabase(const QString &tipFile = QString::null);
+
+ /**
+ * This constructor takes a list of files that will be merged. This constructor
+ * essentially behaves like the one above. It returns when tipFiles is empty.
+ *
+ * @param tipFiles A list of absolute paths to the tips file
+ */
+ KTipDatabase(const QStringList &tipFiles);
+
+ /**
+ * Returns the current tip.
+ */
+ QString tip() const;
+
+ /**
+ * The next tip will become the current one.
+ */
+ void nextTip();
+
+ /**
+ * The previous tip will become the current one.
+ */
+ void prevTip();
+
+private:
+ void loadTips(const QString &tipFile);
+
+ void addTips(const QString &tipFile);
+
+ QStringList mTips;
+
+ int mCurrent;
+ class KTipDatabasePrivate;
+ KTipDatabasePrivate *d;
+};
+
+/**
+ * A Tip-of-the-Day dialog.
+ *
+ * This dialog class presents a tip-of-the-day.
+ *
+ * @author Matthias Hoelzer-Kluepfel <mhk@caldera.de>
+ */
+class KDEUI_EXPORT KTipDialog : public KDialog
+{
+ Q_OBJECT
+public:
+ /**
+ * Construct a tip dialog.
+ *
+ * @param db TipDatabase that should be used by the TipDialog.
+ * @param parent Parent widget of TipDialog.
+ * @param name The object name.
+ */
+ KTipDialog(KTipDatabase *db, QWidget *parent = 0, const char *name = 0);
+ ~KTipDialog();
+
+ /**
+ * Shows a tip.
+ *
+ * This static method is all that is needed to add a tip-of-the-day
+ * dialog to an application. It will pop up the dialog, unless the
+ * user has asked that the dialog does not pop up on startup.
+ *
+ * Note that you probably want an item in the help menu calling
+ * this method with force=true.
+ *
+ * @param parent Parent widget of TipDialog.
+ * @param tipFile The name of the tip file. It has be relative to the "data"
+ * resource of KStandardDirs
+ * @param force If true, the dialog is show, even when the users
+ * disabled it.
+ */
+ static void showTip(QWidget *parent, const QString &tipFile = QString::null, bool force=false);
+
+ /**
+ * Shows a tip
+ *
+ * This method behaves essentially as the one above, but expects a list of tips
+ *
+ * @param parent Parent widget of TipDialog.
+ * @param tipFiles A List of tip files. Each has be relative to the "data"
+ * resource of KStandardDirs
+ * @param force If true, the dialog is show, even when the users
+ * disabled it.
+ */
+ static void showMultiTip(QWidget *parent, const QStringList &tipFiles, bool force=false);
+
+ /**
+ * Shows a tip.
+ *
+ * This methods calls showTip() with the applications main window as parent.
+ *
+ */
+ static void showTip(const QString &tipFile = QString::null, bool force = false);
+
+ /**
+ * Toggles the start behavior.
+ *
+ * Normally, the user can disable the display of the tip in the dialog.
+ * This is just a way to change this setting from outside.
+ */
+ static void setShowOnStart(bool show);
+
+protected:
+ bool eventFilter(QObject *, QEvent *);
+ virtual void virtual_hook( int id, void* data );
+
+private slots:
+ void nextTip();
+ void prevTip();
+ void showOnStart(bool);
+
+private:
+ KTipDatabase *mDatabase;
+
+ QCheckBox *mTipOnStart;
+ KTextBrowser *mTipText;
+
+ class KTipDialogPrivate;
+ KTipDialogPrivate *d;
+
+ static KTipDialog *mInstance;
+
+ QColor mBaseColor, mBlendedColor, mTextColor;
+};
+
+#endif