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
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
612
613 /**
614 * This signal should be emitted whenever the \p view is scrolled horizontally.
615 * \param view view which emitted the signal
616 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
1028
1029 /**
1030 * Returns the currently used AbstractAnnotationItemDelegate
1031 *
1032 * @returns the current AbstractAnnotationItemDelegate
1033 *
1034 * @since 6.0
1035 */
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 */
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 */
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 */
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 */
1106
1107 /**
1108 * Unregister the inline note provider @p provider.
1109 *
1110 * @param provider inline note provider to unregister
1111 * @see registerInlineNoteProvider(), InlineNoteProvider
1112 */
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 */
1130
1131 /**
1132 * Unregister the text hint provider \p provider.
1133 *
1134 * @param provider text hint provider to unregister
1135 * @see registerTextHintProvider(), TextHintProvider
1136 */
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 */
1194
1195 /**
1196 * Unregister a code completion \p model.
1197 * \param model the model that should be unregistered
1198 * \see registerCompletionModel()
1199 */
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 */
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
A delegate for rendering line annotation information and handling events.
An model for providing line annotation information.
An item model for providing code completion, and meta information for enhanced presentation.
The Cursor represents a position in a Document.
Definition cursor.h:75
A KParts derived class representing a text document.
Definition document.h:284
A source of inline notes for a document.
This class allows the application that embeds the KTextEditor component to allow it to access parts o...
Definition mainwindow.h:47
An object representing a section of text, from one Cursor to another.
Class to provide text hints for a View.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
void horizontalScrollPositionChanged(KTextEditor::View *view)
This signal should be emitted whenever the view is scrolled horizontally.
virtual int textHintDelay() const =0
Get the text hint delay in milliseconds.
~View() override
Virtual destructor.
virtual void setConfigValue(const QString &key, const QVariant &value)=0
Set a the key's value to value.
virtual void printPreview()=0
Shows the print preview dialog/.
virtual QMenu * defaultContextMenu(QMenu *menu=nullptr) const =0
Populate menu with default text editor actions.
virtual void setViewInputMode(InputMode inputMode)=0
Set the view's new input mode.
virtual bool isAutomaticInvocationEnabled() const =0
Determine the status of automatic code completion invocation.
virtual bool uniformAnnotationItemSizes() const =0
Checks whether the annotation items all have the same size.
virtual QVariant configValue(const QString &key)=0
Get a value for the key.
virtual ViewMode viewMode() const =0
Get the current view mode/state.
virtual bool setCursorPosition(Cursor position)=0
Set the view's new cursor to position.
virtual void forceCompletion()=0
Force execution of the currently selected completion, and hide the code completion box.
void annotationContextMenuAboutToShow(KTextEditor::View *view, QMenu *menu, int line)
This signal is emitted before a context menu is shown on the annotation border for the given line and...
void configChanged(KTextEditor::View *view)
This signal is emitted whenever the current view configuration is changed.
virtual InputMode viewInputMode() const =0
Get the view's current input mode.
void textInserted(KTextEditor::View *view, KTextEditor::Cursor position, const QString &text)
This signal is emitted from view whenever the users inserts text at position, that means the user typ...
virtual bool setMouseTrackingEnabled(bool enable)=0
Try to enable or disable mouse tracking according to enable.
void statusBarEnabledChanged(KTextEditor::View *view, bool enabled)
This signal is emitted whenever the status bar of view is toggled.
void viewInputModeChanged(KTextEditor::View *view, KTextEditor::View::InputMode mode)
This signal is emitted whenever the view's input mode changes.
virtual void registerInlineNoteProvider(KTextEditor::InlineNoteProvider *provider)=0
Inline Note.
virtual Document * document() const =0
Get the view's document, that means the view is a view of the returned document.
virtual void startCompletion(const Range &word, const QList< CodeCompletionModel * > &models=QList< CodeCompletionModel * >(), KTextEditor::CodeCompletionModel::InvocationType invocationType=KTextEditor::CodeCompletionModel::ManualInvocation)=0
Invoke code completion over a given range, with specific models and invocation type.
virtual bool removeSelectionText()=0
Remove the view's current selection including the selected text.
ViewMode
Possible view modes These correspond to various modes the text editor might be in.
Definition view.h:295
virtual bool blockSelection() const =0
Get the status of the selection mode.
virtual QScrollBar * horizontalScrollBar() const =0
virtual bool print()=0
Print the document.
virtual QPoint cursorPositionCoordinates() const =0
Get the screen coordinates (x, y) of the cursor position in pixels.
virtual QScrollBar * verticalScrollBar() const =0
virtual void setAnnotationItemDelegate(KTextEditor::AbstractAnnotationItemDelegate *delegate)=0
Sets the AbstractAnnotationItemDelegate for this view and the model to provide custom rendering of an...
virtual QList< CodeCompletionModel * > codeCompletionModels() const =0
Obtain the list of registered code completion models.
virtual AnnotationModel * annotationModel() const =0
returns the currently set AnnotationModel or 0 if there's none set
void focusOut(KTextEditor::View *view)
This signal is emitted whenever the view loses the focus.
virtual Cursor cursorPosition() const =0
Get the view's current cursor position.
void annotationActivated(KTextEditor::View *view, int line)
This signal is emitted when an entry on the annotation border was activated, for example by clicking ...
virtual QString viewInputModeHuman() const =0
Get the view's current input mode in human readable form.
void focusIn(KTextEditor::View *view)
This signal is emitted whenever the view gets the focus.
virtual void readSessionConfig(const KConfigGroup &config, const QSet< QString > &flags=QSet< QString >())=0
Read session settings from the given config.
virtual void registerTextHintProvider(KTextEditor::TextHintProvider *provider)=0
Text Hint.
virtual QMenu * contextMenu() const =0
Get the context menu for this view.
virtual bool isAnnotationBorderVisible() const =0
Checks whether the View's annotation border is visible.
virtual void setAnnotationModel(AnnotationModel *model)=0
View Annotation Interface.
InputMode
Possible input modes.
Definition view.h:286
virtual QStringList configKeys() const =0
View Config.
virtual QString viewModeHuman() const =0
Get the current view mode state.
LineType
Possible line types.
Definition view.h:311
virtual void writeSessionConfig(KConfigGroup &config, const QSet< QString > &flags=QSet< QString >())=0
Write session settings to the config.
virtual void setAnnotationUniformItemSizes(bool uniformItemSizes)=0
This function can be used to declare whether it is known that the annotation items rendered by the se...
virtual bool mouseTrackingEnabled() const =0
Check, whether mouse tracking is enabled.
virtual void setAutomaticInvocationEnabled(bool enabled=true)=0
Enable or disable automatic code completion invocation.
virtual void abortCompletion()=0
Abort the currently displayed code completion without executing any currently selected completion.
virtual KTextEditor::Cursor coordinatesToCursor(const QPoint &coord) const =0
Get the text-cursor in the document from the screen coordinates, relative to the view widget.
virtual QList< KTextEditor::AttributeBlock > lineAttributes(int line)=0
Get the list of AttributeBlocks for a given line in the document.
void cursorPositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPosition)
This signal is emitted whenever the view's cursor position changed.
virtual bool setSelection(Range range)=0
Set the view's selection to the range selection.
virtual void setContextMenu(QMenu *menu)=0
Set a context menu for this view to menu.
virtual bool selection() const =0
Query the view whether it has selected text, i.e.
virtual Cursor cursorPositionVirtual() const =0
Get the current virtual cursor position, virtual means the tabulator character (TAB) counts multiple ...
virtual QExplicitlySharedDataPointer< KTextEditor::Attribute > defaultStyleAttribute(KSyntaxHighlighting::Theme::TextStyle defaultStyle) const =0
Returns the attribute for the default style defaultStyle.
virtual void unregisterInlineNoteProvider(KTextEditor::InlineNoteProvider *provider)=0
Unregister the inline note provider provider.
virtual Range selectionRange() const =0
Get the range occupied by the current selection.
virtual void setAnnotationBorderVisible(bool visible)=0
This function can be used to show or hide the annotation border The annotation border is hidden by de...
void mousePositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPosition)
This signal is emitted whenever the position of the mouse changes over this view.
virtual KTextEditor::AbstractAnnotationItemDelegate * annotationItemDelegate() const =0
Returns the currently used AbstractAnnotationItemDelegate.
virtual void registerCompletionModel(CodeCompletionModel *model)=0
Register a new code completion model.
void viewModeChanged(KTextEditor::View *view, KTextEditor::View::ViewMode mode)
This signal is emitted whenever the view mode of view changes.
virtual bool isCompletionActive() const =0
Completion.
virtual void setTextHintDelay(int delay)=0
Set the text hint delay to delay milliseconds.
void selectionChanged(KTextEditor::View *view)
This signal is emitted whenever the view's selection changes.
void annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible)
This signal is emitted when the annotation border is shown or hidden.
virtual QPoint cursorToCoordinate(KTextEditor::Cursor cursor) const =0
Get the screen coordinates (x, y) of the supplied cursor relative to the view widget in pixels.
virtual bool setBlockSelection(bool on)=0
Set block selection mode to state on.
void contextMenuAboutToShow(KTextEditor::View *view, QMenu *menu)
Signal which is emitted immediately prior to showing the current context menu.
virtual bool removeSelection()=0
Remove the view's current selection, without deleting the selected text.
virtual void unregisterTextHintProvider(KTextEditor::TextHintProvider *provider)=0
Unregister the text hint provider provider.
virtual void unregisterCompletionModel(CodeCompletionModel *model)=0
Unregister a code completion model.
virtual KTextEditor::MainWindow * mainWindow() const =0
Get the view's main window, if any.
virtual QString selectionText() const =0
Get the view's selected text.
virtual void startCompletion(Range word, CodeCompletionModel *model)=0
Invoke code completion over a given range, with a specific model.
void verticalScrollPositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPos)
This signal should be emitted whenever the view is scrolled vertically.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:57:26 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.