Provides advanced text display and editing facilities.

The Scintilla class provides advanced text editing capabilities that are suitable for modifying text files of any kind, as well as simple user input features for text input boxes. The code is based on the Scintilla project at http://scintilla.org and it may be useful to study the official Scintilla documentation for further insight into its capabilities.

Structure

The Scintilla class consists of the following fields:

Access

Name

Type

Comment

AllowTabs INT If enabled, use of the tab key produces real tabs and not spaces.

AutoIndent INT If TRUE, enables auto-indenting when the user presses the enter key.

BkgdColour RGB8 Defines the background colour. Alpha blending is not supported.

CursorCol INT The current column of the text cursor.

The CursorCol and CursorRow fields reflect the current row and column of the user's text cursor. The values are updated every time that the cursor is moved. Use EventCallback and listen for the event SEF_CURSOR_POS to receive updates on changes to CursorCol and CursorRow.

CursorColour RGB8 Defines the colour of the text cursor. Alpha blending is not supported.

CursorRow INT The current row of the text cursor.

The CursorCol and CursorRow fields reflect the current row and column of the user's text cursor. The values are updated every time that the cursor is moved. Use EventCallback and listen for the event SEF_CURSOR_POS to receive updates on changes to CursorCol and CursorRow.

EventCallback FUNCTION Provides callbacks for global state changes.

Set this field with a function reference to receive event notifications. It must be set in conjunction with EventFlags so that you can select the type of notifications that will be received.

The callback function must be in the format Function(*Scintilla, INT64 EventFlag).

The EventFlag value will indicate the event that occurred. Please see the EventFlags field for a list of supported events and additional details.

EventFlags SEF Specifies events that need to be reported from the Scintilla object.

To receive event notifications, set EventCallback with a function reference and the EventFlags field with a mask that indicates the events that need to be received.

Name	Description
SEF::CURSOR_POS	The cursor position has changed.
SEF::FAIL_RO	User attempt to edit read-only content.
SEF::MODIFIED	The content has changed to a modified state, i.e. the user has made an edit. The modified state will remain until the content is saved.
SEF::NEW_CHAR	At least one new character has been inserted.

FileDrop FUNCTION A callback for receiving drag and drop file notifications.

Set this field with a reference to a callback function to receive notifications when the user drops a file onto the Scintilla object's surface. The prototype for the callback function is ERR Function(*Scintilla, CSTRING Path)

If multiple files are dropped, the callback will be repeatedly called until all of the file paths have been reported.

Flags SCIF Optional flags.

Name	Description
SCIF::DETECT_LEXER	Automatic lexer detection will occur on initialisation and at any time that a source file is loaded.
SCIF::DISABLED	Read-only. This flag is set if the Scintilla object has been deactivated with the Disable action.
SCIF::EDIT	Must be defined if the document is to be editable via user input.
SCIF::EXT_PAGE	Extends the length of the document by one blank page. This is a visual effect that only has an impact when the user scrolls to the end of the document.

Focus OBJECTID Defines the object that is monitored for user focus changes.

By default, the user focus is managed by monitoring the target Surface for changes (for instance, clicking on or away from the surface will result in a focus state change). If another object should be monitored for focus state changes, it can be defined here prior to initialisation.

FoldingMarkers INT Folding markers in the left margin will be visible when this value is TRUE.

Font *Font Refers to the font that is used for drawing text in the document.

This field refers to the font object that is used for drawing text in the document. It is recommended that all font customisation takes place prior to initialisation of the Scintilla object. Directly altering the font object after initialisation may result in clashes with the Scintilla class that produce unpredictable results.

To change the font post-initialisation, please use the SetFont() method.

LeftMargin INT The amount of white-space at the left side of the page.

Lexer SCLEX The lexer for document styling is defined here.

The lexer for document styling is defined here.

Name	Description
SCLEX::ASP	Active Server Pages
SCLEX::ASSEMBLER	Assembler
SCLEX::BASH	Bash
SCLEX::BATCH	Batch
SCLEX::CPP	C or C++
SCLEX::CSS	CSS
SCLEX::DIFF	Diff
SCLEX::ERRORLIST	ErrorList
SCLEX::FLUID	Fluid
SCLEX::HTML	HTML
SCLEX::MAKEFILE	Makefile
SCLEX::PASCAL	Pascal
SCLEX::PERL	Perl
SCLEX::PHPSCRIPT	PHP Script
SCLEX::PROPERTIES	Properties
SCLEX::PYTHON	Python
SCLEX::REBOL	Rebol
SCLEX::RUBY	Ruby
SCLEX::SQL	SQL
SCLEX::VB	Visual Basic
SCLEX::VBSCRIPT	VBScript
SCLEX::XML	XML

LineCount INT The total number of lines in the document.

LineHighlight RGB8 The colour to use when highlighting the line that contains the user's cursor.

LineNumbers INT Line numbers will appear on the left when this value is TRUE.

Modified INT Returns true if the document has been modified and not saved.

