Warning, file /office/calligra/libs/flake/KoToolManager.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* This file is part of the KDE project 0002 * Copyright (c) 2005-2006 Boudewijn Rempt <boud@valdyas.org> 0003 * Copyright (C) 2006, 2008 Thomas Zander <zander@kde.org> 0004 * Copyright (C) 2006 Thorsten Zachmann <zachmann@kde.org> 0005 * 0006 * This library is free software; you can redistribute it and/or 0007 * modify it under the terms of the GNU Library General Public 0008 * License as published by the Free Software Foundation; either 0009 * version 2 of the License, or (at your option) any later version. 0010 * 0011 * This library is distributed in the hope that it will be useful, 0012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0014 * Library General Public License for more details. 0015 * 0016 * You should have received a copy of the GNU Library General Public License 0017 * along with this library; see the file COPYING.LIB. If not, write to 0018 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0019 * Boston, MA 02110-1301, USA. 0020 */ 0021 #ifndef KO_TOOL_MANAGER 0022 #define KO_TOOL_MANAGER 0023 0024 #include "KoInputDevice.h" 0025 #include "flake_export.h" 0026 0027 #include <QObject> 0028 #include <QList> 0029 0030 class KoCanvasController; 0031 class KoShapeBasedDocumentBase; 0032 class KoToolFactoryBase; 0033 class KoCanvasBase; 0034 class KoToolBase; 0035 class KoCreateShapesTool; 0036 class KActionCollection; 0037 class KoShape; 0038 class KoInputDeviceHandlerEvent; 0039 class KoShapeLayer; 0040 class ToolHelper; 0041 class QKeySequence; 0042 0043 class QCursor; 0044 0045 /** 0046 * This class serves as a QAction-like control object for activation of a tool. 0047 * 0048 * It allows to implement a custom UI to control the activation of tools. 0049 * See KoToolBox & KoModeBox in the kowidgets library. 0050 * 0051 * KoToolAction objects are indirectly owned by the KoToolManager singleton 0052 * and live until the end of its lifetime. 0053 */ 0054 class FLAKE_EXPORT KoToolAction : public QObject 0055 { 0056 Q_OBJECT 0057 public: 0058 // toolHelper takes over ownership, and those live till the end of KoToolManager. 0059 explicit KoToolAction(ToolHelper *toolHelper); 0060 ~KoToolAction() override; 0061 0062 public: 0063 QString id() const; ///< The id of the tool 0064 QString iconText() const; ///< The icontext of the tool 0065 QString toolTip() const; ///< The tooltip of the tool 0066 QString iconName() const; ///< The icon name of the tool 0067 QKeySequence shortcut() const; ///< The shortcut to activate the tool 0068 0069 QString section() const; ///< The section the tool wants to be in. 0070 int priority() const; ///< Lower number (higher priority) means coming first in the section. 0071 int buttonGroupId() const; ///< A unique ID for this tool as passed by changedTool(), >= 0 0072 QString visibilityCode() const; ///< This tool should become visible when we emit this string in toolCodesSelected() 0073 0074 public Q_SLOTS: 0075 void trigger(); ///< Request the activation of the tool 0076 0077 Q_SIGNALS: 0078 void changed(); ///< Emitted when a property changes (shortcut ATM) 0079 0080 private: 0081 friend class ToolHelper; 0082 class Private; 0083 Private *const d; 0084 }; 0085 0086 0087 /** 0088 * This class manages the activation and deactivation of tools for 0089 * each input device. 0090 * 0091 * Managing the active tool and switching tool based on various variables. 0092 * 0093 * The state of the toolbox will be the same for all views in the process so practically 0094 * you can say we have one toolbox per application instance (process). Implementation 0095 * does not allow one widget to be in more then one view, so we just make sure the toolbox 0096 * is hidden in not-in-focus views. 0097 * 0098 * The ToolManager is a singleton and will manage all views in all applications that 0099 * are loaded in this process. This means you will have to register and unregister your view. 0100 * When creating your new view you should use a KoCanvasController() and register that 0101 * with the ToolManager like this: 0102 @code 0103 MyGuiWidget::MyGuiWidget() { 0104 m_canvasController = new KoCanvasController(this); 0105 m_canvasController->setCanvas(m_canvas); 0106 KoToolManager::instance()->addControllers(m_canvasController)); 0107 } 0108 MyGuiWidget::~MyGuiWidget() { 0109 KoToolManager::instance()->removeCanvasController(m_canvasController); 0110 } 0111 @endcode 0112 * 0113 * For a new view that extends KoView all you need to do is implement KoView::createToolBox() 0114 * 0115 * KoToolManager also keeps track of the current tool based on a 0116 complex set of conditions and heuristics: 0117 0118 - there is one active tool per KoCanvasController (and there is one KoCanvasController 0119 per view, because this is a class with scrollbars and a zoomlevel and so on) 0120 - for every pointing device (determined by the unique id of tablet, 0121 or 0 for mice -- you may have more than one mouse attached, but 0122 Qt cannot distinquish between them, there is an associated tool. 0123 - depending on things like tablet leave/enter proximity, incoming 0124 mouse or tablet events and a little timer (that gets stopped when 0125 we know what is what), the active pointing device is determined, 0126 and the active tool is set accordingly. 0127 0128 Nota bene: if you use KoToolManager and register your canvases with 0129 it you no longer have to manually implement methods to route mouse, 0130 tablet, key or wheel events to the active tool. In fact, it's no 0131 longer interesting to you which tool is active; you can safely 0132 route the paint event through KoToolProxy::paint(). 0133 0134 (The reason the input events are handled completely by the 0135 toolmanager and the paint events not is that, generally speaking, 0136 it's okay if the tools get the input events first, but you want to 0137 paint your shapes or other canvas stuff first and only then paint 0138 the tool stuff.) 0139 0140 */ 0141 class FLAKE_EXPORT KoToolManager : public QObject 0142 { 0143 Q_OBJECT 0144 0145 public: 0146 KoToolManager(); 0147 /// Return the toolmanager singleton 0148 static KoToolManager* instance(); 0149 ~KoToolManager() override; 0150 0151 /** 0152 * Register actions for switching to tools at the actionCollection parameter. 0153 * The actions will have the text / shortcut as stated by the toolFactory. 0154 * If the application calls this in their KoView extending class they will have all the benefits 0155 * from allowing this in the menus and to allow the use to configure the shortcuts used. 0156 * @param ac the actionCollection that will be the parent of the actions. 0157 * @param controller tools registered with this controller will have all their actions added as well. 0158 */ 0159 void registerTools(KActionCollection *ac, KoCanvasController *controller); 0160 0161 /** 0162 * Register a new canvas controller 0163 * @param controller the view controller that this toolmanager will manage the tools for 0164 */ 0165 void addController(KoCanvasController *controller); 0166 0167 /** 0168 * Remove a set of controllers 0169 * When the controller is no longer used it should be removed so all tools can be 0170 * deleted and stop eating memory. 0171 * @param controller the controller that is removed 0172 */ 0173 void removeCanvasController(KoCanvasController *controller); 0174 /** 0175 * Attempt to remove a controller. 0176 * This is automatically called when a controller's proxy object is deleted, and 0177 * it ensures that the controller is, in fact, removed, even if the creator forgot 0178 * to do so. 0179 * @param controller the proxy object of the controller to be removed 0180 */ 0181 Q_SLOT void attemptCanvasControllerRemoval(QObject *controller); 0182 0183 /// @return the active canvas controller 0184 KoCanvasController *activeCanvasController() const; 0185 0186 /** 0187 * Connect all the tools for the given canvas to the new shape controller. 0188 * 0189 * @param shapeController the new shape controller 0190 * @param canvasController the canvas 0191 */ 0192 void updateShapeControllerBase(KoShapeBasedDocumentBase *shapeController, KoCanvasController *canvasController); 0193 0194 /** 0195 * Return the tool that is able to create shapes for this param canvas. 0196 * This is typically used by the KoShapeSelector to set which shape to create next. 0197 * @param canvas the canvas that is a child of a previously registered controller 0198 * who's tool you want. 0199 * @see addController() 0200 */ 0201 KoCreateShapesTool *shapeCreatorTool(KoCanvasBase *canvas) const; 0202 0203 /** 0204 * Returns the tool for the given tool id. 0205 * @param canvas the canvas that is a child of a previously registered controller 0206 * who's tool you want. 0207 * @param id the given tool identifier. 0208 * @see addController() 0209 */ 0210 KoToolBase *toolById(KoCanvasBase *canvas, const QString &id) const; 0211 0212 /// @return the currently active pointing device 0213 KoInputDevice currentInputDevice() const; 0214 0215 /** 0216 * For the list of shapes find out which tool is the highest priority tool that can handle it. 0217 * @returns the toolId for the shapes. 0218 * @param shapes a list of shapes, a selection for example, that is used to look for the tool. 0219 */ 0220 QString preferredToolForSelection(const QList<KoShape*> &shapes); 0221 0222 /** 0223 * Returns the list of toolActions for the current tools. 0224 * @returns lists of toolActions for the current tools. 0225 */ 0226 QList<KoToolAction*> toolActionList() const; 0227 0228 /// Request tool activation for the given canvas controller 0229 void requestToolActivation(KoCanvasController *controller); 0230 0231 /// Injects an input event from a plugin based input device 0232 void injectDeviceEvent(KoInputDeviceHandlerEvent *event); 0233 0234 /// Returns the toolId of the currently active tool 0235 QString activeToolId() const; 0236 0237 class Private; 0238 /** 0239 * \internal return the private object for the toolmanager. 0240 */ 0241 KoToolManager::Private *priv(); 0242 0243 public Q_SLOTS: 0244 /** 0245 * Request switching tool 0246 * @param id the id of the tool 0247 */ 0248 void switchToolRequested(const QString &id); 0249 0250 /** 0251 * Request change input device 0252 * @param id the id of the input device 0253 */ 0254 void switchInputDeviceRequested(const KoInputDevice &id); 0255 0256 /** 0257 * a new tool has become known to mankind 0258 */ 0259 void addDeferredToolFactory(KoToolFactoryBase *toolFactory); 0260 0261 /** 0262 * Request for temporary switching the tools. 0263 * This switch can be later reverted with switchBackRequested(). 0264 * @param id the id of the tool 0265 * 0266 * @see switchBackRequested() 0267 */ 0268 void switchToolTemporaryRequested(const QString &id); 0269 0270 /** 0271 * Switches back to the original tool after the temporary switch 0272 * has been done. It the user changed the tool manually on the way, 0273 * then it switches to the interaction tool 0274 */ 0275 void switchBackRequested(); 0276 0277 Q_SIGNALS: 0278 /** 0279 * Emitted when a new tool was selected or became active. 0280 * @param canvas the currently active canvas. 0281 * @param uniqueToolId a random but unique code for the new tool. 0282 */ 0283 void changedTool(KoCanvasController *canvas, int uniqueToolId); 0284 0285 /** 0286 * Emitted after the selection changed to state which unique shape-types are now 0287 * in the selection. 0288 * @param types a list of string that are the shape types of the selected objects. 0289 */ 0290 void toolCodesSelected(const QList<QString> &types); 0291 0292 /** 0293 * Emitted after the current layer changed either its properties or to a new layer. 0294 * @param canvas the currently active canvas. 0295 * @param layer the layer that is selected. 0296 */ 0297 void currentLayerChanged(const KoCanvasController *canvas, const KoShapeLayer *layer); 0298 0299 /** 0300 * Every time a new input device gets used by a tool, this event is emitted. 0301 * @param device the new input device that the user picked up. 0302 */ 0303 void inputDeviceChanged(const KoInputDevice &device); 0304 0305 /** 0306 * Emitted whenever the active canvas changed. 0307 * @param canvas the new activated canvas (might be 0) 0308 */ 0309 void changedCanvas(const KoCanvasBase *canvas); 0310 0311 /** 0312 * Emitted whenever the active tool changes the status text. 0313 * @param statusText the new status text 0314 */ 0315 void changedStatusText(const QString &statusText); 0316 0317 /** 0318 * emitted whenever a new tool is dynamically added for the given canvas 0319 */ 0320 void addedTool(KoToolAction *toolAction, KoCanvasController *canvas); 0321 0322 private: 0323 KoToolManager(const KoToolManager&); 0324 KoToolManager operator=(const KoToolManager&); 0325 0326 Q_PRIVATE_SLOT(d, void toolActivated(ToolHelper *tool)) 0327 Q_PRIVATE_SLOT(d, void detachCanvas(KoCanvasController *controller)) 0328 Q_PRIVATE_SLOT(d, void attachCanvas(KoCanvasController *controller)) 0329 Q_PRIVATE_SLOT(d, void movedFocus(QWidget *from, QWidget *to)) 0330 Q_PRIVATE_SLOT(d, void updateCursor(const QCursor &cursor)) 0331 Q_PRIVATE_SLOT(d, void selectionChanged(const QList<KoShape*> &shapes)) 0332 Q_PRIVATE_SLOT(d, void currentLayerChanged(const KoShapeLayer *layer)) 0333 0334 QPair<QString, KoToolBase*> createTools(KoCanvasController *controller, ToolHelper *tool); 0335 0336 Private *const d; 0337 }; 0338 0339 #endif