1 | /***************************************************************** |
2 | |
3 | Copyright (c) 2000-2003 Matthias Hoelzer-Kluepfel <mhk@kde.org> |
4 | Tobias Koenig <tokoe@kde.org> |
5 | Daniel Molkentin <molkentin@kde.org> |
6 | |
7 | Permission is hereby granted, free of charge, to any person obtaining a copy |
8 | of this software and associated documentation files (the "Software"), to deal |
9 | in the Software without restriction, including without limitation the rights |
10 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
11 | copies of the Software, and to permit persons to whom the Software is |
12 | furnished to do so, subject to the following conditions: |
13 | |
14 | The above copyright notice and this permission notice shall be included in |
15 | all copies or substantial portions of the Software. |
16 | |
17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
18 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
19 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
20 | AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN |
21 | AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
22 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
23 | |
24 | ******************************************************************/ |
25 | |
26 | #ifndef KTIP_H |
27 | #define KTIP_H |
28 | |
29 | #include <QtCore/QStringList> |
30 | |
31 | #include <kdialog.h> |
32 | |
33 | /** |
34 | * A database for tips-of-the-day. |
35 | * |
36 | * This class provides convenient access to a database containing |
37 | * tips of the day. The database is stored in a XML file and parsed |
38 | * when a KTipDatabase object is created. |
39 | * |
40 | * Once the file is read in, you can access the tips to display |
41 | * them in the tip of the day dialog. |
42 | * |
43 | * The state of the tipdialog is saved to the applications's config file |
44 | * in the group "TipOfDay" with a bool entry "RunOnStart". Check this value |
45 | * if you want to allow the user to enable/disable the tipdialog in the |
46 | * application's configuration dialog. |
47 | * |
48 | * \image html ktip.png "KDE Tip-of-the-Day Dialog" |
49 | * |
50 | * @author Matthias Hoelzer-Kluepfel <mhk@kde.org> |
51 | * |
52 | */ |
53 | class KDEUI_EXPORT KTipDatabase |
54 | { |
55 | public: |
56 | /** |
57 | * This constructor reads in the tips from a file with the given name. If |
58 | * no name is given, a file called 'application-name/tips' will be loaded. |
59 | * |
60 | * @param tipFile The absolute path to the tips file. |
61 | */ |
62 | explicit KTipDatabase( const QString &tipFile = QString() ); |
63 | |
64 | /** |
65 | * This constructor takes a list of files that will be merged. This constructor |
66 | * essentially behaves like the one above. It returns when tipFiles is empty. |
67 | * |
68 | * @param tipFiles A list of absolute paths to the tips file |
69 | */ |
70 | explicit KTipDatabase( const QStringList &tipFiles ); |
71 | |
72 | ~KTipDatabase(); |
73 | |
74 | /** |
75 | * Returns the current tip. |
76 | */ |
77 | QString tip() const; |
78 | |
79 | /** |
80 | * The next tip will become the current one. |
81 | */ |
82 | void nextTip(); |
83 | |
84 | /** |
85 | * The previous tip will become the current one. |
86 | */ |
87 | void prevTip(); |
88 | |
89 | private: |
90 | class Private; |
91 | Private* const d; |
92 | |
93 | Q_DISABLE_COPY( KTipDatabase ) |
94 | }; |
95 | |
96 | /** |
97 | * A Tip-of-the-Day dialog. |
98 | * |
99 | * This dialog class presents a tip-of-the-day. |
100 | * |
101 | * @author Matthias Hoelzer-Kluepfel <mhk@caldera.de> |
102 | */ |
103 | class KDEUI_EXPORT KTipDialog : public KDialog |
104 | { |
105 | Q_OBJECT |
106 | |
107 | public: |
108 | /** |
109 | * Construct a tip dialog. |
110 | * |
111 | * @param database TipDatabase that should be used by the TipDialog. The KTipDialog |
112 | * will take ownership of the database, including deleting it. |
113 | * @param parent Parent widget of TipDialog. |
114 | */ |
115 | explicit KTipDialog( KTipDatabase *database, QWidget *parent = 0 ); |
116 | |
117 | /** |
118 | * Destroys the tip dialog. |
119 | */ |
120 | ~KTipDialog(); |
121 | |
122 | /** |
123 | * Shows a tip. |
124 | * |
125 | * This static method is all that is needed to add a tip-of-the-day |
126 | * dialog to an application. It will pop up the dialog, unless the |
127 | * user has asked that the dialog does not pop up on startup. |
128 | * |
129 | * Note that you probably want an item in the help menu calling |
130 | * this method with force=true. |
131 | * |
132 | * @param parent Parent widget of TipDialog. |
133 | * @param tipFile The name of the tip file. It has be relative to the "data" |
134 | * resource of KStandardDirs |
135 | * @param force If true, the dialog is show, even when the users |
136 | * disabled it. |
137 | */ |
138 | static void showTip( QWidget *parent, const QString &tipFile = QString(), bool force = false ); |
139 | |
140 | /** |
141 | * Shows a tip |
142 | * |
143 | * This method behaves essentially as the one above, but expects a list of tips |
144 | * |
145 | * @param parent Parent widget of TipDialog. |
146 | * @param tipFiles A List of tip files. Each has be relative to the "data" |
147 | * resource of KStandardDirs |
148 | * @param force If true, the dialog is show, even when the users |
149 | * disabled it. |
150 | */ |
151 | static void showMultiTip( QWidget *parent, const QStringList &tipFiles, bool force = false ); |
152 | |
153 | /** |
154 | * Shows a tip. |
155 | * |
156 | * This methods calls showTip() with the applications main window as parent. |
157 | * |
158 | */ |
159 | static void showTip( const QString &tipFile = QString(), bool force = false ); |
160 | |
161 | /** |
162 | * Toggles the start behavior. |
163 | * |
164 | * Normally, the user can disable the display of the tip in the dialog. |
165 | * This is just a way to change this setting from outside. |
166 | */ |
167 | static void setShowOnStart( bool show ); |
168 | |
169 | protected: |
170 | bool eventFilter( QObject*, QEvent* ); |
171 | |
172 | private: |
173 | class Private; |
174 | Private* const d; |
175 | |
176 | Q_PRIVATE_SLOT( d, void _k_nextTip() ) |
177 | Q_PRIVATE_SLOT( d, void _k_prevTip() ) |
178 | Q_PRIVATE_SLOT( d, void _k_showOnStart( bool ) ) |
179 | Q_DISABLE_COPY(KTipDialog) |
180 | }; |
181 | |
182 | #endif |
183 | |
184 | |