The Modified field controls the modification state of the document. It is automatically changed to a value of TRUE when the user edits the document. To receive notification of changes to the document state, you should subscribe to the Modified field.

It is recommended that you manually set this field to false if the document is saved to disk. The Scintilla class will not make this change for you automatically.

Origin STRING Similar to the Path field, but does not automatically load content if set.

This field is identical to the Path field, with the exception that it does not update the content of a scintilla object if it is set after initialisation. This may be useful if the origin of the currently loaded content needs to be changed without causing a load operation.

Path CSTRING Identifies the location of a text file to load.

To load data from a text file into a scintilla object, set the Path field.

If the Path is set after initialisation, the existing content will be cleared and data loaded from the location that you specify. To change the path without automatically loading from the source file, set the Origin field instead.

RightMargin INT Defines the amount of white-space at the right side of the page.

SelectBkgd RGB8 Defines the background colour of selected text. Supports alpha blending.

SelectFore RGB8 Defines the colour of selected text. Supports alpha blending.

ShowWhitespace INT White-space characters will be visible to the user when this field is TRUE.

String STRING Manages the text data as a complete string.

A Scintilla document can be completely updated by setting the String field. Equally, the entire document can be retrieved by getting the String field. Please be aware that retrieving the document in string format can be very inefficient, as the document text is normally stored on a per-line basis. Consider using the GetLine() method as the preferred alternative, as it is much more efficient with memory usage.

Surface OBJECTID Refers to the Surface targeted by the Scintilla object.

This compulsory field refers to the Surface that the Scintilla object is targeting for graphics operations. If not set prior to initialisation, the Scintilla object will search for the nearest Surface object based on its ownership hierarchy.

Symbols INT Symbols can be displayed in the left margin when this value is TRUE.

TabWidth INT The width of tab stops in the document, measured as fixed-width characters.

TextColour RGB8 Defines the default colour of foreground text. Supports alpha blending.

Visible INT If TRUE, indicates the Scintilla object is visible in the target Surface.

This field is set to TRUE if the Scintilla object is visible in the target Surface. To control visibility, please use the Show() and Hide() actions appropriately. This field can be set to FALSE prior to initialisation if the Scintilla object should start in a hidden state.

Wordwrap INT Enables automatic word wrapping when TRUE.

Actions

The following actions are currently supported:

Clear

Clears all content from the editor.

Clipboard

Full support for clipboard activity is provided through this action.

ERR acClipboard(*Object, OBJECTID Clipboard, CLIPMODE Mode)

Parameter	Description
Mode	The mode that will be used to shift data between the target object and clipboard system.

Disable

Disables the target Surface.

Draw

Draws the Scintilla object's graphics.

ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)

Parameter	Description
X	The X position of the region to be drawn.
Y	The Y position of the region to be drawn.
Width	The width of the region to be drawn.
Height	The height of the region to be drawn.

Enable

Enables the target Surface.

Focus

Focus on the Scintilla surface.

Hide

Hides a visible object from the view of the user.

Redo

Redo the most recently undone activity.

SaveToObject

Save content as a text stream to another object.

ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

Show

Makes an object visible to the user.

Undo

Undo the last user action.

Methods

The following methods are currently supported:

DeleteLine Deletes a line.

ERR sci::DeleteLine(OBJECTPTR Object, INT Line)

Parameter	Description
Line	The number of the line to delete. Indexing starts from 0.

This method will delete a single line at the position indicated by the Line parameter. If no parameters are provided or the Line parameter is less than zero, the line at the current cursor position will be deleted. If the index exceeds the total number of available lines, the last available line will be targeted.

GetLine Copies the text content of any line to a user-supplied buffer.

ERR sci::GetLine(OBJECTPTR Object, INT Line, STRING Buffer, INT Length)

Parameter	Description
Line	The index of the line to retrieve.
Buffer	The destination buffer.
Length	The byte size of the `Buffer`.

This method will retrieve the string for a Line at a given index. The string is copied to a user supplied Buffer of the indicated Length (in bytes).

GetPos Returns the byte position of a given line and column number.

ERR sci::GetPos(OBJECTPTR Object, INT Line, INT Column, INT * Pos)

Parameter	Description
Line	Line index
Column	Column index
Pos	The byte position is returned in this parameter.

This method converts a Line and Column index to the equivalent byte position within the text document.

GotoLine Moves the cursor to any line in the document.

ERR sci::GotoLine(OBJECTPTR Object, INT Line)

Parameter	Description
Line	The line index to move to.

This method moves the cursor to a given line index. If the index is greater than the total number of available lines, the cursor is moved to the last line in the document. A line index of less than zero is invalid.

InsertText Inserts text into a document.

ERR sci::InsertText(OBJECTPTR Object, CSTRING String, INT Pos)

Parameter	Description
String	A text string to add.
Pos	-1 inserts at the current cursor position, -2 replaces currently selected text, zero or above inserts at the character index indicated.

Use InsertText to insert a string at any point in the document (if adding text to the end of the document, we recommend using data channels instead).

