Table of Contents
16.16 TextEditor (gb.form.editor)
This control is an advanced text editor with support for syntax highlighting and has the following special properties:
- Highlighting: C, C++, Css, Diff, Gambas, Highlight, Html, Javascript, Sh, Sql and Webpage.
- Fully managed editing including copy, paste, cut, undo and redo.
- Context menu, text search and selection of an editor line.
- Selectable display functions such as line numbering, indicators for folding blocks, indicators for matching brackets, bookmarks, tab extension, breakpoint indicators and more.
To create a new TextEditor object:
Dim hTextEditor As TextEditor hTextEditor = New TextEditor ( Parent As Container ) [ As "EventName" ]
This class behaves like a read-only array.
Dim hTextEditor As TextEditor Dim hTextEditorLine As _TextEditor_Line hTextEditorLine = hTextEditor [ Line As Integer ]
A virtual object representing a specific line is returned. The optional parameter ‘Line’ is the line number of the returned object.
16.16.1 Properties
The TextEditor class has these properties:
| Property | Data type | Description |
|---|---|---|
| Bookmarks | Integer [ ] | Returns or defines the list of rows with a bookmark. |
| Border | Boolean | Determines or sets whether the control has a border. |
| Breakpoints | Integer [ ] | Returns the list of lines with a breakpoint or defines this list. |
| CloseBraces | Boolean | Returns or sets whether brackets are closed automatically. Braces include parentheses ( & ), angle brackets [ & ] and curly braces { & }. If you press ( without text in front of it, the closing bracket ( & ) is set to the right of the cursor. If you press ( with text immediately to the right of it, only the one ( (normally) is created. Select any amount of text and press ( to automatically add both curly braces to both ends of the text. |
| CloseStrings | Boolean | Returns or sets whether strings are automatically closed. If you press ‘ without text in front of it, the closing ’ is generated to the right of the cursor. If you press ‘ while there is text immediately to the right, only a ’ will be generated (normally). Select any amount of text and press ‘ to automatically add both inverted commas to both ends of the text. |
| Column | Integer | Delivers the cursor position in the current line. The first character of the line is at position zero. |
| Count | Integer | Returns the number of lines. |
| Current | _TextEditor_Line | Returns the current line as a virtual object. Note: The virtual class is described in detail at https://gambaswiki.org/wiki/comp/gb.form.editor/_texteditor_line. |
| DiffMode | Boolean | Returns or sets whether the ‘Diff mode’ is activated. If ‘Diff mode’ is enabled, the editor becomes read-only and displays any added or removed text defined with the EnterDiffMode method. |
| DisabledBreakpoints | Integer [ ] | Returns or sets the list of lines with a disabled breakpoint. |
| EndOfLine | Integer | Returns the line break separator used or set by the editor. The possible values are: gb.Unix for lines separated by Chr$(10), gb.Windows for lines separated by Chr$(13) & Chr$(10) or gb.Mac for lines separated by Chr$(13). |
| Font | Font | Returns or sets the font used to draw text in the control. To change the font of the control at runtime: Use the Font property of another control. Create a font object from a character string that describes the font. |
| Highlight | String | Returns or sets the highlight mode. It can take one of the following values: ‘c’, ‘c++’ or ‘cplusplus’, ‘css’, ‘custom’, ‘diff’, ‘gambas’, ‘html’, ‘none’, ‘javascript’, ‘sh’, ‘sql’, ‘webpage’. If the highlight mode is set to ‘custom’, ‘none’ or a null string, the highlight event is triggered every time a line needs to be highlighted. If you do not implement the handler for this event, nothing will be highlighted. The property is NULL by default. The required data is the subclass name of the highlight syntax - not one of the constants of the Highlight class. |
| Keywords | String [ ] | Returns the language keywords associated with the editor mode defined by the ‘Mode’ property. |
| LastColumn | Integer | Returns the old column position before a cursor move. This property is only relevant during a change event handler. |
| LastLine | Integer | Returns the old line position before a cursor movement. This property is only relevant during a change event handler. |
| Length | Integer | Calculates the length of the ‘Text’ property as UTF-8 characters and returns it. |
| Line | Integer | Returns the position of the cursor line. The first line is at position zero. |
| LineHeight | Integer | Returns the height of a line in pixels. |
| LineNumberOffset | Integer | Returns or sets the offset of the line number. The value of this property is added to the actual line number for the display. |
| Max | Integer | Returns the number of rows - minus one. |
| Mode | String | Returns or sets the editor mode. The editor mode determines how the text is highlighted and how the editor behaves. The property can have the same values as the Highlight property. If the editor mode is NULL, then there is no user-defined editor behaviour and the text is only highlighted if the Highlight property is set. |
| Overwrite | Boolean | Returns or sets the property whether the editor is in overwrite mode. |
| ReadOnly | Boolean | Returns or sets the value of the property whether the editor is read-only. |
| ScrollBar | Integer | Returns or sets which scrollbars are displayed. A list of the constants that can be used with this property can be found in the Scroll class. |
| ScrollH | Integer | Returns the height of the (text) content. |
| ScrollHeight | Integer | Returns the height of the (text) content. |
| ScrollW | Integer | Returns the width of the (text) content. |
| ScrollWidth | Integer | Returns the width of the (text) content. |
| ScrollX | Integer | Returns or sets the horizontal scroll position. |
| ScrollY | Integer | Returns or sets the vertical scroll position. |
| Selected | Boolean | Returns True if a text is selected. |
| SelectedText | String | Returns the text selected in the editor. |
| SelectionColumn | Integer | Returns the column position of the selection marker. If no text is selected, the same value is returned as in the Column property. |
| SelectionLine | Integer | Returns the row position of the text selection. If no text is selected, the same value is returned as in the Line property. |
| ShowBraces | Boolean | Returns whether matching brackets are highlighted or sets the value of the property. |
| ShowCurrent | Boolean | Returns whether the current line is highlighted or sets the value of the property. |
| ShowCursor | Boolean | Returns whether the cursor is visible or sets the value of the property. |
| ShowExpand | Boolean | Returns whether the functions can be expanded and collapsed or sets the value of the property. |
| ShowIcon | Boolean | Returns whether the breakpoint or bookmark icons are visible or sets the value of the property. |
| ShowIndent | Boolean | Returns whether the editor displays tab characters as small grey arrows or sets the value of the property. |
| ShowLimit | Boolean | Returns whether the function limits are visible or sets the value of the property. |
| ShowLineNumber | Boolean | Returns whether the editor displays line numbers or sets the value of the property. |
| ShowModified | Boolean | Returns or sets whether the modified lines are highlighted in colour in the margin. |
| ShowPosition | Boolean | Returns whether the current position of the cursor is displayed in the editor or sets the value of the property. |
| ShowPreview | Boolean | Returns whether the editor replaces its scrollbar with a minimised preview or sets the value of the property. |
| ShowSpaces | Boolean | Returns whether spaces at the end of a line are displayed as dots or sets the value of the property. |
| StopLine | * | Returns or sets the debugger stop line. |
| Theme | TextHighlighterTheme | Returns or sets the theme used for highlighting. Replaces the Styles property since version 3.17. |
| TabIndent | Boolean | Returns or sets whether the ident consists of tab characters. If this property is TRUE, a ‘\t’ character is used for each indent. If this property is FALSE, the number of spaces specified by the TabSize property is used for each indent. |
| TabSize | Integer | provides or sets the tab size. This is the number of spaces used for indentation. |
| Text | String | Returns or sets the text content of the editor. |
| View | TextEditor | This property allows different editors to share the same content. If this property is NULL (default setting), then the editor has its own content. Otherwise, the editor uses the content of its own view. |
| Wrap | Boolean | Returns or specifies whether the editor wraps the lines to fit the width of the control. If this property is set, you will therefore *not* have a horizontal scrollbar. |
Table 16.16.1.1 : Properties of the TextEditor class
16.16.2 Methods
The TextEditor class has these methods:
| Method | Return type | Description |
|---|---|---|
| Append ( Text As String ) | - | Appends a text to the end of the editor without moving the cursor. Text is the text that is inserted at the end of the editor content. The text can be multi-line. In this case, the line separator is always ‘\n’. |
| Begin ( ) | - | Starts a series of changes that can be undone in one go. |
| End ( ) | - | Ends a series of changes. |
| Clear ( ) | - | Deletes the text content of the editor. |
| CollapseAll ( ) | - | Collapses all functions. |
| ExpandAll ( ) | - | Expands all functions. |
| Copy ( ) | - | Copies the currently selected text to the clipboard. |
| Paste ( ) | - | Pastes the contents of the clipboard into the editor. |
| CursorAt ( [ Line As Integer, Column As Integer ] | Point | Converts a cursor position into a pixel position. The two optional parameters Line and Column define the cursor position. If they are omitted, they are replaced by the (current) cursor position. This method returns the position in pixels as a Point object. |
| Cut ( ) | - | Copies the currently selected text to the clipboard and deletes the selected text. |
| EnterDiffMode ( Added As Integer[], Removed As Collection ) | - | Calls the ‘diff mode’. Added is the list of line numbers that are added. These lines are highlighted with the colour Highlight.Added. Removed is a collection of string arrays indexed by the line number, where the string array contains the lines of text that were removed at that line number. The removed lines are highlighted with the colour Highlight.Removed. In ‘Diff mode’, the editor becomes read-only. |
| LeaveDiffMode ( ) | Leaves diff mode. The editor returns to its normal state. | |
| FindNextDiff ( Y As Integer ) | Integer | Finds the row position of the next difference. Y is the row position at which the search begins. If no difference is found, -1 is returned. |
| FindPreviousDiff ( Y As Integer ) | Integer | Finds the row position of the previous difference. Y is the row position at which the search begins. If no difference is found, -1 is returned. |
| FindNextLimit ( Y As Integer ) | Integer | Finds the row position of the next function limit. Y is the row position at which the search begins. If no limit is found, -1 is returned. |
| FindNextString ( Search As String, ByRef Start As Integer [ , ByRef Column As Integer ] ) | String | Search for the next line that contains a specific string or for the next occurrence of a string. String is the string to be searched for. The search is not case-sensitive. Start is the line position at which the search begins. Column is the optional line position from which to search. If Column is specified, the character string is searched from this column. The result is returned in the arguments Start and Column. If no string is found, -1 is returned. Returns the line number of the next search string found from the Start position. Returns -1 if no string was found. Searches for a given search string from the given start line number and returns the line number of the next successful search, where the first line is 0. Returns -1 if the search string is not found. The search is not case-sensitive. |
| FindPreviousLimit ( Y As Integer ) | Integer | Finds the line position of the previous function limit. Y is the row position at which the search begins. If no boundary is found, -1 is returned. |
| FindPreviousString ( Search As String, ByRef Start As Integer [ , ByRef Column As Integer ] ) | Integer | Finds the previous line containing a specific string or finds the previous occurrence of a string. String is the string to be searched for. The search is not case-sensitive. Start is the line position at which the search begins. Column is the optional line position from which to search. If Column is specified, the string is searched from this column and the result is returned in the arguments Start and Column. If no string is found, -1 is returned. Returns the line number of the next ‘reversed’ search string found from the Start position. Returns -1 if not found. Searches backwards for a given search string from the given start line number and returns the line number of the successful search, where the first line is 0. Returns -1 if the search string is not found. The search is not case-sensitive. |
| GetHighlight ( Y As Integer, ByRef Symbols As String[], ByRef Types As Integer[] ) | - | Returns the highlighting of a specific line. Y is the line number. The list of tokens is returned in symbols. The highlight colours for each token are returned in Types. If no highlighting is assigned to the specified line, Symbols and Types are set to NULL. |
| GetIndent ( StartLine As Integer [ , EndLine As Integer ] ) | String | Returns the indent of a line or a range of lines. StartLine is the first line of the range. EndLine is the last line of the range (not included). If not specified, the indent of the only start line is returned. The indent is the smaller part of the initial spaces of each line. |
| GetSelectedLines | String [ ] | Since version 3.16: Returns the selected lines, if any. The selection is first expanded so that partially selected lines are included in the selection. If nothing is selected, NULL is returned. |
| Goto ( NX As Integer, NY As Integer [ , Mark As Boolean ] ) | - | Moves the cursor to the specified position. NX and NY are the column and row of the new position respectively. If Mark is TRUE, the text between the old position and the new position is selected. |
| GotoCenter ( NX As Integer, NY As Integer ) | - | Moves the cursor to the specified position and centres the view around this position. NX and NY are the column and row of the new position respectively. Moves the cursor to the centre of the specified position NX (column number) and NY (row number). |
| HideSelection ( ) | - | Hides the current selection, if available. |
| HighlightString ( Text As String [ , IgnoreCase As Boolean, WordOnly As Boolean ] ) | - | Highlights a specific string anywhere in the editor. Text is the text to be highlighted. If IgnoreCase is TRUE, the upper and lower case of the text is ignored. If WordOnly is TRUE, the text is only highlighted if it is a whole word. The text is highlighted with the colour Highlight.Highlight. |
| Indent ( ) | - | Indents the selected text or the current line if there is no selected text. |
| Insert ( Text As String ) | - | Inserts a text at the current cursor position. Text is the text to be inserted. The text can be multi-line. In this case, the line separator is always ‘\n’. |
| IsVoid ( ) | Boolean | Returns True if the content of the editor is empty. |
| Load ( Path As String [ , AddNewLine As Boolean ] ) | - | Loads a file into the editor. Path is the path of the file to be loaded. If AddNewLine is TRUE, a line break is inserted at the end of the file if there is no line break. Loads a file from ‘ Path ’ into the TextEditor and optionally ensures that the last character is a line break. Example: TextEditor1.Load(‘/Filepath/Filename.txt’, True). This loads the file ‘/Filepath/Filename.txt’ into the editor and ensures that the last line of text contains a line break (adds a line break if the last line contains text). |
| Save ( Path As String ) | - | Saves the content of the editor to a file. Path is the path of the file. |
| LowerCase ( ) | - | Converts the selected text to lower case. If no text is selected, this method does nothing! |
| UpperCase ( ) | - | Converts the selected text to upper case. If no text is selected, this method has no effect! |
| Redo ( ) | - | The last undone text change in the editor is restored. |
| Undo ( ) | - | Undo the last text change in the editor. |
| Refresh ( ) | - | Updates the text in the editor. |
| Remove ( X1 As Integer, Y1 As Integer, X2 As Integer, Y2 As Integer [ , bRight As Boolean ] ) | - | Removes the text that is between two cursor positions. X1 and Y1 are the column and row of the first position. X2 and Y2 are the column and row of the other position. Set bRight to TRUE if the cursor was at the beginning of the selection. |
| Reset ( ) | - | Resets all change and storage indicators of each row. |
| RestoreCursor ( ) | - | Restores the cursor position and selection range that were saved with the SaveCursor() method. The calls to SaveCursor() and this method can be nested within one another. |
| Select ( Column As Integer, Line As Integer, Column2 As Integer, Line2 As Integer ) | - | Selects a specific text area. Column and Line define the starting column and line of the text area. Column2 and Line2 define the end column and line of the text area. |
| SelectAll ( ) | - | Highlights the entire text of the editor. |
| ShowFindPanel ( ) | - | Displays the text search field below the text field. |
| ShowGotoPanel ( ) | - | Displays the field for the jump line. |
| ToColumn ( X As Integer, Y As Integer ) | Integer | Returns the column that is under the specified mouse pointer position. X and Y are the position of the mouse pointer relative to the TextEditor control. |
| ToLine ( Y As Integer ) | Integer | Returns the line that is under the specified mouse pointer position. Y is the vertical position of the mouse pointer relative to the TextEditor control. |
| ToPos ( [ Line As Integer, Column As Integer ] ) | Point | Returns the relative position of a specific cursor position in pixels. Column and Line are the column and line position. If it is omitted, the current cursor position is used. |
| ToPosX ( [ Column As Integer, Line As Integer ] ) | Integer | Returns the relative horizontal position of a specific cursor position in pixels. Column and Line are the column and line position. If nothing is specified, the current cursor position is used. |
| ToPosY ( [ Line As Integer ] ) | Integer | Returns the relative vertical position of a specific cursor position in pixels. Line is the line position. If it is omitted, the current cursor position is used. |
| Unindent ( ) | - | Indents the selected text or the current line if no text is selected. |
Table 16.16.2.1 : Methods of the TextEditor class
16.16.3 Events
The TextEditor class has the following relevant events:
| Event | Description |
|---|
| Change ( ) | This event is triggered when the content of the editor has changed. |
| Cursor ( ) | This event is triggered when the cursor has been moved. |
| Highlight ( Text As String ) | This event is triggered when a line of text needs to be highlighted. Text is the text that is to be highlighted. This event is only triggered if the Highlight property is set to ‘custom’, ‘none’ or a null string. |
| Margin ( ) | This event is triggered when the user has clicked twice within the margin. The cursor was moved to the clicked line before the event was triggered. |
| Scroll ( ) | This event is triggered when the editor has been scrolled. |
Table 16.16.3.1 : Events of the TextEditor class
16.16.3.1 Example project
The project presented allows you to,
- to create a new HTML document,
- open an HTML file and insert its content into the editor,
- edit the HTML text in the editor and save it in the (existing) file,
- to save the HTML text in a file under a freely chosen name in a file,
- to switch the text highlighting for the HTML markup language on and off,
- to search for text in the editor,
- to render the HTML text and display it in an internal web browser and
- to print the content of the HTML document and
- to call up extensive documentation (PDF document) with the F1 key.
The graphical user interface (GUI) is presented in the next section.
16.16.3.1.1 User interface (GUI)
Figure 16.16.3.1.1: User interface : Editor
Figure 16.16.3.1.2: User interface: Display of the web page in the web browser
16.16.3.1.2 Project archive
The project is made available to you in a project archive in the download area.
Download
Project and documentation
Download