eye.widgets.editor module

Editor widget

Positions

Positions in the text of an editor widget can be expressed in multiple ways.

First, the position of a character can be expressed as “line-index”, which is the line and column of that character, in terms of Unicode codepoints, with the str type. Unless specified otherwise, line and column numbers start at 0 in EYE.

Another way, more low-level, is the byte offset of the byte in the byte text (with type bytes). The internal byte encoding of the editor is UTF-8, regardless of the encoding of the underlying disk file, which only intervenes when loading/saving.

Module contents

class eye.widgets.editor.BaseEditor(**kwargs)

Bases: QsciScintilla

Editor class adding missing Scintilla features

QsciScintilla is an incomplete wrapper to Scintilla, this class aims to add support for a few of the missing editor features.

Note

This class should not be instanciated directly as it exists only to add editor widget features and is thus considered low-level. eye.widgets.editor.Editor contains file-related features and should be used instead.

See also

Since QsciScintilla is used as a base, the QsciScintilla documentation should also be consulted. The more low-level Scintilla documentation can also help, though more rarely.

CaretStyleBlock = <Mock object>

Caret is a block enclosing the next character

CaretStyleInvisible = <Mock object>

Caret is invisible

CaretStyleLine = <Mock object>

Caret is a vertical line between two characters

FoldFlagLevelNumbers = <Mock object>

FoldFlagLineAfterContracted = <Mock object>

FoldFlagLineAfterExpanded = <Mock object>

FoldFlagLineBeforeContracted = <Mock object>

FoldFlagLineBeforeExpanded = <Mock object>

FoldFlagLineState = <Mock object>

IndicatorFlagValueFore = <Mock object>

SelectionLines = <Mock object>

Select full lines between two offsets in the text.

All characters of the lines between the start offset and end offset, included, are selected.

SelectionRectangle = <Mock object>

Select characters in a rectangle between two offsets in the text.

On each line from the line of the start offset to the line of the end offset, only characters from the column of the start offset to end column of the end offset are selected, thus making a rectangle.

SelectionStream = <Mock object>

Select a character stream between two offsets in the text.

If the start offset and end offset are not on the same lines, the characters from the start offset to the end of its line are selected, plus the characters from the end offset to the start of its line, plus the lines in between are completely selected.

SelectionThin = <Mock object>

VsNone = <Mock object>

Virtual space after a line’s end is not accessible

VsRectangular = <Mock object>

Virtual space after a line’s end is accessible with rectangular selection mode

VsUser = <Mock object>

Virtual space after a line’s end is accessible by user with cursor

action_recorded = Signal(object)

Signal action_recorded(object): an action was recorded in macro

The signal argument is the action recorded, and can be passed to replay_macro_action to replay this action. Internally, the action argument is a tuple suitable for Scintilla to process it.

add_selection(line_from, index_from, line_to, index_to)

Add a new selection (line-index based).

The first selection should be set with setSelection, and the next ones with this method.

add_selection_offsets(arg1, arg2)

Add a new selection (offset based).

See add_selection.

add_undo_action(arg1, arg2)

add_undo_action(int, int): add a custom action to the undo buffer

additional_selection_typing()

Return True if typing operates on all selections.

See set_additional_selection_typing.

annotation_styled_text(line)

Return styled text annotations of a line

Each line can have annotations compound of multiple pieces of text styled differently. This method retrieves all text parts along with their styles of the annotations of line.

It can be seen as the “get” counterpart of the annotate function taking a list of QsciStyledText.

Return type:

list of QsciStyledText

caret_period()

Get caret blinking period in milliseconds

caret_style()

Get caret display style

See set_caret_style.

clearIndicatorRange(line_from, index_from, line_to, index_to, indic)

clear_representation(s)

clear_selections()

Deselect all selections.

connectNotify(sig)

create_indicator(name, indicator=<Mock object>)

Create and return an Indicator with name name and style indicator

create_margin(name, margin)

create_marker(name, marker=<Mock object>)

Create and return a Marker with name name and symbol marker

delete_range(arg1, arg2)

Delete characters in byte offset range

disconnectNotify(sig)

