1 /* This file is part of the KDE project
2  *
3  * Copyright (C) 2006-2007, 2010 Thomas Zander <zander@kde.org>
4  * Copyright (C) 2006-2008 Thorsten Zachmann <zachmann@kde.org>
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Library General Public License for more details.
15  *
16  * You should have received a copy of the GNU Library General Public License
17  * along with this library; see the file COPYING.LIB.  If not, write to
18  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20  */
21 
22 #ifndef KOSHAPECONTROLLER_H
23 #define KOSHAPECONTROLLER_H
24 
25 #include "flake_export.h"
26 
27 #include <QList>
28 #include <QMetaType>
29 
30 class KoCanvasBase;
31 class KoShape;
32 class KoShapeBasedDocumentBase;
33 class KUndo2Command;
34 class KoDocumentResourceManager;
35 
36 /**
37  * Class used by tools to maintain the list of shapes.
38  * All applications have some sort of list of all shapes that belong to the document.
39  * The applications implement the KoShapeBasedDocumentBase interface (all pure virtuals)
40  * to add and remove shapes from the document. To ensure that an application can expect
41  * a certain protocol to be adhered to when adding/removing shapes, all tools use the API
42  * from this class for maintaining the list of shapes in the document. So no tool gets
43  * to access the application directly.
44  */
45 class FLAKE_EXPORT KoShapeController
46 {
47 public:
48     /**
49      * Create a new Controller; typically not called by applications, only
50      * by the KonCanvasBase constructor.
51      * @param canvas the canvas this controller works for. The canvas can be 0
52      * @param shapeBasedDocument the application provided shapeBasedDocument that we can call.
53      */
54     KoShapeController(KoCanvasBase *canvas, KoShapeBasedDocumentBase *shapeBasedDocument);
55     /// destructor
56     ~KoShapeController();
57 
58     /**
59      * @brief Add a shape to the document.
60      * If the shape has no parent, the active layer will become its parent.
61      *
62      * @param shape to add to the document
63      * @param parent the parent command if the resulting command is a compound undo command.
64      *
65      * @return command which will insert the shape into the document or 0 if the
66      *         insertion was cancelled. The command is not yet executed.
67      */
68     KUndo2Command* addShape(KoShape *shape, KUndo2Command *parent = 0);
69 
70     /**
71      * @brief Add a shape to the document, skipping any dialogs or other user interaction.
72      *
73      * @param shape to add to the document
74      * @param parent the parent command if the resulting command is a compound undo command.
75      *
76      * @return command which will insert the shape into the document. The command is not yet executed.
77      */
78     KUndo2Command* addShapeDirect(KoShape *shape, KUndo2Command *parent = 0);
79 
80     /**
81      * @brief Remove a shape from the document.
82      *
83      * @param shape to remove from the document
84      * @param parent the parent command if the resulting command is a compound undo command.
85      *
86      * @return command which will remove the shape from the document.
87      *         The command is not yet executed.
88      */
89     KUndo2Command* removeShape(KoShape *shape, KUndo2Command *parent = 0);
90 
91     /**
92      * Remove a shape from the document.
93      *
94      * @param shapes the set of shapes to remove from the document
95      * @param parent the parent command if the resulting command is a compound undo command.
96      *
97      * @return command which will remove the shape from the document.
98      *         The command is not yet executed.
99      */
100     KUndo2Command* removeShapes(const QList<KoShape*> &shapes, KUndo2Command *parent = 0);
101 
102     /**
103      * @brief Set the KoShapeBasedDocumentBase used to add/remove shapes.
104      *
105      * NOTE: only Sheets uses this method. Do not use it in your application. Sheets
106      * has to also call:
107      * <code>KoToolManager::instance()->updateShapeControllerBase(shapeBasedDocument, canvas->canvasController());</code>
108      *
109      * @param shapeBasedDocument the new shapeBasedDocument.
110      */
111     void setShapeControllerBase(KoShapeBasedDocumentBase *shapeBasedDocument);
112 
113     /**
114      * Return a pointer to the resource manager associated with the
115      * shape-set (typically a document). The resource manager contains
116      * document wide resources * such as variable managers, the image
117      * collection and others.
118      */
119     KoDocumentResourceManager *resourceManager() const;
120 
121     /**
122      * @brief Returns the KoShapeBasedDocumentBase used to add/remove shapes.
123      *
124      * @return the KoShapeBasedDocumentBase
125      */
126     KoShapeBasedDocumentBase *documentBase() const;
127 
128 private:
129     class Private;
130     Private * const d;
131 };
132 
133 Q_DECLARE_METATYPE(KoShapeController *)
134 
135 #endif
136