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 _KATE_MAINWINDOW_INCLUDE_ |
20 | #define _KATE_MAINWINDOW_INCLUDE_ |
21 | |
22 | #include <kate_export.h> |
23 | |
24 | #include <QtCore/QObject> |
25 | #include <QtGui/QPixmap> |
26 | |
27 | #include <kxmlguifactory.h> |
28 | #include <kurl.h> |
29 | |
30 | class QWidget; |
31 | |
32 | namespace KTextEditor |
33 | { |
34 | class View; |
35 | class Document; |
36 | } |
37 | |
38 | namespace Kate |
39 | { |
40 | class PluginConfigPageInterface; |
41 | class Plugin; |
42 | class PluginView; |
43 | |
44 | /** |
45 | * \brief Interface to a mainwindow. |
46 | * |
47 | * \section mainwindow_intro Introduction |
48 | * The class MainWindow represents a toplevel window, with menu bar, |
49 | * statusbar etc, get it with window(). A mainwindow usually has an active |
50 | * View, access it with activeView(). To set another active view use |
51 | * activateView(). |
52 | * |
53 | * \section mainwindow_toolviews Toolviews |
54 | * |
55 | * It is possible to embedd new toolviews into a mainwindow. To create a |
56 | * toolview use createToolView(), then you can move, hide or show the toolview |
57 | * by using moveToolView(), hideToolView() or showToolView(). |
58 | * |
59 | * With guiFactory() you can access the KXMLGUIFactory framework and add |
60 | * gui clients. |
61 | * |
62 | * To access a mainwindow use the Application object. |
63 | * You should never have to create an instance of this class yourself. |
64 | * |
65 | * \author Christoph Cullmann \<cullmann@kde.org\> |
66 | * \see KXMLGUIFactory |
67 | */ |
68 | class KATEINTERFACES_EXPORT MainWindow : public QObject |
69 | { |
70 | friend class PrivateMainWindow; |
71 | |
72 | Q_OBJECT |
73 | |
74 | public: |
75 | /** |
76 | * Constructor. |
77 | * |
78 | * Create a new mainwindow. You as a plugin developer should never have |
79 | * to create a new mainwindow yourself. Access the mainwindows via the |
80 | * global Application. |
81 | * \param mainWindow internal usage |
82 | * \internal |
83 | */ |
84 | MainWindow (void *mainWindow); |
85 | /** |
86 | * Virtual destructor. |
87 | */ |
88 | virtual ~MainWindow (); |
89 | |
90 | public: /*these are slots for kjs*/ |
91 | /** |
92 | * Accesstor to the XMLGUIFactory. |
93 | * \return the mainwindow's KXMLGUIFactory. |
94 | */ |
95 | KXMLGUIFactory *guiFactory() const; |
96 | |
97 | /** |
98 | * Get the toplevel widget. |
99 | * \return the kate main window. |
100 | */ |
101 | class QWidget *window() const; |
102 | |
103 | /** |
104 | * Access the widget (in the middle of the four sidebars) in which the |
105 | * editor component and the KateTabBar are embedded. This widget is a |
106 | * KVBox, so other child widgets can be embedded themselves under the |
107 | * editor widget. |
108 | * |
109 | * \return the central widget |
110 | */ |
111 | class QWidget *centralWidget() const; |
112 | |
113 | /** |
114 | * Get a list of all views. |
115 | * @return all views |
116 | */ |
117 | const QList<KTextEditor::View *> &views () const; |
118 | |
119 | /* |
120 | * View stuff, here all stuff belong which allows to |
121 | * access and manipulate the KTextEditor::View's we have in this windows |
122 | */ |
123 | public: |
124 | /** |
125 | * Access the active view. |
126 | * \return active view |
127 | */ |
128 | KTextEditor::View *activeView (); |
129 | |
130 | /** |
131 | * Activate the view with the corresponding \p document. |
132 | * If none exist for this document, create one |
133 | * \param document the document |
134 | * \return activated view of this document |
135 | */ |
136 | KTextEditor::View *activateView ( KTextEditor::Document *document ); |
137 | |
138 | /** |
139 | * Open the document \p url with the given \p encoding. |
140 | * \param url the document's url |
141 | * \param encoding the preferred encoding. If encoding is QString() the |
142 | * encoding will be guessed or the default encoding will be used. |
143 | * \return a pointer to the created view for the new document, if a document |
144 | * with this url is already existing, its view will be activated |
145 | */ |
146 | KTextEditor::View *openUrl (const KUrl &url, const QString &encoding = QString()); |
147 | |
148 | // |
149 | // SIGNALS !!! |
150 | // |
151 | #ifndef Q_MOC_RUN |
152 | #undef signals |
153 | #define signals public |
154 | #endif |
155 | signals: |
156 | #ifndef Q_MOC_RUN |
157 | #undef signals |
158 | #define signals protected |
159 | #endif |
160 | |
161 | /** |
162 | * This signal is emitted whenever the active view changes. |
163 | */ |
164 | // TODO: KDE5 add View* parameter: |
165 | // void viewChanged (KTextEditor::View* view); |
166 | void viewChanged (); |
167 | |
168 | /** |
169 | * This signal is emitted whenever a new view is created |
170 | * @since 4.2 |
171 | */ |
172 | void viewCreated(KTextEditor::View * view); |
173 | |
174 | /** |
175 | * This signal is emitted for every unhandled ShortcutOverride in a view |
176 | */ |
177 | void unhandledShortcutOverride (QEvent *e); |
178 | |
179 | /** |
180 | * This signal is emitted when a Plugin::View is created for this main window. |
181 | * |
182 | * @param name name of plugin |
183 | * @param pluginView the new plugin view |
184 | */ |
185 | void pluginViewCreated (const QString &name, Kate::PluginView *pluginView); |
186 | |
187 | /** |
188 | * This signal is emitted when the Plugin::View got deleted. |
189 | * |
190 | * @param name name of plugin |
191 | * @param pluginView the deleted plugin view |
192 | * |
193 | * Warning !!! DO NOT ACCESS THE DATA REFERENCED BY THE POINTER, IT IS ALREADY INVALID |
194 | * Use the pointer only to remove mappings in hash or maps |
195 | */ |
196 | void pluginViewDeleted (const QString &name, Kate::PluginView *pluginView); |
197 | |
198 | /* |
199 | * ToolView stuff, here all stuff belong which allows to |
200 | * add/remove and manipulate the toolview of this main windows |
201 | */ |
202 | public: |
203 | /** |
204 | * Toolview position. |
205 | * A toolview can only be at one side at a time. |
206 | */ |
207 | enum Position { |
208 | Left = 0, /**< Left side. */ |
209 | Right = 1, /**< Right side. */ |
210 | Top = 2, /**< Top side. */ |
211 | Bottom = 3 /**< Bottom side. */ |
212 | }; |
213 | |
214 | /** |
215 | * Create a new toolview with unique \p identifier at side \p pos |
216 | * with \p icon and caption \p text. Use the returned widget to embedd |
217 | * your widgets. |
218 | * \param identifier unique identifier for this toolview |
219 | * \param pos position for the toolview, if we are in session restore, |
220 | * this is only a preference |
221 | * \param icon icon to use in the sidebar for the toolview |
222 | * \param text translated text (i18n()) to use in addition to icon |
223 | * \return created toolview on success, otherwise NULL |
224 | * @deprecated |
225 | */ |
226 | QWidget *createToolView (const QString &identifier, MainWindow::Position pos, const QPixmap &icon, const QString &text); |
227 | |
228 | /** |
229 | * Create a new toolview with unique \p identifier at side \p pos |
230 | * with \p icon and caption \p text. Use the returned widget to embedd |
231 | * your widgets. |
232 | * \param plugin which owns this tool view |
233 | * \param identifier unique identifier for this toolview |
234 | * \param pos position for the toolview, if we are in session restore, |
235 | * this is only a preference |
236 | * \param icon icon to use in the sidebar for the toolview |
237 | * \param text translated text (i18n()) to use in addition to icon |
238 | * \return created toolview on success, otherwise NULL |
239 | */ |
240 | QWidget *createToolView (Kate::Plugin* plugin, const QString &identifier, MainWindow::Position pos, const QPixmap &icon, const QString &text); |
241 | |
242 | /** |
243 | * Move the toolview \p widget to position \p pos. |
244 | * \param widget the toolview to move, where the widget was constructed |
245 | * by createToolView(). |
246 | * \param pos new position to move widget to |
247 | * \return \e true on success, otherwise \e false |
248 | */ |
249 | bool moveToolView (QWidget *widget, MainWindow::Position pos); |
250 | |
251 | /** |
252 | * Show the toolview \p widget. |
253 | * \param widget the toolview to show, where the widget was constructed |
254 | * by createToolView(). |
255 | * \return \e true on success, otherwise \e false |
256 | * \todo add focus parameter: bool showToolView (QWidget *widget, bool giveFocus ); |
257 | */ |
258 | bool showToolView (QWidget *widget); |
259 | |
260 | /** |
261 | * Hide the toolview \p widget. |
262 | * \param widget the toolview to hide, where the widget was constructed |
263 | * by createToolView(). |
264 | * \return \e true on success, otherwise \e false |
265 | */ |
266 | bool hideToolView (QWidget *widget); |
267 | |
268 | /** |
269 | * This function is used by a plugin to open the kate configuration dialog |
270 | * at one of its own config pages. |
271 | * \param configpageinterface the plugin config page interface of the plugin which requests the settings dialog |
272 | * \param id the positional id of the page within the configuration |
273 | */ |
274 | void showPluginConfigPage(Kate::PluginConfigPageInterface *configpageinterface,uint id); |
275 | |
276 | /** |
277 | * Get a plugin view with identifier \p name. |
278 | * \param name the plugin's name |
279 | * \return pointer to the plugin view if a plugin with \p name is loaded and has a view for this mainwindow, |
280 | * otherwise NULL |
281 | */ |
282 | PluginView *pluginView (const QString &name); |
283 | |
284 | private: |
285 | class PrivateMainWindow *d; |
286 | }; |
287 | } |
288 | |
289 | #endif |
290 | // kate: space-indent on; indent-width 2; replace-tabs on; |
291 | |
292 | |