KTextEditor

view.h
1 /*
2  SPDX-FileCopyrightText: 2001 Christoph Cullmann <[email protected]>
3 
4  Documentation:
5  SPDX-FileCopyrightText: 2005 Dominik Haumann <[email protected]>
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/attribute.h>
14 #include <ktexteditor/document.h>
15 #include <ktexteditor/range.h>
16 #include <ktexteditor_export.h>
17 
18 // gui merging
19 #include <KXMLGUIClient>
20 
21 // theme support
22 #include <KSyntaxHighlighting/Theme>
23 
24 // widget
25 #include <QWidget>
26 
27 class QMenu;
28 
29 class KConfigGroup;
30 
31 namespace KTextEditor
32 {
33 class Document;
34 class MainWindow;
35 class ViewPrivate;
36 
37 /**
38  * \class View view.h <KTextEditor/View>
39  *
40  * \brief A text widget with KXMLGUIClient that represents a Document.
41  *
42  * Topics:
43  * - \ref view_intro
44  * - \ref view_hook_into_gui
45  * - \ref view_selection
46  * - \ref view_cursors
47  * - \ref view_mouse_tracking
48  * - \ref view_modes
49  * - \ref view_extensions
50  *
51  * \section view_intro Introduction
52  *
53  * The View class represents a single view of a KTextEditor::Document,
54  * get the document on which the view operates with document().
55  * A view provides both the graphical representation of the text and the
56  * KXMLGUIClient for the actions. The view itself does not provide
57  * text manipulation, use the methods from the Document instead. The only
58  * method to insert text is insertText(), which inserts the given text
59  * at the current cursor position and emits the signal textInserted().
60  *
61  * Usually a view is created by using Document::createView().
62  * Furthermore a view can have a context menu. Set it with setContextMenu()
63  * and get it with contextMenu().
64  *
65  * \section view_hook_into_gui Merging the View's GUI
66  *
67  * A View is derived from the class KXMLGUIClient, so its GUI elements (like
68  * menu entries and toolbar items) can be merged into the application's GUI
69  * (or into a KXMLGUIFactory) by calling
70  * \code
71  * // view is of type KTextEditor::View*
72  * mainWindow()->guiFactory()->addClient( view );
73  * \endcode
74  * You can add only one view as client, so if you have several views, you first
75  * have to remove the current view, and then add the new one, like this
76  * \code
77  * mainWindow()->guiFactory()->removeClient( currentView );
78  * mainWindow()->guiFactory()->addClient( newView );
79  * \endcode
80  *
81  * \section view_selection Text Selection
82  *
83  * As the view is a graphical text editor it provides \e normal and \e block
84  * text selection. You can check with selection() whether a selection exists.
85  * removeSelection() will remove the selection without removing the text,
86  * whereas removeSelectionText() also removes both, the selection and the
87  * selected text. Use selectionText() to get the selected text and
88  * setSelection() to specify the selected text range. The signal
89  * selectionChanged() is emitted whenever the selection changed.
90  *
91  * \section view_cursors Cursor Positions
92  *
93  * A view has one Cursor which represents a line/column tuple. Two different
94  * kinds of cursor positions are supported: first is the \e real cursor
95  * position where a \e tab character only counts one character. Second is the
96  * \e virtual cursor position, where a \e tab character counts as many
97  * spaces as defined. Get the real position with cursorPosition() and the
98  * virtual position with cursorPositionVirtual(). Set the real cursor
99  * position with setCursorPosition(). The signal cursorPositionChanged() is
100  * emitted whenever the cursor position changed.
101  *
102  * Screen coordinates of the current text cursor position in pixels are obtained
103  * through cursorPositionCoordinates(). Further conversion of screen pixel
104  * coordinates and text cursor positions are provided by cursorToCoordinate()
105  * and coordinatesToCursor().
106  *
107  * \section view_mouse_tracking Mouse Tracking
108  *
109  * It is possible to get notified via the signal mousePositionChanged() for
110  * mouse move events, if mouseTrackingEnabled() returns \e true. Mouse tracking
111  * can be turned on/off by calling setMouseTrackingEnabled(). If an editor
112  * implementation does not support mouse tracking, mouseTrackingEnabled() will
113  * always return \e false.
114  *
115  * \section view_modes Input/View Modes
116  *
117  * A view supports several input modes. Common input modes are
118  * \e NormalInputMode and \e ViInputMode. Which input modes the editor supports depends on the
119  * implementation. The getter viewInputMode() returns enum \InputMode representing the current mode.
120  *
121  * Input modes can have their own view modes. In case of default \e NormalInputMode those are
122  * \e NormalModeInsert and \e NormalModeOverwrite. You can use viewMode() getter to obtain those.
123  *
124  * For viewMode() and viewInputMode() there are also variants with \e Human suffix, which
125  * returns the human readable representation (i18n) usable for displaying in user interface.
126  *
127  * Whenever the input/view mode changes the signals
128  * viewInputModeChanged()/viewModeChanged() are emitted.
129  *
130  * \section view_extensions View Extension Interfaces
131  *
132  * A simple view represents the text of a Document and provides a text cursor,
133  * text selection, edit modes etc.
134  * Advanced concepts like code completion and text hints are defined in the
135  * extension interfaces. An KTextEditor implementation does not need to
136  * support all the extensions. To implement the interfaces multiple
137  * inheritance is used.
138  *
139  * More information about interfaces for the view can be found in
140  * \ref kte_group_view_extensions.
141  *
142  * \see KTextEditor::Document, KTextEditor::CodeCompletionInterface,
143  * KXMLGUIClient
144  * \author Christoph Cullmann <[email protected]>
145  */
146 class KTEXTEDITOR_EXPORT View : public QWidget, public KXMLGUIClient
147 {
148  Q_OBJECT
149 
150 protected:
151  /**
152  * Constructor.
153  *
154  * Create a view attached to the widget \p parent.
155  *
156  * Pass it the internal implementation to store a d-pointer.
157  *
158  * \param impl d-pointer to use
159  * \param parent parent widget
160  * \see Document::createView()
161  */
162  View(ViewPrivate *impl, QWidget *parent);
163 
164 public:
165  /**
166  * Virtual destructor.
167  */
168  ~View() override;
169 
170  /*
171  * Accessor for the document
172  */
173 public:
174  /**
175  * Get the view's \e document, that means the view is a view of the
176  * returned document.
177  * \return the view's document
178  */
179  virtual Document *document() const = 0;
180 
181  /*
182  * General information about this view
183  */
184 public:
185  /**
186  * Possible input modes.
187  * These correspond to various modes the text editor might be in.
188  */
189  enum InputMode {
190  NormalInputMode = 0, /**< Normal Mode. */
191  ViInputMode = 1 /**< Vi mode. The view will behave like the editor vi(m) */
192  };
193 
194  /**
195  * Possible view modes
196  * These correspond to various modes the text editor might be in.
197  */
198  enum ViewMode {
199  NormalModeInsert = 0, /**< Insert mode. Characters will be added. */
200  NormalModeOverwrite = 1, /**< Overwrite mode. Characters will be replaced. */
201 
202  ViModeNormal = 10,
203  ViModeInsert = 11,
204  ViModeVisual = 12,
205  ViModeVisualLine = 13,
206  ViModeVisualBlock = 14,
207  ViModeReplace = 15
208  };
209 
210  /**
211  * Possible line types
212  * \since 5.33
213  */
214  enum LineType {
215  RealLine = 0, /**< Real line */
216  VisibleLine = 1 /**< Visible line. Line that is not folded. */
217  };
218  /**
219  * Get the current view mode/state.
220  * This can be used to detect the view's current mode. For
221  * example \NormalInputMode, \ViInputMode or whatever other input modes are
222  * supported. \see viewModeHuman() for translated version.
223  * \return current view mode/state
224  * \see viewModeChanged()
225  */
226  virtual ViewMode viewMode() const = 0;
227 
228  /**
229  * Get the current view mode state.
230  * This can be used to visually indicate the view's current mode, for
231  * example \e INSERT mode, \e OVERWRITE mode or \e COMMAND mode - or
232  * whatever other edit modes are supported. The string should be
233  * translated (i18n), as this is a user aimed representation of the view
234  * state, which should be shown in the GUI, for example in the status bar.
235  * This string may be rich-text.
236  * \return Human-readable version of the view mode state
237  * \see viewModeChanged()
238  */
239  virtual QString viewModeHuman() const = 0;
240 
241  /**
242  * Set the view's new input mode.
243  * \param inputMode new InputMode value
244  * \see viewInputMode()
245  * @since 5.54
246  * KF6: make virtual
247  */
248  void setViewInputMode(InputMode inputMode);
249 
250  /**
251  * Get the view's current input mode.
252  * The current mode can be \NormalInputMode and \ViInputMode.
253  * For human translated version \see viewInputModeHuman.
254  *
255  * \return the current input mode of this view
256  * \see viewInputModeChanged()
257  */
258  virtual InputMode viewInputMode() const = 0;
259 
260  /**
261  * Get the view's current input mode in human readable form.
262  * The string should be translated (i18n). For id like version \see viewInputMode
263  *
264  * \return the current input mode of this view in human readable form
265  */
266  virtual QString viewInputModeHuman() const = 0;
267 
268  /**
269  * Get the view's main window, if any
270  * \return the view's main window, will always return at least some non-nullptr dummy interface
271  */
272  virtual KTextEditor::MainWindow *mainWindow() const = 0;
273 
274  /*
275  * SIGNALS
276  * following signals should be emitted by the editor view
277  */
278 Q_SIGNALS:
279  /**
280  * This signal is emitted whenever the \p view gets the focus.
281  * \param view view which gets focus
282  * \see focusOut()
283  */
284  void focusIn(KTextEditor::View *view);
285 
286  /**
287  * This signal is emitted whenever the \p view loses the focus.
288  * \param view view which lost focus
289  * \see focusIn()
290  */
291  void focusOut(KTextEditor::View *view);
292 
293  /**
294  * This signal is emitted whenever the view mode of \p view changes.
295  * \param view the view which changed its mode
296  * \param mode new view mode
297  * \see viewMode()
298  */
299  void viewModeChanged(KTextEditor::View *view, KTextEditor::View::ViewMode mode);
300 
301  /**
302  * This signal is emitted whenever the \p view's input \p mode changes.
303  * \param view view which changed its input mode
304  * \param mode new input mode
305  * \see viewInputMode()
306  */
307  void viewInputModeChanged(KTextEditor::View *view, KTextEditor::View::InputMode mode);
308 
309  /**
310  * This signal is emitted from \p view whenever the users inserts \p text
311  * at \p position, that means the user typed/pasted text.
312  * \param view view in which the text was inserted
313  * \param position position where the text was inserted
314  * \param text the text the user has typed into the editor
315  * \see insertText()
316  */
317  void textInserted(KTextEditor::View *view, const KTextEditor::Cursor &position, const QString &text);
318 
319  /*
320  * Context menu handling
321  */
322 public:
323  /**
324  * Set a context menu for this view to \p menu.
325  *
326  * \note any previously assigned menu is not deleted. If you are finished
327  * with the previous menu, you may delete it.
328  *
329  * \warning Use this with care! Plugin xml gui clients are not merged
330  * into this menu!
331  * \warning !!!!!! DON'T USE THIS FUNCTION, UNLESS YOU ARE SURE YOU DON'T WANT PLUGINS TO WORK !!!!!!
332  *
333  * \param menu new context menu object for this view
334  * \see contextMenu()
335  */
336  virtual void setContextMenu(QMenu *menu) = 0;
337 
338  /**
339  * Get the context menu for this view. The return value can be NULL
340  * if no context menu object was set and kxmlgui is not initialized yet.
341  * If there is no user set menu, the kxmlgui menu is returned. Do not delete this menu, if
342  * if it is the xmlgui menu.
343  * \return context menu object
344  * \see setContextMenu()
345  */
346  virtual QMenu *contextMenu() const = 0;
347 
348  /**
349  * Populate \a menu with default text editor actions. If \a menu is
350  * null, a menu will be created with the view as its parent.
351  *
352  * \note to use this menu, you will next need to call setContextMenu(),
353  * as this does not assign the new context menu.
354  *
355  * \warning This contains only basic options from the editor component
356  * (katepart). Plugins are \p not merged/integrated into it!
357  * If you want to be a better citizen and take full advantage
358  * of KTextEditor plugins do something like:
359  * \code
360  * KXMLGUIClient* client = view;
361  * // search parent XmlGuiClient
362  * while (client->parentClient()) {
363  * client = client->parentClient();
364  * }
365  *
366  * if (client->factory()) {
367  * const QList<QWidget*> menuContainers = client->factory()->containers("menu");
368  * for (QWidget *w : menuContainers) {
369  * if (w->objectName() == "ktexteditor_popup") {
370  * // do something with the menu (ie adding an onshow handler)
371  * break;
372  * }
373  * }
374  * }
375  * \endcode
376  * \warning or simply use the aboutToShow, aboutToHide signals !!!!!
377  *
378  * \param menu the menu to be populated, or null to create a new menu.
379  * \return the menu, whether created or passed initially
380  */
381  virtual QMenu *defaultContextMenu(QMenu *menu = nullptr) const = 0;
382 
383 Q_SIGNALS:
384  /**
385  * Signal which is emitted immediately prior to showing the current
386  * context \a menu.
387  */
388  void contextMenuAboutToShow(KTextEditor::View *view, QMenu *menu);
389 
390  /*
391  * Cursor handling
392  */
393 public:
394  /**
395  * Set the view's new cursor to \p position. A \e TAB character
396  * is handled as only on character.
397  * \param position new cursor position
398  * \return \e true on success, otherwise \e false
399  * \see cursorPosition()
400  */
401  virtual bool setCursorPosition(Cursor position) = 0;
402 
403  /**
404  * Set the view's new cursors to \p positions. A \e TAB character
405  * is handled as only on character.
406  *
407  * This allows to create multiple cursors in this view.
408  *
409  * The first passed position will be used for the primary cursor
410  * just like if you would call \ref setCursorPosition.
411  *
412  * \param positions new cursor positions
413  * \see cursorPositions()
414  *
415  * @since 5.95
416  */
417  void setCursorPositions(const QVector<KTextEditor::Cursor> &positions);
418 
419  /**
420  * Get the view's current cursor position. A \e TAB character is
421  * handled as only one character.
422  * \return current cursor position
423  * \see setCursorPosition()
424  */
425  virtual Cursor cursorPosition() const = 0;
426 
427  /**
428  * Get the view's current cursor positions. A \e TAB character is
429  * handled as only one character.
430  *
431  * The returned vector contains the primary cursor as first element.
432  *
433  * @since 5.95
434  *
435  * \return all currently existing cursors
436  */
437  QVector<KTextEditor::Cursor> cursorPositions() const;
438 
439  /**
440  * Get the current \e virtual cursor position, \e virtual means the
441  * tabulator character (TAB) counts \e multiple characters, as configured
442  * by the user (e.g. one TAB is 8 spaces). The virtual cursor
443  * position provides access to the user visible values of the current
444  * cursor position.
445  *
446  * \return virtual cursor position
447  * \see cursorPosition()
448  */
449  virtual Cursor cursorPositionVirtual() const = 0;
450 
451  /**
452  * Get the screen coordinates (x, y) of the supplied \a cursor relative
453  * to the view widget in pixels. Thus, (0, 0) represents the top left hand
454  * of the view widget.
455  *
456  * To map pixel coordinates to a Cursor position (the reverse transformation)
457  * use coordinatesToCursor().
458  *
459  * \param cursor cursor to determine coordinate for.
460  * \return cursor screen coordinates relative to the view widget
461  *
462  * \see cursorPositionCoordinates(), coordinatesToCursor()
463  */
464  virtual QPoint cursorToCoordinate(const KTextEditor::Cursor &cursor) const = 0;
465 
466  /**
467  * Get the screen coordinates (x, y) of the cursor position in pixels.
468  * The returned coordinates are relative to the View such that (0, 0)
469  * represents tht top-left corner of the View.
470  *
471  * If global screen coordinates are required, e.g. for showing a QToolTip,
472  * convert the view coordinates to global screen coordinates as follows:
473  * \code
474  * QPoint viewCoordinates = view->cursorPositionCoordinates();
475  * QPoint globalCoorinates = view->mapToGlobal(viewCoordinates);
476  * \endcode
477  * \return cursor screen coordinates
478  * \see cursorToCoordinate(), coordinatesToCursor()
479  */
480  virtual QPoint cursorPositionCoordinates() const = 0;
481 
482  /**
483  * Get the text-cursor in the document from the screen coordinates,
484  * relative to the view widget.
485  *
486  * To map a cursor to pixel coordinates (the reverse transformation)
487  * use cursorToCoordinate().
488  *
489  * \param coord coordinates relative to the view widget
490  * \return cursor in the View, that points onto the character under
491  * the given coordinate. May be KTextEditor::Cursor::invalid().
492  */
493  virtual KTextEditor::Cursor coordinatesToCursor(const QPoint &coord) const = 0;
494 
495  /*
496  * SIGNALS
497  * following signals should be emitted by the editor view
498  * if the cursor position changes
499  */
500 Q_SIGNALS:
501  /**
502  * This signal is emitted whenever the \p view's cursor position changed.
503  * \param view view which emitted the signal
504  * \param newPosition new position of the cursor (Kate will pass the real
505  * cursor position, not the virtual)
506  * \see cursorPosition(), cursorPositionVirtual()
507  */
508  void cursorPositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPosition);
509 
510  /**
511  * This signal should be emitted whenever the \p view is scrolled vertically.
512  * \param view view which emitted the signal
513  * \param newPos the new scroll position
514  */
515  void verticalScrollPositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPos);
516 
517  /**
518  * This signal should be emitted whenever the \p view is scrolled horizontally.
519  * \param view view which emitted the signal
520  */
521  void horizontalScrollPositionChanged(KTextEditor::View *view);
522  /*
523  * Mouse position
524  */
525 public:
526  /**
527  * Check, whether mouse tracking is enabled.
528  *
529  * Mouse tracking is required to have the signal mousePositionChanged()
530  * emitted.
531  * \return \e true, if mouse tracking is enabled, otherwise \e false
532  * \see setMouseTrackingEnabled(), mousePositionChanged()
533  */
534  virtual bool mouseTrackingEnabled() const = 0;
535 
536  /**
537  * Try to enable or disable mouse tracking according to \p enable.
538  * The return value contains the state of mouse tracking \e after the
539  * request. Mouse tracking is required to have the mousePositionChanged()
540  * signal emitted.
541  *
542  * \note Implementation Notes: An implementation is not forced to support
543  * this, and should always return \e false if it does not have
544  * support.
545  *
546  * \param enable if \e true, try to enable mouse tracking, otherwise disable
547  * it.
548  * \return the current state of mouse tracking
549  * \see mouseTrackingEnabled(), mousePositionChanged()
550  */
551  virtual bool setMouseTrackingEnabled(bool enable) = 0;
552 
553 Q_SIGNALS:
554  /**
555  * This signal is emitted whenever the position of the mouse changes over
556  * this \a view. If the mouse moves off the view, an invalid cursor position
557  * should be emitted, i.e. Cursor::invalid().
558  * \note If mouseTrackingEnabled() returns \e false, this signal is never
559  * emitted.
560  * \param view view which emitted the signal
561  * \param newPosition new position of the mouse or Cursor::invalid(), if the
562  * mouse moved out of the \p view.
563  * \see mouseTrackingEnabled()
564  */
565  void mousePositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPosition);
566 
567  /*
568  * Selection methods.
569  * This deals with text selection and copy&paste
570  */
571 public:
572  /**
573  * Set the view's selection to the range \p selection.
574  * The old selection will be discarded.
575  * \param range the range of the new selection
576  * \return \e true on success, otherwise \e false (e.g. when the cursor
577  * range is invalid)
578  * \see selectionRange(), selection()
579  */
580  virtual bool setSelection(const Range &range) = 0;
581 
582  /**
583  * Set the view's selection to the range \p selection.
584  * The old selection will be discarded.
585  * \param ranges the ranges of the new selections
586  * \see selectionRanges(), selection()
587  *
588  * @since 5.95
589  */
590  void setSelections(const QVector<KTextEditor::Range> &ranges);
591 
592  /**
593  * Query the view whether it has selected text, i.e. whether a selection
594  * exists.
595  * \return \e true if a text selection exists, otherwise \e false
596  * \see setSelection(), selectionRange()
597  */
598  virtual bool selection() const = 0;
599 
600  /**
601  * Get the range occupied by the current selection.
602  * \return selection range, valid only if a selection currently exists.
603  * \see setSelection()
604  */
605  virtual Range selectionRange() const = 0;
606 
607  /**
608  * Get the ranges occupied by the current selections.
609  * \return selection ranges, valid only if a selection currently exists.
610  * \see setSelections()
611  *
612  * @since 5.95
613  */
614  QVector<KTextEditor::Range> selectionRanges() const;
615 
616  /**
617  * Get the view's selected text.
618  * \return the selected text
619  * \see setSelection()
620  */
621  virtual QString selectionText() const = 0;
622 
623  /**
624  * Remove the view's current selection, \e without deleting the selected
625  * text.
626  * \return \e true on success, otherwise \e false
627  * \see removeSelectionText()
628  */
629  virtual bool removeSelection() = 0;
630 
631  /**
632  * Remove the view's current selection \e including the selected text.
633  * \return \e true on success, otherwise \e false
634  * \see removeSelection()
635  */
636  virtual bool removeSelectionText() = 0;
637 
638  /*
639  * Blockselection stuff
640  */
641 public:
642  /**
643  * Set block selection mode to state \p on.
644  * \param on if \e true, block selection mode is turned on, otherwise off
645  * \return \e true on success, otherwise \e false
646  * \see blockSelection()
647  */
648  virtual bool setBlockSelection(bool on) = 0;
649 
650  /**
651  * Get the status of the selection mode. \e true indicates that block
652  * selection mode is on. If this is \e true, selections applied via the
653  * SelectionInterface are handled as block selections and the Copy&Paste
654  * functions work on rectangular blocks of text rather than normal.
655  * \return \e true, if block selection mode is enabled, otherwise \e false
656  * \see setBlockSelection()
657  */
658  virtual bool blockSelection() const = 0;
659 
660  /*
661  * SIGNALS
662  * following signals should be emitted by the editor view for selection
663  * handling.
664  */
665 Q_SIGNALS:
666  /**
667  * This signal is emitted whenever the \p view's selection changes.
668  * \note If the mode switches from block selection to normal selection
669  * or vice versa this signal should also be emitted.
670  * \param view view in which the selection changed
671  * \see selection(), selectionRange(), selectionText()
672  */
673  void selectionChanged(KTextEditor::View *view);
674 
675 public:
676  /**
677  * This is a convenience function which inserts \p text at the view's
678  * current cursor position. You do not necessarily need to reimplement
679  * it, except you want to do some special things.
680  * \param text Text to be inserted
681  * \return \e true on success of insertion, otherwise \e false
682  * \see textInserted()
683  */
684  virtual bool insertText(const QString &text);
685 
686  /**
687  * Insert a template into the document. The template can have editable fields
688  * which can be filled by the user. You can create editable fields
689  * with ${fieldname}; multiple fields with the same name will have their
690  * contents synchronized automatically, and only the first one is editable
691  * in this case.
692  * Fields can have a default value specified by writing ${fieldname=default}.
693  * Note that `default' is a JavaScript expression and strings need to be quoted.
694  * You can also provide a piece of JavaScript for more complex logic.
695  * To create a field which provides text based on a JS function call and the values
696  * of the other, editable fields, use the ${func()} syntax. func() must be a callable
697  * object defined in @p script. You can pass arguments to the function by just
698  * writing any constant expression or a field name.
699  * \param insertPosition where to insert the template
700  * \param templateString template to insert using the above syntax
701  * \param script script with functions which can be used in @p templateScript
702  * \return true on success, false if insertion failed (e.g. read-only mode)
703  */
704  bool insertTemplate(const KTextEditor::Cursor &insertPosition, const QString &templateString, const QString &script = QString());
705 
706  /**
707  * Scroll view to cursor.
708  *
709  * \param cursor the cursor position to scroll to.
710  *
711  * \since 5.33
712  */
713  void setScrollPosition(KTextEditor::Cursor &cursor);
714 
715  /**
716  * Horizontally scroll view to position.
717  *
718  * \param x the pixel position to scroll to.
719  *
720  * \since 5.33
721  */
722  void setHorizontalScrollPosition(int x);
723 
724  /**
725  * Get the cursor corresponding to the maximum position
726  * the view can vertically scroll to.
727  *
728  * \return cursor position of the maximum vertical scroll position.
729  *
730  * \since 5.33
731  */
732  KTextEditor::Cursor maxScrollPosition() const;
733 
734  /**
735  * Get the first displayed line in the view.
736  *
737  * \note If code is folded, many hundred lines can be
738  * between firstDisplayedLine() and lastDisplayedLine().
739  *
740  * \param lineType if RealLine (the default), it returns the real line number
741  * accounting for folded regions. In that case it walks over all folded
742  * regions
743  * O(n) for n == number of folded ranges
744  * \return the first displayed line
745  *
746  * \see lastDisplayedLine()
747  * \since 5.33
748  */
749  int firstDisplayedLine(LineType lineType = RealLine) const;
750 
751  /**
752  * Get the last displayed line in the view.
753  *
754  * \note If code is folded, many hundred lines can be
755  * between firstDisplayedLine() and lastDisplayedLine().
756  *
757  * \param lineType if RealLine (the default), it returns the real line number
758  * accounting for folded regions. In that case it walks over all folded
759  * regions
760  * O(n) for n == number of folded ranges
761  * \return the last displayed line
762  *
763  * \see firstDisplayedLine()
764  * \since 5.33
765  */
766  int lastDisplayedLine(LineType lineType = RealLine) const;
767 
768  /**
769  * Get the view's text area rectangle excluding border, scrollbars, etc.
770  *
771  * \return the view's text area rectangle
772  *
773  * \since 5.33
774  */
775  QRect textAreaRect() const;
776 
777 public:
778  /**
779  * Print the document. This should result in showing the print dialog.
780  *
781  * @returns true if document was printed
782  */
783  virtual bool print() = 0;
784 
785  /**
786  * Shows the print preview dialog/
787  */
788  virtual void printPreview() = 0;
789 
790  /**
791  * Is the status bar enabled?
792  *
793  * @return status bar enabled?
794  */
795  bool isStatusBarEnabled() const;
796 
797  /**
798  * Show/hide the status bar of the view.
799  * Per default, the status bar is enabled.
800  *
801  * @param enable should the status bar be enabled?
802  */
803  void setStatusBarEnabled(bool enable);
804 
805 Q_SIGNALS:
806  /**
807  * This signal is emitted whenever the status bar of \p view is toggled.
808  *
809  * @param enabled Whether the status bar is currently enabled or not
810  */
811  void statusBarEnabledChanged(KTextEditor::View *view, bool enabled);
812 
813 public:
814  /**
815  * Read session settings from the given \p config.
816  *
817  * Known flags:
818  * none atm
819  *
820  * \param config read the session settings from this KConfigGroup
821  * \param flags additional flags
822  * \see writeSessionConfig()
823  */
824  virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
825 
826  /**
827  * Write session settings to the \p config.
828  * See readSessionConfig() for more details.
829  *
830  * \param config write the session settings to this KConfigGroup
831  * \param flags additional flags
832  * \see readSessionConfig()
833  */
834  virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
835 
836 public:
837  /**
838  * Returns the attribute for the default style \p defaultStyle.
839  * @param defaultStyle default style to get the attribute for
840  * @see KTextEditor::Attribute
841  */
842  virtual KTextEditor::Attribute::Ptr defaultStyleAttribute(KTextEditor::DefaultStyle defaultStyle) const = 0;
843 
844  /**
845  * Get the list of AttributeBlocks for a given \p line in the document.
846  *
847  * \return list of AttributeBlocks for given \p line.
848  */
849  virtual QList<KTextEditor::AttributeBlock> lineAttributes(int line) = 0;
850 
851 Q_SIGNALS:
852  /**
853  * This signal is emitted whenever the current view configuration is changed.
854  *
855  * \param view the view which's config has changed
856  *
857  * \since 5.79
858  */
859  void configChanged(KTextEditor::View *view);
860 
861 public:
862  /**
863  * Get the current active theme of this view.
864  * Might change during runtime, configChanged() will be emitted in that cases.
865  *
866  * \return current active theme
867  *
868  * \since 5.79
869  */
870  KSyntaxHighlighting::Theme theme() const;
871 
872 private:
873  /**
874  * private d-pointer, pointing to the internal implementation
875  */
876  ViewPrivate *const d;
877 };
878 
879 }
880 
881 #endif
InputMode
Possible input modes.
Definition: view.h:189
DefaultStyle
The following lists all valid default styles that are used for the syntax highlighting files in the i...
Definition: attribute.h:26
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:198
The Cursor represents a position in a Document.
Definition: cursor.h:71
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
LineType
Possible line types.
Definition: view.h:214
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
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 KParts derived class representing a text document.
Definition: document.h:185
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue May 17 2022 03:46:52 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.