1/* This file is part of the KDE libraries
2 Copyright (C) 1999,2000 Kurt Granroth <granroth@kde.org>
3 Copyright (C) 2001,2002 Ellis Whitehead <ellis@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19#ifndef KSTANDARDACTION_H
20#define KSTANDARDACTION_H
21
22#include <kdeui_export.h>
23#include <kstandardshortcut.h>
24#include <QtCore/QList>
25
26class QObject;
27class QStringList;
28class QWidget;
29class KAction;
30class KRecentFilesAction;
31class KDualAction;
32class KToggleAction;
33class KToggleFullScreenAction;
34
35
36/**
37 * Convenience methods to access all standard KDE actions.
38 *
39 * These actions should be used instead of hardcoding menubar and
40 * toolbar items. Using these actions helps your application easily
41 * conform to the KDE UI Style Guide
42 * @see http://developer.kde.org/documentation/standards/kde/style/basics/index.html .
43 *
44 * All of the documentation for KAction holds for KStandardAction
45 * also. When in doubt on how things work, check the KAction
46 * documention first.
47 * Please note that calling any of these methods automatically adds the action
48 * to the actionCollection() of the QObject given by the 'parent' parameter.
49 *
50 * <b>Simple Example:</b>\n
51 *
52 * In general, using standard actions should be a drop in replacement
53 * for regular actions. For example, if you previously had:
54 *
55 * \code
56 * KAction *newAct = new KAction(i18n("&New"), KIcon("document-new"),
57 * KStandardShortcut::shortcut(KStandardShortcut::New), this,
58 * SLOT(fileNew()), actionCollection());
59 * \endcode
60 *
61 * You could drop that and replace it with:
62 *
63 * \code
64 * KAction *newAct = KStandardAction::openNew(this, SLOT(fileNew()),
65 * actionCollection());
66 * \endcode
67 *
68 * <b>Non-standard Usages</b>\n
69 *
70 * It is possible to use the standard actions in various
71 * non-recommended ways. Say, for instance, you wanted to have a
72 * standard action (with the associated correct text and icon and
73 * accelerator, etc) but you didn't want it to go in the standard
74 * place (this is not recommended, by the way). One way to do this is
75 * to simply not use the XML UI framework and plug it into wherever
76 * you want. If you do want to use the XML UI framework (good!), then
77 * it is still possible.
78 *
79 * Basically, the XML building code matches names in the XML code with
80 * the internal names of the actions. You can find out the internal
81 * names of each of the standard actions by using the name
82 * method like so: KStandardAction::name(KStandardAction::Cut) would return
83 * 'edit_cut'. The XML building code will match 'edit_cut' to the
84 * attribute in the global XML file and place your action there.
85 *
86 * However, you can change the internal name. In this example, just
87 * do something like:
88 *
89 * \code
90 * (void)KStandardAction::cut(this, SLOT(editCut()), actionCollection(), "my_cut");
91 * \endcode
92 *
93 * Now, in your local XML resource file (e.g., yourappui.rc), simply
94 * put 'my_cut' where you want it to go.
95 *
96 * Another non-standard usage concerns getting a pointer to an
97 * existing action if, say, you want to enable or disable the action.
98 * You could do it the recommended way and just grab a pointer when
99 * you instantiate it as in the 'openNew' example above... or you
100 * could do it the hard way:
101 *
102 * \code
103 * KAction *cut = actionCollection()->action(KStandardAction::name(KStandardAction::Cut));
104 * \endcode
105 *
106 * Another non-standard usage concerns instantiating the action in the
107 * first place. Usually, you would use the member functions as
108 * shown above (e.g., KStandardAction::cut(this, SLOT, parent)). You
109 * may, however, do this using the enums provided. This author can't
110 * think of a reason why you would want to, but, hey, if you do,
111 * here's how:
112 *
113 * \code
114 * (void)KStandardAction::action(KStandardAction::New, this, SLOT(fileNew()), actionCollection());
115 * (void)KStandardAction::action(KStandardAction::Cut, this, SLOT(editCut()), actionCollection());
116 * \endcode
117 *
118 * @author Kurt Granroth <granroth@kde.org>
119 */
120namespace KStandardAction
121{
122 /**
123 * The standard menubar and toolbar actions.
124 */
125 enum StandardAction {
126 ActionNone,
127
128 // File Menu
129 New, Open, OpenRecent, Save, SaveAs, Revert, Close,
130 Print, PrintPreview, Mail, Quit,
131
132 // Edit Menu
133 Undo, Redo, Cut, Copy, Paste, SelectAll, Deselect, Find, FindNext, FindPrev,
134 Replace,
135
136 // View Menu
137 ActualSize, FitToPage, FitToWidth, FitToHeight, ZoomIn, ZoomOut,
138 Zoom, Redisplay,
139
140 // Go Menu
141 Up, Back, Forward, Home /*Home page*/, Prior, Next, Goto, GotoPage, GotoLine,
142 FirstPage, LastPage, DocumentBack, DocumentForward,
143
144 // Bookmarks Menu
145 AddBookmark, EditBookmarks,
146
147 // Tools Menu
148 Spelling,
149
150 // Settings Menu
151 ShowMenubar, ShowToolbar, ShowStatusbar,
152 SaveOptions, KeyBindings,
153 Preferences, ConfigureToolbars,
154
155 // Help Menu
156 Help, HelpContents, WhatsThis, ReportBug, AboutApp, AboutKDE,
157 TipofDay,
158
159 // Other standard actions
160 ConfigureNotifications,
161 FullScreen,
162 Clear,
163 PasteText,
164 SwitchApplicationLanguage
165 };
166
167 /**
168 * Creates an action corresponding to one of the
169 * KStandardAction::StandardAction actions, which is connected to the given
170 * object and @p slot, and is owned by @p parent.
171 *
172 * The signal that is connected to @p slot is triggered(bool), except for the case of
173 * OpenRecent standard action, which uses the urlSelected(const KUrl &) signal of
174 * KRecentFilesAction.
175 *
176 * @param id The StandardAction identifier to create a KAction for.
177 * @param recvr The QObject to receive the signal, or 0 if no notification
178 * is needed.
179 * @param slot The slot to connect the signal to (remember to use the SLOT() macro).
180 * @param parent The QObject that should own the created KAction, or 0 if no parent will
181 * own the KAction returned (ensure you delete it manually in this case).
182 */
183 KDEUI_EXPORT KAction* create(StandardAction id, const QObject *recvr, const char *slot,
184 QObject *parent);
185
186 /**
187 * This will return the internal name of a given standard action.
188 */
189 KDEUI_EXPORT const char* name( StandardAction id );
190
191 /// @deprecated use name()
192#ifndef KDE_NO_DEPRECATED
193 inline KDE_DEPRECATED const char* stdName(StandardAction act_enum) { return name( act_enum ); }
194#endif
195
196 /**
197 * Returns a list of all standard names. Used by KAccelManager
198 * to give those heigher weight.
199 */
200 KDEUI_EXPORT QStringList stdNames();
201
202 /**
203 * Returns a list of all actionIds.
204 *
205 * @since 4.2
206 */
207 KDEUI_EXPORT QList<StandardAction> actionIds();
208
209 /**
210 * Returns the standardshortcut associated with @a actionId.
211 *
212 * @param actionId The actionId whose associated shortcut is wanted.
213 *
214 * @since 4.2
215 */
216 KDEUI_EXPORT KStandardShortcut::StandardShortcut shortcutForActionId(StandardAction id);
217
218 /**
219 * Create a new document or window.
220 */
221 KDEUI_EXPORT KAction *openNew(const QObject *recvr, const char *slot, QObject *parent);
222
223 /**
224 * Open an existing file.
225 */
226 KDEUI_EXPORT KAction *open(const QObject *recvr, const char *slot, QObject *parent);
227
228 /**
229 * Open a recently used document. The signature of the slot being called
230 * is of the form slotURLSelected( const KUrl & ).
231 * @param recvr object to receive slot
232 * @param slot The SLOT to invoke when a URL is selected. The slot's
233 * signature is slotURLSelected( const KUrl & ).
234 * @param parent parent widget
235 */
236 KDEUI_EXPORT KRecentFilesAction *openRecent(const QObject *recvr, const char *slot, QObject *parent);
237
238 /**
239 * Save the current document.
240 */
241 KDEUI_EXPORT KAction *save(const QObject *recvr, const char *slot, QObject *parent);
242
243 /**
244 * Save the current document under a different name.
245 */
246 KDEUI_EXPORT KAction *saveAs(const QObject *recvr, const char *slot, QObject *parent);
247
248 /**
249 * Revert the current document to the last saved version
250 * (essentially will undo all changes).
251 */
252 KDEUI_EXPORT KAction *revert(const QObject *recvr, const char *slot, QObject *parent);
253
254 /**
255 * Close the current document.
256 */
257 KDEUI_EXPORT KAction *close(const QObject *recvr, const char *slot, QObject *parent);
258
259 /**
260 * Print the current document.
261 */
262 KDEUI_EXPORT KAction *print(const QObject *recvr, const char *slot, QObject *parent);
263
264 /**
265 * Show a print preview of the current document.
266 */
267 KDEUI_EXPORT KAction *printPreview(const QObject *recvr, const char *slot, QObject *parent);
268
269 /**
270 * Mail this document.
271 */
272 KDEUI_EXPORT KAction *mail(const QObject *recvr, const char *slot, QObject *parent);
273
274 /**
275 * Quit the program.
276 *
277 * Note that you probably want to connect this action to either QWidget::close()
278 * or QApplication::closeAllWindows(), but not QApplication::quit(), so that
279 * KMainWindow::queryClose() is called on any open window (to warn the user
280 * about unsaved changes for example).
281 */
282 KDEUI_EXPORT KAction *quit(const QObject *recvr, const char *slot, QObject *parent);
283
284 /**
285 * Undo the last operation.
286 */
287 KDEUI_EXPORT KAction *undo(const QObject *recvr, const char *slot, QObject *parent);
288
289 /**
290 * Redo the last operation.
291 */
292 KDEUI_EXPORT KAction *redo(const QObject *recvr, const char *slot, QObject *parent);
293
294 /**
295 * Cut selected area and store it in the clipboard.
296 * Calls cut() on the widget with the current focus.
297 */
298 KDEUI_EXPORT KAction *cut(QObject *parent);
299
300 /**
301 * Copy selected area and store it in the clipboard.
302 * Calls copy() on the widget with the current focus.
303 */
304 KDEUI_EXPORT KAction *copy(QObject *parent);
305
306 /**
307 * Paste the contents of clipboard at the current mouse or cursor
308 * Calls paste() on the widget with the current focus.
309 */
310 KDEUI_EXPORT KAction *paste(QObject *parent);
311
312 /**
313 * Clear selected area. Calls clear() on the widget with the current focus.
314 * Note that for some widgets, this may not provide the intended behavior. For
315 * example if you make use of the code above and a K3ListView has the focus, clear()
316 * will clear all of the items in the list. If this is not the intened behavior
317 * and you want to make use of this slot, you can subclass K3ListView and reimplement
318 * this slot. For example the following code would implement a K3ListView without this
319 * behavior:
320 *
321 * \code
322 * class MyListView : public K3ListView {
323 * Q_OBJECT
324 * public:
325 * MyListView( QWidget * parent = 0, const char * name = 0, WFlags f = 0 ) : K3ListView( parent, name, f ) {}
326 * virtual ~MyListView() {}
327 * public Q_SLOTS:
328 * virtual void clear() {}
329 * };
330 * \endcode
331 */
332 KDEUI_EXPORT KAction *clear(QObject *parent);
333
334 /**
335 * Calls selectAll() on the widget with the current focus.
336 */
337 KDEUI_EXPORT KAction *selectAll(QObject *parent);
338
339 /**
340 * Cut selected area and store it in the clipboard.
341 */
342 KDEUI_EXPORT KAction *cut(const QObject *recvr, const char *slot, QObject *parent);
343
344 /**
345 * Copy the selected area into the clipboard.
346 */
347 KDEUI_EXPORT KAction *copy(const QObject *recvr, const char *slot, QObject *parent);
348
349 /**
350 * Paste the contents of clipboard at the current mouse or cursor
351 * position.
352 */
353 KDEUI_EXPORT KAction *paste(const QObject *recvr, const char *slot, QObject *parent);
354
355 /**
356 * Paste the contents of clipboard at the current mouse or cursor
357 * position. Provide a button on the toolbar with the clipboard history
358 * menu if Klipper is running.
359 */
360 KDEUI_EXPORT KAction *pasteText(const QObject *recvr, const char *slot, QObject *parent);
361
362 /**
363 * Clear the content of the focus widget
364 */
365 KDEUI_EXPORT KAction *clear(const QObject *recvr, const char *slot, QObject *parent);
366
367 /**
368 * Select all elements in the current document.
369 */
370 KDEUI_EXPORT KAction *selectAll(const QObject *recvr, const char *slot, QObject *parent);
371
372 /**
373 * Deselect any selected elements in the current document.
374 */
375 KDEUI_EXPORT KAction *deselect(const QObject *recvr, const char *slot, QObject *parent);
376
377 /**
378 * Initiate a 'find' request in the current document.
379 */
380 KDEUI_EXPORT KAction *find(const QObject *recvr, const char *slot, QObject *parent);
381
382 /**
383 * Find the next instance of a stored 'find'.
384 */
385 KDEUI_EXPORT KAction *findNext(const QObject *recvr, const char *slot, QObject *parent);
386
387 /**
388 * Find a previous instance of a stored 'find'.
389 */
390 KDEUI_EXPORT KAction *findPrev(const QObject *recvr, const char *slot, QObject *parent);
391
392 /**
393 * Find and replace matches.
394 */
395 KDEUI_EXPORT KAction *replace(const QObject *recvr, const char *slot, QObject *parent);
396
397 /**
398 * View the document at its actual size.
399 */
400 KDEUI_EXPORT KAction *actualSize(const QObject *recvr, const char *slot, QObject *parent);
401
402 /**
403 * Fit the document view to the size of the current window.
404 */
405 KDEUI_EXPORT KAction *fitToPage(const QObject *recvr, const char *slot, QObject *parent);
406
407 /**
408 * Fit the document view to the width of the current window.
409 */
410 KDEUI_EXPORT KAction *fitToWidth(const QObject *recvr, const char *slot, QObject *parent);
411
412 /**
413 * Fit the document view to the height of the current window.
414 */
415 KDEUI_EXPORT KAction *fitToHeight(const QObject *recvr, const char *slot, QObject *parent);
416
417 /**
418 * Zoom in.
419 */
420 KDEUI_EXPORT KAction *zoomIn(const QObject *recvr, const char *slot, QObject *parent);
421
422 /**
423 * Zoom out.
424 */
425 KDEUI_EXPORT KAction *zoomOut(const QObject *recvr, const char *slot, QObject *parent);
426
427 /**
428 * Popup a zoom dialog.
429 */
430 KDEUI_EXPORT KAction *zoom(const QObject *recvr, const char *slot, QObject *parent);
431
432 /**
433 * Redisplay or redraw the document.
434 */
435 KDEUI_EXPORT KAction *redisplay(const QObject *recvr, const char *slot, QObject *parent);
436
437 /**
438 * Move up (web style menu).
439 */
440 KDEUI_EXPORT KAction *up(const QObject *recvr, const char *slot, QObject *parent);
441
442 /**
443 * Move back (web style menu).
444 */
445 KDEUI_EXPORT KAction *back(const QObject *recvr, const char *slot, QObject *parent);
446
447 /**
448 * Move forward (web style menu).
449 */
450 KDEUI_EXPORT KAction *forward(const QObject *recvr, const char *slot, QObject *parent);
451
452 /**
453 * Go to the "Home" position or document.
454 */
455 KDEUI_EXPORT KAction *home(const QObject *recvr, const char *slot, QObject *parent);
456
457 /**
458 * Scroll up one page.
459 */
460 KDEUI_EXPORT KAction *prior(const QObject *recvr, const char *slot, QObject *parent);
461
462 /**
463 * Scroll down one page.
464 */
465 KDEUI_EXPORT KAction *next(const QObject *recvr, const char *slot, QObject *parent);
466
467 /**
468 * Go to somewhere in general.
469 */
470 KDEUI_EXPORT KAction *goTo(const QObject *recvr, const char *slot, QObject *parent);
471
472
473 /**
474 * Go to a specific page (dialog).
475 */
476 KDEUI_EXPORT KAction *gotoPage(const QObject *recvr, const char *slot, QObject *parent);
477
478 /**
479 * Go to a specific line (dialog).
480 */
481 KDEUI_EXPORT KAction *gotoLine(const QObject *recvr, const char *slot, QObject *parent);
482
483 /**
484 * Jump to the first page.
485 */
486 KDEUI_EXPORT KAction *firstPage(const QObject *recvr, const char *slot, QObject *parent);
487
488 /**
489 * Jump to the last page.
490 */
491 KDEUI_EXPORT KAction *lastPage(const QObject *recvr, const char *slot, QObject *parent);
492
493 /**
494 * Move back (document style menu).
495 */
496 KDEUI_EXPORT KAction *documentBack(const QObject *recvr, const char *slot, QObject *parent);
497
498 /**
499 * Move forward (document style menu).
500 */
501 KDEUI_EXPORT KAction *documentForward(const QObject *recvr, const char *slot, QObject *parent);
502
503 /**
504 * Add the current page to the bookmarks tree.
505 */
506 KDEUI_EXPORT KAction *addBookmark(const QObject *recvr, const char *slot, QObject *parent);
507
508 /**
509 * Edit the application bookmarks.
510 */
511 KDEUI_EXPORT KAction *editBookmarks(const QObject *recvr, const char *slot, QObject *parent);
512
513 /**
514 * Pop up the spell checker.
515 */
516 KDEUI_EXPORT KAction *spelling(const QObject *recvr, const char *slot, QObject *parent);
517
518
519 /**
520 * Show/Hide the menubar.
521 */
522 KDEUI_EXPORT KToggleAction *showMenubar(const QObject *recvr, const char *slot, QObject *parent);
523
524 /**
525 * Show/Hide the statusbar.
526 */
527 KDEUI_EXPORT KToggleAction *showStatusbar(const QObject *recvr, const char *slot, QObject *parent);
528
529 /**
530 * Switch to/from full screen mode
531 */
532 KDEUI_EXPORT KToggleFullScreenAction *fullScreen(const QObject *recvr, const char *slot, QWidget *window, QObject *parent);
533
534 /**
535 * Display the save options dialog.
536 */
537 KDEUI_EXPORT KAction *saveOptions(const QObject *recvr, const char *slot, QObject *parent);
538
539 /**
540 * Display the configure key bindings dialog.
541 *
542 * Note that you might be able to use the pre-built KXMLGUIFactory's function:
543 * KStandardAction::keyBindings(guiFactory(), SLOT(configureShortcuts()), actionCollection());
544 */
545 KDEUI_EXPORT KAction *keyBindings(const QObject *recvr, const char *slot, QObject *parent);
546
547 /**
548 * Display the preferences/options dialog.
549 */
550 KDEUI_EXPORT KAction *preferences(const QObject *recvr, const char *slot, QObject *parent);
551
552 /**
553 * The Customize Toolbar dialog.
554 */
555 KDEUI_EXPORT KAction *configureToolbars(const QObject *recvr, const char *slot, QObject *parent);
556
557 /**
558 * The Configure Notifications dialog.
559 */
560 KDEUI_EXPORT KAction *configureNotifications(const QObject *recvr, const char *slot, QObject *parent);
561
562 /**
563 * Display the help.
564 */
565 KDEUI_EXPORT KAction *help(const QObject *recvr, const char *slot, QObject *parent);
566
567 /**
568 * Display the help contents.
569 */
570 KDEUI_EXPORT KAction *helpContents(const QObject *recvr, const char *slot, QObject *parent);
571
572 /**
573 * Trigger the What's This cursor.
574 */
575 KDEUI_EXPORT KAction *whatsThis(const QObject *recvr, const char *slot, QObject *parent);
576
577 /**
578 * Display "Tip of the Day"
579 */
580 KDEUI_EXPORT KAction *tipOfDay(const QObject *recvr, const char *slot, QObject *parent);
581
582 /**
583 * Open up the Report Bug dialog.
584 */
585 KDEUI_EXPORT KAction *reportBug(const QObject *recvr, const char *slot, QObject *parent);
586
587 /**
588 * Display the application's About box.
589 */
590 KDEUI_EXPORT KAction *aboutApp(const QObject *recvr, const char *slot, QObject *parent);
591
592 /**
593 * Display the About KDE dialog.
594 */
595 KDEUI_EXPORT KAction *aboutKDE(const QObject *recvr, const char *slot, QObject *parent);
596}
597
598#endif // KSTDACTION_H
599