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 | |
28 | namespace KTextEditor |
29 | { |
30 | |
31 | class Document; |
32 | class 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 | */ |
65 | class 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 | */ |
166 | class 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 | */ |
269 | class 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 | |
307 | Q_DECLARE_INTERFACE(KTextEditor::ContainerInterface, "org.kde.KTextEditor.ContainerInterface" ) |
308 | Q_DECLARE_INTERFACE(KTextEditor::MdiContainer, "org.kde.KTextEditor.MdiContainer" ) |
309 | Q_DECLARE_INTERFACE(KTextEditor::ViewBarContainer, "org.kde.KTextEditor.ViewBarContainer" ) |
310 | #endif // KDELIBS_KTEXTEDITOR_CONTAINER_EXTENSION_H |
311 | |