« back to all changes in this revision
Viewing changes to part/kte5/messageinterface.h
- browse files at revision 36
- compare with another revision
- download diff
- download tarball
- view history from revision 36
- Committer: Package Import Robot
- Author(s): Michał Zając
- Date: 2013-06-28 18:00:49 UTC
- mfrom: (1.1.29)
- Revision ID: package-import@ubuntu.com-20130628180049-ul2hye7llxvgebpo
Tags: 4:4.10.90-0ubuntu1
New upstream bet release
- files added:
- examples/syntax/highlight.cc
- tests/data/indent/cppstyle/normal14
- tests/data/indent/cppstyle/normal15
- tests/data/indent/cppstyle/normal16
- files removed:
- part/kte5/messageinterface.cpp
- files modified:
- debian/changelog
added
removed
part/kte5/messageinterface.h
1
/* This file is part of the KDE project
2
*
3
* Copyright (C) 2012-2013 Dominik Haumann <dhaumann@kde.org>
4
*
5
* This library is free software; you can redistribute it and/or
6
* modify it under the terms of the GNU Library General Public
7
* License as published by the Free Software Foundation; either
8
* version 2 of the License, or (at your option) any later version.
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 KTEXTEDITOR_MESSAGEINTERFACE_H
22
#define KTEXTEDITOR_MESSAGEINTERFACE_H
23
24
#include <QtCore/QObject>
25
#include <QtCore/QList>
26
#include <QtGui/QAction>
27
28
#include "katepartprivate_export.h"
29
30
namespace KTextEditor {
31
32
class View;
33
class Document;
34
35
/**
36
* @brief This class holds a Message to display in View%s.
37
*
38
* @section message_intro Introduction
39
*
40
* The Message class holds the data used to display interactive message widgets
41
* in the editor. To post a message, use the MessageInterface.
42
*
43
* @section message_creation Message Creation and Deletion
44
*
45
* To create a new Message, use code like this:
46
* @code
47
* QPointer<Message> message = new Message(Message::Information, "My information text");
48
* message->setWordWrap(true);
49
* // ...
50
* @endcode
51
*
52
* Although discouraged in general, the text of the Message can be changed
53
* on the fly when it is already visible with setText().
54
*
55
* Once you posted the Message through MessageInterface::postMessage(), the
56
* lifetime depends on the user interaction. The Message gets automatically
57
* deleted either if the user clicks a closing action in the message, or for
58
* instance if the document is reloaded.
59
*
60
* If you posted a message but want to remove it yourself again, just delete
61
* the message. But beware of the following warning!
62
*
63
* @warning Always use QPointer\<Message\> to guard the message pointer from
64
* getting invalid, if you need to access the Message after you posted
65
* it.
66
*
67
* @section message_positioning Positioning
68
*
69
* By default, the Message appears right above of the View. However, if desired,
70
* the position can be changed through setPosition(). For instance, the
71
* search-and-replace code in Kate Part shows the number of performed replacements
72
* in a message floating in the view. For further information, have a look at
73
* the enum MessagePosition.
74
*
75
* @section message_hiding Autohiding Messages
76
*
77
* Message%s can be shown for only a short amount of time by using the autohide
78
* feature. With setAutoHide() a timeout in milliseconds can be set after which
79
* the Message is automatically hidden. Further, use setAutoHideMode() to either
80
* trigger the autohide timer as soon as the widget is shown (AutoHideMode::Immediate),
81
* or only after user interaction with the view (AutoHideMode::AfterUserInteraction).
82
*
83
* The default autohide mode is set to AutoHideMode::AfterUserInteraction.
84
* This way, it is unlikely the user misses a notification.
85
*
86
* @see MessageInterface
87
* @author Dominik Haumann \<dhaumann@kde.org\>
88
* @since KDE 4.10
89
*/
90
class KATEPART_TESTS_EXPORT Message : public QObject
91
{
92
Q_OBJECT
93
94
//
95
// public data types
96
//
97
public:
98
/**
99
* Message types used as visual indicator.
100
* The message types match exactly the behavior of KMessageWidget::MessageType.
101
* For simple notifications either use Positive or Information.
102
*/
103
enum MessageType {
104
Positive = 0, ///< positive information message
105
Information, ///< information message type
106
Warning, ///< warning message type
107
Error ///< error message type
108
};
109
110
/**
111
* Message position used to place the message either above or below of the
112
* KTextEditor::View.
113
*/
114
enum MessagePosition {
115
AboveView = 0, ///< show message above view
116
BelowView, ///< show message below view
117
TopInView, ///< show message as view overlay in the top right corner
118
BottomInView ///< show message as view overlay om the bottom right corner
119
};
120
121
/**
122
* The AutoHideMode determines when to trigger the autoHide timer.
123
* @see setAutoHide(), autoHide()
124
*/
125
enum AutoHideMode {
126
Immediate = 0, ///< auto-hide is triggered as soon as the message is shown
127
AfterUserInteraction ///< auto-hide is triggered only after the user interacted with the view
128
};
129
130
public:
131
/**
132
* Constructor for new messages.
133
* @param type the message type, e.g. MessageType::Information
134
* @param richtext text to be displayed
135
*/
136
Message(MessageType type, const QString& richtext);
137
138
/**
139
* Destructor.
140
*/
141
virtual ~Message();
142
143
/**
144
* Returns the text set in the constructor.
145
*/
146
QString text() const;
147
148
/**
149
* Returns the message type set in the constructor.
150
*/
151
MessageType messageType() const;
152
153
/**
154
* Adds an action to the message.
155
*
156
* By default (@p closeOnTrigger = true), the action closes the message
157
* displayed in all View%s. If @p closeOnTrigger is @e false, the message
158
* is stays open.
159
*
160
* The actions will be displayed in the order you added the actions.
161
*
162
* To connect to an action, use the following code:
163
* @code
164
* connect(action, SIGNAL(triggered()), receiver, SLOT(slotActionTriggered()));
165
* @endcode
166
*
167
* @param action action to be added
168
* @param closeOnTrigger when triggered, the message widget is closed
169
*
170
* @warning The added actions are deleted automatically.
171
* So do \em not delete the added actions yourself.
172
*/
173
void addAction(QAction* action, bool closeOnTrigger = true);
174
175
/**
176
* Accessor to all actions, mainly used in the internal implementation
177
* to add the actions into the gui.
178
*/
179
QList<QAction*> actions() const;
180
181
/**
182
* Set the auto hide timer to @p autoHideTimer milliseconds.
183
* If @p autoHideTimer < 0, auto hide is disabled.
184
* If @p autoHideTimer = 0, auto hide is enabled and set to a sane default
185
* value of several seconds.
186
*
187
* By default, auto hide is disabled.
188
*
189
* @see autoHide(), setAutoHideMode()
190
*/
191
void setAutoHide(int autoHideTimer = 0);
192
193
/**
194
* Returns the auto hide time in milliseconds.
195
* Please refer to setAutoHide() for an explanation of the return value.
196
*
197
* @see setAutoHide(), autoHideMode()
198
*/
199
int autoHide() const;
200
201
/**
202
* Sets the autoHide mode to @p mode.
203
* The default mode is set to AutoHideMode::AfterUserInteraction.
204
* @param mode autoHide mode
205
* @see autoHideMode(), setAutoHide()
206
*/
207
void setAutoHideMode(KTextEditor::Message::AutoHideMode mode);
208
209
/**
210
* Get the Message's autoHide mode.
211
* The default mode is set to AutoHideMode::AfterUserInteraction.
212
* @see setAutoHideMode(), autoHide()
213
*/
214
KTextEditor::Message::AutoHideMode autoHideMode() const;
215
216
/**
217
* Enabled word wrap according to @p wordWrap.
218
* By default, auto wrap is disabled.
219
*
220
* Word wrap is enabled automatically, if the Message's width is larger than
221
* the parent widget's width to avoid breaking the gui layout.
222
*
223
* @see wordWrap()
224
*/
225
void setWordWrap(bool wordWrap);
226
227
/**
228
* Check, whether word wrap is enabled or not.
229
*
230
* @see setWordWrap()
231
*/
232
bool wordWrap() const;
233
234
/**
235
* Set the priority of this message to @p priority.
236
* Messages with higher priority are shown first.
237
* The default priority is 0.
238
*
239
* @see priority()
240
*/
241
void setPriority(int priority);
242
243
/**
244
* Returns the priority of the message. Default is 0.
245
*
246
* @see setPriority()
247
*/
248
int priority() const;
249
250
/**
251
* Set the associated view of the message.
252
* If @p view is 0, the message is shown in all View%s of the Document.
253
* If @p view is given, i.e. non-zero, the message is shown only in this view.
254
* @param view the associated view the message should be displayed in
255
*/
256
void setView(KTextEditor::View* view);
257
258
/**
259
* This function returns the view you set by setView(). If setView() was
260
* not called, the return value is 0.
261
*/
262
KTextEditor::View* view() const;
263
264
/**
265
* Set the document pointer to @p document.
266
* This is called by the implementation, as soon as you post a message
267
* through MessageInterface::postMessage(), so that you do not have to
268
* call this yourself.
269
* @see MessageInterface, document()
270
*/
271
void setDocument(KTextEditor::Document* document);
272
273
/**
274
* Returns the document pointer this message was posted in.
275
* This pointer is 0 as long as the message was not posted.
276
*/
277
KTextEditor::Document* document() const;
278
279
/**
280
* Sets the @p position either to AboveView or BelowView.
281
* By default, the position is set to MessagePosition::AboveView.
282
* @see MessagePosition
283
*/
284
void setPosition(MessagePosition position);
285
286
/**
287
* Returns the desired message position of this message.
288
*/
289
MessagePosition position() const;
290
291
public Q_SLOTS:
292
/**
293
* Sets the notification contents to @p text.
294
* If the message was already sent through MessageInterface::postMessage(),
295
* the displayed text changes on the fly.
296
* @note Use this with care, since changing the text may resize the
297
* notification widget, which may result in a distracting user
298
* experience.
299
* @param richtext new notification text (rich text supported)
300
* @see textChanged()
301
*/
302
void setText(const QString& richtext);
303
304
Q_SIGNALS:
305
/**
306
* This signal is emitted before the message is deleted. Afterwards, this
307
* pointer is invalid.
308
*
309
* Use the function document() to access the associated Document.
310
*
311
* @param message closed/processed message
312
*/
313
void closed(KTextEditor::Message* message);
314
315
/**
316
* This signal is emitted whenever setText() is called.
317
* If the message was already sent through MessageInterface::postMessage(),
318
* the displayed text changes on the fly.
319
* @note Use this with care, since changing the text may resize the
320
* notification widget, which may result in a distracting user
321
* experience.
322
*
323
* @param text new notification text (rich text supported)
324
* @see setText()
325
*/
326
void textChanged(const QString& text);
327
328
private:
329
class MessagePrivate * const d;
330
};
331
332
/**
333
* \brief Message interface for posting interactive Message%s to a Document and its View%s.
334
*
335
* \ingroup kte_group_document_extension
336
*
337
* This interface allows to post Message%s to a Document. The Message then
338
* is shown either the specified View if Message::setView() was called, or
339
* in all View%s of the Document.
340
*
341
* \section message_interface Working with Messages
342
*
343
* To post a message, you first have to cast the Document to this interface,
344
* and then create a Message. Example:
345
* \code
346
* // doc is of type KTextEditor::Document*
347
* KTextEditor::MessageInterface *iface =
348
* qobject_cast<KTextEditor::MessageInterface*>( doc );
349
*
350
* if( !iface ) {
351
* // the implementation does not support the interface
352
* return;
353
* }
354
*
355
* // always use a QPointer go guard your Message, if you keep a pointer
356
* // after calling postMessage()
357
* QPointer<Message> message = new Message(Message::Information, "text");
358
* message->setWordWrap(true);
359
* message->addAction(...); // add your actions...
360
* iface->postMessage(message);
361
*
362
* // The Message is deleted automatically if the Message gets closed,
363
* // meaning that you usually can forget the pointer.
364
* // If you really need to delete a message before the user processed it,
365
* guard it with a QPointer!
366
* \endcode
367
*
368
* @see Message
369
* @author Dominik Haumann \<dhaumann@kde.org\>
370
* @since KDE 4.10
371
*/
372
class MessageInterface
373
{
374
public:
375
/**
376
* Default constructor, for internal use.
377
*/
378
MessageInterface();
379
/**
380
* Destructor, for internal use.
381
*/
382
virtual ~MessageInterface();
383
384
/**
385
* Post @p message to the Document and its View%s.
386
* If multiple Message%s are posted, the one with the highest priority
387
* is shown first.
388
*
389
* Usually, you can simply forget the pointer, as the Message is deleted
390
* automatically, once it is processed or the document gets closed.
391
*
392
* If the Document does not have a View yet, the Message is queued and
393
* shown, once a View for the Document is created.
394
*
395
* @param message the message to show
396
* @return @e true, if @p message was posted. @e false, if message == 0.
397
*/
398
virtual bool postMessage(Message* message) = 0;
399
400
private:
401
class MessageInterfacePrivate * const d;
402
};
403
404
}
405
406
Q_DECLARE_INTERFACE(KTextEditor::MessageInterface, "org.kde.KTextEditor.MessageInterface")
407
408
#endif
409
410
// kate: space-indent on; indent-width 2; replace-tabs on;
Loggerhead is a web-based interface for Breezy
Version: 2.0.1