← Back to branch summary

~ubuntu-branches/ubuntu/vivid/kate/vivid-updates

« back to all changes in this revision

Viewing changes to ktexteditor/containerinterface.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2014-12-04 16:49:41 UTC
  • mfrom: (1.6.6)
  • Revision ID: package-import@ubuntu.com-20141204164941-l3qbvsly83hhlw2v
Tags: 4:14.11.97-0ubuntu1
* New upstream release
* Update build-deps and use pkg-kde v3 for Qt 5 build
* kate-data now kate5-data for co-installability

Show diffs side-by-side

added added

removed removed

Lines of Context:
ktexteditor/containerinterface.h
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