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 | |
26 | class QObject; |
27 | class QStringList; |
28 | class QWidget; |
29 | class KAction; |
30 | class KRecentFilesAction; |
31 | class KDualAction; |
32 | class KToggleAction; |
33 | class 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 | */ |
120 | namespace 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 | |