EditorControl

Far Manager

EditorControl

The EditorControl function provides access to the low level API of the internal editor.
int WINAPI EditorControl(
  int Command,
  void* Param
);

Parameters

Command
Control command type. Can be one of the following (EDITOR_CONTROL_COMMANDS enum):
CommandDescription
ECTL_ADDCOLOR Specifies color for a line area. This command can be applied several times to the same line to specify several color areas. Param points to an EditorColor structure. If the specified line does not exist, this command will return FALSE, otherwise TRUE.
ECTL_ADDSTACKBOOKMARK Create navigation position ("stack bookmark") at current editor position. All navigation positions with index greater then current one will be deleted. Param must be NULL. If command is processed successfully, this command returns TRUE, otherwise FALSE.
ECTL_CLEARSTACKBOOKMARKS Deletes all navigation positions. Param must be NULL.
ECTL_DELETEBLOCK Deletes the block currently selected in the editor. Returns TRUE if the block has been deleted successfully or FALSE in case the editor is locked (the user pressed Ctrl-L) or no block is selected. Param must be NULL.
ECTL_DELETECHAR Deletes the character under cursor. Param must be NULL.
ECTL_DELETESTACKBOOKMARK Deletes specified navigation position. Param contains index of navigation position to be deleted (0 and greater) or -1 for deleting current navigation position. Count of navigation positions can be recieved after executing ECTL_GETSTACKBOOKMARKS command with Param containing NULL.
If command is processed successfully, this command returns TRUE, otherwise FALSE.
ECTL_DELETESTRING Deletes the current line. Param must be NULL.
ECTL_EDITORTOOEM Converts text from the editor codepage to the OEM codepage. Param points to an EditorConvertText structure.
ECTL_EXPANDTABS Expands all tabulation characters in a line to spaces. Param points to an integer variable that contains the number of the line to expand or -1 to process the current line.
ECTL_GETBOOKMARKS Returns information about bookmarks for the current editor. Param points to an EditorBookMarks structure.
This command returns FALSE in case:
  1. the file is not yet open;
  2. Param is NULL;
If the command succeeds TRUE is returned.
ECTL_GETSTACKBOOKMARKS Returns information about navigation positions ("stack bookmarks") for the current editor.
Param points to an EditorBookMarks structure or contains NULL. This command returns count of navigation positions were successfully set (or summary navigation positions count in case if Param was NULL).
ECTL_GETCOLOR Gets the color of a line area. Param points to an EditorColor structure. If the specified string or the specified color area does not exist, this command will return FALSE, otherwise TRUE.
ECTL_GETINFO Gets editor information. Param points to an EditorInfo structure.
ECTL_GETSTRING Gets information about a line. Param points to an EditorGetString structure. The received string will be in the editor codepage.
// get the first line of the edited file
struct EditorGetString egs;
egs.StringNumber=0;
Info.EditorControl(ECTL_GETSTRING,&egs);
ECTL_INSERTSTRING Inserts a new line at the current cursor position and moves the cursor to the first position in the new line or to the indented position. If Param oints to an integer variable containing the value 1, indent will be used when executing this command. To disable indent, set Param to NULL or pass 0 in the variable pointed to by Param. The indent behaviour is the same as if the user presses <Enter> in the editor; for example, spaces and tabs are not inserted into the new line if it does not contain any characters after the new cursor position.
// insert an empty string without indentation
Info.EditorControl(ECTL_INSERTSTRING,0);
ECTL_INSERTTEXT Inserts text at the current cursor position. Param points to a null-terminated text string in the OEM codepage. The command correctly processes newline characters (CR). The text is processed in the same way as it it had been entered from the keyboard.
// insert the string "Text" at the current cursor position
Info.EditorControl(ECTL_INSERTTEXT,"Text");
ECTL_NEXTSTACKBOOKMARK Go to next navigation position.
Param must be NULL. If command is processed successfully, this command returns TRUE, otherwise FALSE.
ECTL_OEMTOEDITOR Converts text from the OEM codepage to the editor codepage. Param points to an EditorConvertText structure.
ECTL_PREVSTACKBOOKMARK Go to previous navigation position.If there were no navigation commands after last ECTL_ADDSTACKBOOKMARK command, current editor position will be saved as a new navigation position before executing this command.
Param must be NULL. If command is processed successfully, this command returns TRUE, otherwise FALSE.
ECTL_PROCESSINPUT Passes an INPUT_RECORD structure to the internal editor for processing. Param points to an INPUT_RECORD structure.
Note: if your plugin exports the ProcessEditorInput function, the data in Param will be immediately passed to that function. The scheme is simple:
case ECTL_PROCESSINPUT:
  if (ProcessEditorInput(Param))
    return(TRUE);
  ...
