// view is of type KTextEditor::View*
mainWindow()->guiFactory()->addClient( view );

mainWindow()->guiFactory()->removeClient( currentView );
mainWindow()->guiFactory()->addClient( newView );

Member Function Documentation

[protected] View::View(KTextEditor::ViewPrivate *impl, QWidget *parent)

Constructor.

Create a view attached to the widget parent.

Pass it the internal implementation to store a d-pointer.

impl is the d-pointer to use

parent is the parent widget

See also Document::createView().

[override virtual noexcept] View::~View()

Virtual destructor.

[pure virtual] void View::abortCompletion()

Abort the currently displayed code completion without executing any currently selected completion. This is safe, even when the completion box is not currently active.

See also isCompletionActive().

[signal] void View::annotationActivated(KTextEditor::View *view, int line)

This signal is emitted when an entry on the annotation border was activated, for example by clicking or double-clicking it. This follows the KDE wide setting for activation via click or double-clcik

view is the view to which the activated border belongs to

line is the document line that the activated position belongs to

[signal] void View::annotationBorderVisibilityChanged(KTextEditor::View *view, bool visible)

This signal is emitted when the annotation border is shown or hidden.

view is the view to which the border belongs to

visible is the current visibility state

[signal] void View::annotationContextMenuAboutToShow(KTextEditor::View *view, QMenu *menu, int line)

This signal is emitted before a context menu is shown on the annotation border for the given line and view.

view is the view that the annotation border belongs to

menu is the context menu that will be shown

line is the annotated line for which the context menu is shown

[pure virtual, since 6.0] KTextEditor::AbstractAnnotationItemDelegate *View::annotationItemDelegate() const

Returns the currently used AbstractAnnotationItemDelegate

Returns the current AbstractAnnotationItemDelegate

This function was introduced in 6.0.

See also setAnnotationItemDelegate().

[pure virtual] KTextEditor::AnnotationModel *View::annotationModel() const

Returns the currently set AnnotationModel or 0 if there's none set

See also setAnnotationModel().

[pure virtual] bool View::blockSelection() const

Get the status of the selection mode. true indicates that block selection mode is on. If this is true, selections applied via the SelectionInterface are handled as block selections and the Copy&Paste functions work on rectangular blocks of text rather than normal.

Returns true, if block selection mode is enabled, otherwise false

See also setBlockSelection().

[pure virtual] QList<KTextEditor::CodeCompletionModel *> View::codeCompletionModels() const

Obtain the list of registered code completion models.

Returns a list of a models that are currently registered

See also registerCompletionModel(CodeCompletionModel*).

[signal, since 5.79] void View::configChanged(KTextEditor::View *view)

This signal is emitted whenever the current view configuration is changed.

view is the view whose config has changed

This function was introduced in 5.79.

[pure virtual] QStringList View::configKeys() const

Get a list of all available keys.

[pure virtual] QVariant View::configValue(const QString &key)

Get a value for the key.

See also setConfigValue().

[pure virtual] QMenu *View::contextMenu() const

Get the context menu for this view. The return value can be NULL if no context menu object was set and kxmlgui is not initialized yet. If there is no user set menu, the kxmlgui menu is returned. Do not delete this menu, if if it is the xmlgui menu.

Returns context menu object

See also setContextMenu().

[signal] void View::contextMenuAboutToShow(KTextEditor::View *view, QMenu *menu)

Signal which is emitted immediately prior to showing the current context menu.

view is the related view

[pure virtual] KTextEditor::Cursor View::coordinatesToCursor(const QPoint &coord) const

Get the text-cursor in the document from the screen coordinates, relative to the view widget.

To map a cursor to pixel coordinates (the reverse transformation) use cursorToCoordinate().

coord is the coordinates relative to the view widget

Returns cursor in the View, that points onto the character under the given coordinate. May be KTextEditor::Cursor::invalid().

[pure virtual] KTextEditor::Cursor View::cursorPosition() const

