File indexing completed on 2024-05-12 15:45:41
0001 /* 0002 SPDX-FileCopyrightText: 2001 Christoph Cullmann <cullmann@kde.org> 0003 0004 Documentation: 0005 SPDX-FileCopyrightText: 2005 Dominik Haumann <dhdev@gmx.de> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 0010 #ifndef KTEXTEDITOR_VIEW_H 0011 #define KTEXTEDITOR_VIEW_H 0012 0013 #include <ktexteditor/attribute.h> 0014 #include <ktexteditor/document.h> 0015 #include <ktexteditor/range.h> 0016 #include <ktexteditor_export.h> 0017 0018 // gui merging 0019 #include <KXMLGUIClient> 0020 0021 // theme support 0022 #include <KSyntaxHighlighting/Theme> 0023 0024 // widget 0025 #include <QWidget> 0026 0027 class QMenu; 0028 0029 class KConfigGroup; 0030 0031 namespace KTextEditor 0032 { 0033 class Document; 0034 class MainWindow; 0035 class ViewPrivate; 0036 0037 /** 0038 * \class View view.h <KTextEditor/View> 0039 * 0040 * \brief A text widget with KXMLGUIClient that represents a Document. 0041 * 0042 * Topics: 0043 * - \ref view_intro 0044 * - \ref view_hook_into_gui 0045 * - \ref view_selection 0046 * - \ref view_cursors 0047 * - \ref view_mouse_tracking 0048 * - \ref view_modes 0049 * - \ref view_extensions 0050 * 0051 * \section view_intro Introduction 0052 * 0053 * The View class represents a single view of a KTextEditor::Document, 0054 * get the document on which the view operates with document(). 0055 * A view provides both the graphical representation of the text and the 0056 * KXMLGUIClient for the actions. The view itself does not provide 0057 * text manipulation, use the methods from the Document instead. The only 0058 * method to insert text is insertText(), which inserts the given text 0059 * at the current cursor position and emits the signal textInserted(). 0060 * 0061 * Usually a view is created by using Document::createView(). 0062 * Furthermore a view can have a context menu. Set it with setContextMenu() 0063 * and get it with contextMenu(). 0064 * 0065 * \section view_hook_into_gui Merging the View's GUI 0066 * 0067 * A View is derived from the class KXMLGUIClient, so its GUI elements (like 0068 * menu entries and toolbar items) can be merged into the application's GUI 0069 * (or into a KXMLGUIFactory) by calling 0070 * \code 0071 * // view is of type KTextEditor::View* 0072 * mainWindow()->guiFactory()->addClient( view ); 0073 * \endcode 0074 * You can add only one view as client, so if you have several views, you first 0075 * have to remove the current view, and then add the new one, like this 0076 * \code 0077 * mainWindow()->guiFactory()->removeClient( currentView ); 0078 * mainWindow()->guiFactory()->addClient( newView ); 0079 * \endcode 0080 * 0081 * \section view_selection Text Selection 0082 * 0083 * As the view is a graphical text editor it provides \e normal and \e block 0084 * text selection. You can check with selection() whether a selection exists. 0085 * removeSelection() will remove the selection without removing the text, 0086 * whereas removeSelectionText() also removes both, the selection and the 0087 * selected text. Use selectionText() to get the selected text and 0088 * setSelection() to specify the selected text range. The signal 0089 * selectionChanged() is emitted whenever the selection changed. 0090 * 0091 * \section view_cursors Cursor Positions 0092 * 0093 * A view has one Cursor which represents a line/column tuple. Two different 0094 * kinds of cursor positions are supported: first is the \e real cursor 0095 * position where a \e tab character only counts one character. Second is the 0096 * \e virtual cursor position, where a \e tab character counts as many 0097 * spaces as defined. Get the real position with cursorPosition() and the 0098 * virtual position with cursorPositionVirtual(). Set the real cursor 0099 * position with setCursorPosition(). The signal cursorPositionChanged() is 0100 * emitted whenever the cursor position changed. 0101 * 0102 * Screen coordinates of the current text cursor position in pixels are obtained 0103 * through cursorPositionCoordinates(). Further conversion of screen pixel 0104 * coordinates and text cursor positions are provided by cursorToCoordinate() 0105 * and coordinatesToCursor(). 0106 * 0107 * \section view_mouse_tracking Mouse Tracking 0108 * 0109 * It is possible to get notified via the signal mousePositionChanged() for 0110 * mouse move events, if mouseTrackingEnabled() returns \e true. Mouse tracking 0111 * can be turned on/off by calling setMouseTrackingEnabled(). If an editor 0112 * implementation does not support mouse tracking, mouseTrackingEnabled() will 0113 * always return \e false. 0114 * 0115 * \section view_modes Input/View Modes 0116 * 0117 * A view supports several input modes. Common input modes are 0118 * \e NormalInputMode and \e ViInputMode. Which input modes the editor supports depends on the 0119 * implementation. The getter viewInputMode() returns enum \InputMode representing the current mode. 0120 * 0121 * Input modes can have their own view modes. In case of default \e NormalInputMode those are 0122 * \e NormalModeInsert and \e NormalModeOverwrite. You can use viewMode() getter to obtain those. 0123 * 0124 * For viewMode() and viewInputMode() there are also variants with \e Human suffix, which 0125 * returns the human readable representation (i18n) usable for displaying in user interface. 0126 * 0127 * Whenever the input/view mode changes the signals 0128 * viewInputModeChanged()/viewModeChanged() are emitted. 0129 * 0130 * \section view_extensions View Extension Interfaces 0131 * 0132 * A simple view represents the text of a Document and provides a text cursor, 0133 * text selection, edit modes etc. 0134 * Advanced concepts like code completion and text hints are defined in the 0135 * extension interfaces. An KTextEditor implementation does not need to 0136 * support all the extensions. To implement the interfaces multiple 0137 * inheritance is used. 0138 * 0139 * More information about interfaces for the view can be found in 0140 * \ref kte_group_view_extensions. 0141 * 0142 * \see KTextEditor::Document, KTextEditor::CodeCompletionInterface, 0143 * KXMLGUIClient 0144 * \author Christoph Cullmann \<cullmann@kde.org\> 0145 */ 0146 class KTEXTEDITOR_EXPORT View : public QWidget, public KXMLGUIClient 0147 { 0148 Q_OBJECT 0149 0150 protected: 0151 /** 0152 * Constructor. 0153 * 0154 * Create a view attached to the widget \p parent. 0155 * 0156 * Pass it the internal implementation to store a d-pointer. 0157 * 0158 * \param impl d-pointer to use 0159 * \param parent parent widget 0160 * \see Document::createView() 0161 */ 0162 View(ViewPrivate *impl, QWidget *parent); 0163 0164 public: 0165 /** 0166 * Virtual destructor. 0167 */ 0168 ~View() override; 0169 0170 /* 0171 * Accessor for the document 0172 */ 0173 public: 0174 /** 0175 * Get the view's \e document, that means the view is a view of the 0176 * returned document. 0177 * \return the view's document 0178 */ 0179 virtual Document *document() const = 0; 0180 0181 /* 0182 * General information about this view 0183 */ 0184 public: 0185 /** 0186 * Possible input modes. 0187 * These correspond to various modes the text editor might be in. 0188 */ 0189 enum InputMode { 0190 NormalInputMode = 0, /**< Normal Mode. */ 0191 ViInputMode = 1 /**< Vi mode. The view will behave like the editor vi(m) */ 0192 }; 0193 0194 /** 0195 * Possible view modes 0196 * These correspond to various modes the text editor might be in. 0197 */ 0198 enum ViewMode { 0199 NormalModeInsert = 0, /**< Insert mode. Characters will be added. */ 0200 NormalModeOverwrite = 1, /**< Overwrite mode. Characters will be replaced. */ 0201 0202 ViModeNormal = 10, 0203 ViModeInsert = 11, 0204 ViModeVisual = 12, 0205 ViModeVisualLine = 13, 0206 ViModeVisualBlock = 14, 0207 ViModeReplace = 15 0208 }; 0209 0210 /** 0211 * Possible line types 0212 * \since 5.33 0213 */ 0214 enum LineType { 0215 RealLine = 0, /**< Real line */ 0216 VisibleLine = 1 /**< Visible line. Line that is not folded. */ 0217 }; 0218 /** 0219 * Get the current view mode/state. 0220 * This can be used to detect the view's current mode. For 0221 * example \NormalInputMode, \ViInputMode or whatever other input modes are 0222 * supported. \see viewModeHuman() for translated version. 0223 * \return current view mode/state 0224 * \see viewModeChanged() 0225 */ 0226 virtual ViewMode viewMode() const = 0; 0227 0228 /** 0229 * Get the current view mode state. 0230 * This can be used to visually indicate the view's current mode, for 0231 * example \e INSERT mode, \e OVERWRITE mode or \e COMMAND mode - or 0232 * whatever other edit modes are supported. The string should be 0233 * translated (i18n), as this is a user aimed representation of the view 0234 * state, which should be shown in the GUI, for example in the status bar. 0235 * This string may be rich-text. 0236 * \return Human-readable version of the view mode state 0237 * \see viewModeChanged() 0238 */ 0239 virtual QString viewModeHuman() const = 0; 0240 0241 /** 0242 * Set the view's new input mode. 0243 * \param inputMode new InputMode value 0244 * \see viewInputMode() 0245 * @since 5.54 0246 * KF6: make virtual 0247 */ 0248 void setViewInputMode(InputMode inputMode); 0249 0250 /** 0251 * Get the view's current input mode. 0252 * The current mode can be \NormalInputMode and \ViInputMode. 0253 * For human translated version \see viewInputModeHuman. 0254 * 0255 * \return the current input mode of this view 0256 * \see viewInputModeChanged() 0257 */ 0258 virtual InputMode viewInputMode() const = 0; 0259 0260 /** 0261 * Get the view's current input mode in human readable form. 0262 * The string should be translated (i18n). For id like version \see viewInputMode 0263 * 0264 * \return the current input mode of this view in human readable form 0265 */ 0266 virtual QString viewInputModeHuman() const = 0; 0267 0268 /** 0269 * Get the view's main window, if any 0270 * \return the view's main window, will always return at least some non-nullptr dummy interface 0271 */ 0272 virtual KTextEditor::MainWindow *mainWindow() const = 0; 0273 0274 /* 0275 * SIGNALS 0276 * following signals should be emitted by the editor view 0277 */ 0278 Q_SIGNALS: 0279 /** 0280 * This signal is emitted whenever the \p view gets the focus. 0281 * \param view view which gets focus 0282 * \see focusOut() 0283 */ 0284 void focusIn(KTextEditor::View *view); 0285 0286 /** 0287 * This signal is emitted whenever the \p view loses the focus. 0288 * \param view view which lost focus 0289 * \see focusIn() 0290 */ 0291 void focusOut(KTextEditor::View *view); 0292 0293 /** 0294 * This signal is emitted whenever the view mode of \p view changes. 0295 * \param view the view which changed its mode 0296 * \param mode new view mode 0297 * \see viewMode() 0298 */ 0299 void viewModeChanged(KTextEditor::View *view, KTextEditor::View::ViewMode mode); 0300 0301 /** 0302 * This signal is emitted whenever the \p view's input \p mode changes. 0303 * \param view view which changed its input mode 0304 * \param mode new input mode 0305 * \see viewInputMode() 0306 */ 0307 void viewInputModeChanged(KTextEditor::View *view, KTextEditor::View::InputMode mode); 0308 0309 /** 0310 * This signal is emitted from \p view whenever the users inserts \p text 0311 * at \p position, that means the user typed/pasted text. 0312 * \param view view in which the text was inserted 0313 * \param position position where the text was inserted 0314 * \param text the text the user has typed into the editor 0315 * \see insertText() 0316 */ 0317 void textInserted(KTextEditor::View *view, const KTextEditor::Cursor &position, const QString &text); 0318 0319 /* 0320 * Context menu handling 0321 */ 0322 public: 0323 /** 0324 * Set a context menu for this view to \p menu. 0325 * 0326 * \note any previously assigned menu is not deleted. If you are finished 0327 * with the previous menu, you may delete it. 0328 * 0329 * \warning Use this with care! Plugin xml gui clients are not merged 0330 * into this menu! 0331 * \warning !!!!!! DON'T USE THIS FUNCTION, UNLESS YOU ARE SURE YOU DON'T WANT PLUGINS TO WORK !!!!!! 0332 * 0333 * \param menu new context menu object for this view 0334 * \see contextMenu() 0335 */ 0336 virtual void setContextMenu(QMenu *menu) = 0; 0337 0338 /** 0339 * Get the context menu for this view. The return value can be NULL 0340 * if no context menu object was set and kxmlgui is not initialized yet. 0341 * If there is no user set menu, the kxmlgui menu is returned. Do not delete this menu, if 0342 * if it is the xmlgui menu. 0343 * \return context menu object 0344 * \see setContextMenu() 0345 */ 0346 virtual QMenu *contextMenu() const = 0; 0347 0348 /** 0349 * Populate \a menu with default text editor actions. If \a menu is 0350 * null, a menu will be created with the view as its parent. 0351 * 0352 * \note to use this menu, you will next need to call setContextMenu(), 0353 * as this does not assign the new context menu. 0354 * 0355 * \warning This contains only basic options from the editor component 0356 * (katepart). Plugins are \p not merged/integrated into it! 0357 * If you want to be a better citizen and take full advantage 0358 * of KTextEditor plugins do something like: 0359 * \code 0360 * KXMLGUIClient* client = view; 0361 * // search parent XmlGuiClient 0362 * while (client->parentClient()) { 0363 * client = client->parentClient(); 0364 * } 0365 * 0366 * if (client->factory()) { 0367 * const QList<QWidget*> menuContainers = client->factory()->containers("menu"); 0368 * for (QWidget *w : menuContainers) { 0369 * if (w->objectName() == "ktexteditor_popup") { 0370 * // do something with the menu (ie adding an onshow handler) 0371 * break; 0372 * } 0373 * } 0374 * } 0375 * \endcode 0376 * \warning or simply use the aboutToShow, aboutToHide signals !!!!! 0377 * 0378 * \param menu the menu to be populated, or null to create a new menu. 0379 * \return the menu, whether created or passed initially 0380 */ 0381 virtual QMenu *defaultContextMenu(QMenu *menu = nullptr) const = 0; 0382 0383 Q_SIGNALS: 0384 /** 0385 * Signal which is emitted immediately prior to showing the current 0386 * context \a menu. 0387 */ 0388 void contextMenuAboutToShow(KTextEditor::View *view, QMenu *menu); 0389 0390 /* 0391 * Cursor handling 0392 */ 0393 public: 0394 /** 0395 * Set the view's new cursor to \p position. A \e TAB character 0396 * is handled as only on character. 0397 * \param position new cursor position 0398 * \return \e true on success, otherwise \e false 0399 * \see cursorPosition() 0400 */ 0401 virtual bool setCursorPosition(Cursor position) = 0; 0402 0403 /** 0404 * Set the view's new cursors to \p positions. A \e TAB character 0405 * is handled as only on character. 0406 * 0407 * This allows to create multiple cursors in this view. 0408 * 0409 * The first passed position will be used for the primary cursor 0410 * just like if you would call \ref setCursorPosition. 0411 * 0412 * \param positions new cursor positions 0413 * \see cursorPositions() 0414 * 0415 * @since 5.95 0416 */ 0417 void setCursorPositions(const QVector<KTextEditor::Cursor> &positions); 0418 0419 /** 0420 * Get the view's current cursor position. A \e TAB character is 0421 * handled as only one character. 0422 * \return current cursor position 0423 * \see setCursorPosition() 0424 */ 0425 virtual Cursor cursorPosition() const = 0; 0426 0427 /** 0428 * Get the view's current cursor positions. A \e TAB character is 0429 * handled as only one character. 0430 * 0431 * The returned vector contains the primary cursor as first element. 0432 * 0433 * @since 5.95 0434 * 0435 * \return all currently existing cursors 0436 */ 0437 QVector<KTextEditor::Cursor> cursorPositions() const; 0438 0439 /** 0440 * Get the current \e virtual cursor position, \e virtual means the 0441 * tabulator character (TAB) counts \e multiple characters, as configured 0442 * by the user (e.g. one TAB is 8 spaces). The virtual cursor 0443 * position provides access to the user visible values of the current 0444 * cursor position. 0445 * 0446 * \return virtual cursor position 0447 * \see cursorPosition() 0448 */ 0449 virtual Cursor cursorPositionVirtual() const = 0; 0450 0451 /** 0452 * Get the screen coordinates (x, y) of the supplied \a cursor relative 0453 * to the view widget in pixels. Thus, (0, 0) represents the top left hand 0454 * of the view widget. 0455 * 0456 * To map pixel coordinates to a Cursor position (the reverse transformation) 0457 * use coordinatesToCursor(). 0458 * 0459 * \param cursor cursor to determine coordinate for. 0460 * \return cursor screen coordinates relative to the view widget 0461 * 0462 * \see cursorPositionCoordinates(), coordinatesToCursor() 0463 */ 0464 virtual QPoint cursorToCoordinate(const KTextEditor::Cursor &cursor) const = 0; 0465 0466 /** 0467 * Get the screen coordinates (x, y) of the cursor position in pixels. 0468 * The returned coordinates are relative to the View such that (0, 0) 0469 * represents tht top-left corner of the View. 0470 * 0471 * If global screen coordinates are required, e.g. for showing a QToolTip, 0472 * convert the view coordinates to global screen coordinates as follows: 0473 * \code 0474 * QPoint viewCoordinates = view->cursorPositionCoordinates(); 0475 * QPoint globalCoorinates = view->mapToGlobal(viewCoordinates); 0476 * \endcode 0477 * \return cursor screen coordinates 0478 * \see cursorToCoordinate(), coordinatesToCursor() 0479 */ 0480 virtual QPoint cursorPositionCoordinates() const = 0; 0481 0482 /** 0483 * Get the text-cursor in the document from the screen coordinates, 0484 * relative to the view widget. 0485 * 0486 * To map a cursor to pixel coordinates (the reverse transformation) 0487 * use cursorToCoordinate(). 0488 * 0489 * \param coord coordinates relative to the view widget 0490 * \return cursor in the View, that points onto the character under 0491 * the given coordinate. May be KTextEditor::Cursor::invalid(). 0492 */ 0493 virtual KTextEditor::Cursor coordinatesToCursor(const QPoint &coord) const = 0; 0494 0495 /* 0496 * SIGNALS 0497 * following signals should be emitted by the editor view 0498 * if the cursor position changes 0499 */ 0500 Q_SIGNALS: 0501 /** 0502 * This signal is emitted whenever the \p view's cursor position changed. 0503 * \param view view which emitted the signal 0504 * \param newPosition new position of the cursor (Kate will pass the real 0505 * cursor position, not the virtual) 0506 * \see cursorPosition(), cursorPositionVirtual() 0507 */ 0508 void cursorPositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPosition); 0509 0510 /** 0511 * This signal should be emitted whenever the \p view is scrolled vertically. 0512 * \param view view which emitted the signal 0513 * \param newPos the new scroll position 0514 */ 0515 void verticalScrollPositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPos); 0516 0517 /** 0518 * This signal should be emitted whenever the \p view is scrolled horizontally. 0519 * \param view view which emitted the signal 0520 */ 0521 void horizontalScrollPositionChanged(KTextEditor::View *view); 0522 /* 0523 * Mouse position 0524 */ 0525 public: 0526 /** 0527 * Check, whether mouse tracking is enabled. 0528 * 0529 * Mouse tracking is required to have the signal mousePositionChanged() 0530 * emitted. 0531 * \return \e true, if mouse tracking is enabled, otherwise \e false 0532 * \see setMouseTrackingEnabled(), mousePositionChanged() 0533 */ 0534 virtual bool mouseTrackingEnabled() const = 0; 0535 0536 /** 0537 * Try to enable or disable mouse tracking according to \p enable. 0538 * The return value contains the state of mouse tracking \e after the 0539 * request. Mouse tracking is required to have the mousePositionChanged() 0540 * signal emitted. 0541 * 0542 * \note Implementation Notes: An implementation is not forced to support 0543 * this, and should always return \e false if it does not have 0544 * support. 0545 * 0546 * \param enable if \e true, try to enable mouse tracking, otherwise disable 0547 * it. 0548 * \return the current state of mouse tracking 0549 * \see mouseTrackingEnabled(), mousePositionChanged() 0550 */ 0551 virtual bool setMouseTrackingEnabled(bool enable) = 0; 0552 0553 Q_SIGNALS: 0554 /** 0555 * This signal is emitted whenever the position of the mouse changes over 0556 * this \a view. If the mouse moves off the view, an invalid cursor position 0557 * should be emitted, i.e. Cursor::invalid(). 0558 * \note If mouseTrackingEnabled() returns \e false, this signal is never 0559 * emitted. 0560 * \param view view which emitted the signal 0561 * \param newPosition new position of the mouse or Cursor::invalid(), if the 0562 * mouse moved out of the \p view. 0563 * \see mouseTrackingEnabled() 0564 */ 0565 void mousePositionChanged(KTextEditor::View *view, const KTextEditor::Cursor &newPosition); 0566 0567 /* 0568 * Selection methods. 0569 * This deals with text selection and copy&paste 0570 */ 0571 public: 0572 /** 0573 * Set the view's selection to the range \p selection. 0574 * The old selection will be discarded. 0575 * \param range the range of the new selection 0576 * \return \e true on success, otherwise \e false (e.g. when the cursor 0577 * range is invalid) 0578 * \see selectionRange(), selection() 0579 */ 0580 virtual bool setSelection(const Range &range) = 0; 0581 0582 /** 0583 * Set the view's selection to the range \p selection. 0584 * The old selection will be discarded. 0585 * \param ranges the ranges of the new selections 0586 * \see selectionRanges(), selection() 0587 * 0588 * @since 5.95 0589 */ 0590 void setSelections(const QVector<KTextEditor::Range> &ranges); 0591 0592 /** 0593 * Query the view whether it has selected text, i.e. whether a selection 0594 * exists. 0595 * \return \e true if a text selection exists, otherwise \e false 0596 * \see setSelection(), selectionRange() 0597 */ 0598 virtual bool selection() const = 0; 0599 0600 /** 0601 * Get the range occupied by the current selection. 0602 * \return selection range, valid only if a selection currently exists. 0603 * \see setSelection() 0604 */ 0605 virtual Range selectionRange() const = 0; 0606 0607 /** 0608 * Get the ranges occupied by the current selections. 0609 * \return selection ranges, valid only if a selection currently exists. 0610 * \see setSelections() 0611 * 0612 * @since 5.95 0613 */ 0614 QVector<KTextEditor::Range> selectionRanges() const; 0615 0616 /** 0617 * Get the view's selected text. 0618 * \return the selected text 0619 * \see setSelection() 0620 */ 0621 virtual QString selectionText() const = 0; 0622 0623 /** 0624 * Remove the view's current selection, \e without deleting the selected 0625 * text. 0626 * \return \e true on success, otherwise \e false 0627 * \see removeSelectionText() 0628 */ 0629 virtual bool removeSelection() = 0; 0630 0631 /** 0632 * Remove the view's current selection \e including the selected text. 0633 * \return \e true on success, otherwise \e false 0634 * \see removeSelection() 0635 */ 0636 virtual bool removeSelectionText() = 0; 0637 0638 /* 0639 * Blockselection stuff 0640 */ 0641 public: 0642 /** 0643 * Set block selection mode to state \p on. 0644 * \param on if \e true, block selection mode is turned on, otherwise off 0645 * \return \e true on success, otherwise \e false 0646 * \see blockSelection() 0647 */ 0648 virtual bool setBlockSelection(bool on) = 0; 0649 0650 /** 0651 * Get the status of the selection mode. \e true indicates that block 0652 * selection mode is on. If this is \e true, selections applied via the 0653 * SelectionInterface are handled as block selections and the Copy&Paste 0654 * functions work on rectangular blocks of text rather than normal. 0655 * \return \e true, if block selection mode is enabled, otherwise \e false 0656 * \see setBlockSelection() 0657 */ 0658 virtual bool blockSelection() const = 0; 0659 0660 /* 0661 * SIGNALS 0662 * following signals should be emitted by the editor view for selection 0663 * handling. 0664 */ 0665 Q_SIGNALS: 0666 /** 0667 * This signal is emitted whenever the \p view's selection changes. 0668 * \note If the mode switches from block selection to normal selection 0669 * or vice versa this signal should also be emitted. 0670 * \param view view in which the selection changed 0671 * \see selection(), selectionRange(), selectionText() 0672 */ 0673 void selectionChanged(KTextEditor::View *view); 0674 0675 public: 0676 /** 0677 * This is a convenience function which inserts \p text at the view's 0678 * current cursor position. You do not necessarily need to reimplement 0679 * it, except you want to do some special things. 0680 * \param text Text to be inserted 0681 * \return \e true on success of insertion, otherwise \e false 0682 * \see textInserted() 0683 */ 0684 virtual bool insertText(const QString &text); 0685 0686 /** 0687 * Insert a template into the document. The template can have editable fields 0688 * which can be filled by the user. You can create editable fields 0689 * with ${fieldname}; multiple fields with the same name will have their 0690 * contents synchronized automatically, and only the first one is editable 0691 * in this case. 0692 * Fields can have a default value specified by writing ${fieldname=default}. 0693 * Note that `default' is a JavaScript expression and strings need to be quoted. 0694 * You can also provide a piece of JavaScript for more complex logic. 0695 * To create a field which provides text based on a JS function call and the values 0696 * of the other, editable fields, use the ${func()} syntax. func() must be a callable 0697 * object defined in @p script. You can pass arguments to the function by just 0698 * writing any constant expression or a field name. 0699 * \param insertPosition where to insert the template 0700 * \param templateString template to insert using the above syntax 0701 * \param script script with functions which can be used in @p templateScript 0702 * \return true on success, false if insertion failed (e.g. read-only mode) 0703 */ 0704 bool insertTemplate(const KTextEditor::Cursor &insertPosition, const QString &templateString, const QString &script = QString()); 0705 0706 /** 0707 * Scroll view to cursor. 0708 * 0709 * \param cursor the cursor position to scroll to. 0710 * 0711 * \since 5.33 0712 */ 0713 void setScrollPosition(KTextEditor::Cursor &cursor); 0714 0715 /** 0716 * Horizontally scroll view to position. 0717 * 0718 * \param x the pixel position to scroll to. 0719 * 0720 * \since 5.33 0721 */ 0722 void setHorizontalScrollPosition(int x); 0723 0724 /** 0725 * Get the cursor corresponding to the maximum position 0726 * the view can vertically scroll to. 0727 * 0728 * \return cursor position of the maximum vertical scroll position. 0729 * 0730 * \since 5.33 0731 */ 0732 KTextEditor::Cursor maxScrollPosition() const; 0733 0734 /** 0735 * Get the first displayed line in the view. 0736 * 0737 * \note If code is folded, many hundred lines can be 0738 * between firstDisplayedLine() and lastDisplayedLine(). 0739 * 0740 * \param lineType if RealLine (the default), it returns the real line number 0741 * accounting for folded regions. In that case it walks over all folded 0742 * regions 0743 * O(n) for n == number of folded ranges 0744 * \return the first displayed line 0745 * 0746 * \see lastDisplayedLine() 0747 * \since 5.33 0748 */ 0749 int firstDisplayedLine(LineType lineType = RealLine) const; 0750 0751 /** 0752 * Get the last displayed line in the view. 0753 * 0754 * \note If code is folded, many hundred lines can be 0755 * between firstDisplayedLine() and lastDisplayedLine(). 0756 * 0757 * \param lineType if RealLine (the default), it returns the real line number 0758 * accounting for folded regions. In that case it walks over all folded 0759 * regions 0760 * O(n) for n == number of folded ranges 0761 * \return the last displayed line 0762 * 0763 * \see firstDisplayedLine() 0764 * \since 5.33 0765 */ 0766 int lastDisplayedLine(LineType lineType = RealLine) const; 0767 0768 /** 0769 * Get the view's text area rectangle excluding border, scrollbars, etc. 0770 * 0771 * \return the view's text area rectangle 0772 * 0773 * \since 5.33 0774 */ 0775 QRect textAreaRect() const; 0776 0777 public: 0778 /** 0779 * Print the document. This should result in showing the print dialog. 0780 * 0781 * @returns true if document was printed 0782 */ 0783 virtual bool print() = 0; 0784 0785 /** 0786 * Shows the print preview dialog/ 0787 */ 0788 virtual void printPreview() = 0; 0789 0790 /** 0791 * Is the status bar enabled? 0792 * 0793 * @return status bar enabled? 0794 */ 0795 bool isStatusBarEnabled() const; 0796 0797 /** 0798 * Show/hide the status bar of the view. 0799 * Per default, the status bar is enabled. 0800 * 0801 * @param enable should the status bar be enabled? 0802 */ 0803 void setStatusBarEnabled(bool enable); 0804 0805 Q_SIGNALS: 0806 /** 0807 * This signal is emitted whenever the status bar of \p view is toggled. 0808 * 0809 * @param enabled Whether the status bar is currently enabled or not 0810 */ 0811 void statusBarEnabledChanged(KTextEditor::View *view, bool enabled); 0812 0813 public: 0814 /** 0815 * Read session settings from the given \p config. 0816 * 0817 * Known flags: 0818 * none atm 0819 * 0820 * \param config read the session settings from this KConfigGroup 0821 * \param flags additional flags 0822 * \see writeSessionConfig() 0823 */ 0824 virtual void readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0; 0825 0826 /** 0827 * Write session settings to the \p config. 0828 * See readSessionConfig() for more details. 0829 * 0830 * \param config write the session settings to this KConfigGroup 0831 * \param flags additional flags 0832 * \see readSessionConfig() 0833 */ 0834 virtual void writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>()) = 0; 0835 0836 public: 0837 /** 0838 * Returns the attribute for the default style \p defaultStyle. 0839 * @param defaultStyle default style to get the attribute for 0840 * @see KTextEditor::Attribute 0841 */ 0842 virtual KTextEditor::Attribute::Ptr defaultStyleAttribute(KTextEditor::DefaultStyle defaultStyle) const = 0; 0843 0844 /** 0845 * Get the list of AttributeBlocks for a given \p line in the document. 0846 * 0847 * \return list of AttributeBlocks for given \p line. 0848 */ 0849 virtual QList<KTextEditor::AttributeBlock> lineAttributes(int line) = 0; 0850 0851 Q_SIGNALS: 0852 /** 0853 * This signal is emitted whenever the current view configuration is changed. 0854 * 0855 * \param view the view which's config has changed 0856 * 0857 * \since 5.79 0858 */ 0859 void configChanged(KTextEditor::View *view); 0860 0861 public: 0862 /** 0863 * Get the current active theme of this view. 0864 * Might change during runtime, configChanged() will be emitted in that cases. 0865 * 0866 * \return current active theme 0867 * 0868 * \since 5.79 0869 */ 0870 KSyntaxHighlighting::Theme theme() const; 0871 0872 private: 0873 /** 0874 * private d-pointer, pointing to the internal implementation 0875 */ 0876 ViewPrivate *const d; 0877 }; 0878 0879 } 0880 0881 #endif