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
27namespace KTextEditor
28{
29 class Document;
30}
31
32namespace 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