You will need to specify the character position at which the provided String should be inserted. Two special character positions are also supported as an alternative - a value of -1 inserts the text at the current cursor position and a value of -2 replaces currently selected text.

ReplaceLine Replaces a line with new text content.

ERR sci::ReplaceLine(OBJECTPTR Object, INT Line, CSTRING String, INT Length)

Parameter	Description
Line	Index of the line being targeted.
String	The new string that will replace the line.
Length	The number of characters to replace the target with, or -1 for the entire source string.

This method will replace an entire line with a new text string. If the new string contains line feeds, then multiple lines will be inserted at the target position. It is possible to limit the number of characters inserted from the source string by setting the Length parameter. To insert all characters from the source string, set a Length of -1.

ReplaceText Replaces all text within an entire document or limited range.

ERR sci::ReplaceText(OBJECTPTR Object, CSTRING Find, CSTRING Replace, STF Flags, INT Start, INT End)

Parameter	Description
Find	The keyword string to find.
Replace	The string that will replace the keyword.
Flags	Optional flags.
Start	The start of the search - set to zero if covering the entire document. If -1, starts from the current cursor position.
End	The end of the search - set to -1 if covering the entire document.

The ReplaceText method will replace all instances of the Find string with the content of the Replace string, between a given Start and End point. The STF::CASE, STF::SCAN_SELECTION and STF::EXPRESSION are valid flag options for this method (see FindText for details).

ScrollToPoint Scrolls text by moving the Page.

ERR sci::ScrollToPoint(OBJECTPTR Object, INT X, INT Y)

Parameter	Description
X	New horizontal position.
Y	New vertical position.

This method will scroll text in the Scintilla document by moving the page position.

SelectRange Selects a range of text, can also deselect all text.

ERR sci::SelectRange(OBJECTPTR Object, INT Start, INT End)

Parameter	Description
Start	The character at which the selection will start.
End	The character at which the selection will end. If negative, the last character in the document will be targeted.

This method will select an area of text between a start and end point, measured in characters. It can also deselect all text if no arguments are provided.

SetFont Changes the font that is used for text display.

ERR sci::SetFont(OBJECTPTR Object, CSTRING Face)

Parameter	Description
Face	The name of the new font face.

Call SetFont() to change the font face that is used for displaying text. The string format follows the standard for font requests, e.g. Helvete:12:Bold Italic:#ff0000. Refer to the Face field in the Font class for more details.

If the new face is invalid or fails to load, the current font will remain unchanged.

TrimWhitespace Strips trailing white-space from the document.

ERR sci::TrimWhitespace(OBJECTPTR Object)

The TrimWhitespace method will remove trailing white-space from every line in the document. Both tabs and spaces are considered white-space - all other characters shall be treated as content.

The position of the cursor is reset to the left margin as a result of calling this method.

SCIF Type

Optional flags.

Name	Description
SCIF::DETECT_LEXER	Automatic lexer detection will occur on initialisation and at any time that a source file is loaded.
SCIF::DISABLED	Read-only. This flag is set if the Scintilla object has been deactivated with the Disable action.
SCIF::EDIT	Must be defined if the document is to be editable via user input.
SCIF::EXT_PAGE	Extends the length of the document by one blank page. This is a visual effect that only has an impact when the user scrolls to the end of the document.

SCLEX Type

Scintilla Lexers. These codes originate from the Scintilla library.

Name	Description
SCLEX::ASP	Active Server Pages
SCLEX::ASSEMBLER	Assembler
SCLEX::BASH	Bash
SCLEX::BATCH	Batch
SCLEX::CPP	C or C++
SCLEX::CSS	CSS
SCLEX::DIFF	Diff
SCLEX::ERRORLIST	ErrorList
SCLEX::FLUID	Fluid
SCLEX::HTML	HTML
SCLEX::MAKEFILE	Makefile
SCLEX::PASCAL	Pascal
SCLEX::PERL	Perl
SCLEX::PHPSCRIPT	PHP Script
SCLEX::PROPERTIES	Properties
SCLEX::PYTHON	Python
SCLEX::REBOL	Rebol
SCLEX::RUBY	Ruby
SCLEX::SQL	SQL
SCLEX::VB	Visual Basic
SCLEX::VBSCRIPT	VBScript
SCLEX::XML	XML

SEF Type

Flags for EventCallback and EventFlags

Name	Description
SEF::CURSOR_POS	The cursor position has changed.
SEF::FAIL_RO	User attempt to edit read-only content.
SEF::MODIFIED	The content has changed to a modified state, i.e. the user has made an edit. The modified state will remain until the content is saved.
SEF::NEW_CHAR	At least one new character has been inserted.

STF Type

Scintilla search flags.

Name	Description
STF::BACKWARDS	Search backwards.
STF::CASE	Case sensitive search.
STF::EXPRESSION	Search text is a regular expression.
STF::MOVE_CURSOR	The cursor is moved to the discovered string. If not set, the string is auto-selected.
STF::SCAN_SELECTION	Limit search to within the user's current selection.
STF::WRAP	Wrap search at the end of the document.