So if you use EditorControl(ECTL_PROCESSINPUT) inside the ProcessEditorInput function, you should take care to avoid infinite recursion.
ECTL_PROCESSKEY This command allows to send keystrokes to the internal editor. The codes of the keystrokes are passed in Param.
The internal key codes are used (see farkeys.hpp).
This command always returns TRUE.
// go to the end of the file
Info.EditorControl(ECTL_PROCESSKEY,(void*)KEY_CTRLEND);
ECTL_QUIT Closes the editor. Any unsaved information will be lost. Param must be NULL. This command always returns TRUE.
ECTL_READINPUT Fills the INPUT_RECORD structure with data recieved from the standard input device. Param points to an INPUT_RECORD (this structure is defined in Win32 API and used by the ReadConsoleInput function).
ECTL_REALTOTAB Converts real string position to screen position. If string does not contain tabulation characters, source and result positions will be equal. Param points to an EditorConvertPos structure.
ECTL_REDRAW Redraws the editor window. Param must be NULL.
ECTL_SAVEFILE Saves the file currently being edited. Param points to anEditorSaveFile structure. If Param is NULL, the default file name and format (DOS-format - newline is replaced by "\r\n", Unix-format - "\n"). If the file is saved successfully, this command returns TRUE, otherwise FALSE.
ECTL_SELECT Selects or deselects a block. Param points to an EditorSelect structure.
ECTL_SETKEYBAR Allows to control key bar titles in the editor:
Param = NULL - restores the previous value
Param = -1 - redraws the key bar
Param = pointer to a KeyBarTitles structure.

This command cannot be used in the code that processes the editor event EE_READ, because when this event is processed, the key bar titles object does not yet exist.
This command returns TRUE on success or FALSE if it wasn't possible to set the key bar titles (if the key bar titles object does not yet exist).

ECTL_SETPARAM Changes the settings of the current editor. Param points to an EditorSetParameter structure.
This function returns TRUE if the settings have been successfully changed or FALSE otherwise.
ECTL_SETPOSITION Sets the cursor position. Param points to an EditorSetPosition structure.
ECTL_SETSTRING Sets the text of a line. Param points to an EditorSetString structure. The new string should be in the editor codepage.
ECTL_SETTITLE DrawLine\DrawLine.cpp: The SetTitle() function is used Sets the editor window title (top status line). The standard title will be automatically restored after the plugin has finished processing. Param points to a null-terminated text string that will be used as the title.
// DrawLine\DrawLine.cpp: SetTitle function
Info.EditorControl(ECTL_SETTITLE,(char *)GetMsg(IDTitle));
ECTL_TABTOREAL Converts screen cursor position to a real string position. If string does not contain tabulation characters, source and result positions will be equal. Param points to an EditorConvertPos structure.
ECTL_TURNOFFMARKINGBLOCK Resets the editor flag that is set while the user is marking a block in the editor. This flag is internal to FAR Manager and is not used by plugins. However, minor (mostly cosmetic) defects may appear if the user starts marking a block, then launches your plugin (or it is lunched automatically) and the plugin modifies, for example, the cursor position. Therefore, you should use this command before returning control to the FAR editor if your plugin modifies the text in the editor, block selection or cursor position.
Param must be NULL.
Param
Points to control command parameters. Read the description of the Command parameter for concrete information.

Return value

If the function succeeds, the return value is TRUE. If the function fails, FALSE is returned.

Remarks

The editor window contents is updated upon any active user operation. Call the ECTL_REDRAW command to force an update after any changes to the contents.
See also: