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 handeled 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  * Get the view's current cursor position. A \e TAB character is
405  * handeled as only one character.
406  * \return current cursor position
407  * \see setCursorPosition()
408  */
409  virtual Cursor cursorPosition() const = 0;
410 
411  /**
412  * Get the current \e virtual cursor position, \e virtual means the
413  * tabulator character (TAB) counts \e multiple characters, as configured
414  * by the user (e.g. one TAB is 8 spaces). The virtual cursor
415  * position provides access to the user visible values of the current
416  * cursor position.
417  *
418  * \return virtual cursor position
419  * \see cursorPosition()
420  */
421  virtual Cursor cursorPositionVirtual() const = 0;
422 
423  /**
424  * Get the screen coordinates (x, y) of the supplied \a cursor relative
425  * to the view widget in pixels. Thus, (0, 0) represents the top left hand
426  * of the view widget.
427  *
428  * To map pixel coordinates to a Cursor position (the reverse transformation)
429  * use coordinatesToCursor().
430  *
431  * \param cursor cursor to determine coordinate for.
432  * \return cursor screen coordinates relative to the view widget
433  *
434  * \see cursorPositionCoordinates(), coordinatesToCursor()
435  */
436  virtual QPoint cursorToCoordinate(const KTextEditor::Cursor &cursor) const = 0;
437 
438  /**
439  * Get the screen coordinates (x, y) of the cursor position in pixels.
440  * The returned coordinates are relative to the View such that (0, 0)
441  * represents tht top-left corner of the View.
442  *
443  * If global screen coordinates are required, e.g. for showing a QToolTip,
444  * convert the view coordinates to global screen coordinates as follows:
445  * \code
446  * QPoint viewCoordinates = view->cursorPositionCoordinates();
447  * QPoint globalCoorinates = view->mapToGlobal(viewCoordinates);
448  * \endcode
449  * \return cursor screen coordinates
450  * \see cursorToCoordinate(), coordinatesToCursor()
451  */
452  virtual QPoint cursorPositionCoordinates() const = 0;
453 
454  /**
455  * Get the text-cursor in the document from the screen coordinates,
456  * relative to the view widget.
457  *
458  * To map a cursor to pixel coordinates (the reverse transformation)
459  * use cursorToCoordinate().
460  *
461  * \param coord coordinates relative to the view widget
462  * \return cursor in the View, that points onto the character under
463  * the given coordinate. May be KTextEditor::Cursor::invalid().
464  */
465  virtual KTextEditor::Cursor coordinatesToCursor(const QPoint &coord) const = 0;
466 
467  /*
468  * SIGNALS
469  * following signals should be emitted by the editor view
470  * if the cursor position changes
471  */
472 Q_SIGNALS:
473  /**
474  * This signal is emitted whenever the \p view's cursor position changed.
475  * \param view view which emitted the signal
476  * \param newPosition new position of the cursor (Kate will pass the real
477  * cursor position, not the virtual)
478  * \see cursorPosition(), cursorPositionVirtual()
479  */
480  void cursorPositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPosition);
481 
482  /**
483  * This signal should be emitted whenever the \p view is scrolled vertically.
484  * \param view view which emitted the signal
485  * \param newPos the new scroll position
486  */
487  void verticalScrollPositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPos);
488 
489  /**
490  * This signal should be emitted whenever the \p view is scrolled horizontally.
491  * \param view view which emitted the signal
492  */
493  void horizontalScrollPositionChanged(KTextEditor::View *view);
494  /*
495  * Mouse position
496  */
497 public:
498  /**
499  * Check, whether mouse tracking is enabled.
500  *
501  * Mouse tracking is required to have the signal mousePositionChanged()
502  * emitted.
503  * \return \e true, if mouse tracking is enabled, otherwise \e false
504  * \see setMouseTrackingEnabled(), mousePositionChanged()
505  */
506  virtual bool mouseTrackingEnabled() const = 0;
507 
508  /**
509  * Try to enable or disable mouse tracking according to \p enable.
510  * The return value contains the state of mouse tracking \e after the
511  * request. Mouse tracking is required to have the mousePositionChanged()
512  * signal emitted.
513  *
514  * \note Implementation Notes: An implementation is not forced to support
515  * this, and should always return \e false if it does not have
516  * support.
517  *
518  * \param enable if \e true, try to enable mouse tracking, otherwise disable
519  * it.
520  * \return the current state of mouse tracking
521  * \see mouseTrackingEnabled(), mousePositionChanged()
522  */
523  virtual bool setMouseTrackingEnabled(bool enable) = 0;
524 
525 Q_SIGNALS:
526  /**
527  * This signal is emitted whenever the position of the mouse changes over
528  * this \a view. If the mouse moves off the view, an invalid cursor position
529  * should be emitted, i.e. Cursor::invalid().
530  * \note If mouseTrackingEnabled() returns \e false, this signal is never
531  * emitted.
532  * \param view view which emitted the signal
533  * \param newPosition new position of the mouse or Cursor::invalid(), if the
534  * mouse moved out of the \p view.
535  * \see mouseTrackingEnabled()
536  */
537  void mousePositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPosition);
538 
539  /*
540  * Selection methods.
541  * This deals with text selection and copy&paste
542  */
543 public:
544  /**
545  * Set the view's selection to the range \p selection.
546  * The old selection will be discarded.
547  * \param range the range of the new selection
548  * \return \e true on success, otherwise \e false (e.g. when the cursor
549  * range is invalid)
550  * \see selectionRange(), selection()
551  */
552  virtual bool setSelection(const Range &range) = 0;
553 
554  /**
555  * Query the view whether it has selected text, i.e. whether a selection
556  * exists.
557  * \return \e true if a text selection exists, otherwise \e false
558  * \see setSelection(), selectionRange()
559  */
560  virtual bool selection() const = 0;
561 
562  /**
563  * Get the range occupied by the current selection.
564  * \return selection range, valid only if a selection currently exists.
565  * \see setSelection()
566  */
567  virtual Range selectionRange() const = 0;
568 
569  /**
570  * Get the view's selected text.
571  * \return the selected text
572  * \see setSelection()
573  */
574  virtual QString selectionText() const = 0;
575 
576  /**
577  * Remove the view's current selection, \e without deleting the selected
578  * text.
579  * \return \e true on success, otherwise \e false
580  * \see removeSelectionText()
581  */
582  virtual bool removeSelection() = 0;
583 
584  /**
585  * Remove the view's current selection \e including the selected text.
586  * \return \e true on success, otherwise \e false
587  * \see removeSelection()
588  */
589  virtual bool removeSelectionText() = 0;
590 
591  /*
592  * Blockselection stuff
593  */
594 public:
595  /**
596  * Set block selection mode to state \p on.
597  * \param on if \e true, block selection mode is turned on, otherwise off
598  * \return \e true on success, otherwise \e false
599  * \see blockSelection()
600  */
601  virtual bool setBlockSelection(bool on) = 0;
602 
603  /**
604  * Get the status of the selection mode. \e true indicates that block
605  * selection mode is on. If this is \e true, selections applied via the
606  * SelectionInterface are handled as block selections and the Copy&Paste
607  * functions work on rectangular blocks of text rather than normal.
608  * \return \e true, if block selection mode is enabled, otherwise \e false
609  * \see setBlockSelection()
610  */
611  virtual bool blockSelection() const = 0;
612 
613  /*
614  * SIGNALS
615  * following signals should be emitted by the editor view for selection
616  * handling.
617  */
618 Q_SIGNALS:
619  /**
620  * This signal is emitted whenever the \p view's selection changes.
621  * \note If the mode switches from block selection to normal selection
622  * or vice versa this signal should also be emitted.
623  * \param view view in which the selection changed
624  * \see selection(), selectionRange(), selectionText()
625  */
626  void selectionChanged(KTextEditor::View *view);
627 
628 public:
629  /**
630  * This is a convenience function which inserts \p text at the view's
631  * current cursor position. You do not necessarily need to reimplement
632  * it, except you want to do some special things.
633  * \param text Text to be inserted
634  * \return \e true on success of insertion, otherwise \e false
635  * \see textInserted()
636  */
637  virtual bool insertText(const QString &text);
638 
639  /**
640  * Insert a template into the document. The template can have editable fields
641  * which can be filled by the user. You can create editable fields
642  * with ${fieldname}; multiple fields with the same name will have their
643  * contents synchronized automatically, and only the first one is editable
644  * in this case.
645  * Fields can have a default value specified by writing ${fieldname=default}.
646  * Note that `default' is a JavaScript expression and strings need to be quoted.
647  * You can also provide a piece of JavaScript for more complex logic.
648  * To create a field which provides text based on a JS function call and the values
649  * of the other, editable fields, use the ${func()} syntax. func() must be a callable
650  * object defined in @p script. You can pass arguments to the function by just
651  * writing any constant expression or a field name.
652  * \param insertPosition where to insert the template
653  * \param templateString template to insert using the above syntax
654  * \param script script with functions which can be used in @p templateScript
655  * \return true on success, false if insertion failed (e.g. read-only mode)
656  */
657  bool insertTemplate(const KTextEditor::Cursor &insertPosition, const QString &templateString, const QString &script = QString());
658 
659  /**
660  * Scroll view to cursor.
661  *
662  * \param cursor the cursor position to scroll to.
663  *
664  * \since 5.33
665  */
666  void setScrollPosition(KTextEditor::Cursor &cursor);
667 
668  /**
669  * Horizontally scroll view to position.
670  *
671  * \param x the pixel position to scroll to.
672  *
673  * \since 5.33
674  */
675  void setHorizontalScrollPosition(int x);
676 
677  /**
678  * Get the cursor corresponding to the maximum position
679  * the view can vertically scroll to.
680  *
681  * \return cursor position of the maximum vertical scroll position.
682  *
683  * \since 5.33
684  */
685  KTextEditor::Cursor maxScrollPosition() const;
686 
687  /**
688  * Get the first displayed line in the view.
689  *
690  * \note If code is folded, many hundred lines can be
691  * between firstDisplayedLine() and lastDisplayedLine().
692  *
693  * \param lineType if RealLine (the default), it returns the real line number
694  * accounting for folded regions. In that case it walks over all folded
695  * regions
696  * O(n) for n == number of folded ranges
697  * \return the first displayed line
698  *
699  * \see lastDisplayedLine()
700  * \since 5.33
701  */
702  int firstDisplayedLine(LineType lineType = RealLine) const;
703 
704  /**
705  * Get the last displayed line in the view.
706  *
707  * \note If code is folded, many hundred lines can be
708  * between firstDisplayedLine() and lastDisplayedLine().
709  *
710  * \param lineType if RealLine (the default), it returns the real line number
711  * accounting for folded regions. In that case it walks over all folded
712  * regions
713  * O(n) for n == number of folded ranges
714  * \return the last displayed line
715  *
716  * \see firstDisplayedLine()
717  * \since 5.33
718  */
719  int lastDisplayedLine(LineType lineType = RealLine) const;
720 
721  /**
722  * Get the view's text area rectangle excluding border, scrollbars, etc.
723  *
724  * \return the view's text area rectangle
725  *
726  * \since 5.33
727  */
728  QRect textAreaRect() const;
729 
730 public:
731  /**
732  * Print the document. This should result in showing the print dialog.
733  *
734  * @returns true if document was printed
735  */
736  virtual bool print() = 0;
737 
738  /**
739  * Shows the print preview dialog/
740  */
741  virtual void printPreview() = 0;
742 
743  /**
744  * Is the status bar enabled?
745  *
746  * @return status bar enabled?
747  */
748  bool isStatusBarEnabled() const;
749 
750  /**
751  * Show/hide the status bar of the view.
752  * Per default, the status bar is enabled.
753  *
754  * @param enable should the status bar be enabled?
755  */
756  void setStatusBarEnabled(bool enable);
757 
758 Q_SIGNALS:
759  /**
760  * This signal is emitted whenever the status bar of \p view is toggled.
761  *
762  * @param enabled Whether the status bar is currently enabled or not
763  */
764  void statusBarEnabledChanged(KTextEditor::View *view, bool enabled);
765 
766 public:
767  /**
768  * Read session settings from the given \p config.
769  *
770  * Known flags:
771  * none atm
772  *
773  * \param config read the session settings from this KConfigGroup
774  * \param flags additional flags
775  * \see writeSessionConfig()
776  */
777  virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
778 
779  /**
780  * Write session settings to the \p config.
781  * See readSessionConfig() for more details.
782  *
783  * \param config write the session settings to this KConfigGroup
784  * \param flags additional flags
785  * \see readSessionConfig()
786  */
787  virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0;
788 
789 public:
790  /**
791  * Returns the attribute for the default style \p defaultStyle.
792  * @param defaultStyle default style to get the attribute for
793  * @see KTextEditor::Attribute
794  */
795  virtual KTextEditor::Attribute::Ptr defaultStyleAttribute(KTextEditor::DefaultStyle defaultStyle) const = 0;
796 
797  /**
798  * Get the list of AttributeBlocks for a given \p line in the document.
799  *
800  * \return list of AttributeBlocks for given \p line.
801  */
802  virtual QList<KTextEditor::AttributeBlock> lineAttributes(int line) = 0;
803 
804 Q_SIGNALS:
805  /**
806  * This signal is emitted whenever the current view configuration is changed.
807  *
808  * \param view the view which's config has changed
809  *
810  * \since 5.79
811  */
812  void configChanged(KTextEditor::View *view);
813 
814 public:
815  /**
816  * Get the current active theme of this view.
817  * Might change during runtime, configChanged() will be emitted in that cases.
818  *
819  * \return current active theme
820  *
821  * \since 5.79
822  */
823  KSyntaxHighlighting::Theme theme() const;
824 
825 private:
826  /**
827  * private d-pointer, pointing to the internal implementation
828  */
829  ViewPrivate *const d;
830 };
831 
832 }
833 
834 #endif
LineType
Possible line types.
Definition: view.h:214
DefaultStyle
The following lists all valid default styles that are used for the syntax highlighting files in the i...
Definition: attribute.h:26
QString mode() const override
Return the name of the currently used mode.
The Cursor represents a position in a Document.
Definition: cursor.h:71
A KParts derived class representing a text document.
Definition: document.h:185
void readSessionConfig(const KConfigGroup &config, const QSet< QString > &flags=QSet< QString >()) override
Read session settings from the given config.
ViewMode
Possible view modes These correspond to various modes the text editor might be in.
Definition: view.h:198
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
KateDocumentConfig * config()
Configuration.
void writeSessionConfig(KConfigGroup &config, const QSet< QString > &flags=QSet< QString >()) override
Write session settings to the config.
An object representing a section of text, from one Cursor to another.
InputMode
Possible input modes.
Definition: view.h:189
A text widget with KXMLGUIClient that represents a Document.
Definition: view.h:146
This class allows the application that embeds the KTextEditor component to allow it to access parts o...
Definition: mainwindow.h:43
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Dec 5 2021 22:50:09 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.