dispose_indicator(name)

dispose_marker(name)

drop_selection_n(*args)

Deselect the n-th selection.

empty_undo_buffer()

empty_undo_buffer(): empty the undo buffer

fillIndicatorRange(line_from, index_from, line_to, index_to, indic, value=1)

get_fold_level(*args)

Get fold level of line value

get_marker_next(line, marker)

get_marker_previous(line, marker)

get_position_from_point(arg1, arg2)

get_position_from_point(int):

get_position_from_point_close(arg1, arg2)

get_position_from_point_close(int, int):

get_representation(s)

get_selection_n(n)

Get line-indexes of the n-th selection.

Returns a 4-tuple with line-index of the anchor and line-index of the caret. Note that the caret may be before or after the anchor.

Parameters:

n (int) – index of the selection

Return type:

tuple[int, int, int, int]

get_style_at(value)

get_style_at(int): get style number at given byte position

get_style_hotspot(*args)

get_style_hotspot(int): get whether a style is a hotspot

indicator_end(*args)

indicator_flags(value)

indicator_start(*args)

indicator_value_at(*args)

insert_bytes(*args)

Insert byte characters at byte offset

lexer_property(prop)

macro_record_started = Signal()

Signal macro_record_started()

After this signal is emitted, and until macro_record_stopped() is emitted, actions performed by user will be recorded and action_recorded(object) will be emitted for each action.

macro_record_stopped = Signal()

Signal macro_record_stopped()

This signal is emitted when macro recording stops. action_recorded() will not be emitted any more after.

main_selection()

Return the main selection index.

markerAdd(line, marker)

Add marker with name/id i at line ln

markerDelete(line, marker)

Delete marker with name/id i from line ln

multi_paste()

Return True if pasting operates on all selections.

See setMultiPaste.

multiple_selection()

Return True if multiple selection is enabled

position_relative(*args)

Get byte-offset from byte-offset + number of characters

replace_target(arg1, arg2)

replay_macro_action(action)

Replay a macro action

sci_modified = Signal(object)

Signal sci_modified(object): a modification was done

The signal argument is a 10-tuple describing the modification. The modifications signalled can be of various types.

scn_autoccancelled()

This slot has signature scn_autoccancelled().

scn_macro(msg, lp, wp)

scn_modified(*args)

This slot has signature scn_modified(int, int, 'const char*', int, int, int, int, int, int, int).

search_flags()

search_in_target(s)

selection_mode()

selection_n_anchor(*args)

Get the offset of the n-th selection’s anchor.

selection_n_caret(*args)

Get the offset of the n-th selection’s caret.

selections_count()

Return the number of selection ranges (if multiple selections are enabled, else 1)

selections_empty()

Return True if all selections are empty.

setMarkerBackgroundColor(color, marker)

Set background color c to marker with id/name i

setMarkerForegroundColor(color, marker)

set_additional_selection_typing(*args)

Set whether typing in a multi-selection should type in all selections.

If set to True, when multiple regions are selected, typing or removing characters will act on all selections instead of the main selection only.

set_caret_period(value)

Set caret blinking period in milliseconds

set_caret_style(value)

Set caret display style

Should be one of CaretStyleInvisible, CaretStyleLine, CaretStyleBlock.

set_fold_flags(value)

set_fold_level(*args)

Set fold level of a line

Set fold level arg2 for line arg1.

set_indicator_flags(arg1, arg2)

set_lexer_property(*args)

set_lexer_property(bytes, bytes): set a lexer property (key/value)

set_main_selection(*args)

Set the index of the main selection.

When there are multiple selections, set the main selection to be the n-th selection.

set_multi_paste(value)

Set whether pasting in a multi-selection should paste in all selections

If set to True, when multiple regions are selected, pasting will paste in all selections instead of the main selection only.

set_multiple_selection(value)

setMultipleSelection(bool)

Set if multiple ranges of characters can be selected. All ranges are selected in the same selection mode.

set_representation(arg1, arg2)

set_search_flags(value)

set_selection_mode(value)

set_style_hotspot(int, bool): set whether a style is a hotspot (like a link)

set_target_end(*args)

