# 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):

Command | Description
--- | ---
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: the file is not yet open; 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 | 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:
AdvControl, Control