/* This file is part of the KDE libraries
Copyright (C) 1999,2000 Kurt Granroth <granroth@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
#ifndef KSTDACTION_H
#define KSTDACTION_H
class KRecentFilesAction;
class KToggleAction;
class KAction;
class QObject;
class KStdActionPrivate;
/**
* Convenience methods to access all standard KDE actions.
*
* These actions should be used instead of hardcoding menubar and
* toolbar items. Using these actions helps your application easily
* conform to the KDE UI Style Guide
* @see http://developer.kde.org/documentation/standards/kde/style/basics/index.html .
*
* All of the documentation for @ref KAction holds for @ref KStdAction
* also. When in doubt on how things work, check the @ref KAction
* documention first.
*
* @sect Simple Example:
*
* In general, using standard actions should be a drop in replacement
* for regular actions. For example, if you previously had:
*
* <PRE>
* KAction *newAct = new KAction(i18n("&New"), QIconSet(BarIcon("filenew")),
* KStdAccel::key(KStdAccel::New), this,
* SLOT(fileNew()), actionCollection());
* </PRE>
*
* You could drop that and replace it with:
*
* <PRE>
* KAction *newAct = KStdAction::openNew(this, SLOT(fileNew()),
* actionCollection());
* </PRE>
*
* @sect Non-standard Usages
*
* It is possible to use the standard actions in various
* non-recommended ways. Say, for instance, you wanted to have a
* standard action (with the associated correct text and icon and
* accelerator, etc) but you didn't want it to go in the standard
* place (this is not recommended, by the way). One way to do this is
* to simply not use the XML UI framework and plug it into wherever
* you want. If you do want to use the XML UI framework (good!), then
* it is still possible.
*
* Basically, the XML building code matches names in the XML code with
* the internal names of the actions. You can find out the internal
* names of each of the standard actions by using the @ref stdName
* action like so: @ref KStdAction::stdName(KStdAction::Cut) would return
* 'edit_cut'. The XML building code will match 'edit_cut' to the
* attribute in the global XML file and place your action there.
*
* However, you can change the internal name. In this example, just
* do something like:
*
* <PRE>
* (void)KStdAction::cut(this, SLOT(editCut()), actionCollection(), "my_cut");
* </PRE>
*
* Now, in your local XML resource file (e.g., yourappui.rc), simply
* put 'my_cut' where you want it to go.
*
* Another non-standard usage concerns getting a pointer to an
* existing action if, say, you want to enable or disable the action.
* You could do it the recommended way and just grab a pointer when
* you instantiate it as in the the 'openNew' example above... or you
* could do it the hard way:
*
* <pre>
* KAction *cut = actionCollection()->action(KStdAction::stdName(KStdAction::Cut));
* </pre>
*
* Another non-standard usage concerns instantiating the action in the
* first place. Usually, you would use the static member functions as
* shown above (e.g., KStdAction::cut(this, SLOT, parent)). You
* may, however, do this using the enums provided. This author can't
* think of a reason why you would want to, but, hey, if you do,
* here's how:
*
* <pre>
* (void)KStdAction::action(KStdAction::New, this, SLOT(fileNew()), actionCollection());
* (void)KStdAction::action(KStdAction::Cut, this, SLOT(editCut()), actionCollection());
* </pre>
*
* @author Kurt Granroth <granroth@kde.org>
*/
class KStdAction
{
public:
/**
* The standard menubar and toolbar actions.
**/
enum StdAction {
// File Menu
New=1, Open, OpenRecent, Save, SaveAs, Revert, Close,
Print, PrintPreview, Mail, Quit,
// Edit Menu
Undo, Redo, Cut, Copy, Paste, SelectAll, Find, FindNext, FindPrev,
Replace,
// View Menu
ActualSize, FitToPage, FitToWidth, FitToHeight, ZoomIn, ZoomOut,
Zoom, Redisplay,
// Go Menu
Up, Back, Forward, Home, Prior, Next, Goto, GotoPage, GotoLine,
FirstPage, LastPage,
// Bookmarks Menu
AddBookmark, EditBookmarks,
// Tools Menu
Spelling,
// Settings Menu
ShowMenubar, ShowToolbar, ShowStatusbar, SaveOptions, KeyBindings,
Preferences, ConfigureToolbars,
// Help Menu
Help, HelpContents, WhatsThis, ReportBug, AboutApp, AboutKDE,
// NULL entries for possible later use
NULL1, NULL2, NULL3, NULL4, NULL5, NULL6, NULL7, NULL8, NULL9,
NULL10, NULL11, NULL12, NULL13, NULL14, NULL15, NULL16, NULL17,
NULL18, NULL19, NULL20
};
/**
* Constructor.
**/
KStdAction();
/**
* Destructor.
**/
~KStdAction();
/**
* Retrieve the action corresponding to the
* @ref KStdAction::StdAction enum.
*/
static KAction *action(StdAction act_enum, const QObject *recvr = 0,
const char *slot = 0, QObject *parent = 0,
const char *name = 0L );
/**
* This will return the internal name of a given standard action.
*/
static const char* stdName(StdAction act_enum);
/** Create a new document or window. */
static KAction *openNew(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Open an existing file.
*/
static KAction *open(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Open a recently used document.
*/
static KRecentFilesAction *openRecent(const QObject *recvr = 0,
const char *slot = 0,
QObject *parent = 0,
const char *name = 0L );
/**
* Save the current document.
*/
static KAction *save(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Save the current document under a different name.
*/
static KAction *saveAs(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Revert the current document to the last saved version
* (essentially will undo all changes).
*/
static KAction *revert(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Close the current document.
*/
static KAction *close(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Print the current document.
*/
static KAction *print(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Show a print preview of the current document.
*/
static KAction *printPreview(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Mail this document.
*/
static KAction *mail(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Quit the program.
*/
static KAction *quit(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Undo the last operation.
*/
static KAction *undo(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Redo the last operation.
*/
static KAction *redo(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Cut selected area and store it in the clipboard.
*/
static KAction *cut(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Copy the selected area into the clipboard.
*/
static KAction *copy(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Paste the contents of clipboard at the current mouse or cursor
* position.
*/
static KAction *paste(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Select all elements in the current document.
*/
static KAction *selectAll(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Initiate a 'find' request in the current document.
*/
static KAction *find(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Find the next instance of a stored 'find'.
*/
static KAction *findNext(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Find a previous instance of a stored 'find'.
*/
static KAction *findPrev(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Find and replace matches.
*/
static KAction *replace(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* View the document at its actual size.
*/
static KAction *actualSize(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Fit the document view to the size of the current window.
*/
static KAction *fitToPage(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Fit the document view to the width of the current window.
*/
static KAction *fitToWidth(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Fit the document view to the height of the current window.
*/
static KAction *fitToHeight(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Zoom in.
*/
static KAction *zoomIn(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Zoom out.
*/
static KAction *zoomOut(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Popup a zoom dialog.
*/
static KAction *zoom(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Redisplay or redraw the document.
*/
static KAction *redisplay(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Move up (web style menu).
*/
static KAction *up(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Move back (web style menu).
*/
static KAction *back(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Move forward (web style menu).
*/
static KAction *forward(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Go to the "Home" position or document.
*/
static KAction *home(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Scroll up one page.
*/
static KAction *prior(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Scroll down one page.
*/
static KAction *next(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Go to somewhere in general.
*/
static KAction *goTo(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Go to a specific page (dialog).
*/
static KAction *gotoPage(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Go to a specific line (dialog).
*/
static KAction *gotoLine(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Jump to the first page.
*/
static KAction *firstPage(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Jump to the last page.
*/
static KAction *lastPage(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Add the current page to the bookmarks tree.
*/
static KAction *addBookmark(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Edit the application bookmarks.
*/
static KAction *editBookmarks(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Pop up the spell checker.
*/
static KAction *spelling(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Show/Hide the menubar.
*/
static KToggleAction *showMenubar(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Show/Hide the primary toolbar.
*/
static KToggleAction *showToolbar(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Show/Hide the statusbar.
*/
static KToggleAction *showStatusbar(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Display the save options dialog.
*/
static KAction *saveOptions(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Display the configure key bindings dialog.
*/
static KAction *keyBindings(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Display the preferences/options dialog.
*/
static KAction *preferences(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* The Customize Toolbar dialog.
*/
static KAction *configureToolbars(const QObject *recvr = 0,
const char *slot = 0,
QObject *parent = 0,
const char *name = 0L );
/**
* Display the help.
*/
static KAction *help(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Display the help contents.
*/
static KAction *helpContents(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Trigger the What's This cursor.
*/
static KAction *whatsThis(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Open up the Report Bug dialog.
*/
static KAction *reportBug(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Display the application's About box.
*/
static KAction *aboutApp(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
/**
* Display the About KDE dialog.
*/
static KAction *aboutKDE(const QObject *recvr = 0, const char *slot = 0,
QObject *parent = 0, const char *name = 0L );
private:
KStdActionPrivate *d;
};
#endif // KSTDACTION_H
| Generated by: faure on ftp.kde.com on Wed Jun 20 13:26:11 2001, using kdoc 2.0a53. |