set_target_range(*args)

set_target_start(*args)

set_undo_collection(b)

set_undo_collection(bool): set whether editing actions are collected in the undo buffer

set_virtual_space_options(value)

Set options for virtual space after a line’s end

Should be an or-combination of one or more flags in VsNone, VsRectangular, VsUser.

showUserList(id, items)

start_macro_record()

Start recording macro

Also emits macro_record_started()

stop_macro_record()

Stop recording macro

Also emits macro_record_stopped()

target_end()

target_start()

undo_collection()

undo_collection(): return whether editing actions are collected in the undo buffer

virtual_space_options()

Get virtual space options

See setVirtualSpaceOptions.

class eye.widgets.editor.Editor(**kwargs)

Bases: BaseEditor, CentralWidgetMixin

Editor widget class

By default, instances of this class have the “editor” category set (see eye.connector module for more info).

See also

Since QsciScintilla is used as a base, the QsciScintilla documentation should also be consulted.

SmartCaseSensitive = <object object>

annotate_append(line, item, style=None)

Append a new annotation

Add an annotation for line. If there was an existing annotation at this line, unlike annotate, the old annotation is not overwritten, but the new annotation is appended to the old one.

If item is a string, it should be the text of the annotation to add, and style argument must be given. item can be a QsciStyledText object, which comprises both the text and the style, so the style argument should not be passed.

Parameters:

line (int) – the line of the editor where to add the annotation

annotate_append_line(line, item, style=None)

Append a new annotation on a line

bytes_length()

Return the length of the text in bytes

clear_search_highlight()

closeEvent(ev)

Overrides a Qt method.

close_file()

Prepare for closing file and return True if modification state is clean

If editor has no unsaved modifications, returns True. Else, ask user if modifications should be saved, then return True if accepted, else return False.

cursor_column()

Return the column number of the cursor position (starting from 0)

Note the column number is the number of Unicode codepoints since the start of the line. For example, a tab character will count for 1 column only, see cursor_visual_column.

cursor_line()

Return the line number of the cursor position (starting from 0)

cursor_line_index()

Return the cursor line-index starting from 0

See Positions.

cursor_offset()

Return the cursor position in byte offset

As this function returns a byte-offset, it should not be used unless necessary. See Positions.

cursor_position()

Return the cursor line-index starting from 0

Note

This function is misnamed in QsciScintilla and the naming is kept here to avoid more confusion.

See Positions.

cursor_visual_column()

does_remove_trailing_whitespace()

Return True if always trimming trailing whitespace when saving.

See set_remove_trailing_whitespace.

encoding()

Return the encoding to use for loading/saving

file_about_to_be_opened = Signal(str)

Signal file_about_to_be_opened(str)

file_about_to_be_saved = Signal(str)

Signal file_about_to_be_saved(str)

file_modified_externally = Signal()

Signal file_modified_externally()

file_opened = Signal(str)

Signal file_opened(str)

file_saved = Signal(str)

Signal file_saved(str)

file_saved_as = Signal(str)

Signal file_saved_as(str)

find(expr, case_sensitive=None, is_re=None, whole=None, wrap=None)

find_backward()

find_forward()

goto1(line, col=None)

This slot has signature goto1().

lexer()

lexer_changed = Signal(object)

Signal lexer_changed(object)

open_document(other)

open_file(path)

position_jumped = Signal(int, int)

Signal position_jumped(int, int)

reload_file()

Reload file contents (losing unsaved modifications)

Reload file from disk and replace editor contents with updated text. If the user made modifications to the editor contents without saving them, calling this method will will lose them. However, the replacement can be undone by the user.

This slot has signature reload_file().

save_file()

Save edited file

If no file path is set, a file dialog is shown to ask the user where to save content.

This slot has signature save_file().

setLexer(lexer)

set_encoding(s)

Set the file data encoding for loading/saving

When loading file contents from disk or saving file to disk, this encoding will be used. This does not change the internal encoding used by the editor widget, which is utf-8.

This does not cause the file to be re-saved.

set_remove_trailing_whitespace(b)

Set whether trailing whitespace should be trimmed when saving to disk

