← Back to branch summary

~ubuntu-branches/ubuntu/vivid/kate/vivid-proposed

« back to all changes in this revision

Viewing changes to ktexteditor/markinterface.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/markinterface.h
1
 
/* This file is part of the KDE project
2
 
   Copyright (C) 2001 Christoph Cullmann (cullmann@kde.org)
3
 
   Copyright (C) 2005 Dominik Haumann (dhdev@gmx.de) (documentation)
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 KDELIBS_KTEXTEDITOR_MARKINTERFACE_H
22
 
#define KDELIBS_KTEXTEDITOR_MARKINTERFACE_H
23
 
 
24
 
#include <ktexteditor/ktexteditor_export.h>
25
 
 
26
 
#include <QtCore/QHash>
27
 
#include <QtCore/QObject>
28
 
 
29
 
class QPixmap;
30
 
class QPoint;
31
 
class QMenu;
32
 
 
33
 
namespace KTextEditor
34
 
{
35
 
 
36
 
class Document;
37
 
 
38
 
/**
39
 
 * \brief Mark class containing line and mark types.
40
 
 *
41
 
 * \section mark_intro Introduction
42
 
 *
43
 
 * The class Mark represents a mark in a Document. It contains the \e line
44
 
 * and \e type. A line can have multiple marks, like a \e bookmark and a
45
 
 * \e breakpoint, i.e. the \e type contains all marks combined with a logical
46
 
 * \e OR (<tt>|</tt>). There are several predefined mark types, look into the
47
 
 * MarkInterface for further details.
48
 
 *
49
 
 * \see KTextEditor::MarkInterface, KTextEditor::Document
50
 
 */
51
 
class Mark
52
 
{
53
 
  public:
54
 
    /** The line that contains the mark. */
55
 
    int line;
56
 
 
57
 
    /** The mark types in the line, combined with logical OR. */
58
 
    uint type;
59
 
};
60
 
 
61
 
/**
62
 
 * \brief Mark extension interface for the Document.
63
 
 *
64
 
 * \ingroup kte_group_doc_extensions
65
 
 *
66
 
 * \section markext_intro Introduction
67
 
 *
68
 
 * The MarkInterface provides methods to enable and disable marks in a
69
 
 * Document, a marked line can be visualized for example with a shaded
70
 
 * background color and/or a pixmap in the iconborder of the Document's View.
71
 
 * There are a number of predefined mark types, specified in
72
 
 * reservedMarkersCount(). Additionally it is possible to add custom marks
73
 
 * and set custom pixmaps.
74
 
 *
75
 
 * \section markext_access Accessing the Interface
76
 
 *
77
 
 * The MarkInterface is supposed to be an extension interface for a Document,
78
 
 * i.e. the Document inherits the interface \e provided that the
79
 
 * KTextEditor library in use implements the interface. Use qobject_cast to access
80
 
 * the interface:
81
 
 * \code
82
 
 * // doc is of type KTextEditor::Document*
83
 
 * KTextEditor::MarkInterface *iface =
84
 
 *     qobject_cast<KTextEditor::MarkInterface*>( doc );
85
 
 *
86
 
 * if( iface ) {
87
 
 *     // the implementation supports the interface
88
 
 *     // do stuff
89
 
 * }
90
 
 * \endcode
91
 
 *
92
 
 * \section markext_handling Handling Marks
93
 
 *
94
 
 * Get all marks in the document by calling marks(). Use clearMarks() to
95
 
 * remove all marks in the entire document. A single mark can be retrieved
96
 
 * with mark(). To remove all marks from a line call clearMark(). To add
97
 
 * and remove marks from a given line use addMark() and removeMark(). It is
98
 
 * also possible to replace all marks with setMark(), i.e. setMark() is the
99
 
 * same as a call of clearMark() followed by addMark(). The signals
100
 
 * marksChanged() and markChanged() are emitted whenever a line's marks
101
 
 * changed.
102
 
 *
103
 
 * \attention A mark type is represented as an \e uint. An \e uint can have
104
 
 *     several mark types combined (see above: logical OR). That means for
105
 
 *     all functions/signals with an \e uint parameter, e.g. setMark(),
106
 
 *     removeMark(), etc, the \e uint may contain \e multiple marks, i.e.
107
 
 *     you can add and remove multiple marks \e simultaneously.
108
 
 *
109
 
 * \section markext_userdefined User Defined Marks
110
 
 *
111
 
 * All marks that should be editable by the user can be specified with a mark
112
 
 * mask via setEditableMarks(). To set a description and pixmap of a mark type
113
 
 * call setMarkDescription() and setMarkPixmap().
114
 
 *
115
 
 * \see KTextEditor::Document, KTextEditor::Mark
116
 
 * \author Christoph Cullmann \<cullmann@kde.org\>
117
 
 */
