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>
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.
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.
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.
19
#ifndef KSTANDARDACTION_H
20
#define KSTANDARDACTION_H
26
class KActionCollection;
27
class KRecentFilesAction;
29
class KToggleToolBarAction;
30
class KToggleFullScreenAction;
32
#include <kdelibs_export.h>
35
* Convenience methods to access all standard KDE actions.
37
* These actions should be used instead of hardcoding menubar and
38
* toolbar items. Using these actions helps your application easily
39
* conform to the KDE UI Style Guide
40
* @see http://developer.kde.org/documentation/standards/kde/style/basics/index.html .
42
* All of the documentation for KAction holds for KStandardAction
43
* also. When in doubt on how things work, check the KAction
46
* <b>Simple Example:</b>\n
48
* In general, using standard actions should be a drop in replacement
49
* for regular actions. For example, if you previously had:
52
* KAction *newAct = new KAction(i18n("&New"), KIcon("filenew"),
53
* KStandardShortcut::shortcut(KStandardShortcut::New), this,
54
* SLOT(fileNew()), actionCollection());
57
* You could drop that and replace it with:
60
* KAction *newAct = KStandardAction::openNew(this, SLOT(fileNew()),
61
* actionCollection());
64
* <b>Non-standard Usages</b>\n
66
* It is possible to use the standard actions in various
67
* non-recommended ways. Say, for instance, you wanted to have a
68
* standard action (with the associated correct text and icon and
69
* accelerator, etc) but you didn't want it to go in the standard
70
* place (this is not recommended, by the way). One way to do this is
71
* to simply not use the XML UI framework and plug it into wherever
72
* you want. If you do want to use the XML UI framework (good!), then
73
* it is still possible.
75
* Basically, the XML building code matches names in the XML code with
76
* the internal names of the actions. You can find out the internal
77
* names of each of the standard actions by using the stdName
78
* action like so: KStandardAction::stdName(KStandardAction::Cut) would return
79
* 'edit_cut'. The XML building code will match 'edit_cut' to the
80
* attribute in the global XML file and place your action there.
82
* However, you can change the internal name. In this example, just
86
* (void)KStandardAction::cut(this, SLOT(editCut()), actionCollection(), "my_cut");
89
* Now, in your local XML resource file (e.g., yourappui.rc), simply
90
* put 'my_cut' where you want it to go.
92
* Another non-standard usage concerns getting a pointer to an
93
* existing action if, say, you want to enable or disable the action.
94
* You could do it the recommended way and just grab a pointer when
95
* you instantiate it as in the the 'openNew' example above... or you
96
* could do it the hard way:
99
* KAction *cut = actionCollection()->action(KStandardAction::stdName(KStandardAction::Cut));
102
* Another non-standard usage concerns instantiating the action in the
103
* first place. Usually, you would use the member functions as
104
* shown above (e.g., KStandardAction::cut(this, SLOT, parent)). You
105
* may, however, do this using the enums provided. This author can't
106
* think of a reason why you would want to, but, hey, if you do,
110
* (void)KStandardAction::action(KStandardAction::New, this, SLOT(fileNew()), actionCollection());
111
* (void)KStandardAction::action(KStandardAction::Cut, this, SLOT(editCut()), actionCollection());
114
* @author Kurt Granroth <granroth@kde.org>
116
namespace KStandardAction
119
* The standard menubar and toolbar actions.
121
enum StandardAction {
125
New, Open, OpenRecent, Save, SaveAs, Revert, Close,
126
Print, PrintPreview, Mail, Quit,
129
Undo, Redo, Cut, Copy, Paste, SelectAll, Deselect, Find, FindNext, FindPrev,
133
ActualSize, FitToPage, FitToWidth, FitToHeight, ZoomIn, ZoomOut,
137
Up, Back, Forward, Home, Prior, Next, Goto, GotoPage, GotoLine,
141
AddBookmark, EditBookmarks,
147
ShowMenubar, ShowToolbar, ShowStatusbar,
148
SaveOptions, KeyBindings,
149
Preferences, ConfigureToolbars,
152
Help, HelpContents, WhatsThis, ReportBug, AboutApp, AboutKDE,
155
// Another settings menu item
156
ConfigureNotifications,
163
* Creates an action corresponding to the
164
* KStandardAction::StandardAction enum.
166
KDEUI_EXPORT KAction* create(StandardAction id, const QObject *recvr, const char *slot,
170
* This will return the internal name of a given standard action.
172
KDEUI_EXPORT const char* name( StandardAction id );
174
/// @obsolete. Use name()
175
inline const char* stdName(StandardAction act_enum) { return name( act_enum ); }
178
* Returns a list of all standard names. Used by KAccelManager
179
* to give those heigher weight.
181
KDEUI_EXPORT QStringList stdNames();
184
* Create a new document or window.
186
KDEUI_EXPORT KAction *openNew(const QObject *recvr, const char *slot, QObject *parent);
189
* Open an existing file.
191
KDEUI_EXPORT KAction *open(const QObject *recvr, const char *slot, QObject *parent);
194
* Open a recently used document. The signature of the slot being called
195
* is of the form slotURLSelected( const KUrl & ).
196
* @param recvr object to receive slot
197
* @param slot The SLOT to invoke when a URL is selected. The slot's
198
* signature is slotURLSelected( const KUrl & ).
199
* @param parent parent widget
200
* @param name name of widget
202
KDEUI_EXPORT KRecentFilesAction *openRecent(const QObject *recvr, const char *slot, QObject *parent);
205
* Save the current document.
207
KDEUI_EXPORT KAction *save(const QObject *recvr, const char *slot, QObject *parent);
210
* Save the current document under a different name.
212
KDEUI_EXPORT KAction *saveAs(const QObject *recvr, const char *slot, QObject *parent);
215
* Revert the current document to the last saved version
216
* (essentially will undo all changes).
218
KDEUI_EXPORT KAction *revert(const QObject *recvr, const char *slot, QObject *parent);
221
* Close the current document.
223
KDEUI_EXPORT KAction *close(const QObject *recvr, const char *slot, QObject *parent);
226
* Print the current document.
228
KDEUI_EXPORT KAction *print(const QObject *recvr, const char *slot, QObject *parent);
231
* Show a print preview of the current document.
233
KDEUI_EXPORT KAction *printPreview(const QObject *recvr, const char *slot, QObject *parent);
236
* Mail this document.
238
KDEUI_EXPORT KAction *mail(const QObject *recvr, const char *slot, QObject *parent);
243
KDEUI_EXPORT KAction *quit(const QObject *recvr, const char *slot, QObject *parent);
246
* Undo the last operation.
248
KDEUI_EXPORT KAction *undo(const QObject *recvr, const char *slot, QObject *parent);
251
* Redo the last operation.
253
KDEUI_EXPORT KAction *redo(const QObject *recvr, const char *slot, QObject *parent);
256
* Cut selected area and store it in the clipboard.
257
* Calls cut() on the widget with the current focus.
259
KDEUI_EXPORT KAction *cut(QObject *parent);
262
* Copy selected area and store it in the clipboard.
263
* Calls copy() on the widget with the current focus.
265
KDEUI_EXPORT KAction *copy(QObject *parent);
268
* Paste the contents of clipboard at the current mouse or cursor
269
* Calls paste() on the widget with the current focus.
271
KDEUI_EXPORT KAction *paste(QObject *parent);
274
* Clear selected area. Calls clear() on the widget with the current focus.
275
* Note that for some widgets, this may not provide the intended bahavior. For
276
* example if you make use of the code above and a K3ListView has the focus, clear()
277
* will clear all of the items in the list. If this is not the intened behavior
278
* and you want to make use of this slot, you can subclass K3ListView and reimplement
279
* this slot. For example the following code would implement a K3ListView without this
283
* class MyListView : public K3ListView {
286
* MyListView( QWidget * parent = 0, const char * name = 0, WFlags f = 0 ) : K3ListView( parent, name, f ) {}
287
* virtual ~MyListView() {}
289
* virtual void clear() {}
293
KDEUI_EXPORT KAction *clear(QObject *parent);
296
* Calls selectAll() on the widget with the current focus.
298
KDEUI_EXPORT KAction *selectAll(QObject *parent);
301
* Cut selected area and store it in the clipboard.
303
KDEUI_EXPORT KAction *cut(const QObject *recvr, const char *slot, QObject *parent);
306
* Copy the selected area into the clipboard.
308
KDEUI_EXPORT KAction *copy(const QObject *recvr, const char *slot, QObject *parent);
311
* Paste the contents of clipboard at the current mouse or cursor
314
KDEUI_EXPORT KAction *paste(const QObject *recvr, const char *slot, QObject *parent);
317
* Paste the contents of clipboard at the current mouse or cursor
318
* position. Provide a button on the toolbar with the clipboard history
319
* menu if Klipper is running.
321
KDEUI_EXPORT KAction *pasteText(const QObject *recvr, const char *slot, QObject *parent);
324
* Clear the content of the focus widget
326
KDEUI_EXPORT KAction *clear(const QObject *recvr, const char *slot, QObject *parent);
329
* Select all elements in the current document.
331
KDEUI_EXPORT KAction *selectAll(const QObject *recvr, const char *slot, QObject *parent);
334
* Deselect any selected elements in the current document.
336
KDEUI_EXPORT KAction *deselect(const QObject *recvr, const char *slot, QObject *parent);
339
* Initiate a 'find' request in the current document.
341
KDEUI_EXPORT KAction *find(const QObject *recvr, const char *slot, QObject *parent);
344
* Find the next instance of a stored 'find'.
346
KDEUI_EXPORT KAction *findNext(const QObject *recvr, const char *slot, QObject *parent);
349
* Find a previous instance of a stored 'find'.
351
KDEUI_EXPORT KAction *findPrev(const QObject *recvr, const char *slot, QObject *parent);
354
* Find and replace matches.
356
KDEUI_EXPORT KAction *replace(const QObject *recvr, const char *slot, QObject *parent);
359
* View the document at its actual size.
361
KDEUI_EXPORT KAction *actualSize(const QObject *recvr, const char *slot, QObject *parent);
364
* Fit the document view to the size of the current window.
366
KDEUI_EXPORT KAction *fitToPage(const QObject *recvr, const char *slot, QObject *parent);
369
* Fit the document view to the width of the current window.
371
KDEUI_EXPORT KAction *fitToWidth(const QObject *recvr, const char *slot, QObject *parent);
374
* Fit the document view to the height of the current window.
376
KDEUI_EXPORT KAction *fitToHeight(const QObject *recvr, const char *slot, QObject *parent);
381
KDEUI_EXPORT KAction *zoomIn(const QObject *recvr, const char *slot, QObject *parent);
386
KDEUI_EXPORT KAction *zoomOut(const QObject *recvr, const char *slot, QObject *parent);
389
* Popup a zoom dialog.
391
KDEUI_EXPORT KAction *zoom(const QObject *recvr, const char *slot, QObject *parent);
394
* Redisplay or redraw the document.
396
KDEUI_EXPORT KAction *redisplay(const QObject *recvr, const char *slot, QObject *parent);
399
* Move up (web style menu).
401
KDEUI_EXPORT KAction *up(const QObject *recvr, const char *slot, QObject *parent);
404
* Move back (web style menu).
406
KDEUI_EXPORT KAction *back(const QObject *recvr, const char *slot, QObject *parent);
409
* Move forward (web style menu).
411
KDEUI_EXPORT KAction *forward(const QObject *recvr, const char *slot, QObject *parent);
414
* Go to the "Home" position or document.
416
KDEUI_EXPORT KAction *home(const QObject *recvr, const char *slot, QObject *parent);
419
* Scroll up one page.
421
KDEUI_EXPORT KAction *prior(const QObject *recvr, const char *slot, QObject *parent);
424
* Scroll down one page.
426
KDEUI_EXPORT KAction *next(const QObject *recvr, const char *slot, QObject *parent);
429
* Go to somewhere in general.
431
KDEUI_EXPORT KAction *goTo(const QObject *recvr, const char *slot, QObject *parent);
435
* Go to a specific page (dialog).
437
KDEUI_EXPORT KAction *gotoPage(const QObject *recvr, const char *slot, QObject *parent);
440
* Go to a specific line (dialog).
442
KDEUI_EXPORT KAction *gotoLine(const QObject *recvr, const char *slot, QObject *parent);
445
* Jump to the first page.
447
KDEUI_EXPORT KAction *firstPage(const QObject *recvr, const char *slot, QObject *parent);
450
* Jump to the last page.
452
KDEUI_EXPORT KAction *lastPage(const QObject *recvr, const char *slot, QObject *parent);
455
* Add the current page to the bookmarks tree.
457
KDEUI_EXPORT KAction *addBookmark(const QObject *recvr, const char *slot, QObject *parent);
460
* Edit the application bookmarks.
462
KDEUI_EXPORT KAction *editBookmarks(const QObject *recvr, const char *slot, QObject *parent);
465
* Pop up the spell checker.
467
KDEUI_EXPORT KAction *spelling(const QObject *recvr, const char *slot, QObject *parent);
471
* Show/Hide the menubar.
473
KDEUI_EXPORT KToggleAction *showMenubar(const QObject *recvr, const char *slot, QObject *parent);
476
* Show/Hide the statusbar.
478
KDEUI_EXPORT KToggleAction *showStatusbar(const QObject *recvr, const char *slot, QObject *parent);
481
* Switch to/from full screen mode
483
KDEUI_EXPORT KToggleFullScreenAction *fullScreen(const QObject *recvr, const char *slot, QWidget *window, QObject *parent);
486
* Display the save options dialog.
488
KDEUI_EXPORT KAction *saveOptions(const QObject *recvr, const char *slot, QObject *parent);
491
* Display the configure key bindings dialog.
493
* Note that you might be able to use the pre-built KXMLGUIFactory's function:
494
* KStandardAction::keyBindings(guiFactory(), SLOT(configureShortcuts()), actionCollection());
496
KDEUI_EXPORT KAction *keyBindings(const QObject *recvr, const char *slot, QObject *parent);
499
* Display the preferences/options dialog.
501
KDEUI_EXPORT KAction *preferences(const QObject *recvr, const char *slot, QObject *parent);
504
* The Customize Toolbar dialog.
506
KDEUI_EXPORT KAction *configureToolbars(const QObject *recvr, const char *slot, QObject *parent);
509
* The Configure Notifications dialog.
511
KDEUI_EXPORT KAction *configureNotifications(const QObject *recvr, const char *slot, QObject *parent);
516
KDEUI_EXPORT KAction *help(const QObject *recvr, const char *slot, QObject *parent);
519
* Display the help contents.
521
KDEUI_EXPORT KAction *helpContents(const QObject *recvr, const char *slot, QObject *parent);
524
* Trigger the What's This cursor.
526
KDEUI_EXPORT KAction *whatsThis(const QObject *recvr, const char *slot, QObject *parent);
529
* Display "Tip of the Day"
531
KDEUI_EXPORT KAction *tipOfDay(const QObject *recvr, const char *slot, QObject *parent);
534
* Open up the Report Bug dialog.
536
KDEUI_EXPORT KAction *reportBug(const QObject *recvr, const char *slot, QObject *parent);
539
* Display the application's About box.
541
KDEUI_EXPORT KAction *aboutApp(const QObject *recvr, const char *slot, QObject *parent);
544
* Display the About KDE dialog.
546
KDEUI_EXPORT KAction *aboutKDE(const QObject *recvr, const char *slot, QObject *parent);
549
#endif // KSTDACTION_H