File indexing completed on 2024-05-12 16:39:38
0001 /* This file is part of the KDE project 0002 Copyright (C) 2003 Lucijan Busch <lucijan@kde.org> 0003 Copyright (C) 2003-2014 Jarosław Staniek <staniek@kde.org> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Library General Public 0007 License as published by the Free Software Foundation; either 0008 version 2 of the License, or (at your option) any later version. 0009 0010 This library is distributed in the hope that it will be useful, 0011 but WITHOUT ANY WARRANTY; without even the implied warranty of 0012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0013 Library General Public License for more details. 0014 0015 You should have received a copy of the GNU Library General Public License 0016 along with this library; see the file COPYING.LIB. If not, write to 0017 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0018 * Boston, MA 02110-1301, USA. 0019 */ 0020 0021 #ifndef KEXIPART_H 0022 #define KEXIPART_H 0023 0024 #include <QObject> 0025 #include <QMap> 0026 0027 #include <kexiutils/InternalPropertyMap.h> 0028 #include "kexipartbase.h" 0029 0030 #include <KDbTristate> 0031 0032 class KActionCollection; 0033 class KexiWindow; 0034 class KexiWindowData; 0035 class KexiView; 0036 class KDbQuerySchema; 0037 class QAction; 0038 class QKeySequence; 0039 0040 namespace KexiPart 0041 { 0042 class Item; 0043 class GUIClient; 0044 class StaticPartInfo; 0045 0046 /*! Official (registered) type IDs for objects like table, query, form... */ 0047 enum ObjectType { 0048 UnknownObjectType = KDb::UnknownObjectType, //!< -1, helper 0049 AnyObjectType = KDb::AnyObjectType, //!< 0, helper 0050 TableObjectType = KDb::TableObjectType, //!< 1, like in KDb::ObjectType 0051 QueryObjectType = KDb::QueryObjectType, //!< 2, like in KDb::ObjectType 0052 FormObjectType = 3, 0053 ReportObjectType = 4, 0054 ScriptObjectType = 5, 0055 WebObjectType = 6, 0056 MacroObjectType = 7, 0057 LastObjectType = 7, //ALWAYS UPDATE THIS 0058 0059 UserObjectType = 100 //!< external types 0060 }; 0061 0062 //! @return Kexi Part API version: "major.minor" 0063 //! @since 3.1 0064 KEXICORE_EXPORT QString version(); 0065 0066 //! @short The main class for kexi frontend parts (plugins) like tables, queries, forms and reports 0067 /*! 0068 Plugins create windows (KexiWindow) for a given type of object. 0069 0070 Notes for plugins implementors: This class supports InternalPropertyMap interface, 0071 so supported internal properties affecting its behaviour are: 0072 - newObjectsAreDirty: True if newly created, unsaved objects are dirty. False by default. 0073 - textViewModeCaption: custum i18n'd action text replacing standard "Text View" text. 0074 Used in for query's "SQL View". 0075 In general: a whole set of i18n'd action names, initialised on KexiPart::Part subclass ctor. 0076 The names are useful because the same action can have other name for each part, 0077 e.g. "New table" vs "New query" can have different forms for some languages. 0078 So this is a flexible way for customizing translatable strings. 0079 */ 0080 class KEXICORE_EXPORT Part : public PartBase 0081 { 0082 Q_OBJECT 0083 0084 public: 0085 virtual ~Part(); 0086 0087 //! @todo make it protected, outside world should use KexiProject 0088 /*! Try to execute the part. Implementations of this \a Part 0089 are able to overwrite this method to offer execution. 0090 \param item The \a KexiPart::Item that should be executed. 0091 \param sender The sender QObject which likes to execute this \a Part or 0092 NULL if there is no sender. The KFormDesigner uses this to pass 0093 the actual widget (e.g. the button that was pressed). 0094 \return true if execution was successfully else false. 0095 */ 0096 virtual bool execute(KexiPart::Item* item, QObject* sender = 0) { 0097 Q_UNUSED(item); 0098 Q_UNUSED(sender); 0099 return false; 0100 } 0101 0102 //! @todo make it protected, outside world should use KexiProject 0103 /*! "Opens" an instance that the part provides, pointed by \a item in a mode \a viewMode. 0104 \a viewMode is one of Kexi::ViewMode enum. 0105 \a staticObjectArgs can be passed for static Kexi Parts. 0106 The new widget will be a child of \a parent. */ 0107 KexiWindow* openInstance(QWidget* parent, KexiPart::Item *item, 0108 Kexi::ViewMode viewMode = Kexi::DataViewMode, QMap<QString, QVariant>* staticObjectArgs = 0); 0109 0110 //! @todo make it protected, outside world should use KexiProject 0111 /*! Removes any stored data pointed by \a item (example: table is dropped for table part). 0112 From now this data is inaccesible, and \a item disappear. 0113 You do not need to remove \a item, or remove object's schema stored in the database, 0114 beacuse this will be done automatically by KexiProject after successful 0115 call of this method. All object's data blocks are also automatically removed from database 0116 (from "kexi__objectdata" table). 0117 For this, a database connection associated with kexi project owned by \a win can be used. 0118 0119 Database transaction is started by KexiProject before calling this method, 0120 and it will be rolled back if you return false here. 0121 You shouldn't use by hand transactions here. 0122 0123 Default implementation just removes object from kexi__* system structures 0124 at the database backend using KDbConnection::removeObject(). */ 0125 virtual tristate remove(KexiPart::Item *item); 0126 0127 /*! Renames stored data pointed by \a item to \a newName 0128 (example: table name is altered in the database). 0129 For this, a database connection associated with kexi project owned by \a win can be used. 0130 You do not need to change \a item, and change object's schema stored in the database, 0131 beacuse this is automatically handled by KexiProject. 0132 0133 Database transaction is started by KexiProject before calling this method, 0134 and it will be rolled back if you return false here. 0135 You shouldn't use by hand transactions here. 0136 0137 Default implementation does nothing and returns true. */ 0138 virtual tristate rename(KexiPart::Item *item, const QString& newName); 0139 0140 /*! Creates and returns a new temporary data for a window \a window. 0141 This method is called on openInstance() once per dialog. 0142 Reimplement this to return KexiWindowData subclass instance. 0143 Default implemention just returns empty KexiWindowData object. */ 0144 Q_REQUIRED_RESULT virtual KexiWindowData *createWindowData(KexiWindow *window); 0145 0146 /*! Creates a new view for mode \a viewMode, \a item and \a parent. The view will be 0147 used inside \a dialog. */ 0148 virtual KexiView *createView(QWidget *parent, KexiWindow *window, KexiPart::Item *item, 0149 Kexi::ViewMode viewMode = Kexi::DataViewMode, 0150 QMap<QString, QVariant> *staticObjectArgs = nullptr) /*Q_REQUIRED_RESULT*/ = 0; 0151 0152 //virtual void initTabs(); 0153 0154 /*! @return i18n'd instance name usable for displaying in gui as object's name, 0155 e.g. "table". 0156 The name is valid identifier - contains latin-1 lowercase characters only. */ 0157 QString instanceName() const; 0158 0159 /*! @return i18n'd tooltip that can also act as descriptive name of the action. 0160 Example: "Create new table". */ 0161 QString toolTip() const; 0162 0163 /*! @return i18n'd "what's this" string. Example: "Creates new table." */ 0164 QString whatsThis() const; 0165 0166 /*! \return part's GUI Client, so you can 0167 create part-wide actions using this client. */ 0168 GUIClient *guiClient() const; 0169 0170 /*! \return part's GUI Client, so you can 0171 create instance-wide actions using this client. */ 0172 GUIClient *instanceGuiClient(Kexi::ViewMode mode = Kexi::AllViewModes) const; 0173 0174 /*! \return action collection for mode \a viewMode. */ 0175 KActionCollection* actionCollectionForMode(Kexi::ViewMode viewMode) const; 0176 0177 const Kexi::ObjectStatus& lastOperationStatus() const; 0178 0179 /*! \return query schema currently edited in the \a view. 0180 * It may be the original/saved query if user has no unsaved changes so far 0181 * or a temporary unsaved query if there are unsaved modifications. 0182 * The query can be used for example by data exporting routines so user can 0183 * export result of a running unsaved query without prior saving it. For implementation in plugins. */ 0184 virtual KDbQuerySchema *currentQuery(KexiView* view); 0185 0186 /*! @internal 0187 Creates GUIClients for this part, attached to the main window. 0188 This method is called by KexiMainWindow. */ 0189 void createGUIClients(); 0190 0191 Q_SIGNALS: 0192 void newObjectRequest(KexiPart::Info *info); 0193 0194 protected: 0195 /*! 0196 Creates new Plugin 0197 @param parent parent of this plugin 0198 @param instanceName i18n'd instance name written using only lowercase alphanumeric 0199 characters (a..z, 0..9). 0200 Use '_' character instead of spaces. First character should be a..z character. 0201 If you cannot use latin characters in your language, use english word. 0202 Example: "table". 0203 @param toolTip i18n'd tooltip that can also act as descriptive name of the action. 0204 Example: "Create new table". 0205 @param whatsThis i18n'd "what's this" string. Example: "Creates new table." 0206 @param list extra arguments passed to the plugin 0207 */ 0208 Part(QObject *parent, 0209 const QString& instanceName, 0210 const QString& toolTip, 0211 const QString& whatsThis, 0212 const QVariantList& list); 0213 0214 //! Used by StaticPart 0215 Part(QObject* parent, StaticPartInfo *info); 0216 0217 virtual void initPartActions(); 0218 virtual void initInstanceActions(); 0219 0220 /*! Can be reimplemented if object data is extended beyond the default set of properties. This 0221 is the case for table and query schema objects, where object of KDbObject subclass is returned. 0222 In this case value pointed by @a ownedByWindow is set to false. Default implemenatation returns 0223 owned KDbObject object (value pointed by @a ownedByWindow is set to true). 0224 @a ownedByWindow is required. */ 0225 Q_REQUIRED_RESULT virtual KDbObject *loadSchemaObject(KexiWindow *window, const KDbObject &object, 0226 Kexi::ViewMode viewMode, bool *ownedByWindow); 0227 0228 bool loadDataBlock(KexiWindow *window, QString *dataString, const QString& dataID = QString()); 0229 0230 /*! Creates shared action for action collection declared 0231 for 'instance actions' of this part. 0232 See KexiSharedActionHost::createSharedAction() for details. 0233 Pass desired QAction subclass with \a subclassName (e.g. "KToggleAction") to have 0234 that subclass allocated instead just QAction (what is the default). */ 0235 QAction * createSharedAction(Kexi::ViewMode mode, const QString &text, 0236 const QString &pix_name, const QKeySequence &cut, const char *name, 0237 const char *subclassName = 0); 0238 0239 /*! Convenience version of above method - creates shared toggle action. */ 0240 QAction * createSharedToggleAction(Kexi::ViewMode mode, const QString &text, 0241 const QString &pix_name, const QKeySequence &cut, const char *name); 0242 0243 /*! Creates shared action for action collection declared 0244 for 'part actions' of this part. 0245 See KexiSharedActionHost::createSharedAction() for details. 0246 Pass desired QAction subclass with \a subclassName (e.g. "KToggleAction") to have 0247 that subclass allocated instead just QAction (what is the default). */ 0248 QAction * createSharedPartAction(const QString &text, 0249 const QString &pix_name, const QKeySequence &cut, const char *name, 0250 const char *subclassName = 0); 0251 0252 /*! Convenience version of above method - creates shared toggle action 0253 for 'part actions' of this part. */ 0254 QAction * createSharedPartToggleAction(const QString &text, 0255 const QString &pix_name, const QKeySequence &cut, const char *name); 0256 0257 void setActionAvailable(const char *action_name, bool avail); 0258 0259 private: 0260 //! Calls loadSchemaObject() (virtual), updates ownership of object data for @a window 0261 //! and assigns the created data to @a window. 0262 void loadAndSetSchemaObject(KexiWindow *window, const KDbObject& object, 0263 Kexi::ViewMode viewMode); 0264 0265 Q_DISABLE_COPY(Part) 0266 0267 class Private; 0268 Private * const d; 0269 0270 friend class Manager; 0271 friend class ::KexiWindow; 0272 friend class GUIClient; 0273 }; 0274 0275 /*! \return full caption for item \a item and part \a part. 0276 If \a part is provided, the captions will be in a form of "name : inctancetype", e.g. "Employees : Table", 0277 otherwise it will be in a form of "name", e.g. "Employees". */ 0278 KEXICORE_EXPORT QString fullCaptionForItem(KexiPart::Item *item, KexiPart::Part *part); 0279 0280 } // namespace KexiPart 0281 0282 #endif