File indexing completed on 2024-05-26 04:31:45
0001 /* This file is part of the KDE libraries 0002 SPDX-FileCopyrightText: 1999, 2000 Kurt Granroth <granroth@kde.org> 0003 SPDX-FileCopyrightText: 2001, 2002 Ellis Whitehead <ellis@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-only 0006 */ 0007 #ifndef KSTANDARDACTION_H 0008 #define KSTANDARDACTION_H 0009 0010 #include <kritawidgetutils_export.h> 0011 #include <kstandardshortcut.h> 0012 #include <QList> 0013 0014 class QObject; 0015 class QStringList; 0016 class QWidget; 0017 class QAction; 0018 class KRecentFilesAction; 0019 class KDualAction; 0020 class KToggleAction; 0021 class KToggleFullScreenAction; 0022 0023 /** 0024 * Convenience methods to access all standard KDE actions. 0025 * 0026 * These actions should be used instead of hardcoding menubar and 0027 * toolbar items. Using these actions helps your application easily 0028 * conform to the KDE UI Style Guide. 0029 * 0030 * All of the documentation for QAction holds for KStandardAction 0031 * also. When in doubt on how things work, check the QAction 0032 * documentation first. 0033 * Please note that calling any of these methods automatically adds the action 0034 * to the actionCollection() of the QObject given by the 'parent' parameter. 0035 * 0036 * <b>Simple Example:</b>\n 0037 * 0038 * In general, using standard actions should be a drop in replacement 0039 * for regular actions. For example, if you previously had: 0040 * 0041 * \code 0042 * QAction *newAct = new QAction(i18n("&New"), KisIconUtils::loadIcon("document-new"), 0043 * KStandardShortcut::shortcut(KStandardShortcut::New), this, 0044 * SLOT(fileNew()), actionCollection()); 0045 * \endcode 0046 * 0047 * You could drop that and replace it with: 0048 * 0049 * \code 0050 * QAction *newAct = KStandardAction::openNew(this, SLOT(fileNew()), 0051 * actionCollection()); 0052 * \endcode 0053 * 0054 * <b>Non-standard Usages</b>\n 0055 * 0056 * It is possible to use the standard actions in various 0057 * non-recommended ways. Say, for instance, you wanted to have a 0058 * standard action (with the associated correct text and icon and 0059 * accelerator, etc) but you didn't want it to go in the standard 0060 * place (this is not recommended, by the way). One way to do this is 0061 * to simply not use the XML UI framework and plug it into wherever 0062 * you want. If you do want to use the XML UI framework (good!), then 0063 * it is still possible. 0064 * 0065 * Basically, the XML building code matches names in the XML code with 0066 * the internal names of the actions. You can find out the internal 0067 * names of each of the standard actions by using the name 0068 * method like so: KStandardAction::name(KStandardAction::Cut) would return 0069 * 'edit_cut'. The XML building code will match 'edit_cut' to the 0070 * attribute in the global XML file and place your action there. 0071 * 0072 * However, you can change the internal name. In this example, just 0073 * do something like: 0074 * 0075 * \code 0076 * (void)KStandardAction::cut(this, SLOT(editCut()), actionCollection(), "my_cut"); 0077 * \endcode 0078 * 0079 * Now, in your local XML resource file (e.g., yourappui.rc), simply 0080 * put 'my_cut' where you want it to go. 0081 * 0082 * Another non-standard usage concerns getting a pointer to an 0083 * existing action if, say, you want to enable or disable the action. 0084 * You could do it the recommended way and just grab a pointer when 0085 * you instantiate it as in the 'openNew' example above... or you 0086 * could do it the hard way: 0087 * 0088 * \code 0089 * QAction *cut = actionCollection()->action(KStandardAction::name(KStandardAction::Cut)); 0090 * \endcode 0091 * 0092 * Another non-standard usage concerns instantiating the action in the 0093 * first place. Usually, you would use the member functions as 0094 * shown above (e.g., KStandardAction::cut(this, SLOT, parent)). You 0095 * may, however, do this using the enums provided. This author can't 0096 * think of a reason why you would want to, but, hey, if you do, 0097 * here's how: 0098 * 0099 * \code 0100 * (void)KStandardAction::action(KStandardAction::New, this, SLOT(fileNew()), actionCollection()); 0101 * (void)KStandardAction::action(KStandardAction::Cut, this, SLOT(editCut()), actionCollection()); 0102 * \endcode 0103 * 0104 * @author Kurt Granroth <granroth@kde.org> 0105 */ 0106 namespace KStandardAction 0107 { 0108 /** 0109 * The standard menubar and toolbar actions. 0110 */ 0111 enum StandardAction { 0112 ActionNone, 0113 0114 // File Menu 0115 New, Open, OpenRecent, Save, SaveAs, Revert, Close, 0116 Print, PrintPreview, Mail, Quit, 0117 0118 // Edit Menu 0119 Undo, Redo, Cut, Copy, Paste, SelectAll, Deselect, Find, FindNext, FindPrev, 0120 Replace, 0121 0122 // View Menu 0123 ActualSize, FitToPage, FitToWidth, FitToHeight, ZoomIn, ZoomOut, 0124 Zoom, Redisplay, 0125 0126 // Go Menu 0127 Up, Back, Forward, Home /*Home page*/, Prior, Next, Goto, GotoPage, GotoLine, 0128 FirstPage, LastPage, DocumentBack, DocumentForward, 0129 0130 // Bookmarks Menu 0131 AddBookmark, EditBookmarks, 0132 0133 // Tools Menu 0134 Spelling, 0135 0136 // Settings Menu 0137 ShowMenubar, ShowToolbar, ShowStatusbar, 0138 SaveOptions, KeyBindings, 0139 Preferences, ConfigureToolbars, ResetConfigurations, 0140 0141 // Help Menu 0142 Help, HelpContents, WhatsThis, ReportBug, AboutApp, AboutKDE, 0143 TipofDay, 0144 0145 // Other standard actions 0146 ConfigureNotifications, 0147 FullScreen, 0148 Clear, 0149 PasteText, 0150 SwitchApplicationLanguage 0151 }; 0152 0153 /** 0154 * Creates an action corresponding to one of the 0155 * KStandardAction::StandardAction actions, which is connected to the given 0156 * object and @p slot, and is owned by @p parent. 0157 * 0158 * The signal that is connected to @p slot is triggered(bool), except for the case of 0159 * OpenRecent standard action, which uses the urlSelected(const QUrl &) signal of 0160 * KRecentFilesAction. 0161 * 0162 * @param id The StandardAction identifier to create a QAction for. 0163 * @param recvr The QObject to receive the signal, or 0 if no notification 0164 * is needed. 0165 * @param slot The slot to connect the signal to (remember to use the SLOT() macro). 0166 * @param parent The QObject that should own the created QAction, or 0 if no parent will 0167 * own the QAction returned (ensure you delete it manually in this case). 0168 */ 0169 KRITAWIDGETUTILS_EXPORT QAction *create(StandardAction id, const QObject *recvr, const char *slot, 0170 QObject *parent); 0171 0172 /** 0173 * This will return the internal name of a given standard action. 0174 */ 0175 KRITAWIDGETUTILS_EXPORT const char *name(StandardAction id); 0176 0177 /// @deprecated use name() 0178 #ifndef KDE_NO_DEPRECATED 0179 inline KRITAWIDGETUTILS_DEPRECATED const char *stdName(StandardAction act_enum) 0180 { 0181 return name(act_enum); 0182 } 0183 #endif 0184 0185 /** 0186 * Returns a list of all standard names. Used by KAccelManager 0187 * to give those higher weight. 0188 */ 0189 KRITAWIDGETUTILS_EXPORT QStringList stdNames(); 0190 0191 /** 0192 * Returns a list of all actionIds. 0193 * 0194 * @since 4.2 0195 */ 0196 KRITAWIDGETUTILS_EXPORT QList<StandardAction> actionIds(); 0197 0198 /** 0199 * Returns the standardshortcut associated with @a actionId. 0200 * 0201 * @param id The actionId whose associated shortcut is wanted. 0202 * 0203 * @since 4.2 0204 */ 0205 KRITAWIDGETUTILS_EXPORT KStandardShortcut::StandardShortcut shortcutForActionId(StandardAction id); 0206 0207 /** 0208 * Create a new document or window. 0209 */ 0210 KRITAWIDGETUTILS_EXPORT QAction *openNew(const QObject *recvr, const char *slot, QObject *parent); 0211 0212 /** 0213 * Open an existing file. 0214 */ 0215 KRITAWIDGETUTILS_EXPORT QAction *open(const QObject *recvr, const char *slot, QObject *parent); 0216 0217 /** 0218 * Open a recently used document. The signature of the slot being called 0219 * is of the form slotURLSelected( const QUrl & ). 0220 * @param recvr object to receive slot 0221 * @param slot The SLOT to invoke when a URL is selected. The slot's 0222 * signature is slotURLSelected( const QUrl & ). 0223 * @param parent parent widget 0224 */ 0225 KRITAWIDGETUTILS_EXPORT KRecentFilesAction *openRecent(const QObject *recvr, const char *slot, QObject *parent); 0226 0227 /** 0228 * Save the current document. 0229 */ 0230 KRITAWIDGETUTILS_EXPORT QAction *save(const QObject *recvr, const char *slot, QObject *parent); 0231 0232 /** 0233 * Save the current document under a different name. 0234 */ 0235 KRITAWIDGETUTILS_EXPORT QAction *saveAs(const QObject *recvr, const char *slot, QObject *parent); 0236 0237 /** 0238 * Revert the current document to the last saved version 0239 * (essentially will undo all changes). 0240 */ 0241 KRITAWIDGETUTILS_EXPORT QAction *revert(const QObject *recvr, const char *slot, QObject *parent); 0242 0243 /** 0244 * Close the current document. 0245 */ 0246 KRITAWIDGETUTILS_EXPORT QAction *close(const QObject *recvr, const char *slot, QObject *parent); 0247 0248 /** 0249 * Print the current document. 0250 */ 0251 KRITAWIDGETUTILS_EXPORT QAction *print(const QObject *recvr, const char *slot, QObject *parent); 0252 0253 /** 0254 * Show a print preview of the current document. 0255 */ 0256 KRITAWIDGETUTILS_EXPORT QAction *printPreview(const QObject *recvr, const char *slot, QObject *parent); 0257 0258 /** 0259 * Mail this document. 0260 */ 0261 KRITAWIDGETUTILS_EXPORT QAction *mail(const QObject *recvr, const char *slot, QObject *parent); 0262 0263 /** 0264 * Quit the program. 0265 * 0266 * Note that you probably want to connect this action to either QWidget::close() 0267 * or QApplication::closeAllWindows(), but not QApplication::quit(), so that 0268 * KisKMainWindow::queryClose() is called on any open window (to warn the user 0269 * about unsaved changes for example). 0270 */ 0271 KRITAWIDGETUTILS_EXPORT QAction *quit(const QObject *recvr, const char *slot, QObject *parent); 0272 0273 /** 0274 * Undo the last operation. 0275 */ 0276 KRITAWIDGETUTILS_EXPORT QAction *undo(const QObject *recvr, const char *slot, QObject *parent); 0277 0278 /** 0279 * Redo the last operation. 0280 */ 0281 KRITAWIDGETUTILS_EXPORT QAction *redo(const QObject *recvr, const char *slot, QObject *parent); 0282 0283 /** 0284 * Cut selected area and store it in the clipboard. 0285 * Calls cut() on the widget with the current focus. 0286 */ 0287 KRITAWIDGETUTILS_EXPORT QAction *cut(QObject *parent); 0288 0289 /** 0290 * Copy selected area and store it in the clipboard. 0291 * Calls copy() on the widget with the current focus. 0292 */ 0293 KRITAWIDGETUTILS_EXPORT QAction *copy(QObject *parent); 0294 0295 /** 0296 * Paste the contents of clipboard at the current mouse or cursor 0297 * Calls paste() on the widget with the current focus. 0298 */ 0299 KRITAWIDGETUTILS_EXPORT QAction *paste(QObject *parent); 0300 0301 /** 0302 * Clear selected area. Calls clear() on the widget with the current focus. 0303 * Note that for some widgets, this may not provide the intended behavior. For 0304 * example if you make use of the code above and a K3ListView has the focus, clear() 0305 * will clear all of the items in the list. If this is not the intended behavior 0306 * and you want to make use of this slot, you can subclass K3ListView and reimplement 0307 * this slot. For example the following code would implement a K3ListView without this 0308 * behavior: 0309 * 0310 * \code 0311 * class MyListView : public K3ListView { 0312 * Q_OBJECT 0313 * public: 0314 * MyListView( QWidget * parent = 0, const char * name = 0, WFlags f = Qt::WindowFlags() ) : K3ListView( parent, name, f ) {} 0315 * virtual ~MyListView() {} 0316 * public Q_SLOTS: 0317 * virtual void clear() {} 0318 * }; 0319 * \endcode 0320 */ 0321 KRITAWIDGETUTILS_EXPORT QAction *clear(QObject *parent); 0322 0323 /** 0324 * Calls selectAll() on the widget with the current focus. 0325 */ 0326 KRITAWIDGETUTILS_EXPORT QAction *selectAll(QObject *parent); 0327 0328 /** 0329 * Cut selected area and store it in the clipboard. 0330 */ 0331 KRITAWIDGETUTILS_EXPORT QAction *cut(const QObject *recvr, const char *slot, QObject *parent); 0332 0333 /** 0334 * Copy the selected area into the clipboard. 0335 */ 0336 KRITAWIDGETUTILS_EXPORT QAction *copy(const QObject *recvr, const char *slot, QObject *parent); 0337 0338 /** 0339 * Paste the contents of clipboard at the current mouse or cursor 0340 * position. 0341 */ 0342 KRITAWIDGETUTILS_EXPORT QAction *paste(const QObject *recvr, const char *slot, QObject *parent); 0343 0344 /** 0345 * Paste the contents of clipboard at the current mouse or cursor 0346 * position. Provide a button on the toolbar with the clipboard history 0347 * menu if Klipper is running. 0348 */ 0349 KRITAWIDGETUTILS_EXPORT QAction *pasteText(const QObject *recvr, const char *slot, QObject *parent); 0350 0351 /** 0352 * Clear the content of the focus widget 0353 */ 0354 KRITAWIDGETUTILS_EXPORT QAction *clear(const QObject *recvr, const char *slot, QObject *parent); 0355 0356 /** 0357 * Select all elements in the current document. 0358 */ 0359 KRITAWIDGETUTILS_EXPORT QAction *selectAll(const QObject *recvr, const char *slot, QObject *parent); 0360 0361 /** 0362 * Deselect any selected elements in the current document. 0363 */ 0364 KRITAWIDGETUTILS_EXPORT QAction *deselect(const QObject *recvr, const char *slot, QObject *parent); 0365 0366 /** 0367 * Initiate a 'find' request in the current document. 0368 */ 0369 KRITAWIDGETUTILS_EXPORT QAction *find(const QObject *recvr, const char *slot, QObject *parent); 0370 0371 /** 0372 * Find the next instance of a stored 'find'. 0373 */ 0374 KRITAWIDGETUTILS_EXPORT QAction *findNext(const QObject *recvr, const char *slot, QObject *parent); 0375 0376 /** 0377 * Find a previous instance of a stored 'find'. 0378 */ 0379 KRITAWIDGETUTILS_EXPORT QAction *findPrev(const QObject *recvr, const char *slot, QObject *parent); 0380 0381 /** 0382 * Find and replace matches. 0383 */ 0384 KRITAWIDGETUTILS_EXPORT QAction *replace(const QObject *recvr, const char *slot, QObject *parent); 0385 0386 /** 0387 * View the document at its actual size. 0388 */ 0389 KRITAWIDGETUTILS_EXPORT QAction *actualSize(const QObject *recvr, const char *slot, QObject *parent); 0390 0391 /** 0392 * Fit the document view to the size of the current window. 0393 */ 0394 KRITAWIDGETUTILS_EXPORT QAction *fitToPage(const QObject *recvr, const char *slot, QObject *parent); 0395 0396 /** 0397 * Fit the document view to the width of the current window. 0398 */ 0399 KRITAWIDGETUTILS_EXPORT QAction *fitToWidth(const QObject *recvr, const char *slot, QObject *parent); 0400 0401 /** 0402 * Fit the document view to the height of the current window. 0403 */ 0404 KRITAWIDGETUTILS_EXPORT QAction *fitToHeight(const QObject *recvr, const char *slot, QObject *parent); 0405 0406 /** 0407 * Zoom in. 0408 */ 0409 KRITAWIDGETUTILS_EXPORT QAction *zoomIn(const QObject *recvr, const char *slot, QObject *parent); 0410 0411 /** 0412 * Zoom out. 0413 */ 0414 KRITAWIDGETUTILS_EXPORT QAction *zoomOut(const QObject *recvr, const char *slot, QObject *parent); 0415 0416 /** 0417 * Popup a zoom dialog. 0418 */ 0419 KRITAWIDGETUTILS_EXPORT QAction *zoom(const QObject *recvr, const char *slot, QObject *parent); 0420 0421 /** 0422 * Redisplay or redraw the document. 0423 */ 0424 KRITAWIDGETUTILS_EXPORT QAction *redisplay(const QObject *recvr, const char *slot, QObject *parent); 0425 0426 /** 0427 * Move up (web style menu). 0428 */ 0429 KRITAWIDGETUTILS_EXPORT QAction *up(const QObject *recvr, const char *slot, QObject *parent); 0430 0431 /** 0432 * Move back (web style menu). 0433 */ 0434 KRITAWIDGETUTILS_EXPORT QAction *back(const QObject *recvr, const char *slot, QObject *parent); 0435 0436 /** 0437 * Move forward (web style menu). 0438 */ 0439 KRITAWIDGETUTILS_EXPORT QAction *forward(const QObject *recvr, const char *slot, QObject *parent); 0440 0441 /** 0442 * Go to the "Home" position or document. 0443 */ 0444 KRITAWIDGETUTILS_EXPORT QAction *home(const QObject *recvr, const char *slot, QObject *parent); 0445 0446 /** 0447 * Scroll up one page. 0448 */ 0449 KRITAWIDGETUTILS_EXPORT QAction *prior(const QObject *recvr, const char *slot, QObject *parent); 0450 0451 /** 0452 * Scroll down one page. 0453 */ 0454 KRITAWIDGETUTILS_EXPORT QAction *next(const QObject *recvr, const char *slot, QObject *parent); 0455 0456 /** 0457 * Go to somewhere in general. 0458 */ 0459 KRITAWIDGETUTILS_EXPORT QAction *goTo(const QObject *recvr, const char *slot, QObject *parent); 0460 0461 /** 0462 * Go to a specific page (dialog). 0463 */ 0464 KRITAWIDGETUTILS_EXPORT QAction *gotoPage(const QObject *recvr, const char *slot, QObject *parent); 0465 0466 /** 0467 * Go to a specific line (dialog). 0468 */ 0469 KRITAWIDGETUTILS_EXPORT QAction *gotoLine(const QObject *recvr, const char *slot, QObject *parent); 0470 0471 /** 0472 * Jump to the first page. 0473 */ 0474 KRITAWIDGETUTILS_EXPORT QAction *firstPage(const QObject *recvr, const char *slot, QObject *parent); 0475 0476 /** 0477 * Jump to the last page. 0478 */ 0479 KRITAWIDGETUTILS_EXPORT QAction *lastPage(const QObject *recvr, const char *slot, QObject *parent); 0480 0481 /** 0482 * Move back (document style menu). 0483 */ 0484 KRITAWIDGETUTILS_EXPORT QAction *documentBack(const QObject *recvr, const char *slot, QObject *parent); 0485 0486 /** 0487 * Move forward (document style menu). 0488 */ 0489 KRITAWIDGETUTILS_EXPORT QAction *documentForward(const QObject *recvr, const char *slot, QObject *parent); 0490 0491 /** 0492 * Add the current page to the bookmarks tree. 0493 */ 0494 KRITAWIDGETUTILS_EXPORT QAction *addBookmark(const QObject *recvr, const char *slot, QObject *parent); 0495 0496 /** 0497 * Edit the application bookmarks. 0498 */ 0499 KRITAWIDGETUTILS_EXPORT QAction *editBookmarks(const QObject *recvr, const char *slot, QObject *parent); 0500 0501 /** 0502 * Pop up the spell checker. 0503 */ 0504 KRITAWIDGETUTILS_EXPORT QAction *spelling(const QObject *recvr, const char *slot, QObject *parent); 0505 0506 /** 0507 * Show/Hide the menubar. 0508 */ 0509 KRITAWIDGETUTILS_EXPORT KToggleAction *showMenubar(const QObject *recvr, const char *slot, QObject *parent); 0510 0511 /** 0512 * Show/Hide the statusbar. 0513 */ 0514 KRITAWIDGETUTILS_EXPORT KToggleAction *showStatusbar(const QObject *recvr, const char *slot, QObject *parent); 0515 0516 /** 0517 * Switch to/from full screen mode 0518 */ 0519 KRITAWIDGETUTILS_EXPORT KToggleFullScreenAction *fullScreen(const QObject *recvr, const char *slot, QWidget *window, QObject *parent); 0520 0521 /** 0522 * Display the save options dialog. 0523 */ 0524 KRITAWIDGETUTILS_EXPORT QAction *saveOptions(const QObject *recvr, const char *slot, QObject *parent); 0525 0526 /** 0527 * Display the configure key bindings dialog. 0528 * 0529 * Note that you might be able to use the pre-built KisKXMLGUIFactory's function: 0530 * KStandardAction::keyBindings(guiFactory(), SLOT(configureShortcuts()), actionCollection()); 0531 */ 0532 KRITAWIDGETUTILS_EXPORT QAction *keyBindings(const QObject *recvr, const char *slot, QObject *parent); 0533 0534 /** 0535 * Display the preferences/options dialog. 0536 */ 0537 KRITAWIDGETUTILS_EXPORT QAction *preferences(const QObject *recvr, const char *slot, QObject *parent); 0538 0539 /** 0540 * The Customize Toolbar dialog. 0541 */ 0542 KRITAWIDGETUTILS_EXPORT QAction *configureToolbars(const QObject *recvr, const char *slot, QObject *parent); 0543 0544 /** 0545 * The Configure Notifications dialog. 0546 */ 0547 KRITAWIDGETUTILS_EXPORT QAction *configureNotifications(const QObject *recvr, const char *slot, QObject *parent); 0548 0549 /** 0550 * Display the help. 0551 */ 0552 KRITAWIDGETUTILS_EXPORT QAction *help(const QObject *recvr, const char *slot, QObject *parent); 0553 0554 /** 0555 * Display the help contents. 0556 */ 0557 KRITAWIDGETUTILS_EXPORT QAction *helpContents(const QObject *recvr, const char *slot, QObject *parent); 0558 0559 /** 0560 * Trigger the What's This cursor. 0561 */ 0562 KRITAWIDGETUTILS_EXPORT QAction *whatsThis(const QObject *recvr, const char *slot, QObject *parent); 0563 0564 /** 0565 * Display "Tip of the Day" 0566 */ 0567 KRITAWIDGETUTILS_EXPORT QAction *tipOfDay(const QObject *recvr, const char *slot, QObject *parent); 0568 0569 /** 0570 * Open up the Report Bug dialog. 0571 */ 0572 KRITAWIDGETUTILS_EXPORT QAction *reportBug(const QObject *recvr, const char *slot, QObject *parent); 0573 0574 /** 0575 * Display the application's About box. 0576 */ 0577 KRITAWIDGETUTILS_EXPORT QAction *aboutApp(const QObject *recvr, const char *slot, QObject *parent); 0578 0579 /** 0580 * Display the About KDE dialog. 0581 */ 0582 KRITAWIDGETUTILS_EXPORT QAction *aboutKDE(const QObject *recvr, const char *slot, QObject *parent); 0583 } 0584 0585 #endif // KSTANDARDACTION_H