1/* This file is part of the KDE libraries
2 Copyright (C) 2001 Holger Freyther <freyther@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef kstandardguiitem_h
20#define kstandardguiitem_h
21
22#include <kdeui_export.h>
23
24#include <QtCore/QPair>
25
26#include <kguiitem.h>
27
28class QString;
29
30/**
31 * @short Provides a set of standardized KGuiItems.
32 *
33 * The various KDEUI_EXPORT methods returns standardized @ref KGuiItem's
34 * conforming to the KDE UI Standards. Use them instead of creating
35 * your own.
36 *
37 * @author Holger Freyther <freyther@kde.org>
38 */
39namespace KStandardGuiItem
40{
41 /**
42 * The back and forward items by default use the RTL settings for Hebrew
43 * and Arab countries. If you want those actions to ignore the RTL value
44 * and force 'Western' behavior instead, use the IgnoreRTL value instead.
45 */
46 enum BidiMode { UseRTL = 0, IgnoreRTL };
47
48 enum StandardItem
49 {
50 Ok=1, Cancel, Yes, No, Discard, Save, DontSave, SaveAs, Apply, Clear,
51 Help, Defaults, Close, Back, Forward, Print, Continue, Open, Quit,
52 AdminMode, Reset, Delete, Insert, Configure, Find, Stop, Add, Remove,
53 Test, Properties, Overwrite, CloseWindow, CloseDocument
54 };
55
56 /**
57 * Returns the gui item for the given identifier @param id.
58 *
59 * @param id the identifier to search for
60 */
61 KDEUI_EXPORT KGuiItem guiItem( StandardItem id );
62
63 /**
64 * Returns the name of the gui item for the given identifier @param id.
65 *
66 * @param id the identifier to search for
67 */
68 KDEUI_EXPORT QString standardItem( StandardItem id );
69
70 /**
71 * Returns the 'Ok' gui item.
72 */
73 KDEUI_EXPORT KGuiItem ok();
74
75 /**
76 * Returns the 'Cancel' gui item.
77 */
78 KDEUI_EXPORT KGuiItem cancel();
79
80 /**
81 * Returns the 'Yes' gui item.
82 */
83 KDEUI_EXPORT KGuiItem yes();
84
85 /**
86 * Returns the 'No' gui item.
87 */
88 KDEUI_EXPORT KGuiItem no();
89
90 /**
91 * Returns the 'Insert' gui item.
92 */
93 KDEUI_EXPORT KGuiItem insert();
94
95 /**
96 * Returns the 'Discard' gui item.
97 */
98 KDEUI_EXPORT KGuiItem discard();
99
100 /**
101 * Returns the 'Save' gui item.
102 */
103 KDEUI_EXPORT KGuiItem save();
104
105 /**
106 * Returns the 'Help' gui item.
107 */
108 KDEUI_EXPORT KGuiItem help();
109
110 /**
111 * Returns the 'DontSave' gui item.
112 */
113 KDEUI_EXPORT KGuiItem dontSave();
114
115 /**
116 * Returns the 'SaveAs' gui item.
117 */
118 KDEUI_EXPORT KGuiItem saveAs();
119
120 /**
121 * Returns the 'Apply' gui item.
122 */
123 KDEUI_EXPORT KGuiItem apply();
124
125 /**
126 * Returns the 'Clear' gui item.
127 */
128 KDEUI_EXPORT KGuiItem clear();
129
130 /**
131 * Returns the 'Defaults' gui item.
132 */
133 KDEUI_EXPORT KGuiItem defaults();
134
135 /**
136 * Returns the 'Close' gui item.
137 */
138 KDEUI_EXPORT KGuiItem close();
139
140 /**
141 * Returns the 'CloseWindow' gui item.
142 * @since 4.3
143 */
144 KDEUI_EXPORT KGuiItem closeWindow();
145
146 /**
147 * Returns the 'CloseDocument' gui item.
148 * @since 4.3
149 */
150 KDEUI_EXPORT KGuiItem closeDocument();
151
152 /**
153 * Returns the 'Print' gui item.
154 */
155 KDEUI_EXPORT KGuiItem print();
156
157 /**
158 * Returns the 'Properties' gui item.
159 */
160 KDEUI_EXPORT KGuiItem properties();
161
162 /**
163 * Returns the 'Reset' gui item.
164 */
165 KDEUI_EXPORT KGuiItem reset();
166
167 /**
168 * Returns the 'Overwrite' gui item.
169 */
170 KDEUI_EXPORT KGuiItem overwrite();
171
172 /**
173 * Returns a KGuiItem suiting for cases where code or functionality
174 * runs under root privileges. Used in conjunction with KConfig Modules.
175 */
176 KDEUI_EXPORT KGuiItem adminMode();
177
178 /**
179 * Returns the 'Continue' gui item. The short name is due to 'continue' being a
180 * reserved word in the C++ language.
181 */
182 KDEUI_EXPORT KGuiItem cont();
183
184 /**
185 * Returns the 'Delete' gui item. The short name is due to 'delete' being a
186 * reserved word in the C++ language.
187 */
188 KDEUI_EXPORT KGuiItem del();
189
190 /**
191 * Returns the 'Open' gui item.
192 */
193 KDEUI_EXPORT KGuiItem open();
194
195 /**
196 * Returns the 'Back' gui item, like Konqueror's back button.
197 * This GUI item can optionally honor the user's setting for BiDi, so the
198 * icon for right-to-left languages (Hebrew and Arab) has the arrow
199 * pointing in the opposite direction.
200 * By default the arrow points in the Western 'back' direction (i.e.
201 * to the left). This is because usually you only want the Bidi aware
202 * GUI item if you also want the 'forward' item. Those two are available
203 * in the separate backAndForward() method.
204 */
205 KDEUI_EXPORT KGuiItem back( BidiMode useBidi = IgnoreRTL );
206
207 /**
208 * Returns the 'Forward' gui item, like Konqueror's forward
209 * button. This GUI item can optionally honor the user's setting for BiDi,
210 * so the icon for right-to-left languages (Hebrew and Arab) has the arrow
211 * pointing in the opposite direction.
212 * By default the arrow points in the Western 'forward' direction (i.e.
213 * to the right). This is because usually you only want the Bidi aware
214 * GUI item if you also want the 'back' item. Those two are available
215 * in the separate backAndForward() method.
216 */
217 KDEUI_EXPORT KGuiItem forward( BidiMode useBidi = IgnoreRTL );
218
219 /**
220 * Returns the 'Configure' gui item.
221 */
222 KDEUI_EXPORT KGuiItem configure();
223
224 /**
225 * Return both a back and a forward gui item. This function always returns
226 * items that are aware of the Right-to-Left setting for Arab and Hebrew
227 * locales. If you have a reason for wanting the 'Western' back/forward
228 * buttons, please use the back() and forward() items instead.
229 */
230 KDEUI_EXPORT QPair<KGuiItem, KGuiItem> backAndForward();
231
232 /**
233 * Returns the 'Quit' gui item.
234 */
235 KDEUI_EXPORT KGuiItem quit();
236
237 /**
238 * Returns the 'Find' gui item.
239 */
240 KDEUI_EXPORT KGuiItem find();
241
242 /**
243 * Returns the 'Stop' gui item.
244 */
245 KDEUI_EXPORT KGuiItem stop();
246
247 /**
248 * Returns the 'Add' gui item.
249 */
250 KDEUI_EXPORT KGuiItem add();
251
252 /**
253 * Returns the 'Remove' gui item.
254 */
255 KDEUI_EXPORT KGuiItem remove();
256
257 /**
258 * Returns the 'Test' gui item.
259 */
260 KDEUI_EXPORT KGuiItem test();
261
262}
263
264#endif
265