1/*
2 SPDX-FileCopyrightText: 2001 Christoph Cullmann <cullmann@kde.org>
3
4 Documentation:
5 SPDX-FileCopyrightText: 2005 Dominik Haumann <dhdev@gmx.de>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#ifndef KTEXTEDITOR_VIEW_H
11#define KTEXTEDITOR_VIEW_H
12
13#include <ktexteditor_export.h>
14
15// gui merging
16#include <KSyntaxHighlighting/Theme>
17#include <KXMLGUIClient>
18#include <ktexteditor/codecompletionmodel.h>
19
20// widget
21#include <QSet>
22#include <QWidget>
23
24class QMenu;
25class QScrollBar;
26class KConfigGroup;
27
28namespace KSyntaxHighlighting
29{
30class Theme;
31}
32
33namespace KTextEditor
34{
35class Document;
36class MainWindow;
37class ViewPrivate;
38class Attribute;
39class AttributeBlock;
40class Range;
41class Cursor;
42class AnnotationModel;
43class AbstractAnnotationItemDelegate;
44class InlineNoteProvider;
45class TextHintProvider;
46class CodeCompletionModel;
47
48/**
49 * \class View view.h <KTextEditor/View>
50 *
51 * \brief A text widget with KXMLGUIClient that represents a Document.
52 *
53 * Topics:
54 * - \ref view_intro
55 * - \ref view_hook_into_gui
56 * - \ref view_selection
57 * - \ref view_cursors
58 * - \ref view_mouse_tracking
59 * - \ref view_modes
60 * - \ref view_config
61 * - \ref view_annoview
62 * - \ref view_inlinenote
63 * - \ref view_texthint
64 * - \ref view_compiface
65 *
66 * \section view_intro Introduction
67 *
68 * The View class represents a single view of a KTextEditor::Document,
69 * get the document on which the view operates with document().
70 * A view provides both the graphical representation of the text and the
71 * KXMLGUIClient for the actions. The view itself does not provide
72 * text manipulation, use the methods from the Document instead. The only
73 * method to insert text is insertText(), which inserts the given text
74 * at the current cursor position and emits the signal textInserted().
75 *
76 * Usually a view is created by using Document::createView().
77 * Furthermore a view can have a context menu. Set it with setContextMenu()
78 * and get it with contextMenu().
79 *
80 * \section view_hook_into_gui Merging the View's GUI
81 *
82 * A View is derived from the class KXMLGUIClient, so its GUI elements (like
83 * menu entries and toolbar items) can be merged into the application's GUI
84 * (or into a KXMLGUIFactory) by calling
85 * \code
86 * // view is of type KTextEditor::View*
87 * mainWindow()->guiFactory()->addClient( view );
88 * \endcode
89 * You can add only one view as client, so if you have several views, you first
90 * have to remove the current view, and then add the new one, like this
91 * \code
92 * mainWindow()->guiFactory()->removeClient( currentView );
93 * mainWindow()->guiFactory()->addClient( newView );
94 * \endcode
95 *
96 * \section view_selection Text Selection
97 *
98 * As the view is a graphical text editor it provides \e normal and \e block
99 * text selection. You can check with selection() whether a selection exists.
100 * removeSelection() will remove the selection without removing the text,
101 * whereas removeSelectionText() also removes both, the selection and the
102 * selected text. Use selectionText() to get the selected text and
103 * setSelection() to specify the selected text range. The signal
104 * selectionChanged() is emitted whenever the selection changed.
105 *
106 * \section view_cursors Cursor Positions
107 *
108 * A view has one Cursor which represents a line/column tuple. Two different
109 * kinds of cursor positions are supported: first is the \e real cursor
110 * position where a \e tab character only counts one character. Second is the
111 * \e virtual cursor position, where a \e tab character counts as many
112 * spaces as defined. Get the real position with cursorPosition() and the
113 * virtual position with cursorPositionVirtual(). Set the real cursor
114 * position with setCursorPosition(). The signal cursorPositionChanged() is
115 * emitted whenever the cursor position changed.
116 *
117 * Screen coordinates of the current text cursor position in pixels are obtained
118 * through cursorPositionCoordinates(). Further conversion of screen pixel
119 * coordinates and text cursor positions are provided by cursorToCoordinate()
120 * and coordinatesToCursor().
121 *
122 * \section view_mouse_tracking Mouse Tracking
123 *
124 * It is possible to get notified via the signal mousePositionChanged() for
125 * mouse move events, if mouseTrackingEnabled() returns \e true. Mouse tracking
126 * can be turned on/off by calling setMouseTrackingEnabled(). If an editor
127 * implementation does not support mouse tracking, mouseTrackingEnabled() will
128 * always return \e false.
129 *
130 * \section view_modes Input/View Modes
131 *
132 * A view supports several input modes. Common input modes are
133 * \e NormalInputMode and \e ViInputMode. Which input modes the editor supports depends on the
134 * implementation. The getter viewInputMode() returns enum \InputMode representing the current mode.
135 *
136 * Input modes can have their own view modes. In case of default \e NormalInputMode those are
137 * \e NormalModeInsert and \e NormalModeOverwrite. You can use viewMode() getter to obtain those.
138 *
139 * For viewMode() and viewInputMode() there are also variants with \e Human suffix, which
140 * returns the human readable representation (i18n) usable for displaying in user interface.
141 *
142 * Whenever the input/view mode changes the signals
143 * viewInputModeChanged()/viewModeChanged() are emitted.
144 *
145 * \section view_config View Config
146 * Config provides methods to access and modify the low level config information for a given
147 * View
148 * KTextEditor::View has support for the following keys:
149 * - line-numbers [bool], show/hide line numbers
150 * - icon-bar [bool], show/hide icon bar
151 * - folding-bar [bool], show/hide the folding bar
152 * - folding-preview [bool], enable/disable folding preview when mouse hovers
153 * on folded region
154 * - dynamic-word-wrap [bool], enable/disable dynamic word wrap
155 * - background-color [QColor], read/set the default background color
156 * - selection-color [QColor], read/set the default color for selections
157 * - search-highlight-color [QColor], read/set the background color for search
158 * - replace-highlight-color [QColor], read/set the background color for replaces
159 * - default-mark-type [uint], read/set the default mark type
160 * - allow-mark-menu [bool], enable/disable the menu shown when right clicking
161 * on the left gutter. When disabled, click on the gutter will always set
162 * or clear the mark of default type.
163 * - icon-border-color [QColor] read/set the icon border color (on the left,
164 * with the line numbers)
165 * - folding-marker-color [QColor] read/set folding marker colors (in the icon border)
166 * - line-number-color [QColor] read/set line number colors (in the icon border)
167 * - current-line-number-color [QColor] read/set current line number color (in the icon border)
168 * - modification-markers [bool] read/set whether the modification markers are shown
169 * - word-count [bool] enable/disable the counting of words and characters in the statusbar
170 * - line-count [bool] show/hide the total number of lines in the status bar (@since 5.66)
171 * - scrollbar-minimap [bool] enable/disable scrollbar minimap
172 * - scrollbar-preview [bool] enable/disable scrollbar text preview on hover
173 * - font [QFont] change the font
174 * - theme [QString] change the theme
175 * - word-completion-minimal-word-length [int] minimal word length to trigger word completion
176 * - enter-to-insert-completion [bool] enable/disable whether pressing enter inserts completion
177 *
178 * You can retrieve the value of a config key using configValue() and set the value
179 * for a config key using setConfigValue().
180 *
181 * \section view_annoview Annotation Interface
182 *
183 * The Annotation Interface allows to do these things:
184 * - (1) show/hide the annotation border along with the possibility to add actions
185 * into its context menu.
186 * - (2) set a separate AnnotationModel for the View: Note that this interface
187 * inherits the AnnotationInterface.
188 * - (3) set a custom AbstractAnnotationItemDelegate for the View.
189 *
190 * For a more detailed explanation about whether you want to set a custom
191 * delegate for rendering the annotations, read the detailed documentation about the
192 * AbstractAnnotationItemDelegate.
193 *
194 * \section view_inlinenote Inline Notes
195 *
196 * The inline notes interface provides a way to render arbitrary things in
197 * the text. The text layout of the line is adapted to create space for the
198 * note. Possible applications include showing a name of a function parameter
199 * in a function call or rendering a square with a color preview next to CSS
200 * color property.
201 *
202 * \image html inlinenote.png "Inline note showing a CSS color preview"
203 *
204 * To register as inline note provider, call registerInlineNoteProvider() with
205 * an instance that inherits InlineNoteProvider. Finally, make sure you remove
206 * your inline note provider by calling unregisterInlineNoteProvider().
207 *
208 * \section view_texthint Introduction
209 *
210 * The text hint interface provides a way to show tool tips for text located
211 * under the mouse. Possible applications include showing a value of a variable
212 * when debugging an application, or showing a complete path of an include
213 * directive.
214 *
215 * \image html texthint.png "Text hint showing the contents of a variable"
216 *
217 * To register as text hint provider, call registerTextHintProvider() with an
218 * instance that inherits TextHintProvider. Finally, make sure you remove your
219 * text hint provider by calling unregisterTextHintProvider().
220 *
221 * Text hints are shown after the user hovers with the mouse for a delay of
222 * textHintDelay() milliseconds over the same word. To change the delay, call
223 * setTextHintDelay().
224 *
225 * \section view_compiface Completion Interface
226 *
227 * The Completion Interface is designed to provide code completion
228 * functionality for a KTextEditor::View. This interface provides the basic
229 * mechanisms to display a list of completions, update this list according
230 * to user input, and allow the user to select a completion.
231 *
232 * Essentially, this provides an item view for the available completions. In
233 * order to use this interface, you will need to implement a
234 * CodeCompletionModel that generates the relevant completions given the
235 * current input.
236 *
237 * More information about interfaces for the view can be found in
238 * \ref kte_group_view_extensions.
239 *
240 * \see KTextEditor::Document, KXMLGUIClient
241 * \author Christoph Cullmann \<cullmann@kde.org\>
242 */
243class KTEXTEDITOR_EXPORT View : public QWidget, public KXMLGUIClient
244{
245 Q_OBJECT
246
247protected:
248 /**
249 * Constructor.
250 *
251 * Create a view attached to the widget \p parent.
252 *
253 * Pass it the internal implementation to store a d-pointer.
254 *
255 * \param impl d-pointer to use
256 * \param parent parent widget
257 * \see Document::createView()
258 */
259 View(ViewPrivate *impl, QWidget *parent);
260
261public:
262 /**
263 * Virtual destructor.
264 */
265 ~View() override;
266
267 /*
268 * Accessor for the document
269 */
270public:
271 /**
272 * Get the view's \e document, that means the view is a view of the
273 * returned document.
274 * \return the view's document
275 */
276 virtual Document *document() const = 0;
277
278 /*
279 * General information about this view
280 */
281public:
282 /**
283 * Possible input modes.
284 * These correspond to various modes the text editor might be in.
285 */
286 enum InputMode {
287 NormalInputMode = 0, /**< Normal Mode. */
288 ViInputMode = 1 /**< Vi mode. The view will behave like the editor vi(m) */
289 };
290
291 /**
292 * Possible view modes
293 * These correspond to various modes the text editor might be in.
294 */
295 enum ViewMode {
296 NormalModeInsert = 0, /**< Insert mode. Characters will be added. */
297 NormalModeOverwrite = 1, /**< Overwrite mode. Characters will be replaced. */
298
299 ViModeNormal = 10,
300 ViModeInsert = 11,
301 ViModeVisual = 12,
302 ViModeVisualLine = 13,
303 ViModeVisualBlock = 14,
304 ViModeReplace = 15
305 };
306
307 /**
308 * Possible line types
309 * \since 5.33
310 */
311 enum LineType {
312 RealLine = 0, /**< Real line */
313 VisibleLine = 1 /**< Visible line. Line that is not folded. */
314 };
315 /**
316 * Get the current view mode/state.
317 * This can be used to detect the view's current mode. For
318 * example \NormalInputMode, \ViInputMode or whatever other input modes are
319 * supported. \see viewModeHuman() for translated version.
320 * \return current view mode/state
321 * \see viewModeChanged()
322 */
323 virtual ViewMode viewMode() const = 0;
324
325 /**
326 * Get the current view mode state.
327 * This can be used to visually indicate the view's current mode, for
328 * example \e INSERT mode, \e OVERWRITE mode or \e COMMAND mode - or
329 * whatever other edit modes are supported. The string should be
330 * translated (i18n), as this is a user aimed representation of the view
331 * state, which should be shown in the GUI, for example in the status bar.
332 * This string may be rich-text.
333 * \return Human-readable version of the view mode state
334 * \see viewModeChanged()
335 */
336 virtual QString viewModeHuman() const = 0;
337
338 /**
339 * Set the view's new input mode.
340 * \param inputMode new InputMode value
341 * \see viewInputMode()
342 * @since 5.54
343 */
344 virtual void setViewInputMode(InputMode inputMode) = 0;
345
346 /**
347 * Get the view's current input mode.
348 * The current mode can be \NormalInputMode and \ViInputMode.
349 * For human translated version \see viewInputModeHuman.
350 *
351 * \return the current input mode of this view
352 * \see viewInputModeChanged()
353 */
354 virtual InputMode viewInputMode() const = 0;
355
356 /**
357 * Get the view's current input mode in human readable form.
358 * The string should be translated (i18n). For id like version \see viewInputMode
359 *
360 * \return the current input mode of this view in human readable form
361 */
362 virtual QString viewInputModeHuman() const = 0;
363
364 /**
365 * Get the view's main window, if any
366 * \return the view's main window, will always return at least some non-nullptr dummy interface
367 */
368 virtual KTextEditor::MainWindow *mainWindow() const = 0;
369
370 /*
371 * SIGNALS
372 * following signals should be emitted by the editor view
373 */
374Q_SIGNALS:
375 /**
376 * This signal is emitted whenever the \p view gets the focus.
377 * \param view view which gets focus
378 * \see focusOut()
379 */
380 void focusIn(KTextEditor::View *view);
381
382 /**
383 * This signal is emitted whenever the \p view loses the focus.
384 * \param view view which lost focus
385 * \see focusIn()
386 */
387 void focusOut(KTextEditor::View *view);
388
389 /**
390 * This signal is emitted whenever the view mode of \p view changes.
391 * \param view the view which changed its mode
392 * \param mode new view mode
393 * \see viewMode()
394 */
395 void viewModeChanged(KTextEditor::View *view, KTextEditor::View::ViewMode mode);
396
397 /**
398 * This signal is emitted whenever the \p view's input \p mode changes.
399 * \param view view which changed its input mode
400 * \param mode new input mode
401 * \see viewInputMode()
402 */
403 void viewInputModeChanged(KTextEditor::View *view, KTextEditor::View::InputMode mode);
404
405 /**
406 * This signal is emitted from \p view whenever the users inserts \p text
407 * at \p position, that means the user typed/pasted text.
408 * \param view view in which the text was inserted
409 * \param position position where the text was inserted
410 * \param text the text the user has typed into the editor
411 * \see insertText()
412 */
413 void textInserted(KTextEditor::View *view, KTextEditor::Cursor position, const QString &text);
414
415 /*
416 * Context menu handling
417 */
418public:
419 /**
420 * Set a context menu for this view to \p menu.
421 *
422 * \note any previously assigned menu is not deleted. If you are finished
423 * with the previous menu, you may delete it.
424 *
425 * \warning Use this with care! Plugin xml gui clients are not merged
426 * into this menu!
427 * \warning !!!!!! DON'T USE THIS FUNCTION, UNLESS YOU ARE SURE YOU DON'T WANT PLUGINS TO WORK !!!!!!
428 *
429 * \param menu new context menu object for this view
430 * \see contextMenu()
431 */
432 virtual void setContextMenu(QMenu *menu) = 0;
433
434 /**
435 * Get the context menu for this view. The return value can be NULL
436 * if no context menu object was set and kxmlgui is not initialized yet.
437 * If there is no user set menu, the kxmlgui menu is returned. Do not delete this menu, if
438 * if it is the xmlgui menu.
439 * \return context menu object
440 * \see setContextMenu()
441 */
442 virtual QMenu *contextMenu() const = 0;
443
444 /**
445 * Populate \a menu with default text editor actions. If \a menu is
446 * null, a menu will be created with the view as its parent.
447 *
448 * \note to use this menu, you will next need to call setContextMenu(),
449 * as this does not assign the new context menu.
450 *
451 * \warning This contains only basic options from the editor component
452 * (katepart). Plugins are \p not merged/integrated into it!
453 * If you want to be a better citizen and take full advantage
454 * of KTextEditor plugins do something like:
455 * \code
456 * KXMLGUIClient* client = view;
457 * // search parent XmlGuiClient
458 * while (client->parentClient()) {
459 * client = client->parentClient();
460 * }
461 *
462 * if (client->factory()) {
463 * const QList<QWidget*> menuContainers = client->factory()->containers("menu");
464 * for (QWidget *w : menuContainers) {
465 * if (w->objectName() == "ktexteditor_popup") {
466 * // do something with the menu (ie adding an onshow handler)
467 * break;
468 * }
469 * }
470 * }
471 * \endcode
472 * \warning or simply use the aboutToShow, aboutToHide signals !!!!!
473 *
474 * \param menu the menu to be populated, or null to create a new menu.
475 * \return the menu, whether created or passed initially
476 */
477 virtual QMenu *defaultContextMenu(QMenu *menu = nullptr) const = 0;
478
479Q_SIGNALS:
480 /**
481 * Signal which is emitted immediately prior to showing the current
482 * context \a menu.
483 */
484 void contextMenuAboutToShow(KTextEditor::View *view, QMenu *menu);
485
486 /*
487 * Cursor handling
488 */
489public:
490 /**
491 * Set the view's new cursor to \p position. A \e TAB character
492 * is handled as only on character.
493 * \param position new cursor position
494 * \return \e true on success, otherwise \e false
495 * \see cursorPosition()
496 */
497 virtual bool setCursorPosition(Cursor position) = 0;
498
499 /**
500 * Set the view's new cursors to \p positions. A \e TAB character
501 * is handled as only on character.
502 *
503 * This allows to create multiple cursors in this view.
504 *
505 * The first passed position will be used for the primary cursor
506 * just like if you would call \ref setCursorPosition.
507 *
508 * \param positions new cursor positions
509 * \see cursorPositions()
510 *
511 * @since 5.95
512 */
513 void setCursorPositions(const QList<KTextEditor::Cursor> &positions);
514
515 /**
516 * Get the view's current cursor position. A \e TAB character is
517 * handled as only one character.
518 * \return current cursor position
519 * \see setCursorPosition()
520 */
521 virtual Cursor cursorPosition() const = 0;
522
523 /**
524 * Get the view's current cursor positions. A \e TAB character is
525 * handled as only one character.
526 *
527 * The returned vector contains the primary cursor as first element.
528 *
529 * @since 5.95
530 *
531 * \return all currently existing cursors
532 */
533 QList<KTextEditor::Cursor> cursorPositions() const;
534
535 /**
536 * Get the current \e virtual cursor position, \e virtual means the
537 * tabulator character (TAB) counts \e multiple characters, as configured
538 * by the user (e.g. one TAB is 8 spaces). The virtual cursor
539 * position provides access to the user visible values of the current
540 * cursor position.
541 *
542 * \return virtual cursor position
543 * \see cursorPosition()
544 */
545 virtual Cursor cursorPositionVirtual() const = 0;
546
547 /**
548 * Get the screen coordinates (x, y) of the supplied \a cursor relative
549 * to the view widget in pixels. Thus, (0, 0) represents the top left hand
550 * of the view widget.
551 *
552 * To map pixel coordinates to a Cursor position (the reverse transformation)
553 * use coordinatesToCursor().
554 *
555 * \param cursor cursor to determine coordinate for.
556 * \return cursor screen coordinates relative to the view widget
557 *
558 * \see cursorPositionCoordinates(), coordinatesToCursor()
559 */
560 virtual QPoint cursorToCoordinate(KTextEditor::Cursor cursor) const = 0;
561
562 /**
563 * Get the screen coordinates (x, y) of the cursor position in pixels.
564 * The returned coordinates are relative to the View such that (0, 0)
565 * represents tht top-left corner of the View.
566 *
567 * If global screen coordinates are required, e.g. for showing a QToolTip,
568 * convert the view coordinates to global screen coordinates as follows:
569 * \code
570 * QPoint viewCoordinates = view->cursorPositionCoordinates();
571 * QPoint globalCoorinates = view->mapToGlobal(viewCoordinates);
572 * \endcode
573 * \return cursor screen coordinates
574 * \see cursorToCoordinate(), coordinatesToCursor()
575 */
576 virtual QPoint cursorPositionCoordinates() const = 0;
577
578 /**
579 * Get the text-cursor in the document from the screen coordinates,
580 * relative to the view widget.
581 *
582 * To map a cursor to pixel coordinates (the reverse transformation)
583 * use cursorToCoordinate().
584 *
585 * \param coord coordinates relative to the view widget
586 * \return cursor in the View, that points onto the character under
587 * the given coordinate. May be KTextEditor::Cursor::invalid().
588 */
589 virtual KTextEditor::Cursor coordinatesToCursor(const QPoint &coord) const = 0;
590
591 /*
592 * SIGNALS
593 * following signals should be emitted by the editor view
594 * if the cursor position changes
595 */
596Q_SIGNALS:
597 /**
598 * This signal is emitted whenever the \p view's cursor position changed.
599 * \param view view which emitted the signal
600 * \param newPosition new position of the cursor (Kate will pass the real
601 * cursor position, not the virtual)
602 * \see cursorPosition(), cursorPositionVirtual()
603 */
604 void cursorPositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPosition);
605
606 /**
607 * This signal should be emitted whenever the \p view is scrolled vertically.
608 * \param view view which emitted the signal
609 * \param newPos the new scroll position
610 */
611 void verticalScrollPositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPos);
612
613 /**
614 * This signal should be emitted whenever the \p view is scrolled horizontally.
615 * \param view view which emitted the signal
616 */
617 void horizontalScrollPositionChanged(KTextEditor::View *view);
618 /*
619 * Mouse position
620 */
621public:
622 /**
623 * Check, whether mouse tracking is enabled.
624 *
625 * Mouse tracking is required to have the signal mousePositionChanged()
626 * emitted.
627 * \return \e true, if mouse tracking is enabled, otherwise \e false
628 * \see setMouseTrackingEnabled(), mousePositionChanged()
629 */
630 virtual bool mouseTrackingEnabled() const = 0;
631
632 /**
633 * Try to enable or disable mouse tracking according to \p enable.
634 * The return value contains the state of mouse tracking \e after the
635 * request. Mouse tracking is required to have the mousePositionChanged()
636 * signal emitted.
637 *
638 * \note Implementation Notes: An implementation is not forced to support
639 * this, and should always return \e false if it does not have
640 * support.
641 *
642 * \param enable if \e true, try to enable mouse tracking, otherwise disable
643 * it.
644 * \return the current state of mouse tracking
645 * \see mouseTrackingEnabled(), mousePositionChanged()
646 */
647 virtual bool setMouseTrackingEnabled(bool enable) = 0;
648
649Q_SIGNALS:
650 /**
651 * This signal is emitted whenever the position of the mouse changes over
652 * this \a view. If the mouse moves off the view, an invalid cursor position
653 * should be emitted, i.e. Cursor::invalid().
654 * \note If mouseTrackingEnabled() returns \e false, this signal is never
655 * emitted.
656 * \param view view which emitted the signal
657 * \param newPosition new position of the mouse or Cursor::invalid(), if the
658 * mouse moved out of the \p view.
659 * \see mouseTrackingEnabled()
660 */
661 void mousePositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPosition);
662
663 /*
664 * Selection methods.
665 * This deals with text selection and copy&paste
666 */
667public:
668 /**
669 * Set the view's selection to the range \p selection.
670 * The old selection will be discarded.
671 * \param range the range of the new selection
672 * \return \e true on success, otherwise \e false (e.g. when the cursor
673 * range is invalid)
674 * \see selectionRange(), selection()
675 */
676 virtual bool setSelection(Range range) = 0;
677
678 /**
679 * Set the view's selection to the range \p selection.
680 * The old selection will be discarded.
681 * \param ranges the ranges of the new selections
682 * \see selectionRanges(), selection()
683 *
684 * @since 5.95
685 */
686 void setSelections(const QList<KTextEditor::Range> &ranges);
687
688 /**
689 * Query the view whether it has selected text, i.e. whether a selection
690 * exists.
691 * \return \e true if a text selection exists, otherwise \e false
692 * \see setSelection(), selectionRange()
693 */
694 virtual bool selection() const = 0;
695
696 /**
697 * Get the range occupied by the current selection.
698 * \return selection range, valid only if a selection currently exists.
699 * \see setSelection()
700 */
701 virtual Range selectionRange() const = 0;
702
703 /**
704 * Get the ranges occupied by the current selections.
705 * \return selection ranges, valid only if a selection currently exists.
706 * \see setSelections()
707 *
708 * @since 5.95
709 */
710 QList<KTextEditor::Range> selectionRanges() const;
711
712 /**
713 * Get the view's selected text.
714 * \return the selected text
715 * \see setSelection()
716 */
717 virtual QString selectionText() const = 0;
718
719 /**
720 * Remove the view's current selection, \e without deleting the selected
721 * text.
722 * \return \e true on success, otherwise \e false
723 * \see removeSelectionText()
724 */
725 virtual bool removeSelection() = 0;
726
727 /**
728 * Remove the view's current selection \e including the selected text.
729 * \return \e true on success, otherwise \e false
730 * \see removeSelection()
731 */
732 virtual bool removeSelectionText() = 0;
733
734 /*
735 * Blockselection stuff
736 */
737public:
738 /**
739 * Set block selection mode to state \p on.
740 * \param on if \e true, block selection mode is turned on, otherwise off
741 * \return \e true on success, otherwise \e false
742 * \see blockSelection()
743 */
744 virtual bool setBlockSelection(bool on) = 0;
745
746 /**
747 * Get the status of the selection mode. \e true indicates that block
748 * selection mode is on. If this is \e true, selections applied via the
749 * SelectionInterface are handled as block selections and the Copy&Paste
750 * functions work on rectangular blocks of text rather than normal.
751 * \return \e true, if block selection mode is enabled, otherwise \e false
752 * \see setBlockSelection()
753 */
754 virtual bool blockSelection() const = 0;
755
756 /*
757 * SIGNALS
758 * following signals should be emitted by the editor view for selection
759 * handling.
760 */
761Q_SIGNALS:
762 /**
763 * This signal is emitted whenever the \p view's selection changes.
764 * \note If the mode switches from block selection to normal selection
765 * or vice versa this signal should also be emitted.
766 * \param view view in which the selection changed
767 * \see selection(), selectionRange(), selectionText()
768 */
769 void selectionChanged(KTextEditor::View *view);
770
771public:
772 /**
773 * This is a convenience function which inserts \p text at the view's
774 * current cursor position. You do not necessarily need to reimplement
775 * it, except you want to do some special things.
776 * \param text Text to be inserted
777 * \return \e true on success of insertion, otherwise \e false
778 * \see textInserted()
779 */
780 virtual bool insertText(const QString &text);
781
782 /**
783 * Insert a template into the document. The template can have editable fields
784 * which can be filled by the user. You can create editable fields
785 * with ${fieldname}; multiple fields with the same name will have their
786 * contents synchronized automatically, and only the first one is editable
787 * in this case.
788 * Fields can have a default value specified by writing ${fieldname=default}.
789 * Note that `default' is a JavaScript expression and strings need to be quoted.
790 * You can also provide a piece of JavaScript for more complex logic.
791 * To create a field which provides text based on a JS function call and the values
792 * of the other, editable fields, use the ${func()} syntax. func() must be a callable
793 * object defined in @p script. You can pass arguments to the function by just
794 * writing any constant expression or a field name.
795 * \param insertPosition where to insert the template
796 * \param templateString template to insert using the above syntax
797 * \param script script with functions which can be used in @p templateScript
798 * \return true on success, false if insertion failed (e.g. read-only mode)
799 */
800 bool insertTemplate(KTextEditor::Cursor insertPosition, const QString &templateString, const QString &script = QString());
801
802 /**
803 * Scroll view to cursor.
804 *
805 * \param cursor the cursor position to scroll to.
806 *
807 * \since 5.33
808 */
809 void setScrollPosition(KTextEditor::Cursor cursor);
810
811 /**
812 * Horizontally scroll view to position.
813 *
814 * \param x the pixel position to scroll to.
815 *
816 * \since 5.33
817 */
818 void setHorizontalScrollPosition(int x);
819
820 /**
821 * Get the cursor corresponding to the maximum position
822 * the view can vertically scroll to.
823 *
824 * \return cursor position of the maximum vertical scroll position.
825 *
826 * \since 5.33
827 */
828 KTextEditor::Cursor maxScrollPosition() const;
829
830 /**
831 * Get the first displayed line in the view.
832 *
833 * \note If code is folded, many hundred lines can be
834 * between firstDisplayedLine() and lastDisplayedLine().
835 *
836 * \param lineType if RealLine (the default), it returns the real line number
837 * accounting for folded regions. In that case it walks over all folded
838 * regions
839 * O(n) for n == number of folded ranges
840 * \return the first displayed line
841 *
842 * \see lastDisplayedLine()
843 * \since 5.33
844 */
845 int firstDisplayedLine(LineType lineType = RealLine) const;
846
847 /**
848 * Get the last displayed line in the view.
849 *
850 * \note If code is folded, many hundred lines can be
851 * between firstDisplayedLine() and lastDisplayedLine().
852 *
853 * \param lineType if RealLine (the default), it returns the real line number
854 * accounting for folded regions. In that case it walks over all folded
855 * regions
856 * O(n) for n == number of folded ranges
857 * \return the last displayed line
858 *
859 * \see firstDisplayedLine()
860 * \since 5.33
861 */
862 int lastDisplayedLine(LineType lineType = RealLine) const;
863
864 /**
865 * Get the view's text area rectangle excluding border, scrollbars, etc.
866 *
867 * \return the view's text area rectangle
868 *
869 * \since 5.33
870 */
871 QRect textAreaRect() const;
872
873 /**
874 * \return The vertical scrollbar of this view
875 * \since 6.0
876 */
877 virtual QScrollBar *verticalScrollBar() const = 0;
878
879 /**
880 * \return The horizontal scrollbar of this view
881 * \since 6.0
882 */
883 virtual QScrollBar *horizontalScrollBar() const = 0;
884
885public:
886 /**
887 * Print the document. This should result in showing the print dialog.
888 *
889 * @returns true if document was printed
890 */
891 virtual bool print() = 0;
892
893 /**
894 * Shows the print preview dialog/
895 */
896 virtual void printPreview() = 0;
897
898 /**
899 * Is the status bar enabled?
900 *
901 * @return status bar enabled?
902 */
903 bool isStatusBarEnabled() const;
904
905 /**
906 * Show/hide the status bar of the view.
907 * Per default, the status bar is enabled.
908 *
909 * @param enable should the status bar be enabled?
910 */
911 void setStatusBarEnabled(bool enable);
912
913Q_SIGNALS:
914 /**
915 * This signal is emitted whenever the status bar of \p view is toggled.
916 *
917 * @param enabled Whether the status bar is currently enabled or not
918 */
919 void statusBarEnabledChanged(KTextEditor::View *view, bool enabled);
920
921public:
922 /**
923 * Read session settings from the given \p config.
924 *
925 * Known flags:
926 * none atm
927 *
928 * \param config read the session settings from this KConfigGroup
929 * \param flags additional flags
930 * \see writeSessionConfig()
931 */
932 virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
933
934 /**
935 * Write session settings to the \p config.
936 * See readSessionConfig() for more details.
937 *
938 * \param config write the session settings to this KConfigGroup
939 * \param flags additional flags
940 * \see readSessionConfig()
941 */
942 virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
943
944public:
945 /**
946 * Returns the attribute for the default style \p defaultStyle.
947 * @param defaultStyle default style to get the attribute for
948 * @see KTextEditor::Attribute
949 */
950 virtual QExplicitlySharedDataPointer<KTextEditor::Attribute> defaultStyleAttribute(KSyntaxHighlighting::Theme::TextStyle defaultStyle) const = 0;
951
952 /**
953 * Get the list of AttributeBlocks for a given \p line in the document.
954 *
955 * \return list of AttributeBlocks for given \p line.
956 */
957 virtual QList<KTextEditor::AttributeBlock> lineAttributes(int line) = 0;
958
959Q_SIGNALS:
960 /**
961 * This signal is emitted whenever the current view configuration is changed.
962 *
963 * \param view the view which's config has changed
964 *
965 * \since 5.79
966 */
967 void configChanged(KTextEditor::View *view);
968
969 /**
970 * View Config
971 */
972public:
973 /**
974 * Get a list of all available keys.
975 */
976 virtual QStringList configKeys() const = 0;
977 /**
978 * Get a value for the \p key.
979 */
980 virtual QVariant configValue(const QString &key) = 0;
981 /**
982 * Set a the \p key's value to \p value.
983 */
984 virtual void setConfigValue(const QString &key, const QVariant &value) = 0;
985
986 /**
987 * View Annotation Interface
988 */
989public:
990 /**
991 * Sets a new \ref AnnotationModel for this document to provide
992 * annotation information for each line.
993 *
994 * \param model the new AnnotationModel
995 */
996 virtual void setAnnotationModel(AnnotationModel *model) = 0;
997
998 /**
999 * returns the currently set \ref AnnotationModel or 0 if there's none
1000 * set
1001 * @returns the current \ref AnnotationModel
1002 */
1003 virtual AnnotationModel *annotationModel() const = 0;
1004
1005 /**
1006 * This function can be used to show or hide the annotation border
1007 * The annotation border is hidden by default.
1008 *
1009 * @param visible if \e true the annotation border is shown, otherwise hidden
1010 */
1011 virtual void setAnnotationBorderVisible(bool visible) = 0;
1012
1013 /**
1014 * Checks whether the View's annotation border is visible.
1015 */
1016 virtual bool isAnnotationBorderVisible() const = 0;
1017
1018 /**
1019 * Sets the AbstractAnnotationItemDelegate for this view and the model
1020 * to provide custom rendering of annotation information for each line.
1021 * Ownership is not transferred.
1022 *
1023 * \param delegate the new AbstractAnnotationItemDelegate, or \c nullptr to reset to the default delegate
1024 *
1025 * @since 6.0
1026 */
1027 virtual void setAnnotationItemDelegate(KTextEditor::AbstractAnnotationItemDelegate *delegate) = 0;
1028
1029 /**
1030 * Returns the currently used AbstractAnnotationItemDelegate
1031 *
1032 * @returns the current AbstractAnnotationItemDelegate
1033 *
1034 * @since 6.0
1035 */
1036 virtual KTextEditor::AbstractAnnotationItemDelegate *annotationItemDelegate() const = 0;
1037
1038 /**
1039 * This function can be used to declare whether it is known that the annotation items
1040 * rendered by the set delegate all have the same size.
1041 * This enables the view to do some optimizations for performance purposes.
1042 *
1043 * By default the value of this property is \c false .
1044 *
1045 * @param uniformItemSizes if \c true the annotation items are considered to all have the same size
1046 *
1047 * @since 6.0
1048 */
1049 virtual void setAnnotationUniformItemSizes(bool uniformItemSizes) = 0;
1050
1051 /**
1052 * Checks whether the annotation items all have the same size.
1053 *
1054 * @since 6.0
1055 */
1056 virtual bool uniformAnnotationItemSizes() const = 0;
1057
1058Q_SIGNALS:
1059 /**
1060 * This signal is emitted before a context menu is shown on the annotation
1061 * border for the given line and view.
1062 *
1063 * \note Kate Part implementation detail: In Kate Part, the menu has an
1064 * entry to hide the annotation border.
1065 *
1066 * \param view the view that the annotation border belongs to
1067 * \param menu the context menu that will be shown
1068 * \param line the annotated line for which the context menu is shown
1069 */
1070 void annotationContextMenuAboutToShow(KTextEditor::View *view, QMenu *menu, int line);
1071
1072 /**
1073 * This signal is emitted when an entry on the annotation border was activated,
1074 * for example by clicking or double-clicking it. This follows the KDE wide
1075 * setting for activation via click or double-clcik
1076 *
1077 * \param view the view to which the activated border belongs to
1078 * \param line the document line that the activated position belongs to
1079 */
1080 void annotationActivated(KTextEditor::View *view, int line);
1081
1082 /**
1083 * This signal is emitted when the annotation border is shown or hidden.
1084 *
1085 * \param view the view to which the border belongs to
1086 * \param visible the current visibility state
1087 */
1088 void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible);
1089
1090 /**
1091 * Inline Note
1092 */
1093public:
1094 /**
1095 * Register the inline note provider @p provider.
1096 *
1097 * Whenever a line is painted, the @p provider will be queried for notes
1098 * that should be painted in it. When the provider is about to be
1099 * destroyed, make sure to call unregisterInlineNoteProvider() to avoid a
1100 * dangling pointer.
1101 *
1102 * @param provider inline note provider
1103 * @see unregisterInlineNoteProvider(), InlineNoteProvider
1104 */
1105 virtual void registerInlineNoteProvider(KTextEditor::InlineNoteProvider *provider) = 0;
1106
1107 /**
1108 * Unregister the inline note provider @p provider.
1109 *
1110 * @param provider inline note provider to unregister
1111 * @see registerInlineNoteProvider(), InlineNoteProvider
1112 */
1113 virtual void unregisterInlineNoteProvider(KTextEditor::InlineNoteProvider *provider) = 0;
1114
1115 /**
1116 * Text Hint
1117 */
1118public:
1119 /**
1120 * Register the text hint provider \p provider.
1121 *
1122 * Whenever the user hovers over text, \p provider will be asked for
1123 * a text hint. When the provider is about to be destroyed, make
1124 * sure to call unregisterTextHintProvider() to avoid a dangling pointer.
1125 *
1126 * @param provider text hint provider
1127 * @see unregisterTextHintProvider(), TextHintProvider
1128 */
1129 virtual void registerTextHintProvider(KTextEditor::TextHintProvider *provider) = 0;
1130
1131 /**
1132 * Unregister the text hint provider \p provider.
1133 *
1134 * @param provider text hint provider to unregister
1135 * @see registerTextHintProvider(), TextHintProvider
1136 */
1137 virtual void unregisterTextHintProvider(KTextEditor::TextHintProvider *provider) = 0;
1138
1139 /**
1140 * Set the text hint delay to \p delay milliseconds.
1141 *
1142 * The delay specifies the time the user needs to hover over the text
1143 * before the tool tip is shown. Therefore, \p delay should not be
1144 * too large, a value of 500 milliseconds is recommended and set by
1145 * default.
1146 *
1147 * If \p delay is <= 0, the default delay will be set.
1148 *
1149 * \param delay tool tip delay in milliseconds
1150 */
1151 virtual void setTextHintDelay(int delay) = 0;
1152
1153 /**
1154 * Get the text hint delay in milliseconds.
1155 * By default, the text hint delay is set to 500 milliseconds.
1156 * It can be changed by calling \p setTextHintDelay().
1157 */
1158 virtual int textHintDelay() const = 0;
1159
1160 /**
1161 * Completion
1162 */
1163public:
1164 /**
1165 * Query whether the code completion box is currently displayed.
1166 */
1167 virtual bool isCompletionActive() const = 0;
1168
1169 /**
1170 * Invoke code completion over a given range, with a specific \a model.
1171 */
1172 virtual void startCompletion(Range word, CodeCompletionModel *model) = 0;
1173
1174 /**
1175 * Abort the currently displayed code completion without executing any currently
1176 * selected completion. This is safe, even when the completion box is not currently
1177 * active.
1178 * \see isCompletionActive()
1179 */
1180 virtual void abortCompletion() = 0;
1181
1182 /**
1183 * Force execution of the currently selected completion, and hide the code completion
1184 * box.
1185 */
1186 virtual void forceCompletion() = 0;
1187
1188 /**
1189 * Register a new code completion \p model.
1190 * \param model new completion model
1191 * \see unregisterCompletionModel()
1192 */
1193 virtual void registerCompletionModel(CodeCompletionModel *model) = 0;
1194
1195 /**
1196 * Unregister a code completion \p model.
1197 * \param model the model that should be unregistered
1198 * \see registerCompletionModel()
1199 */
1200 virtual void unregisterCompletionModel(CodeCompletionModel *model) = 0;
1201
1202 /**
1203 * Determine the status of automatic code completion invocation.
1204 */
1205 virtual bool isAutomaticInvocationEnabled() const = 0;
1206
1207 /**
1208 * Enable or disable automatic code completion invocation.
1209 */
1210 virtual void setAutomaticInvocationEnabled(bool enabled = true) = 0;
1211
1212 /**
1213 * Invoke code completion over a given range, with specific models and invocation type.
1214 * \param models list of models to start. If this is an empty list, all registered models are started.
1215 */
1216 virtual void startCompletion(const Range &word,
1217 const QList<CodeCompletionModel *> &models = QList<CodeCompletionModel *>(),
1218 KTextEditor::CodeCompletionModel::InvocationType invocationType = KTextEditor::CodeCompletionModel::ManualInvocation) = 0;
1219
1220 /**
1221 * Obtain the list of registered code completion models.
1222 * \returns a list of a models that are currently registered
1223 * \see registerCompletionModel(CodeCompletionModel*)
1224 */
1225 virtual QList<CodeCompletionModel *> codeCompletionModels() const = 0;
1226
1227public:
1228 /**
1229 * Get the current active theme of this view.
1230 * Might change during runtime, configChanged() will be emitted in that cases.
1231 *
1232 * \return current active theme
1233 *
1234 * \since 5.79
1235 */
1236 KSyntaxHighlighting::Theme theme() const;
1237
1238private:
1239 /**
1240 * private d-pointer, pointing to the internal implementation
1241 */
1242 ViewPrivate *const d;
1243};
1244
1245}
1246
1247#endif
1248

source code of ktexteditor/src/include/ktexteditor/view.h