1.49.7 Send methods

editor ->_dabbrev_expand: event_id

@see editor->dabbrev_expand

editor ->align: column=int, index=[int]

Insert/delete spaces and tab characters such that the character at index [editor<-caret] will have editor<-indentation column. When layout characters are deleted, at least a single space remains.

Useful for realising automatic indentation and alignment of comments in syntax driven editors.

editor ->align_line: column=[int]

Align the line holding the caret such that the first non-layout character is at the indicated column. When columns is omitted, editor<-left_margin is used. See also editor->align, align_region and editor->indent_line.

editor ->align_region: column=[int]

Apply editor->align_line to all lines in the current region (mark, caret).

editor ->append: text=char_array

Append the specified text. If editor<-left_margin is not zero, editor->align the last line to editor<-left_margin. Then append the text. If editor<-auto_newline is @on, append a newline too. Set the editor->caret at the end of the buffer.

editor->print editor->insert’s the text at the editor<-caret, followed by a newline character if editor<-auto_newline equals @on.

Bugs: Messy. New code should use the editor->align and editor->format methods.

See also

- editor-left_margin
- editor-auto_newline

editor ->print: text=string

Insert text at caret (auto_newline).

editor ->appendf: format=char_array, argument=any ...

Formatted append (see editor->format and string->format (argument specification).

editor ->auto_fill: from=[int], skip=[regex]

Fill after editor->insert_self_fill detected a long line. The default implementation fills from the start of the current line to the end of the paragraph, using the left-margin from the current indentation.

This method is intended for redefinition in language mode to perform more mode-dependent filling such as breaking long comments, log argument lists, etc.

editor ->auto_fill_mode: [int]

Inherits description from: editor-fill_mode

editor ->backward_paragraph: [int]

Move paragraphs backward.

editor ->backward_sentence: [int]

Move sentences backward.

editor ->backward_term: [int]

Move Prolog terms backward.

editor ->backward_word: [int]

Move words backward.

editor ->backward_char: [int]

Move the caret the times the indicated unit backwards. The definition of words, sentences and paragraphs depends on the syntax_table object associate to the editor<-text_buffer. See also text_buffer<-scan.

editor ->delete_char: [int]

Delete characters forward.

editor ->backward_delete_char: [int]

Delete characters from the caret. By default deletes a single character.

editor ->kill_line: [int]

Kill lines forward.

editor ->kill_paragraph: [int]

Kill paragraphs.

editor ->kill_sentence: [int]

Kill sentences forward.

editor ->kill_term: [int]

Kill Prolog terms.

editor ->kill_word: [int]

Kill words forward.

editor ->backward_kill_word: [int]

Kill the specified (default 1) number of units in the specified direction. See editor->kill and editor->yank for details on killing and yanking (cut/copy) text.

editor ->beginning_of_line: [int]

Move lines backward, default is to the start of the current line.

editor ->downcase_previous_word: [int]

Lower-case n words before caret.

editor ->upcase_previous_word: [int]

Uppercase n words before caret.

editor ->capitalise_previous_word: [int]

Similar to the editor->capitalise_word/editor->upcase_word and editor->downcase_word group, but affects the word before rather than after the editor<-caret. Saves keystrokes when used to correct typos while entering text.

editor ->downcase_word: [int]

Loser-case n words after caret.

editor ->upcase_word: [int]

Uppercase n words after caret.

editor ->capitalise_word: [int]

Change the case of the word, starting at the first letter scanning forwards from the editor<-caret up to the end of this word. editor->capitalise_word maps the first letter to uppercase and the remainder to lowercase.

editor ->clear:

Remove all text and fragments using text_buffer->clear. Deletes the selection and sets the editor<-caret to 0.

editor ->column: column=int

Inherits description from: editor<-column

editor ->compute:

Invoke text_image->compute. Next verifies that the editor<-caret is in the window and moves the window if necessary. Finally update the editor<-text_cursor, editor<-margin and editor<-scroll_bar.

editor ->cua_key_as_prefix: event|event_id

Test whether to use the keys \C-x or \C-c as Emacs prefix keys or CUA-mode Cut/Copy commands. The rules for this are based on cua.el, a GNU-Emacs mode merging CUA and Emacs by Kim F. Storm (storm@cua.dk):

• If there is an active selection (see editor<-mark_status), map them to copy or cut.
• If the shift-key is depressed, map them to their Emacs prefix behaviour.
• If another key is depressed within 0.25 seconds, use map them to their Emacs prefix behaviour.

  According to Kim this results in pretty normal behaviour for both Emacs and CUA users. CUA users expect the bevahiour on the selection only. Emacs users have some trouble with \C-c or \C-x commands that act on the region, but luckily these conflicts are acceptable.

  The underlying behaviour is implemented by key_binding->typed.

editor ->dabbrev_expand:

Expand the word before the caret. This is achieved by scanning the current buffer backwards for words that start the same way as the partial current word. Successive execution of this method will try alternative completions.

See also

- editor-dabbrev_target
- editor-dabbrev_reject
- editor-dabbrev_pos
- editor-dabbrev_origin
- editor->_dabbrev_expand

editor ->delete: from=int, to=int

Each of the commands editor->delete, editor->grab and editor->kill operate on characters in the range [from, to) (i.e. to minus from characters). If to < from, the arguments are first swapped. The commands may or may not delete the range and may or may not add the deleted text to the kill-buffer @text_kill_ring:

editor->delete	Just deletes the text
editor->kill	editor->delete and add the deleted text to the kill ring
editor->grab	Add the text to the kill-ring without deleting it.

See also @text_kill_ring and editor->yank.

editor ->delete_blank_lines:

GNU-Emacs compatible command. See also editor->delete_horizontal_space and editor->just_one_space.

editor ->grab: from=int, to=int

Add text to the kill-buffer.

editor ->kill: from=int, to=int

Delete text and add it to the kill-buffer.

editor ->delete_horizontal_space: [int]

Delete all white space (no newlines) around caret and reinsert the specified number of spaces. Default is to insert 0 spaces. See also editor->just_one_space.

editor ->capitalise_region:

Capitalise words in region.

editor ->downcase_region:

Map all characters in the region [editor<-mark ... editor<-caret) to the specified case. editor->capitalise_region will map any first letter of a word to uppercase and any other letter to lowercase.

See also

editor->upcase_region

editor ->electric_caret: index=int, seconds=[real]

Temporary display the caret at the indicated position. The caret is restored to the insertion-point after the indicated time (in seconds) or after the user has typed in the editor.

This method may be used to indicate a related position. For example if the user types a closing-bracket this method may be used to indicate the matching opening bracket.

Defaults: The default time to restore the caret is 0.5 seconds.

See also

editor->show_caret_at

editor ->event: event

Process an event:

1. Succeed if device->event succeeds. This allows for redefining event-handling on any of the parts of the editor.
2. If the event is a keyboard event, invoke editor->typed.
3. If the event is an area event, update the graphical->active status.
4. If the recogniser object @editor_recogniser exists, invoke recogniser->event to this object and return the result thereof.

editor ->exchange_point_and_mark:

Exchange the location of editor<-mark with editor<-caret. Note that commands operating on the region (the text between the two) do not care which of the two has the lowest index.

See also

editor-mark

editor ->fill: from=int, to=int, left_margin=[int], right_margin=[int], justify=[bool]

Fill paragraphs in the range [from, to). The specified margins default to editor<-left_margin and editor<-right_margin. If justify equals @on, editor->fill inserts spaces such that the right_margin will be straight.

Bugs: Only works properly with fixed-width fonts,

editor ->fill_region:

Fill paragraphs in region.

editor ->fill_selection:

Compat: editor->fill_region.

editor ->fill_paragraph: justify=[int]

Frontend methods to editor->fill the specified text. The margins default to editor<-left_margin and editor<-right_margin.

See also

- editor-right_margin
- editor-left_margin

editor ->find_cut_buffer: [int]

Find the value of the indicated display<-cut_buffer as a plain string. Respects editor<-exact_case. If the string is found it is selected, otherwise a warning is editor->report’ed.

editor ->format: format=char_array, argument=any ...

Inserts formatted text at the editor<-caret location. See string->format for a description on the format specification. See also editor->appendf.

editor ->forward_paragraph: [int]

Move paragraphs forward.

editor ->forward_sentence: [int]

Move sentences forward.

editor ->forward_term: [int]

Move Prolog terms forward.

editor ->forward_word: [int]

Move words forward.

editor ->forward_char: [int]

Move the caret the times the indicated unit forwards. The definition of words, sentences and paragraphs depends on the syntax_table object associate to the editor<-text_buffer. See also text_buffer<-scan.

editor ->geometry: x=[int], y=[int], width=[int], height=[int]

Handle geometry requests to the editor. Properly resizes and positions the editor<-scroll_bar, editor<-image and editor<-margin. The minimum size is defined to be 50x20 pixels.

editor ->gosmacs_transpose:

Transpose characters compatible to the GosMacs editor: transposes the character before the caret with the one before that one. The advantage lies in correcting character transposition typos. Using editor->gosmacs_transpose this requires a single keystroke. Using editor->transpose_chars this requires 3 keystrokes.

graphical ->height: int

Inherits description from: editor-size

editor ->hover_fragment_icon: fragment=fragment*, icon_area=[area]

Virtual method. Called from the text_margin object when the mouse enters and exits the area of an icon. On enter the fragment object and the area where the fragment is painted relative to the margin is passed. On exit, the fragment is @nil and the argument @default.

editor ->indent_region: [int]

Indent lines in region by editor<-indent_increment.

editor ->indent_selection: [int]

Compat: editor->indent_region.

editor ->undent_line: [int]

Unindent line by editor<-indent_increment.

editor ->undent_region: [int]

Unindent lines in region by editor<-indent_increment.

editor ->undent_selection: [int]

Compat: editor->undent_region.

editor ->indent_line: [int]

Increase (undent: decrease) the indentation of the current line by arg times editor<-indent_increment. This group of methods is compatible to the Dope editor and allows for manipulating the indentation when editing source-code. See also editor->align_line.

See also

editor-indent_increment

editor ->initialise: text=[text_buffer], width=[int], height=[int], margin=[int]

Create an editor object from the specified arguments. If no text_buffer is specified, a default empty text_buffer object is used. The width and height arguments are interpreted in terms of character units.

The margin specifies the with of the text_margin object attached to the right side used for annotations. The default is 0, attaching no annotation margin. See also editor->margin.

Class view encapsulates an editor object in a window.

editor ->insert: text=char_array

Insert the given text at the caret and move the caret to point just after the inserted text.

editor ->insert_cut_buffer: [int]

Insert the text from the display<-cut_buffer. Move caret to the end.

editor ->insert_self_fill: times=[int], character=[char]

Insert char n times; adjust margins.

editor ->insert_self: times=[int], character=[char]

Insert the argument character times times.

The editor->insert method calls editor->insert_self_fill if editor<-auto_fill_mode equals @on.

The editor->insert_self_fill calls editor->auto_fill if -after the insertion-, the text extends the editor<-right_margin. Normally this fills the remainder of the paragraph. By redefining editor->auto_fill, more specialised handling of long lines can be implemented.

See also

editor-fill_mode

editor ->isearch_backward:

Start incremental search backward.

editor ->isearch_forward:

Start an incremental search. The editor will search for the typed plain text (respecting editor<-exact_case) and indicate the first hit using the selection on each subsequent letter typed by the user. While searching, the following keys have special meaning:

keyboard_quit			Abort and revert to where search started
isearch_backward
isearch_forward			Revert direction or search for next
backward_delete_char	Remove the last character from the target
ESCAPE					Terminate search
\C-w					Extend target to current word

See also

- editor->isearch_backward
- editor-search_string
- editor-search_origin
- editor-search_direction
- editor-search_base
- editor-exact_case

editor ->just_one_space:

Replace all white-space (tab, space, not newline) surrounding the caret by a single space.

editor ->justify_region:

Justify region.

editor ->justify_paragraph:

Front-end to editor->fill the specified unit of text. The justify argument of editor->fill is set to @on, creating a straight right margin.

editor ->key_binding: key=name, action=name|code

Add a new binding to editor<-bindings using key_binding->function to this object. The key_binding remains local to the receiving editor. The method editor<-key_binding requests the current binding (local or global) using key_binding<-function.

editor ->kill_or_grab_region: [int]

Without an argument, editor->kill the current region. Otherwise editor->grab the region.

editor ->label: name

Associate a label with the editor and set the string of the label. The label is displayed by editor<-label_text. The font of the label is dictated by editor.label_font. See also editor<->show_label.

editor ->line_number: line=int

Position the caret at the start of nth (1-based) line.

editor ->line_to_top_of_window: [int]

Scroll such that the current line is the nth (1 based, default = 1) line of the window. See also editor->normalise.

editor ->load: file=source_sink

Load the contents of the specified file object. Performs the following steps:

->clear						Clear the editor
`text_buffer ->insert_file`	Insert the file contents
<-file						Assign the file variable
->caret: 0					Put the caret `home`
`text_buffer ->modified: @off`	Clear modified
`text_buffer ->reset_undo`	Clear undo info
->editable: Bool

If file->access succeeds, editor->editable: @on is invoked on the editor, otherwise editor->editable: @off.

See also

editor-file

editor ->lost_text_buffer:

Invoked by the associated editor<-text_buffer if it is being freed. By default, this method will simply send object->free to the editor, or its associated view object.

This method may be redefined, but should either free the editor, or associate another (new) text_buffer object with the editor.

See also text_buffer->unlink.

editor ->margin_width: pixels=int

Inherits description from: editor-margin, editor<-margin_width

See also

- style-icon
- editor-margin
- class text_margin

editor ->mark: mark=[int], status=[{active,inactive,highlight}]

Set mark and region-status. The region (selection) is defined by the characters in the range [editor<-mark ... editor<-caret) or [editor<-caret .. editor<-mark) if the caret is before the mark. The old position of the mark is pushed in editor<-mark_ring. If the mark is active, it can be used for region-commands.

See also editor->set_mark, editor<-mark_ring and editor->selection.

editor ->newline: [int]

Insert times newline characters. editor->newline inserts before the caret, editor->open_line after the caret, so the caret remains at the same line.

editor ->open_line: [int]

Insert newlines after caret.

editor ->newline_and_indent: [int]

Start a new line and copy the indentation from the previous line. The argument defines the number of lines inserted.

editor ->next_line: lines=[int], column=[int]

Move lines downward; place caret at column. If columns is omitted, editor<-column is used. Normally the column is maintained by class key_binding.

See also

editor-save_column

editor ->normalise: from=[int], to=[int]

Try to make the range [from,to) visible. If this range is too big to fit on a screenful, the line on which from resides will be the first line displayed. See also editor->line_to_top_of_window and editor->recenter.

Defaults: Both arguments default to editor<-caret

See also

editor->selection

editor ->point_to_bottom_of_window: [int]

Scroll caret to bottom of window.

editor ->point_to_bottom_of_file: [int]

Place the caret at the nth-line from the end of the file/window. Without an argument, the caret is placed at the end of the file/window.

editor ->point_to_mark:

Move editor<-caret to the editor<-mark. In most cases editor->exchange_point_and_mark is to be preferred. See also editor->set_mark.

See also

editor-mark

editor ->point_to_top_of_window: [int]

Move to 1st character of window.

editor ->point_to_top_of_file: [int]

Move caret to the nth-line from the top of the file/window. Default is the start of the file/window. See also editor->line_number.

editor ->previous_line: lines=[int], column=[int]

@see editor-save_column

editor ->recenter: [int]

Same as editor->line_to_top_of_window, but centers the current line on the window rather than making it the first line.

editor ->report: kind={status,inform,progress,done,warning,error,fatal}, format=[char_array], argument=any ...

If editor<-error_message is not @nil, execute it using the following arguments:

@receiver	The editor<-master of the editor
@arg1	The editor
@arg2	the kind
@arg3	The message

See visual->report for a discussion on the reporting mechanism.

editor ->save: file=[file]

Save to editor<-file or named file. If no file is specified and editor<-file is @nil, this method fails. If the file to save in exists, a backup is created using file->backup. Next, the contents of the editor is saved into the named file. If a file was specified, editor<-file will be filled with the argument file.

See also

editor-file

editor ->save_buffer: always=[int]

Save the editor to editor<-file if it is editor<-modified or the argument is not @default. If the operation succeeds, the editor<-modified flag is cleared. Diagnostics are reported using editor->report.

See also

editor-file

editor ->scroll_one_line_down: [int]

Scroll lines (1 line) downward.

editor ->scroll_one_line_up: [int]

Scroll lines (1 line) upward.

editor ->scroll_up: [int]

Scroll lines (1 screen) upward.

editor ->scroll_down: [int]

Scroll forwards or backwards by the specified number of lines. For the one_line versions of this method, the default is to scroll a single line. For editor->scroll_up/editor->scroll_down the default is a screenful minus a line.

editor ->scroll_to: index=[int], screenline=[int]

Set start of screenline-th line of window to index (character based). Index should be the start of a physical line, though this is not actively enforced. If screenline is @default, the given position is centered in the window. The first screenline is line 1.

See text_buffer<-scan.

editor ->scroll_vertical: direction={forwards,backwards,goto}, unit={file,page,line}, amount=int

Handle requests from the editor<-scroll_bar. Normally there is no reason to deal with this method yourself. We document it here to explain the three scrolling models used by the editor.

If the text_buffer<-size (i.e. the number of characters held by the editor) is large, It determines the position and size of the scrollbar based on character offsets.

If the size gets medium, it counts physical lines, i.e. the number of newline characters.

If the size gets small, it computes the line-layout, including line-heigth using the current editor<-wrap setting. This mode provides relyable precise scrolling, but quickly gets too costly for real-time usage.

Inherits description from: editor<-length

editor ->select_line: line=[int], newline=[bool]

Select the line with given number. Numbering lines starts at 1.

editor ->selected_fragment: fragment*

@see class fragment

editor ->selected_fragment_style: style

Style for the currently editor<-selected_fragment.

See also editor->margin_width, editor->selection_style and class style.

editor ->selection: mark=[int], caret=[int], status=[{active,inactive,highlight}]

Make characters in the range [from,to) the selection and invoke editor->normalise on the same range to make the selection or as much as possible thereof visible. If to is equal to from, no selection is visible and the editor is not normalised.

The selection is determined by editor<-mark and editor<-caret. It can be in three modes as described with editor<->mark_status.

See also editor<-selected, editor<-selection, editor<-selection_start and editor<-selection_end.

Defaults: The first argument (from) defaults to the current start of the selection; the second (to) to the current end of the selection.

See also

editor->normalise

editor ->selection_extend: to=int

Extend the selection to include the specified index. This method is used when defining the selection with the pointer. This method respects -selection_unit.

editor ->set_fill_column: [int]

Inherits description from: editor-left_margin

See also

- editor-right_margin
- editor-left_margin

editor ->set_mark: [int]

Interactive command to set editor<-mark at editor<-caret, starting an active selection, also called region. With an argument this command cycles through the list marks in the editor<-mark_ring.

Programmatic access to the mark is provided by editor->mark.

See also

editor-mark

editor ->show_caret: show=bool

Controls the visibility of the caret. In addition, if the caret is not visible, the cursor up/down keys scroll the editor rather than moving the (invisible) caret. See also editor->editable.

editor ->show_caret_at: index=[int]

Display the caret at the indicated location without moving the insertion-point. The indicated position must be inside the visible range of the editor (see editor<-start and editor<-view). This method is used by editor->electric_caret..

See also

editor->electric_caret

editor ->show_label: show=bool

Show/unshow the label. If the editor has no editor<-label_text, one is created. Otherwise the graphical<->displayed attribute of the label_text is used to control the visibility of the label. The method editor->geometry is invoked to realise the proper layout of the components of the editor object.

editor ->show_matching_bracket: index=[int]

Indicate the bracket matching the bracket at index (default editor<-caret) using editor->electric_caret.

graphical ->size: size

Inherits description from: editor-size

editor ->sort: from=[int], to=[int]

Inherits description from: text_buffer->sort

editor ->style: fragment=name, style=style*

Inherits description from: editor-styles

See also

class style

editor ->switch_case_mode: [int]

Inherits description from: editor-exact_case

See also

editor-exact_case

editor ->tab_stops: vector*

Set/query tab-stops at the indicated (pixel) positions. This method is commonly used to display tabular information.

See also

editor<-tab_stops

editor ->transpose_lines:

Transpose line with line above.

editor ->transpose_terms:

Transpose Prolog terms around point.

editor ->transpose_word:

Transpose words around caret.

editor ->transpose_chars:

Transpose the unit before the caret with the one after the caret. The exact definition of the unit depends on the syntax_table object associated to the editor<-text_buffer

editor ->typed: event|event_id

Normally called from editor->event to handle typing. Handles editor<-focus_function and/or invokes key_binding->typed on editor<-bindings.

See also

editor-bindings

editor ->undo:

Undo the last interactively given command. Marking the undo-log is achieved by editor->event.

editor ->upcase_region:

@see editor->downcase_region

graphical ->width: int

Inherits description from: editor-size

editor ->wrap: {none,character,word}

Inherits description from: editor<-wrap

editor ->yank: [int]

Insert the text from the nth (default 0) vector<-element of @text_kill_ring. Text is inserted in the kill-ring using editor->kill or editor->grab.