Get the view's current cursor position. A TAB character is handled as only one character.

Returns current cursor position

See also setCursorPosition().

[signal] void View::cursorPositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPosition)

This signal is emitted whenever the view's cursor position changed.

view is the view which emitted the signal

newPosition is the new position of the cursor (Kate will pass the real cursor position, not the virtual)

See also cursorPosition() and cursorPositionVirtual().

[pure virtual] QPoint View::cursorPositionCoordinates() const

Get the screen coordinates (x, y) of the cursor position in pixels. The returned coordinates are relative to the View such that (0, 0) represents tht top-left corner of the View.

If global screen coordinates are required, e.g. for showing a QToolTip, convert the view coordinates to global screen coordinates as follows:

QPoint viewCoordinates = view->cursorPositionCoordinates();
QPoint globalCoorinates = view->mapToGlobal(viewCoordinates);

Returns cursor screen coordinates

See also cursorToCoordinate() and coordinatesToCursor().

[pure virtual] KTextEditor::Cursor View::cursorPositionVirtual() const

Get the current virtual cursor position, virtual means the tabulator character (TAB) counts multiple characters, as configured by the user (e.g. one TAB is 8 spaces). The virtual cursor position provides access to the user visible values of the current cursor position.

Returns virtual cursor position

See also cursorPosition().

[since 5.95] QList<KTextEditor::Cursor> View::cursorPositions() const

Get the view's current cursor positions. A TAB character is handled as only one character.

The returned vector contains the primary cursor as first element.

Returns all currently existing cursors

This function was introduced in 5.95.

See also setCursorPositions().

[pure virtual] QPoint View::cursorToCoordinate(KTextEditor::Cursor cursor) const

Get the screen coordinates (x, y) of the supplied cursor relative to the view widget in pixels. Thus, (0, 0) represents the top left hand of the view widget.

To map pixel coordinates to a Cursor position (the reverse transformation) use coordinatesToCursor().

cursor is the cursor to determine coordinate for.

Returns cursor screen coordinates relative to the view widget

See also cursorPositionCoordinates() and coordinatesToCursor().

[pure virtual] QMenu *View::defaultContextMenu(QMenu *menu = nullptr) const

Populate menu with default text editor actions. If menu is null, a menu will be created with the view as its parent.

KXMLGUIClient* client = view;
// search parent XmlGuiClient
while (client->parentClient()) {
  client = client->parentClient();
}

if (client->factory()) {
  const QList<QWidget*> menuContainers = client->factory()->containers("menu");
  for (QWidget *w : menuContainers) {
    if (w->objectName() == "ktexteditor_popup") {
      // do something with the menu (ie adding an onshow handler)
      break;
    }
  }
}

menu is the menu to be populated, or null to create a new menu.

Returns the menu, whether created or passed initially

[pure virtual] QExplicitlySharedDataPointer<KTextEditor::Attribute> View::defaultStyleAttribute(KSyntaxHighlighting::Theme::TextStyle defaultStyle) const

Returns the attribute for the default style defaultStyle.

defaultStyle default style to get the attribute for

See also KTextEditor::Attribute.

[pure virtual] KTextEditor::Document *View::document() const

Get the view's document, that means the view is a view of the returned document. Returns the view's document

[since 5.33] int View::firstDisplayedLine(KTextEditor::View::LineType lineType = RealLine) const

Get the first displayed line in the view.

lineType if RealLine (the default), it returns the real line number accounting for folded regions. In that case it walks over all folded regions O(n) for n == number of folded ranges

Returns the first displayed line

This function was introduced in 5.33.

See also lastDisplayedLine().

[signal] void View::focusIn(KTextEditor::View *view)

This signal is emitted whenever the view gets the focus.

view is the view which gets focus

See also focusOut().

[signal] void View::focusOut(KTextEditor::View *view)

This signal is emitted whenever the view loses the focus.

view is view which lost focus

See also focusIn().

[pure virtual] void View::forceCompletion()