If b is True, trailing whitespace will be removed from each line on the the file saved to disk. It is still kept in the editor though (but this behavior may change in the future).

This does not cause the file to be re-saved.

set_use_final_newline(b)

Set whether a final newline should always be added when saving to disk

If b is False, the contents of the editor won’t be changed when saving file to disk: the file will only contain a final newline if the editor text ends with a newline.

If b is True, a final newline will be added to the file saved on disk, but this final newline won’t be shown in the editor. When the file is loaded, if it ends with a final newline, it won’t be shown in the editor either, though will be kept when saving again.

This does not cause the file to be re-saved.

text_length()

Return the length of the text in Unicode codepoints

undo_group(undo_on_error=False)

Context-manager to run actions in an undo-group.

Operations done in this context manager are put in an undo-group: undo and redo will do them all-at-once. The undo-group is opened at the beginning of the context and automatically closed at the end of the context. For example, removing a whole word will appear the same, undo-wise, as removing the word character-by-character, if all characters are removed while an undo-group was open.

Parameters:

undo_on_error (bool) – if an exception is raised inside the context, operations done in the group are undone

use_final_newline()

Return True if always adding a final newline when saving.

See set_use_final_newline.

word_at_cursor()

word_at_pos(pos)

class eye.widgets.editor.Indicator(style, editor=None, id=-1)

Bases: HasWeakEditorMixin

Text indicator

An indicator styles parts of the text with some particular visual style. It can be used for example by a spellchecker to underline misspelled words, or to highlight search results.

In an editor, an indicator can be set for multiple ranges of characters in the text content, which will then be displayed in the configured style.

Additionally, a numeric value can be associated when putting the indicator on a range. This allows to do some kind of sub-indicators. Where the indicator is not set, the value is always 0. The default value where an indicator is set is 1.

Example:

indic = editor.create_indicator(‘highlight’, editor.BoxIndicator) # declare an indicator named ‘highlight’ with a “box” style (the text will be surrounded by a box) # the Indicator instance can be retrieved later: # indic = editor.indicators[‘highlight’] indic.putAt(0, 0, 1, 0) # the first line will be styled with this indicator

Like eye.widgets.editor.Marker, Indicator`s are associated to an `Editor and have an arbitrary name. There can be at most 40 different indicator types per editor widget.

clear()

Remove the indicator from all characters in the editor widget

get_at_offset(offset)

Return the value of the indicator is present at byte offset

If the indicator is not set at byte offset, 0 is returned, else the value of the indicator at this offset is returned.

get_current_range(offset)

get_flags()

get_next_edge(offset)

Return the offset of the first edge of this indicator after offset.

If offset is inside a range of characters with this indicator set, the end of the range is returned. The returned end is exclusive: it’s the first offset outside the range.

If offset is outside a range, the start of the next range after offset is returned. The returned start is inclusive: it is the first offset in the range.

If there is no range after, -1 is returned.

Example:

>>> indicator.put_at_offset(4, 10)
>>> indicator.get_next_edge(0)
4
>>> indicator.get_next_edge(4)
10
>>> indicator.get_next_edge(10)
-1

get_next_range(offset, expected=None)

get_previous_edge(offset)

Return the offset of the first edge of this indicator before offset.

If offset is inside a range of characters with this indicator set, the start of the range is returned. The returned start is inclusive: it is the first offset in the range.

If offset is outside, the end of the previous range before offset is returned. The returned end is exclusive: it’s the first offset outside the range.

If there is no range before, -1 is returned.

Example:

>>> indicator.put_at_offset(4, 10)
>>> indicator.get_previous_edge(12)
10
>>> indicator.get_previous_edge(10)
4
>>> indicator.get_previous_edge(4)
-1

get_previous_range(offset, expected=None)

is_on_edge(offset)

iter_lines()

iter_ranges()

Return (start, end, value) tuples listing the ranges where the indicator is set.

Returns an iterator of (start, end, value) range tuple. For each tuple, start (inclusive) and end (exclusive) are byte offsets. value is the value of the indicator in this range.

put_at(line_from, index_from, line_to, index_to, value=1)

