1 | /* This file is part of the KDE project |
2 | Copyright (C) 2001 Christoph Cullmann <cullmann@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License version 2 as published by the Free Software Foundation. |
7 | |
8 | This library is distributed in the hope that it will be useful, |
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | Library General Public License for more details. |
12 | |
13 | You should have received a copy of the GNU Library General Public License |
14 | along with this library; see the file COPYING.LIB. If not, write to |
15 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | Boston, MA 02110-1301, USA. |
17 | */ |
18 | |
19 | #ifndef DOCUMENTMANAGER_H |
20 | #define DOCUMENTMANAGER_H |
21 | |
22 | #include <kate_export.h> |
23 | |
24 | #include <QtCore/QObject> |
25 | #include <kurl.h> |
26 | |
27 | namespace KTextEditor |
28 | { |
29 | class Document; |
30 | } |
31 | |
32 | namespace Kate |
33 | { |
34 | /** |
35 | * \brief Interface for the document manager. |
36 | * |
37 | * This interface provides access to Kate's document manager. The document |
38 | * manager manages all documents. Use document() get a given document, |
39 | * activeDocument() to retrieve the active document. Check with isOpen() |
40 | * whether an URL is opened and use findDocument() to get it. To get the |
41 | * number of managed documents use documents(). |
42 | * |
43 | * Open new documents with openUrl() and close a document with closeDocument() |
44 | * or closeAllDocuments(). Several signals are provided, documentChanged() is |
45 | * emitted whenever the document's content changed, documentCreated() when a |
46 | * new document was created and documentDeleted() when a document was closed. |
47 | * |
48 | * To access the document manager use the global accessor function |
49 | * documentManager() or Application::documentManager(). You should never have |
50 | * to create an instance of this class yourself. |
51 | * |
52 | * \author Christoph Cullmann \<cullmann@kde.org\> |
53 | */ |
54 | class KATEINTERFACES_EXPORT DocumentManager : public QObject |
55 | { |
56 | friend class PrivateDocumentManager; |
57 | |
58 | Q_OBJECT |
59 | |
60 | public: |
61 | /** |
62 | * Construtor. |
63 | * |
64 | * The constructor is internally used by the Kate application, so it is |
65 | * of no interest for plugin developers. Plugin developers should use the |
66 | * global accessor pluginManager() instead. |
67 | * |
68 | * \param documentManager internal usage |
69 | * |
70 | * \internal |
71 | */ |
72 | DocumentManager ( void *documentManager ); |
73 | /** |
74 | * Virtual destructor. |
75 | */ |
76 | virtual ~DocumentManager (); |
77 | |
78 | public: |
79 | /** |
80 | * Get a list of all documents. |
81 | * @return all documents |
82 | */ |
83 | const QList<KTextEditor::Document*> &documents () const; |
84 | |
85 | /** |
86 | * Get the document with the URL \p url. |
87 | * if multiple documents match the searched url, return the first found one... |
88 | * \param url the document's URL |
89 | * \return the document with the given \p url or NULL, if no such document |
90 | * is in the document manager's internal list. |
91 | */ |
92 | KTextEditor::Document *findUrl (const KUrl &url) const; |
93 | |
94 | /** |
95 | * Open the document \p url with the given \p encoding. |
96 | * if the url is empty, a new empty document will be created |
97 | * \param url the document's url |
98 | * \param encoding the preferred encoding. If encoding is QString() the |
99 | * encoding will be guessed or the default encoding will be used. |
100 | * \return a pointer to the created document |
101 | */ |
102 | KTextEditor::Document *openUrl (const KUrl &url, const QString &encoding = QString()); |
103 | |
104 | /** |
105 | * Close the given \p document. |
106 | * \param document the document to be closed |
107 | * \return \e true on success, otherwise \e false |
108 | */ |
109 | bool closeDocument (KTextEditor::Document* document); |
110 | |
111 | /** |
112 | * Close a list of documents. If any of them are modified, show a "save modified" dialog. |
113 | * \param documents list of documents to be closed |
114 | * \return \e true on success, otherwise \e false |
115 | */ |
116 | bool closeDocumentList (QList<KTextEditor::Document*> documents); |
117 | |
118 | // |
119 | // SIGNALS !!! |
120 | // |
121 | #ifndef Q_MOC_RUN |
122 | #undef signals |
123 | #define signals public |
124 | #endif |
125 | signals: |
126 | #ifndef Q_MOC_RUN |
127 | #undef signals |
128 | #define signals protected |
129 | #endif |
130 | |
131 | /** |
132 | * This signal is emitted when the \p document was created. |
133 | */ |
134 | void documentCreated (KTextEditor::Document *document); |
135 | |
136 | /** |
137 | * This signal is emitted before a \p document which should be closed is deleted |
138 | * The document is still accessible and usable, but it will be deleted |
139 | * after this signal was send. |
140 | */ |
141 | void documentWillBeDeleted (KTextEditor::Document *document); |
142 | |
143 | /** |
144 | * This signal is emitted when the \p document has been deleted. |
145 | * |
146 | * Warning !!! DO NOT ACCESS THE DATA REFERENCED BY THE POINTER, IT IS ALREADY INVALID |
147 | * Use the pointer only to remove mappings in hash or maps |
148 | */ |
149 | void documentDeleted (KTextEditor::Document *document); |
150 | |
151 | /** |
152 | * will be loading a bunch of documents, you can step back for a while |
153 | */ |
154 | void aboutToLoadDocuments(); |
155 | |
156 | /** |
157 | * bunch of documents have been loaded, you can come back |
158 | */ |
159 | void documentsLoaded(const QList<KTextEditor::Document *> &); |
160 | |
161 | /** |
162 | * signal which documents are going to be deleted soon |
163 | * |
164 | * note that the batch can be interupted in the middle and only some |
165 | * of the documents may be actually deleted. See @documentsDeleted signal. |
166 | */ |
167 | void aboutToDeleteDocuments(const QList<KTextEditor::Document *> &); |
168 | |
169 | /** |
170 | * the batch closing signal for @aboutToDeleteDocuments |
171 | * @documents the documents that weren't deleted after all |
172 | */ |
173 | void documentsDeleted(const QList<KTextEditor::Document *> &documents); |
174 | |
175 | private: |
176 | class PrivateDocumentManager *d; |
177 | }; |
178 | |
179 | /** |
180 | * Global accessor to the document manager object. |
181 | * \return document manager object |
182 | */ |
183 | KATEINTERFACES_EXPORT DocumentManager *documentManager (); |
184 | |
185 | } |
186 | |
187 | #endif // DOCUMENTMANAGER_H |
188 | |
189 | // kate: space-indent on; indent-width 2; replace-tabs on; |
190 | |