Force execution of the currently selected completion, and hide the code completion box.

[pure virtual, since 6.0] QScrollBar *View::horizontalScrollBar() const

Returns The horizontal scrollbar of this view

This function was introduced in 6.0.

[signal] void View::horizontalScrollPositionChanged(KTextEditor::View *view)

This signal should be emitted whenever the view is scrolled horizontally.

view is the view which emitted the signal

bool View::insertTemplate(KTextEditor::Cursor insertPosition, const QString &templateString, const QString &script = QString())

Insert a template into the document. The template can have editable fields which can be filled by the user. You can create editable fields with ${fieldname}; multiple fields with the same name will have their contents synchronized automatically, and only the first one is editable in this case. Fields can have a default value specified by writing ${fieldname=default}. Note that `default' is a JavaScript expression and strings need to be quoted. You can also provide a piece of JavaScript for more complex logic. To create a field which provides text based on a JS function call and the values of the other, editable fields, use the ${func()} syntax. func() must be a callable object defined in script. You can pass arguments to the function by just writing any constant expression or a field name.

insertPosition is where to insert the template

templateString is the template to insert using the above syntax

script is a script with functions which can be used in templateString

Returns true on success, false if insertion failed (e.g. read-only mode)

[virtual] bool View::insertText(const QString &text)

This is a convenience function which inserts text at the view's current cursor position. You do not necessarily need to reimplement it, except you want to do some special things.

text is the text to be inserted

Returns true on success of insertion, otherwise false

See also textInserted().

[pure virtual] bool View::isAnnotationBorderVisible() const

Returns true if he View's annotation border is visible.

[pure virtual] bool View::isAutomaticInvocationEnabled() const

Returns true if automatic code completion invocation is enabled.

[pure virtual] bool View::isCompletionActive() const

Returns true if the code completion box is currently displayed.

bool View::isStatusBarEnabled() const

Is the status bar enabled?

Returns status bar enabled?

[since 5.33] int View::lastDisplayedLine(KTextEditor::View::LineType lineType = RealLine) const

Get the last displayed line in the view.

lineType is if RealLine (the default), it returns the real line number accounting for folded regions. In that case it walks over all folded regions. O(n) for n == number of folded ranges

Returns the last displayed line

This function was introduced in 5.33.

See also firstDisplayedLine().

[pure virtual] QList<KTextEditor::AttributeBlock> View::lineAttributes(int line)

Get the list of AttributeBlocks for a given line in the document.

Returns list of AttributeBlocks for given line.

[pure virtual] KTextEditor::MainWindow *View::mainWindow() const

Get the view's main window, if any

Returns the view's main window, will always return at least some non-nullptr dummy interface

[since 5.33] KTextEditor::Cursor View::maxScrollPosition() const

Get the cursor corresponding to the maximum position the view can vertically scroll to.

Returns cursor position of the maximum vertical scroll position.

This function was introduced in 5.33.

[signal] void View::mousePositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPosition)

This signal is emitted whenever the position of the mouse changes over this view. If the mouse moves off the view, an invalid cursor position should be emitted, i.e. Cursor::invalid().

view is the view which emitted the signal

newPosition is the new position of the mouse or Cursor::invalid(), if the mouse moved out of the view.

See also mouseTrackingEnabled().

[pure virtual] bool View::mouseTrackingEnabled() const

Check, whether mouse tracking is enabled.

Mouse tracking is required to have the signal mousePositionChanged() emitted.

Returns true, if mouse tracking is enabled, otherwise false

See also setMouseTrackingEnabled() and mousePositionChanged().

[pure virtual] bool View::print()

Print the document. This should result in showing the print dialog.

Returns true if document was printed

[pure virtual] void View::printPreview()

Shows the print preview dialog/

[pure virtual] void View::readSessionConfig(const KConfigGroup &config, const QSet<QString> &flags = QSet<QString>())

Read session settings from the given config.

Known flags: none atm

config is the KConfigGroup to read the session settings from

flags is additional flags

See also writeSessionConfig().

[pure virtual] void View::registerCompletionModel(KTextEditor::CodeCompletionModel *model)

Register a new code completion model.

model is new completion model

See also unregisterCompletionModel().

[pure virtual] void View::registerInlineNoteProvider(KTextEditor::InlineNoteProvider *provider)

Register the inline note provider provider.

Whenever a line is painted, the provider will be queried for notes that should be painted in it. When the provider is about to be destroyed, make sure to call unregisterInlineNoteProvider() to avoid a dangling pointer.

provider inline note provider

See also unregisterInlineNoteProvider() and KTextEditor::InlineNoteProvider.

[pure virtual] void View::registerTextHintProvider(KTextEditor::TextHintProvider *provider)

Register the text hint provider provider.

Whenever the user hovers over text, provider will be asked for a text hint. When the provider is about to be destroyed, make sure to call unregisterTextHintProvider() to avoid a dangling pointer.

provider text hint provider

See also unregisterTextHintProvider() and KTextEditor::TextHintProvider.

[pure virtual] bool View::removeSelection()

Remove the view's current selection, without deleting the selected text.

Returns true on success, otherwise false

See also removeSelectionText().

[pure virtual] bool View::removeSelectionText()

Remove the view's current selection including the selected text.

Returns true on success, otherwise false

See also removeSelection().

[pure virtual] bool View::selection() const

Query the view whether it has selected text, i.e. whether a selection exists.

Returns true if a text selection exists, otherwise false

See also setSelection() and selectionRange().

[signal] void View::selectionChanged(KTextEditor::View *view)

This signal is emitted whenever the view's selection changes.

view is the view in which the selection changed

See also selection(), selectionRange(), and selectionText().

[pure virtual] KTextEditor::Range View::selectionRange() const

Get the range occupied by the current selection.

Returns selection range, valid only if a selection currently exists.

See also setSelection().

[since 5.95] QList<KTextEditor::Range> View::selectionRanges() const

Get the ranges occupied by the current selections.

Returns selection ranges, valid only if a selection currently exists.

This function was introduced in 5.95.

See also setSelections().

[pure virtual] QString View::selectionText() const

Get the view's selected text.

Returns the selected text

See also setSelection().

[pure virtual] void View::setAnnotationBorderVisible(bool visible)

This function can be used to show or hide the annotation border The annotation border is hidden by default.

visible if true the annotation border is shown, otherwise hidden

See also isAnnotationBorderVisible().

[pure virtual, since 6.0] void View::setAnnotationItemDelegate(KTextEditor::AbstractAnnotationItemDelegate *delegate)

Sets the AbstractAnnotationItemDelegate for this view and the model to provide custom rendering of annotation information for each line. Ownership is not transferred.

delegate is the new AbstractAnnotationItemDelegate, or nullptr to reset to the default delegate

This function was introduced in 6.0.

See also annotationItemDelegate().

[pure virtual] void View::setAnnotationModel(KTextEditor::AnnotationModel *model)

Sets a new AnnotationModel for this document to provide annotation information for each line.

model is the new AnnotationModel

See also annotationModel().

[pure virtual, since 6.0] void View::setAnnotationUniformItemSizes(bool uniformItemSizes)

This function can be used to declare whether it is known that the annotation items rendered by the set delegate all have the same size. This enables the view to do some optimizations for performance purposes.

By default the value of this property is false .

uniformItemSizes if true the annotation items are considered to all have the same size

This function was introduced in 6.0.

[pure virtual] void View::setAutomaticInvocationEnabled(bool enabled = true)

Enable (if enabled is true) or disable automatic code completion invocation.

See also isAutomaticInvocationEnabled().

[pure virtual] bool View::setBlockSelection(bool on)

Set block selection mode to state on.

on if true, block selection mode is turned on, otherwise off

Returns true on success, otherwise false

See also blockSelection().

[pure virtual] void View::setConfigValue(const QString &key, const QVariant &value)

Set a the key's value to value.

See also configValue().

[pure virtual] void View::setContextMenu(QMenu *menu)

Set a context menu for this view to menu.

menu is the new context menu object for this view

See also contextMenu().

[pure virtual] bool View::setCursorPosition(KTextEditor::Cursor position)

Set the view's new cursor to position. A TAB character is handled as only on character.

position is the new cursor position

Returns true on success, otherwise false

See also cursorPosition().

[since 5.95] void View::setCursorPositions(const QList<KTextEditor::Cursor> &positions)

Set the view's new cursors to positions. A TAB character is handled as only on character.

This allows to create multiple cursors in this view.

The first passed position will be used for the primary cursor just like if you would call setCursorPosition().

positions is the new cursor positions

This function was introduced in 5.95.

See also cursorPositions().

[since 5.33] void View::setHorizontalScrollPosition(int x)

Horizontally scroll view to position.

x is the pixel position to scroll to.

This function was introduced in 5.33.

[pure virtual] bool View::setMouseTrackingEnabled(bool enable)

Try to enable or disable mouse tracking according to enable. The return value contains the state of mouse tracking after the request. Mouse tracking is required to have the mousePositionChanged() signal emitted.

enable if true, try to enable mouse tracking, otherwise disable it.

Returns the current state of mouse tracking

See also mouseTrackingEnabled() and mousePositionChanged().

[since 5.33] void View::setScrollPosition(KTextEditor::Cursor cursor)

Scroll view to cursor.

cursor is the cursor position to scroll to.

This function was introduced in 5.33.

[pure virtual] bool View::setSelection(KTextEditor::Range range)

Set the view's selection to the range selection. The old selection will be discarded.

range is the range of the new selection

Returns true on success, otherwise false (e.g. when the cursor range is invalid)

See also selectionRange() and selection().

[since 5.95] void View::setSelections(const QList<KTextEditor::Range> &ranges)

Set the view's selections to the ranges selection. The old selection will be discarded.

ranges is the ranges of the new selections

This function was introduced in 5.95.

See also selectionRanges() and selection().

void View::setStatusBarEnabled(bool enable)

Show/hide the status bar of the view. Per default, the status bar is enabled.

enable should the status bar be enabled?

See also isStatusBarEnabled().

[pure virtual] void View::setTextHintDelay(int delay)

Set the text hint delay to delay milliseconds.

The delay specifies the time the user needs to hover over the text before the tool tip is shown. Therefore, delay should not be too large, a value of 500 milliseconds is recommended and set by default.

If delay is <= 0, the default delay will be set.

delay is the tool tip delay in milliseconds

See also textHintDelay().

[pure virtual, since 5.54] void View::setViewInputMode(KTextEditor::View::InputMode inputMode)

Set the view's new input mode.

inputMode is new InputMode value

This function was introduced in 5.54.

See also viewInputMode().

[pure virtual] void View::startCompletion(KTextEditor::Range word, KTextEditor::CodeCompletionModel *model)

Invoke code completion over a given range word with a specific model.

[pure virtual] void View::startCompletion(const KTextEditor::Range &word, const QList<KTextEditor::CodeCompletionModel *> &models = QList<CodeCompletionModel *>(), KTextEditor::CodeCompletionModel::InvocationType invocationType = KTextEditor::CodeCompletionModel::ManualInvocation)

Invoke code completion over a given range, with specific models and invocation type.

models is the list of models to start. If this is an empty list, all registered models are started.

[signal] void View::statusBarEnabledChanged(KTextEditor::View *view, bool enabled)

This signal is emitted whenever the status bar of view is toggled.

enabled Whether the status bar is currently enabled or not

[since 5.33] QRect View::textAreaRect() const

Get the view's text area rectangle excluding border, scrollbars, etc.

Returns the view's text area rectangle

This function was introduced in 5.33.

[pure virtual] int View::textHintDelay() const

Get the text hint delay in milliseconds. By default, the text hint delay is set to 500 milliseconds. It can be changed by calling setTextHintDelay().

See also setTextHintDelay().

[signal] void View::textInserted(KTextEditor::View *view, KTextEditor::Cursor position, const QString &text)

This signal is emitted from view whenever the users inserts text at position, that means the user typed/pasted text.

view is the view in which the text was inserted

position is the position where the text was inserted

text is the inserted text

See also insertText().

[since 5.79] KSyntaxHighlighting::Theme View::theme() const

Get the current active theme of this view. Might change during runtime, configChanged() will be emitted in that cases.

Returns current active theme

This function was introduced in 5.79.

[pure virtual, since 6.0] bool View::uniformAnnotationItemSizes() const

Returns true if the annotation items all have the same size.

This function was introduced in 6.0.

[pure virtual] void View::unregisterCompletionModel(KTextEditor::CodeCompletionModel *model)

Unregister a code completion model.

model is the model that should be unregistered

See also registerCompletionModel().

[pure virtual] void View::unregisterInlineNoteProvider(KTextEditor::InlineNoteProvider *provider)

Unregister the inline note provider provider.

provider inline note provider to unregister

See also registerInlineNoteProvider() and KTextEditor::InlineNoteProvider.

[pure virtual] void View::unregisterTextHintProvider(KTextEditor::TextHintProvider *provider)

Unregister the text hint provider provider.

provider text hint provider to unregister

See also registerTextHintProvider() and KTextEditor::TextHintProvider.

[pure virtual, since 6.0] QScrollBar *View::verticalScrollBar() const

Returns The vertical scrollbar of this view

This function was introduced in 6.0.

[signal] void View::verticalScrollPositionChanged(KTextEditor::View *view, KTextEditor::Cursor newPos)

This signal should be emitted whenever the view is scrolled vertically.

view is the view which emitted the signal

newPos is the new scroll position

[pure virtual] KTextEditor::View::InputMode View::viewInputMode() const

Get the view's current input mode. The current mode can be NormalInputMode and ViInputMode. For human translated version

Returns the current input mode of this view

See also setViewInputMode(), viewInputModeHuman, and viewInputModeChanged().

[signal] void View::viewInputModeChanged(KTextEditor::View *view, KTextEditor::View::InputMode mode)

This signal is emitted whenever the view's input mode changes.

view is the view which changed its input mode

mode is the new input mode

See also viewInputMode().

[pure virtual] QString View::viewInputModeHuman() const

Get the view's current input mode in human readable form. The string should be translated (i18n). For id like version

Returns the current input mode of this view in human readable form

See also viewInputMode.

[pure virtual] KTextEditor::View::ViewMode View::viewMode() const

Get the current view mode/state. This can be used to detect the view's current mode. For example NormalInputMode, ViInputMode or whatever other input modes are supported.

Returns current view mode/state

See also viewModeChanged() and viewModeHuman().

[signal] void View::viewModeChanged(KTextEditor::View *view, KTextEditor::View::ViewMode mode)

This signal is emitted whenever the view mode of view changes.

view is the view which changed its mode

mode is the new view mode

See also viewMode().

[pure virtual] QString View::viewModeHuman() const

Get the current view mode state.

This can be used to visually indicate the view's current mode, for example INSERT mode, OVERWRITE mode or COMMAND mode - or whatever other edit modes are supported. The string should be translated (i18n), as this is a user aimed representation of the view state, which should be shown in the GUI, for example in the status bar. This string may be rich-text.

Returns Human-readable version of the view mode state

See also viewModeChanged().

[pure virtual] void View::writeSessionConfig(KConfigGroup &config, const QSet<QString> &flags = QSet<QString>())

Write session settings to the config. See readSessionConfig() for more details.

config is the KConfigGroup to write the session settings to

flags is additional flags (see the known flags listed in readSessionConfig())

See also readSessionConfig().