118
 
class KTEXTEDITOR_EXPORT MarkInterface
119
 
{
120
 
  public:
121
 
    MarkInterface ();
122
 
 
123
 
    /**
124
 
     * Virtual destructor.
125
 
     */
126
 
    virtual ~MarkInterface ();
127
 
 
128
 
  //
129
 
  // slots !!!
130
 
  //
131
 
  public:
132
 
    /**
133
 
     * Get all marks set on the \p line.
134
 
     * \param line requested line
135
 
     * \return a \e uint representing of the marks set in \p line concatenated
136
 
     *         by logical OR
137
 
     * \see addMark(), removeMark()
138
 
     */
139
 
    virtual uint mark (int line) = 0;
140
 
 
141
 
    /**
142
 
     * Set the \p line's mark types to \p markType.
143
 
     * If \p line already contains a mark of the given type it has no effect.
144
 
     * All other marks are deleted before the mark is set. You can achieve
145
 
     * the same by calling
146
 
     * \code
147
 
     * clearMark(line);
148
 
     * addMark(line, markType);
149
 
     * \endcode
150
 
     * \param line line to set the mark
151
 
     * \param markType mark type
152
 
     * \see clearMark(), addMark(), mark()
153
 
     */
154
 
    virtual void setMark (int line, uint markType) = 0;
155
 
 
156
 
    /**
157
 
     * Clear all marks set in the \p line.
158
 
     * \param line line to clear marks
159
 
     * \see clearMarks(), removeMark(), addMark()
160
 
     */
161
 
    virtual void clearMark (int line) = 0;
162
 
 
163
 
    /**
164
 
     * Add marks of type \p markType to \p line. Existing marks on this line
165
 
     * are preserved. If the mark \p markType already is set, nothing
166
 
     * happens.
167
 
     * \param line line to set the mark
168
 
     * \param markType mark type
169
 
     * \see removeMark(), setMark()
170
 
     */
171
 
    virtual void addMark (int line, uint markType) = 0;
172
 
 
173
 
    /**
174
 
     * Remove the mark mask of type \p markType from \p line.
175
 
     * \param line line to remove the mark
176
 
     * \param markType mark type to be removed
177
 
     * \see clearMark()
178
 
     */
179
 
    virtual void removeMark (int line, uint markType) = 0;
180
 
 
181
 
    /**
182
 
     * Get a hash holding all marks in the document.
183
 
     * The hash key for a mark is its line.
184
 
     * \return a hash holding all marks in the document
185
 
     */
186
 
    virtual const QHash<int, KTextEditor::Mark*> &marks () = 0;
187
 
 
188
 
    /**
189
 
     * Clear all marks in the entire document.
190
 
     * \see clearMark(), removeMark()
191
 
     */
192
 
    /// TODO: dominik: add argument unit mask = 0
193
 
    virtual void clearMarks () = 0;
194
 
 
195
 
    /**
196
 
     * Get the number of predefined mark types we have so far.
197
 
     * \note FIXME: If you change this you have to make sure katepart
198
 
     *              supports the new size!
199
 
     * \return number of reserved marker types
200
 
     */
201
 
    static int reservedMarkersCount() { return 7; }
202
 
 
203
 
    /**
204
 
     * Predefined mark types.
205
 
     *
206
 
     * To add a new standard mark type, edit this interface and document
207
 
     * the type.
208
 
     */
209
 
    enum MarkTypes
210
 
    {
211
 
      /** Bookmark */
212
 
      markType01= 0x1,
213
 
      /** Breakpoint active */
214
 
      markType02= 0x2,
215
 
      /** Breakpoint reached */
216
 
      markType03= 0x4,
217
 
      /** Breakpoint disabled */
218
 
      markType04= 0x8,
219
 
      /** Execution mark */
220
 
      markType05= 0x10,
221
 
      /** Warning */
222
 
      markType06= 0x20,
223
 
      /** Error */
224
 
      markType07= 0x40,
225
 
 
226
 
      markType08= 0x80,
227
 
      markType09= 0x100,
228
 
      markType10= 0x200,
229
 
      markType11= 0x400,
230
 
      markType12= 0x800,
231
 
      markType13= 0x1000,
232
 
      markType14= 0x2000,
233
 
      markType15= 0x4000,
234
 
      markType16= 0x8000,
235
 
      markType17= 0x10000,
236
 
      markType18= 0x20000,
237
 
      markType19= 0x40000,
238
 
      markType20= 0x80000,
239
 
      markType21= 0x100000,
240
 
      markType22= 0x200000,
241
 
      markType23= 0x400000,
242
 
      markType24= 0x800000,
243
 
      markType25= 0x1000000,
244
 
      markType26= 0x2000000,
245
 
      markType27= 0x4000000,
246
 
      markType28= 0x8000000,
247
 
      markType29= 0x10000000,
248
 
      markType30= 0x20000000,
249
 
      markType31= 0x40000000,
250
 
      markType32= 0x80000000,
251
 
      /* reserved marks */
252
 
      Bookmark = markType01,
253
 
      BreakpointActive = markType02,
254
 
      BreakpointReached = markType03,
255
 
      BreakpointDisabled = markType04,
256
 
      Execution = markType05,
257
 
      Warning = markType06,
258
 
      Error = markType07
259
 
    };
260
 
 
261
 
  //
262
 
  // signals !!!
263
 
  //
264
 
  public:
265
 
    /**
266
 
     * The \p document emits this signal whenever a mark mask changed.
267
 
     * \param document document which emitted this signal
268
 
     * \see markChanged()
269
 
     */
270
 
    virtual void marksChanged (KTextEditor::Document* document) = 0;
271
 
 
272
 
    /*
273
 
     * Methods to modify mark properties.
274
 
     */
275
 
  public:
276
 
    /**
277
 
     * Set the \p mark's pixmap to \p pixmap.
278
 
     * \param mark mark to which the pixmap will be attached
279
 
     * \param pixmap new pixmap
280
 
     * \see setMarkDescription()
281
 
     */
282
 
    virtual void setMarkPixmap( MarkTypes mark, const QPixmap &pixmap ) = 0;
283
 
 
284
 
    /**
285
 
     * Get the \p mark's pixmap.
286
 
     * \param mark mark type. If the pixmap does not exist the resulting is null
287
 
     *        (check with QPixmap::isNull()).
288
 
     * \see setMarkDescription()
289
 
     */
290
 
    virtual QPixmap markPixmap( MarkTypes mark ) const = 0;
291
 
 
292
 
    /**
293
 
     * Set the \p mark's description to \p text.
294
 
     * \param mark mark to set the description
295
 
     * \param text new descriptive text
296
 
     * \see markDescription(), setMarkPixmap()
297
 
     */
298
 
    virtual void setMarkDescription( MarkTypes mark, const QString &text ) = 0;
299
 
 
300
 
    /**
301
 
     * Get the \p mark's description to text.
302
 
     * \param mark mark to set the description
303
 
     * \return text of the given \p mark or QString(), if the entry does not
304
 
     *         exist
305
 
     * \see setMarkDescription(), setMarkPixmap()
306
 
     */
307
 
    virtual QString markDescription( MarkTypes mark ) const = 0;
308
 
 
309
 
    /**
310
 
     * Set the mark mask the user is allowed to toggle to \p markMask.
311
 
     * I.e. concatenate all editable marks with a logical OR. If the user should
312
 
     * be able to add a bookmark and set a breakpoint with the context menu in
313
 
     * the icon pane, you have to call
314
 
     * \code
315
 
     * // iface is of Type KTextEditor::MarkInterface*
316
 
     * // only make bookmark and breakpoint editable
317
 
     * iface->setEditableMarks( MarkInterface::Bookmark |
318
 
     *                          MarkInterface::BreakpointActive );
319
 
     *
320
 
     * // or preserve last settings, and add bookmark and breakpoint
321
 
     * iface->setEditableMarks( iface->editableMarks() |
322
 
     *                          MarkInterface::Bookmark |
323
 
     *                          MarkInterface::BreakpointActive );
324
 
     * \endcode
325
 
     * \param markMask bitmap pattern
326
 
     * \see editableMarks(), setMarkPixmap(), setMarkDescription()
327
 
     */
328
 
    virtual void setEditableMarks( uint markMask ) = 0;
329
 
 
330
 
    /**
331
 
     * Get, which marks can be toggled by the user.
332
 
     * The returned value is a mark mask containing all editable marks combined
333
 
     * with a logical OR.
334
 
     * \return mark mask containing all editable marks
335
 
     * \see setEditableMarks()
336
 
     */
337
 
    virtual uint editableMarks() const = 0;
338
 
 
339
 
    /**
340
 
     * Possible actions on a mark.
341
 
     * \see markChanged()
342
 
     */
343
 
    enum MarkChangeAction {
344
 
      MarkAdded=0,    /**< action: a mark was added.  */
345
 
      MarkRemoved=1   /**< action: a mark was removed. */
346
 
        };
347
 
 
348
 
  //
349
 
  // signals !!!
350
 
  //
351
 
  public:
352
 
    /**
353
 
     * The \p document emits this signal whenever the \p mark changes.
354
 
     * \param document the document which emitted the signal
355
 
     * \param mark changed mark
356
 
     * \param action action, either removed or added
357
 
     * \see marksChanged()
358
 
     */
359
 
    virtual void markChanged ( KTextEditor::Document* document, KTextEditor::Mark mark,
360
 
                               KTextEditor::MarkInterface::MarkChangeAction action) = 0;
361
 
 
362
 
    Q_SIGNALS:
363
 
      
364
 
    /**
365
 
     * The \p document emits this signal whenever the \p mark is hovered using the mouse,
366
 
     * and the receiver may show a tooltip.
367
 
     * \param document the document which emitted the signal
368
 
     * \param mark mark that was hovered
369
 
     * \param position mouse position during the hovering
370
 
     * \param handled set this to 'true' if this event was handled externally
371
 
     */
372
 
    void markToolTipRequested ( KTextEditor::Document* document, KTextEditor::Mark mark,
373
 
                               QPoint position, bool& handled );
374
 
    
375
 
    /**
376
 
     * The \p document emits this signal whenever the \p mark is right-clicked to show a context menu.
377
 
     * The receiver may show an own context menu instead of the kate internal one.
378
 
     * \param document the document which emitted the signal
379
 
     * \param mark mark that was right-clicked
380
 
     * \param pos position where the menu should be started
381
 
     * \param handled set this to 'true' if this event was handled externally, and kate should not create an own context menu.
382
 
     */
383
 
    void markContextMenuRequested( KTextEditor::Document* document, KTextEditor::Mark mark,
384
 
                               QPoint pos, bool& handled );
385
 
 
386
 
    
387
 
    /**
388
 
     * The \p document emits this signal whenever the \p mark is left-clicked.
389
 
     * \param document the document which emitted the signal
390
 
     * \param mark mark that was right-clicked
391
 
     * \param pos position where the menu should be started
392
 
     * \param handled set this to 'true' if this event was handled externally, and kate should not do own handling of the left click.
393
 
     */
394
 
    void markClicked( KTextEditor::Document* document, KTextEditor::Mark mark, bool& handled );
395
 
 
396
 
  private:
397
 
    class MarkInterfacePrivate* const d;
398
 
};
399
 
 
400
 
}
401
 
 
402
 
Q_DECLARE_INTERFACE(KTextEditor::MarkInterface, "org.kde.KTextEditor.MarkInterface")
403
 
 
404
 
#endif
405
 
 
406
 
// kate: space-indent on; indent-width 2; replace-tabs on;