1/* This file is part of the KDE libraries
2 Copyright (C) 2007 Philippe Fremy (phil at freehackers dot org)
3 Copyright (C) 2008 Joseph Wenninger (jowenn@kde.org)
4
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 version 2 as published by the Free Software Foundation.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KDELIBS_KTEXTEDITOR_CONTAINER_INTERFACE_H
22#define KDELIBS_KTEXTEDITOR_CONTAINER_INTERFACE_H
23
24#include <ktexteditor/ktexteditor_export.h>
25
26#include <QtCore/QObject>
27
28namespace KTextEditor
29{
30
31class Document;
32class View;
33
34
35/**
36 * \brief Class that allows the kpart host to provide some extensions.
37 *
38 * \ingroup kte_group_editor_extensions
39 *
40 * The KTextEditor framework allows the kpart host to provide additional
41 * services to the kpart. Those services are provided through the
42 * ContainerInterface class.
43 *
44 * If the container supports those specific services, it should set an
45 * instance of the service class with ContainerInterface::setContainer(). That
46 * instance should inherit QObject, have the Q_OBJECT macro and declare a
47 * Q_INTERFACES(), in order for the qobject_cast mechanism to work.
48 *
49 * To obtain a ContainerInterface, in order to set a specific container
50 * extension, the kpart host should do:
51 * \code
52 * // inside the kpart host
53 * Editor * editor = KTextEditor::EditorChooser::editor();
54 * ContainerInterface * iface = qobject_cast<ContainerInterface *>( editor );
55 * if (iface != NULL) {
56 * iface->setContainer( myContainerExtension );
57 * } else {
58 * // the kpart does not support ContainerInterface.
59 * }
60 * \endcode
61 *
62 * It is then up to the kpart to use it.
63 *
64 */
65class KTEXTEDITOR_EXPORT ContainerInterface
66{
67 public:
68 /**
69 * Constructor.
70 */
71 ContainerInterface();
72
73 /** Virtual Destructor */
74 virtual ~ContainerInterface();
75
76 /**
77 * Set the KTextEditor container.
78 *
79 * This method is used by the KTextEditor host to set an instance
80 * of a class providing optional container extensions.
81 *
82 * \sa container
83 */
84 virtual void setContainer( QObject * container ) = 0;
85
86 /**
87 * Fetch the container extension.
88 *
89 * This method is used by the KTextEditor component to know
90 * which extensions are supported by the KTextEditor host.
91 *
92 * The kpart will cast the result with qobject_cast() to the right
93 * container extension to see if that particular extension is supported:
94 *
95 * <b>Example:</b>
96 * \code
97 * // inside the kpart
98 *
99 * Editor * editor = KTextEditor::EditorChooser::editor();
100 * ContainerInterface * iface = qobject_cast<ConainterInterace *>( editor );
101 * SomeContainerExtension * myExt =
102 * qobject_cast<SomeContainerExtension *>( iface->container() );
103 *
104 * if (myExt) {
105 * // do some stuff with the specific container extension
106 * // ...
107 * } else {
108 * // too bad, that extension is not supported.
109 * }
110 * \endcode
111 *
112 * \sa setContainer
113 */
114 virtual QObject * container() = 0;
115}; // class ContainerInterface
116
117/**
118 * A container for MDI-capable kpart hosts.
119 *
120 * The kpart container for the KTextEditor interface may have different
121 * capabilities. For example, inside KDevelop or Kate, the container can
122 * manage multiple views and multiple documents. However, if the kpart text
123 * is used inside konqueror as a replacement of the text entry in html
124 * forms, the container will only support one view with one document.
125 *
126 * This class allows the kpart component to create and delete views, create
127 * and delete documents, fetch and set the current view. Note that the
128 * ktexteditor framework already supports multiple document and views and
129 * that the kpart host can create them and delete them as it wishes. What
130 * this class provides is the ability for the <i>kpart component</i> being
131 * hosted to do the same.
132 *
133 * An instance of this extension should be set with
134 * ContainerInterface::setContainerExtension().Check ContainerInterface() to
135 * see how to obtain an instance of ContainerInterface. The instance should
136 * inherit QObject, inherit MdiContainer, declare the Q_OBJECT macro and
137 * declare a Q_INTERFACES(KTextEditor::MdiContainer) .
138 *
139 * Code example to support MdiContainer (in the kpart host):
140 * \code
141 * class MyMdiContainer : public QObject,
142 * public MdiContainer
143 * {
144 * Q_OBJECT
145 * Q_INTERFACES( KTextEditor::MdiContainer )
146 *
147 * public:
148 * // ...
149 * }
150 * \endcode
151 *
152 *
153 * To check if the kpart hosts supports the MDI container:
154 * \code
155 * Editor * editor = KTextEditor::EditorChooser::editor();
156 * ContainerInterface * iface = qobject_cast<ContainerInterface *>( editor );
157 * if (iface) {
158 * MdiContainer * mdiContainer = qobject_cast<MdiContainer *>( iface->container() );
159 * if (MdiContainer != NULL ) {
160 * // great, I can create additional views
161 * // ...
162 * }
163 * }
164 * \endcode
165 */
166class KTEXTEDITOR_EXPORT MdiContainer
167{
168 public:
169
170 /** Constructor */
171 MdiContainer();
172
173 /** Virtual destructor */
174 virtual ~MdiContainer();
175
176 /**
177 * Set the \p view requested by the part as the active view.
178 *
179 * \sa activeView
180 */
181 virtual void setActiveView( View * view )=0;
182
183 /**
184 * Get the current activew view.
185 *
186 * \return the active view.
187 *
188 * \sa setActiveView
189 */
190 virtual View * activeView()=0;
191
192 /**
193 * Create a new Document and return it to the kpart.
194 *
195 * Canonical implementation is:
196 * \code
197 * Document * createDocument()
198 * {
199 * Document * doc;
200 * // set parentQObject to relevant value
201 * doc = editor->createDocument( parentQObject );
202 * // integrate the new document in the document list of the
203 * // container, ...
204 * return doc;
205 * }
206 * \endcode
207 *
208 * The signal documentCreated() will be emitted during the creation.
209 *
210 * \return a pointer to the new Document object.
211 */
212 virtual Document * createDocument()=0;
213
214 /**
215 * Closes of document \p doc .
216 *
217 * The document is about to be closed but is still valid when this
218 * call is made. The Document does not contain any view when this
219 * call is made (closeView() has been called on all the views of the
220 * document previously).
221 *
222 * The signal aboutToClose() is emitted before this method is
223 * called.
224 *
225 * \return true if the removal is authorized and acted, or
226 * false if removing documents by the kpart is not supported
227 * by the container.
228 */
229 virtual bool closeDocument( Document * doc )=0;
230
231 /**
232 * Creates a new View and return it to the kpart.
233 *
234 * Canonical implementation is:
235 * \code
236 * View * createView( Document * doc )
237 * {
238 * // set parentWidget to relevant value
239 * return doc->createView( parentWidget );
240 * }
241 * \endcode
242 *
243 * The signal viewCreated() will be emitted during the createView()
244 * call.
245 *
246 * \return a pointer to the new View created.
247 */
248 virtual View * createView( Document * doc )=0;
249
250 /**
251 * Closes the View \p view .
252 *
253 * The view is still valid when this call is made but will be deleted
254 * shortly after.
255 *
256 * \return true if the removal is authorized and acted, or
257 * false if the container does not support view removing from
258 * the kpart, or
259 */
260 virtual bool closeView( View * view )=0;
261}; // class MdiContainer
262
263
264/**
265 * An application providing a centralized place for horizontal view bar containers (eg search bars) has
266 * to implement this
267 * @since 4.2
268 */
269class KTEXTEDITOR_EXPORT ViewBarContainer
270{
271 public:
272 enum Position{LeftBar=0,TopBar=1,RightBar=2,BottomBar=3};
273 /** Constructor */
274 ViewBarContainer();
275
276 /** Virtual destructor */
277 virtual ~ViewBarContainer();
278
279 /** At this point the views parent window has to be already set, so this has to be called after any reparentings
280 * eg.: The implementation in Kate uses view->window() to determine where to place of the container
281 * if 0 is returned, the view has to handle the bar internally
282 */
283 virtual QWidget* getViewBarParent(View *view,enum Position position)=0;
284
285 /** It is advisable to store only QPointers to the bar and its children in the caller after this point.
286 * The container may at any point delete the bar, eg if the container is destroyed
287 * The caller has to ensure that bar->parentWidget() is the widget returned by the previous function
288 */
289 virtual void addViewBarToLayout(View *view,QWidget *bar,enum Position position)=0;
290
291 ///show hide a view bar. The implementor of this interface has to take care for not showing
292 /// the bars of unfocused views, if needed
293 virtual void showViewBarForView(View *view,enum Position position)=0;
294 virtual void hideViewBarForView(View *view,enum Position position)=0;
295
296 /**
297 * The view should not delete the bar by itself, but tell the container to delete the bar.
298 * This is for instance useful, in the destructor of the view. The bar must not life longer
299 * than the view.
300 */
301 virtual void deleteViewBarForView(View *view,enum Position position)=0;
302
303};
304
305} // namespace KTextEditor
306
307Q_DECLARE_INTERFACE(KTextEditor::ContainerInterface, "org.kde.KTextEditor.ContainerInterface")
308Q_DECLARE_INTERFACE(KTextEditor::MdiContainer, "org.kde.KTextEditor.MdiContainer")
309Q_DECLARE_INTERFACE(KTextEditor::ViewBarContainer, "org.kde.KTextEditor.ViewBarContainer")
310#endif // KDELIBS_KTEXTEDITOR_CONTAINER_EXTENSION_H
311