KTextEditor

view.h
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 
24 class QMenu;
25 class QScrollBar;
26 class KConfigGroup;
27 
28 namespace KSyntaxHighlighting
29 {
30 class Theme;
31 }
32 
33 namespace KTextEditor
34 {
35 class Document;
36 class MainWindow;
37 class ViewPrivate;
38 class Attribute;
39 class AttributeBlock;
40 class Range;
41 class Cursor;
42 class AnnotationModel;
43 class AbstractAnnotationItemDelegate;
44 class InlineNoteProvider;
45 class TextHintProvider;
46 class 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  */
243 class KTEXTEDITOR_EXPORT View : public QWidget, public KXMLGUIClient
244 {
245  Q_OBJECT
246 
247 protected:
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 
261 public:
262  /**
263  * Virtual destructor.
264  */
265  ~View() override;
266 
267  /*
268  * Accessor for the document
269  */
270 public:
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  */
281 public:
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  */
374 Q_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  */
418 public:
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 
479 Q_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  */
489 public:
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  */
596 Q_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  */
621 public:
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 
649 Q_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  */
667 public:
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  */
737 public:
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  */
761 Q_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 
771 public:
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 
885 public:
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 
913 Q_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 
921 public:
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 
944 public:
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 
959 Q_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  */
972 public:
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  */
989 public:
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 
1058 Q_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  */
1093 public:
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  */
1118 public:
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  */
1163 public:
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,
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 
1227 public:
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 
1238 private:
1239  /**
1240  * private d-pointer, pointing to the internal implementation
1241  */
1242  ViewPrivate *const d;
1243 };
1244 
1245 }
1246 
1247 #endif
A delegate for rendering line annotation information and handling events.
An item model for providing code completion, and meta information for enhanced presentation.
InputMode
Possible input modes.
Definition: view.h:286
An model for providing line annotation information.
An object representing a section of text, from one Cursor to another.
QString mode() const override
Return the name of the currently used mode.
void writeSessionConfig(KConfigGroup &config, const QSet< QString > &flags=QSet< QString >()) override
Write session settings to the config.
ViewMode
Possible view modes These correspond to various modes the text editor might be in.
Definition: view.h:295
The Cursor represents a position in a Document.
Definition: cursor.h:74
Class to provide text hints for a View.
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:243
LineType
Possible line types.
Definition: view.h:311
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:19
Q_SCRIPTABLE bool focusIn(int ms=-1)
void readSessionConfig(const KConfigGroup &config, const QSet< QString > &flags=QSet< QString >()) override
Read session settings from the given config.
KateDocumentConfig * config()
Configuration.
Q_SCRIPTABLE bool focusOut(int ms=-1)
A source of inline notes for a document.
A KParts derived class representing a text document.
Definition: document.h:283
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 03:50:45 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.