Add the indicator to a range of characters (line-index based)

The indicator is set from (line_from, index_from) (inclusive) to (line_to, index_to) (exclusive). In this range, the indicator will have value.

put_at_offset(start, end, value=1)

Add the indicator to a range of characters (byte offset based)

Parameters:

• start – start offset (inclusive)

• end – end offset (exclusive)

• value – in the range, indicator will have this value

remove_at(line_from, index_from, line_to, index_to)

Remove the indicator from a range of characters (line-index based)

The indicator is unset from (lineFrom, indexFrom) (inclusive) to (lineTo, indexTo) (exclusive). In this range, the indicator value will be reset to 0.

remove_at_offset(start, end)

Remove the indicator from a range of characters (byte offset based)

In this range, the indicator value will be reset to 0.

Parameters:

• start – start offset (inclusive)

• end – end offset (exclusive)

set_color(col)

Set the color of the text marked by this indicator

set_flags(flags)

set_outline_color(col)

Set the outline color of the text marked by this indicator

set_style(style)

Set the visual style of the text marked by this indicator

Parameters:

style (QsciScintilla.IndicatorStyle) – the new visual style to use

class eye.widgets.editor.Margin(editor=None, id=3)

Bases: HasWeakEditorMixin

static FoldMargin(editor=None)

static NumbersMargin(editor=None)

static SymbolMargin(editor=None)

hide()

set_all_marker_types()

set_marker_types(names)

set_text(line, txt)

set_width(w)

show()

class eye.widgets.editor.Marker(sym, editor=None, id=-1)

Bases: HasWeakEditorMixin

Margin marker of an editor

Markers are graphical symbols that can be added in the margin of editor widgets. For example, a marker can be used to indicate a breakpoint is present on a particular line of the file.

In an editor, a Marker can be set or unset for multiple lines, in which cases the configured symbol will be shown in the margin of the lines where the marker has been set.

Example:

marker = editor.create_marker('breakpoint', editor.Circle)
# declare a marker type called 'breakpoint' which will show a circle in the margin
# the Marker instance can be retrieved if needed
# marker = editor.markers['breakpoint']
marker.putAt(2)  # marker is added at 3rd line
marker.putAt(20)  # marker is added at 21st line

A Marker is associated with an eye.widgets.editor.Editor. An Editor can have multiple Marker`s, each with an arbitrary name. A `Marker has a symbol or pixmap configured and can then be put or removed for individual lines of the associated Editor.

get_next(line)

Return the line number of first line having this marker after line

-1 is returned if there is no line with the marker after line.

get_previous(line)

Return the line number of first line having this marker before line

-1 is returned if there is no line with the marker before line.

is_at(line)

Return True if a marker of this type is present at line

list_all()

List all lines that have this marker set

put_at(line)

Add a marker symbol of this type at line

remove_at(line)

Remove marker of this type at line if present

set_background_color(color)

Set background color of this marker type

set_color(color)

Set foreground color of this marker type

set_symbol(param)

Change the visual symbol of the marker

to_bit()

Return the internal Scintilla marker id in this editor instance

toggle_at(line)

Toggle marker of this type at line

class eye.widgets.editor.QsciScintilla(*args, **kwargs)

Bases: Mock

class eye.widgets.editor.SciModification(position, modificationType, text, length, linesAdded, line, foldLevelNow, foldLevelPrev, token, annotationLinesAdded)

Bases: tuple

Create new instance of SciModification(position, modificationType, text, length, linesAdded, line, foldLevelNow, foldLevelPrev, token, annotationLinesAdded)

annotationLinesAdded

Alias for field number 9

foldLevelNow

Alias for field number 6

foldLevelPrev

Alias for field number 7

length

Alias for field number 3

line

Alias for field number 5

linesAdded

Alias for field number 4

modificationType

Alias for field number 1

position

Alias for field number 0

text

Alias for field number 2

token

Alias for field number 8

eye.widgets.editor.zoom_on_wheel(ed, ev)

This handler is disabled by default.

This handler is registered as event filter for categories ['editor'] with event types [<Mock object at 0x77fc3892aad0>].