Warning, file /office/calligra/libs/flake/KoShapeFactoryBase.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) 2006 Boudewijn Rempt (boud@valdyas.org) 0003 * Copyright (C) 2006-2007 Thomas Zander <zander@kde.org> 0004 * Copyright (C) 2008 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 0022 #ifndef KOSHAPEFACTORYBASE_H 0023 #define KOSHAPEFACTORYBASE_H 0024 0025 #include <QObject> 0026 #include <QStringList> 0027 #include <QString> 0028 #include <QList> 0029 0030 #include "flake_export.h" 0031 0032 #include <KoXmlReader.h> 0033 0034 class KoShape; 0035 class KoProperties; 0036 class KoShapeConfigFactoryBase; 0037 class KoShapeConfigWidgetBase; 0038 class KoShapeLoadingContext; 0039 class KoDocumentResourceManager; 0040 0041 #define SHAPETEMPLATE_MIMETYPE "application/x-flake-shapetemplate" 0042 #define SHAPEID_MIMETYPE "application/x-flake-shapeId" 0043 0044 /** 0045 * Contains a KoProperties object that describes the settings of a 0046 * particular variant of a shape object, together with a name, a description 0047 * and an icon for use in the user interface. 0048 */ 0049 struct FLAKE_EXPORT KoShapeTemplate { 0050 KoShapeTemplate() { 0051 properties = 0; 0052 order = 0; 0053 } 0054 QString id; ///< The id of the shape 0055 QString templateId; ///< The id of this particular template - only has to be unique with the shape 0056 QString name; ///< The name to be shown for this template 0057 QString family; ///< The family of the shape (possible values are: "funny","arrow") 0058 QString toolTip; ///< The tooltip text for the template 0059 QString iconName; ///< Icon name 0060 /** 0061 * The properties which, when passed to the KoShapeFactoryBase::createShape() method 0062 * result in the shape this template represents. 0063 */ 0064 const KoProperties *properties; 0065 0066 int order; ///< If order differs between shapes, they are ordered in ascending order 0067 }; 0068 0069 /** 0070 * A factory for KoShape objects. 0071 * The baseclass for all shape plugins. Each plugin that ships a KoShape should also 0072 * ship a factory. That factory will extend this class and set variable data like 0073 * a toolTip and icon in the constructor of that extending class. 0074 * 0075 * An example usage would be: 0076 @code 0077 class MyShapeFactory : public KoShapeFactoryBase { 0078 public: 0079 MyShapeFactory() 0080 : KoShapeFactoryBase("MyShape", i18n("My Shape")) { 0081 setToolTip(i18n("A nice shape")); 0082 } 0083 ~MyShapeFactory() {} 0084 // more methods here 0085 }; 0086 @endcode 0087 0088 * After you created the factory you should create a plugin that can announce the factory to the 0089 * KoShapeRegistry. See the KoPluginLoader as well. 0090 */ 0091 class FLAKE_EXPORT KoShapeFactoryBase : public QObject 0092 { 0093 Q_OBJECT 0094 public: 0095 0096 /** 0097 * Create the new factory 0098 * @param id a string that will be used internally for referencing the shape, for 0099 * example for use by the KoToolBase::activateTemporary. 0100 * @param name the user visible name of the shape this factory creates. 0101 */ 0102 KoShapeFactoryBase(const QString &id, const QString &name, const QString &deferredPluginName = QString()); 0103 ~KoShapeFactoryBase() override; 0104 0105 /** 0106 * Create a list of option panels to show on creating a new shape. 0107 * The shape type this factory creates may have general or specific setting panels 0108 * that will be shown after inserting a new shape. 0109 * The first item in the list will be shown as the first tab in the list of panels, 0110 * behind all app specific panels. 0111 * This is a separate list as set by setOptionPanels() and fetched by panelFactories() 0112 */ 0113 virtual QList<KoShapeConfigWidgetBase*> createShapeOptionPanels() { 0114 return QList<KoShapeConfigWidgetBase*>(); 0115 } 0116 0117 /** 0118 * Set app specific panel factories to show config options after creating a new shape. 0119 * The application that lets the user create shapes is able to set option 0120 * widgets that will be shown after the user inserted a new shape of the 0121 * type that this factory presents. 0122 * Example: 0123 * @code 0124 * // Init shape Factories with our frame based configuration panels. 0125 * QList<KoShapeConfigFactoryBase *> panels; 0126 * panels.append(new AppConfigFactory()); // insert some factory 0127 * foreach(QString id, KoShapeRegistry::instance()->keys()) 0128 * KoShapeRegistry::instance()->value(id)->setOptionPanels(panels); 0129 * @endcode 0130 * @see panelFactories() 0131 */ 0132 void setOptionPanels(const QList<KoShapeConfigFactoryBase*> &panelFactories); 0133 0134 /** 0135 * Return the app-specific panels. 0136 * @see setOptionPanels() 0137 */ 0138 QList<KoShapeConfigFactoryBase*> panelFactories() const; 0139 0140 /** 0141 * return the id for the shape this factory creates. 0142 * @return the id for the shape this factory creates. 0143 */ 0144 QString id() const; 0145 /** 0146 * Return all the templates this factory knows about. 0147 * Each template shows a different way to create a shape this factory is specialized in. 0148 */ 0149 QList<KoShapeTemplate> templates() const; 0150 /** 0151 * return a translated tooltip Text for a selector of shapes 0152 * @return a translated tooltip Text 0153 */ 0154 QString toolTip() const; 0155 /** 0156 * return the basename of the icon for a selector of shapes 0157 * @return the basename of the icon for a selector of shapes 0158 */ 0159 QString iconName() const; 0160 /** 0161 * return the user visible (and translated) name to be seen by the user. 0162 * @return the user visible (and translated) name to be seen by the user. 0163 */ 0164 QString name() const; 0165 /** 0166 * return the non-visible name of the family the default shape belongs to. 0167 * @return the family name. 0168 */ 0169 QString family() const; 0170 /// lower prio means the shape is more generic and will be checked later 0171 int loadingPriority() const; 0172 0173 /** 0174 * The list of namespaces to the supported elements the factory supports. 0175 */ 0176 QList<QPair<QString, QStringList> > odfElements() const; 0177 0178 /// returns true if this shapeFactory is able to load the ODF type 0179 /// started at argument element. ('draw:line' / 'draw:frame' / etc) 0180 virtual bool supports(const KoXmlElement &element, KoShapeLoadingContext &context) const = 0; 0181 0182 /** 0183 * The hidden boolean requests if the shape should be hidden in the 0184 * shape selector or shown with all its templates. 0185 * The default is false 0186 * @see setHidden() 0187 */ 0188 bool hidden() const; 0189 0190 /** 0191 * This method is called whenever there is a new document resource 0192 * manager that is created. The factory may reimplement this in 0193 * order to get existing resources or put factory specific resources in. 0194 * In case the factory creates new resources it is advised to parent 0195 * them to the manager (which is a QObject) for memory management 0196 * purposes. 0197 * 0198 * FIXME: this method is only used by Tables. We should refactor so 0199 * it is no longer necessary. 0200 * 0201 * NOTE: this actually is also used somehow to create the imagecollection 0202 * for the picture shape? 0203 * 0204 * NOTE: we store the documentmanagers in a list, and remove them 0205 * from the list on delete. 0206 * 0207 * @param manager the new manager 0208 */ 0209 virtual void newDocumentResourceManager(KoDocumentResourceManager *manager) const; 0210 QList<KoDocumentResourceManager *> documentResourceManagers() const; 0211 0212 /** 0213 * This method should be implemented by factories to create a shape that the user 0214 * gets when doing a base insert. For example from a script. The created shape 0215 * should have its values set to good defaults that the user can then adjust further if 0216 * needed. Including the KoShape:setShapeId(), with the Id from this factory 0217 * The default shape position is not relevant, it will be moved by the caller. 0218 * @param documentResources the resources manager that has all the document wide 0219 * resources which can be used to create the object. 0220 * @return a new shape 0221 * @see createShape() newDocumentResourceManager() 0222 */ 0223 virtual KoShape *createDefaultShape(KoDocumentResourceManager *documentResources = 0) const; 0224 0225 /** 0226 * This method should be implemented by factories to create a shape based on a set of 0227 * properties that are specifically made for this shape-type. 0228 * This method should also set this factories shapeId on the shape using KoShape::setShapeId() 0229 * The default implementation just ignores 'params' and calls createDefaultShape() 0230 * @return a new shape 0231 * @param params the parameters to use when creating the shape 0232 * @param documentResources the resources manager that has all the document wide 0233 * resources which can be used to create the object. 0234 * @see createDefaultShape() newDocumentResourceManager() addTemplate() 0235 * @see KoShapeTemplate::properties 0236 */ 0237 virtual KoShape *createShape(const KoProperties *params, KoDocumentResourceManager *documentResources = 0) const; 0238 0239 /** 0240 * This method provides the default implementation for creating a shape 0241 * from a specified xml element of an odf document. 0242 * Most derived factories do not need to reimplement this method, however if a factory 0243 * has some special requirements or does something special it is still possible. 0244 * One example is creating different shapes depending on the content of the passed 0245 * xml element. 0246 */ 0247 virtual KoShape *createShapeFromOdf(const KoXmlElement &element, KoShapeLoadingContext &context); 0248 0249 protected: 0250 0251 /** 0252 * Add a template with the properties of a specific type of shape this factory can generate 0253 * using the createShape() method. The factory will take ownership of the properties object 0254 * to which the member @p properties of @p params points to and destroy it only in its own destructor. 0255 * @param params the new template this factory knows to produce 0256 */ 0257 void addTemplate(const KoShapeTemplate ¶ms); 0258 0259 /** 0260 * Set the tooltip to be used for a selector of shapes 0261 * @param tooltip the tooltip 0262 */ 0263 void setToolTip(const QString &tooltip); 0264 0265 /** 0266 * Set an icon to be used in a selector of shapes 0267 * @param iconName the name of the icon per icon theme spec 0268 */ 0269 void setIconName(const QString &iconName); 0270 0271 /** 0272 * Set the family name of the default shape 0273 * @param family the family name of the default shape this factory creates. 0274 * for example "funny", "arrows", "geometrics". Use "" for default 0275 */ 0276 void setFamily(const QString &family); 0277 0278 /** 0279 * Set the loading priority for this icon; higher priority means 0280 * the shape is more specific which means it will be earlier in 0281 * the queue to try loading a particular odf element. 0282 */ 0283 void setLoadingPriority(int priority); 0284 0285 /** 0286 * Set the namespace and element tags used for quick checking whether this shapefactory 0287 * is able to create a shape from xml identified by this element 0288 * name. 0289 * 0290 * @param nameSpace the ODF name space (like 0291 * urn:oasis:names:tc:opendocument:xmlns:text:1.0, 0292 * take it from KoXmlNS.h) 0293 * @param elementNames the name of the element itself, like "path" 0294 * 0295 */ 0296 void setXmlElementNames(const QString &nameSpace, const QStringList &elementNames); 0297 0298 /** 0299 * Set the namespaces and according element tags used for quick checking whether this shapefactory 0300 * is able to create a shape from xml identified by this element 0301 * name. 0302 * 0303 * @param elementNamesList containing a list of namespace (like 0304 * urn:oasis:names:tc:opendocument:xmlns:text:1.0, 0305 * take it from KoXmlNS.h) to a list of elementName of the element itself, like "path" 0306 */ 0307 void setXmlElements(const QList<QPair<QString, QStringList> > &elementNamesList); 0308 0309 /** 0310 * The hidden boolean requests if the shape should be hidden in the 0311 * shape selector or shown with all its templates. 0312 * The default is false 0313 * @see hidden() 0314 */ 0315 void setHidden(bool hidden); 0316 0317 private: 0318 0319 void getDeferredPlugin(); 0320 0321 private Q_SLOTS: 0322 0323 /// called whenever a document KoDocumentResourceManager is deleted 0324 void pruneDocumentResourceManager(QObject *); 0325 0326 private: 0327 0328 class Private; 0329 Private * const d; 0330 }; 0331 0332 #endif