Difference between revisions of "CudaText API"

From Lazarus wiki
Jump to navigationJump to search
(Categuntaunta)
(new API)
 
(135 intermediate revisions by 2 users not shown)
Line 10: Line 10:
 
=Event plugins=
 
=Event plugins=
  
To make plugin react to some program event, add method to class Command. For example, method "Command.on_save" will be called by program event "on_save" - if plugin is subscribed to that event. Event methods have param "ed_self": this is Editor object in which event occured. This object is the same as object "ed" in most cases ("ed" always refers to focused editor), but in some cases event occurs in inactive editor, e.g. command "Save all tabs" calls event "on_save" for passive tabs.
+
To make plugin react to some program event, add method to class Command. For example, method "Command.on_save" will be called by program event "on_save" - if plugin is subscribed to that event. Event methods have param "ed_self": this is Editor object in which event occurred. This object is the same as object "ed" in most cases ("ed" always refers to focused editor), but in some cases event occurs in inactive editor, e.g. command "Save all tabs" calls event "on_save" for passive tabs.
  
 
Plugin can subscribe to events in several ways:
 
Plugin can subscribe to events in several ways:
Line 32: Line 32:
 
* on_save_pre(self, ed_self): Called before saving file. Method can return False to disable saving, other value is ignored.
 
* on_save_pre(self, ed_self): Called before saving file. Method can return False to disable saving, other value is ignored.
 
* on_save_naming(self, ed_self): Called before saving untitled tab, to get suggested filename without path and extension. Method must return valid filename string or None.
 
* on_save_naming(self, ed_self): Called before saving untitled tab, to get suggested filename without path and extension. Method must return valid filename string or None.
* on_start(self, ed_self): Called once on program start. ed_self is None.
+
* on_delete_file(self, ed_self, filename): Called on running command "File / Close and delete file". ed_self is None.
 +
* on_start(self, ed_self): Called once on program start. Called early, before applying config files. ed_self is None.
 +
* on_start2(self, ed_self): Called once on program start. Called later than on_start, after configs are applied, just before the main form shows. ed_self is None.
 +
* on_init_plugins_menu(self, ed_self): Called after filling the "Plugins" menu. On startup, it is called after on_start/on_start2, and after app goes into 'idle' state for the first time. App inits the "Plugins" menu in the 'idle' state. Event is also called when app has to update the "Plugins" menu again, e.g. after installing plugin from zip-file. ed_self is None.
 
* on_exit(self, ed_self): Called on exiting application. This event is lazy, ie it's called only for already loaded plugins. ed_self is None.
 
* on_exit(self, ed_self): Called on exiting application. This event is lazy, ie it's called only for already loaded plugins. ed_self is None.
 
* on_app_activate(self, ed_self): Called when application window gets focus. ed_self is None.
 
* on_app_activate(self, ed_self): Called when application window gets focus. ed_self is None.
 
* on_app_deactivate(self, ed_self): Called when application window looses focus. ed_self is None.
 
* on_app_deactivate(self, ed_self): Called when application window looses focus. ed_self is None.
 +
* on_cli(self, param1, param2...): Called when application gets command-line parameter "-p=cuda_pluginname#param1#param2...". Count of params is plugin-defined, e.g. Differ plugin needs 2 params. This event is not sent to all plugins, but only to the single specified plugin.
  
 
==Events - Tabs==
 
==Events - Tabs==
  
* on_tab_change(self, ed_self): Called after active tab is changed.
+
* on_tab_change(self, ed_self): Called after active UI-tab is changed.
* on_tab_move(self, ed_self): Called after closing a tab (another tab is already activated), or moving a tab (by drag-n-drop, or UI command).
+
* on_tab_menu(self, ed_self): Called just before showing popup menu for UI-tab title. Method can return False to disable the standard popup menu, other return value is ignored.
 +
* on_tab_move(self, ed_self): Called after closing a UI-tab (another UI-tab is already activated), or moving a UI-tab (by drag-n-drop, or UI command).
  
 
==Events - Editor==
 
==Events - Editor==
  
 
* on_change(self, ed_self): Called after editor text is changed.
 
* on_change(self, ed_self): Called after editor text is changed.
* on_change_slow(self, ed_self): Called after editor text is changed, and few seconds (option) passed. Used in CudaLint plugin, it needs to react to change after a delay.
+
* on_change_slow(self, ed_self): Called after editor text is changed, and small pause is passed (CudaText option "py_change_slow"), and application "idle" event happens (no keyboard/mouse input for 1-2sec).
* on_caret(self, ed_self): Called after editor caret position and/or selection is changed.
+
* on_caret(self, ed_self): Called after caret position/selection is changed.
 +
* on_caret_slow(self, ed_self): Called after caret position/selection is changed, and small pause is passed. Pause is CudaText option "py_caret_slow".
 
* on_insert(self, ed_self, text): Called before inserting a text. Method can return False to disable insertion, other return value is ignored.
 
* on_insert(self, ed_self, text): Called before inserting a text. Method can return False to disable insertion, other return value is ignored.
 
* on_key(self, ed_self, key, state): Called when user presses a key in editor. Param "key" is int key code; values are listed in the module cudatext_keys. Param "state" is string of chars: "a" if Alt pressed, "c" if Ctrl pressed, "s" if Shift pressed, "m" if Meta (Windows-key) pressed. Method can return False to disable key processing, other return value is ignored.
 
* on_key(self, ed_self, key, state): Called when user presses a key in editor. Param "key" is int key code; values are listed in the module cudatext_keys. Param "state" is string of chars: "a" if Alt pressed, "c" if Ctrl pressed, "s" if Shift pressed, "m" if Meta (Windows-key) pressed. Method can return False to disable key processing, other return value is ignored.
Line 57: Line 63:
 
* on_mouse_stop(self, ed_self, x, y): Called when mouse cursor stops (for a short delay) over editor. Params "x", "y" are mouse editor-related coords.
 
* on_mouse_stop(self, ed_self, x, y): Called when mouse cursor stops (for a short delay) over editor. Params "x", "y" are mouse editor-related coords.
 
* on_hotspot(self, ed_self, entered, hotspot_index): Called when mouse cursor moves in/out of hotspot. See ed.hotspots() API.
 
* on_hotspot(self, ed_self, entered, hotspot_index): Called when mouse cursor moves in/out of hotspot. See ed.hotspots() API.
* on_state(self, ed_self, state): Called after some app state is changed. Param "state" is one of APPSTATE_nnnn constants. ed_self is None.
 
* on_state_ed(self, ed_self, state): Called after some editor state is changed. Param "state" is one of EDSTATE_nnnn constants.
 
 
* on_snippet(self, ed_self, snippet_id, snippet_text): Called when user chooses snippet to insert, in ed.complete_alt() call.
 
* on_snippet(self, ed_self, snippet_id, snippet_text): Called when user chooses snippet to insert, in ed.complete_alt() call.
  
Line 65: Line 69:
 
* on_click(self, ed_self, state): Called after mouse click on text area. Param "state": same meaning as in on_key.
 
* on_click(self, ed_self, state): Called after mouse click on text area. Param "state": same meaning as in on_key.
 
* on_click_dbl(self, ed_self, state): Called after mouse double-click on text area. Param "state": same meaning as in on_key. Method can return False to disable default processing.
 
* on_click_dbl(self, ed_self, state): Called after mouse double-click on text area. Param "state": same meaning as in on_key. Method can return False to disable default processing.
 +
* on_click_right(self, ed_self, state): Called after mouse right-click. Param "state": same meaning as in on_key. Method can return False to disable default processing.
 
* on_click_gutter(self, ed_self, state, nline, nband): Called on mouse click on gutter area. Param "state": same as in on_key. Param "nline": index of editor line. Param "nband": index of gutter band. Method can return False to disable default processing.
 
* on_click_gutter(self, ed_self, state, nline, nband): Called on mouse click on gutter area. Param "state": same as in on_key. Param "nline": index of editor line. Param "nband": index of gutter band. Method can return False to disable default processing.
 
* on_click_gap(self, ed_self, state, nline, ntag, size_x, size_y, pos_x, pos_y): Called after mouse click on inter-line gap: see Editor.gap(). Param "state": same meaning as in on_key. Other params: properties of clicked gap.
 
* on_click_gap(self, ed_self, state, nline, ntag, size_x, size_y, pos_x, pos_y): Called after mouse click on inter-line gap: see Editor.gap(). Param "state": same meaning as in on_key. Other params: properties of clicked gap.
 
* on_click_link(self, ed_self, state, link): Called after link/URL in the editor is activated by click or double-click (event is not called on URL opening from Command Palette or from editor context menu). Param "state": same meaning as in on_key. Param "link": link string. Method can return False to disable default program action.
 
* on_click_link(self, ed_self, state, link): Called after link/URL in the editor is activated by click or double-click (event is not called on URL opening from Command Palette or from editor context menu). Param "state": same meaning as in on_key. Param "link": link string. Method can return False to disable default program action.
 +
 +
==Events - State changes==
 +
 +
* on_state(self, ed_self, state): Called after some app state is changed. Param "state" is one of APPSTATE_nnnn constants. ed_self is None.
 +
* on_state_ed(self, ed_self, state): Called after some editor state is changed. Param "state" is one of EDSTATE_nnnn constants.
 +
 +
Constants in "on_state":
 +
 +
* APPSTATE_LANG: Changed UI translation.
 +
* APPSTATE_THEME_UI: Changed UI-theme.
 +
* APPSTATE_THEME_SYNTAX: Changed syntax-theme.
 +
* APPSTATE_GROUPS: Changed UI-tab grouping mode (see top menu item "=").
 +
* APPSTATE_CONFIG_REREAD: App config file is re-read and applied.
 +
* APPSTATE_SESSION_LOAD_BEGIN: Session loading begins.
 +
* APPSTATE_SESSION_LOAD: Session loading completes (after APPSTATE_SESSION_LOAD_BEGIN).
 +
* APPSTATE_SESSION_LOAD_FAIL: Session loading fails (after APPSTATE_SESSION_LOAD_BEGIN).
 +
* APPSTATE_PROJECT: Current project in the Project Manager is changed.
 +
 +
* APPSTATE_API_SUBCOMMANDS: API call app_proc(PROC_SET_SUBCOMMANDS, ...).
 +
* APPSTATE_API_MENU_ADD: API menu_proc() added some menu item.
 +
* APPSTATE_API_MENU_REMOVE: API menu_proc() removed some menu item.
 +
* APPSTATE_API_MENU_CHANGE: API menu_proc() changed some menu item.
 +
 +
* APPSTATE_CODETREE_CLEAR: Code-Tree: content is cleared.
 +
* APPSTATE_CODETREE_BEFORE_FILL: Code-Tree: before filling the content.
 +
* APPSTATE_CODETREE_AFTER_FILL: Code-Tree: after filling the content.
 +
* APPSTATE_CODETREE_SET_SELECTION: Code-Tree double-click changed scroll pos, or app sync'ed Code-Tree with caret pos.
 +
 +
* APPSTATE_WINDOW: Changed state of the main window: minimized/normal/maximized/fullscreen. Read current state via app_proc(PROC_GET_WINDOW_STATE, "").
 +
 +
Constants in "on_state_ed":
 +
 +
* EDSTATE_WRAP: Word-wrap state is changed.
 +
* EDSTATE_TAB_TITLE: UI-tab title is changed.
 +
* EDSTATE_MODIFIED: Document modified state is changed.
 +
* EDSTATE_PINNED: UI-tab 'pinned' state is changed.
 +
* EDSTATE_READONLY: Read-only state is changed.
 +
* EDSTATE_ZOOM: Scale of document is changed, using Ctrl+MouseWheel or by a command.
 +
* EDSTATE_BOOKMARK: Bookmark is added or removed.
  
 
==Events - Smart commands==
 
==Events - Smart commands==
  
 
* on_complete(self, ed_self): Called by "auto-completion menu" command (default hotkey: Ctrl+Space). Method should read editor text, find all needed data, and call Editor.complete() API to show the actual auto-completion listbox to user. True return value means that plugin handled the event, don't call other plugins.
 
* on_complete(self, ed_self): Called by "auto-completion menu" command (default hotkey: Ctrl+Space). Method should read editor text, find all needed data, and call Editor.complete() API to show the actual auto-completion listbox to user. True return value means that plugin handled the event, don't call other plugins.
* on_func_hint(self, ed_self): Called by "show function-hint" command (default hotkey: Ctrl+Shift+Space). Method should return function-hint string (comma-separated parameters, brackets are optional). Empty string or None mean that no hint was found. True return value means that plugin handled the event, don't call other plugins.
+
* on_func_hint(self, ed_self): Called by "show function-hint" command (default hotkey: Ctrl+Shift+Space). Method should return function-hint string (comma-separated parameters, brackets are optional). Non-empty string result means that plugin handled the event, don't call other plugins. Empty string or None mean that no hint was found.
 
* on_goto_def(self, ed_self): Called by "go to definition" command (e.g. by mouse shortcut or by menu item in the editor context menu). Method must return True if it handled the command, otherwise None.
 
* on_goto_def(self, ed_self): Called by "go to definition" command (e.g. by mouse shortcut or by menu item in the editor context menu). Method must return True if it handled the command, otherwise None.
 
* on_goto_enter(self, ed_self, text): Called after user entered text in the Go To dialog. Method can return False to disable default processing.
 
* on_goto_enter(self, ed_self, text): Called after user entered text in the Go To dialog. Method can return False to disable default processing.
Line 79: Line 123:
  
 
* on_message(self, ed_self, id, text): Called on showing a text in the statusbar. Param "id" means statusbar column index, currently only value 0 is used ("text message" statusbar cell). Method can return False to disable usual showing of message. Param "ed_self" is None here.
 
* on_message(self, ed_self, id, text): Called on showing a text in the statusbar. Param "id" means statusbar column index, currently only value 0 is used ("text message" statusbar cell). Method can return False to disable usual showing of message. Param "ed_self" is None here.
* on_console_nav(self, ed_self, text): Called on double-clicking line, or calling context menu item "Navigate", in Python Console panel. Param "text" is line with caret. Param "ed_self" is None here.
+
* on_console_nav(self, ed_self, text): Called on double-clicking a line, or calling context menu item "Navigate", in the Console's multi-line memo field. Param "text" is Console memo line with caret. Param "ed_self" is None here.
* on_output_nav(self, ed_self, text, tag): Called on clicking line, or pressing Enter, in the Output or Validate panel. Param "text" is clicked line, param "tag" is int value associated with line. Event is called only if app cannot parse output line by itself using given regex, or regex is not set. Param "ed_self" is None here.
+
* on_console_complete(self, ed_self): Called when user presses hotkey of "auto-complete" in the Console input. Param "ed_self" is None here. True return value means that plugin handled the event, don't call other plugins.
 +
* on_output_nav(self, ed_self, text, tag): Called on double-clicking a line, or pressing Enter, in the Output/Validate panels. Param "text" is clicked line, param "tag" is int value associated with the line. Event is called only if app cannot parse output line by itself using given RegEx, or if RegEx is not set. Param "ed_self" is None here.
 +
* on_sidebar_popup(self, ed_self, caption): Called on right-click on sidebar (with bottom-bar) buttons. Param "caption" is caption of clicked button (this is non-translatable string, always in English). Param "ed_self" is None here.
  
 
==Events - Macros==
 
==Events - Macros==
  
* on_macro(self, ed_self, text): Called when command "macros: stop recording" runs. In text the "\n"-separated list of macro items is passed. These items were run after command "macros: start recording" and before command "macros: stop recording".
+
* on_macro(self, ed_self, text): Called when command "start/stop macro recording" stops the recording. Param "text" is string: "\n"-separated text of macro items, which were run during the macro recording.
** if item is "number" then it's simple command.
+
** if item is str(number) then it's simple command.
** if item is "number,string" then it's command with str parameter (usually it's command cCommand_TextInsert).
+
** if item is "number,string" then it's command with string parameter (usually it's command cCommand_TextInsert).
 
** if item is "py:string_module,string_method,string_param" then it's call of Python plugin (usually string_param is empty).
 
** if item is "py:string_module,string_method,string_param" then it's call of Python plugin (usually string_param is empty).
  
Line 112: Line 158:
 
Parameter can be in these forms:
 
Parameter can be in these forms:
  
* callable, ie name of a Python function, or just "lambda". Internally, callable will be converted to a weird string. Note that some functions do not support "callable form". You can detect this support by reading the code of "py/cudatext.py" module, which performs the convertions from callable to string.
+
* callable, ie name of a Python function, or just "lambda". Internally, callable will be converted to a weird string. Note that some functions do not support "callable form". You can detect this support by reading the code of "py/cudatext.py" module, which performs the conversions from callable to string.
* string "module=mmm;cmd=nnn;" - to call method nnn (in class Command) in plugin mmm, where mmm is usually sub-dir in the "cudatext/py", but can be any module name
+
* string "module=mmm;cmd=nnn;" - to call method nnn (in class Command) in plugin mmm, where mmm is usually sub-dir in the "cudatext/py", but can be any module name.
* string "module=mmm;cmd=nnn;info=iii;" - the same, and callback will get param "info" with your value
+
* string "module=mmm;cmd=nnn;info=iii;" - the same, and callback will get param "info" with your value.
* string "mmm.nnn" - the same, to call method, short form
+
* string "mmm.nnn" - the same, to call method, short form.
* string "module=mmm;func=nnn;" - to call function nnn in root of module mmm
+
* string "module=mmm;func=nnn;" - to call function nnn in root of module mmm.
* string "module=mmm;func=nnn;info=iii;" - the same, and callback will get param "info" with your value
+
* string "module=mmm;func=nnn;info=iii;" - the same, and callback will get param "info" with your value.
 +
* string "exec=command_line_params_here" - to handle the contents of callback (after prefix "exec=") as a command line passed to CudaText process. For example, here you can pass filenames of text/picture files, of .cuda-proj project files, of .cuda-session session files.
  
 
For example:
 
For example:
Line 137: Line 184:
  
 
Returns version of API. String, 3 dot-separated numbers.
 
Returns version of API. String, 3 dot-separated numbers.
 
API
 
 
Constant, int. It is the last number from app_api_version() complex result.
 
  
 
Example of version check:
 
Example of version check:
Line 146: Line 189:
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
 
   from cudatext import *
 
   from cudatext import *
   if API < 350:
+
   if app_api_version() < '1.0.350':
 
       msg_box('Plugin needs newer program version', MB_OK+MB_ICONWARNING)
 
       msg_box('Plugin needs newer program version', MB_OK+MB_ICONWARNING)
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 154: Line 197:
 
  app_path(id)
 
  app_path(id)
  
Returns file-system path. Possible values of "id":
+
Returns some file-system path. Possible values of "id":
  
 
* APP_DIR_EXE: Folder of program executable.
 
* APP_DIR_EXE: Folder of program executable.
* APP_DIR_SETTINGS: Folder "settings" (it should contain user.json file).
+
* APP_DIR_SETTINGS: Folder "settings" (which usually contains user.json file).
* APP_DIR_SETTINGS_DEF: Folder "settings_default".
+
* APP_DIR_SETTINGS_DEF: Folder "settings_default" (which usually contains default.json file).
 
* APP_DIR_DATA: Folder "data".
 
* APP_DIR_DATA: Folder "data".
* APP_DIR_PY: Folder "py" with Python files.
+
* APP_DIR_PY: Folder "py" (with Python codes).
* APP_DIR_INSTALLED_ADDON: Folder of last installed addon (for plugins it is folder in "py", for data-files it is folder in "data", for lexers it is folder "lexlib"). This dir is updated only if addon installed via file_open() or from app (Open dialog or command line).
+
* APP_DIR_INSTALLED_ADDON: Folder of last installed add-on. For plugins it is subfolder in "py", for data-files it is subfolder in "data", for lexers it is folder "data/lexlib". This path is internally updated when add-on was installed: via file_open() API; via "Open file" dialog when you open .zip file; via command-line with .zip file.
* APP_FILE_SESSION: Filename of current session. Default filename is "history session.json" without path. Missing path means that folder "settings" will be used.
+
* APP_FILE_SESSION: Filename of current session. Default filename is "history session.json" without path. Missing path means that session file is in the folder "settings".
* APP_FILE_RECENTS: Str: "\n"-separated filenames of recent files.
+
* APP_FILE_RECENTS: String, "\n"-separated filenames of recently used files.
  
 
===app_proc===
 
===app_proc===
Line 173: Line 216:
 
Parameter "text" is usually string, but can be of other types (bool, int, float, tuple/list of simple types).
 
Parameter "text" is usually string, but can be of other types (bool, int, float, tuple/list of simple types).
  
====Misc properties====
+
====app_proc - Getting handles====
  
* PROC_GET_LANG: Returns string id of active app translation. E.g. "ru_RU" if translation file is "ru_RU.ini", or "translation template" if such file is used. Returns empty string if built-in English translation is used.
 
* PROC_GET_GROUPING: Returns grouping mode in program, one of GROUPS_nnnn int contants.
 
* PROC_SET_GROUPING: Sets grouping mode in program, one of GROUPS_nnnn int contants.
 
* PROC_PROGRESSBAR: Changes state of the progress-bar (hidden by default), which is located on the status-bar right corner. Int value<0: progressbar hides, value in 0..100: progressbar shows with the given value.
 
 
* PROC_GET_TAB_IMAGELIST: Returns int handle of imagelist, containing icons of all UI-tabs. Use imagelist_proc() to work with it. Use PROP_TAB_ICON property to get/set file-tab icon index (index in this imagelist).
 
* PROC_GET_TAB_IMAGELIST: Returns int handle of imagelist, containing icons of all UI-tabs. Use imagelist_proc() to work with it. Use PROP_TAB_ICON property to get/set file-tab icon index (index in this imagelist).
 
* PROC_GET_CODETREE: Returns int handle of built-in code-tree UI control. Use tree_proc() to work with it.
 
* PROC_GET_CODETREE: Returns int handle of built-in code-tree UI control. Use tree_proc() to work with it.
 
* PROC_GET_CONSOLE_FORM: Returns int handle of built-in Console form. Use dlg_proc() to work with it.
 
* PROC_GET_CONSOLE_FORM: Returns int handle of built-in Console form. Use dlg_proc() to work with it.
 +
* PROC_GET_OUTPUT_FORM: Returns int handle of built-in Output form (contains the Output read-only editor). Use dlg_proc() to work with it.
 +
* PROC_GET_VALIDATE_FORM: Returns int handle of built-in Validate form (contains the Validate read-only editor). Use dlg_proc() to work with it.
 +
* PROC_GET_MAIN_TOOLBAR: Returns int handle of main app toolbar. Use toolbar_proc() to work with it.
 +
* PROC_GET_MAIN_STATUSBAR: Returns int handle of main app statusbar. Use statusbar_proc() to work with it.
 +
 +
====app_proc - Misc properties====
 +
 +
* PROC_GET_LANG: Returns string id of active app translation. E.g. "ru_RU" if translation file is "ru_RU.ini", or "translation template" if such file is used. Returns empty string if built-in English translation is used.
 +
* PROC_GET_GROUPING: Returns grouping mode in program, one of GROUPS_nnnn int constants.
 +
* PROC_SET_GROUPING: Sets grouping mode in program, one of GROUPS_nnnn int constants.
 +
* PROC_PROGRESSBAR: Changes state of the progress-bar (hidden by default), which is located on the status-bar right corner. Int value<0: progressbar hides, value in 0..100: progressbar shows with the given value.
 +
 
* PROC_SET_FOLDER: Sets path of folder which will be used as initial folder in program's Open/Save-as dialogs.
 
* PROC_SET_FOLDER: Sets path of folder which will be used as initial folder in program's Open/Save-as dialogs.
 +
* PROC_SET_PROJECT: Informs the program that some "project" (in the Project Manager) has been opened or closed. Program will fire "on_state" event with APPSTATE_PROJECT.
 +
 
* PROC_WINDOW_TOPMOST_GET: Returns bool flag: main window has "always on top" style.
 
* PROC_WINDOW_TOPMOST_GET: Returns bool flag: main window has "always on top" style.
 
* PROC_WINDOW_TOPMOST_SET: Sets bool flag: main window has "always on top" style.
 
* PROC_WINDOW_TOPMOST_SET: Sets bool flag: main window has "always on top" style.
Line 195: Line 248:
 
* PROC_CONFIG_SCALE_SET: Sets UI scales, value must be 2-tuple (int_scale_UI, int_scale_font).
 
* PROC_CONFIG_SCALE_SET: Sets UI scales, value must be 2-tuple (int_scale_UI, int_scale_font).
  
====Search properties====
+
* PROC_PARSE_COMMAND_LINE: Parses/handles the text as the program command line. Separator of params is space, double-quoted params are supported. Here you may pass, for example, several filenames, including project and session filenames (.cuda-proj and .cuda-session extensions).
 +
 
 +
* PROC_GET_WINDOW_STATE: Gets state of application window, one of int constants:
 +
** WND_NORMAL: Window is normal
 +
** WND_MAXIMIZED: Window is maximized
 +
** WND_MINIMIZED: Window is minimized
 +
** WND_FULLSCREEN: Full-screen mode
 +
** WND_FULLSCREEN2: Full-screen + Distraction-free mode
 +
 
 +
====app_proc - Search properties====
  
 
Actions work with props of Find/Replace dialog, and props of low-level search engine. When user runs some search command in the dialog, dialog applies its props to the search engine. So most of the time, props of dialog and search engine are sync'ed. But they aren't sync'ed if user just typed new text in the dialog. They also aren't sync'ed if user runs some search command via Command Palette or hotkey (e.g. "find current word, previous").
 
Actions work with props of Find/Replace dialog, and props of low-level search engine. When user runs some search command in the dialog, dialog applies its props to the search engine. So most of the time, props of dialog and search engine are sync'ed. But they aren't sync'ed if user just typed new text in the dialog. They also aren't sync'ed if user runs some search command via Command Palette or hotkey (e.g. "find current word, previous").
Line 209: Line 271:
 
** "op_word": option "whole words" of search engine
 
** "op_word": option "whole words" of search engine
 
** "op_regex": option "reg.ex." of search engine
 
** "op_regex": option "reg.ex." of search engine
 +
** "op_regex_subst": option "reg.ex. substitute in 'Replace with' field" of search engine
 
** "op_cfm": option "confirm on replace" of search engine
 
** "op_cfm": option "confirm on replace" of search engine
 
** "op_insel": option "in selection" of search engine
 
** "op_insel": option "in selection" of search engine
 
** "op_wrap": option "wrapped search" of search engine
 
** "op_wrap": option "wrapped search" of search engine
 +
** "op_wrap_c": option "show wrapped-search confirmation when search reaches the document edge" of search engine
 
** "op_back": option "backward search" (low level) of search engine
 
** "op_back": option "backward search" (low level) of search engine
 
** "op_fromcaret": option "search from caret" (low level) of search engine
 
** "op_fromcaret": option "search from caret" (low level) of search engine
 
** "op_tokens": option "allowed syntax elements" of search engine (int)
 
** "op_tokens": option "allowed syntax elements" of search engine (int)
 +
** "op_prescase": option "preserve case on replacement" of search engine
 
** "op_case_d": option "case sensitive" of dialog, None if dialog not inited
 
** "op_case_d": option "case sensitive" of dialog, None if dialog not inited
 
** "op_word_d": option "whole words" of dialog, None if dialog not inited
 
** "op_word_d": option "whole words" of dialog, None if dialog not inited
 
** "op_regex_d": option "reg.ex." of dialog, None if dialog not inited
 
** "op_regex_d": option "reg.ex." of dialog, None if dialog not inited
 +
** "op_regex_subst_d": option "reg.ex. substitute in 'Replace with' field" of dialog, None if dialog not inited
 
** "op_cfm_d": option "confirm on replace" of dialog, None if dialog not inited
 
** "op_cfm_d": option "confirm on replace" of dialog, None if dialog not inited
 
** "op_insel_d": option "in selection" of dialog, None if dialog not inited
 
** "op_insel_d": option "in selection" of dialog, None if dialog not inited
Line 223: Line 289:
 
** "op_mulline_d": option "multi-line input fields" of dialog, None if dialog not inited
 
** "op_mulline_d": option "multi-line input fields" of dialog, None if dialog not inited
 
** "op_tokens_d": option "allowed syntax elements" of dialog (int), None if dialog not inited
 
** "op_tokens_d": option "allowed syntax elements" of dialog (int), None if dialog not inited
 +
** "op_prescase_d": option "preserve case on replacement" of dialog, None if dialog not inited
 +
** "op_hi_d": option "highlight all matches" of dialog, None if dialog not inited
  
 
* PROC_SET_FINDER_PROP: Sets properties of Find/Replace dialog and search engine. Param "text" must be dict, with all or some keys listed in PROC_GET_FINDER_PROP. Values types: str (for text fields), bool (for flags), int (for choices).
 
* PROC_SET_FINDER_PROP: Sets properties of Find/Replace dialog and search engine. Param "text" must be dict, with all or some keys listed in PROC_GET_FINDER_PROP. Values types: str (for text fields), bool (for flags), int (for choices).
  
====System====
+
====app_proc - System====
  
* PROC_ENUM_FONTS: Returns list of font names, currently installed in OS. Note: only some names are common in all OSes (like Arial, Courier, Courier New, Terminal, maybe more).
+
* PROC_ENUM_FONTS: Returns list of font names, currently installed in OS. There are no font names common in all OS'es.
 +
* PROC_ENUM_ENCODINGS: Returns list of supported encoding names.
 
* PROC_GET_SYSTEM_PPI: Returns int value of screen pixels-per-inch. Usual value is 96. When OS UI is scaled, it's bigger, e.g. for scale 150% it is round(96*1.5).
 
* PROC_GET_SYSTEM_PPI: Returns int value of screen pixels-per-inch. Usual value is 96. When OS UI is scaled, it's bigger, e.g. for scale 150% it is round(96*1.5).
 
* PROC_GET_GUI_HEIGHT: Returns height (pixels) of GUI element for dlg_custom(). Possible values of 'text': 'button', 'label', 'linklabel', 'combo', 'combo_ro', 'edit', 'spinedit', 'check', 'radio', 'checkbutton', 'filter_listbox', 'filter_listview'. Special value 'scrollbar' gets size of OS scrollbar. Returns None for other values.
 
* PROC_GET_GUI_HEIGHT: Returns height (pixels) of GUI element for dlg_custom(). Possible values of 'text': 'button', 'label', 'linklabel', 'combo', 'combo_ro', 'edit', 'spinedit', 'check', 'radio', 'checkbutton', 'filter_listbox', 'filter_listview'. Special value 'scrollbar' gets size of OS scrollbar. Returns None for other values.
Line 235: Line 304:
 
* PROC_GET_UNIQUE_TAG: Gets integer value, which is unique for the current CudaText process (it starts with 100, increasing with each call). Use this value for Editor.markers() and Editor.attr() tag values.
 
* PROC_GET_UNIQUE_TAG: Gets integer value, which is unique for the current CudaText process (it starts with 100, increasing with each call). Use this value for Editor.markers() and Editor.attr() tag values.
  
====Clipboard====
+
* PROC_GET_OS_SUFFIX: Returns string of OS suffix, which is used in some CudaText option names. Possible values are listed in the default.json file.
 +
* PROC_GET_COMPILER_INFO: Returns information about OS/CPU/WidgetSet CudaText was compiled for, as dict. Dict keys are: "os", "cpu", "widgetset", "fpc".
 +
 
 +
====app_proc - Clipboard====
  
 
* PROC_GET_CLIP: Returns clipboard text.
 
* PROC_GET_CLIP: Returns clipboard text.
* PROC_SET_CLIP: Copies text to clipboard (usual).
+
 
 +
* PROC_GET_CLIP_EX: Returns additional info, stored to clipboard by CudaText, as dict. Dict keys are:
 +
** "is_column": bool: True if clipboard contains the column (vertical) block.
 +
** "caret_pos": 4-tuple of int: Position (x, y, x_end, y_end) of the first caret, at the moment of copying.
 +
** "caret_count": int: Number of caret(s), at the moment of copying.
 +
** "indent_chars": int: Number of indentation chars (spaces/tabs), of the block's first line, in the original document. Tab-chars are not expanded (counted as 1).
 +
** "indent_columns": int: Number of indentation columns, of the block's first line, in the original document. Tab-chars are expanded.
 +
** "file_name": str: Full path of the file from which text was copyied. Limited by 255 chars.
 +
** "version": int: Modification version of the document, at the moment of copying.
 +
** "tick_on_copy": int: OS tick-count in milliseconds, at the moment of copying.
 +
** "tick_current": int: OS tick-count in milliseconds, at the moment of this API call.
 +
 
 +
* PROC_SET_CLIP: Copies text to clipboard (usual clipboard). Note: this clears the clipboard first.
 +
* PROC_SET_CLIP_HTML: Copies text to clipboard (usual clipboard) in HTML format, additionally to clipboard contents in plain-text format. Param "text" must be HTML-formatted fragment. Note: this does not clear the clipboard first.
 
* PROC_SET_CLIP_ALT: Copies text to alternate clipboard on Linux, called "primary selection".
 
* PROC_SET_CLIP_ALT: Copies text to alternate clipboard on Linux, called "primary selection".
** CudaText Copy commands put text to usual clipboard + primary selection.
+
** CudaText "Copy" commands put text to usual clipboard + primary selection.
** CudaText Paste commands get text from usual clipboard.
+
** CudaText "Paste" commands get text from usual clipboard.
** CudaText Paste with option "mouse_mid_click_paste":true gets text from primary selection.
+
** CudaText middle-click with option "mouse_mid_click_paste":true gets text from primary selection.
  
 
* PROC_CLIP_ENUM: Returns string, where each char represents a format stored in Clipboard.
 
* PROC_CLIP_ENUM: Returns string, where each char represents a format stored in Clipboard.
Line 248: Line 333:
 
** "h": HTML format.
 
** "h": HTML format.
 
** "p": Picture format.
 
** "p": Picture format.
 +
** "c": CudaText format telling about "is it column (vertical) block".
 +
** "x": CudaText format telling about last copying to Clipboard (PROC_GET_CLIP_EX will show these details).
  
 
* PROC_CLIP_SAVE_PIC: If Clipboard has a picture format, saves it to given filename (recommended the .png extension). Returns bool: clipboard has a picture, file is saved.
 
* PROC_CLIP_SAVE_PIC: If Clipboard has a picture format, saves it to given filename (recommended the .png extension). Returns bool: clipboard has a picture, file is saved.
  
====Plugin calls====
+
====app_proc - Plugin calls====
  
 
* PROC_SET_EVENTS: Subscribes plugin to events. First it removes all subscribed events for specified module name (even those from install.inf file) and then adds specified events (if event list is not empty). Param "text" must be 4 values ";"-separated: "module_name;event_list;lexer_list;filter".
 
* PROC_SET_EVENTS: Subscribes plugin to events. First it removes all subscribed events for specified module name (even those from install.inf file) and then adds specified events (if event list is not empty). Param "text" must be 4 values ";"-separated: "module_name;event_list;lexer_list;filter".
Line 289: Line 376:
 
** (for plugins) "p_in_menu": str: Value of parameter "menu" from install.inf.
 
** (for plugins) "p_in_menu": str: Value of parameter "menu" from install.inf.
  
====Hotkeys====
+
* PROC_GET_AUTOCOMPLETION_INVOKE: Returns the invokation kind of "on_complete" event call. Possible string values:
 +
** "c": Command or hotkey.
 +
** "a": Work of option "autocomplete_autoshow_chars".
 +
** "r": Re-showing of listbox, caused by typing, deleting, arrows left/right.
 +
 
 +
====app_proc - Hotkeys====
 +
 
 +
* PROC_GET_ESCAPE: Returns Esc-key flag (bool). This flag is set when user presses Esc key, each Esc press is counted since app start.
 +
** Note: if you run long loop, to allow app to react to keyboard/mouse in the loop, call msg_status(text, True).
 +
* PROC_SET_ESCAPE: Sets Esc-key flag. Param "text" must be bool.
 +
 
 +
* PROC_GET_HOTKEY: Returns hotkey(s) string for given command_id. Returns empty string for unknown command_id.
 +
** Command_id can be: str(int_command_code) or "module,method" or "module,method,param".
 +
** Examples of result: "F1", "Ctrl+B * B", "Ctrl+B * B * C|Ctrl+B * D" (two hotkeys for one command).
 +
* PROC_SET_HOTKEY: Sets hotkeys for given command_id from strings. Param "text" must be "command_id|hotkey1|hotkey2", where hotkey1/hotkey2 examples are: "F1", "Ctrl+B * B", "Ctrl+B * B * C". Symbol "*" can be without near spaces. Returns bool: command_id exists, hotkey(s) was set.
  
* PROC_GET_ESCAPE: Returns Esc-key flag (bool). This flag is set when user presses Esc key, each Esc press is counted since app start. Note: to allow app to handle key press in long loop, call msg_status('text', True).
 
* PROC_SET_ESCAPE: Sets Esc-key flag. Param "text" must be bool (or "0"/"1").
 
* PROC_GET_HOTKEY: Returns hotkeys strings for given command_id. Examples of result: "F1", "Ctrl+B * B", "Ctrl+B * B * C|Ctrl+B * D" (two hotkeys for one command). Returns empty str for unknown command_id.
 
* PROC_SET_HOTKEY: Sets hotkeys for given command_id from strings. Text must be "command_id|hotkey1|hotkey2", where hotkey1/hotkey2 examples: "F1", "Ctrl+B * B", "Ctrl+B * B * C". Symbol "*" can be without near spaces. Returns bool: command_id exists, changed.
 
 
* PROC_GET_KEYSTATE: Returns state of pressed keyboard keys and mouse buttons. String result has chars:
 
* PROC_GET_KEYSTATE: Returns state of pressed keyboard keys and mouse buttons. String result has chars:
 
** "c" for Ctrl
 
** "c" for Ctrl
Line 303: Line 400:
 
** "R" for right mouse button
 
** "R" for right mouse button
 
** "M" for middle mouse button
 
** "M" for middle mouse button
* PROC_HOTKEY_STR_TO_INT: Converts given string hotkey to int. Returns 0 for incorrect string. Example: converts "alt+shift+z" to 41050.
+
** "4" for the 4th mouse button
* PROC_HOTKEY_INT_TO_STR: Converts given int hotkey to string. Returns empty str for unknown code. Example: converts 41050 to "Shift+Alt+Z".
+
** "5" for the 5th mouse button
 
 
Notes:
 
  
* Value of command_id can be: str(int_command_code) or "module,method" or "module,method,param".
+
* PROC_HOTKEY_STR_TO_INT: Converts given string hotkey to int. Returns 0 for incorrect hotkey string.
 +
** Example: converts "alt+shift+z" to 41050.
 +
* PROC_HOTKEY_INT_TO_STR: Converts given int hotkey to string. Returns empty string for incorrect hotkey code.
 +
** Example: converts 41050 to "Shift+Alt+Z".
  
====Python====
+
====app_proc - Python====
 
* PROC_EXEC_PYTHON: Runs Python string in the context of Console. It is not the same as standard exec() call, it uses the same globals/locals as CudaText Console.
 
* PROC_EXEC_PYTHON: Runs Python string in the context of Console. It is not the same as standard exec() call, it uses the same globals/locals as CudaText Console.
 
* PROC_EXEC_PLUGIN: Runs Python plugin's method. Text must be comma-separated: "module_name,method_name,params", where "params" is optional part, it is parameter(s) for the method.
 
* PROC_EXEC_PLUGIN: Runs Python plugin's method. Text must be comma-separated: "module_name,method_name,params", where "params" is optional part, it is parameter(s) for the method.
  
====Themes====
+
====app_proc - Themes====
  
 
Notes:
 
Notes:
Line 331: Line 429:
 
* PROC_THEME_SYNTAX_DICT_GET: Returns contents of current syntax-theme, as dict. For description of keys of result, see LEXER_GET_STYLES.
 
* PROC_THEME_SYNTAX_DICT_GET: Returns contents of current syntax-theme, as dict. For description of keys of result, see LEXER_GET_STYLES.
  
====Sessions====
+
====app_proc - Sessions====
  
 
Session is a set of opened files + untitled tabs, with some properties of editors in these tabs, with group-indexes of tabs, with layout of groups. Session format is JSON.
 
Session is a set of opened files + untitled tabs, with some properties of editors in these tabs, with group-indexes of tabs, with layout of groups. Session format is JSON.
  
* PROC_SAVE_SESSION: Saves session to file with given name. Returns bool: session was saved.
+
* PROC_SAVE_SESSION: Saves session to file with given name. Returns bool: session was saved. Param "text" must be file name, and optional addition: ";" with several option-chars after ";":
* PROC_LOAD_SESSION: Loads session from file with given name (closes all tabs first). Returns bool: tabs closed w/o pressing Cancel, session was loaded.
+
** char 'n': Don't save text of modified named files.
 +
** char 'u': Don't save text of untitled documents (which are always modified).
 +
** char 't': Show additional text in the Console message: "; by timer at ...".
 +
 
 +
* PROC_LOAD_SESSION: Loads session from file with given name (closes all tabs first). Returns bool: tabs were closed without pressing Cancel, session was loaded.
 +
 
 
* PROC_SET_SESSION: Tells to app filename of session. Session with this filename will be saved on exit, loaded on start, shown in app title in {} brackets. Don't set here empty string. Default filename is "history session.json" without path. Missing path means that folder "settings" will be used.
 
* PROC_SET_SESSION: Tells to app filename of session. Session with this filename will be saved on exit, loaded on start, shown in app title in {} brackets. Don't set here empty string. Default filename is "history session.json" without path. Missing path means that folder "settings" will be used.
  
====Sidebar panels====
+
(Feature of API version 1.0.418.) Session-related actions support specifying the JSON path, into which session will be saved/loaded. If you want to use this feature, add the JSON path to the session filename, after pipe-char "|", e.g. "/some/path/sessionname.cuda-session|/my/key". Here "/my/key" specifies the JSON path of 2 levels ("key" inside "my").
 +
 
 +
====app_proc - Sidebar panels====
  
 
General notes:
 
General notes:
Line 351: Line 456:
  
 
* PROC_SIDEPANEL_ADD_DIALOG: Adds tab, with embedded dialog. Returns bool: all parameters are correct, tab was added. Param "text" must be 3-tuple:
 
* PROC_SIDEPANEL_ADD_DIALOG: Adds tab, with embedded dialog. Returns bool: all parameters are correct, tab was added. Param "text" must be 3-tuple:
** Item[0]: Caption of tab.
+
** Item 0: Caption of tab.
** Item[1]: Int handle of dialog, from dlg_proc().
+
** Item 1: Int handle of dialog, from dlg_proc().
** Item[2]: Name of icon file.
+
** Item 2: Name of icon file.
  
 
* PROC_SIDEPANEL_REMOVE: Removes tab. Param "text" is caption of tab. (Note: actually it hides tab, dialog for this tab is still in memory). Returns bool: tab was found/removed.
 
* PROC_SIDEPANEL_REMOVE: Removes tab. Param "text" is caption of tab. (Note: actually it hides tab, dialog for this tab is still in memory). Returns bool: tab was found/removed.
Line 359: Line 464:
 
** str: caption.
 
** str: caption.
 
** 2-tuple (caption, bool_set_focus). Default for bool_set_focus is False.
 
** 2-tuple (caption, bool_set_focus). Default for bool_set_focus is False.
 
* (deprecated) PROC_SIDEPANEL_ENUM: Enumerates tabs. Returns str, "\n"-separated captions of tabs.
 
  
 
* PROC_SIDEPANEL_ENUM_ALL: Enumerates tabs. Returns list of dict, each dict item has keys:
 
* PROC_SIDEPANEL_ENUM_ALL: Enumerates tabs. Returns list of dict, each dict item has keys:
** "cap": str: Caption.
+
** "cap": str: Panel caption (not affected by translation)
** "hint": str: Floating tooltip (it changes when translation is applied).
+
** "hint": str: Button's floating tooltip (affected by translation).
** "dlg": int: Handle of dialog. Can be 0, if dialog is not yet created, like for plugins "Tabs", "Snippet panel".
+
** "dlg": int: Handle of panel's dialog. Can be 0, if dialog is not yet created. For example, plugins "Tabs List" and "Snippet Panel" do not create the dialog until plugin is called.
** "img": int: Image-index in the imagelist.
+
** "img": int: Button's image-index in the imagelist.
 +
** "btn_h": int: Button's handle. Use this handle with button_proc().
 
** "module": str: Python module name, or empty str.
 
** "module": str: Python module name, or empty str.
 
** "method": str: Python method name, or empty str.
 
** "method": str: Python method name, or empty str.
Line 374: Line 478:
  
 
* PROC_SIDEPANEL_SET_PROP: Changes properties of sidebar button. Returns bool: button was found/changed. Param "text" must be 3-tuple:
 
* PROC_SIDEPANEL_SET_PROP: Changes properties of sidebar button. Returns bool: button was found/changed. Param "text" must be 3-tuple:
** Item[0]: Caption of tab.
+
** Item 0: Caption of tab.
** Item[1]: Int index of button's icon in sidebar's imagelist, or -1 to keep old value.
+
** Item 1: Int index of button's icon in sidebar's imagelist, or -1 to keep old value.
** Item[2]: Floating tooltip string (it's independent from caption), or empty str to keep old value.
+
** Item 2: Floating tooltip string (it's independent from caption), or empty str to keep old value.
  
 
* PROC_SIDEPANEL_GET_IMAGELIST: Returns int handle of sidebar's imagelist. Use this handle with imagelist_proc().
 
* PROC_SIDEPANEL_GET_IMAGELIST: Returns int handle of sidebar's imagelist. Use this handle with imagelist_proc().
  
==== Bottom-bar panels====
+
====app_proc - Bottom-bar panels====
  
 
* PROC_BOTTOMPANEL_ADD_DIALOG: Adds tab. Same as for PROC_SIDEPANEL_ADD_DIALOG.
 
* PROC_BOTTOMPANEL_ADD_DIALOG: Adds tab. Same as for PROC_SIDEPANEL_ADD_DIALOG.
 
* PROC_BOTTOMPANEL_REMOVE: Removes tab. Same as for PROC_SIDEPANEL_REMOVE.
 
* PROC_BOTTOMPANEL_REMOVE: Removes tab. Same as for PROC_SIDEPANEL_REMOVE.
 
* PROC_BOTTOMPANEL_ACTIVATE: Activates tab. Same as for PROC_SIDEPANEL_ACTIVATE.
 
* PROC_BOTTOMPANEL_ACTIVATE: Activates tab. Same as for PROC_SIDEPANEL_ACTIVATE.
* (deprecated) PROC_BOTTOMPANEL_ENUM: Enumerates tabs. Same as for PROC_SIDEPANEL_ENUM.
 
 
* PROC_BOTTOMPANEL_ENUM_ELL: Enumerates tabs. Same as for PROC_SIDEPANEL_ENUM_ALL.
 
* PROC_BOTTOMPANEL_ENUM_ELL: Enumerates tabs. Same as for PROC_SIDEPANEL_ENUM_ALL.
 
* PROC_BOTTOMPANEL_GET_CONTROL: Returns int handle of control. Same as for PROC_SIDEPANEL_GET_CONTROL.
 
* PROC_BOTTOMPANEL_GET_CONTROL: Returns int handle of control. Same as for PROC_SIDEPANEL_GET_CONTROL.
Line 391: Line 494:
 
* PROC_BOTTOMPANEL_SET_PROP: Sets sidebar's button properties. Same as for PROC_SIDEPANEL_SET_PROP.  
 
* PROC_BOTTOMPANEL_SET_PROP: Sets sidebar's button properties. Same as for PROC_SIDEPANEL_SET_PROP.  
  
====Splitters====
+
====app_proc - Splitters====
  
 
Splitter id:
 
Splitter id:
Line 462: Line 565:
 
</pre>
 
</pre>
  
====Show/Hide/Undock UI elements====
+
====app_proc - Show/Hide/Undock UI elements====
  
Actions can get/set state of UI elements (pass "0"/"1" or False/True):
+
Actions get/set state of UI elements, "value" must be False/True:
  
* PROC_SHOW_STATUSBAR_GET
+
* PROC_SHOW_STATUSBAR_GET: for main statusbar (on the bottom).
 
* PROC_SHOW_STATUSBAR_SET
 
* PROC_SHOW_STATUSBAR_SET
* PROC_SHOW_TOOLBAR_GET
+
* PROC_SHOW_TOOLBAR_GET: for horizontal toolbar (on the top).
 
* PROC_SHOW_TOOLBAR_SET
 
* PROC_SHOW_TOOLBAR_SET
* PROC_SHOW_SIDEBAR_GET
+
* PROC_SHOW_SIDEBAR_GET: for vertical sidebar.
 
* PROC_SHOW_SIDEBAR_SET
 
* PROC_SHOW_SIDEBAR_SET
* PROC_SHOW_SIDEPANEL_GET
+
* PROC_SHOW_SIDEPANEL_GET: for panels near the sidebar (Code-Tree, Project Manager etc).
 
* PROC_SHOW_SIDEPANEL_SET
 
* PROC_SHOW_SIDEPANEL_SET
* PROC_SHOW_BOTTOMPANEL_GET
+
* PROC_SHOW_BOTTOMPANEL_GET: for panels near the statusbar (Console, Output etc.)
 
* PROC_SHOW_BOTTOMPANEL_SET
 
* PROC_SHOW_BOTTOMPANEL_SET
* PROC_SHOW_TABS_GET
+
* PROC_SHOW_TABS_GET: for UI-tabs bar (can be placed at all 4 sides).
 
* PROC_SHOW_TABS_SET
 
* PROC_SHOW_TABS_SET
* PROC_SHOW_TREEFILTER_GET
+
* PROC_SHOW_TREEFILTER_GET: for Code-Tree "filter" input field.
 
* PROC_SHOW_TREEFILTER_SET
 
* PROC_SHOW_TREEFILTER_SET
* PROC_SHOW_FLOATGROUP1_GET
+
* PROC_SHOW_FLOATGROUP1_GET: for "floating group 1", which is activated by moving some UI-tabs there, from UI-tab context menu.
 
* PROC_SHOW_FLOATGROUP1_SET
 
* PROC_SHOW_FLOATGROUP1_SET
* PROC_SHOW_FLOATGROUP2_GET
+
* PROC_SHOW_FLOATGROUP2_GET: for "floating group 2".
 
* PROC_SHOW_FLOATGROUP2_SET
 
* PROC_SHOW_FLOATGROUP2_SET
* PROC_SHOW_FLOATGROUP3_GET
+
* PROC_SHOW_FLOATGROUP3_GET: for "floating group 3".
 
* PROC_SHOW_FLOATGROUP3_SET
 
* PROC_SHOW_FLOATGROUP3_SET
  
* PROC_FLOAT_SIDE_GET
+
* PROC_FLOAT_SIDE_GET: "floating" property of side panels.
 
* PROC_FLOAT_SIDE_SET
 
* PROC_FLOAT_SIDE_SET
* PROC_FLOAT_BOTTOM_GET
+
* PROC_FLOAT_BOTTOM_GET: "floating" property of bottom panels.
 
* PROC_FLOAT_BOTTOM_SET
 
* PROC_FLOAT_BOTTOM_SET
  
====Screen coordinates====
+
====app_proc - Screen coordinates====
  
 
Notes:
 
Notes:
  
 
* When getting or setting coords, you get/set 4-tuple of int: (left, top, right, bottom).
 
* When getting or setting coords, you get/set 4-tuple of int: (left, top, right, bottom).
 +
* Any coord of any monitor (and 'desktop') can be negative. For example, tuple (-1920, 0, 0, 1080) - this means that OS configuration has placed that monitor lefter than x=0.
  
 
Actions:
 
Actions:
Line 502: Line 606:
 
* PROC_COORD_WINDOW_GET: Returns coords of app window.
 
* PROC_COORD_WINDOW_GET: Returns coords of app window.
 
* PROC_COORD_WINDOW_SET: Sets coords of app window.
 
* PROC_COORD_WINDOW_SET: Sets coords of app window.
* PROC_COORD_DESKTOP: Returns coords of virtual desktop, which includes all monitors.
+
 
 
* PROC_COORD_MONITOR: Returns coords of monitor with app window.
 
* PROC_COORD_MONITOR: Returns coords of monitor with app window.
 
* PROC_COORD_MONITOR0: Returns coords of 1st monitor.
 
* PROC_COORD_MONITOR0: Returns coords of 1st monitor.
Line 508: Line 612:
 
* PROC_COORD_MONITOR2: Returns coords of 3rd monitor, or None if no such monitor.
 
* PROC_COORD_MONITOR2: Returns coords of 3rd monitor, or None if no such monitor.
 
* PROC_COORD_MONITOR3: Returns coords of 4th monitor, or None if no such monitor.
 
* PROC_COORD_MONITOR3: Returns coords of 4th monitor, or None if no such monitor.
 +
 +
* PROC_COORD_DESKTOP: Returns coords of 'desktop', which is the combined areas of all existing monitors. For example, with 2 monitors, 'desktop' is about 2x wider or about 2x taller than one average monitor. With 3-4 monitors, you cannot assume that all monitors are placed in horizontal row, or in vertical row, or in another shape. But you can detect that from coords of all monitors.
  
 
===app_log===
 
===app_log===
Line 522: Line 628:
 
Possible values of "id" for Output/Validate panels:
 
Possible values of "id" for Output/Validate panels:
  
* LOG_CLEAR: Clears log panel. Param "text" ignored.
+
* LOG_CLEAR: Clears log panel. Param "text" is ignored.
* LOG_ADD: Adds line to log panel. Param "tag" is used here: int value associated with line, it's passed in on_output_nav.
+
* LOG_ADD: Adds line to log panel.
* LOG_SET_REGEX: Sets parsing regex for log panel. Param "text". Regex must have some groups in round brackets, indexes of these groups must be passed in separate API calls. All lines in log panel, which can be parsed by this regex, will allow navigation to source code by click or double-click.
+
* LOG_SET_REGEX: Sets parsing RegEx for log panel. Param "text" is RegEx string. RegEx must have some groups in round brackets, indexes of these groups must be passed in separate API calls. All lines in log panel, which can be parsed by this regex, will allow navigation to source code by click or double-click.
 
* LOG_SET_LINE_ID: Sets index of regex group for line-number. Param "text" is one-char string from "1" to "8", and "0" means "not used".
 
* LOG_SET_LINE_ID: Sets index of regex group for line-number. Param "text" is one-char string from "1" to "8", and "0" means "not used".
* LOG_SET_COL_ID: Sets index of regex group for column-number. Param "text".
+
* LOG_SET_COL_ID: Sets index of regex group for column-number. Param "text" must be str(number).
* LOG_SET_NAME_ID: Sets index of regex group for file-name. Param "text".
+
* LOG_SET_NAME_ID: Sets index of regex group for file-name. Param "text" must be str(number).
* LOG_SET_FILENAME: Sets default file name, which will be used when regex cannot find file name in a string. Param "text".
+
* LOG_SET_FILENAME: Sets default file name, which will be used when regex cannot find file name in a string. Param "text" is value.
* LOG_SET_ZEROBASE: Sets flag: line and column numbers are 0-based, not 1-based. Param "text" is one-char string "0" or "1".
+
* LOG_SET_ZEROBASE: Sets flag: line and column numbers are 0-based, not 1-based. Param "text" must be one-char string "0" or "1".
* LOG_GET_LINES_LIST: Returns items in panel's listbox, as list of 2-tuples (line, tag).
+
* LOG_GET_LINES_LIST: Returns items in panel's listbox, as list of 2-tuples (line, 0).
 
* LOG_GET_LINEINDEX: Returns index of selected line in panel's listbox.
 
* LOG_GET_LINEINDEX: Returns index of selected line in panel's listbox.
* LOG_SET_LINEINDEX: Sets index of selected line in panel's listbox.
+
* LOG_SET_LINEINDEX: Sets index of selected line in panel's listbox. Param "text" must be str(number).
  
 
Possible values of "id" for "Console" panel:
 
Possible values of "id" for "Console" panel:
Line 543: Line 649:
 
* LOG_CONSOLE_GET_COMBO_LINES: Returns list of lines in combobox-control.
 
* LOG_CONSOLE_GET_COMBO_LINES: Returns list of lines in combobox-control.
 
* LOG_CONSOLE_GET_MEMO_LINES: Returns list of lines in memo-control.
 
* LOG_CONSOLE_GET_MEMO_LINES: Returns list of lines in memo-control.
 +
 +
Parameter "tag" is deprecated and is not used.
  
 
====Example====
 
====Example====
Line 639: Line 747:
 
===msg_status_alt===
 
===msg_status_alt===
  
  msg_status_alt(text, seconds)
+
  msg_status_alt(text, pause, pos=HINTPOS_CARET, x=0, y=0)
  
Shows given text in the floating tooptip on the top. Multi-line text (with "\n") is supported.
+
Shows given text in the floating tooptip.
  
Param "seconds": show pause in seconds, 1..30. Value<=0 hides the tooltip.
+
* Param "text": Text of tooltip. Multi-line text, with "\n", is supported.
 +
* Param "pause": Show duration in seconds, 1..30. Value<=0 hides the tooltip, if it's already shown.
 +
* Param "pos": Possible values are:
 +
** HINTPOS_CARET: Show near the first caret.
 +
** HINTPOS_CARET_BRACKET: Like HINTPOS_CARET, but moves to the nearest opening bracket.
 +
** HINTPOS_TEXT: Show near custom text position specified by params "x" and "y" (0-based).
 +
** HINTPOS_TEXT_BRACKET: Like HINTPOS_TEXT, but moves to the nearest opening bracket.
 +
** HINTPOS_WINDOW_TOP: Show near the window top.
 +
** HINTPOS_WINDOW_BOTTOM: Show near the window bottom.
  
 
===dlg_input===
 
===dlg_input===
  
  dlg_input(label, text)
+
  dlg_input(prompt, text)
  
 
Shows modal dialog to input one string. Returns entered string or None if cancelled.
 
Shows modal dialog to input one string. Returns entered string or None if cancelled.
  
* Param "label": prompt text above input field.
+
* Param "prompt": Description text above the input field. It can be multi-line ("\n"-separated) and can have long line(s).
* Param "text": initial value of input field.
+
* Param "text": Initial value of the input field.
  
 
===dlg_input_ex===
 
===dlg_input_ex===
  
 
  dlg_input_ex(number, caption,
 
  dlg_input_ex(number, caption,
               label1   , text1="", label2="", text2="", label3="", text3="",
+
               prompt1   , text1="", prompt2="", text2="", prompt3="", text3="",
               label4="", text4="", label5="", text5="", label6="", text6="",
+
               prompt4="", text4="", prompt5="", text5="", prompt6="", text6="",
               label7="", text7="", label8="", text8="", label9="", text9="",
+
               prompt7="", text7="", prompt8="", text8="", prompt9="", text9="",
               label10="", text10="")
+
               prompt10="", text10="")
  
 
Shows modal dialog to enter 1 to 10 string fields at once. Returns list of strings or None if cancelled.
 
Shows modal dialog to enter 1 to 10 string fields at once. Returns list of strings or None if cancelled.
  
* Param "number": count of input fields.
+
* Param "number": Count of input fields.
* Params "label": prompt text above input field.
+
* Params "prompt*": Descriptions near input fields. They cannot be multi-line.
* Params "text": initial value of input field.
+
* Params "text*": Initial values of input fields.
  
 
===dlg_file===
 
===dlg_file===
Line 756: Line 872:
 
Shows dialog with controls of many types. This is legacy API, it is recommended to use "dlg_proc" instead.
 
Shows dialog with controls of many types. This is legacy API, it is recommended to use "dlg_proc" instead.
  
====Types of dialog controls====
+
====dlg_custom - Types of controls====
  
 
* "button": simple button
 
* "button": simple button
Line 788: Line 904:
 
* "tabs": TabControl: set of tabs, w/o pages attached to them
 
* "tabs": TabControl: set of tabs, w/o pages attached to them
 
* "pages": PageControl: set of tabs, with pages attached to them (only one of pages is visible)
 
* "pages": PageControl: set of tabs, with pages attached to them (only one of pages is visible)
* "splitter": divider bar, which can be dragged by mouse. It finds "linked control", ie control with the same "parent" and "align", nearest to splitter. On mouse drag, splitter resizes this linked control. Recommended to place another control with "align": ALIGN_CLIENT, so splitter will resize two controls at once.
+
* "splitter": divider bar (vertical or horizontal), which can be dragged by mouse, to change width/height of nearest control. It finds linked control, ie control with the same "parent" and "align", which position (coordinates) are nearest to the splitter. On mouse drag, splitter resizes this linked control. It's recommended to place another control with "align": ALIGN_CLIENT, so splitter will resize two controls at once. A panel may contain several splitters (mixed with other controls between them).
 +
* "scrollbox": like panel, but has two auto-shown scrollbars to scroll the area containing children controls (ie controls which parent is this scrollbox)
  
 
Details:
 
Details:
  
* Controls "combo", "combo_ro", "listbox": value is 0-based index of selected item, or -1 if none is selected.
 
 
* Control "button_ex": to change advanced props, you must get handle via DLG_CTL_HANDLE, and pass it to button_proc().
 
* Control "button_ex": to change advanced props, you must get handle via DLG_CTL_HANDLE, and pass it to button_proc().
 
* Control "treeview" don't have "items"/"value": to work with it, you must get handle of control via DLG_CTL_HANDLE, and pass it to tree_proc().
 
* Control "treeview" don't have "items"/"value": to work with it, you must get handle of control via DLG_CTL_HANDLE, and pass it to tree_proc().
Line 802: Line 918:
 
* Control property "name" is required for "filter_nnnnn" controls: must set name of listbox/listview, and name of its filter - to the same name with prefix "f_" (e.g. listbox name "mylist" with filter name "f_mylist").
 
* Control property "name" is required for "filter_nnnnn" controls: must set name of listbox/listview, and name of its filter - to the same name with prefix "f_" (e.g. listbox name "mylist" with filter name "f_mylist").
  
==== Properties of dialog controls ====
+
====dlg_custom - Properties of controls====
  
 
Parameter "text" in "dlg_custom" is "\n"-separated items, one item per control.
 
Parameter "text" in "dlg_custom" is "\n"-separated items, one item per control.
Line 831: Line 947:
 
* "items": list of items. Described below.
 
* "items": list of items. Described below.
  
====Property "items" of dialog controls====
+
====dlg_custom - Property "items"====
  
 
Possible values of "items" in "dlg_custom":
 
Possible values of "items" in "dlg_custom":
Line 844: Line 960:
 
Action DLG_CTL_PROP_GET also returns key "items" (in the same format) for these controls: "listbox", "checklistbox", "listview", "checklistview".
 
Action DLG_CTL_PROP_GET also returns key "items" (in the same format) for these controls: "listbox", "checklistbox", "listview", "checklistview".
  
====Property "columns" of dialog controls====
+
====dlg_custom - Property "columns"====
  
 
* For "listview", "checklistview": "\t"-separated items, each item is "\r"-separated props of a column:
 
* For "listview", "checklistview": "\t"-separated items, each item is "\r"-separated props of a column:
Line 861: Line 977:
 
Action DLG_CTL_PROP_SET, for "listview", allows both "items" (it sets columns) and "columns", and "columns" is applied last.
 
Action DLG_CTL_PROP_SET, for "listview", allows both "items" (it sets columns) and "columns", and "columns" is applied last.
  
====Property "val" of dialog controls====
+
====dlg_custom - Property "val"====
  
* For "check": checked state "0", "1" or "?" for grayed state
+
* For "combo", "combo_ro", "listbox": value is 0-based index of selected item, or -1 if none is selected.
* For "radio", "checkbutton": checked state "0", "1"
+
* For "check": value is checked state "0"/"1" or "?" for "grayed" state.
* For "edit", "edit_pwd", "spinedit", "combo", "filter_*": text in control
+
* For "radio", "checkbutton": value is checked state "0"/"1".
* For "memo": "\t"-separated lines, in lines "\t" chars must be replaced with chr(3)
+
* For "edit", "edit_pwd", "spinedit", "combo", "filter_*": value is text in control.
* For "combo_ro", "listbox", "radiogroup", "listview": index (0-based) of selected item
+
* For "memo": value is "\t"-separated lines, in lines "\t" chars must be replaced with chr(3).
* For "checkgroup": ","-separated checked states ("0", "1")
+
* For "combo_ro", "listbox", "radiogroup", "listview": value is index (0-based) of selected item.
* For "checklistbox", "checklistview": index + ";" + checked_states
+
* For "checkgroup": value is ","-separated checked states "0"/"1".
* For "tabs", "pages": index of active tab
+
* For "checklistbox", "checklistview": value is str(index) + ";" + checked_states.
* For "trackbar", "progressbar": position, int value
+
* For "tabs", "pages": value is index of active tab.
 +
* For "trackbar", "progressbar": value is position, int value.
 +
* For "scrollbox":
 +
** on reading: value is 6 numbers ","-separated: vert_position, horz_position, vert_range, horz_range, vert_pagesize, horz_pagesize
 +
** on writing: value is only 2 numbers ","-separated: vert_position, horz_position.
  
====Properties "ex" of dialog controls====
+
====dlg_custom - Properties "ex"====
  
Properties "ex0"..."ex9" are control-specific. They have different simple type (str, bool, int...).
+
Properties "ex0"..."ex9" are specific to each control kind. They have different simple types (str, bool, int...). Note: for dlg_custom, bool values must be specified as "0"/"1", not as strings "True"/"False".
  
 
* "button":
 
* "button":
Line 942: Line 1,062:
 
** "ex1": bool: on mouse drag, use instant repainting (else splitter paints after mouse released)
 
** "ex1": bool: on mouse drag, use instant repainting (else splitter paints after mouse released)
 
** "ex2": bool: auto jump to edge, when size of linked control becomes < min size
 
** "ex2": bool: auto jump to edge, when size of linked control becomes < min size
** "ex3": int: mininal size of linked control (controlled by splitter)
+
** "ex3": int: minimal size of linked control (controlled by splitter)
  
====Return value of dlg_custom====
+
====dlg_custom - Return value====
  
 
Dialog is closed by clicking any button or by changing of any control which has "act=1".
 
Dialog is closed by clicking any button or by changing of any control which has "act=1".
Line 954: Line 1,074:
 
** "state_text": "\n"-separated values of controls. Same count of items as in text, plus optional additional lines in the form "key=value". Line "focused=N" with index of last focused control (0-based) or -1.
 
** "state_text": "\n"-separated values of controls. Same count of items as in text, plus optional additional lines in the form "key=value". Line "focused=N" with index of last focused control (0-based) or -1.
  
====Notes====
+
====dlg_custom - Notes====
  
 
* Property "type" must be first.
 
* Property "type" must be first.
Line 977: Line 1,097:
 
* Set param "index" to control's index. You get index of newly created control from dlg_proc call. You can find the index from name, using DLG_CTL_FIND action. Param "index" is used if it's >=0 and param "name" is empty.
 
* Set param "index" to control's index. You get index of newly created control from dlg_proc call. You can find the index from name, using DLG_CTL_FIND action. Param "index" is used if it's >=0 and param "name" is empty.
  
====Types of dlg_proc controls====
+
====dlg_proc - Types of controls====
  
 
Possible types of UI controls are described in "dlg_custom" topic.
 
Possible types of UI controls are described in "dlg_custom" topic.
Line 992: Line 1,112:
 
* "treeview": tree structure with nodes and nested nodes, works via tree_proc()
 
* "treeview": tree structure with nodes and nested nodes, works via tree_proc()
  
====Form properties====
+
====dlg_proc - Forms properties====
  
 
* "cap": str: Caption of form.
 
* "cap": str: Caption of form.
Line 1,001: Line 1,121:
 
* "p": int: Handle of parent form, or 0 if no parent.
 
* "p": int: Handle of parent form, or 0 if no parent.
 
* "tag": str: Any string, set by plugin.
 
* "tag": str: Any string, set by plugin.
* "border": int: Sets border of form, DBORDER_nnn constants. Don't specify it together with deprecated "resize".
+
 
 +
* "border": int: Border-style of form, one of DBORDER_nnn constants.
 
** DBORDER_NONE: No visible border, not resizable
 
** DBORDER_NONE: No visible border, not resizable
 
** DBORDER_SIZE: Standard resizable border (on Windows: with Minimize/Maximize buttons)
 
** DBORDER_SIZE: Standard resizable border (on Windows: with Minimize/Maximize buttons)
Line 1,008: Line 1,129:
 
** DBORDER_TOOL: Like DBORDER_SINGLE but with a smaller caption
 
** DBORDER_TOOL: Like DBORDER_SINGLE but with a smaller caption
 
** DBORDER_TOOLSIZE: Like DBORDER_SIZE but with a smaller caption
 
** DBORDER_TOOLSIZE: Like DBORDER_SIZE but with a smaller caption
* "topmost": bool: Makes form stay on top of other forms in CudaText.
+
 
 
* "vis": bool: Visible state.
 
* "vis": bool: Visible state.
 
* "color": int: Background color.
 
* "color": int: Background color.
* "autosize": bool: Form resizes to minimal size, which shows all visible controls. Don't use it together with "resize".
+
* "autosize": bool: Form automatically resizes to the minimal size, which shows all visible controls.
 
* "keypreview": bool: If on, then key press calls on_key_down before passing key to focused control. Should be True if form needs to handle on_key_down.
 
* "keypreview": bool: If on, then key press calls on_key_down before passing key to focused control. Should be True if form needs to handle on_key_down.
 
* "p": int: Parent handle. Set this property to int handle of any windowed UI control or form, this control/form will be parent of form.
 
* "p": int: Parent handle. Set this property to int handle of any windowed UI control or form, this control/form will be parent of form.
 
* "focused" (only for reading): index of currently focused control.
 
* "focused" (only for reading): index of currently focused control.
* (deprecated) "resize": bool: Border of form has "resizable" style.
+
* "form_state" (only for reading): current form state, string: "norm" for normal, "min" for minimized, "max" for maximized, "fullscr" for full-screen.
 +
* "topmost": bool: Makes form stay on top of other forms in CudaText.
 +
* "taskbar": int enum: When form appears on OS taskbar.
 +
** 0: Application default behaviour
 +
** 1: Always
 +
** 2: Never
  
====Form events====
+
====dlg_proc - Forms events====
  
 
These are also properties of forms.
 
These are also properties of forms.
Line 1,027: Line 1,153:
 
* "on_show": Called after form shows.
 
* "on_show": Called after form shows.
 
* "on_hide": Called after form hides.
 
* "on_hide": Called after form hides.
* "on_act": Called when form is activated.
+
* "on_act": Called after form is activated (gets focus).
* "on_deact": Called when form is deactivated.
+
* "on_deact": Called after form is deactivated (lost focus).
 
* "on_mouse_enter": Called when mouse cursor enters form area.
 
* "on_mouse_enter": Called when mouse cursor enters form area.
 
* "on_mouse_exit": Called when mouse cursor leaves form area.
 
* "on_mouse_exit": Called when mouse cursor leaves form area.
 +
 +
* "on_form_state": Called after form is minimized/maximized/restored.
 +
** param "data": Current form state, string value like in the property "form_state".
  
 
* "on_key_down": Called when key is pressed in form (form should have "keypreview":True). If plugin returns False, key is blocked.
 
* "on_key_down": Called when key is pressed in form (form should have "keypreview":True). If plugin returns False, key is blocked.
Line 1,036: Line 1,165:
 
** param "data": key-state string: few chars, "c" for Ctrl, "a" for Alt, "s" for Shift, "m" for Meta.
 
** param "data": key-state string: few chars, "c" for Ctrl, "a" for Alt, "s" for Shift, "m" for Meta.
  
* "on_key_up": Called when key is depressed (after on_key_down). If plugin returns False, depressing of key is blocked.
+
* "on_key_up": Called when key is depressed (after "on_key_down"). If plugin returns False, depressing of key is blocked.
  
How to get nice key description in on_key_down, e.g. "Ctrl+Alt+Esc" from id_ctl=27 and data="ca":
+
* "on_key_press": Called when character-key is pressed (additional to "on_key_down"). If plugin returns False, pressing of key is blocked.
 +
** param "id_ctl": int character code.
 +
** param "data": key-state string, like in "on_key_down".
 +
 
 +
How to get nice key description in "on_key_down", e.g. "Ctrl+Alt+Esc" from id_ctl=27 and data="ca":
  
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
Line 1,049: Line 1,182:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
====Control properties====
+
====dlg_proc - Control properties====
  
 
* "name": str: Optional name of control, to find control later by name. May be not unique for controls.
 
* "name": str: Optional name of control, to find control later by name. May be not unique for controls.
Line 1,075: Line 1,208:
 
* "sp_l", "sp_r", "sp_t", "sp_b", "sp_a": int: Border spacing, ie padding of control's edge from anchored controls (or parent form). 5 props here: left, right, top, bottom, around. "Around" padding is added to padding of all 4 sides.
 
* "sp_l", "sp_r", "sp_t", "sp_b", "sp_a": int: Border spacing, ie padding of control's edge from anchored controls (or parent form). 5 props here: left, right, top, bottom, around. "Around" padding is added to padding of all 4 sides.
  
* "a_l", "a_r", "a_t", "a_b": 2-tuple (str_control_name, str_side): Anchors of control. See [[#Anchors]]. Value is 2-tuple, or None to disable anchor.
+
* "a_l", "a_r", "a_t", "a_b": 2-tuple (str_control_name, str_side): Anchors of control. See [[#dlg_proc_-_Anchors]]. Value is 2-tuple, or None to disable anchor.
 
** Item-0: name of target control, or empty str to use control's parent (it is form by default).
 
** Item-0: name of target control, or empty str to use control's parent (it is form by default).
 
** Item-1: side of target control, one of 3 values: "[" (left/top), "-" (center), "]" (right/bottom).
 
** Item-1: side of target control, one of 3 values: "[" (left/top), "-" (center), "]" (right/bottom).
Line 1,099: Line 1,232:
 
* "tab_hovered": int: index of tab/cell under mouse cursor. Property is missed if no such tab/cell.
 
* "tab_hovered": int: index of tab/cell under mouse cursor. Property is missed if no such tab/cell.
  
====Control events - general====
+
====dlg_proc - Control events - general====
  
 
General events for all controls:
 
General events for all controls:
Line 1,114: Line 1,247:
 
* "on_menu": Called before showing context menu, after right click or ContextMenu hotkey. Param "data": like in "on_mouse_down". Method can return False to disable default menu (if any).
 
* "on_menu": Called before showing context menu, after right click or ContextMenu hotkey. Param "data": like in "on_mouse_down". Method can return False to disable default menu (if any).
  
====Control events - for specific controls====
+
====dlg_proc - Control events - for specific controls====
  
 
Special events for controls "listview", "checklistview":
 
Special events for controls "listview", "checklistview":
Line 1,124: Line 1,257:
  
 
* "on_click_x": Called when listbox has X marks shown and X mark is clicked.
 
* "on_click_x": Called when listbox has X marks shown and X mark is clicked.
 +
* "on_click_header": Called when listbox shows a header, and header is clicked. Param "data": int column index.
 
* "on_draw_item": Called if listbox is owner-drawn. Param "data" is dict: { "canvas": canvas_id, "index": int_item_index, "rect": item_rectangle_4_tuple }.
 
* "on_draw_item": Called if listbox is owner-drawn. Param "data" is dict: { "canvas": canvas_id, "index": int_item_index, "rect": item_rectangle_4_tuple }.
  
Line 1,131: Line 1,265:
 
* "on_select": Called after selection is changed.
 
* "on_select": Called after selection is changed.
  
====Control events - for editor control====
+
====dlg_proc - Control events - for editor control====
  
 
Special events for control "editor"/"editor_edit"/"editor_combo":
 
Special events for control "editor"/"editor_edit"/"editor_combo":
Line 1,145: Line 1,279:
 
* "on_paste": Called before doing one of Paste commands. Param "data" is dict: {"keep_caret": bool, "sel_then": bool}. Method can return False to disable default operation.
 
* "on_paste": Called before doing one of Paste commands. Param "data" is dict: {"keep_caret": bool, "sel_then": bool}. Method can return False to disable default operation.
  
====Signatures of event callbacks====
+
====dlg_proc - Signatures of event callbacks====
  
Callbacks must be in forms shown in the topic [[#Callback_param]].
+
Callbacks must be in forms shown in the topic [[#Callback_parameter]].
 
+
Callbacks can be functions (out of class) or class methods, it depends on the look of the callback (again see "Callback parameter" topic).
Callbacks for "dlg_proc" must be declared as:
 
  
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
 
# for functions
 
# for functions
def my(id_dlg, id_ctl, data='', info=''):
+
def my_callback(id_dlg, id_ctl, data='', info=''):
 
   pass
 
   pass
  
 
# for class methods
 
# for class methods
 
class Command:
 
class Command:
   def my(self, id_dlg, id_ctl, data='', info=''):
+
   def my_callback(self, id_dlg, id_ctl, data='', info=''):
 
     pass
 
     pass
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 1,164: Line 1,297:
 
Parameters:
 
Parameters:
  
* "id_dlg": Int handle of the form.
+
* "id_dlg": Int, handle of the form.
* "id_ctl": Int index of control. But for event "on_key_down" it has different meaning.
+
* "id_ctl": Int, index of the control which fired the event. Note: for event "on_key_down" it has different meaning.
* "data": Value specific to event.
+
* "data" and "info": Values specific to event. If these parameters are used, they are described in the event descriptioon.
* "info": Additional value passed from CudaText, if extended form of callback is specified, with "info" part.
 
  
====Actions====
+
====dlg_proc - Actions====
  
 
Param "prop": it can be of any simple type (str, int, bool), also tuple/list (of any simple type), also dict (keys: str, values: simple type or tuple/list). Most used is dict. Example: prop={"cap": "...", "x": 10, "y": 10, "w": 600, "en": False}.
 
Param "prop": it can be of any simple type (str, int, bool), also tuple/list (of any simple type), also dict (keys: str, values: simple type or tuple/list). Most used is dict. Example: prop={"cap": "...", "x": 10, "y": 10, "w": 600, "en": False}.
Line 1,223: Line 1,355:
 
** String format is the same as in DLG_POS_GET_STR, comma-separated numbers "x,y,w,h", any number can be skipped to keep old value.
 
** String format is the same as in DLG_POS_GET_STR, comma-separated numbers "x,y,w,h", any number can be skipped to keep old value.
  
====Anchors====
+
====dlg_proc - Anchors====
  
 
Anchor is attaching of control's side to another control, or to the parent form, so control is auto positioned, initially and on form resize. Lazarus IDE has such Anchor Editor dialog:
 
Anchor is attaching of control's side to another control, or to the parent form, so control is auto positioned, initially and on form resize. Lazarus IDE has such Anchor Editor dialog:
Line 1,243: Line 1,375:
 
           | target |
 
           | target |
 
           +--------+
 
           +--------+
 
+
 
 
           +--------------+
 
           +--------------+
 
           |  control    |
 
           |  control    |
Line 1,253: Line 1,385:
 
           | target |
 
           | target |
 
           +--------+
 
           +--------+
 
+
 
 
     +--------------+
 
     +--------------+
 
     |  control    |
 
     |  control    |
Line 1,263: Line 1,395:
 
           | target |
 
           | target |
 
           +--------+
 
           +--------+
 
+
 
 
         +--------------+
 
         +--------------+
 
         |  control    |
 
         |  control    |
 
         +--------------+
 
         +--------------+
 +
 +
Useful information in the Lazarus wiki: [[Anchor_Docking#Why_use_Anchors_instead_of_Align.3F]].
  
 
Example: to attach "colorpanel" to the right side of form, clear left anchor (set to None), and add right/bottom anchors. This also sets spacing-aroung (padding) to 6 pixels.
 
Example: to attach "colorpanel" to the right side of form, clear left anchor (set to None), and add right/bottom anchors. This also sets spacing-aroung (padding) to 6 pixels.
Line 1,276: Line 1,410:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
====Example====
+
====dlg_proc - Example====
  
 
Detailed demo plugin exists, it shows many dlg_proc actions, shows modal/nonmodal forms, uses callbacks, moves control by button click, moves control on form resize. It is in the CudaText repo with name "cuda_testing_dlg_proc".
 
Detailed demo plugin exists, it shows many dlg_proc actions, shows modal/nonmodal forms, uses callbacks, moves control by button click, moves control on form resize. It is in the CudaText repo with name "cuda_testing_dlg_proc".
Line 1,306: Line 1,440:
 
  file_open((filename1, filename2), group=-1, options="")
 
  file_open((filename1, filename2), group=-1, options="")
  
Opens editor tab with given filename. If filename already opened, activates its tab. Pass empty string to open untitled tab.
+
Opens editor tab with given filename. If filename already opened, activates its tab.
  
First parameter can be 2-tuple (or 2-list) of string, to open two files in a single tab, in a splitted view. In this case, second filename won't be handled specially for zip file, picture file, binary file etc.
+
First parameter can be 2-tuple / 2-list of string, to open 2 files in a single tab, in a splitted view. In this case, second filename won't be handled specially for zip file, picture file, binary file etc.
 +
 
 +
The case of empty filename: opens empty untitled tab.
 +
The case of empty filename1 and non-empty filename2 is not supported: it also opens empty untitled tab, not splitted.
  
 
Returns bool. True, if first filename is empty. Otherwise, returns True if first filename exists, and second filename is empty or exists.
 
Returns bool. True, if first filename is empty. Otherwise, returns True if first filename exists, and second filename is empty or exists.
 
For zip file (only first filename is checked for it), returns True only if zip file contains valid CudaText add-on, and it was installed.
 
For zip file (only first filename is checked for it), returns True only if zip file contains valid CudaText add-on, and it was installed.
  
* Param "group": index of tab-group (0-based), default means "current group". If you pass index of currently hidden group, group won't show, you need to call editor command to show it, see [[#cmd]].
+
* Param "group": index of tab-group, currently 0...8 (6 normal groups + 3 floating groups). Default means "current group". If you pass index of currently hidden group, group won't show, you need to call editor command to show it, see [[#cmd]].
 
* Param "options": string:
 
* Param "options": string:
 
** If it has "/preview", then file opens in a "temporary preview" tab, with italic caption. Param "group" is ignored then, used 1st group.
 
** If it has "/preview", then file opens in a "temporary preview" tab, with italic caption. Param "group" is ignored then, used 1st group.
 
** If it has "/nohistory", file's saved history (caret, scroll pos, etc) won't be used.
 
** If it has "/nohistory", file's saved history (caret, scroll pos, etc) won't be used.
 +
** If it has "/noloadundo", file's persistent-undo (additional file created by using option "undo_persistent") won't be loaded.
 
** If it has "/nolexerdetect", lexer won't be auto-detected.
 
** If it has "/nolexerdetect", lexer won't be auto-detected.
 
** If it has "/noevent", then "on_open_pre" event won't fire.
 
** If it has "/noevent", then "on_open_pre" event won't fire.
Line 1,323: Line 1,461:
 
** If it has "/silent", then zipped add-on will install w/o prompt and report.
 
** If it has "/silent", then zipped add-on will install w/o prompt and report.
 
** If it has "/passive", then tab will not activate, it will be passive tab.
 
** If it has "/passive", then tab will not activate, it will be passive tab.
** If it has "/nonear", then app option "ui_tab_new_near_current" will be ignored, tab will append to end.
+
** If it has "/nonear", then app option "ui_tab_new_near_current" will be ignored, tab will be appended to the end.
 +
** If it has "/donear", then app option "ui_tab_new_near_current" will be ignored, tab will be opened near the active one.
 
** If it has "/nozip", then .zip files will not be handled specially.
 
** If it has "/nozip", then .zip files will not be handled specially.
 
** If it has "/nopictures", then picture files will not be handled specially.
 
** If it has "/nopictures", then picture files will not be handled specially.
 +
** If it has "/noupdateaddons", then after installing add-ons from .zip file(s), Plugins menu will not be reloaded / lexer library will not be reloaded.
 
** If it has "/view-text', then file will open in internal viewer, text (variable width) mode.
 
** If it has "/view-text', then file will open in internal viewer, text (variable width) mode.
 
** If it has "/view-binary', then file will open in internal viewer, binary (fixed width) mode.
 
** If it has "/view-binary', then file will open in internal viewer, binary (fixed width) mode.
Line 1,349: Line 1,489:
 
  ed_handles()
 
  ed_handles()
  
Returns range object: it contains int handles of all editor tabs. Pass each handle to Editor() to make editor object from handle.
+
Returns range object, which contains int handles of all editor UI-tabs. Pass each handle to Editor() to make editor object from handle.
  
Example code, which shows filenames of all tabs:
+
Example which shows filenames of all tabs:
  
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
    #show all file names in console
 
 
     for h in ed_handles():
 
     for h in ed_handles():
 
         e = Editor(h)
 
         e = Editor(h)
 
         print(e.get_filename())
 
         print(e.get_filename())
 +
</syntaxhighlight>
 +
 +
Note: resulting int handles are virtual (small int numbers, not memory addresses). To get unique handle which is memory address of an editor, use PROP_HANDLE_SELF:
 +
 +
<syntaxhighlight lang="python">
 +
    for h in ed_handles():
 +
        e = Editor(h)
 +
        print('Unique handle:', e.get_prop(PROP_HANDLE_SELF, ''))
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 1,466: Line 1,613:
 
* TREE_ITEM_SET_ICON: Sets item's icon. Params: "id_item", "image_index".
 
* TREE_ITEM_SET_ICON: Sets item's icon. Params: "id_item", "image_index".
  
* TREE_ITEM_SELECT: Selects item.
+
* TREE_ITEM_SELECT: Selects the item specified by "id_item". If "id_item" is 0, it removes the selection.
 
* TREE_ITEM_SHOW: Makes item visible, ie scrolls control to this item.
 
* TREE_ITEM_SHOW: Makes item visible, ie scrolls control to this item.
 
* TREE_ITEM_GET_SELECTED: Returns int handle of selected item (param "id_item" is ignored). Returns None if nothing is selected.
 
* TREE_ITEM_GET_SELECTED: Returns int handle of selected item (param "id_item" is ignored). Returns None if nothing is selected.
Line 1,487: Line 1,634:
 
* TREE_ITEM_UNFOLD: Unfolds item w/o subitems.
 
* TREE_ITEM_UNFOLD: Unfolds item w/o subitems.
 
* TREE_ITEM_UNFOLD_DEEP: Unfolds item with subitems. Root-item allowed too.
 
* TREE_ITEM_UNFOLD_DEEP: Unfolds item with subitems. Root-item allowed too.
* TREE_GET_IMAGELIST: Returns int handle of imagelist object.
+
 
* TREE_PROP_SHOW_ROOT: This allows to hide lines for invisible root-item. If hidden, tree (folded) looks like listbox. Param text: "0"/"1" to hide/show.
+
* TREE_GET_MULSELECT: Returns string, which shows multi-selection options.
 +
** String "-": Multi-selection is disabled
 +
** Empty string or several "option chars": multi-selection is enabled. "Option chars" are:
 +
*** "c": Enable Ctrl+click to select/deselect single node
 +
*** "s": Enable Shift+click to select range of nodes
 +
*** "v": Multi-selection has only visible nodes
 +
*** "i": Multi-selection has only sibling nodes
 +
* TREE_SET_MULSELECT: Sets multi-selection options. Param "text" must be one of possible values described in TREE_GET_MULSELECT.
 +
* TREE_GET_SELECTIONS: Returns list of selected tree nodes, one handle per each selected node. When multi-selection is disabled, result is empty list or list with single item.
 +
 
 +
* TREE_FIND_FOR_TEXT_POS: For the treeview, filled with code-tree information (it can be plugin-created treeview), finds the tree-item corresponding to given text position. Param "id_item" is ignored, param "text" must be 2-tuple of int (column, line). Returns handle of tree-item. Returns None if "text" doesn't contain valid text position. Returns 0 if tree-item is not found.
 +
 
 +
* TREE_GET_IMAGELIST: Returns handle of imagelist object, int value.
 +
* TREE_SET_IMAGELIST: Sets handle of imagelist object. Param "text" must be int handle, it can be 0 to remove current imagelist.
 +
 
 +
* TREE_PROP_SHOW_ROOT: Allows to change "show root-item" property. When root-item is hidden, treeview (folded) looks like a listbox. Param "text" must be bool value.
 
* TREE_LOCK: Disables repainting of control.
 
* TREE_LOCK: Disables repainting of control.
 
* TREE_UNLOCK: Enables repainting of control.
 
* TREE_UNLOCK: Enables repainting of control.
Line 1,495: Line 1,657:
 
* TREE_ITEM_GET_RANGE: Should be used only for code-tree. Returns range, stored in tree-item, as 4-tuple (start_x, start_y, end_x, end_y). If range is not set, returns (-1,-1,-1,-1).
 
* TREE_ITEM_GET_RANGE: Should be used only for code-tree. Returns range, stored in tree-item, as 4-tuple (start_x, start_y, end_x, end_y). If range is not set, returns (-1,-1,-1,-1).
 
* TREE_ITEM_SET_RANGE: Should be used only for code-tree. Sets range for tree-item. Param "text" must be 4-tuple of int (start_x, start_y, end_x, end_y).
 
* TREE_ITEM_SET_RANGE: Should be used only for code-tree. Sets range for tree-item. Param "text" must be 4-tuple of int (start_x, start_y, end_x, end_y).
 +
 +
'''Example of fast treeview filling''', with locking to prevert treeview repaints:
 +
 +
<syntaxhighlight lang="python">
 +
    tree_proc(h_tree, TREE_LOCK)
 +
 +
    for i in range(5000):
 +
        tree_proc(h_tree, TREE_ITEM_ADD, index=-1, text='text')
 +
 +
    tree_proc(h_tree, TREE_UNLOCK)
 +
</syntaxhighlight>
 +
 +
'''Example of getting code-tree text range''' for some code-tree node. The following is the Console input commands and their outputs. Comments "### ..." are inserted by hands later.
 +
 +
<syntaxhighlight lang="python">
 +
### Step 1 - get handle of code-tree.
 +
 +
>>> ct=app_proc(PROC_GET_CODETREE,'')
 +
>>> ct
 +
140556715678064
 +
 +
### Step 2 - enumerate code-tree root level.
 +
 +
>>> =tree_proc(ct, TREE_ITEM_ENUM_EX, id_item=0)
 +
[{'id': 140556582911424, 'text': 'log', 'data': '', 'img': 5, 'sub_items': False},
 +
{'id': 140556582911904, 'text': 'Command', 'data': '', 'img': 1, 'sub_items': True}]
 +
 +
### Step 3 - enumerate sub-items of 'Command' node.
 +
### We got last node with 'text'=='Command' and 'sub_items':True.
 +
### Copy its id and pass it to param "id_item".
 +
 +
>>> =tree_proc(ct, TREE_ITEM_ENUM_EX, id_item=140556582911904)
 +
[{'id': 140556582912064, 'text': '__init__', 'data': '', 'img': 5, 'sub_items': False},
 +
{'id': 140556582913344, 'text': 'on_focus', 'data': '', 'img': 5, 'sub_items': False},
 +
{'id': 140556582913504, 'text': 'work', 'data': '', 'img': 5, 'sub_items': False}]
 +
 +
### Step 4 - get text range of node.
 +
### Copy id of some item and get its text range (x1, y1, x2, y2).
 +
 +
>>> =tree_proc(ct, TREE_ITEM_GET_RANGE, id_item=140556582913504)
 +
(4, 102, 21, 180)
 +
</syntaxhighlight>
  
 
===listbox_proc===
 
===listbox_proc===
Line 1,534: Line 1,738:
 
* LISTBOX_GET_SCROLLPOS_HORZ: Returns horizontal scroll position.
 
* LISTBOX_GET_SCROLLPOS_HORZ: Returns horizontal scroll position.
 
* LISTBOX_SET_SCROLLPOS_HORZ: Sets horizontal scroll position. Param "index": int value.
 
* LISTBOX_SET_SCROLLPOS_HORZ: Sets horizontal scroll position. Param "index": int value.
 +
* LISTBOX_GET_HEADER: Returns header string.
 +
* LISTBOX_SET_HEADER: Sets header string. It may contain "column separator char", see LISTBOX_SET_COLUMN_SEP.
 +
* LISTBOX_GET_HEADER_IMAGELIST: Returns int handle of header's image-list.
 +
* LISTBOX_SET_HEADER_IMAGELIST: Sets int handle of header's image-list.
 +
* LISTBOX_GET_HEADER_IMAGEINDEXES: Returns header's image-list indexes, as list of int.
 +
* LISTBOX_SET_HEADER_IMAGEINDEXES: Sets header's image-list indexes. Param "text": list of int. For example, [-1, 4, 6] means "show image=4 for column 1, and image=6 for column 2".
  
 
Listbox can have columns. It works only if listbox is not owner-drawn, and column sizes were set via LISTBOX_SET_COLUMNS. You must add separator-chars inside items to split items into columns. Column sizes are passed as list of int. Each list item can be:
 
Listbox can have columns. It works only if listbox is not owner-drawn, and column sizes were set via LISTBOX_SET_COLUMNS. You must add separator-chars inside items to split items into columns. Column sizes are passed as list of int. Each list item can be:
 
* value>0: Column width in pixels.
 
* value>0: Column width in pixels.
* value<0: Column width in percents of listbox width.
+
* value<0: Column width in percents (percents of the entire listbox width, minus all fixed sizes).
* value=0: Column is auto-stretched to fill the entire width. Several auto-stretched columns are allowed.
+
* value=0: Column is auto-stretched to fill the rest of the width. Several auto-stretched columns are allowed.
  
 
Actions for columns:
 
Actions for columns:
Line 1,545: Line 1,755:
 
* LISTBOX_SET_COLUMN_SEP: Sets column separator char. Param "text" must be single-char string.
 
* LISTBOX_SET_COLUMN_SEP: Sets column separator char. Param "text" must be single-char string.
 
* LISTBOX_GET_COLUMNS: Returns list of column sizes.
 
* LISTBOX_GET_COLUMNS: Returns list of column sizes.
* LISTBOX_SET_COLUMNS: Sets list of column sizes. Param "text" must be list of int.
+
* LISTBOX_SET_COLUMNS: Sets list of column sizes. Param "text" must be list of int. List items can be >0, <0, =0, see above.
  
 
Example adds 3 columns:
 
Example adds 3 columns:
Line 1,561: Line 1,771:
 
   style=-1, p1=-1, p2=-1)
 
   style=-1, p1=-1, p2=-1)
  
Performs action on canvas (drawing surface of some GUI control).
+
Performs action on canvas, ie drawing surface of some GUI control.
Id_canvas is handle of canvas of some GUI control. Special value 0 means testing empty panel, it appears at the top of app, when used.
+
Param "id_canvas" is handle of canvas of some GUI control. Special value 0 means testing empty panel, it appears at the top of app, when used.
  
 
Possible values of "id_action":
 
Possible values of "id_action":
  
* CANVAS_SET_FONT: Sets props of font. Params:
+
* CANVAS_SET_FONT: Sets props of font. Params used:
 
** "text": font name
 
** "text": font name
 
** "color"
 
** "color"
Line 1,572: Line 1,782:
 
** "style": 0 for normal, or sum of values FONT_B (bold), FONT_I (italic), FONT_U (underline), FONT_S (strikeout)
 
** "style": 0 for normal, or sum of values FONT_B (bold), FONT_I (italic), FONT_U (underline), FONT_S (strikeout)
  
* CANVAS_SET_PEN: Sets props of pen. Params:
+
* CANVAS_SET_PEN: Sets props of pen. Params used:
 
** "color"
 
** "color"
 
** "size"
 
** "size"
Line 1,579: Line 1,789:
 
** "p2": line joining style - one of PEN_JOIN_nnnn
 
** "p2": line joining style - one of PEN_JOIN_nnnn
  
* CANVAS_SET_BRUSH: Sets props of brush. Params:
+
* CANVAS_SET_BRUSH: Sets props of brush. Params used:
 
** "color"
 
** "color"
 
** "style": one of BRUSH_nnnn. Usually used: BRUSH_SOLID (filled background), BRUSH_CLEAR (transparent background).
 
** "style": one of BRUSH_nnnn. Usually used: BRUSH_SOLID (filled background), BRUSH_CLEAR (transparent background).
  
* CANVAS_SET_ANTIALIAS: Sets anti-aliasing mode of canvas. Params: style - ANTIALIAS_NONE, _ON, _OFF.
+
* CANVAS_SET_ANTIALIAS: Sets anti-aliasing mode of canvas. Params used: "style" - ANTIALIAS_NONE, ANTIALIAS_ON, ANTIALIAS_OFF.
* CANVAS_GET_TEXT_SIZE: Returns size of text on canvas, as 2-tuple (size_x, size_y). Uses font. Params: text.
+
* CANVAS_GET_TEXT_SIZE: Returns size of text on canvas, as 2-tuple (size_x, size_y). Uses font. Params used: "text".
* CANVAS_TEXT: Paints text at given coords. Uses font and brush. Params: text, x, y.
+
* CANVAS_TEXT: Paints text at given coords. Uses font and brush. Params used: "text", "x", "y".
* CANVAS_LINE: Paints line at given coords. Uses pen. Params: x, y, x2, y2.
+
* CANVAS_LINE: Paints line at given coords. Uses pen. Params used: "x", "y", "x2", "y2".
* CANVAS_PIXEL: Paints one pixel at given coords. Params: x, y, color.
+
* CANVAS_PIXEL: Paints one pixel at given coords. Params used: "x", "y", "color".
* CANVAS_RECT: Paints rectangle. Uses pen and brush. Params: x, y, x2, y2.
+
* CANVAS_RECT: Paints rectangle. Uses pen and brush. Params used: "x", "y", "x2", "y2".
* CANVAS_RECT_FRAME: Paints rectangle. Uses only pen. Params: x, y, x2, y2.
+
* CANVAS_RECT_FRAME: Paints rectangle. Uses only pen. Params used: "x", "y", "x2", "y2".
* CANVAS_RECT_FILL: Paints rectangle. Uses only brush. Params: x, y, x2, y2.
+
* CANVAS_RECT_FILL: Paints rectangle. Uses only brush. Params used: "x", "y", "x2", "y2".
* CANVAS_RECT_ROUND: Paints rounded rectangle. Uses pen and brush. Params: x, y, x2, y2, style - radius of corners.
+
* CANVAS_RECT_ROUND: Paints rounded rectangle. Uses pen and brush. Params used: "x", "y", "x2", "y2", "style" - radius of corners.
* CANVAS_ELLIPSE: Paints ellipse or circle. Uses pen and brush. Params: x, y, x2, y2.
+
* CANVAS_ELLIPSE: Paints ellipse or circle. Uses pen and brush. Params used: "x", "y", "x2", "y2".
* CANVAS_POLYGON: Paints polygon from any number of points (>2). Uses pen and brush. Params: text - comma separated list of (x,y) coords. Example: "10,10,200,50,10,100" - 3 points.
+
* CANVAS_POLYGON: Paints polygon from any number of points (>2). Uses pen and brush. Params used: "text" - comma separated list of (x,y) coords. Example: "10,10,200,50,10,100" - 3 points.
* CANVAS_SET_TESTPANEL: Sets height of testing panel at the top. Params: size. If it's "too small", panel hides; for big size, size is limited.
+
* CANVAS_SET_TESTPANEL: Sets height of testing panel at the top. Params used: "size". If it's "too small" then panel hides; for big value, panel height is limited.
  
 
=== timer_proc ===
 
=== timer_proc ===
Line 1,615: Line 1,825:
 
Result is True if params are OK, False if params not OK (callback string incorrect, not created callback specified on stopping); or None (for unknown "id").
 
Result is True if params are OK, False if params not OK (callback string incorrect, not created callback specified on stopping); or None (for unknown "id").
  
====Callbacks====
+
====timer_proc - Callbacks====
  
Callback param must be in one of these forms: [[#Callback_param]].
+
Callback param must be in one of these forms: [[#Callback_parameter]].
  
 
Callbacks in timer_proc must be declared as:
 
Callbacks in timer_proc must be declared as:
Line 1,637: Line 1,847:
 
Perform action on menu items.
 
Perform action on menu items.
  
====Menu id====
+
====menu_proc - Menu id====
  
 
Value of "id_menu" can be:
 
Value of "id_menu" can be:
Line 1,654: Line 1,864:
 
* "toolmenu:"+name: dropdown submenu of toolbar button
 
* "toolmenu:"+name: dropdown submenu of toolbar button
  
====Command for new items====
+
====menu_proc - Command for new items====
  
 
Value of "command" parameter for MENU_ADD can be:
 
Value of "command" parameter for MENU_ADD can be:
  
 
* int_command or str(int_command) - int command code, from module cudatext_cmd (pass 0 if item does nothing)
 
* int_command or str(int_command) - int command code, from module cudatext_cmd (pass 0 if item does nothing)
* callback in one of these forms: [[#Callback_param]].
+
* callback in one of these forms: [[#Callback_parameter]].
 
* (deprecated callback form) callback in the form "module,method" or "module,method,param" (param can be of any primitive type).
 
* (deprecated callback form) callback in the form "module,method" or "module,method,param" (param can be of any primitive type).
  
Line 1,669: Line 1,879:
 
* empty string, if item will be used as submenu (item is a submenu, if any subitems are added to it)
 
* empty string, if item will be used as submenu (item is a submenu, if any subitems are added to it)
  
====Item props as dict====
+
====menu_proc - Properties as dict====
  
Some actions get dict for menu items. Dict keys:
+
Some actions get dict for menu items. Note that some keys are optional, they are returned only when value is not the default (e.g. "vis" is returned only when visibility is off). Dict keys:
  
* "id": menu_id, int
+
* "id", int: menu id
* "cap": caption, str (for separator items it is "-")
+
* "cap", str: caption; for separator items it is "-"
* "cmd": command code (e.g. from module cudatext_cmd), int
+
* "cmd", int: command code (e.g. from module cudatext_cmd); for plugin menu items it can be 0 or -1
* "hint": callback (used if "cmd" value <=0), str
+
* (optional) "hint", str: callback, used if "cmd" value <=0
* "hotkey": hotkey, str
+
* (optional) "hotkey", str: keyboard hotkey
* "command": combined command description: int value of "cmd" (if code>0), or str value of "hint" (otherwise)
+
* (optional) "tag", str: some plugin-defined data, if plugin set it
* "tag": plugin-defined tag, str
+
* (optional) "en", bool: menu item is enabled
* "en": enabled state, bool
+
* (optional) "vis", bool: menu item is visible
* "vis": visible state, bool
+
* (optional) "checked", bool: menu item is checked
* "checked": checked state, bool
+
* (optional) "radio", bool: menu item has rounded checkmark
* "radio": radio-item state, bool (it means round checkmark in checked state)
 
  
====Actions====
+
====menu_proc - Actions====
  
 
Possible values of "id_action":
 
Possible values of "id_action":
Line 1,714: Line 1,923:
 
* MENU_SET_IMAGEINDEX: Changes icon index of menu item (index in imagelist). Param "index" must be icon index.
 
* MENU_SET_IMAGEINDEX: Changes icon index of menu item (index in imagelist). Param "index" must be icon index.
  
====Example====
+
* MENU_SET_AUTO_HOTKEY: Sets the hotkey of menu item according to this item's command code (which must be already set). It skips some special commands: "Clipboard copy", "Clipboard paste", "Clipboard cut", "Select all", "Undo", "Redo" (because for example Ctrl+C hotkey in the top menu overrides the Ctrl+C pressing in the Console / Code-Tree filter / docked plugin dialogs). And it skips some special hotkeys: Esc, Shift+Tab.
 +
* MENU_SET_AUTO_HOTKEY_DEEP: Performs the action MENU_SET_AUTO_HOTKEY for all menu items nested in the given submenu. The deepness of the recusion (0-based) must be given in the param "command" as str(int_value).
 +
 
 +
====menu_proc - Example====
  
 
Example adds item "Misc" to the main menu, and sub-items: "About", separator, "Rename file" (from CudaExt plugin):
 
Example adds item "Misc" to the main menu, and sub-items: "About", separator, "Rename file" (from CudaExt plugin):
Line 1,735: Line 1,947:
 
===toolbar_proc===
 
===toolbar_proc===
  
  toolbar_proc(id_toolbar, id_action, text="", text2="", command=0, index=-1, index2=-1)
+
  toolbar_proc(id_bar, id_action, text="", text2="", command=0, index=-1, index2=-1)
  
 
Perform action on toolbar UI control.
 
Perform action on toolbar UI control.
  
Param "id_toolbar": int handle of toolbar. Can be "top" for main app toolbar. Function returns None, if id_toolbar not correct.
+
Param "id_bar": int handle of toolbar.
  
 
Param "id_action" possible values:
 
Param "id_action" possible values:
Line 1,761: Line 1,973:
 
===statusbar_proc===
 
===statusbar_proc===
  
  statusbar_proc(id_statusbar, id_action, index=-1, tag=0, value="")
+
  statusbar_proc(id_bar, id_action, index=-1, tag=0, value="")
  
 
Perform action on statusbar UI control.
 
Perform action on statusbar UI control.
  
* Param "id_statusbar": handle of control. Can be "main" for main program statusbar.
+
* Param "id_bar": int handle of statusbar.
* Param "index": index of cell (0-based), if action needs it.
+
* Param "index": int index of cell (0-based), if action needs it.
* Param "tag": int tag of cell. Tag value, if not 0, overrides "index" param. It's needed to address a cell without knowing its index, only by tag. CudaText addresses standard cells by tag in the range 1..20.
+
* Param "tag": int tag of cell. Tag value, if not 0, overrides "index" param. It's needed to address a cell without knowing its index, only by tag. CudaText addresses standard cells by tags in the range 1..20.
  
 
Param "id_action" can be:
 
Param "id_action" can be:
Line 1,777: Line 1,989:
 
* STATUSBAR_ADD_CELL: Adds one cell. Param "index": -1: cell will be appended; >=0: cell will be inserted at given index. Param "tag" has special meaning: it is tag value of a new cell. Returns index of new cell, or None if cannot add (e.g. "tag" is busy).
 
* STATUSBAR_ADD_CELL: Adds one cell. Param "index": -1: cell will be appended; >=0: cell will be inserted at given index. Param "tag" has special meaning: it is tag value of a new cell. Returns index of new cell, or None if cannot add (e.g. "tag" is busy).
 
* STATUSBAR_FIND_CELL: Returns index if cell from tag, or None. Param "value": int tag. Params "index", "tag" ignored.
 
* STATUSBAR_FIND_CELL: Returns index if cell from tag, or None. Param "value": int tag. Params "index", "tag" ignored.
 +
* STATUSBAR_MOVE_CELL: Moves cell with specified index or tag, to another index specified in the int param "value". Returns bool: source/target indexes are OK, cell was moved.
  
 
* STATUSBAR_GET_IMAGELIST: Returns handle of imagelist object, attached to statusbar, or 0 for none.
 
* STATUSBAR_GET_IMAGELIST: Returns handle of imagelist object, attached to statusbar, or 0 for none.
 
* STATUSBAR_SET_IMAGELIST: Sets handle if imagelist object. Param "value": handle.
 
* STATUSBAR_SET_IMAGELIST: Sets handle if imagelist object. Param "value": handle.
 +
* STATUSBAR_GET_PADDING: Returns cells padding (left and right, in pixels).
 +
* STATUSBAR_SET_PADDING: Sets cells padding. Param "value": int value.
 +
* STATUSBAR_GET_SEPARATOR: Returns inter-cell separator string.
 +
* STATUSBAR_SET_SEPARATOR: Sets inter-cell separator string. Param "value": string value.
 +
 +
* STATUSBAR_GET_OVERFLOW_LEFT: Returns bool flag "overflow to left". This flag takes action when sum of cells widths overflows the entire statusbar width - flag pushes "redundant first cells" to the left side.
 +
* STATUSBAR_SET_OVERFLOW_LEFT: Sets bool flag "overflow to left". Param "value": bool value.
  
 
* STATUSBAR_GET_COLOR_BACK: Returns color of background.
 
* STATUSBAR_GET_COLOR_BACK: Returns color of background.
 
* STATUSBAR_GET_COLOR_FONT: Returns color of font.
 
* STATUSBAR_GET_COLOR_FONT: Returns color of font.
* STATUSBAR_GET_COLOR_BORDER_TOP: Returns color of border-top.
+
* STATUSBAR_GET_COLOR_BORDER_TOP: Returns color of entire-border-top.
* STATUSBAR_GET_COLOR_BORDER_L: Returns color of border-left.
+
* STATUSBAR_GET_COLOR_BORDER_BOTTOM: Returns color of entire-border-bottom.
* STATUSBAR_GET_COLOR_BORDER_R: Returns color of border-right.
+
* STATUSBAR_GET_COLOR_BORDER_L: Returns color of cells-border-left.
* STATUSBAR_GET_COLOR_BORDER_U: Returns color of border-up.
+
* STATUSBAR_GET_COLOR_BORDER_R: Returns color of cells-border-right.
* STATUSBAR_GET_COLOR_BORDER_D: Returns color of border-down.
+
* STATUSBAR_GET_COLOR_BORDER_U: Returns color of cells-border-up.
 +
* STATUSBAR_GET_COLOR_BORDER_D: Returns color of cells-border-down.
  
 
* STATUSBAR_SET_COLOR_BACK: Sets color of background. Param "value": int color.
 
* STATUSBAR_SET_COLOR_BACK: Sets color of background. Param "value": int color.
 
* STATUSBAR_SET_COLOR_FONT: Sets color of font.
 
* STATUSBAR_SET_COLOR_FONT: Sets color of font.
* STATUSBAR_SET_COLOR_BORDER_TOP: Sets color of border-top.
+
* STATUSBAR_SET_COLOR_BORDER_TOP: Sets color of entire-border-top.
* STATUSBAR_SET_COLOR_BORDER_L: Sets color of border-left.
+
* STATUSBAR_SET_COLOR_BORDER_BOTTOM: Sets color of entire-border-bottom, which is painted if value not equals to COLOR_NONE.
* STATUSBAR_SET_COLOR_BORDER_R: Sets color of border-right.
+
* STATUSBAR_SET_COLOR_BORDER_L: Sets color of cells-border-left.
* STATUSBAR_SET_COLOR_BORDER_U: Sets color of border-up.
+
* STATUSBAR_SET_COLOR_BORDER_R: Sets color of cells-border-right.
* STATUSBAR_SET_COLOR_BORDER_D: Sets color of border-down.
+
* STATUSBAR_SET_COLOR_BORDER_U: Sets color of cells-border-up.
 +
* STATUSBAR_SET_COLOR_BORDER_D: Sets color of cells-border-down.
  
* STATUSBAR_GET_CELL_SIZE: Returns width of cell.
+
* STATUSBAR_GET_CELL_RECT: Returns rectangle of cell coordinates (related to control) as 4-tuple of int, or None.
* STATUSBAR_GET_CELL_AUTOSIZE: Returns auto-size of cell, bool. Auto-size: adjust width of cell to its icon+text.
+
* STATUSBAR_GET_CELL_SIZE: Returns width of cell, or None.
* STATUSBAR_GET_CELL_AUTOSTRETCH: Returns auto-stretch of cell, bool. Auto-stretch: stretch cell to fill entire statusbar width.
+
* STATUSBAR_GET_CELL_AUTOSIZE: Returns auto-size property of cell, bool. Auto-size: adjust width of cell to its icon+text.
* STATUSBAR_GET_CELL_ALIGN: Returns alignment of cell. One of str values: "L" (left), "C" (center), "R" (right).
+
* STATUSBAR_GET_CELL_AUTOSTRETCH: Returns auto-stretch property of cell, bool. Auto-stretch: stretch cell to fill the entire statusbar width.
 +
* STATUSBAR_GET_CELL_ALIGN: Returns alignment of cell's content. One of str values: "L" (left), "C" (center), "R" (right).
 
* STATUSBAR_GET_CELL_TEXT: Returns text of cell.
 
* STATUSBAR_GET_CELL_TEXT: Returns text of cell.
 
* STATUSBAR_GET_CELL_HINT: Returns hint of cell.
 
* STATUSBAR_GET_CELL_HINT: Returns hint of cell.
Line 1,810: Line 2,033:
 
* STATUSBAR_GET_CELL_FONT_NAME: Returns special font name of cell (if empty str, not used).
 
* STATUSBAR_GET_CELL_FONT_NAME: Returns special font name of cell (if empty str, not used).
 
* STATUSBAR_GET_CELL_FONT_SIZE: Returns special font size of cell (if <=0, not used).
 
* STATUSBAR_GET_CELL_FONT_SIZE: Returns special font size of cell (if <=0, not used).
* STATUSBAR_GET_CELL_TAG: Returns int tag of cell.
+
* STATUSBAR_GET_CELL_TAG: Returns int tag of cell. Tag is some plugin-defined int value.
 
* STATUSBAR_GET_CELL_CALLBACK: Returns callback string of cell.
 
* STATUSBAR_GET_CELL_CALLBACK: Returns callback string of cell.
 
* STATUSBAR_GET_CELL_OVERLAY: Returns overlay string of cell.
 
* STATUSBAR_GET_CELL_OVERLAY: Returns overlay string of cell.
Line 1,872: Line 2,095:
  
 
* IMAGE_GET_SIZE: Returns current image size as 2-tuple (width, height).
 
* IMAGE_GET_SIZE: Returns current image size as 2-tuple (width, height).
* IMAGE_LOAD: Reads picture file into image object. Param "value" must be full file path (png, jpg, bmp, gif, ico).
+
* IMAGE_LOAD: Reads picture file into image object. Param "value" must be full file path. Supported formats: PNG, JPEG (extensions: jpg/jpeg/jfif), BMP, GIF, ICO, WEBP.
 
* IMAGE_PAINT: Paints image object on given canvas, at given coords. Param "value" must be tuple (canvas_id, x, y). Value canvas_id can be 0, for testing paintbox in CudaText.
 
* IMAGE_PAINT: Paints image object on given canvas, at given coords. Param "value" must be tuple (canvas_id, x, y). Value canvas_id can be 0, for testing paintbox in CudaText.
 
* IMAGE_PAINT_SIZED: Paints image object on given canvas, resized to given rectangle. Param "value" must be tuple (canvas_id, x1, y1, x2, y2).
 
* IMAGE_PAINT_SIZED: Paints image object on given canvas, resized to given rectangle. Param "value" must be tuple (canvas_id, x1, y1, x2, y2).
Line 1,915: Line 2,138:
 
* BTN_GET_FLAT: Returns flat state, bool.
 
* BTN_GET_FLAT: Returns flat state, bool.
 
* BTN_SET_FLAT: Sets flat state. Param "value" must be bool.
 
* BTN_SET_FLAT: Sets flat state. Param "value" must be bool.
* BTN_GET_DATA1: Returns data1 string. Data1 contains:
+
* BTN_GET_DATA1: Returns data1 string.
** str(integer_command_code) to run command by number like Editor.cmd()
+
* BTN_SET_DATA1: Sets data1 string. It must contain one of the following:
** or string with [[#Callback_param]]. Note: not any callback form, only string callback form
+
** str(command_code) to run command by its integer code, like Editor.cmd() API does.
* BTN_SET_DATA1: Sets data1 string. See BTN_GET_DATA1.
+
** string with [[#Callback_parameter]]. Note: only string callback forms are allowed here, ie callable form is not allowed.
* BTN_GET_DATA2: Returns data2 string. Data2 is currently not used by CudaText.
+
* BTN_GET_DATA2: Returns data2 string. This string is not used by CudaText, but is used by plugins.
* BTN_SET_DATA2: Sets data2 string. See BTN_GET_DATA2.
+
* BTN_SET_DATA2: Sets data2 string.
 
* BTN_GET_WIDTH: Returns width (in pixels).
 
* BTN_GET_WIDTH: Returns width (in pixels).
 
* BTN_SET_WIDTH: Sets width.
 
* BTN_SET_WIDTH: Sets width.
Line 1,940: Line 2,163:
 
=Editor class=
 
=Editor class=
  
Editor class has methods to work with editor. Global objects of Editor exist:
+
Editor class has methods to work with editor-controls.
 +
 
 +
* Editor(0), the same as global object "ed", refers to the currently focused editor in UI-tabs.
 +
* Editor(1) refers the editor of right-clicked UI-tab.
  
* "ed": refers to currently focused editor (in any tab).
+
Notes:
 +
 
 +
* Most of Editor APIs work for editor-controls in the UI-tabs and for editor-controls created by dlg_proc(). But not all the APIs, some of them require the editor-control in the UI-tab. For example, some get_prop()/set_prop() properties need the editor in UI-tab.
 +
* While CudaText has the file viewer active (not the editor, only binary/hex viewer), the editor is hidden and empty, so Editor APIs don't work.
  
 
==Carets==
 
==Carets==
Line 1,974: Line 2,203:
 
Controls carets. Possible values of "id":
 
Controls carets. Possible values of "id":
  
* CARET_SET_ONE: Removes multi-carets and sets single caret with given position (posx, posy, endx, endy). To place caret without selection, set both "endx", "endy" to -1.
+
* CARET_SET_ONE: Removes multi-carets and sets single caret to the given position (posx, posy, endx, endy). To place caret without selection, set both "endx", "endy" to -1.
* CARET_ADD: Adds caret (multi-carets feature) with given position. Returns number of carets after that.
+
* CARET_ADD: Adds caret (multi-carets feature) with given position (posx, posy, endx, endy). Returns number of carets after that.
* CARET_DELETE_ALL: Deletes all carets. Note: you must add caret then to enable text editing to user.
+
* CARET_DELETE_ALL: Deletes all carets. Parameters "posx", "posy", "endx", "endy" are ignored here. Note: you must add caret(s) later, to enable text editing to user.
* CARET_SET_INDEX + N, where N is 0...1e6: Changes single caret with index N to given position.
+
* CARET_SET_INDEX + N, where N is 0...1e6: Places single caret, with index N, to the given position (posx, posy, endx, endy).
* CARET_DELETE_INDEX + N, where N is 0...1e6: Deletes single caret with index N.
+
* CARET_DELETE_INDEX + N, where N is 0...1e6: Deletes single caret, with index N. Parameters "posx", "posy", "endx", "endy" are ignored here.
  
 
Param "options" must be 0 or sum of the following flags:
 
Param "options" must be 0 or sum of the following flags:
  
 
* CARET_OPTION_NO_SCROLL: Don't scroll to new caret position. For id=CARET_SET_ONE.
 
* CARET_OPTION_NO_SCROLL: Don't scroll to new caret position. For id=CARET_SET_ONE.
* CARET_OPTION_UNFOLD: If caret placed into folded line, unfold that line. For id=CARET_SET_ONE.
 
  
 
==Text read/write==
 
==Text read/write==
Line 1,991: Line 2,219:
 
  get_text_all()
 
  get_text_all()
  
Returns the entire editor text, as string.
+
Returns the entire editor text as string.
Returns "\n" as line-breaks.
+
 
 +
Notes:
 +
* All line breaks are returned as LF, ie "\n".
  
 
===Editor.set_text_all===
 
===Editor.set_text_all===
Line 2,004: Line 2,234:
 
* Function cannot work with read-only editor (see Editor.get_prop, Editor.set_prop and PROP_RO).
 
* Function cannot work with read-only editor (see Editor.get_prop, Editor.set_prop and PROP_RO).
 
* Function looses Undo information. To support Undo, use another API to set text, e.g. Editor.replace().
 
* Function looses Undo information. To support Undo, use another API to set text, e.g. Editor.replace().
 +
 +
===Editor.get_line_len===
 +
 +
get_line_len(index)
 +
 +
Returns length of internal line UTF-16 (without BOM) representation.
 +
It is not the same as len(ed.get_text_line(index)), if internal UTF-16 representation has surrogate-pairs.
 +
Returns None if index is incorrect.
  
 
===Editor.get_text_line===
 
===Editor.get_text_line===
Line 2,010: Line 2,248:
  
 
Returns single line (str) with given index (0-based). Without ending line-break char(s).
 
Returns single line (str) with given index (0-based). Without ending line-break char(s).
Returns None if index incorrect.
+
Returns None if index is incorrect.
  
 
If param "max_len" is non-zero, and UTF-8 length of given line is greater than "max_len", function returns empty str. This allows to skip huge lines.
 
If param "max_len" is non-zero, and UTF-8 length of given line is greater than "max_len", function returns empty str. This allows to skip huge lines.
Line 2,018: Line 2,256:
 
  set_text_line(index, text)
 
  set_text_line(index, text)
  
Sets single line (str) with given index (0-based).
+
Changes single line with given index (0-based) to given text.
Text must be without line-breaks.
+
Text should be without line-breaks, because "\n" and "\r" chars will be replaced with "_".
To add new line, pass index=-1.
+
 
 +
Special "index" values:
 +
* -1: Append new line, with final end-of-line.
 +
* -2: Append new line, but without final end-of-line.
  
 
===Editor.get_text_substr===
 
===Editor.get_text_substr===
Line 2,027: Line 2,268:
  
 
Returns substring from position (x1, y1) to bigger position (x2, y2).
 
Returns substring from position (x1, y1) to bigger position (x2, y2).
 +
Coordinates x1 / x2 are in the UTF-16 internal representation of line.
  
 
===Editor.delete===
 
===Editor.delete===
Line 2,033: Line 2,275:
  
 
Deletes range from position (x1, y1) to bigger position (x2, y2).
 
Deletes range from position (x1, y1) to bigger position (x2, y2).
 +
Coordinates x1 / x2 are in the UTF-16 internal representation of line.
  
 
* Too big x1/x2 are allowed (after line-end)
 
* Too big x1/x2 are allowed (after line-end)
 
* Too big y2 means delete to end of file
 
* Too big y2 means delete to end of file
  
Note: don't pass tuple from get_carets()[0], this tuple has not sorted pos=(x1, y1), end=(x2, y2), you need to sort them (first sort by y, then by x).
+
Note: don't pass tuple from get_carets()[0], this tuple has not sorted positions (x1, y1) and (x2, y2), you need to sort them (first sort by y, then by x).
  
 
Example replaces selection of 1st caret with text:
 
Example replaces selection of 1st caret with text:
Line 2,055: Line 2,298:
 
  insert(x, y, text)
 
  insert(x, y, text)
  
Inserts given text at position (x, y). If y too big, appends block to end (even to final line w/out line-end).
+
Inserts given text at position (x, y).
Text can be multi-line, all CR LF are converted to currently used line-breaks.
+
If param "y" is after the actual line-count, appends block to the end (even to final line without line-ending).
 +
Coordinate "x" is in the UTF-16 internal representation of line.
 +
Text can be multi-line, all CR LF will be converted to currently used line-breaks.
  
 
Returns 2-tuple (x, y) of position after inserted text. It is on the same line, if text is single line. Returns None if cannot insert.
 
Returns 2-tuple (x, y) of position after inserted text. It is on the same line, if text is single line. Returns None if cannot insert.
Line 2,065: Line 2,310:
  
 
Replaces range from position (x1, y1) to bigger position (x2, y2), with new text.
 
Replaces range from position (x1, y1) to bigger position (x2, y2), with new text.
 +
Coordinates x1 / x2 are in the UTF-16 internal representation of line.
  
 
* Too big x1/x2 are allowed (after line-end)
 
* Too big x1/x2 are allowed (after line-end)
Line 2,084: Line 2,330:
 
* Index y1 must be valid index (0 to count-1)
 
* Index y1 must be valid index (0 to count-1)
 
* Index y2 can be less than y1 (to not delete), and can be too big (to delete lines to end)
 
* Index y2 can be less than y1 (to not delete), and can be too big (to delete lines to end)
* Param lines is list/tuple of str. Can be empty list to just delete lines. Inside items should not be "\n" and "\r": "\n" will generate additonal lines, "\r" not handled.
+
* Param lines is list/tuple of str. Can be empty list to just delete lines. Inside items should not be "\n" and "\r": "\n" will generate additional lines, "\r" not handled.
  
 
Returns bool: index y1 correct, replace done.
 
Returns bool: index y1 correct, replace done.
Line 2,127: Line 2,373:
  
 
Returns number of lines.
 
Returns number of lines.
 +
 +
===Editor.get_char_count===
 +
 +
get_char_count(max_chars, max_time)
 +
 +
Returns number of UTF-16 characters.
 +
 +
Each UTF-16 character in internal storage is counted as 1.
 +
Line-break is counted as 1, even for CR LF endings.
 +
 +
* Param "max_chars": If result becomes (in internal loop) bigger than param value, stop counting and return -1. Pass very big value, for example 0x7fffFFFF, to avoid the limit.
 +
* Param "max_time": If method working time becomes bigger than param value (in milliseconds), stop counting and return -2. Pass 0x7fffFFFF to avoid time checking.
 +
** Example: on CPU Intel Core i3 3GHz, with file "torrent.cpp" with 5K lines with 414K chars, "max_time" must be >=10 to count all content.
  
 
===Editor.get_filename===
 
===Editor.get_filename===
Line 2,132: Line 2,391:
 
  get_filename(options="")
 
  get_filename(options="")
  
Returns filename (str) of the editor.
+
Returns filename (string) of the editor.
  
 
* Returns empty string for untitled tab.
 
* Returns empty string for untitled tab.
* Returns string "?" if tab contains not normal text editor. See: get_prop(PROP_KIND).
+
* Returns string "?" if ui-tab contains not normal text editor, but picture viewer or binary viewer. You can detect the kind of ui-tab: Editor.get_prop(PROP_KIND).
  
If param "options" contains char "*", the real file name is always returned, even in hex/picture viewer mode.
+
If param "options" contains char "*", the real file name is always returned, even in picture/binary viewer mode.
  
 
===Editor.get_prop===
 
===Editor.get_prop===
Line 2,152: Line 2,411:
 
* PROP_GUTTER_FOLD: bool: show gutter column "folding".
 
* PROP_GUTTER_FOLD: bool: show gutter column "folding".
 
* PROP_GUTTER_BM: bool: show gutter column "bookmarks".
 
* PROP_GUTTER_BM: bool: show gutter column "bookmarks".
 +
* PROP_GUTTER_EMPTY: bool: show gutter column "empty padding".
 +
* PROP_GUTTER_EMPTY_WIDTH: int: width of gutter column "empty padding".
 +
 
* PROP_NEWLINE: str: kind of line endings. One of values "lf", "crlf", "cr".
 
* PROP_NEWLINE: str: kind of line endings. One of values "lf", "crlf", "cr".
 
* PROP_WRAP: int: word-wrap mode. One of WRAP_nnn values.
 
* PROP_WRAP: int: word-wrap mode. One of WRAP_nnn values.
Line 2,160: Line 2,422:
 
* PROP_MODIFIED: bool: editor is modified.
 
* PROP_MODIFIED: bool: editor is modified.
 
* PROP_MODIFIED_VERSION: int: counter which is incremented on each text change.
 
* PROP_MODIFIED_VERSION: int: counter which is incremented on each text change.
* PROP_RULER: bool: horz ruler is shown.
+
* PROP_RULER: bool: show 'ruler' horizontal band.
 +
* PROP_RULER_TEXT: str: text of one line or several "\n"-separated lines, which is rendered on 'ruler' band. [[#HTML formatting]] is allowed if "&lt;html&gt;" prefix is used.  
  
 
* PROP_LINE_STATE: int: state of the line with given index. One of LINESTATE_nnn values.
 
* PROP_LINE_STATE: int: state of the line with given index. One of LINESTATE_nnn values.
Line 2,168: Line 2,431:
 
* PROP_LINE_NUMBERS: int: style of line numbers. One of LINENUM_nnn values.
 
* PROP_LINE_NUMBERS: int: style of line numbers. One of LINENUM_nnn values.
 
* PROP_LINE_TOP: int: index of line visible at the top of editor.
 
* PROP_LINE_TOP: int: index of line visible at the top of editor.
 +
** Note: If you set PROP_LINE_TOP immediately after file_open(), it may not work, you need to call app_idle(True) first.
 
* PROP_LINE_BOTTOM: int: index of line visible at the bottom of editor (considers word wrap).
 
* PROP_LINE_BOTTOM: int: index of line visible at the bottom of editor (considers word wrap).
  
Line 2,179: Line 2,443:
 
* PROP_SCROLLSTYLE_VERT: int: style of vertical scrollbar, one of SCROLLSTYLE_ constants.
 
* PROP_SCROLLSTYLE_VERT: int: style of vertical scrollbar, one of SCROLLSTYLE_ constants.
  
 +
* PROP_CORNER_TEXT: str: short text (multi-line is allowed, separator chr(10)) in the right-bottom corner (rendered above editor text).
 +
* PROP_CORNER_COLOR_FONT: int: font-color for PROP_CORNER_TEXT; can be COLOR_NONE.
 +
* PROP_CORNER_COLOR_BACK: int: background-color for PROP_CORNER_TEXT; can be COLOR_NONE.
 +
* PROP_CORNER_COLOR_BORDER: int: border-color for PROP_CORNER_TEXT; can be COLOR_NONE.
 +
* PROP_CORNER_FONT_NAME: str: if not empty, specifies font name for PROP_CORNER_TEXT. If empty, editor font name is used.
 +
* PROP_CORNER_FONT_SIZE: int: if >0, specifies font size for PROP_CORNER_TEXT. If 0, editor font size is used.
 +
* PROP_CORNER2_TEXT: like PROP_CORNER_TEXT but for the right-top corner.
 +
* PROP_CORNER2_COLOR_FONT: like PROP_CORNER_COLOR_FONT but for the right-top corner.
 +
* PROP_CORNER2_COLOR_BACK: like PROP_CORNER_COLOR_BACK but for the right-top corner.
 +
* PROP_CORNER2_COLOR_BORDER: like PROP_CORNER_COLOR_BORDER but for the right-top corner.
 +
* PROP_CORNER2_FONT_NAME: like PROP_CORNER_FONT_NAME but for the right-top corner.
 +
* PROP_CORNER2_FONT_SIZE: like PROP_CORNER_FONT_SIZE but for the right-top corner.
 +
 +
* PROP_BORDER_COLOR: int: if active, ie value not equals to COLOR_NONE, specifies color of border around the editor (like with macro-recording active).
 +
* PROP_BORDER_COLOR_WIDTH: int: border width for PROP_BORDER_COLOR.
 +
 +
* PROP_WHEEL_ZOOMS: bool: enable zooming by Ctrl+[mouse wheel up/down].
 
* PROP_SCALE_FONT: int: scale of editor's font in percents, or 0 to use global app font scale.
 
* PROP_SCALE_FONT: int: scale of editor's font in percents, or 0 to use global app font scale.
 
* PROP_COLOR: int: color property. Value must be one of COLOR_ID_nnn values. Returns None for incorrect id.
 
* PROP_COLOR: int: color property. Value must be one of COLOR_ID_nnn values. Returns None for incorrect id.
Line 2,198: Line 2,479:
 
* PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
 
* PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
 
* PROP_CARET_STOP_UNFOCUSED: bool: caret blinks only when editor is focused.
 
* PROP_CARET_STOP_UNFOCUSED: bool: caret blinks only when editor is focused.
 +
* PROP_CARET_MULTI: bool: allow multi-carets.
 
* PROP_MACRO_REC: bool: currently macro is recording.
 
* PROP_MACRO_REC: bool: currently macro is recording.
 
* PROP_MARKED_RANGE: 2-tuple with line indexes of "marked range"; (-1, -1) if range not set.
 
* PROP_MARKED_RANGE: 2-tuple with line indexes of "marked range"; (-1, -1) if range not set.
Line 2,204: Line 2,486:
 
* PROP_PICTURE: properties of picture file as 3-tuple: (picture_filename, size_x, size_y), or None if not picture loaded in tab. For picture ed.get_filename() returns "?".
 
* PROP_PICTURE: properties of picture file as 3-tuple: (picture_filename, size_x, size_y), or None if not picture loaded in tab. For picture ed.get_filename() returns "?".
 
* PROP_MINIMAP: bool: minimap is visible.
 
* PROP_MINIMAP: bool: minimap is visible.
 +
* PROP_MINIMAP_CHAR_WIDTH: int: minimap width, in average chars.
 +
* PROP_MINIMAP_SCALE: int: minimap custom scale, in percents; if value<=100: auto-detect.
 +
* PROP_MINIMAP_AT_LEFT: bool: minimap is shown on the left side.
 
* PROP_MICROMAP: bool: micromap is visible.
 
* PROP_MICROMAP: bool: micromap is visible.
 
* PROP_LINK_AT_POS: str: hyperlink string in the document, at given position. Value must be 2-tuple: (pos_x, pos_y).
 
* PROP_LINK_AT_POS: str: hyperlink string in the document, at given position. Value must be 2-tuple: (pos_x, pos_y).
Line 2,211: Line 2,496:
 
* PROP_IN_SESSION: bool: document was loaded from "session".
 
* PROP_IN_SESSION: bool: document was loaded from "session".
 
* PROP_IN_HISTORY: bool: document history was loaded from history file (history embedded to "session" or main history file).
 
* PROP_IN_HISTORY: bool: document history was loaded from history file (history embedded to "session" or main history file).
* PROP_TAB_SPACES: bool: tab-key inserts spaces (not tab-char).
+
* PROP_TAB_SPACES: bool: tab-key inserts spaces, not tab-char.
 
* PROP_TAB_SIZE: int: size of tab-char.
 
* PROP_TAB_SIZE: int: size of tab-char.
 +
* PROP_TAB_SMART: bool: smart-tabs option, known from many text editors.
 
* PROP_TAB_COLLECT_MARKERS: bool: tab-key collects (jumps to and deletes) markers (if markers placed).
 
* PROP_TAB_COLLECT_MARKERS: bool: tab-key collects (jumps to and deletes) markers (if markers placed).
* PROP_TAB_TITLE: str: title of tab, useful for untitled tabs, for tabs with picture files.
+
* PROP_TAB_TITLE: str: custom title of ui-tab; setting to empty string removes the custom title.
* PROP_TAB_COLOR: int: color of tab containing editor; COLOR_NONE if not set.
+
* PROP_TAB_TITLE_REASON: str (1 char): reason of current ui-tab title.
* PROP_TAB_ICON: int: index of tab icon, ie index in imagelist, which handle you can get via app_proc(PROC_GET_TAB_IMAGELIST).
+
** "u": Usual untitled tab
* PROP_TAB_PINNED: bool: tab is "pinned" (shows additional confirmation on closing).
+
** "s": App-special untitled tab, e.g. "RegEx search", "Welcome"
* PROP_TAB_ID: int: unique tab's identifier (one number for main/secondary editors in tab), it is not changed when tab is moved.
+
** "f": Title was calculated from filename
 +
** "p": Title was set by plugin API
 +
* PROP_TAB_COLOR: int: color of ui-tab title background, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
 +
* PROP_TAB_COLOR_FONT: int: color of ui-tab title font, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
 +
* PROP_TAB_ICON: int: index of ui-tab icon, ie index in imagelist, which handle you can get via app_proc(PROC_GET_TAB_IMAGELIST).
 +
* PROP_TAB_PINNED: bool: ui-tab is "pinned" (shows additional confirmation on closing).
 +
* PROP_TAB_UI_SHOW: bool: ui-tab header is visible on the tabs-bar.
 +
* PROP_TAB_ID: int: ui-tab's unique identifier (single value for primary/secondary editors in tab); it is not changed when tab is moved to another position/group.
 
* PROP_INDENT_SIZE: int: size of indent for Indent/Unindent commands. N>0: indent in spaces, N<0: indent in tabs, N=0: indent from PROP_TAB_SIZE/PROP_TAB_SPACES.
 
* PROP_INDENT_SIZE: int: size of indent for Indent/Unindent commands. N>0: indent in spaces, N<0: indent in tabs, N=0: indent from PROP_TAB_SIZE/PROP_TAB_SPACES.
 
* PROP_INDENT_KEEP_ALIGN: bool: command Unindent keeps alignment of block edge, ie don't unindent if any line reached column 0.
 
* PROP_INDENT_KEEP_ALIGN: bool: command Unindent keeps alignment of block edge, ie don't unindent if any line reached column 0.
Line 2,251: Line 2,544:
 
* PROP_FONT_I: 2-tuple (str, int): italic font: name, size. Empty name: not used.
 
* PROP_FONT_I: 2-tuple (str, int): italic font: name, size. Empty name: not used.
 
* PROP_FONT_BI: 2-tuple (str, int): bold+italic font: name, size. Empty name: not used.
 
* PROP_FONT_BI: 2-tuple (str, int): bold+italic font: name, size. Empty name: not used.
* PROP_ACTIVATION_TIME: int: relative time (in OS timer ticks) when tab ("main" or "brother" editor in the same tab) was last focused. It's 0 for not yet focused tabs. It's None for editors created by dlg_proc().
+
* PROP_ACTIVATION_TIME: int: time (in milliseconds since OS start) when editor was last focused. It's 0 for not yet focused editors.
 
* PROP_KIND: str: kind of UI control in the tab.
 
* PROP_KIND: str: kind of UI control in the tab.
** "text": normal editor
+
** "text": normal editor.
** "bin": binary viewer
+
** "bin": text/binary/hex viewer.
** "pic": picture
+
** "pic": picture viewer.
  
 
* PROP_SPLIT: 2-tuple: information about primary/secondary editors splitting as tuple (split_kind, split_pos).
 
* PROP_SPLIT: 2-tuple: information about primary/secondary editors splitting as tuple (split_kind, split_pos).
Line 2,265: Line 2,558:
 
* PROP_SAVING_TRIM_FINAL_EMPTY_LINES: bool: on saving file, trim redundant empty lines at end of document.
 
* PROP_SAVING_TRIM_FINAL_EMPTY_LINES: bool: on saving file, trim redundant empty lines at end of document.
  
* PROP_HANDLE_SELF: int: handle of editor object, for which get_prop() is called. This handle is unique among all objects in program (it is memory address).
+
* PROP_HANDLE_SELF: int: handle of editor object, for which get_prop() is called. This handle is unique among all objects in program (it is memory address). Why not just use "ed.h"? Because: 1) For "ed" object its handle "ed.h" is zero - zero handle is virtual handle pointing to the focused editor. 2) For "ed_handles()" result, handles are also virtual, they are some small integer numbers, not memory addresses. Note: to get editor object from handle, use "Editor(handle_value)".
** To get editor object from handle, use ed_obj=Editor(handle_value).
 
** Object "ed" has virtual handle 0 for active focused editor, ie ed.h==0. And PROP_HANDLE_SELF returns the actual non-zero handle.
 
 
* PROP_HANDLE_PRIMARY: int: handle of editor object, which is primary editor in ui-tab (primary editor is always visible). It's None for editor objects created from dlg_proc().
 
* PROP_HANDLE_PRIMARY: int: handle of editor object, which is primary editor in ui-tab (primary editor is always visible). It's None for editor objects created from dlg_proc().
 
* PROP_HANDLE_SECONDARY: int: handle of editor object, which is secondary editor in ui-tab (secondary editor is visible only when ui-tab is splitted). It's None for editor objects created from dlg_proc().
 
* PROP_HANDLE_SECONDARY: int: handle of editor object, which is secondary editor in ui-tab (secondary editor is visible only when ui-tab is splitted). It's None for editor objects created from dlg_proc().
* PROP_HANDLE_PARENT: int: handle of parent of editor object, or 0 if no such parent. This handle is needed to dock forms near the editor.
+
* PROP_HANDLE_PARENT: int: handle of parent of editor object, or 0 if no such parent. This is handle of dialog containing the editor, it can be passed to dlg_proc(). This handle is needed to dock custom dialogs into the editor, again via dlg_proc().
 
 
 
* PROP_COORDS: 4-tuple of int: rectangle of entire editor area, relative to screen.
 
* PROP_COORDS: 4-tuple of int: rectangle of entire editor area, relative to screen.
 
* PROP_RECT_CLIENT: 4-tuple of int: rectangle of entire editor area, relative to editor.
 
* PROP_RECT_CLIENT: 4-tuple of int: rectangle of entire editor area, relative to editor.
Line 2,280: Line 2,570:
 
* PROP_RECT_RULER: 4-tuple of int: rectangle of "horizontal ruler" editor area, relative to editor. It is (0,0,0,0) if area is hidden.
 
* PROP_RECT_RULER: 4-tuple of int: rectangle of "horizontal ruler" editor area, relative to editor. It is (0,0,0,0) if area is hidden.
  
 +
* PROP_THEMED: bool: for editors out of UI-tabs, allows to automatically apply current theme on app theme changing.
 
* PROP_COMBO_ITEMS: only for "editor_combo" control, contents of drop-down list. On getting: list of str. On setting: value must be str with '\n'-separated items.
 
* PROP_COMBO_ITEMS: only for "editor_combo" control, contents of drop-down list. On getting: list of str. On setting: value must be str with '\n'-separated items.
  
Line 2,287: Line 2,578:
 
* PROP_NUMBERS_ONLY: bool: allow to input only numbers.
 
* PROP_NUMBERS_ONLY: bool: allow to input only numbers.
 
* PROP_NUMBERS_NEGATIVE: bool: additional to PROP_NUMBERS_ONLY, allow negative numbers<0.
 
* PROP_NUMBERS_NEGATIVE: bool: additional to PROP_NUMBERS_ONLY, allow negative numbers<0.
 +
 +
* PROP_COMMAND_LOG: list of last executed commands, as list of dict. Dict keys are:
 +
** "code": Integer command code.
 +
*** Special codes: value cmd_PluginRun means 'plugin started', value cmd_PluginEnd means 'plugin returned'. For these codes, "text" key has the value "py:module,method," or "py:module,method,param".
 +
** "invoke": String, how the command was invoked. One of values:
 +
*** "int": Internal calling from core components.
 +
*** "int_ime": Internal calling via OS IME dialog.
 +
*** "key": Calling via some hotkey.
 +
*** "menu_ctx": Calling from some context menu.
 +
*** "menu_main": Calling from the main menu.
 +
*** "app_int": Internal calling from high-level CudaText code.
 +
*** "app_pal": Calling from the Command Palette.
 +
*** "app_toolbar": Calling via toolbar buttons.
 +
*** "app_sidebar": Calling via sidebar buttons.
 +
*** "app_charmap": Calling via Char Map dialog.
 +
*** "app_dragdrop": Calling via drag-and-drop.
 +
*** "app_api": Calling from some Python API handler.
 +
** "text": Text of command. It's not empty only in few cases, e.g. for command codes cCommand_TextInsert / cmd_PluginRun / cmd_PluginEnd.
 +
 +
* PROP_COMMAND_LOG_LIMIT: int: maximal count of items in the list returned by PROP_COMMAND_LOG.
 +
 +
* PROP_DIM_UNFOCUSED: int: for unfocused editor, dim the background color by specified percents (ranges is -250...250, 0: disabled).
  
 
* PROP_V_MODE: int: mode of binary viewer. Reading it for editor, returns VMODE_NONE. Reading it for viewer, returns one of: VMODE_TEXT, VMODE_BINARY, VMODE_HEX, VMODE_UNICODE, VMODE_UNICODE_HEX.
 
* PROP_V_MODE: int: mode of binary viewer. Reading it for editor, returns VMODE_NONE. Reading it for viewer, returns one of: VMODE_TEXT, VMODE_BINARY, VMODE_HEX, VMODE_UNICODE, VMODE_UNICODE_HEX.
Line 2,295: Line 2,608:
 
* PROP_V_WIDTH_HEX: int: for binary viewer, width of text in mode VMODE_HEX.
 
* PROP_V_WIDTH_HEX: int: for binary viewer, width of text in mode VMODE_HEX.
 
* PROP_V_WIDTH_UHEX: int: for binary viewer, width of text in mode VMODE_UNICODE_HEX.
 
* PROP_V_WIDTH_UHEX: int: for binary viewer, width of text in mode VMODE_UNICODE_HEX.
 +
* PROP_V_ENC: str: for binary viewer, its encoding.
  
 
===Editor.set_prop===
 
===Editor.set_prop===
Line 2,309: Line 2,623:
 
* PROP_GUTTER_FOLD: bool: show gutter column "folding".
 
* PROP_GUTTER_FOLD: bool: show gutter column "folding".
 
* PROP_GUTTER_BM: bool: show gutter column "bookmarks".
 
* PROP_GUTTER_BM: bool: show gutter column "bookmarks".
 +
* PROP_GUTTER_EMPTY: bool: show gutter column "empty padding".
 +
* PROP_GUTTER_EMPTY_WIDTH: int: width of gutter column "empty padding".
 +
 
* PROP_WRAP: int: word-wrap mode. One of WRAP_nnn values.
 
* PROP_WRAP: int: word-wrap mode. One of WRAP_nnn values.
 
* PROP_RO: bool: read-only mode.
 
* PROP_RO: bool: read-only mode.
Line 2,316: Line 2,633:
 
* PROP_INSERT: bool: insert/overwrite mode.
 
* PROP_INSERT: bool: insert/overwrite mode.
 
* PROP_MODIFIED: bool: editor is modified.
 
* PROP_MODIFIED: bool: editor is modified.
* PROP_RULER: bool: show ruler.
+
* PROP_RULER: bool: show 'ruler' horizontal band.
 +
* PROP_RULER_TEXT: str: text of one line or several "\n"-separated lines, which is rendered on 'ruler' band. [[#HTML formatting]] is allowed if "&lt;html&gt;" prefix is used.
 +
 
 
* PROP_COLOR: color property, value must be 2-tuple (COLOR_ID_nnnn, int_color_value).
 
* PROP_COLOR: color property, value must be 2-tuple (COLOR_ID_nnnn, int_color_value).
 
* PROP_LINE_TOP: int: index of line visible at the editor top.
 
* PROP_LINE_TOP: int: index of line visible at the editor top.
 +
** Note: If you set PROP_LINE_TOP immediately after file_open(), it may not work, you need to call app_idle(True) first.
 
* PROP_LINE_NUMBERS: int: style of line numbers. One of LINENUM_nnn values.
 
* PROP_LINE_NUMBERS: int: style of line numbers. One of LINENUM_nnn values.
 
* PROP_LINE_STATE: 2-tuple: state of the line with given index. 2-tuple (line_index, LINESTATE_nnn).
 
* PROP_LINE_STATE: 2-tuple: state of the line with given index. 2-tuple (line_index, LINESTATE_nnn).
Line 2,330: Line 2,650:
 
* PROP_SCROLLSTYLE_VERT: int: style of vertical scrollbar, one of SCROLLSTYLE_ constants.
 
* PROP_SCROLLSTYLE_VERT: int: style of vertical scrollbar, one of SCROLLSTYLE_ constants.
  
 +
* PROP_CORNER_TEXT: str: short text (multi-line is allowed, separator chr(10)) in the right-bottom corner (rendered above editor text).
 +
* PROP_CORNER_COLOR_FONT: int: font-color for PROP_CORNER_TEXT; can be COLOR_NONE.
 +
* PROP_CORNER_COLOR_BACK: int: background-color for PROP_CORNER_TEXT; can be COLOR_NONE.
 +
* PROP_CORNER_COLOR_BORDER: int: border-color for PROP_CORNER_TEXT; can be COLOR_NONE.
 +
* PROP_CORNER_FONT_NAME: str: if not empty, specifies font name for PROP_CORNER_TEXT. If empty, editor font name is used.
 +
* PROP_CORNER_FONT_SIZE: int: if >0, specifies font size for PROP_CORNER_TEXT. If 0, editor font size is used.
 +
* PROP_CORNER2_TEXT: like PROP_CORNER_TEXT but for the right-top corner.
 +
* PROP_CORNER2_COLOR_FONT: like PROP_CORNER_COLOR_FONT but for the right-top corner.
 +
* PROP_CORNER2_COLOR_BACK: like PROP_CORNER_COLOR_BACK but for the right-top corner.
 +
* PROP_CORNER2_COLOR_BORDER: like PROP_CORNER_COLOR_BORDER but for the right-top corner.
 +
* PROP_CORNER2_FONT_NAME: like PROP_CORNER_FONT_NAME but for the right-top corner.
 +
* PROP_CORNER2_FONT_SIZE: like PROP_CORNER_FONT_SIZE but for the right-top corner.
 +
 +
* PROP_BORDER_COLOR: int: if active, ie value not equals to COLOR_NONE, specifies color of border around the editor (like with macro-recording active).
 +
* PROP_BORDER_COLOR_WIDTH: int: border width for PROP_BORDER_COLOR.
 +
 +
* PROP_WHEEL_ZOOMS: bool: enable zooming by Ctrl+[mouse wheel up/down].
 
* PROP_SCALE_FONT: int: scale of editor's font in percents, or 0 to use global app font scale.
 
* PROP_SCALE_FONT: int: scale of editor's font in percents, or 0 to use global app font scale.
 
* PROP_ENC: str: encoding name. Names listed at [[CudaText#Encodings]].
 
* PROP_ENC: str: encoding name. Names listed at [[CudaText#Encodings]].
Line 2,347: Line 2,684:
 
* PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
 
* PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
 
* PROP_CARET_STOP_UNFOCUSED: bool: caret blinks only when editor is focused.
 
* PROP_CARET_STOP_UNFOCUSED: bool: caret blinks only when editor is focused.
 +
* PROP_CARET_MULTI: bool: allow multi-carets.
 
* PROP_MARKED_RANGE: line indexes of "marked range", value is 2-tuple (index1, index2) or (-1, -1) to remove this range.
 
* PROP_MARKED_RANGE: line indexes of "marked range", value is 2-tuple (index1, index2) or (-1, -1) to remove this range.
 
* PROP_MINIMAP: bool: minimap is visible.
 
* PROP_MINIMAP: bool: minimap is visible.
 +
* PROP_MINIMAP_CHAR_WIDTH: int: minimap width, in average chars.
 +
* PROP_MINIMAP_SCALE: int: minimap custom scale, in percents; if value<=100: auto-detect.
 +
* PROP_MINIMAP_AT_LEFT: bool: minimap is shown on the left side.
 
* PROP_MICROMAP: bool: micromap is visible.
 
* PROP_MICROMAP: bool: micromap is visible.
 
* PROP_LINKS_SHOW: bool: enable hyperlinks underlining.
 
* PROP_LINKS_SHOW: bool: enable hyperlinks underlining.
 
* PROP_LINKS_REGEX: str: regular expression for hyperlinks.
 
* PROP_LINKS_REGEX: str: regular expression for hyperlinks.
 
* PROP_LINKS_CLICKS: int: how mouse clicks activate hyperlinks. 0: disabled, 1: single click, 2: double click.
 
* PROP_LINKS_CLICKS: int: how mouse clicks activate hyperlinks. 0: disabled, 1: single click, 2: double click.
* PROP_TAB_SPACES: bool: tab-key inserts spaces.
+
* PROP_TAB_SPACES: bool: tab-key inserts spaces, not tab-char.
 
* PROP_TAB_SIZE: int: size of tab-char.
 
* PROP_TAB_SIZE: int: size of tab-char.
 +
* PROP_TAB_SMART: bool: smart-tabs option, known from many text editors.
 
* PROP_TAB_COLLECT_MARKERS: bool: tab-key collects (jumps to and deletes) markers.
 
* PROP_TAB_COLLECT_MARKERS: bool: tab-key collects (jumps to and deletes) markers.
* PROP_TAB_COLOR: int: color of tab containing editor; set COLOR_NONE to reset.
+
* PROP_TAB_COLOR: int: color of ui-tab title background, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
* PROP_TAB_TITLE: str: title of tab, useful for untitled tabs.
+
* PROP_TAB_COLOR_FONT: int: color of ui-tab title font, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
* PROP_TAB_ICON: int: index of tab icon, ie index in imagelist, which handle you can get via app_proc(PROC_GET_TAB_IMAGELIST).
+
* PROP_TAB_TITLE: str: custom title of ui-tab; setting to empty string removes the custom title.
* PROP_TAB_PINNED: bool: tab is "pinned" (shows additional confirmation on closing).
+
* PROP_TAB_TITLE_REASON: str (1 char): reason of current ui-tab title.
 +
** "u": Usual untitled tab
 +
** "s": App-special untitled tab, e.g. "RegEx search", "Welcome"
 +
** "f": Title was calculated from filename
 +
** "p": Title was set by plugin API
 +
* PROP_TAB_ICON: int: index of ui-tab icon, ie index in imagelist, which handle you can get via app_proc(PROC_GET_TAB_IMAGELIST).
 +
* PROP_TAB_PINNED: bool: ui-tab is "pinned" (shows additional confirmation on closing).
 +
* PROP_TAB_UI_SHOW: bool: ui-tab header is visible on the tabs-bar.
 
* PROP_INDENT_SIZE: int: size of indent for Indent/Unindent commands. N>0: indent in spaces, N<0: indent in tabs, N=0: indent from PROP_TAB_SIZE/PROP_TAB_SPACES.
 
* PROP_INDENT_SIZE: int: size of indent for Indent/Unindent commands. N>0: indent in spaces, N<0: indent in tabs, N=0: indent from PROP_TAB_SIZE/PROP_TAB_SPACES.
 
* PROP_INDENT_KEEP_ALIGN: bool: command Unindent keeps alignment of block edge, ie don't unindent if any line reached column 0.
 
* PROP_INDENT_KEEP_ALIGN: bool: command Unindent keeps alignment of block edge, ie don't unindent if any line reached column 0.
Line 2,374: Line 2,723:
 
* PROP_HILITE_CUR_LINE_IF_FOCUS: bool: highlight current line, only when editor focused.
 
* PROP_HILITE_CUR_LINE_IF_FOCUS: bool: highlight current line, only when editor focused.
 
* PROP_CODETREE: bool: enable standard code-tree filling.
 
* PROP_CODETREE: bool: enable standard code-tree filling.
 +
* PROP_CODETREE_SUBLEXER: bool: enable code-tree to show nodes from sublexer(s) of current lexer.
 
* PROP_EDITORS_LINKED: bool: enable sharing of the same text by primary/secondary editors in file tab.
 
* PROP_EDITORS_LINKED: bool: enable sharing of the same text by primary/secondary editors in file tab.
 
* PROP_ONE_LINE: bool: editor has single-line mode.
 
* PROP_ONE_LINE: bool: editor has single-line mode.
Line 2,389: Line 2,739:
 
* PROP_FONT_I: 2-tuple (str, int): italic font: name, size. Empty name: not used.
 
* PROP_FONT_I: 2-tuple (str, int): italic font: name, size. Empty name: not used.
 
* PROP_FONT_BI: 2-tuple (str, int): bold+italic font: name, size. Empty name: not used.
 
* PROP_FONT_BI: 2-tuple (str, int): bold+italic font: name, size. Empty name: not used.
* PROP_CODETREE_SUBLEXER: bool: enable code-tree to show nodes from sublexer(s) of current lexer.
 
  
 
* PROP_SPLIT: 2-tuple: information about primary/secondary editors splitting as tuple (split_kind, split_pos).
 
* PROP_SPLIT: 2-tuple: information about primary/secondary editors splitting as tuple (split_kind, split_pos).
Line 2,399: Line 2,748:
 
* PROP_SAVING_TRIM_FINAL_EMPTY_LINES: bool: on saving file, trim redundant empty lines at end of document.
 
* PROP_SAVING_TRIM_FINAL_EMPTY_LINES: bool: on saving file, trim redundant empty lines at end of document.
  
 +
* PROP_THEMED: bool: for editors out of UI-tabs, allows to automatically apply current theme on app theme changing.
 
* PROP_COMBO_ITEMS: only for "editor_combo" control, contents of drop-down list. On getting: list of str. On setting: value must be str with '\n'-separated items.
 
* PROP_COMBO_ITEMS: only for "editor_combo" control, contents of drop-down list. On getting: list of str. On setting: value must be str with '\n'-separated items.
  
Line 2,406: Line 2,756:
 
* PROP_NUMBERS_ONLY: bool: allow to input only numbers.
 
* PROP_NUMBERS_ONLY: bool: allow to input only numbers.
 
* PROP_NUMBERS_NEGATIVE: bool: additional to PROP_NUMBERS_ONLY, allow negative numbers<0.
 
* PROP_NUMBERS_NEGATIVE: bool: additional to PROP_NUMBERS_ONLY, allow negative numbers<0.
 +
 +
* PROP_COMMAND_LOG_LIMIT: int: maximal count of items in the list returned by PROP_COMMAND_LOG.
 +
 +
* PROP_DIM_UNFOCUSED: int: for unfocused editor, dim the background color by specified percents (ranges is -250...250, 0: disabled).
  
 
* PROP_V_MODE: int: mode of binary viewer. Setting it for viewer to one of VMODE_ values, changes viewer mode. Setting it for editor to one of VMODE_ values, switches editor to viewer in the given mode. Setting it for viewer to VMODE_NONE, switches viewer to editor.
 
* PROP_V_MODE: int: mode of binary viewer. Setting it for viewer to one of VMODE_ values, changes viewer mode. Setting it for editor to one of VMODE_ values, switches editor to viewer in the given mode. Setting it for viewer to VMODE_NONE, switches viewer to editor.
Line 2,414: Line 2,768:
 
* PROP_V_WIDTH_HEX: int: for binary viewer, width of text in mode VMODE_HEX.
 
* PROP_V_WIDTH_HEX: int: for binary viewer, width of text in mode VMODE_HEX.
 
* PROP_V_WIDTH_UHEX: int: for binary viewer, width of text in mode VMODE_UNICODE_HEX.
 
* PROP_V_WIDTH_UHEX: int: for binary viewer, width of text in mode VMODE_UNICODE_HEX.
 +
* PROP_V_ENC: str: for binary viewer, its encoding.
  
 
===props vs options===
 
===props vs options===
  
Many get_prop/set_prop ids correspond to CudaText options. List of correspoding pairs:
+
Many get_prop/set_prop ids correspond to CudaText options. List of corresponding pairs:
  
 
* PROP_CARET_VIRTUAL - "caret_after_end"
 
* PROP_CARET_VIRTUAL - "caret_after_end"
Line 2,458: Line 2,813:
 
** "hint": str
 
** "hint": str
 
** "auto_delx": enum, 0: don't auto-delete; 1: auto-delete; 2: auto-delete if global option is set
 
** "auto_delx": enum, 0: don't auto-delete; 1: auto-delete; 2: auto-delete if global option is set
** "auto_del" (deprecated): bool, True if "auto_delx" is 1
 
 
** "show_in_list": bool
 
** "show_in_list": bool
 
* BOOKMARK_GET_LIST: Returns list of line indexes, which have bookmarks. Param "nline" ignored.
 
* BOOKMARK_GET_LIST: Returns list of line indexes, which have bookmarks. Param "nline" ignored.
Line 2,473: Line 2,827:
 
* BOOKMARK_CLEAR: Removes bookmark from line, specified by "nline" param.
 
* BOOKMARK_CLEAR: Removes bookmark from line, specified by "nline" param.
 
* BOOKMARK_CLEAR_ALL: Removes all bookmarks ("nline" ignored).
 
* BOOKMARK_CLEAR_ALL: Removes all bookmarks ("nline" ignored).
* BOOKMARK_DELETE_BY_TAG: Removes all bookmarks, which have tag, given by "tag" param.
+
* BOOKMARK_DELETE_BY_TAG: Removes all bookmarks, which have the tag, given by "tag" param.
  
* BOOKMARK_SETUP: Configures bookmarks with kind, given by "nkind" param.
+
* BOOKMARK_SETUP: Configures bookmarks background color and icon for the given "kind". This setup is global, ie it is shared by all editors in UI-tabs. Once you applied some color and/or icon here, it will be shared by bookmarks in all editors in UI-tabs.
 +
** Param "nkind": Integer kind of bookmarks which will be configured.
 
** Param "ncolor": Color of bookmarked line.
 
** Param "ncolor": Color of bookmarked line.
 
*** Can be COLOR_NONE to not use background color.
 
*** Can be COLOR_NONE to not use background color.
Line 2,501: Line 2,856:
 
Controls decorations on gutter. It is used to show some visual marks, which look like bookmark icons, but independent of bookmarks. Possible values of "id":
 
Controls decorations on gutter. It is used to show some visual marks, which look like bookmark icons, but independent of bookmarks. Possible values of "id":
  
* DECOR_GET_ALL: Returns list of all decorations, as list of dict.
+
* DECOR_GET_ALL:
* DECOR_GET: Returns decoration for single line, as dict. Params used: "line".
+
** If param "line" <0: returns list of all decorations, as list of dict.
* DECOR_SET: Sets decoration for single line, overwriting existing item for that line. Returns bool: line index correct, item added. Params used:
+
** If param "line" >=0: return list of decorations for the given line index, as list of dict.
 +
 
 +
* DECOR_GET: Returns decoration for given line, as dict. Params used: "line".
 +
 
 +
* DECOR_SET: Sets decoration for given line. Returns bool: line index correct, item added. Params used:
 
** "line": int, line index.
 
** "line": int, line index.
 
** "tag": int, some value attached to item.
 
** "tag": int, some value attached to item.
** "text": str, text to show; decoration will be text.
+
** "text": str, text to show.
 +
*** If "text" is not empty, decoration will be text.
 +
*** If "text" is empty, decoration depends on "image" value, see below.
 
** "color": int, color of text decoration.
 
** "color": int, color of text decoration.
 
** "bold": bool, use bold font for text decoration.
 
** "bold": bool, use bold font for text decoration.
 
** "italic": bool, use italic font for text decoration.
 
** "italic": bool, use italic font for text decoration.
** "image": int, icon index from decoration imagelist; decoration will be icon, if text is empty.
+
** "image": int, icon index from decoration imagelist.
 +
*** If "text" is empty and "image" is >=0, decoration will be icon.
 +
*** If "text" is empty and "image" is -1, decoratiton will be cell background filled with "color".
 
** "auto_del": bool, auto-delete decoration, when its line is deleted.
 
** "auto_del": bool, auto-delete decoration, when its line is deleted.
  
 
* DECOR_DELETE_BY_LINE: Deletes single decoration for given line. Params used: "line".
 
* DECOR_DELETE_BY_LINE: Deletes single decoration for given line. Params used: "line".
* DECOR_DELETE_BY_TAG: Deletes all decorations for given tag. Param used: "tag".
+
* DECOR_DELETE_BY_TAG: Deletes all decorations with the given tag. Param used: "tag".
 
* DECOR_DELETE_ALL: Deletes all decorations.
 
* DECOR_DELETE_ALL: Deletes all decorations.
 
* DECOR_GET_IMAGELIST: Returns int handle of decoration imagelist (default size is 16x16).
 
* DECOR_GET_IMAGELIST: Returns int handle of decoration imagelist (default size is 16x16).
 +
 +
Notes:
 +
* Decor item's "text" can contain 2 items if you use chr(1): caption + chr(1) + tooltip.
 +
* Decoration list allows 2 items for the same line number. One of items (it can be added first or last) must be "background filler" (ie empty "text" and "image" is -1), and another one must be "not background filler".
  
 
===Editor.folding===
 
===Editor.folding===
  
  folding(id, index=-1, item_x=-1, item_y=-1, item_y2=-1, item_staple=False, item_hint="")
+
  folding(id, index=-1, item_x=-1, item_y=-1, item_y2=-1, item_staple=False, item_hint="", item_x2=0, item_tag=0)
  
 
Performs action on folding ranges. Possible values of "id":
 
Performs action on folding ranges. Possible values of "id":
  
* FOLDING_GET_LIST: Returns list of folding ranges. Params used: none except "id". Returns list of tuples (y, y2, x, staple, folded), or None.
+
* FOLDING_ENUM: Returns list of folding ranges. If param "item_y"<0, returns list of all ranges; otherwise makes filtering of ranges by params "item_y" and "item_y2" - ie, gets only ranges which contain line indexes from "item_y" to "item_y2" inclusive. Each list item is dict with fields:
** "y": int: line of range start.
+
** "x": int, column index of range beginning.
** "y2": int: line of range end. If y==y2, then range is simple and don't have gutter-mark and staple.
+
** "y": int, line index of range beginning.
** "x": int: x-offset of range start (char index in start line).
+
** "x2": int, column index of range ending.
** "staple": bool: range has block staple.
+
** "y2": int, line index of range ending.
** "folded": bool: range is currently folded.
+
** "staple": bool, indicates that range has 'block staple'.
 
+
** "folded": bool, indicates that range is folded.
* FOLDING_GET_LIST_FILTERED: Returns list of folding ranges, which contain given range: line indexes from param "item_y" to param "item_y2" (inclusive). If item_y<0, then no filtering is done. You can perform this filtering from the result of FOLDING_GET_LIST, but it's slower.
+
** "hint": string, hint of range (it is rendered when range is folded).
 +
** "tag": int 64-bit, tag value. For example, it is -1 for ranges created by CudaText command "fold selected lines".
  
* FOLDING_FOLD: Folds range with given index (index in list, from FOLDING_GET_LIST). Params used: "index".
+
* FOLDING_FOLD: Folds range with given index (index in unfiltered list returned by FOLDING_ENUM). Params used: "index".
 
* FOLDING_FOLD_ALL: Folds all ranges.
 
* FOLDING_FOLD_ALL: Folds all ranges.
 
* FOLDING_FOLD_LEVEL: Unfolds all ranges, then folds ranges starting with given nesting level. Params used: "index": nesting level, 0..9.
 
* FOLDING_FOLD_LEVEL: Unfolds all ranges, then folds ranges starting with given nesting level. Params used: "index": nesting level, 0..9.
  
* FOLDING_UNFOLD: Unfolds range with given index (index in list, from FOLDING_GET_LIST). Params used: "index".
+
* FOLDING_UNFOLD: Unfolds range with given index (index in unfiltered list returned by FOLDING_ENUM). Params used: "index".
 
* FOLDING_UNFOLD_ALL: Unfolds all ranges.
 
* FOLDING_UNFOLD_ALL: Unfolds all ranges.
* FOLDING_UNFOLD_LINE: Unfolds line with given index (index in lines list). Params used: "index".
+
* FOLDING_UNFOLD_LINE: Unfolds all ranges containing editor line with given index. Params used: "index".
  
 
* FOLDING_ADD: Adds folding range. Life time of this range is until lexer analisys runs (it clears ranges and adds ranges from lexer), which runs after any text change. Params used:
 
* FOLDING_ADD: Adds folding range. Life time of this range is until lexer analisys runs (it clears ranges and adds ranges from lexer), which runs after any text change. Params used:
** "item_x": char index (offset in line) of range start.
+
** "item_x": column index (offset in line) of range start.
 
** "item_y": line index of range start.
 
** "item_y": line index of range start.
** "item_y2": line index of range end.
+
** "item_x2" (optional): column index (offset in line) of range ending.
** "item_staple" (optional): bool, range has block staple.
+
** "item_y2": line index of range ending.
 +
** "item_staple" (optional): bool, indicates that range has 'block staple'.
 
** "item_hint" (optional): str, hint which is shown when range is folded.
 
** "item_hint" (optional): str, hint which is shown when range is folded.
 +
** "item_tag" (optional): int 64-bit, tag value. For example, it is -1 for ranges created by CudaText command "fold selected lines".
 
** "index": if it's valid range index (0-based), range inserts at this index, otherwise range appends.
 
** "index": if it's valid range index (0-based), range inserts at this index, otherwise range appends.
  
* FOLDING_DELETE: Deletes folding range with given index (index in list, from FOLDING_GET_LIST). Params used: "index".
+
* FOLDING_DELETE: Deletes folding range with given index (index in unfiltered list returned by FOLDING_ENUM). Params used: "index".
 
* FOLDING_DELETE_ALL: Deletes all folding ranges. Params used: none except "id".
 
* FOLDING_DELETE_ALL: Deletes all folding ranges. Params used: none except "id".
* FOLDING_FIND: Finds index of range (index in list, from FOLDING_GET_LIST). Returns None if not found. Params used: "item_y" is line index at which range begins.
+
* FOLDING_FIND: Finds index of range (index in unfiltered list returned by FOLDING_ENUM). Returns None if not found. Params used: "item_y" is line index at which range begins.
 
* FOLDING_CHECK_RANGE_INSIDE: For 2 ranges, which indexes given by "index" and "item_x", detects: 1st range is inside 2nd range. Returns bool. Returns False if indexes incorrect.
 
* FOLDING_CHECK_RANGE_INSIDE: For 2 ranges, which indexes given by "index" and "item_x", detects: 1st range is inside 2nd range. Returns bool. Returns False if indexes incorrect.
 
* FOLDING_CHECK_RANGES_SAME: For 2 ranges, which indexes given by "index" and "item_x", detects: ranges are "equal" (x, y, y2 in ranges may differ). Returns bool. Returns False if indexes incorrect.
 
* FOLDING_CHECK_RANGES_SAME: For 2 ranges, which indexes given by "index" and "item_x", detects: ranges are "equal" (x, y, y2 in ranges may differ). Returns bool. Returns False if indexes incorrect.
Line 2,571: Line 2,941:
 
  get_token(id, index1=0, index2=0)
 
  get_token(id, index1=0, index2=0)
  
Returns info about lexer "tokens". "Token" is minimal text fragment for lexer, e.g. one indentifier, one operator, one whole comment, one whole string. Each token has its color from lexer properties or color theme. Function returns None if no lexer is active in editor.
+
Returns info about lexer "tokens". "Token" is minimal text fragment for lexer, e.g. one identifier, one operator, one whole comment, one whole string. Each token has its color from lexer properties or color theme. Function returns None if no lexer is active in editor.
  
 
Possible values of "id":
 
Possible values of "id":
Line 2,594: Line 2,964:
 
===Editor.get_wrapinfo===
 
===Editor.get_wrapinfo===
  
  get_wrapinfo()
+
  get_wrapinfo(param1=-1, param2=-1)
  
Gets info about wrapped lines. It allows to calculate, at which positions long lines are wrapped (when wrap mode is on). It allows to see, which text parts are folded.
+
Gets info about wrapping of lines on screen. It allows to calculate, at which positions long lines are wrapped (when "word wrap mode" is on). It allows to see, which text parts are folded.
  
Returns list of dict. Dict items has keys:
+
Returns list of dict, for specified lines range. Dict items has keys:
  
 
* "line": int: Original line index, for this part.
 
* "line": int: Original line index, for this part.
Line 2,606: Line 2,976:
 
* "final": int: State of this part. 0: final part of the entire line; 1: partially folded part; 2: first or middle part of the entire line.
 
* "final": int: State of this part. 0: final part of the entire line; 1: partially folded part; 2: first or middle part of the entire line.
 
* "initial": bool: True if part is initial for the entire (wrapped) line, False if it is continuation (ie, wrapped) part.
 
* "initial": bool: True if part is initial for the entire (wrapped) line, False if it is continuation (ie, wrapped) part.
 +
 +
Parameter "param1" is the minimal line index (0-based) for which to return the information.
 +
Parameter "param2" is the maximal line index.
 +
Notes:
 +
 +
* If both "param1" and "param2" are default, returns entire document information.
 +
* If "param2" < "param1", returns empty list.
 +
* If "param1" < 0, its value is replaced to the minimal possible index.
 +
* If "param1" specifies incorrect line index, returns empty list.
 +
* If "param2" is < 0 or specifies incorrect line index, its value is replaced to the maximal possible index.
 +
* Length of resulting list equals the lines count for non-wrapped document. For wrapped document, you get 1 or more list items per each document line.
  
 
===Editor.markers===
 
===Editor.markers===
Line 2,634: Line 3,015:
 
* MARKERS_DELETE_BY_TAG: Deletes all markers with the given tag. Param "tag": tag value.
 
* MARKERS_DELETE_BY_TAG: Deletes all markers with the given tag. Param "tag": tag value.
 
* MARKERS_DELETE_BY_INDEX: Deletes marker by its index in the markers list. Param "tag": index (0-based).
 
* MARKERS_DELETE_BY_INDEX: Deletes marker by its index in the markers list. Param "tag": index (0-based).
 +
* MARKERS_DELETE_BY_POS: Deletes markers for specified text position.
 +
** If param "x">=0, deletes markers for position given by "x" and "y"
 +
** If param "x"<0, deletes all markers for line given by param "y"
 +
 +
* MARKERS_GET_DUPS: Gets "duplicates for the same x/y are allowed" flag, bool value.
 +
* MARKERS_SET_DUPS: Sets "duplicates for the same x/y are allowed" flag (it will be used on next item adding). Param "tag": 0 or 1.
  
 
===Editor.attr===
 
===Editor.attr===
Line 2,650: Line 3,037:
 
** "len": Length of fragment in chars.
 
** "len": Length of fragment in chars.
 
*** If len<0, and "show_on_map" is set, it will be multi-line micromap fragment with specified height=-len.
 
*** If len<0, and "show_on_map" is set, it will be multi-line micromap fragment with specified height=-len.
** "color_nnnn": Color values (RGB) for font, background, borders.
+
** "color_*": Color values (RGB) for font, background, borders.
** "font_nnnn": Font attributes: 0 - off, 1 - on.
+
** "font_*": Font attributes: 0 - off, 1 - on.
** "border_nnnn": Border types for edges, int value 0..6: none, solid, dash, solid 2pixel, dotted, rounded, wave.
+
** "border_*": Border types for edges, int value 0..6: none, solid, dash, solid 2pixel, dotted, rounded, wave.
 
** "show_on_map": How to show this fragment on micromap:
 
** "show_on_map": How to show this fragment on micromap:
 
*** int value>=0: Show on micromap column with given tag. Don't pass value=0, because micromap column with tag=0 is reserved.
 
*** int value>=0: Show on micromap column with given tag. Don't pass value=0, because micromap column with tag=0 is reserved.
Line 2,663: Line 3,050:
 
* MARKERS_ADD_MANY: Adds one or multiple fragments at once. Also returns number of fragments. Parameters:
 
* MARKERS_ADD_MANY: Adds one or multiple fragments at once. Also returns number of fragments. Parameters:
 
** "x", "y", "len": The same as for MARKERS_ADD, but can be also list/tuple of int. Lists/tuples must contain the equal number of elements (otherwise the minimal number of elements will be used).
 
** "x", "y", "len": The same as for MARKERS_ADD, but can be also list/tuple of int. Lists/tuples must contain the equal number of elements (otherwise the minimal number of elements will be used).
 +
** "color_*": Can be one value or list/tuple of values. Length of list/tuple is not limited.
 +
** "font_*": Can be one value or list/tuple of values. Length of list/tuple is not limited.
 
** other parameters: The same as for MARKERS_ADD.
 
** other parameters: The same as for MARKERS_ADD.
  
Line 2,672: Line 3,061:
 
* MARKERS_DELETE_BY_TAG: Deletes all fragments with the given tag. Param "tag": tag value.
 
* MARKERS_DELETE_BY_TAG: Deletes all fragments with the given tag. Param "tag": tag value.
 
* MARKERS_DELETE_BY_INDEX: Deletes fragment by its index in the list. Param "tag": index (0-based).
 
* MARKERS_DELETE_BY_INDEX: Deletes fragment by its index in the list. Param "tag": index (0-based).
 +
* MARKERS_DELETE_BY_POS: Deletes fragments for specified text position.
 +
** If param "x">=0, deletes fragments for position given by "x" and "y"
 +
** If param "x"<0, deletes all fragments for line given by param "y"
 +
 +
* MARKERS_GET_DUPS: Gets "duplicates for the same x/y are allowed" flag, bool value.
 +
* MARKERS_SET_DUPS: Sets "duplicates for the same x/y are allowed" flag (it will be used on next item adding). Param "tag": 0 or 1.
  
 
Notes:
 
Notes:
Line 2,700: Line 3,095:
 
* HOTSPOT_DELETE_ALL: Deletes all hotspots.
 
* HOTSPOT_DELETE_ALL: Deletes all hotspots.
 
* HOTSPOT_DELETE_LAST: Deletes last hotspot.
 
* HOTSPOT_DELETE_LAST: Deletes last hotspot.
* HOTSPOT_DELETE_BY_TAG: Deletes all hotspots with specified "tag".
+
* HOTSPOT_DELETE_BY_TAG: Deletes all hotspots with the given tag, "tag" param.
  
 
==Misc==
 
==Misc==
Line 2,706: Line 3,101:
 
===Editor.save===
 
===Editor.save===
  
  save(filename="")
+
  save(filename="", as_copy=False)
 +
 
 +
Saves editor's text to file.
 +
Returns bool: file was saved without errors.
 +
 
 +
Param "filename" (str): suggested filename to save to.
  
Saves editor's tab to disk.
+
Param "as_copy" (bool):
 +
* False: Editor uses new filename (if it's not empty). Untitled document becomes titled. If filename is empty and document is untitled, function shows "Save as" dialog first.
 +
* True: Creates the file but editor doesn't use new filename. Filename must be not empty, otherwise function will return False.
  
Shows save-as dialog for untitled tab.
+
Notes:
If param filename not empty, uses it (untitled tab becomes titled).
+
* Function can be used for editor created in dlg_proc() only if param "as_copy" is False, otherwise it will return None.
Returns bool: file was saved.
+
* For "as_copy" = False, code performs more detailed write-error checks.
  
 
===Editor.cmd===
 
===Editor.cmd===
Line 2,718: Line 3,120:
 
  cmd(code, text="")
 
  cmd(code, text="")
  
Command runner, it runs any command in editor by its int code.
+
Runs any command in editor by its integer code.
 +
See possible codes in module "cudatext_cmd".
  
See codes in module cudatext_cmd. Param text is needed for rare commands (e.g. by cCommand_TextInsert).
+
Param "text" is needed only for rare commands, mainly for "cCommand_TextInsert".
 +
 
 +
Notes:
 +
* When you perform some caret-positioning command (e.g. "cCommand_GotoTextEnd") in not yet painted editor-control, it doesn't run OK. Reason: editor must be properly inited which happens on first painting. If you need to place the caret on form showing ("dlg_proc" API), do it in form's "on_show" event. Maybe you need also to start a timer ("timer_proc" API) which will run the caret command.
  
 
===Editor.focus===
 
===Editor.focus===
Line 2,743: Line 3,149:
 
Converts something in editor. Possible values of "id":
 
Converts something in editor. Possible values of "id":
  
* CONVERT_CHAR_TO_COL: Convert char coordinates (x,y) to column coordinates (column,y), using current tab size.
+
* CONVERT_CHAR_TO_COL: Convert char coordinates (x,y) to column coordinates (column,y), using current tabulation size. Param "text" is ignored. Returns 2-tuple of int.
* CONVERT_COL_TO_CHAR: Convert column coordinates (x,y) to char coordinates (chars,y).
+
* CONVERT_COL_TO_CHAR: Convert column coordinates (x,y) to char coordinates (chars,y). Param "text" is ignored. Returns 2-tuple of int.
* CONVERT_LINE_TABS_TO_SPACES: Convert line (param "text") from tab-chars to spaces, using current tab size. Returns str. Returns original line, if no tab-chars in it.
+
* CONVERT_LINE_TABS_TO_SPACES: Convert line, given in param "text", from tabulation-chars to spaces, using current tabulation size. Returns string. Returns original line, if it does not contain tabulation-chars.
* CONVERT_SCREEN_TO_LOCAL: Convert pixel coordinates (x,y), from screen-related to control-related.
+
* CONVERT_SCREEN_TO_LOCAL: Convert pixel coordinates (x,y), from screen-related to control-related. Param "text" is ignored. Returns 2-tuple of int.
* CONVERT_LOCAL_TO_SCREEN: Convert pixel coordinates (x,y), from control-related to screen-related.
+
* CONVERT_LOCAL_TO_SCREEN: Convert pixel coordinates (x,y), from control-related to screen-related. Param "text" is ignored. Returns 2-tuple of int.
* CONVERT_PIXELS_TO_CARET: Convert pixel control-related coords (x,y) to caret position (column,line).
+
* CONVERT_PIXELS_TO_CARET: Convert pixel control-related coords (x,y) to text position (column,line). Param "text" is ignored. Returns 2-tuple of int.
* CONVERT_CARET_TO_PIXELS: Convert caret position (column,line) to pixel control-related coords (x,y).
+
* CONVERT_CARET_TO_PIXELS: Convert text position (x,y) to pixel control-related coords (x,y). Param "text" is ignored. Returns 2-tuple of int.
 +
* CONVERT_OFFSET_TO_CARET: Convert absolute offset (0-based) given by param "x", to text position (column,line). Params "y", "text" are ignored. Returns 2-tuple of int.
 +
* CONVERT_CARET_TO_OFFSET: Convert text position (x,y) to absolute text offset (0-based). Param "text" is ignored. Returns int.
  
Returns None if params incorrect, or cannot calc result.
+
Returns None if params are incorrect, or cannot calculate the result.
  
 
===Editor.complete===
 
===Editor.complete===
Line 2,769: Line 3,177:
 
** alt_order=True: pass items in each line in such order: id, prefix, desc. Listbox shows id at the left edge. Use it if plugin needs to show long "prefixes".
 
** alt_order=True: pass items in each line in such order: id, prefix, desc. Listbox shows id at the left edge. Use it if plugin needs to show long "prefixes".
  
Note: listbox disappears if you move caret or type text, unlike usual auto-completion listboxes (they can recalculate items for new caret pos).
+
Note:
 +
* Listbox disappears if you move caret or type text, unlike usual auto-completion listboxes (they can recalculate items for new caret pos).
 +
 
 +
If an item begins with "&lt;html&gt;", [[#HTML formatting]] is allowed in this item.
  
 
===Editor.complete_alt===
 
===Editor.complete_alt===
Line 2,793: Line 3,204:
 
* Param "snippet_id": Value from complete_alt() call.
 
* Param "snippet_id": Value from complete_alt() call.
 
* Param "snippet_text": Text of chosen snippet.
 
* Param "snippet_text": Text of chosen snippet.
 +
 +
If an item begins with "&lt;html&gt;", [[#HTML formatting]] is allowed in this item.
  
 
===Editor.gap===
 
===Editor.gap===
Line 2,814: Line 3,227:
 
* GAP_ADD: Adds gap to editor. Returns bool: params correct, gap added. Params:
 
* GAP_ADD: Adds gap to editor. Returns bool: params correct, gap added. Params:
 
** "num1": int: Line index; can be -1 for gap before the first line.
 
** "num1": int: Line index; can be -1 for gap before the first line.
** "num2": int: If 0, gap will be empty; otherwise it is bitmap handle (id_bitmap), which you got from GAP_MAKE_BITMAP.
+
** "num2": int: Can be:
 +
*** 0: gap is empty, filled with specified color;
 +
*** handle of bitmap (created via GAP_MAKE_BITMAP): place bitmap in the gap;
 +
*** handle of dialog (created via dlg_proc()): place dialog in the gap.
 
** "tag": int: Some value, to separate gaps from several plugins.
 
** "tag": int: Some value, to separate gaps from several plugins.
 
** "size": int: If >0, it is gap height in pixels. If 0, gap height is calculated from bitmap handle.
 
** "size": int: If >0, it is gap height in pixels. If 0, gap height is calculated from bitmap handle.
 
** "color": int: If not COLOR_NONE, then it's gap background color.
 
** "color": int: If not COLOR_NONE, then it's gap background color.
  
* GAP_DELETE: Deletes gaps, for line indexes from num1 to num2.
 
 
* GAP_DELETE_ALL: Deletes all gaps.
 
* GAP_DELETE_ALL: Deletes all gaps.
 +
* GAP_DELETE: Deletes gaps for the given line indexes range, from value of "num1" to value of "num2" (inclusive).
 +
* GAP_DELETE_BY_TAG: Deletes gaps which have the tag, given by param "tag".
  
 
Example plugin:
 
Example plugin:
Line 2,888: Line 3,305:
 
** "param1": Search string.
 
** "param1": Search string.
 
** "param2": Search options, see [[#Finder_options_as_string]].
 
** "param2": Search options, see [[#Finder_options_as_string]].
** "param3": Optional. Maximal line length (default is 0x7FFFFFFF). Lines longer than this value will be skipped during search.
+
** "param3": Optional. Maximal line length, 32-bit signed integer, default is 0x7FFFFFFF. Lines longer than this value will be skipped during search.
 
** Note: returns False for incorrect RegEx.
 
** Note: returns False for incorrect RegEx.
  
Line 2,896: Line 3,313:
 
** "param3": Max distance, in lines, to the pair bracket. Must be 32-bit signed int.
 
** "param3": Max distance, in lines, to the pair bracket. Must be 32-bit signed int.
  
* EDACTION_SHOW_POS: Make text position visible without caret moving. Returns True if params correct and scrolling occured, returns False if params correct and no scrolling occured, returns None if params not correct.
+
* EDACTION_SHOW_POS: Make text position visible without caret moving. Returns True if params correct and scrolling occurred, returns False if params correct and no scrolling occurred, returns None if params not correct.
 
** "param1": Text position as 2-tuple (column, line).
 
** "param1": Text position as 2-tuple (column, line).
 
** "param2": Indentation of text position from edges as 2-tuple (indent_horz, indent_vert). Values meaning is like for CudaText options "find_indent_horz", "find_indent_vert".
 
** "param2": Indentation of text position from edges as 2-tuple (indent_horz, indent_vert). Values meaning is like for CudaText options "find_indent_horz", "find_indent_vert".
Line 2,904: Line 3,321:
 
* EDACTION_LEXER_SCAN: Run lexer parsing (if lexer is set) from line index, given by "param1". Waits until parsing finishes.
 
* EDACTION_LEXER_SCAN: Run lexer parsing (if lexer is set) from line index, given by "param1". Waits until parsing finishes.
  
* EDACTION_EXPORT_HTML: Create HTML file from editor's text with syntax highlighting. Returns bool: file is created. Param "param1" must be dict with the following keys:
+
* EDACTION_APPLY_THEME: Apply current UI-theme colors to editor control. So you don't have to apply all COLOR_ID_nnn properties via Editor.set_prop().
** "file_name": str: Full path of file.
+
 
** "title": str: HTML page title.
+
* EDACTION_EXPORT_HTML: Create HTML file or buffer from editor's text with syntax highlighting. For file, returns bool: file is created. Param "param1" must be dict with the following optional keys:
** "font_name": str: Font name.
+
** "file_name": str: Full path of file, or special value "-" to return HTML text as function result. This key is mandatory, empty value is not allowed.
** "font_size": int: Font size, in HTML points.
+
** "title": str: Title of HTML page.
** "with_numbers": bool: Show gutter with line numbers.
+
** "font_name": str: Font name. Empty value is allowed, some standard monospaced font will be used.
 +
** "font_size": int: Font size, in HTML "px".
 +
** "with_numbers": bool: Make additional table cell with line numbers.
 
** "color_back": int: RGB color of page background.
 
** "color_back": int: RGB color of page background.
 
** "color_numbers": int: RGB color of line numbers.
 
** "color_numbers": int: RGB color of line numbers.
 +
** "line_begin": int: Index of beginning line (0-based). Default is 0.
 +
** "line_end": int: Index of ending line (0-based). Value after maximal line index is allowed, it is auto-limited. Default is "count of lines".
 +
** "col_begin": int: Beginning offset in beginning line (0-based). Default is 0.
 +
** "col_end": int: Ending offset in ending line (0-based). Default is 0 (works OK with default of "line_end").
  
 
===Editor.micromap===
 
===Editor.micromap===
Line 2,931: Line 3,354:
  
 
* MICROMAP_DELETE: Delete micromap column by its tag. Param "param1": tag. Returns bool: column was found and deleted.
 
* MICROMAP_DELETE: Delete micromap column by its tag. Param "param1": tag. Returns bool: column was found and deleted.
 +
 +
=HTML formatting=
 +
Several APIs support rendering of HTML-formatted strings. Small subset of HTML tags is supported:
 +
 +
<pre>
 +
<b>bold style</b>
 +
<i>italic style</i>
 +
<u>underline style</u>
 +
<s>strikeout style</s>
 +
<font color="#AABBCC">colored font</font>
 +
<font color="#ABC">colored font</font>
 +
</pre>
  
 
=TreeHelpers=
 
=TreeHelpers=
Line 2,940: Line 3,375:
  
 
Section(s) "treehelper" followed by any string (e.g. "treehelper1"):
 
Section(s) "treehelper" followed by any string (e.g. "treehelper1"):
* key "lexers" is comma-separated lexers list
+
* key "lexers" is comma-separated lexers list (can contain lite lexer with suffix)
 
* key "method" is name of getter method in __init__.py
 
* key "method" is name of getter method in __init__.py
 +
* key "fold" (value 0/1) is deprecated, not handled anymore
  
 
File __init__.py must contain getter method(s), referenced by install.inf. Getter has signature (with any name):
 
File __init__.py must contain getter method(s), referenced by install.inf. Getter has signature (with any name):
Line 2,967: Line 3,403:
 
Getter can also return value not of "list" type, in this case CudaText will not update the code-tree.
 
Getter can also return value not of "list" type, in this case CudaText will not update the code-tree.
  
See examples of TreeHelpers: for Markdown, for MediaWiki. They are add-ons in the CudaText AddonManager.
+
TreeHelpers can be written in Pascal too. This way they will work much faster.
 +
To write/debug a TreeHelper in Pascal, use the project "treehelpertester" in the CudaText GitHub repo.
 +
These TreeHelpers were rewritten from Python to Pascal and are built-in now:
 +
 
 +
* Markdown
 +
* MediaWiki
 +
* reST
  
 
=Linters=
 
=Linters=
Line 2,998: Line 3,440:
 
* "o": Confirm replaces
 
* "o": Confirm replaces
 
* "a": Wrap search at edge of text
 
* "a": Wrap search at edge of text
 +
* "A": When "wrap search at edge of text" is off, and search reaches the document edge, show confirmation to continue search from the opposite edge
 
* "T" followed by a digit: Allowed syntax elements. Digit can be:
 
* "T" followed by a digit: Allowed syntax elements. Digit can be:
 
** "0": any
 
** "0": any
Line 3,039: Line 3,482:
 
* end-of-line kind, number 0..3:
 
* end-of-line kind, number 0..3:
 
** 0: none
 
** 0: none
** 1: CRLF
+
** 1: CR LF
 
** 2: LF
 
** 2: LF
 
** 3: CR
 
** 3: CR
Line 3,047: Line 3,490:
 
** 2: added
 
** 2: added
 
** 3: saved
 
** 3: saved
* caret position(s). "x0,y0;" + "x1,y1;" + "x2,y2;" + ... ie 2*N numbers for N carets.
+
* caret position(s); carets are ";"-separated and x/y coords (32-bit) are ","-separated; for example "x0,y0;x1,y1;" for 2 carets;
 +
** plus chr(1) and marker position(s), 64-bit numbers ","-separated, where each marker is encoded as 7 numbers:
 +
*** position x,
 +
*** position y,
 +
*** selection-end x,
 +
*** selection-end y,
 +
*** tab-stop index,
 +
*** some value attached to marker,
 +
*** marker show mode, enum 0..2; 0: show in text only; 1: show in micromap only; 2: show in text and micromap.
 +
** plus chr(1) and global undo counter, 32-bit integer;
 +
** plus chr(1) and OS tick counter, 64-bit integer, in milliseconds (shows how much time is passed betweem items).
 
* soft mark flag, number 0/1 (boolean). Logic of soft/hard marks is described in wiki page [[ATSynEdit]].
 
* soft mark flag, number 0/1 (boolean). Logic of soft/hard marks is described in wiki page [[ATSynEdit]].
 
* hard mark flag, number 0/1.
 
* hard mark flag, number 0/1.
Line 3,055: Line 3,508:
  
 
=API of 3rd-party plugins=
 
=API of 3rd-party plugins=
==Options Editor==
+
==API of Options Editor==
 
Options Editor plugin (preinstalled in CudaText) has API which allows to call its dialog with custom options. Example shows dialog with 4 custom options, with custom title. Options which user changed in dialog will be saved to user.json or lexer-specific config.
 
Options Editor plugin (preinstalled in CudaText) has API which allows to call its dialog with custom options. Example shows dialog with 4 custom options, with custom title. Options which user changed in dialog will be saved to user.json or lexer-specific config.
  
Line 3,124: Line 3,577:
 
Options Editor stores values in JSON with trailing comma, so to read these options, plugin must use cudax_lib.get_opt() instead of json.load().
 
Options Editor stores values in JSON with trailing comma, so to read these options, plugin must use cudax_lib.get_opt() instead of json.load().
  
==Project Manager==
+
==API of Project Manager==
 +
'''Opening project from plugin'''
 +
 
 +
To open a project, you need to call the Project Manager's method Command.action_open_project, which can be done via action PROC_EXEC_PLUGIN. For example, this code loads the project "/home/user/tt.cuda-proj":
 +
 
 +
app_proc(PROC_EXEC_PLUGIN, 'cuda_project_man,action_open_project,/home/user/tt.cuda-proj')
 +
 
 +
'''Getting current project info'''
 +
 
 
Project Manager plugin (preinstalled in CudaText) gives API to read properties of currently opened project. It has global variable '''global_project_info''', which is dict with keys:
 
Project Manager plugin (preinstalled in CudaText) gives API to read properties of currently opened project. It has global variable '''global_project_info''', which is dict with keys:
  
Line 3,226: Line 3,687:
  
 
* Call ed.complete() or ed.complete_alt() to show completions list.
 
* Call ed.complete() or ed.complete_alt() to show completions list.
 +
 +
==Show me the template of complex plugin with side-panel and bottom-panel==
 +
 +
Here is the example plugin: https://github.com/CudaText-addons/cuda_r_plugin .
 +
It provides:
 +
 +
* Main toolbar, separate from the CudaText toolbar. Contains 2 dummy buttons.
 +
* Side-panel, which contains the small toolbar (with 2 dummy buttons) and listbox (filled with dummy data). Double-click on listbox - inserts clicked item to the current editor.
 +
* Bottom-panel, which contains the "console input" control and "console log" multi-line control. You can enter commands in the "input" and they will show in the log. Entered commands (last 10) are also stored to the file "[CudaText]/settings/cuda_r_plugin.ini" and re-read on start, you can recall them by clicking the down arrow in the "input" combobox.
 +
* Plugin supports few options. Saved in the file "[CudaText]/settings/cuda_r_plugin.ini".
 +
* Menu items in "Plugins / R Plugin", to open side-panel and bottom-panel.
 +
* Menu item in the "Options / Settings-plugins / R Plugin", to open the config file.
 +
* Predefined red buttons "R" in the CudaText sidebar and bottom bar. Visible even before the plugin is activated from Plugins menu.
  
 
=History=
 
=History=
Line 3,554: Line 4,028:
  
 
1.0.220 (app 1.38.2)
 
1.0.220 (app 1.38.2)
* add: on_state event aslo called with new constants APPSTATE_nnnn
+
* add: on_state supports new constants APPSTATE_nnnn
  
 
1.0.221 (app 1.38.3)
 
1.0.221 (app 1.38.3)
Line 3,779: Line 4,253:
  
 
1.0.267 (app 1.70.3)
 
1.0.267 (app 1.70.3)
* add: on_state: add APPSTATE_CONFIG_REREAD
+
* add: on_state supports also APPSTATE_CONFIG_REREAD
* add: on_state: add APPSTATE_SESSION_LOAD
+
* add: on_state supports also APPSTATE_SESSION_LOAD
  
 
1.0.268 (app 1.71.5)
 
1.0.268 (app 1.71.5)
Line 4,148: Line 4,622:
 
1.0.352 (app 1.115.6)
 
1.0.352 (app 1.115.6)
 
* add: app_path: APP_DIR_SETTINGS_DEF
 
* add: app_path: APP_DIR_SETTINGS_DEF
* add: file_open: added possible option "/nontext-view-uhex"
+
* add: file_open: added option "/nontext-view-uhex"
  
 
1.0.353 (app 1.115.7)
 
1.0.353 (app 1.115.7)
Line 4,258: Line 4,732:
 
* change: Editor.dim returns [] if no items
 
* change: Editor.dim returns [] if no items
 
* change: Editor.gap returns [] if no items
 
* change: Editor.gap returns [] if no items
 +
 +
1.0.377 (app 1.130.5)
 +
* change: changed values of cCommand_MoveSelection* commands
 +
 +
1.0.379 (app 1.131.0)
 +
* add: file_open: added option "/noloadundo"
 +
* add: app_proc: PROC_GET_OUTPUT_FORM
 +
* add: app_proc: PROC_GET_VALIDATE_FORM
 +
 +
1.0.381 (app 1.131.1)
 +
* change: app_log: param "tag" is now ignored
 +
* add: on_state supports also APPSTATE_SESSION_LOAD_BEGIN, APPSTATE_SESSION_LOAD_FAIL
 +
 +
1.0.383 (app 1.132.0)
 +
* add: msg_status_alt: added params "pos", "x", "y"
 +
* add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new key "op_hi_d"
 +
 +
1.0.385 (app 1.132.0)
 +
* add: app_proc: PROC_SET_PROJECT
 +
* add: event on_state supports also APPSTATE_PROJECT
 +
* add: event on_console_nav: also it's called when Console input is changed
 +
 +
1.0.388 (app 1.132.9)
 +
* add: dlg_proc: control "splitter" supports property "color"
 +
* add: dlg_proc: control "listbox_ex" supports event "on_click_header"
 +
* add: listbox_proc: LISTBOX_GET_HEADER, LISTBOX_SET_HEADER
 +
* add: listbox_proc: LISTBOX_GET_HEADER_IMAGELIST, LISTBOX_SET_HEADER_IMAGELIST
 +
* add: listbox_proc: LISTBOX_GET_HEADER_IMAGEINDEXES, LISTBOX_SET_HEADER_IMAGEINDEXES
 +
* fix: controls "editor_edit" and "editor_combo" didn't support PROP_RO
 +
 +
1.0.390 (app 1.133.0)
 +
* change: listbox_proc: LISTBOX_SET_COLUMNS calcs "percent values" (value<0) after the counting "pixel values" (value>0)
 +
* add: dlg_proc: control "listbox_ex" border is themed now
 +
* add: app_proc: PROC_GET_OS_SUFFIX
 +
 +
1.0.391 (app 1.133.1)
 +
* add: tree_proc: TREE_ITEM_SELECT with id_item=0 removes the selection
 +
 +
1.0.392 (app 1.133.2)
 +
* add: event on_state supports also APPSTATE_CODETREE_*
 +
* add: app_proc: PROC_SIDEPANEL_ENUM_ALL/PROC_BOTTOMPANEL_ENUM_ALL gets also button handles
 +
 +
1.0.393 (app 1.133.6)
 +
* add: Editor.gap: add GAP_DELETE_BY_TAG
 +
* add: Editor.gap: GAP_ADD can also add the dialog, using its handle
 +
 +
1.0.394 (app 1.134.1.2)
 +
* add: app_proc: PROC_GET_MAIN_TOOLBAR
 +
* add: app_proc: PROC_GET_MAIN_STATUSBAR
 +
* delete: redundant "API" constant which had the API version (seems no one used it)
 +
* deprecate: toolbar_proc() special string handle "top"
 +
* deprecate: statusbar_proc() special string handle "main"
 +
 +
1.0.397 (app 1.135.2)
 +
* add: Editor.get_wrapinfo: add optional params to specify lines range
 +
* add: Editor.convert: CONVERT_OFFSET_TO_CARET
 +
* add: Editor.convert: CONVERT_CARET_TO_OFFSET
 +
* add: Editor.get_prop/set_prop: PROP_TAB_UI_SHOW
 +
* add: editors in ui-tabs are now placed on a hidden form to support dlg_proc() API, you can get this form's handle via PROP_HANDLE_PARENT
 +
 +
1.0.398 (app 1.136.1)
 +
* add: tree_proc: TREE_FIND_FOR_TEXT_POS
 +
 +
1.0.399 (app 1.136.2)
 +
* add: statusbar_proc: STATUSBAR_GET_PADDING
 +
* add: statusbar_proc: STATUSBAR_SET_PADDING
 +
 +
1.0.401 (app 1.137.1)
 +
* add: statusbar_proc: STATUSBAR_GET_SEPARATOR
 +
* add: statusbar_proc: STATUSBAR_SET_SEPARATOR
 +
* add: statusbar_proc: STATUSBAR_GET_COLOR_BORDER_BOTTOM
 +
* add: statusbar_proc: STATUSBAR_SET_COLOR_BORDER_BOTTOM
 +
* add: statusbar_proc: STATUSBAR_GET_OVERFLOW_LEFT
 +
* add: statusbar_proc: STATUSBAR_SET_OVERFLOW_LEFT
 +
* add: statusbar_proc: STATUSBAR_GET_CELL_RECT
 +
 +
1.0.402 (app 1.137.3)
 +
* add: dlg_proc: forms have the "on_form_state" event
 +
* add: dlg_proc: forms have additional property "form_state"
 +
* deleted deprecated: MENU_LIST, MENU_LIST_ALT, MENU_NO_FUZZY, MENU_NO_FULLFILTER, MENU_CENTERED, MENU_EDITORFONT
 +
 +
1.0.403 (app 1.137.3)
 +
* add: code-tree is compatible with dlg_proc() API, you can get its form handle via app_proc(PROC_SIDEPANEL_GET_CONTROL, 'Code tree')
 +
* add: tree_proc: TREE_SET_IMAGELIST
 +
* add: file_open: option "/donear"
 +
 +
1.0.404 (app 1.137.7)
 +
* add: forms now have "on_key_press" event
 +
 +
1.0.405 (app 1.139.0)
 +
* add: Editor.action: EDACTION_APPLY_THEME
 +
 +
1.0.406 (app 1.139.1)
 +
* add: on_state_ed is fired with EDSTATE_ZOOM
 +
* add: on_state_ed is fired with EDSTATE_BOOKMARK
 +
 +
1.0.407 (app 1.139.2)
 +
* add: Editor.get_prop/set_prop: PROP_THEMED
 +
* add: app_proc: PROC_GET_KEYSTATE returns flags for 4th/5th mouse buttons
 +
 +
1.0.408 (app 1.140.6)
 +
* add: Editor.get_prop: PROP_COMMAND_LOG
 +
* add: Editor.get_prop/set_prop: PROP_COMMAND_LOG_LIMIT
 +
 +
1.0.409 (app 1.142.0)
 +
* change: auto-completion is allowed in comments, if lexer name has 'HTML'
 +
* add: event "on_cli"
 +
 +
1.0.410 (app 1.142.1)
 +
* deprecate: option CARET_OPTION_UNFOLD (it's always On now)
 +
* add: event on_state supports also APPSTATE_API_SUBCOMMANDS, APPSTATE_API_MENU_xxxx
 +
 +
1.0.411 (app 1.145.1)
 +
* add: callbacks (e.g. in toolbar buttons) can have form "exec=command_line_here"
 +
* add: app_proc: PROC_PARSE_COMMAND_LINE
 +
 +
1.0.412 (app 1.146.1)
 +
* change: command "macros: start recording" is renamed to "start/stop recording", commands "stop recording" and "cancel recording" are deprecated
 +
 +
1.0.413 (app 1.148.1)
 +
* add: dlg_proc: new control "scrollbox"
 +
 +
1.0.414 (app 1.149.4)
 +
* add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new keys "op_regex_subst", "op_regex_subst_d"
 +
 +
1.0.415 (app 1.153.1)
 +
* add: app_proc: PROC_SAVE_SESSION supports additional parameters
 +
 +
1.0.416 (app 1.157.2)
 +
* add: app_proc: PROC_GET_CLIP_EX
 +
* add: app_proc: additional chars in result of PROC_CLIP_ENUM
 +
* deleted deprecated: "resize" property of forms in dlg_proc()
 +
 +
1.0.417 (app 1.157.6)
 +
* add: app_proc: PROC_GET_COMPILER_INFO
 +
 +
1.0.418 (app 1.158.3)
 +
* add: app_proc: session-related actions support specifying of JSON path for sessions
 +
 +
1.0.419 (app 1.159.0)
 +
* add: event on_delete_file
 +
 +
1.0.420 (app 1.159.3)
 +
* add: Editor.decor: allow to fill cell background, if "text" is empty and "image" is -1
 +
* add: Editor.decor: allow 2 decor items for the same line index
 +
 +
1.0.421 (app 1.163.2)
 +
* add: tree_proc: TREE_GET_MULSELECT, TREE_SET_MULSELECT
 +
* add: tree_proc: TREE_GET_SELECTIONS
 +
 +
1.0.422 (app 1.166.0)
 +
* add: ed.get_prop/set_prop: PROP_V_ENC
 +
* add: app_proc: PROC_ENUM_ENCODINGS
 +
 +
1.0.423 (app 1.166.1)
 +
* add: Editor.cmd: cmd(cmd_DialogCommands, text) now sets text as initial filter of Command Palette
 +
* add: Editor.set_text_line: support special value -2
 +
 +
1.0.424 (app 1.166.4)
 +
* add: Editor.markers: MARKERS_DELETE_BY_POS
 +
* add: Editor.attr: MARKERS_DELETE_BY_POS
 +
 +
1.0.425 (app 1.166.6)
 +
* add: Editor.get_prop/set_prop: PROP_GUTTER_EMPTY
 +
* add: Editor.get_prop/set_prop: PROP_GUTTER_EMPTY_WIDTH
 +
* add: Editor.attr: MARKERS_ADD_MANY allows lists for params "color_*" and "font_*"
 +
* add: Editor.markers/attr: MARKERS_GET_DUPS
 +
* add: Editor.markers/attr: MARKERS_SET_DUPS
 +
* add: event "on_sidebar_popup"
 +
 +
1.0.426 (app 1.167.2)
 +
* add: Editor.get_prop/set_prop: PROP_WHEEL_ZOOMS
 +
 +
1.0.427 (app 1.169.1)
 +
* add: Editor.decor: item "text" can contain tooltip after chr(1)
 +
 +
1.0.428 (app 1.169.5)
 +
* add: event "on_caret_slow"
 +
* add: app_proc: PROC_GET_AUTOCOMPLETION_INVOKE
 +
* add: Editor.get_prop/set_prop: PROP_TAB_COLOR_FONT
 +
 +
1.0.429 (app 1.170.1)
 +
* add: dlg_proc: form property "taskbar"
 +
* add: Editor.get_prop/set_prop: PROP_DIM_UNFOCUSED
 +
 +
1.0.430 (app 1.171.0)
 +
* delete deprecated: statusbar_proc special handle 'main'
 +
* delete depreacted: toolbar_proc special handle 'top'
 +
* add: statusbar_proc: STATUSBAR_MOVE_CELL
 +
* add: Editor.get_prop/set_prop: PROP_CARET_MULTI
 +
* add: Editor.set_prop: PROP_TAB_TITLE setting to empty str, resets the caption
 +
* fix: Editor.action: EDACTION_UPDATE did not work sometimes (cmd_RepaintEditor worked better)
 +
 +
1.0.431 (app 1.171.5)
 +
* add: Editor.complete, Editor.complete_alt: if cell begins with "&lt;html&gt;", HTML tags are allowed: b, i, u, s
 +
* add: Editor.get_prop/set_prop: PROP_MINIMAP_CHAR_WIDTH
 +
* add: Editor.get_prop/set_prop: PROP_MINIMAP_SCALE
 +
* add: Editor.get_prop/set_prop: PROP_MINIMAP_AT_LEFT
 +
 +
1.0.432 (app 1.172.1)
 +
* delete deprecated: PROC_SIDEPANEL_ENUM
 +
* delete deprecated: PROC_BOTTOMPANEL_ENUM
 +
 +
1.0.433 (app 1.173.0)
 +
* add: Editor.complete, Editor.complete_alt: support HTML tag "font color=..."
 +
 +
1.0.435 (app 1.176.5)
 +
* add: event on_start2
 +
* add: Editor() supports handle==1 to get editor from right-clicked tab
 +
 +
1.0.436 (app 1.178.0)
 +
* add: event on_tab_menu
 +
 +
1.0.437 (app 1.180.5)
 +
* add: event on_click_right
 +
 +
1.0.438 (app 1.182.0)
 +
* add: Editor.action: EDACTION_EXPORT_HTML: added optional params "line_begin", "line_end", "col_begin", "col_end"
 +
* add: Editor.action: EDACTION_EXPORT_HTML: allow to export to memory by specifying "file_name" as "-"
 +
* add: app_proc: PROC_SET_CLIP_HTML
 +
* add: Editor.get_prop/set_prop: PROP_TAB_TITLE_REASON
 +
 +
1.0.439 (app 1.184.0)
 +
* add: Editor.get_prop/set_prop: PROP_RULER_TEXT (it allows HTML formatting too)
 +
 +
1.0.441 (app 1.185.5)
 +
* add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new keys "op_prescase", "op_prescase_d"
 +
* add: menu_proc: MENU_SET_AUTO_HOTKEY, MENU_SET_AUTO_HOTKEY_DEEP
 +
 +
1.0.442 (app 1.186.1)
 +
* add: event on_caret_line
 +
* add: Editor.get_line_len()
 +
 +
1.0.443 (app 1.186.5)
 +
* add: app_proc: PROC_GET_WINDOW_STATE
 +
* add: event on_state supports also APPSTATE_WINDOW
 +
* fix: event on_click_gutter was not called for gutter bands "line numbers" and "folding"
 +
* add: event on_click_gutter was not able to block default processing
 +
 +
1.0.444 (app 1.189.0)
 +
* add: event on_console_complete
 +
* add: Editor(h).cmd(cmd_FileClose) now closes the handle's ui-tab (before it closed the active tab)
 +
 +
1.0.445 (app 1.190.1)
 +
* add: Editor.get_prop/set_prop: PROP_TAB_SMART
 +
 +
1.0.446 (app 1.195.1)
 +
* delete event on_caret_line
 +
 +
1.0.447 (app 1.196.3)
 +
* add: PROC_GET_FINDER_PROP new option "op_wrap_c", and new option "A" in the string form of search options
 +
 +
1.0.448 (app 1.197.0)
 +
* add: Editor.folding: FOLDING_ENUM
 +
* add: Editor.folding: add optional params "item_x2", "item_tag"
 +
* deprecate FOLDING_GET_LIST and FOLDING_GET_LIST_FILTERED (use FOLDING_ENUM instead of them)
 +
* add: Editor.get_prop/set_prop: PROP_BORDER_COLOR
 +
* add: Editor.get_prop/set_prop: PROP_BORDER_COLOR_WIDTH
 +
* add: Editor.get_prop/set_prop: PROP_CORNER_TEXT
 +
* add: Editor.get_prop/set_prop: PROP_CORNER_COLOR_FONT
 +
* add: Editor.get_prop/set_prop: PROP_CORNER_COLOR_BACK
 +
* add: Editor.get_prop/set_prop: PROP_CORNER_COLOR_BORDER
 +
* add: Editor.get_prop/set_prop: PROP_CORNER2_TEXT
 +
* add: Editor.get_prop/set_prop: PROP_CORNER2_COLOR_FONT
 +
* add: Editor.get_prop/set_prop: PROP_CORNER2_COLOR_BACK
 +
* add: Editor.get_prop/set_prop: PROP_CORNER2_COLOR_BORDER
 +
 +
1.0.449 (app 1.206.0)
 +
* add: event on_init_plugins_menu
 +
* change: initing of "Plugins" menu is now performed _after_ on_start2, before on_init_plugins_menu
 +
* change: menu_proc: don't return redundant dict key 'command'
 +
* change: menu_proc: don't return dict keys if they are defaults: 'vis', 'en', 'checked', 'radio', 'hotkey', 'hint', 'tag'
 +
* add: menu items in "Plugins" menu support introspection by menu_proc() better: "hint" property is filled for them now
 +
 +
1.0.450 (app 1.206.4)
 +
* delete deprecated actions FOLDING_GET_LIST and FOLDING_GET_LIST_FILTERED (use FOLDING_ENUM instead of them)
 +
* add: file_open: option "/noupdateaddons"
 +
 +
1.0.451 (app 1.206.6)
 +
* delete deprecated key "auto_del" in results of BOOKMARK_GET_ALL
 +
* change: Editor.get_prop/set_prop: PROP_ACTIVATION_TIME is now available for editors created via dlg_proc; it is different now for primary/secondary editor in the same ui-tab
 +
 +
1.0.452 (app 1.209.0)
 +
* add: Editor.decor: DECOR_GET_ALL now can return all items for given line, if "line">=0
 +
* add: Editor.save: add optional parameter "as_copy"
 +
* add: PROP_CORNER_TEXT supports multi-line text
 +
* add: Editor.get_prop/set_prop: PROP_CORNER_FONT_NAME
 +
* add: Editor.get_prop/set_prop: PROP_CORNER_FONT_SIZE
 +
* add: Editor.get_prop/set_prop: PROP_CORNER2_FONT_NAME
 +
* add: Editor.get_prop/set_prop: PROP_CORNER2_FONT_SIZE
 +
 +
1.0.453 (app 1.210.5)
 +
* add: image_proc: support WEBP format
 +
 +
1.0.454 (app 1.211.3)
 +
* add: Editor.get_char_count
 +
* add: Editor.action: EDACTION_FIND_ALL supports multi-selections when searching with 's' option (before it handled only first selection)
 +
* delete deprecated CARET_OPTION_UNFOLD
  
 
[[Category:CudaText]]
 
[[Category:CudaText]]
[[Category:Python]]
 

Latest revision as of 15:20, 22 March 2024

Intro

This is API for CudaText in Python.

  • Module: cudatext. Constants, functions, class Editor, objects of class Editor.
  • Module: cudatext_cmd. Constants for Editor.cmd().
  • Module: cudatext_keys. Constants for on_key.
  • Module: cudax_lib. High-level functions for plugins, e.g. read/write configs.
  • Module: cudax_nodejs. Helper functions for plugins which use Node.js.

Event plugins

To make plugin react to some program event, add method to class Command. For example, method "Command.on_save" will be called by program event "on_save" - if plugin is subscribed to that event. Event methods have param "ed_self": this is Editor object in which event occurred. This object is the same as object "ed" in most cases ("ed" always refers to focused editor), but in some cases event occurs in inactive editor, e.g. command "Save all tabs" calls event "on_save" for passive tabs.

Plugin can subscribe to events in several ways:

  • Static subscribing in "install.inf". This is used, when plugin needs to always react to some events, with any combination of its options.
  • Static subscribing via config file "settings/plugins.ini". This is used when plugin doesn't need some events initially, but after changing some options, it needs more events. File "plugins.ini" section [events] can contain lines like "cuda_modulename=event1,event2,...". File "plugins.ini" is read on plugins initialization, so after writing there, CudaText should be restarted.
  • Run-time subscribing/unsubscribing via API. See description of action PROC_SET_EVENTS in app_proc().

Event handlers (Command.on_nnnnn methods) return-value is ignored is many cases, but sometimes return value True or False has special meaning. Usually the False return value blocks propagation of event to other plugins, so don't return False if not necessary.

Events - General

  • on_open(self, ed_self): Called after file is opened from disk.
  • on_open_pre(self, ed_self, filename): Called before file opening. Method can return False to disable opening, other value is ignored.
  • on_open_none(self, ed_self): Called after file is opened, and none lexer was detected/set for it.
  • on_close_pre(self, ed_self): Called before closing tab, before checking if tab modified or not. Method can return False to disable closing.
  • on_close(self, ed_self): Called before closing tab, after modified file was saved, and editor is still active.
  • on_save(self, ed_self): Called after saving file.
  • on_save_pre(self, ed_self): Called before saving file. Method can return False to disable saving, other value is ignored.
  • on_save_naming(self, ed_self): Called before saving untitled tab, to get suggested filename without path and extension. Method must return valid filename string or None.
  • on_delete_file(self, ed_self, filename): Called on running command "File / Close and delete file". ed_self is None.
  • on_start(self, ed_self): Called once on program start. Called early, before applying config files. ed_self is None.
  • on_start2(self, ed_self): Called once on program start. Called later than on_start, after configs are applied, just before the main form shows. ed_self is None.
  • on_init_plugins_menu(self, ed_self): Called after filling the "Plugins" menu. On startup, it is called after on_start/on_start2, and after app goes into 'idle' state for the first time. App inits the "Plugins" menu in the 'idle' state. Event is also called when app has to update the "Plugins" menu again, e.g. after installing plugin from zip-file. ed_self is None.
  • on_exit(self, ed_self): Called on exiting application. This event is lazy, ie it's called only for already loaded plugins. ed_self is None.
  • on_app_activate(self, ed_self): Called when application window gets focus. ed_self is None.
  • on_app_deactivate(self, ed_self): Called when application window looses focus. ed_self is None.
  • on_cli(self, param1, param2...): Called when application gets command-line parameter "-p=cuda_pluginname#param1#param2...". Count of params is plugin-defined, e.g. Differ plugin needs 2 params. This event is not sent to all plugins, but only to the single specified plugin.

Events - Tabs

  • on_tab_change(self, ed_self): Called after active UI-tab is changed.
  • on_tab_menu(self, ed_self): Called just before showing popup menu for UI-tab title. Method can return False to disable the standard popup menu, other return value is ignored.
  • on_tab_move(self, ed_self): Called after closing a UI-tab (another UI-tab is already activated), or moving a UI-tab (by drag-n-drop, or UI command).

Events - Editor

  • on_change(self, ed_self): Called after editor text is changed.
  • on_change_slow(self, ed_self): Called after editor text is changed, and small pause is passed (CudaText option "py_change_slow"), and application "idle" event happens (no keyboard/mouse input for 1-2sec).
  • on_caret(self, ed_self): Called after caret position/selection is changed.
  • on_caret_slow(self, ed_self): Called after caret position/selection is changed, and small pause is passed. Pause is CudaText option "py_caret_slow".
  • on_insert(self, ed_self, text): Called before inserting a text. Method can return False to disable insertion, other return value is ignored.
  • on_key(self, ed_self, key, state): Called when user presses a key in editor. Param "key" is int key code; values are listed in the module cudatext_keys. Param "state" is string of chars: "a" if Alt pressed, "c" if Ctrl pressed, "s" if Shift pressed, "m" if Meta (Windows-key) pressed. Method can return False to disable key processing, other return value is ignored.
  • on_key_up(self, ed_self, key, state): Called when user depresses a key in editor. Params meaning is the same as in "on_key". Currently called only for Ctrl/Shift/Alt keys (to not slow down).
  • on_focus(self, ed_self): Called after any editor gets focus.
  • on_lexer(self, ed_self): Called after editor's lexer is changed.
  • on_lexer_parsed(self, ed_self): Called after lexer has finished its parsing. To not slow down usual work, event is called only if parsing time was >=600 msec.
  • on_paste(self, ed_self, keep_caret, select_then): Called before some Clipboard Paste command runs. Parameters are options of various paste commands. Method can return False to disable default operation.
  • on_scroll(self, ed_self): Called on scrolling in editor.
  • on_mouse_stop(self, ed_self, x, y): Called when mouse cursor stops (for a short delay) over editor. Params "x", "y" are mouse editor-related coords.
  • on_hotspot(self, ed_self, entered, hotspot_index): Called when mouse cursor moves in/out of hotspot. See ed.hotspots() API.
  • on_snippet(self, ed_self, snippet_id, snippet_text): Called when user chooses snippet to insert, in ed.complete_alt() call.

Events - Editor clicks

  • on_click(self, ed_self, state): Called after mouse click on text area. Param "state": same meaning as in on_key.
  • on_click_dbl(self, ed_self, state): Called after mouse double-click on text area. Param "state": same meaning as in on_key. Method can return False to disable default processing.
  • on_click_right(self, ed_self, state): Called after mouse right-click. Param "state": same meaning as in on_key. Method can return False to disable default processing.
  • on_click_gutter(self, ed_self, state, nline, nband): Called on mouse click on gutter area. Param "state": same as in on_key. Param "nline": index of editor line. Param "nband": index of gutter band. Method can return False to disable default processing.
  • on_click_gap(self, ed_self, state, nline, ntag, size_x, size_y, pos_x, pos_y): Called after mouse click on inter-line gap: see Editor.gap(). Param "state": same meaning as in on_key. Other params: properties of clicked gap.
  • on_click_link(self, ed_self, state, link): Called after link/URL in the editor is activated by click or double-click (event is not called on URL opening from Command Palette or from editor context menu). Param "state": same meaning as in on_key. Param "link": link string. Method can return False to disable default program action.

Events - State changes

  • on_state(self, ed_self, state): Called after some app state is changed. Param "state" is one of APPSTATE_nnnn constants. ed_self is None.
  • on_state_ed(self, ed_self, state): Called after some editor state is changed. Param "state" is one of EDSTATE_nnnn constants.

Constants in "on_state":

  • APPSTATE_LANG: Changed UI translation.
  • APPSTATE_THEME_UI: Changed UI-theme.
  • APPSTATE_THEME_SYNTAX: Changed syntax-theme.
  • APPSTATE_GROUPS: Changed UI-tab grouping mode (see top menu item "=").
  • APPSTATE_CONFIG_REREAD: App config file is re-read and applied.
  • APPSTATE_SESSION_LOAD_BEGIN: Session loading begins.
  • APPSTATE_SESSION_LOAD: Session loading completes (after APPSTATE_SESSION_LOAD_BEGIN).
  • APPSTATE_SESSION_LOAD_FAIL: Session loading fails (after APPSTATE_SESSION_LOAD_BEGIN).
  • APPSTATE_PROJECT: Current project in the Project Manager is changed.
  • APPSTATE_API_SUBCOMMANDS: API call app_proc(PROC_SET_SUBCOMMANDS, ...).
  • APPSTATE_API_MENU_ADD: API menu_proc() added some menu item.
  • APPSTATE_API_MENU_REMOVE: API menu_proc() removed some menu item.
  • APPSTATE_API_MENU_CHANGE: API menu_proc() changed some menu item.
  • APPSTATE_CODETREE_CLEAR: Code-Tree: content is cleared.
  • APPSTATE_CODETREE_BEFORE_FILL: Code-Tree: before filling the content.
  • APPSTATE_CODETREE_AFTER_FILL: Code-Tree: after filling the content.
  • APPSTATE_CODETREE_SET_SELECTION: Code-Tree double-click changed scroll pos, or app sync'ed Code-Tree with caret pos.
  • APPSTATE_WINDOW: Changed state of the main window: minimized/normal/maximized/fullscreen. Read current state via app_proc(PROC_GET_WINDOW_STATE, "").

Constants in "on_state_ed":

  • EDSTATE_WRAP: Word-wrap state is changed.
  • EDSTATE_TAB_TITLE: UI-tab title is changed.
  • EDSTATE_MODIFIED: Document modified state is changed.
  • EDSTATE_PINNED: UI-tab 'pinned' state is changed.
  • EDSTATE_READONLY: Read-only state is changed.
  • EDSTATE_ZOOM: Scale of document is changed, using Ctrl+MouseWheel or by a command.
  • EDSTATE_BOOKMARK: Bookmark is added or removed.

Events - Smart commands

  • on_complete(self, ed_self): Called by "auto-completion menu" command (default hotkey: Ctrl+Space). Method should read editor text, find all needed data, and call Editor.complete() API to show the actual auto-completion listbox to user. True return value means that plugin handled the event, don't call other plugins.
  • on_func_hint(self, ed_self): Called by "show function-hint" command (default hotkey: Ctrl+Shift+Space). Method should return function-hint string (comma-separated parameters, brackets are optional). Non-empty string result means that plugin handled the event, don't call other plugins. Empty string or None mean that no hint was found.
  • on_goto_def(self, ed_self): Called by "go to definition" command (e.g. by mouse shortcut or by menu item in the editor context menu). Method must return True if it handled the command, otherwise None.
  • on_goto_enter(self, ed_self, text): Called after user entered text in the Go To dialog. Method can return False to disable default processing.

Events - Panels

  • on_message(self, ed_self, id, text): Called on showing a text in the statusbar. Param "id" means statusbar column index, currently only value 0 is used ("text message" statusbar cell). Method can return False to disable usual showing of message. Param "ed_self" is None here.
  • on_console_nav(self, ed_self, text): Called on double-clicking a line, or calling context menu item "Navigate", in the Console's multi-line memo field. Param "text" is Console memo line with caret. Param "ed_self" is None here.
  • on_console_complete(self, ed_self): Called when user presses hotkey of "auto-complete" in the Console input. Param "ed_self" is None here. True return value means that plugin handled the event, don't call other plugins.
  • on_output_nav(self, ed_self, text, tag): Called on double-clicking a line, or pressing Enter, in the Output/Validate panels. Param "text" is clicked line, param "tag" is int value associated with the line. Event is called only if app cannot parse output line by itself using given RegEx, or if RegEx is not set. Param "ed_self" is None here.
  • on_sidebar_popup(self, ed_self, caption): Called on right-click on sidebar (with bottom-bar) buttons. Param "caption" is caption of clicked button (this is non-translatable string, always in English). Param "ed_self" is None here.

Events - Macros

  • on_macro(self, ed_self, text): Called when command "start/stop macro recording" stops the recording. Param "text" is string: "\n"-separated text of macro items, which were run during the macro recording.
    • if item is str(number) then it's simple command.
    • if item is "number,string" then it's command with string parameter (usually it's command cCommand_TextInsert).
    • if item is "py:string_module,string_method,string_param" then it's call of Python plugin (usually string_param is empty).

Note: To run each on_macro item (with number) later, call ed.cmd(): number is command code, string after comma is command text.

Events priority

By default all events in all plugins have priority=0. So for any event, if 2+ plugins handle this event, they're called in the order on module names (e.g. cuda_aa, then cuda_dd, then cuda_mmm).

You may want to handle some event first. To change priority for your plugin event, write in install.inf event like this: "on_key+", "on_key++"... with any number of "+" up to 4. Each "+" makes higher priority. So first called "on_key" with maximal number of "+", last called "on_key" without "+".

Lazy events

By default all event handlers, except on_exit, are not "lazy". On_exit is always "lazy" - it means that it's called only for already loaded plugins. To make other event handlers lazy, write in install.inf event name with "~":

events=on_focus~,on_open~,on_state~

It's allowed to combine "+" and "~" suffixes, like on_focus~++

Callback parameter

Callback parameter is supported in several API functions: dlg_proc, timer_proc, menu_proc, button_proc etc. For all functions, "string form" of callback is supported. For most but not all functions, "callable form" is supported too.

Parameter can be in these forms:

  • callable, ie name of a Python function, or just "lambda". Internally, callable will be converted to a weird string. Note that some functions do not support "callable form". You can detect this support by reading the code of "py/cudatext.py" module, which performs the conversions from callable to string.
  • string "module=mmm;cmd=nnn;" - to call method nnn (in class Command) in plugin mmm, where mmm is usually sub-dir in the "cudatext/py", but can be any module name.
  • string "module=mmm;cmd=nnn;info=iii;" - the same, and callback will get param "info" with your value.
  • string "mmm.nnn" - the same, to call method, short form.
  • string "module=mmm;func=nnn;" - to call function nnn in root of module mmm.
  • string "module=mmm;func=nnn;info=iii;" - the same, and callback will get param "info" with your value.
  • string "exec=command_line_params_here" - to handle the contents of callback (after prefix "exec=") as a command line passed to CudaText process. For example, here you can pass filenames of text/picture files, of .cuda-proj project files, of .cuda-session session files.

For example:

  • If you need to call function "f" from plugin cuda_my, from file "py/cuda_my/__init__.py", callback must be "module=cuda_my;func=f;"
  • If you need to call it from file "py/cuda_my/lib/mod.py", callback must be "module=cuda_my.lib.mod;func=f;".

Value after "info=" can be of any type, e.g. "info=20;" will pass int 20 to callback, "info='my';" will pass string 'my'.

Global functions

version

app_exe_version()

Returns version of program. String, 4 dot-separated numbers.

app_api_version()

Returns version of API. String, 3 dot-separated numbers.

Example of version check:

  from cudatext import *
  if app_api_version() < '1.0.350':
      msg_box('Plugin needs newer program version', MB_OK+MB_ICONWARNING)

app_path

app_path(id)

Returns some file-system path. Possible values of "id":

  • APP_DIR_EXE: Folder of program executable.
  • APP_DIR_SETTINGS: Folder "settings" (which usually contains user.json file).
  • APP_DIR_SETTINGS_DEF: Folder "settings_default" (which usually contains default.json file).
  • APP_DIR_DATA: Folder "data".
  • APP_DIR_PY: Folder "py" (with Python codes).
  • APP_DIR_INSTALLED_ADDON: Folder of last installed add-on. For plugins it is subfolder in "py", for data-files it is subfolder in "data", for lexers it is folder "data/lexlib". This path is internally updated when add-on was installed: via file_open() API; via "Open file" dialog when you open .zip file; via command-line with .zip file.
  • APP_FILE_SESSION: Filename of current session. Default filename is "history session.json" without path. Missing path means that session file is in the folder "settings".
  • APP_FILE_RECENTS: String, "\n"-separated filenames of recently used files.

app_proc

app_proc(id, text)

Performs application-wide action.

Parameter "text" is usually string, but can be of other types (bool, int, float, tuple/list of simple types).

app_proc - Getting handles

  • PROC_GET_TAB_IMAGELIST: Returns int handle of imagelist, containing icons of all UI-tabs. Use imagelist_proc() to work with it. Use PROP_TAB_ICON property to get/set file-tab icon index (index in this imagelist).
  • PROC_GET_CODETREE: Returns int handle of built-in code-tree UI control. Use tree_proc() to work with it.
  • PROC_GET_CONSOLE_FORM: Returns int handle of built-in Console form. Use dlg_proc() to work with it.
  • PROC_GET_OUTPUT_FORM: Returns int handle of built-in Output form (contains the Output read-only editor). Use dlg_proc() to work with it.
  • PROC_GET_VALIDATE_FORM: Returns int handle of built-in Validate form (contains the Validate read-only editor). Use dlg_proc() to work with it.
  • PROC_GET_MAIN_TOOLBAR: Returns int handle of main app toolbar. Use toolbar_proc() to work with it.
  • PROC_GET_MAIN_STATUSBAR: Returns int handle of main app statusbar. Use statusbar_proc() to work with it.

app_proc - Misc properties

  • PROC_GET_LANG: Returns string id of active app translation. E.g. "ru_RU" if translation file is "ru_RU.ini", or "translation template" if such file is used. Returns empty string if built-in English translation is used.
  • PROC_GET_GROUPING: Returns grouping mode in program, one of GROUPS_nnnn int constants.
  • PROC_SET_GROUPING: Sets grouping mode in program, one of GROUPS_nnnn int constants.
  • PROC_PROGRESSBAR: Changes state of the progress-bar (hidden by default), which is located on the status-bar right corner. Int value<0: progressbar hides, value in 0..100: progressbar shows with the given value.
  • PROC_SET_FOLDER: Sets path of folder which will be used as initial folder in program's Open/Save-as dialogs.
  • PROC_SET_PROJECT: Informs the program that some "project" (in the Project Manager) has been opened or closed. Program will fire "on_state" event with APPSTATE_PROJECT.
  • PROC_WINDOW_TOPMOST_GET: Returns bool flag: main window has "always on top" style.
  • PROC_WINDOW_TOPMOST_SET: Sets bool flag: main window has "always on top" style.
  • PROC_CONFIG_READ: Reads param "text" as contents of CudaText JSON config file.
  • PROC_CONFIG_NEWDOC_EOL_GET: Returns str: line endings of newly created documents (app option "newdoc_ends").
  • PROC_CONFIG_NEWDOC_EOL_SET: Sets str: line endings of newly created documents.
  • PROC_CONFIG_NEWDOC_ENC_GET: Returns str: encoding of newly created documents (app option "newdoc_encoding").
  • PROC_CONFIG_NEWDOC_ENC_SET: Sets str: encoding of newly created documents.
  • PROC_CONFIG_SCALE_GET: Returns UI scales, as 2-tuple (int_scale_UI, int_scale_font). Both values are in percents, defaults are 100.
  • PROC_CONFIG_SCALE_SET: Sets UI scales, value must be 2-tuple (int_scale_UI, int_scale_font).
  • PROC_PARSE_COMMAND_LINE: Parses/handles the text as the program command line. Separator of params is space, double-quoted params are supported. Here you may pass, for example, several filenames, including project and session filenames (.cuda-proj and .cuda-session extensions).
  • PROC_GET_WINDOW_STATE: Gets state of application window, one of int constants:
    • WND_NORMAL: Window is normal
    • WND_MAXIMIZED: Window is maximized
    • WND_MINIMIZED: Window is minimized
    • WND_FULLSCREEN: Full-screen mode
    • WND_FULLSCREEN2: Full-screen + Distraction-free mode

app_proc - Search properties

Actions work with props of Find/Replace dialog, and props of low-level search engine. When user runs some search command in the dialog, dialog applies its props to the search engine. So most of the time, props of dialog and search engine are sync'ed. But they aren't sync'ed if user just typed new text in the dialog. They also aren't sync'ed if user runs some search command via Command Palette or hotkey (e.g. "find current word, previous").

  • PROC_GET_FINDER_PROP: Returns properties of Find/Replace dialog and search engine. Returns dict with keys:
    • "find": string "what to find" of search engine
    • "rep": string "replace with" of search engine
    • "find_d": string "what to find" of dialog field, None if dialog not inited
    • "rep_d": string "replace with" of dialog field, None if dialog not inited
    • "find_h": drop-down history list of "what to find" dialog field, None if dialog not inited
    • "rep_h": drop-down history list of "replace with" dialog field, None if dialog not inited
    • "op_case": option "case sensitive" of search engine
    • "op_word": option "whole words" of search engine
    • "op_regex": option "reg.ex." of search engine
    • "op_regex_subst": option "reg.ex. substitute in 'Replace with' field" of search engine
    • "op_cfm": option "confirm on replace" of search engine
    • "op_insel": option "in selection" of search engine
    • "op_wrap": option "wrapped search" of search engine
    • "op_wrap_c": option "show wrapped-search confirmation when search reaches the document edge" of search engine
    • "op_back": option "backward search" (low level) of search engine
    • "op_fromcaret": option "search from caret" (low level) of search engine
    • "op_tokens": option "allowed syntax elements" of search engine (int)
    • "op_prescase": option "preserve case on replacement" of search engine
    • "op_case_d": option "case sensitive" of dialog, None if dialog not inited
    • "op_word_d": option "whole words" of dialog, None if dialog not inited
    • "op_regex_d": option "reg.ex." of dialog, None if dialog not inited
    • "op_regex_subst_d": option "reg.ex. substitute in 'Replace with' field" of dialog, None if dialog not inited
    • "op_cfm_d": option "confirm on replace" of dialog, None if dialog not inited
    • "op_insel_d": option "in selection" of dialog, None if dialog not inited
    • "op_wrap_d": option "wrapped search" of dialog, None if dialog not inited
    • "op_mulline_d": option "multi-line input fields" of dialog, None if dialog not inited
    • "op_tokens_d": option "allowed syntax elements" of dialog (int), None if dialog not inited
    • "op_prescase_d": option "preserve case on replacement" of dialog, None if dialog not inited
    • "op_hi_d": option "highlight all matches" of dialog, None if dialog not inited
  • PROC_SET_FINDER_PROP: Sets properties of Find/Replace dialog and search engine. Param "text" must be dict, with all or some keys listed in PROC_GET_FINDER_PROP. Values types: str (for text fields), bool (for flags), int (for choices).

app_proc - System

  • PROC_ENUM_FONTS: Returns list of font names, currently installed in OS. There are no font names common in all OS'es.
  • PROC_ENUM_ENCODINGS: Returns list of supported encoding names.
  • PROC_GET_SYSTEM_PPI: Returns int value of screen pixels-per-inch. Usual value is 96. When OS UI is scaled, it's bigger, e.g. for scale 150% it is round(96*1.5).
  • PROC_GET_GUI_HEIGHT: Returns height (pixels) of GUI element for dlg_custom(). Possible values of 'text': 'button', 'label', 'linklabel', 'combo', 'combo_ro', 'edit', 'spinedit', 'check', 'radio', 'checkbutton', 'filter_listbox', 'filter_listview'. Special value 'scrollbar' gets size of OS scrollbar. Returns None for other values.
  • PROC_GET_MOUSE_POS: Returns mouse cursor position in screen-related coordinates, as (x, y) tuple.
  • PROC_SEND_MESSAGE: For Windows. Sends message to a window by its handle. Param "text" must be 4-tuple of int (window_handle, msg_code, param1, param2).
  • PROC_GET_UNIQUE_TAG: Gets integer value, which is unique for the current CudaText process (it starts with 100, increasing with each call). Use this value for Editor.markers() and Editor.attr() tag values.
  • PROC_GET_OS_SUFFIX: Returns string of OS suffix, which is used in some CudaText option names. Possible values are listed in the default.json file.
  • PROC_GET_COMPILER_INFO: Returns information about OS/CPU/WidgetSet CudaText was compiled for, as dict. Dict keys are: "os", "cpu", "widgetset", "fpc".

app_proc - Clipboard

  • PROC_GET_CLIP: Returns clipboard text.
  • PROC_GET_CLIP_EX: Returns additional info, stored to clipboard by CudaText, as dict. Dict keys are:
    • "is_column": bool: True if clipboard contains the column (vertical) block.
    • "caret_pos": 4-tuple of int: Position (x, y, x_end, y_end) of the first caret, at the moment of copying.
    • "caret_count": int: Number of caret(s), at the moment of copying.
    • "indent_chars": int: Number of indentation chars (spaces/tabs), of the block's first line, in the original document. Tab-chars are not expanded (counted as 1).
    • "indent_columns": int: Number of indentation columns, of the block's first line, in the original document. Tab-chars are expanded.
    • "file_name": str: Full path of the file from which text was copyied. Limited by 255 chars.
    • "version": int: Modification version of the document, at the moment of copying.
    • "tick_on_copy": int: OS tick-count in milliseconds, at the moment of copying.
    • "tick_current": int: OS tick-count in milliseconds, at the moment of this API call.
  • PROC_SET_CLIP: Copies text to clipboard (usual clipboard). Note: this clears the clipboard first.
  • PROC_SET_CLIP_HTML: Copies text to clipboard (usual clipboard) in HTML format, additionally to clipboard contents in plain-text format. Param "text" must be HTML-formatted fragment. Note: this does not clear the clipboard first.
  • PROC_SET_CLIP_ALT: Copies text to alternate clipboard on Linux, called "primary selection".
    • CudaText "Copy" commands put text to usual clipboard + primary selection.
    • CudaText "Paste" commands get text from usual clipboard.
    • CudaText middle-click with option "mouse_mid_click_paste":true gets text from primary selection.
  • PROC_CLIP_ENUM: Returns string, where each char represents a format stored in Clipboard.
    • "t": Text format.
    • "h": HTML format.
    • "p": Picture format.
    • "c": CudaText format telling about "is it column (vertical) block".
    • "x": CudaText format telling about last copying to Clipboard (PROC_GET_CLIP_EX will show these details).
  • PROC_CLIP_SAVE_PIC: If Clipboard has a picture format, saves it to given filename (recommended the .png extension). Returns bool: clipboard has a picture, file is saved.

app_proc - Plugin calls

  • PROC_SET_EVENTS: Subscribes plugin to events. First it removes all subscribed events for specified module name (even those from install.inf file) and then adds specified events (if event list is not empty). Param "text" must be 4 values ";"-separated: "module_name;event_list;lexer_list;filter".
    • module_name is plugin's main module name, usually starting with "cuda_".
    • event_list is comma-separated event names, e.g. "on_open,on_save", or empty string.
    • lexer_list is comma-separated lexer names, e.g. "C,C++", or empty string.
    • filter is additional parameter, used by some events, if that filter is not empty:
      • filter for "on_key": comma-separated list of int key codes to handle in event, e.g. "9,32" means that event is only called for pressed Tab and Space.
      • filter for "on_open", "on_open_pre": comma-separated list of lower-case file extensions, without leading dot, to handle in event.
  • PROC_GET_LAST_PLUGIN: Returns info about last plugin which run from program. It is str "module_name,method_name", values are empty if no plugins run yet.
  • PROC_SET_SUBCOMMANDS: Adds command items (items which can be called from Command Palette). These items will run specified module name and method name, but with different parameters to that method. For example, plugin External Tools uses this API to add command items for configured tools. Param "text" must be ";"-separated: "module_name;method_name;param_list".
    • "param_list" is "\n"-separated items, each item is param_caption+"\t"+param_value.
    • "param_caption" is caption for Command Palette.
    • "param_value" is parameter for Python method. It can be any primitive type: int, string, bool, None, or even some expression.
  • PROC_GET_COMMANDS: Returns list of all commands, as list of dict. Dict keys are:
    • "type": str: Possible values:
      • "cmd": usual built-in command
      • "lexer": command to activate lexer
      • "plugin": plugin command
      • "openedfile": command to switch active tab
      • "recentfile": command to reopen recent file
    • "cmd": int: Command code, to use in ed.cmd() call.
    • "name": str: Pretty name, which is visible in the Commands dialog.
    • "key1": str: Hotkey-1.
    • "key2": str: Hotkey-2.
    • "key1_init": str: Hotkey-1 from built-in config.
    • "key2_init": str: Hotkey-2 from built-in config.
    • (for plugins) "p_caption": str: Menu-item caption from install.inf.
    • (for plugins) "p_module": str: Python module.
    • (for plugins) "p_method": str: Python method in Command class.
    • (for plugins) "p_method_params": str: Optional params for Python method.
    • (for plugins) "p_lexers": str: Comma-separated lexers list.
    • (for plugins) "p_from_api": bool: Shows that command was generated from API by some plugin.
    • (for plugins) "p_in_menu": str: Value of parameter "menu" from install.inf.
  • PROC_GET_AUTOCOMPLETION_INVOKE: Returns the invokation kind of "on_complete" event call. Possible string values:
    • "c": Command or hotkey.
    • "a": Work of option "autocomplete_autoshow_chars".
    • "r": Re-showing of listbox, caused by typing, deleting, arrows left/right.

app_proc - Hotkeys

  • PROC_GET_ESCAPE: Returns Esc-key flag (bool). This flag is set when user presses Esc key, each Esc press is counted since app start.
    • Note: if you run long loop, to allow app to react to keyboard/mouse in the loop, call msg_status(text, True).
  • PROC_SET_ESCAPE: Sets Esc-key flag. Param "text" must be bool.
  • PROC_GET_HOTKEY: Returns hotkey(s) string for given command_id. Returns empty string for unknown command_id.
    • Command_id can be: str(int_command_code) or "module,method" or "module,method,param".
    • Examples of result: "F1", "Ctrl+B * B", "Ctrl+B * B * C|Ctrl+B * D" (two hotkeys for one command).
  • PROC_SET_HOTKEY: Sets hotkeys for given command_id from strings. Param "text" must be "command_id|hotkey1|hotkey2", where hotkey1/hotkey2 examples are: "F1", "Ctrl+B * B", "Ctrl+B * B * C". Symbol "*" can be without near spaces. Returns bool: command_id exists, hotkey(s) was set.
  • PROC_GET_KEYSTATE: Returns state of pressed keyboard keys and mouse buttons. String result has chars:
    • "c" for Ctrl
    • "a" for Alt
    • "s" for Shift
    • "m" for Meta (Windows key)
    • "L" for left mouse button
    • "R" for right mouse button
    • "M" for middle mouse button
    • "4" for the 4th mouse button
    • "5" for the 5th mouse button
  • PROC_HOTKEY_STR_TO_INT: Converts given string hotkey to int. Returns 0 for incorrect hotkey string.
    • Example: converts "alt+shift+z" to 41050.
  • PROC_HOTKEY_INT_TO_STR: Converts given int hotkey to string. Returns empty string for incorrect hotkey code.
    • Example: converts 41050 to "Shift+Alt+Z".

app_proc - Python

  • PROC_EXEC_PYTHON: Runs Python string in the context of Console. It is not the same as standard exec() call, it uses the same globals/locals as CudaText Console.
  • PROC_EXEC_PLUGIN: Runs Python plugin's method. Text must be comma-separated: "module_name,method_name,params", where "params" is optional part, it is parameter(s) for the method.

app_proc - Themes

Notes:

  • Theme names are short strings, lowercase, e.g. "cobalt", "sub". Empty string means built-in theme.
  • Setting default theme (empty str) resets both UI + syntax themes.
  • To enumerate themes, you need to list themes folder.

Actions:

  • PROC_THEME_UI_GET: Returns name of UI-theme.
  • PROC_THEME_UI_SET: Sets name of UI-theme.
  • PROC_THEME_SYNTAX_GET: Returns name of syntax-theme.
  • PROC_THEME_SYNTAX_SET: Sets name of syntax-theme.
  • PROC_THEME_UI_DICT_GET: Returns contents of current UI-theme, as dict.
  • PROC_THEME_SYNTAX_DICT_GET: Returns contents of current syntax-theme, as dict. For description of keys of result, see LEXER_GET_STYLES.

app_proc - Sessions

Session is a set of opened files + untitled tabs, with some properties of editors in these tabs, with group-indexes of tabs, with layout of groups. Session format is JSON.

  • PROC_SAVE_SESSION: Saves session to file with given name. Returns bool: session was saved. Param "text" must be file name, and optional addition: ";" with several option-chars after ";":
    • char 'n': Don't save text of modified named files.
    • char 'u': Don't save text of untitled documents (which are always modified).
    • char 't': Show additional text in the Console message: "; by timer at ...".
  • PROC_LOAD_SESSION: Loads session from file with given name (closes all tabs first). Returns bool: tabs were closed without pressing Cancel, session was loaded.
  • PROC_SET_SESSION: Tells to app filename of session. Session with this filename will be saved on exit, loaded on start, shown in app title in {} brackets. Don't set here empty string. Default filename is "history session.json" without path. Missing path means that folder "settings" will be used.

(Feature of API version 1.0.418.) Session-related actions support specifying the JSON path, into which session will be saved/loaded. If you want to use this feature, add the JSON path to the session filename, after pipe-char "|", e.g. "/some/path/sessionname.cuda-session|/my/key". Here "/my/key" specifies the JSON path of 2 levels ("key" inside "my").

app_proc - Sidebar panels

General notes:

  • Word "tab" here means: sidebar button with attached embedded dialog, which looks like a tab.
  • Caption of "tab" must not contain ",". Name of icon file - too. Tooltip string - too.
  • Actions find "tabs" by caption, caption is some latin text, which is not affected by CudaText translation. E.g. caption "Code tree" always refers to Code-Tree tab, with any active translation.
  • Name of icon file: path of PNG/BMP file. Icon size/dimensions should be equal to the size of current sidebar imagelist. Default is 20x20. You can detect size of this imagelist, by using PROC_SIDEBAR_GET_IMAGELIST and passing returned handle to imagelist_proc(). If filename is without path, CudaText subfolder "data/sideicons" is used.

Actions:

  • PROC_SIDEPANEL_ADD_DIALOG: Adds tab, with embedded dialog. Returns bool: all parameters are correct, tab was added. Param "text" must be 3-tuple:
    • Item 0: Caption of tab.
    • Item 1: Int handle of dialog, from dlg_proc().
    • Item 2: Name of icon file.
  • PROC_SIDEPANEL_REMOVE: Removes tab. Param "text" is caption of tab. (Note: actually it hides tab, dialog for this tab is still in memory). Returns bool: tab was found/removed.
  • PROC_SIDEPANEL_ACTIVATE: Activates tab. Returns bool: tab was found/activated. Param "text" can be string or tuple:
    • str: caption.
    • 2-tuple (caption, bool_set_focus). Default for bool_set_focus is False.
  • PROC_SIDEPANEL_ENUM_ALL: Enumerates tabs. Returns list of dict, each dict item has keys:
    • "cap": str: Panel caption (not affected by translation)
    • "hint": str: Button's floating tooltip (affected by translation).
    • "dlg": int: Handle of panel's dialog. Can be 0, if dialog is not yet created. For example, plugins "Tabs List" and "Snippet Panel" do not create the dialog until plugin is called.
    • "img": int: Button's image-index in the imagelist.
    • "btn_h": int: Button's handle. Use this handle with button_proc().
    • "module": str: Python module name, or empty str.
    • "method": str: Python method name, or empty str.
  • PROC_SIDEPANEL_GET_CONTROL: Returns int handle of dialog, inserted into tab. Param "text" is caption of tab. Returns None if cannot find tab.
  • PROC_SIDEPANEL_GET: Returns caption of last activated tab.
  • PROC_SIDEPANEL_SET_PROP: Changes properties of sidebar button. Returns bool: button was found/changed. Param "text" must be 3-tuple:
    • Item 0: Caption of tab.
    • Item 1: Int index of button's icon in sidebar's imagelist, or -1 to keep old value.
    • Item 2: Floating tooltip string (it's independent from caption), or empty str to keep old value.
  • PROC_SIDEPANEL_GET_IMAGELIST: Returns int handle of sidebar's imagelist. Use this handle with imagelist_proc().

app_proc - Bottom-bar panels

  • PROC_BOTTOMPANEL_ADD_DIALOG: Adds tab. Same as for PROC_SIDEPANEL_ADD_DIALOG.
  • PROC_BOTTOMPANEL_REMOVE: Removes tab. Same as for PROC_SIDEPANEL_REMOVE.
  • PROC_BOTTOMPANEL_ACTIVATE: Activates tab. Same as for PROC_SIDEPANEL_ACTIVATE.
  • PROC_BOTTOMPANEL_ENUM_ELL: Enumerates tabs. Same as for PROC_SIDEPANEL_ENUM_ALL.
  • PROC_BOTTOMPANEL_GET_CONTROL: Returns int handle of control. Same as for PROC_SIDEPANEL_GET_CONTROL.
  • PROC_BOTTOMPANEL_GET: Returns caption of last activated tab. Same as for PROC_SIDEPANEL_GET.
  • PROC_BOTTOMPANEL_SET_PROP: Sets sidebar's button properties. Same as for PROC_SIDEPANEL_SET_PROP.

app_proc - Splitters

Splitter id:

  • SPLITTER_SIDE: splitter near side panel.
  • SPLITTER_BOTTOM: splitter above bottom panel.
  • SPLITTER_G1 .. SPLITTER_G5: splitters between groups.

Actions:

  • PROC_SPLITTER_GET: Returns info about splitter, as 4-tuple: (bool_vertical, bool_visible, int_pos, int_parent_panel_size). Param "text" is int splitter id.
  • PROC_SPLITTER_SET: Sets splitter pos. Param "text" is 2-tuple (int_splitter_id, int_splitter_pos).

Positions of group splitters (G1, G2, G3, G4, G5) are determined by grouping view, in one view splitter may be horizontal with one parent panel, in other view - vertical with another parent panel. Detailed:

2VERT     t G1 t

2HORZ     t
          G1
          t

3VERT     t G1 t G2 t

3HORZ     t
          G1
          t
          G2
          t

1P2VERT    t G3 t
               G2
                t

1P2HORZ    t
           G3
           t G2 t

4VERT     t G1 t G2 t G3 t

4HORZ     t
          G1
          t
          G2
          t
          G3
          t

4GRID     t G1 t
          G3
          t G2 t

6VERT     t G1 t G2 t G3 t G4 t G5 t

6HORZ     t
          G1
          t
          G2
          t
          G3
          t
          G4
          t
          G5
          t

6GRID     t G1 t G2 t
          G3
          t G1 t G2 t

app_proc - Show/Hide/Undock UI elements

Actions get/set state of UI elements, "value" must be False/True:

  • PROC_SHOW_STATUSBAR_GET: for main statusbar (on the bottom).
  • PROC_SHOW_STATUSBAR_SET
  • PROC_SHOW_TOOLBAR_GET: for horizontal toolbar (on the top).
  • PROC_SHOW_TOOLBAR_SET
  • PROC_SHOW_SIDEBAR_GET: for vertical sidebar.
  • PROC_SHOW_SIDEBAR_SET
  • PROC_SHOW_SIDEPANEL_GET: for panels near the sidebar (Code-Tree, Project Manager etc).
  • PROC_SHOW_SIDEPANEL_SET
  • PROC_SHOW_BOTTOMPANEL_GET: for panels near the statusbar (Console, Output etc.)
  • PROC_SHOW_BOTTOMPANEL_SET
  • PROC_SHOW_TABS_GET: for UI-tabs bar (can be placed at all 4 sides).
  • PROC_SHOW_TABS_SET
  • PROC_SHOW_TREEFILTER_GET: for Code-Tree "filter" input field.
  • PROC_SHOW_TREEFILTER_SET
  • PROC_SHOW_FLOATGROUP1_GET: for "floating group 1", which is activated by moving some UI-tabs there, from UI-tab context menu.
  • PROC_SHOW_FLOATGROUP1_SET
  • PROC_SHOW_FLOATGROUP2_GET: for "floating group 2".
  • PROC_SHOW_FLOATGROUP2_SET
  • PROC_SHOW_FLOATGROUP3_GET: for "floating group 3".
  • PROC_SHOW_FLOATGROUP3_SET
  • PROC_FLOAT_SIDE_GET: "floating" property of side panels.
  • PROC_FLOAT_SIDE_SET
  • PROC_FLOAT_BOTTOM_GET: "floating" property of bottom panels.
  • PROC_FLOAT_BOTTOM_SET

app_proc - Screen coordinates

Notes:

  • When getting or setting coords, you get/set 4-tuple of int: (left, top, right, bottom).
  • Any coord of any monitor (and 'desktop') can be negative. For example, tuple (-1920, 0, 0, 1080) - this means that OS configuration has placed that monitor lefter than x=0.

Actions:

  • PROC_COORD_WINDOW_GET: Returns coords of app window.
  • PROC_COORD_WINDOW_SET: Sets coords of app window.
  • PROC_COORD_MONITOR: Returns coords of monitor with app window.
  • PROC_COORD_MONITOR0: Returns coords of 1st monitor.
  • PROC_COORD_MONITOR1: Returns coords of 2nd monitor, or None if no such monitor.
  • PROC_COORD_MONITOR2: Returns coords of 3rd monitor, or None if no such monitor.
  • PROC_COORD_MONITOR3: Returns coords of 4th monitor, or None if no such monitor.
  • PROC_COORD_DESKTOP: Returns coords of 'desktop', which is the combined areas of all existing monitors. For example, with 2 monitors, 'desktop' is about 2x wider or about 2x taller than one average monitor. With 3-4 monitors, you cannot assume that all monitors are placed in horizontal row, or in vertical row, or in another shape. But you can detect that from coords of all monitors.

app_log

app_log(id, text, tag=0, panel="")

Performs action with standard panels in the bottom panel: Output, Validate, Console.

Possible values of "panel":

  • value LOG_PANEL_OUTPUT: Output panel
  • value LOG_PANEL_VALIDATE: Validate panel

Possible values of "id" for Output/Validate panels:

  • LOG_CLEAR: Clears log panel. Param "text" is ignored.
  • LOG_ADD: Adds line to log panel.
  • LOG_SET_REGEX: Sets parsing RegEx for log panel. Param "text" is RegEx string. RegEx must have some groups in round brackets, indexes of these groups must be passed in separate API calls. All lines in log panel, which can be parsed by this regex, will allow navigation to source code by click or double-click.
  • LOG_SET_LINE_ID: Sets index of regex group for line-number. Param "text" is one-char string from "1" to "8", and "0" means "not used".
  • LOG_SET_COL_ID: Sets index of regex group for column-number. Param "text" must be str(number).
  • LOG_SET_NAME_ID: Sets index of regex group for file-name. Param "text" must be str(number).
  • LOG_SET_FILENAME: Sets default file name, which will be used when regex cannot find file name in a string. Param "text" is value.
  • LOG_SET_ZEROBASE: Sets flag: line and column numbers are 0-based, not 1-based. Param "text" must be one-char string "0" or "1".
  • LOG_GET_LINES_LIST: Returns items in panel's listbox, as list of 2-tuples (line, 0).
  • LOG_GET_LINEINDEX: Returns index of selected line in panel's listbox.
  • LOG_SET_LINEINDEX: Sets index of selected line in panel's listbox. Param "text" must be str(number).

Possible values of "id" for "Console" panel:

  • LOG_CONSOLE_CLEAR: Clears UI controls in console.
    • If text empty or has "m" then memo-control (above) is cleared.
    • If text empty or has "e" then edit-control (below) is cleared.
    • If text empty or has "h" then combobox history list is cleared.
  • LOG_CONSOLE_ADD: Adds line to console (its combobox and memo).
  • LOG_CONSOLE_GET_COMBO_LINES: Returns list of lines in combobox-control.
  • LOG_CONSOLE_GET_MEMO_LINES: Returns list of lines in memo-control.

Parameter "tag" is deprecated and is not used.

Example

For line "line 10 column 20: text message here" the following regex and indexes can be used:

  • regex "\w+ (\d+) \w+ (\d+): .+"
  • line-number index "1"
  • column-number index "2"
  • file-name index "0" (not used)
  • zero-base flag "0" (off)

app_idle

app_idle(wait=False)

Performs application's message-processing. If wait=True, also waits for new UI event.

emmet

emmet(id, text, p1="", p2="")

Performs action with embedded Emmet engine. Possible values of "id":

  • EMMET_EXPAND: Expand abbreviation. Returns 2-tuple (str_result, bool_multi_caret) or None.
    • Param "text": Emmet abbreviation.
    • Param "p1": Emmet syntax. Possible values: "html", "xml", "xsl", "css", "svg", "sass", "less".
  • EMMET_WRAP: Wrap text with abbreviation. Returns str result or None.
    • Param "text": Emmet abbreviation.
    • Param "p1": Emmet syntax.
    • Param "p2": Text to wrap. Can be multi-line with LF line breaks.
  • EMMET_GET_POS: Find beginning of abbreviation in given string. Returns offset in string (0-based), or None.
    • Param "text": Text string (can include unneeded text after caret position, can include HTML tags before abbreviation).
    • Param "p1": Caret offset (0-based) to search abbreviation to the left of it.

msg_box

msg_box(text, flags)

Shows modal message-box.

Param "text" is message text. Multi-line text with "\n" is supported.

Param "flags" is sum of button-value (OK, OK/Cancel, Yes/No etc):

  • MB_OK
  • MB_OKCANCEL
  • MB_ABORTRETRYIGNORE
  • MB_YESNOCANCEL
  • MB_YESNO
  • MB_RETRYCANCEL

and icon-value:

  • MB_ICONERROR
  • MB_ICONQUESTION
  • MB_ICONWARNING
  • MB_ICONINFO

Returns int code of pressed button (returns ID_CANCEL if dialog cancelled):

  • ID_OK
  • ID_CANCEL
  • ID_ABORT
  • ID_RETRY
  • ID_IGNORE
  • ID_YES
  • ID_NO

msg_box_ex

msg_box_ex(caption, text, buttons, icon, focused=0)

Shows modal message-box with any number of buttons with any captions.

  • Param "caption": str: Caption of dialog.
  • Param "text": str: Message text. Multi-line text with "\n" is supported.
  • Param "buttons": list of str: Non-empty list of button captions. Multi-line captions are not supported on Windows.
  • Param "icon": int: Icon in dialog, one of constants:
    • MB_ICONERROR
    • MB_ICONQUESTION
    • MB_ICONWARNING
    • MB_ICONINFO
  • Param "focused": int: Index of focused button.

Returns int index of pressed button (0-based), or None of cancelled.

msg_status

msg_status(text, process_messages=False)

Shows given text in statusbar.

Param "process_messages": if True, function also does UI messages processing. It takes some time, it is needed to refresh status of Esc-key pressed. After call msg_status(..., True) you can get state of Esc-key pressed via PROC_GET_ESCAPE, otherwise plugin gets an old state, until UI messages are processed.

msg_status_alt

msg_status_alt(text, pause, pos=HINTPOS_CARET, x=0, y=0)

Shows given text in the floating tooptip.

  • Param "text": Text of tooltip. Multi-line text, with "\n", is supported.
  • Param "pause": Show duration in seconds, 1..30. Value<=0 hides the tooltip, if it's already shown.
  • Param "pos": Possible values are:
    • HINTPOS_CARET: Show near the first caret.
    • HINTPOS_CARET_BRACKET: Like HINTPOS_CARET, but moves to the nearest opening bracket.
    • HINTPOS_TEXT: Show near custom text position specified by params "x" and "y" (0-based).
    • HINTPOS_TEXT_BRACKET: Like HINTPOS_TEXT, but moves to the nearest opening bracket.
    • HINTPOS_WINDOW_TOP: Show near the window top.
    • HINTPOS_WINDOW_BOTTOM: Show near the window bottom.

dlg_input

dlg_input(prompt, text)

Shows modal dialog to input one string. Returns entered string or None if cancelled.

  • Param "prompt": Description text above the input field. It can be multi-line ("\n"-separated) and can have long line(s).
  • Param "text": Initial value of the input field.

dlg_input_ex

dlg_input_ex(number, caption,
              prompt1   , text1="", prompt2="", text2="", prompt3="", text3="",
              prompt4="", text4="", prompt5="", text5="", prompt6="", text6="",
              prompt7="", text7="", prompt8="", text8="", prompt9="", text9="",
              prompt10="", text10="")

Shows modal dialog to enter 1 to 10 string fields at once. Returns list of strings or None if cancelled.

  • Param "number": Count of input fields.
  • Params "prompt*": Descriptions near input fields. They cannot be multi-line.
  • Params "text*": Initial values of input fields.

dlg_file

dlg_file(is_open, init_filename, init_dir, filters, caption="")

Shows "Open file" or "Save file as" modal dialog. Returns filename (or list of filenames) or None if cancelled.

  • Param "is_open": True for "Open" dialog, False for "Save as" dialog.
  • Param "init_filename": Initial filename for "Save as" dialog. Can be empty.
  • Param "init_dir": Initial folder. Can be empty.
  • Param "filters": How to filter filenames from file system. Can be empty. Must be in format used by Lazarus IDE, example for 2 filters: "Source codes|*.pas;*.inc|Text files|*.txt"
  • Param "caption": If not empty, dialog caption. If empty, default dialog caption is used: "Open file", "Save file".

Additional options:

  • To allow multi-selection in the "Open" dialog, pass init_filename="*". If single filename was selected, result is str. If several filenames were selected, result is list of str.
  • To disable checking "entered filename exists" in the "Open" dialog, start init_filename with "!".

dlg_dir

dlg_dir(init_dir, caption="Select folder")

Shows dialog to select folder path. Returns path (str), or None if cancelled.

  • Param "init_dir": Initial folder.
  • Param "caption": Dialog caption.

dlg_menu

dlg_menu(id, items, focused=0, caption="", clip=0, w=0, h=0)

Shows menu-like dialog. Returns index of selected item (0-based), or None if cancelled.

Possible values of "id":

  • DMENU_LIST: Dialog with listbox and filter.
  • DMENU_LIST_ALT: Dialog with listbox and filter, but each item has double height, and instead of right-aligning, 2nd part of an item shows below.

Additional flags to add to above "id" values:

  • DMENU_NO_FUZZY: Disable fuzzy search in the items list.
  • DMENU_NO_FULLFILTER: Disable filtering by second part of items (after "\t"), filter only by first part.
  • DMENU_CENTERED: Show menu centered on screen (otherwise it's aligned to current editor).
  • DMENU_EDITORFONT: Use editor's font (monospaced) for list items, instead of variable-width UI font.

Parameters:

  • Param "items": Menu items, can be list of str, tuple of str, or string with "\n"-separated parts. Each item can be simple string or part1+"\t"+part2, where part2 shows right-aligned or below.
  • Param "focused": Index of initially selected item.
  • Param "caption": If not empty string, it is dialog caption.
  • Param "clip": How to shorten too long lines, one of values: CLIP_NONE (default), CLIP_LEFT, CLIP_MIDDLE, CLIP_RIGHT.
  • Param "w": If value>0, width of dialog.
  • Param "h": If value>0, height of dialog.

dlg_color

dlg_color(value)

Shows select-color dialog with given initial color (int).

Returns int color, or None if cancelled.

dlg_hotkey

dlg_hotkey(title="")

Shows dialog to press single hotkey.

Returns str of hotkey (e.g. "F1", "Ctrl+Alt+B") or None if cancelled.

dlg_hotkeys

dlg_hotkeys(command, lexer="")

Shows dialog to configure hotkeys of internal command or plugin. Returns bool: OK pressed and hotkeys saved (to keys.json).

Param "command" can be:

  • str(int_command): for internal command codes (module cudatext_cmd).
  • "module_name,method_name" or "module_name,method_name,method_param": for command plugin.

Param "lexer" is optional lexer name. If not empty, dialog enables checkbox "For current lexer" and, if checkbox checked, saves hotkey to lexer-specific config "keys lexer NNNN.json".

dlg_custom

dlg_custom(title, size_x, size_y, text, focused=-1, get_dict=False)

Shows dialog with controls of many types. This is legacy API, it is recommended to use "dlg_proc" instead.

dlg_custom - Types of controls

  • "button": simple button
  • "label": simple read-only text
  • "check": checkbox, checked/unchecked/grayed
  • "radio": radio-button, only one of radio-buttons can be checked
  • "edit": single-line input
  • "edit_pwd": single-line input for password, text is masked
  • "combo": combobox, editable + drop-down, value is text
  • "combo_ro": combobox, drop-down only, value is index of drop-down
  • "listbox": list of items with one item selected
  • "checkbutton": looks like button, but don't close dialog, checked/unchecked
  • "memo": multi-line input
  • "checkgroup": group of check-boxes
  • "radiogroup": group of radio-buttons
  • "checklistbox": listbox with checkboxes
  • "spinedit": input for numbers, has min-value, max-value, increment
  • "listview": list with columns, with column headers, value is index
  • "checklistview": listview with checkboxes, value is check-flags
  • "linklabel": label which activates URL on click
  • "panel": rectangle with centered caption only (client area is entire rect)
  • "group": rectangle with OS-themed border and caption on border (client area is decreased by this border)
  • "colorpanel": panel, with N-pixels colored border, with colored background
  • "image": picture, which shows picture-file
  • "trackbar": horiz/vert bar with handler, has position
  • "progressbar": horiz/vert bar, only shows position
  • "progressbar_ex": like progressbar, with new styles
  • "filter_listbox": input, which filters content of another "listbox" control
  • "filter_listview": input, which filter content of another "listview" control
  • "bevel": control which shows only border (at one side, or all 4 sides), w/o value/caption
  • "tabs": TabControl: set of tabs, w/o pages attached to them
  • "pages": PageControl: set of tabs, with pages attached to them (only one of pages is visible)
  • "splitter": divider bar (vertical or horizontal), which can be dragged by mouse, to change width/height of nearest control. It finds linked control, ie control with the same "parent" and "align", which position (coordinates) are nearest to the splitter. On mouse drag, splitter resizes this linked control. It's recommended to place another control with "align": ALIGN_CLIENT, so splitter will resize two controls at once. A panel may contain several splitters (mixed with other controls between them).
  • "scrollbox": like panel, but has two auto-shown scrollbars to scroll the area containing children controls (ie controls which parent is this scrollbox)

Details:

  • Control "button_ex": to change advanced props, you must get handle via DLG_CTL_HANDLE, and pass it to button_proc().
  • Control "treeview" don't have "items"/"value": to work with it, you must get handle of control via DLG_CTL_HANDLE, and pass it to tree_proc().
  • Control "listbox_ex" don't have "items"/"value": to work with it, you must get handle of control via DLG_CTL_HANDLE, and pass it to listbox_proc().
  • Control "toolbar" don't have "items"/"value": to work with it, you must get handle via DLG_CTL_HANDLE, and pass it to toolbar_proc().
  • Control "statusbar" don't have "items"/"value": to work with it, you must get handle via DLG_CTL_HANDLE, and pass it to statusbar_proc().
  • Controls "editor"/"editor_edit"/"editor_combo" don't have "items"/"value": to work with it, you must get handle via DLG_CTL_HANDLE, and pass it to Editor() to make editor object.
  • Control "paintbox" is empty area, plugin can paint on it. Get canvas_id via DLG_CTL_HANDLE, and use it in canvas_proc().
  • Control property "name" is required for "filter_nnnnn" controls: must set name of listbox/listview, and name of its filter - to the same name with prefix "f_" (e.g. listbox name "mylist" with filter name "f_mylist").

dlg_custom - Properties of controls

Parameter "text" in "dlg_custom" is "\n"-separated items, one item per control. Each item is chr(1)-separated properties in the form "name=value". Possible properties:

  • "type": type of control; must be specified first
  • "cap": caption
  • "act": active state, bool. For many controls (edit, check, radio, combo_ro, checkbutton, listbox'es, listview's, tabs), it means that control's value change fires events (for dlg_proc) or closes form (for dlg_custom).
  • "x", "y": position, left/top
  • "w", "h": size, width/height
  • "w_min", "w_max": Constraints for width, min/max value.
  • "h_min", "h_max": Constraints for height, min/max value.
  • "pos": position, str in the form "left,top,right,bottom". Some one-line controls ignore bottom and do auto size. If specified "x/y/w/h" together with "pos", then last mentioned prop has effect.
  • "en": enabled state, bool
  • "vis": visible state, bool
  • "hint": hint string for mouse-over. Can be multiline, "\r"-separated.
  • "texthint": text, shown with italic+pale font when value of control is empty. For "edit", "memo", "editor", "editor_edit", "editor_combo". Cannot be multi-line.
  • "color": background color
  • "autosize": control is auto-sized (by width and/or height, it's control-specific)
  • "font_name": font name
  • "font_size": font size
  • "font_color": font color
  • "font_style": font styles. String, each char can be: "b": bold, "i": italic, "u": underline, "s": strikeout.
  • "name": optional name of control. It may be not unique for all controls.
  • "ex0"..."ex9": advanced control-specific props. Described below.
  • "val": value of control. Described below.
  • "items": list of items. Described below.

dlg_custom - Property "items"

Possible values of "items" in "dlg_custom":

  • For "combo", "combo_ro", "listbox", "checkgroup", "radiogroup", "checklistbox", "tabs": "\t"-separated lines
  • For "listview", "checklistview": "\t"-separated items.
    • first item is column headers: title1+"="+size1 + "\r" + title2+"="+size2 + "\r" +...
    • size1...sizeN can be with lead char to specify alignment of column: L (default), R, C
    • other items are data: cell1+"\r"+cell2+"\r"+... (count of cells may be less than count of columns)
  • For "image": full path of picture file (png/gif/jpg/bmp)

Action DLG_CTL_PROP_GET also returns key "items" (in the same format) for these controls: "listbox", "checklistbox", "listview", "checklistview".

dlg_custom - Property "columns"

  • For "listview", "checklistview": "\t"-separated items, each item is "\r"-separated props of a column:
    • caption (must be without "\t", "\r", "\n")
    • width, as str
    • (optional) minimal width, as str. 0 means "not used". Not supported on Windows.
    • (optional) maximal width, as str. 0 means "not used". Not supported on Windows.
    • (optional) alignment - one of "L", "R", "C"
    • (optional) autosize - "0", "1"
    • (optional) visible - "0", "1"
  • For "radiogroup", it is number of vertical columns of radiobuttons.

Action DLG_CTL_PROP_GET also returns key "columns" in the same format.

Action DLG_CTL_PROP_SET, for "listview", allows both "items" (it sets columns) and "columns", and "columns" is applied last.

dlg_custom - Property "val"

  • For "combo", "combo_ro", "listbox": value is 0-based index of selected item, or -1 if none is selected.
  • For "check": value is checked state "0"/"1" or "?" for "grayed" state.
  • For "radio", "checkbutton": value is checked state "0"/"1".
  • For "edit", "edit_pwd", "spinedit", "combo", "filter_*": value is text in control.
  • For "memo": value is "\t"-separated lines, in lines "\t" chars must be replaced with chr(3).
  • For "combo_ro", "listbox", "radiogroup", "listview": value is index (0-based) of selected item.
  • For "checkgroup": value is ","-separated checked states "0"/"1".
  • For "checklistbox", "checklistview": value is str(index) + ";" + checked_states.
  • For "tabs", "pages": value is index of active tab.
  • For "trackbar", "progressbar": value is position, int value.
  • For "scrollbox":
    • on reading: value is 6 numbers ","-separated: vert_position, horz_position, vert_range, horz_range, vert_pagesize, horz_pagesize
    • on writing: value is only 2 numbers ","-separated: vert_position, horz_position.

dlg_custom - Properties "ex"

Properties "ex0"..."ex9" are specific to each control kind. They have different simple types (str, bool, int...). Note: for dlg_custom, bool values must be specified as "0"/"1", not as strings "True"/"False".

  • "button":
    • "ex0": bool: default for Enter key
  • "edit", "memo":
    • "ex0": bool: read-only
    • "ex1": bool: font is monospaced
    • "ex2": bool: show border
  • "spinedit":
    • "ex0": int: min value
    • "ex1": int: max value
    • "ex2": int: increment
  • "label":
    • "ex0": bool: right aligned
  • "linklabel":
    • "ex0": str: URL. Should not have ",". Clicking on http:/mailto: URLs should work, result of clicking on other kinds depends on OS.
  • "listview":
    • "ex0": bool: show grid lines
  • "radiogroup":
    • "ex0": int: 0: arrange items horizontally then vertically (default); 1: opposite
  • "tabs", "pages":
    • "ex0": int: 0: tab position on top, 1: on bottom, 2: on left, 3: on right
  • "colorpanel":
    • "ex0": int: border width (from 0)
    • "ex1": int: color of fill
    • "ex2": int: color of font
    • "ex3": int: color of border
  • "filter_listview":
    • "ex0": bool: filter works for all columns
  • "image":
    • "ex0": bool: center picture
    • "ex1": bool: stretch picture
    • "ex2": bool: allow stretch in
    • "ex3": bool: allow stretch out
    • "ex4": bool: keep origin x, when big picture clipped
    • "ex5": bool: keep origin y, when big picture clipped
  • "trackbar":
    • "ex0": int: orientation (0: horz, 1: vert)
    • "ex1": int: min value
    • "ex2": int: max value
    • "ex3": int: line size
    • "ex4": int: page size
    • "ex5": bool: reversed
    • "ex6": int: tick marks position (0: bottom-right, 1: top-left, 2: both)
    • "ex7": int: tick style (0: none, 1: auto, 2: manual)
  • "progressbar":
    • "ex0": int: orientation (0: horz, 1: vert, 2: right-to-left, 3: top-down)
    • "ex1": int: min value
    • "ex2": int: max value
    • "ex3": bool: smooth bar
    • "ex4": int: step
    • "ex5": int: style (0: normal, 1: marquee)
    • "ex6": bool: show text (only for some OSes)
  • "progressbar_ex":
    • "ex0": int: style (0: text only, 1: horz bar, 2: vert bar, 3: pie, 4: needle, 5: half-pie)
    • "ex1": int: min value
    • "ex2": int: max value
    • "ex3": bool: show text
    • "ex4": int: color of background
    • "ex5": int: color of foreground
    • "ex6": int: color of border
  • "bevel":
    • "ex0": int: shape (0: sunken panel, 1: 4 separate lines - use it as border for group of controls, 2: top line, 3: bottom line, 4: left line, 5: right line, 6: no lines, empty space)
  • "splitter":
    • "ex0": bool: paint border
    • "ex1": bool: on mouse drag, use instant repainting (else splitter paints after mouse released)
    • "ex2": bool: auto jump to edge, when size of linked control becomes < min size
    • "ex3": int: minimal size of linked control (controlled by splitter)

dlg_custom - Return value

Dialog is closed by clicking any button or by changing of any control which has "act=1".

  • If cancelled, returns None
  • If get_dict=True, returns dict: {0: str_value_0, 1: str_value_1, ..., 'clicked': N, 'focused': N}
  • If get_dict=False, returns 2-tuple: (clicked_index, state_text)
    • "clicked_index": index of control which closed dialog (0-based).
    • "state_text": "\n"-separated values of controls. Same count of items as in text, plus optional additional lines in the form "key=value". Line "focused=N" with index of last focused control (0-based) or -1.

dlg_custom - Notes

  • Property "type" must be first.
  • Property "act" must be set after "val".
  • Controls sizes differ on Win/Linux/OSX, picture shows controls (Linux/Win) auto-aligned, not in CudaText, only example app:

controls autosizes.png

  • So it's good to use common height for single-line controls, 30 pixels is ok for edit/button/check/radio, 36 for combobox.
  • Control "tabs" height cannot auto-size, please make correct height for control (it is usually like big buttons).

dlg_proc

dlg_proc(id_dialog, id_action, prop="", index=-1, index2=-1, name="")

Advanced work with dialogs (forms). More advanced than "dlg_custom", forms can show in modal/nonmodal way, controls can change their value during form showing.

Often the function works with some control. To pass some control here, use one of 2 methods:

  • Set param "name" to control's name. You give name to a control when you create this control. Param "name" is used if it's not empty.
  • Set param "index" to control's index. You get index of newly created control from dlg_proc call. You can find the index from name, using DLG_CTL_FIND action. Param "index" is used if it's >=0 and param "name" is empty.

dlg_proc - Types of controls

Possible types of UI controls are described in "dlg_custom" topic. Additional types, supported only by "dlg_proc":

  • "button_ex": button, application-themed, works via button_proc()
  • "editor": full-featured multi-line editor, accessible via Editor API
  • "editor_edit": one-line variant of "editor"
  • "editor_combo": one-line variant of "editor", with drop-down arrow
  • "listbox_ex": listbox, application-themed, works via listbox_proc()
  • "paintbox": control which must be painted by plugin via canvas_proc()
  • "statusbar": statusbar: panel with one horizontal row of cells, works via statusbar_proc()
  • "toolbar": toolbar: panel which holds buttons with icons, works via toolbar_proc()
  • "treeview": tree structure with nodes and nested nodes, works via tree_proc()

dlg_proc - Forms properties

  • "cap": str: Caption of form.
  • "x", "y": int: Position (screen coordinates), left/top.
  • "w", "h": int: Size, width/height.
  • "w_min", "w_max": int: Constraints for width, min/max value.
  • "h_min", "h_max": int: Constraints for height, min/max value.
  • "p": int: Handle of parent form, or 0 if no parent.
  • "tag": str: Any string, set by plugin.
  • "border": int: Border-style of form, one of DBORDER_nnn constants.
    • DBORDER_NONE: No visible border, not resizable
    • DBORDER_SIZE: Standard resizable border (on Windows: with Minimize/Maximize buttons)
    • DBORDER_SINGLE: Single-line border, not resizable (on Windows: form has icon and Minimize button)
    • DBORDER_DIALOG: Standard dialog box border, not resizable (on Windows: form has no icon nor Minimize button)
    • DBORDER_TOOL: Like DBORDER_SINGLE but with a smaller caption
    • DBORDER_TOOLSIZE: Like DBORDER_SIZE but with a smaller caption
  • "vis": bool: Visible state.
  • "color": int: Background color.
  • "autosize": bool: Form automatically resizes to the minimal size, which shows all visible controls.
  • "keypreview": bool: If on, then key press calls on_key_down before passing key to focused control. Should be True if form needs to handle on_key_down.
  • "p": int: Parent handle. Set this property to int handle of any windowed UI control or form, this control/form will be parent of form.
  • "focused" (only for reading): index of currently focused control.
  • "form_state" (only for reading): current form state, string: "norm" for normal, "min" for minimized, "max" for maximized, "fullscr" for full-screen.
  • "topmost": bool: Makes form stay on top of other forms in CudaText.
  • "taskbar": int enum: When form appears on OS taskbar.
    • 0: Application default behaviour
    • 1: Always
    • 2: Never

dlg_proc - Forms events

These are also properties of forms.

  • "on_resize": Called after form is resized.
  • "on_close": Called after form is closed.
  • "on_close_query": Called to ask plugin, is it allowed to close form (in any way: pressing Esc key, clicking X icon, pressing Alt+F4 or similar hotkey). Plugin must return bool, if True then form will be closed.
  • "on_show": Called after form shows.
  • "on_hide": Called after form hides.
  • "on_act": Called after form is activated (gets focus).
  • "on_deact": Called after form is deactivated (lost focus).
  • "on_mouse_enter": Called when mouse cursor enters form area.
  • "on_mouse_exit": Called when mouse cursor leaves form area.
  • "on_form_state": Called after form is minimized/maximized/restored.
    • param "data": Current form state, string value like in the property "form_state".
  • "on_key_down": Called when key is pressed in form (form should have "keypreview":True). If plugin returns False, key is blocked.
    • param "id_ctl": int key code.
    • param "data": key-state string: few chars, "c" for Ctrl, "a" for Alt, "s" for Shift, "m" for Meta.
  • "on_key_up": Called when key is depressed (after "on_key_down"). If plugin returns False, depressing of key is blocked.
  • "on_key_press": Called when character-key is pressed (additional to "on_key_down"). If plugin returns False, pressing of key is blocked.
    • param "id_ctl": int character code.
    • param "data": key-state string, like in "on_key_down".

How to get nice key description in "on_key_down", e.g. "Ctrl+Alt+Esc" from id_ctl=27 and data="ca":

    str_key =\
      ('Meta+' if 'm' in data else '')+\
      ('Ctrl+' if 'c' in data else '')+\
      ('Alt+' if 'a' in data else '')+\
      ('Shift+' if 's' in data else '')+\
      app_proc(PROC_HOTKEY_INT_TO_STR, id_ctl)

dlg_proc - Control properties

  • "name": str: Optional name of control, to find control later by name. May be not unique for controls.
  • "cap": str: Caption.
  • "act": bool: Active state. For many controls (edit, check, radio, combo_ro, checkbutton, listbox'es, listview's, tabs), it means that control's value change fires events (for dlg_proc) or closes form (for dlg_custom).
  • "x", "y": int: Position (coordinates relative to dialog), left/top.
  • "w", "h": int: Size, width/height.
  • "en": bool: Enabled state.
  • "vis": bool: Visible state.
  • "color": int: Color.
  • "border": bool: Control has border.
  • "font_name": str: Font name.
  • "font_size": int: Font size.
  • "font_color": int: Font color.
  • "hint": str: Hint (tooltip) for mouse-over. Newlines must be "\r".
  • "ex0"..."ex9": Advanced control-specific props. Described in dlg_custom.
  • "items": str: Usually tab-separated items. Described in dlg_custom.
  • "val": str: Value of control. Described in dlg_custom.
  • "tag": str: Any string, set by plugin.
  • "focused": bool: Shows if control has focus.
  • "tab_stop": bool: Allows tab-key to jump to this control.
  • "tab_order": int: Tab-key jumps to controls using tab_orders. First activated is control with tab_order=0, next with =1, etc. If tab_orders not set, controls activated by creation order.
  • "sp_l", "sp_r", "sp_t", "sp_b", "sp_a": int: Border spacing, ie padding of control's edge from anchored controls (or parent form). 5 props here: left, right, top, bottom, around. "Around" padding is added to padding of all 4 sides.
  • "a_l", "a_r", "a_t", "a_b": 2-tuple (str_control_name, str_side): Anchors of control. See #dlg_proc_-_Anchors. Value is 2-tuple, or None to disable anchor.
    • Item-0: name of target control, or empty str to use control's parent (it is form by default).
    • Item-1: side of target control, one of 3 values: "[" (left/top), "-" (center), "]" (right/bottom).
  • "align": alignment of control:
    • ALIGN_NONE: no alignment (props "x", "y", "w", "h" have meaning)
    • ALIGN_CLIENT: stretched to entire parent area (props "x", "y", "w", "h" are ignored)
    • ALIGN_LEFT: glued to the left side of parent (only prop "w" has meaning)
    • ALIGN_RIGHT: glued to the right side of parent (only prop "w" has meaning)
    • ALIGN_TOP: glued to the top of parent (only prop "h" has meaning)
    • ALIGN_BOTTOM: glued to the bottom of parent (only prop "h" has meaning)
  • "p": str: Name of control's parent control, or empty if the form is used as a parent. Coordinates x/y of a control are relative to the current parent, so control is attached to its parent. For example, you can place several controls on a "panel" control (panel can have hidden border), then change this panel's coordinates to visually move all child controls. Special case: to place control on PageControl's page with index N, specify such parent: pages_name+"."+str(N).

Special properties for control "listview":

  • "imagelist_small": int: handle of ImageList with small icons. This ImageList is used in usual "report" mode of listview.
  • "imagelist_large": int: handle of ImageList with large icons. This ImageList is used in "big icons" mode of listview.
  • "imageindexes": str: string with '\t'-separated numbers. Each number is icon index, or -1 if icon is not used.

Special properties for controls "tabs", "pages", "toolbar", "statusbar":

  • "tab_hovered": int: index of tab/cell under mouse cursor. Property is missed if no such tab/cell.

dlg_proc - Control events - general

General events for all controls:

  • "on_change": Called after "value" of control is changed. For buttons, "on_change" is called on button click, instead of "on_click".
  • "on_click": Called after mouse click on control, for non-active controls, which don't change "value" by click. Param "data" is tuple (x, y) with control-related coordinates of click.
  • "on_click_dbl": Called after mouse double-click on control. Param "data" is tuple (x, y) with control-related coordinates.
  • "on_mouse_down": Called when mouse button pressed. Param "data" is dict: { "btn": int_button_code, "state": str_keyboard_state, "x": int, "y": int }. Button code: 0: left; 1: right; 2: middle. Keyboard state: value like in global event "on_key".
  • "on_mouse_up": Called when mouse button depressed (released). Param "data": like in "on_mouse_down".
  • "on_mouse_enter": Called when mouse cursor enters control area.
  • "on_mouse_exit": Called when mouse cursor leaves control area.
  • "on_focus_enter": Called when control gets focus. Not supported for controls (they don't have OS window handle): label, button, button_ex, panel, linklabel, colorpanel, bevel, image, progressbar_ex, paintbox, statusbar.
  • "on_focus_exit": Called when control looses focus. Supported for the same controls as "on_focus_enter".
  • "on_menu": Called before showing context menu, after right click or ContextMenu hotkey. Param "data": like in "on_mouse_down". Method can return False to disable default menu (if any).

dlg_proc - Control events - for specific controls

Special events for controls "listview", "checklistview":

  • "on_click_header": Called when user clicks on column header. Param "data": int column index.
  • "on_select": Called after selection is changed. Param "data" is tuple: (int_item_index, bool_item_selected).

Special events for control "listbox_ex":

  • "on_click_x": Called when listbox has X marks shown and X mark is clicked.
  • "on_click_header": Called when listbox shows a header, and header is clicked. Param "data": int column index.
  • "on_draw_item": Called if listbox is owner-drawn. Param "data" is dict: { "canvas": canvas_id, "index": int_item_index, "rect": item_rectangle_4_tuple }.

Special events for control "treeview":

  • "on_fold", "on_unfold": Called before treeview node is folded/unfolded. Param "data" is int handle of treeview node.
  • "on_select": Called after selection is changed.

dlg_proc - Control events - for editor control

Special events for control "editor"/"editor_edit"/"editor_combo":

  • "on_change": Called after text is changed.
  • "on_caret": Called after caret position and/or selection is changed.
  • "on_scroll": Called after editor is scrolled.
  • "on_key_down": Called when user presses a key. Param "data" is tuple (int_key_code, str_key_state). Method can return False to disable default processing.
  • "on_key_up": Called when user depresses a key. Param "data" is tuple (int_key_code, str_key_state). Method can return False to disable default processing.
  • "on_click_gutter": Called on mouse click on gutter area. Param "data" is dict: {"state": str_key_state, "line": int_line_index, "band": int_gutterband_index}.
  • "on_click_gap": Called on mouse click on inter-line gap. Param "data" is dict: {"state": str_key_state, "line": int, "tag": int, "gap_w": int, "gap_h": int, "x": int, "y": int}.
  • "on_click_link": Called on mouse click (single or double, depends on settings) over hyperlink (hyperlinks are defined via PROP_LINKS_SHOW, PROP_LINKS_REGEX). Param "data" is str.
  • "on_paste": Called before doing one of Paste commands. Param "data" is dict: {"keep_caret": bool, "sel_then": bool}. Method can return False to disable default operation.

dlg_proc - Signatures of event callbacks

Callbacks must be in forms shown in the topic #Callback_parameter. Callbacks can be functions (out of class) or class methods, it depends on the look of the callback (again see "Callback parameter" topic).

# for functions
def my_callback(id_dlg, id_ctl, data='', info=''):
  pass

# for class methods
class Command:
  def my_callback(self, id_dlg, id_ctl, data='', info=''):
    pass

Parameters:

  • "id_dlg": Int, handle of the form.
  • "id_ctl": Int, index of the control which fired the event. Note: for event "on_key_down" it has different meaning.
  • "data" and "info": Values specific to event. If these parameters are used, they are described in the event descriptioon.

dlg_proc - Actions

Param "prop": it can be of any simple type (str, int, bool), also tuple/list (of any simple type), also dict (keys: str, values: simple type or tuple/list). Most used is dict. Example: prop={"cap": "...", "x": 10, "y": 10, "w": 600, "en": False}.

Param "id_dialog": int, form handle. Ignored only for DLG_CREATE action (pass 0 with it).

Possible values of "id_action":

  • DLG_CREATE: Creates new empty form, returns form "handle". You must pass this handle (int) to next calls of dlg_proc().
  • DLG_HIDE: Hides form.
  • DLG_FREE: Hides and deletes form.
  • DLG_SHOW_MODAL: Shows form in modal mode. Waits for form to hide, then returns.
  • DLG_SHOW_NONMODAL: Shows form in non-modal mode. Returns immediately.
  • DLG_FOCUS: Focuses form (in non-modal mode).
  • DLG_SCALE: Scales form, with all controls, for the current OS high-DPI value. E.g. of OS scale is 150%, all will be scaled by 1.5.
  • DLG_TO_FRONT: Puts form to the foreground (in Z-order of forms).
  • DLG_PROP_GET: Returns form props, as dict. See example plugin, which props are returned.
  • DLG_PROP_SET: Sets form props, from dict. Param "prop" is dict. Only props mentioned in "prop" are applied, other props don't change.
  • DLG_DOCK: Docks (inserts) form into another form. Param "index" is handle of another form, and 0 means main CudaText form. Param "prop" can be: "L", "R", "T", "B" for sides left/right/top/bottom (default is bottom).
  • DLG_UNDOCK: Undocks form from it's current parent form.
  • DLG_LOCK: Disables updating of the form. This can be used before adding many controls at once, to remove flickering of these controls.
  • DLG_UNLOCK: Enables updating of the form. This must be used in pair with DLG_LOCK.
  • DLG_CTL_COUNT: Returns count of controls on form.
  • DLG_CTL_ADD: Adds new control to form, returns its index, or None if cannot add. Param "prop" is type of control. See description in dlg_custom.
  • DLG_CTL_PROP_GET: Returns control props, as dict. Control must be specified by name or index.
  • DLG_CTL_PROP_SET: Sets control props. Control must be specified by name or index. Param "prop" is dict with props. Only props mentioned in "prop" are applied, other props don't change. To "reset" some props, you must mention them with some value.
  • DLG_CTL_FOCUS: Focuses control. Control must be specified by name or index.
  • DLG_CTL_DELETE: Deletes control. Control must be specified by name or index. Controls are stored in list, so after a control deleted, indexes of next controls shift by -1. So don't use fixed indexes if you delete some, use DLG_CTL_FIND.
  • DLG_CTL_DELETE_ALL: Deletes all controls.
  • DLG_CTL_FIND: Returns index of control by name, or -1 if cannot find. Param "prop" is name.
  • DLG_CTL_HANDLE: Returns int "handle" of control on a form. Control must be specified by name or index. This handle is currently useful for types:
    • type "button_ex": pass handle to button_proc()
    • types "editor"/"editor_edit"/"editor_combo": pass handle to Editor() constructor
    • type "listbox_ex": pass handle to listbox_proc()
    • type "paintbox": pass handle to canvas_proc()
    • type "statusbar": pass handle to statusbar_proc()
    • type "treeview": pass handle to tree_proc()
    • type "toolbar": pass handle to toolbar_proc()
  • DLG_CTL_TO_FRONT: Puts control to the foreground (in Z-order of controls).
  • DLG_CTL_TO_BACK: Puts control to the background (in Z-order of controls).
  • DLG_COORD_LOCAL_TO_SCREEN: Converts x/y coordinates from form-related, to screen-related. Param "index" is x, "index2" is y. Returns tuple (x,y).
  • DLG_COORD_SCREEN_TO_LOCAL: Converts x/y coordinates from screen-related, to form-related. Param "index" is x, "index2" is y. Returns tuple (x,y).
  • DLG_POS_GET_STR: Returns form position/size as string.
  • DLG_POS_SET_FROM_STR: Sets form position/size from string. Param "prop" is string value.
    • It is faster than setting form properties "x", "y", "w", "h", it makes single resize.
    • String format is the same as in DLG_POS_GET_STR, comma-separated numbers "x,y,w,h", any number can be skipped to keep old value.

dlg_proc - Anchors

Anchor is attaching of control's side to another control, or to the parent form, so control is auto positioned, initially and on form resize. Lazarus IDE has such Anchor Editor dialog:

Anchor Editor en.png

In this dialog you see, that all 4 sides of control attach to one of 3 sides of another control (or parent form).

  • Anchors override absolute positions, e.g. anchor of left side overrides prop "x".
  • Anchoring to invisible control is allowed.
  • Anchoring circles (A to B to C to A) is not allowed, but should not give errors.

To change anchors of control, set its properties: a_l, a_r, a_t, a_b. Initially left/top anchors are set (to the parent form).

Side value "[" aligns control to left/top side of target:

         +--------+
         | target |
         +--------+
 
         +--------------+
         |   control    |
         +--------------+

Side value "]" aligns control to right/bottom side of target:

          +--------+
          | target |
          +--------+
 
    +--------------+
    |   control    |
    +--------------+

Side value "-" centers control relative to target:

          +--------+
          | target |
          +--------+
 
       +--------------+
       |   control    |
       +--------------+

Useful information in the Lazarus wiki: Anchor_Docking#Why_use_Anchors_instead_of_Align.3F.

Example: to attach "colorpanel" to the right side of form, clear left anchor (set to None), and add right/bottom anchors. This also sets spacing-aroung (padding) to 6 pixels.

  #attach colorpanel to the right
  dlg_proc(id_form, DLG_CTL_PROP_SET, index=n, prop=
      { 'a_l': None, 'a_r': ('', ']'), 'a_b': ('', ']'), 'sp_a': 6  } )

dlg_proc - Example

Detailed demo plugin exists, it shows many dlg_proc actions, shows modal/nonmodal forms, uses callbacks, moves control by button click, moves control on form resize. It is in the CudaText repo with name "cuda_testing_dlg_proc".

dlg_commands

dlg_commands(options, title="", w=0, h=0)

Show commands dialog, which is customizable version of Commands (F1) dialog in CudaText.

Param "options" should be 0 or sum of int flags:

  • COMMANDS_USUAL: Show usual commands, which have int codes. Function returns "c:"+str(int_command) for them.
  • COMMANDS_PLUGINS: Show plugins commands. Function returns "p:"+callback_string for them.
  • COMMANDS_LEXERS: Show lexers pseudo-commands. Function returns "l:"+lexer_name for them.
  • COMMANDS_FILES: Show opened files pseudo-commands. Function returns "f:"+file_name for them.
  • COMMANDS_RECENTS: Show recent files pseudo-commands. Function returns "r:"+file_name for them.
  • COMMANDS_CONFIG: Allow to call Configure Hotkeys dialog by F9 key.
  • COMMANDS_CONFIG_LEXER: Enable checkbox "For current lexer" when dialog to configure hotkey is called.
  • COMMANDS_CENTERED: Set dialog position to the center of desktop. Otherwise, position depends on CudaText option.

Params "w" and "h": if values>0, they are width and height of dialog.

Returns string if command selected, or None if cancelled.

file_open

file_open(filename, group=-1, options="")
file_open((filename1, filename2), group=-1, options="")

Opens editor tab with given filename. If filename already opened, activates its tab.

First parameter can be 2-tuple / 2-list of string, to open 2 files in a single tab, in a splitted view. In this case, second filename won't be handled specially for zip file, picture file, binary file etc.

The case of empty filename: opens empty untitled tab. The case of empty filename1 and non-empty filename2 is not supported: it also opens empty untitled tab, not splitted.

Returns bool. True, if first filename is empty. Otherwise, returns True if first filename exists, and second filename is empty or exists. For zip file (only first filename is checked for it), returns True only if zip file contains valid CudaText add-on, and it was installed.

  • Param "group": index of tab-group, currently 0...8 (6 normal groups + 3 floating groups). Default means "current group". If you pass index of currently hidden group, group won't show, you need to call editor command to show it, see #cmd.
  • Param "options": string:
    • If it has "/preview", then file opens in a "temporary preview" tab, with italic caption. Param "group" is ignored then, used 1st group.
    • If it has "/nohistory", file's saved history (caret, scroll pos, etc) won't be used.
    • If it has "/noloadundo", file's persistent-undo (additional file created by using option "undo_persistent") won't be loaded.
    • If it has "/nolexerdetect", lexer won't be auto-detected.
    • If it has "/noevent", then "on_open_pre" event won't fire.
    • If it has "/noopenedevent", then "on_open" event won't fire.
    • If it has "/nononeevent", then "on_open_none" event won't fire.
    • If it has "/silent", then zipped add-on will install w/o prompt and report.
    • If it has "/passive", then tab will not activate, it will be passive tab.
    • If it has "/nonear", then app option "ui_tab_new_near_current" will be ignored, tab will be appended to the end.
    • If it has "/donear", then app option "ui_tab_new_near_current" will be ignored, tab will be opened near the active one.
    • If it has "/nozip", then .zip files will not be handled specially.
    • If it has "/nopictures", then picture files will not be handled specially.
    • If it has "/noupdateaddons", then after installing add-ons from .zip file(s), Plugins menu will not be reloaded / lexer library will not be reloaded.
    • If it has "/view-text', then file will open in internal viewer, text (variable width) mode.
    • If it has "/view-binary', then file will open in internal viewer, binary (fixed width) mode.
    • If it has "/view-hex', then file will open in internal viewer, hex mode.
    • If it has "/view-unicode', then file will open in internal viewer, unicode (variable width) mode.
    • If it has "/nontext-view-text", then in the case of non-text file, file will open in internal viewer, text (variable width) mode.
    • If it has "/nontext-view-binary", then in the case of non-text file, file will open in internal viewer, binary (fixed width) mode.
    • If it has "/nontext-view-hex", then in the case of non-text file, file will open in internal viewer, hex mode.
    • If it has "/nontext-view-unicode", then in the case of non-text file, file will open in internal viewer, unicode mode.
    • If it has "/nontext-view-uhex", then in the case of non-text file, file will open in internal viewer, unicode+hex mode.
    • If it has "/nontext-cancel", then in the case of non-text file, function will fail and return False.

Note: "ed" is always the current editor, after file_open() current editor changes, and "ed" is the new cur editor.

Example opens untitled tab, and writes multi-line text to it:

  file_open('')
  ed.set_text_all(text)

ed_handles

ed_handles()

Returns range object, which contains int handles of all editor UI-tabs. Pass each handle to Editor() to make editor object from handle.

Example which shows filenames of all tabs:

    for h in ed_handles():
        e = Editor(h)
        print(e.get_filename())

Note: resulting int handles are virtual (small int numbers, not memory addresses). To get unique handle which is memory address of an editor, use PROP_HANDLE_SELF:

    for h in ed_handles():
        e = Editor(h)
        print('Unique handle:', e.get_prop(PROP_HANDLE_SELF, ''))

ed_group

ed_group(index)

Returns Editor object for active editor in tab-group with given group-index. Returns None for incorrect index, or if no tabs in this group.

Index possible values: 0..5 (first 6 groups) and 6..8 (3 floating groups).

ini_read/ini_write

ini_read(filename, section, key, value)
ini_write(filename, section, key, value)

Reads/writes single string from/to .ini file. Params:

  • "filename": str: Path of file. Can be without path, this means that path of "settings" dir is used.
  • "section": str: Section of ini file.
  • "key": str: Key in section.
  • "value": str:
    • on read: default value which is returned if no such filename/section/key was found.
    • on write: value to write.

On read: returns string value. On write: returns None.

ini_proc

ini_proc(id, filename, section="", key="")

Performs action on .ini file. Filename can be without path, this means that path of "settings" dir is used.

Possible values of "id":

  • INI_GET_SECTIONS: Returns list of sections. Params "section", "key" ignored.
  • INI_GET_KEYS: Returns list of keys in given section. Param "key" ignored.
  • INI_DELETE_KEY: Deletes given key in given section.
  • INI_DELETE_SECTION: Deletes given section with all its keys. Param "key" ignored.

lexer_proc

lexer_proc(id, value)

Perform some lexer-related action.

Possible values of "id":

  • LEXER_GET_LEXERS: Returns list of lexers. Param "value" must be bool: allow to include also hidden lexers (not visible in the lexers menu).
  • LEXER_GET_PROP: For lexer name (param "value"), returns lexer general properties, as dict. Supported for "lite" lexers too (lexer name must end with ^ suffix). For incorrect lexer name, returns None. Keys of dict:
    • "en": bool: lexer is visible in the lexers menu.
    • "typ": list of str: list of file-types (they detect lexer when file loads; "ext" is simple extension, "ext1.ext2" is double extension, "/fullname" is name w/o path).
    • "st": list of str: list of all styles.
    • "st_c": list of str: list of styles of syntax comments (e.g. used by Spell Checker).
    • "st_s": list of str: list of styles of syntax strings (e.g. used by Spell Checker).
    • "sub": list of str: list of sub-lexers (some items can be empty if lexer setup broken).
    • "kinds": list of str: list of token kind names. (This list has strings which lexer author had assigned in lexer properties, it has nothing common with "syntax elements" search.)
    • "c_line": str or None: line comment (until end-of-line).
    • "c_str": 2-tuple or None: stream comment (for any range).
    • "c_lined": 2-tuple or None: comment for full lines.
  • LEXER_GET_STYLES: For lexer name (param "value"), returns lexer styles properties, as dict. This works even if CudaText lexer themes are disabled (option "ui_lexer_themes": false). Not supported for "lite" lexers. Dict keys:
    • "type": Kind of style. Enum. 0: reserved value, 1: colors and font styles, 2: colors only, 3: background color only.
    • "color_font": RGB color of font.
    • "color_back": RGB color of background. Can be COLOR_NONE if not used.
    • "color_border": RGB color of border.
    • "border_left", "border_right", "border_top", "border_bottom": Kind of border at one side. Enum. Values from 0: none, solid, dash, dot, dash dot, dash dot dot, solid2, solid3, wave, double.
    • "styles": Font styles, as string. If empty, no styles. If "b" in value, bold. If "i" in value, italic. If "u" in value, underline. If "s" in value, strikeout.
    • "tkind": Kind of syntax element. "c" - comment, "s" - string, "a" - any other.
  • LEXER_DETECT: Detects lexer name by file name (param "value" is file name). Returns None if cannot detect. Returns string or tuple of string (for example, "C" and "C++" for "test.h"). Function tests file extension, or even filename before extension (e.g. "/path/makefile.gcc" gives "Makefile").
  • LEXER_REREAD_LIB: Re-reads lexer library from disk, updates lexer menu. Make sure that plugins' dialogs don't use editor with lexer, which may crash.
  • LEXER_ADD_VIRTUAL: Adds virtual lexer, which doesn't have a file and doesn't highlight text, it's only an item in lexers list. The purpose of virtual lexers is to avoid creating lexer files, but allow plugins to be activated by some lexer name / some file types. Param "value" must be tuple of string: (lexer_name, file_types, line_comment, range_comment_begin, range_comment_end). Item file_types here must have the same notation as for "lite" lexers, e.g. "*.pas;*.pp;*.lpr". Virtual lexers are added to the "lite" lexers list, and show the same suffix in lexer menu. To activate such a lexer, call Editor.set_prop(PROP_LEXER_FILE, lexer_name+suffix). Action returns bool: lexer_name didn't exist, lexer was added.

tree_proc

tree_proc(id_tree, id_action, id_item=0, index=0, text="", image_index=-1, data="")

Perform action on treeview UI-control.

  • Param "id_tree": int handle of treeview.
  • Param "id_item": int handle of tree-item. Can be 0 for invisible root-item:
    • can clear entire tree using root-item
    • can enumerate root level using root-item.

Possible values of "id_action":

  • TREE_ITEM_ENUM: Enumerates subitems of given item. Params: "id_item". Returns list of 2-tuples, or None.
    • tuple item 0: int: handle of item.
    • tuple item 1: string: caption of item.
  • TREE_ITEM_ENUM_EX: Enumerates subitems of given item. Params: "id_item". Returns list of dict, or None. Dict keys are:
    • "id": int: handle of item.
    • "text": str: caption of item
    • "data": str: data string of item.
    • "img": int: icon index of item, or -1 if icon not used.
    • "sub_items": bool: item has the sub-items.
  • TREE_ITEM_ADD: Adds subitem as item's child. Returns int handle of subitem.
    • Param "id_item": handle of item.
    • Param "index": at which subitem index to insert (0-based), or -1 to append.
    • Param "text": caption of item.
    • Param "image_index": index in tree's icon list or -1 to not show icon.
    • Param "data": optional data string attached to item.
  • TREE_ITEM_DELETE: Deletes item (with all subitems). Params: "id_item".
  • TREE_ITEM_SET_TEXT: Sets item's text. Params: "id_item", "text".
  • TREE_ITEM_SET_ICON: Sets item's icon. Params: "id_item", "image_index".
  • TREE_ITEM_SELECT: Selects the item specified by "id_item". If "id_item" is 0, it removes the selection.
  • TREE_ITEM_SHOW: Makes item visible, ie scrolls control to this item.
  • TREE_ITEM_GET_SELECTED: Returns int handle of selected item (param "id_item" is ignored). Returns None if nothing is selected.
  • TREE_ITEM_GET_PROPS: Returns properties of item, as dict. Dict keys are:
    • "text": str: caption of item
    • "data": str: data string of item
    • "icon": int: index of icon in tree's imagelist object, or -1 for none
    • "level": int: how deep this item is nested (how many parents this item has)
    • "parent": int: id of parent item, or 0 if no parent
    • "folded": bool: is this item folded (item itself, not parents)
    • "selected": bool: is this item selected
    • "sub_items": bool: item has sub-items
    • "index": int: index of item, relative to its branch
    • "index_abs": int: absolute index of item, relative to root
  • TREE_ITEM_FOLD: Folds item w/o subitems.
  • TREE_ITEM_FOLD_DEEP: Folds item with subitems. Root-item allowed too.
  • TREE_ITEM_FOLD_LEVEL: Folds all items (id_item ignored) from level with specified index, 1 or bigger. (This is what CudaText commands "fold level N" do for code-tree).
  • TREE_ITEM_UNFOLD: Unfolds item w/o subitems.
  • TREE_ITEM_UNFOLD_DEEP: Unfolds item with subitems. Root-item allowed too.
  • TREE_GET_MULSELECT: Returns string, which shows multi-selection options.
    • String "-": Multi-selection is disabled
    • Empty string or several "option chars": multi-selection is enabled. "Option chars" are:
      • "c": Enable Ctrl+click to select/deselect single node
      • "s": Enable Shift+click to select range of nodes
      • "v": Multi-selection has only visible nodes
      • "i": Multi-selection has only sibling nodes
  • TREE_SET_MULSELECT: Sets multi-selection options. Param "text" must be one of possible values described in TREE_GET_MULSELECT.
  • TREE_GET_SELECTIONS: Returns list of selected tree nodes, one handle per each selected node. When multi-selection is disabled, result is empty list or list with single item.
  • TREE_FIND_FOR_TEXT_POS: For the treeview, filled with code-tree information (it can be plugin-created treeview), finds the tree-item corresponding to given text position. Param "id_item" is ignored, param "text" must be 2-tuple of int (column, line). Returns handle of tree-item. Returns None if "text" doesn't contain valid text position. Returns 0 if tree-item is not found.
  • TREE_GET_IMAGELIST: Returns handle of imagelist object, int value.
  • TREE_SET_IMAGELIST: Sets handle of imagelist object. Param "text" must be int handle, it can be 0 to remove current imagelist.
  • TREE_PROP_SHOW_ROOT: Allows to change "show root-item" property. When root-item is hidden, treeview (folded) looks like a listbox. Param "text" must be bool value.
  • TREE_LOCK: Disables repainting of control.
  • TREE_UNLOCK: Enables repainting of control.
  • TREE_THEME: Applies current color theme to control.
  • TREE_ITEM_GET_RANGE: Should be used only for code-tree. Returns range, stored in tree-item, as 4-tuple (start_x, start_y, end_x, end_y). If range is not set, returns (-1,-1,-1,-1).
  • TREE_ITEM_SET_RANGE: Should be used only for code-tree. Sets range for tree-item. Param "text" must be 4-tuple of int (start_x, start_y, end_x, end_y).

Example of fast treeview filling, with locking to prevert treeview repaints:

    tree_proc(h_tree, TREE_LOCK)

    for i in range(5000):
        tree_proc(h_tree, TREE_ITEM_ADD, index=-1, text='text')

    tree_proc(h_tree, TREE_UNLOCK)

Example of getting code-tree text range for some code-tree node. The following is the Console input commands and their outputs. Comments "### ..." are inserted by hands later.

### Step 1 - get handle of code-tree.

>>> ct=app_proc(PROC_GET_CODETREE,'')
>>> ct
140556715678064

### Step 2 - enumerate code-tree root level.

>>> =tree_proc(ct, TREE_ITEM_ENUM_EX, id_item=0)
[{'id': 140556582911424, 'text': 'log', 'data': '', 'img': 5, 'sub_items': False},
{'id': 140556582911904, 'text': 'Command', 'data': '', 'img': 1, 'sub_items': True}]

### Step 3 - enumerate sub-items of 'Command' node.
### We got last node with 'text'=='Command' and 'sub_items':True.
### Copy its id and pass it to param "id_item".

>>> =tree_proc(ct, TREE_ITEM_ENUM_EX, id_item=140556582911904)
[{'id': 140556582912064, 'text': '__init__', 'data': '', 'img': 5, 'sub_items': False},
{'id': 140556582913344, 'text': 'on_focus', 'data': '', 'img': 5, 'sub_items': False},
{'id': 140556582913504, 'text': 'work', 'data': '', 'img': 5, 'sub_items': False}]

### Step 4 - get text range of node.
### Copy id of some item and get its text range (x1, y1, x2, y2).

>>> =tree_proc(ct, TREE_ITEM_GET_RANGE, id_item=140556582913504)
(4, 102, 21, 180)

listbox_proc

listbox_proc(id_listbox, id_action, index=0, text="", tag=0)

Perform action on listbox UI-control.

  • Param id_listbox: int handle of listbox.
  • Param index: index of item (0-base).

Possible values of "id_action":

  • LISTBOX_GET_COUNT: Returns number if items.
  • LISTBOX_ADD: Adds item with given text and tag. Returns new count of items. Param "index": index of new item, or -1 to append. Param "text": text of item. Param "tag": int tag.
  • LISTBOX_ADD_PROP: Adds item with given text and other properties. Returns new count of items. Param "index": index of new item, or -1 to append. Param "text": text of item. Param "tag": dict with keys "tag", "modified", "datatext".
  • LISTBOX_DELETE: Deletes item with given index.
  • LISTBOX_DELETE_ALL: Deletes all items.
  • LISTBOX_GET_ITEM: Returns text/tag of item with given index. Returns 2-tuple (text, tag) or None if index incorrect.
  • LISTBOX_SET_ITEM: Sets text/tag of item with given index. Params used: "index", "text", "tag".
  • LISTBOX_GET_ITEM_PROP: Returns properties of item with given index, as dict or None. Dict keys are: "text", "tag", "modified", "datatext".
  • LISTBOX_SET_ITEM_PROP: Sets properties of item with given index. Param "index": int value. Param "text": new text of item. Param "tag": dict with keys "tag", "modified", "datatext".
  • LISTBOX_GET_ITEM_H: Returns height of items in pixels.
  • LISTBOX_SET_ITEM_H: Sets height of items in pixels. Param "index": int value
  • LISTBOX_GET_SEL: Returns selected index. -1 for none.
  • LISTBOX_SET_SEL: Sets selected index. Param "index": int value
  • LISTBOX_GET_TOP: Returns index of top visible item.
  • LISTBOX_SET_TOP: Sets index of top visible item. Param "index": int value
  • LISTBOX_GET_DRAWN: Returns owner-drawn state (bool). Owner-drawn state means that listbox doesn't paint itself, but plugin must paint it via event "on_draw_item".
  • LISTBOX_SET_DRAWN: Sets owner-drawn state. Param "index": 0 or 1 (off/on).
  • LISTBOX_GET_SHOW_X: Returns state of X marks. Int value: 0: don't show, 1: show for all items, 2: show for mouse-over item.
  • LISTBOX_SET_SHOW_X: Sets state of X marks. Param "index": int value.
  • LISTBOX_GET_HOTTRACK: Returns HotTrack state (bool). HotTrack means that listbox highlights item under mouse cursor.
  • LISTBOX_SET_HOTTRACK: Sets HotTrack state. Param "index": 0 or 1 (off/on).
  • LISTBOX_GET_SCROLLSTYLE_HORZ: Returns style of horizontal scrollbar. One of SCROLLSTYLE_ constants.
  • LISTBOX_SET_SCROLLSTYLE_HORZ: Sets style of horizontal scrollbar. Param "index": int value, one of SCROLLSTYLE_ constants.
  • LISTBOX_GET_SCROLLSTYLE_VERT: Returns style of vertical scrollbar. One of SCROLLSTYLE_ constants.
  • LISTBOX_SET_SCROLLSTYLE_VERT: Sets style of vertical scrollbar. Param "index": int value, one of SCROLLSTYLE_ constants.
  • LISTBOX_GET_SCROLLPOS_HORZ: Returns horizontal scroll position.
  • LISTBOX_SET_SCROLLPOS_HORZ: Sets horizontal scroll position. Param "index": int value.
  • LISTBOX_GET_HEADER: Returns header string.
  • LISTBOX_SET_HEADER: Sets header string. It may contain "column separator char", see LISTBOX_SET_COLUMN_SEP.
  • LISTBOX_GET_HEADER_IMAGELIST: Returns int handle of header's image-list.
  • LISTBOX_SET_HEADER_IMAGELIST: Sets int handle of header's image-list.
  • LISTBOX_GET_HEADER_IMAGEINDEXES: Returns header's image-list indexes, as list of int.
  • LISTBOX_SET_HEADER_IMAGEINDEXES: Sets header's image-list indexes. Param "text": list of int. For example, [-1, 4, 6] means "show image=4 for column 1, and image=6 for column 2".

Listbox can have columns. It works only if listbox is not owner-drawn, and column sizes were set via LISTBOX_SET_COLUMNS. You must add separator-chars inside items to split items into columns. Column sizes are passed as list of int. Each list item can be:

  • value>0: Column width in pixels.
  • value<0: Column width in percents (percents of the entire listbox width, minus all fixed sizes).
  • value=0: Column is auto-stretched to fill the rest of the width. Several auto-stretched columns are allowed.

Actions for columns:

  • LISTBOX_GET_COLUMN_SEP: Returns column separator char.
  • LISTBOX_SET_COLUMN_SEP: Sets column separator char. Param "text" must be single-char string.
  • LISTBOX_GET_COLUMNS: Returns list of column sizes.
  • LISTBOX_SET_COLUMNS: Sets list of column sizes. Param "text" must be list of int. List items can be >0, <0, =0, see above.

Example adds 3 columns:

  listbox_proc(h_list, LISTBOX_SET_COLUMN_SEP, text='|')
  listbox_proc(h_list, LISTBOX_SET_COLUMNS, text=[-50,0,-20]) # width<0 means value in %
  listbox_proc(h_list, LISTBOX_ADD, index=-1, text='first|second|third')

canvas_proc

canvas_proc(id_canvas, id_action,
  text="", color=-1, size=-1,
  x=-1, y=-1, x2=-1, y2=-1,
  style=-1, p1=-1, p2=-1)

Performs action on canvas, ie drawing surface of some GUI control. Param "id_canvas" is handle of canvas of some GUI control. Special value 0 means testing empty panel, it appears at the top of app, when used.

Possible values of "id_action":

  • CANVAS_SET_FONT: Sets props of font. Params used:
    • "text": font name
    • "color"
    • "size"
    • "style": 0 for normal, or sum of values FONT_B (bold), FONT_I (italic), FONT_U (underline), FONT_S (strikeout)
  • CANVAS_SET_PEN: Sets props of pen. Params used:
    • "color"
    • "size"
    • "style": one of PEN_STYLE_nnnn
    • "p1": end caps style - one of PEN_CAPS_nnnn
    • "p2": line joining style - one of PEN_JOIN_nnnn
  • CANVAS_SET_BRUSH: Sets props of brush. Params used:
    • "color"
    • "style": one of BRUSH_nnnn. Usually used: BRUSH_SOLID (filled background), BRUSH_CLEAR (transparent background).
  • CANVAS_SET_ANTIALIAS: Sets anti-aliasing mode of canvas. Params used: "style" - ANTIALIAS_NONE, ANTIALIAS_ON, ANTIALIAS_OFF.
  • CANVAS_GET_TEXT_SIZE: Returns size of text on canvas, as 2-tuple (size_x, size_y). Uses font. Params used: "text".
  • CANVAS_TEXT: Paints text at given coords. Uses font and brush. Params used: "text", "x", "y".
  • CANVAS_LINE: Paints line at given coords. Uses pen. Params used: "x", "y", "x2", "y2".
  • CANVAS_PIXEL: Paints one pixel at given coords. Params used: "x", "y", "color".
  • CANVAS_RECT: Paints rectangle. Uses pen and brush. Params used: "x", "y", "x2", "y2".
  • CANVAS_RECT_FRAME: Paints rectangle. Uses only pen. Params used: "x", "y", "x2", "y2".
  • CANVAS_RECT_FILL: Paints rectangle. Uses only brush. Params used: "x", "y", "x2", "y2".
  • CANVAS_RECT_ROUND: Paints rounded rectangle. Uses pen and brush. Params used: "x", "y", "x2", "y2", "style" - radius of corners.
  • CANVAS_ELLIPSE: Paints ellipse or circle. Uses pen and brush. Params used: "x", "y", "x2", "y2".
  • CANVAS_POLYGON: Paints polygon from any number of points (>2). Uses pen and brush. Params used: "text" - comma separated list of (x,y) coords. Example: "10,10,200,50,10,100" - 3 points.
  • CANVAS_SET_TESTPANEL: Sets height of testing panel at the top. Params used: "size". If it's "too small" then panel hides; for big value, panel height is limited.

timer_proc

timer_proc(id, callback, interval, tag="")

Perform action on timers. Many different timers are allowed, they work at the same time, each unique callback makes new timer with its own interval. To stop some timer, you must specify the same callback as you did on starting that timer.

  • "callback": Callback which is called on timer tick, see below.
  • "interval": Timer delay in msec. For value<10, app will use 10. Specify it only on starting (ignored on stopping).
  • "tag": Some string, if not empty, it will be parameter to callback. If empty, callback is called without additional params.

Possible values of "id":

  • TIMER_START - Create and start timer, for infinite ticks. If timer for such callback is already created, then it's restated.
  • TIMER_START_ONE - Create and start timer, for single tick. If timer for such callback is already created, then it's restated.
  • TIMER_STOP - Stop timer (timer must be created before).
  • TIMER_DELETE - Stop timer, and delete it from list of timers. Usually don't use it, use only to save memory if created lot of timers.

Result is True if params are OK, False if params not OK (callback string incorrect, not created callback specified on stopping); or None (for unknown "id").

timer_proc - Callbacks

Callback param must be in one of these forms: #Callback_parameter.

Callbacks in timer_proc must be declared as:

#function
def my(tag='', info=''):
  pass
#method
class Command:
  def my(self, tag='', info=''):
    pass

menu_proc

menu_proc(id_menu, id_action, command="", caption="", index=-1, hotkey="", tag="")

Perform action on menu items.

menu_proc - Menu id

Value of "id_menu" can be:

  • number, str(number): all menu items can be specified by unique int value
  • "top": top menu
  • "top-file": top menu "File" submenu
  • "top-edit": top menu "Edit" submenu
  • "top-sel": top menu "Selection" submenu
  • "top-sr": top menu "Search" submenu
  • "top-view": top menu "View" submenu
  • "top-op": top menu "Options" submenu
  • "top-help": top menu "Help" submenu
  • "text": editor context menu
  • "tab": tab header context menu
  • "toolmenu:"+name: dropdown submenu of toolbar button

menu_proc - Command for new items

Value of "command" parameter for MENU_ADD can be:

  • int_command or str(int_command) - int command code, from module cudatext_cmd (pass 0 if item does nothing)
  • callback in one of these forms: #Callback_parameter.
  • (deprecated callback form) callback in the form "module,method" or "module,method,param" (param can be of any primitive type).
  • to create standard special sub-menus, special values:
    • "_recents": Recent-files submenu
    • "_plugins": Plugins submenu
    • "_oplugins": Settings-plugins submenu
  • empty string, if item will be used as submenu (item is a submenu, if any subitems are added to it)

menu_proc - Properties as dict

Some actions get dict for menu items. Note that some keys are optional, they are returned only when value is not the default (e.g. "vis" is returned only when visibility is off). Dict keys:

  • "id", int: menu id
  • "cap", str: caption; for separator items it is "-"
  • "cmd", int: command code (e.g. from module cudatext_cmd); for plugin menu items it can be 0 or -1
  • (optional) "hint", str: callback, used if "cmd" value <=0
  • (optional) "hotkey", str: keyboard hotkey
  • (optional) "tag", str: some plugin-defined data, if plugin set it
  • (optional) "en", bool: menu item is enabled
  • (optional) "vis", bool: menu item is visible
  • (optional) "checked", bool: menu item is checked
  • (optional) "radio", bool: menu item has rounded checkmark

menu_proc - Actions

Possible values of "id_action":

  • MENU_CLEAR: Removes all sub-items from menu item.
  • MENU_ENUM: Enumerates sub-items of the menu item. Returns list of dict, or None (for incorrect menu_id).
  • MENU_GET_PROP: Returns props of menu item, as dict.
  • MENU_ADD: Adds sub-item to menu item. Returns string, menu_id for newly added sub-item. Params:
    • "id_menu": Item in which you add sub-item.
    • "caption": Caption of item, or "-" for menu separator.
    • "index": Index (0-based) at which to insert sub-item. Default: append item to end.
    • "command": Values are described above.
    • "hotkey": String of hotkey (e.g. "Ctrl+Shift+A"). Hotkey combos are not allowed. It overrides hotkey, which is auto assigned from command code.
    • "tag": Any string stored in menu item.
  • MENU_REMOVE: Deletes menu item. Note: don't remove items, which are auto-updated by CudaText, because you'll get Access Violation on showing menu containing these items. E.g. some items in the tab context menu are auto-updated.
  • MENU_CREATE: Creates new popup-menu, independent from CudaText menus. It can be filled like other menus, then shown via MENU_SHOW.
  • MENU_SHOW: Shows given popup-menu. Only menu created with MENU_CREATE should be specified here. Param "command" must be tuple (x,y) or string "x,y" with screen-related coordinates, if empty - menu shows at mouse cursor.
  • MENU_SET_CAPTION: Changes caption of menu item. Param "command" must be str value.
  • MENU_SET_VISIBLE: Changes visible state of menu item. Param "command" must be bool value.
  • MENU_SET_ENABLED: Changes enabled state of menu item. Param "command" must be bool value.
  • MENU_SET_HOTKEY: Changes hotkey of menu item. Param "command" must be str value, e.g. "Ctrl+Alt+F1".
  • MENU_SET_CHECKED: Changes checked state of menu item. When item is checked, it shows a checkmark. Param "command" must be bool value.
  • MENU_SET_RADIOITEM: Changes radio kind of menu item. When item has radio kind, its checkmark is round (in checked state). Param "command" must be bool value.
  • MENU_SET_IMAGELIST: Changes imagelist object of menu, which contains menu item. Param "command" must be imagelist handle.
  • MENU_SET_IMAGEINDEX: Changes icon index of menu item (index in imagelist). Param "index" must be icon index.
  • MENU_SET_AUTO_HOTKEY: Sets the hotkey of menu item according to this item's command code (which must be already set). It skips some special commands: "Clipboard copy", "Clipboard paste", "Clipboard cut", "Select all", "Undo", "Redo" (because for example Ctrl+C hotkey in the top menu overrides the Ctrl+C pressing in the Console / Code-Tree filter / docked plugin dialogs). And it skips some special hotkeys: Esc, Shift+Tab.
  • MENU_SET_AUTO_HOTKEY_DEEP: Performs the action MENU_SET_AUTO_HOTKEY for all menu items nested in the given submenu. The deepness of the recusion (0-based) must be given in the param "command" as str(int_value).

menu_proc - Example

Example adds item "Misc" to the main menu, and sub-items: "About", separator, "Rename file" (from CudaExt plugin):

  menuid = menu_proc('top', MENU_ADD, caption='Misc')
  n = menu_proc(menuid, MENU_ADD, command=2700, caption='About')
  n = menu_proc(menuid, MENU_ADD, caption='-')
  n = menu_proc(menuid, MENU_ADD, command='cuda_ext.rename_file', caption='Rename file')

Example creates popup-menu with one item and shows it at (x=100, y=100):

  h = menu_proc(0, MENU_CREATE)
  menu_proc(h, MENU_ADD, command=2700, caption='About...')
  menu_proc(h, MENU_SHOW, command=(100,100) )

toolbar_proc

toolbar_proc(id_bar, id_action, text="", text2="", command=0, index=-1, index2=-1)

Perform action on toolbar UI control.

Param "id_bar": int handle of toolbar.

Param "id_action" possible values:

  • TOOLBAR_GET_COUNT: Returns number of buttons in toolbar.
  • TOOLBAR_GET_IMAGELIST: Returns int handle of imagelist object.
  • TOOLBAR_GET_BUTTON_HANDLE: Returns int handle of button to use in button_proc(), or None if index not correct. Param "index": button index.
  • TOOLBAR_GET_BUTTON_HANDLES: Returns list of handles of all buttons.
  • TOOLBAR_GET_INDEX_HOVERED: Returns index of button under mouse cursor, or -1 if none.
  • TOOLBAR_DELETE_ALL: Deletes all buttons.
  • TOOLBAR_DELETE_BUTTON: Deletes one button. Param "index": button index.
  • TOOLBAR_ADD_ITEM: Adds one button, of usual kind. Returns its handle. Param "index": button index at which to insert, -1 to append.
  • TOOLBAR_ADD_MENU: Adds one button, with submenu appearing by left click (not context menu). Returns its handle. Param "index": button index at which to insert, -1 to append.
  • TOOLBAR_UPDATE: Updates buttons positions and sizes (for current size of imagelist, current captions etc).
  • TOOLBAR_GET_VERTICAL: Returns vertical state of toolbar.
  • TOOLBAR_SET_VERTICAL: Sets vertical state of toolbar. Param "index": bool value.
  • TOOLBAR_GET_WRAP: Returns wrappable state of toolbar.
  • TOOLBAR_SET_WRAP: Sets wrappable state of toolbar (implemented for horizontal toolbar only). Param "index": bool value.
  • TOOLBAR_THEME: Applies current UI theme to toolbar.

statusbar_proc

statusbar_proc(id_bar, id_action, index=-1, tag=0, value="")

Perform action on statusbar UI control.

  • Param "id_bar": int handle of statusbar.
  • Param "index": int index of cell (0-based), if action needs it.
  • Param "tag": int tag of cell. Tag value, if not 0, overrides "index" param. It's needed to address a cell without knowing its index, only by tag. CudaText addresses standard cells by tags in the range 1..20.

Param "id_action" can be:

  • STATUSBAR_GET_COUNT: Returns int number of cells.
  • STATUSBAR_DELETE_ALL: Deletes all cells.
  • STATUSBAR_DELETE_CELL: Deletes one cell (by "index" or "tag").
  • STATUSBAR_ADD_CELL: Adds one cell. Param "index": -1: cell will be appended; >=0: cell will be inserted at given index. Param "tag" has special meaning: it is tag value of a new cell. Returns index of new cell, or None if cannot add (e.g. "tag" is busy).
  • STATUSBAR_FIND_CELL: Returns index if cell from tag, or None. Param "value": int tag. Params "index", "tag" ignored.
  • STATUSBAR_MOVE_CELL: Moves cell with specified index or tag, to another index specified in the int param "value". Returns bool: source/target indexes are OK, cell was moved.
  • STATUSBAR_GET_IMAGELIST: Returns handle of imagelist object, attached to statusbar, or 0 for none.
  • STATUSBAR_SET_IMAGELIST: Sets handle if imagelist object. Param "value": handle.
  • STATUSBAR_GET_PADDING: Returns cells padding (left and right, in pixels).
  • STATUSBAR_SET_PADDING: Sets cells padding. Param "value": int value.
  • STATUSBAR_GET_SEPARATOR: Returns inter-cell separator string.
  • STATUSBAR_SET_SEPARATOR: Sets inter-cell separator string. Param "value": string value.
  • STATUSBAR_GET_OVERFLOW_LEFT: Returns bool flag "overflow to left". This flag takes action when sum of cells widths overflows the entire statusbar width - flag pushes "redundant first cells" to the left side.
  • STATUSBAR_SET_OVERFLOW_LEFT: Sets bool flag "overflow to left". Param "value": bool value.
  • STATUSBAR_GET_COLOR_BACK: Returns color of background.
  • STATUSBAR_GET_COLOR_FONT: Returns color of font.
  • STATUSBAR_GET_COLOR_BORDER_TOP: Returns color of entire-border-top.
  • STATUSBAR_GET_COLOR_BORDER_BOTTOM: Returns color of entire-border-bottom.
  • STATUSBAR_GET_COLOR_BORDER_L: Returns color of cells-border-left.
  • STATUSBAR_GET_COLOR_BORDER_R: Returns color of cells-border-right.
  • STATUSBAR_GET_COLOR_BORDER_U: Returns color of cells-border-up.
  • STATUSBAR_GET_COLOR_BORDER_D: Returns color of cells-border-down.
  • STATUSBAR_SET_COLOR_BACK: Sets color of background. Param "value": int color.
  • STATUSBAR_SET_COLOR_FONT: Sets color of font.
  • STATUSBAR_SET_COLOR_BORDER_TOP: Sets color of entire-border-top.
  • STATUSBAR_SET_COLOR_BORDER_BOTTOM: Sets color of entire-border-bottom, which is painted if value not equals to COLOR_NONE.
  • STATUSBAR_SET_COLOR_BORDER_L: Sets color of cells-border-left.
  • STATUSBAR_SET_COLOR_BORDER_R: Sets color of cells-border-right.
  • STATUSBAR_SET_COLOR_BORDER_U: Sets color of cells-border-up.
  • STATUSBAR_SET_COLOR_BORDER_D: Sets color of cells-border-down.
  • STATUSBAR_GET_CELL_RECT: Returns rectangle of cell coordinates (related to control) as 4-tuple of int, or None.
  • STATUSBAR_GET_CELL_SIZE: Returns width of cell, or None.
  • STATUSBAR_GET_CELL_AUTOSIZE: Returns auto-size property of cell, bool. Auto-size: adjust width of cell to its icon+text.
  • STATUSBAR_GET_CELL_AUTOSTRETCH: Returns auto-stretch property of cell, bool. Auto-stretch: stretch cell to fill the entire statusbar width.
  • STATUSBAR_GET_CELL_ALIGN: Returns alignment of cell's content. One of str values: "L" (left), "C" (center), "R" (right).
  • STATUSBAR_GET_CELL_TEXT: Returns text of cell.
  • STATUSBAR_GET_CELL_HINT: Returns hint of cell.
  • STATUSBAR_GET_CELL_IMAGEINDEX: Returns icon index (inside imagelist) of cell, -1 for none.
  • STATUSBAR_GET_CELL_COLOR_FONT: Returns font color of cell, COLOR_NONE if not set.
  • STATUSBAR_GET_CELL_COLOR_BACK: Returns background color of cell, COLOR_NONE if not set.
  • STATUSBAR_GET_CELL_COLOR_LINE: Returns line-top color of cell, COLOR_NONE if not set.
  • STATUSBAR_GET_CELL_COLOR_LINE2: Returns line-bottom color of cell, COLOR_NONE if not set.
  • STATUSBAR_GET_CELL_FONT_NAME: Returns special font name of cell (if empty str, not used).
  • STATUSBAR_GET_CELL_FONT_SIZE: Returns special font size of cell (if <=0, not used).
  • STATUSBAR_GET_CELL_TAG: Returns int tag of cell. Tag is some plugin-defined int value.
  • STATUSBAR_GET_CELL_CALLBACK: Returns callback string of cell.
  • STATUSBAR_GET_CELL_OVERLAY: Returns overlay string of cell.
  • STATUSBAR_SET_CELL_SIZE: Sets width of cell. Param "value": int.
  • STATUSBAR_SET_CELL_AUTOSIZE: Sets auto-size of cell. Param "value": bool.
  • STATUSBAR_SET_CELL_AUTOSTRETCH: Sets auto-stretch of cell. Param "value": bool.
  • STATUSBAR_SET_CELL_ALIGN: Sets alignment of cell. Param "value": str constant: "L", "C", "R".
  • STATUSBAR_SET_CELL_TEXT: Sets text of cell. Param "value": str.
  • STATUSBAR_SET_CELL_HINT: Sets hint of cell. Param "value": str.
  • STATUSBAR_SET_CELL_IMAGEINDEX: Sets icon index (inside imagelist) of cell, -1 for none. Param "value": int.
  • STATUSBAR_SET_CELL_COLOR_FONT: Sets font color of cell. Param "value": int color or COLOR_NONE.
  • STATUSBAR_SET_CELL_COLOR_BACK: Sets background color of cell. Param "value": int color or COLOR_NONE.
  • STATUSBAR_SET_CELL_COLOR_LINE: Sets line-top color of cell. Param "value": int color or COLOR_NONE.
  • STATUSBAR_SET_CELL_COLOR_LINE2: Sets line-bottom color of cell. Param "value": int color or COLOR_NONE.
  • STATUSBAR_SET_CELL_FONT_NAME: Sets special font name of cell (if empty str, not used). Param "value": str.
  • STATUSBAR_SET_CELL_FONT_SIZE: Sets special font size of cell (if <=0, not used). Param "value": int.
  • STATUSBAR_SET_CELL_TAG: Sets tag of cell. Param "value": int.
  • STATUSBAR_SET_CELL_CALLBACK: Sets callback string of cell.
  • STATUSBAR_SET_CELL_OVERLAY: Sets overlay string of cell.

Notes:

  • If cell text not empty, alignment applies only for text, icon is on the left. If text empty, alignment applies for icon.

imagelist_proc

imagelist_proc(id_list, id_action, value="")

Perform action on imagelist object.

Param "id_list" is int handle of imagelist. It is required for all actions, except IMAGELIST_CREATE, where it should be 0.

Possible values of "id_action":

  • IMAGELIST_CREATE: Creates new imagelist object with default icon size 16x16. Returns int handle of this imagelist. Param "value" must be int handle of owner form of object.
    • If it is form handle from dlg_proc, object will be deleted after deletion of this form.
    • If it is 0, main application form is used as owner, and object will be persistent.
  • IMAGELIST_COUNT: Returns int number of icons in imagelist.
  • IMAGELIST_GET_SIZE: Returns current icon size as 2-tuple (width, height).
  • IMAGELIST_SET_SIZE: Sets new icon size, and clears imagelist. Param "value" must be 2-tuple of int (width, height). Returns new icon size (corrected by minimal value) as 2-tuple.
  • IMAGELIST_ADD: Loads image into imagelist. Param "value" must be full path to PNG/BMP image file. Size of image should be the same as size of imagelist (otherwise image will be loaded cropped or maybe stretched, it depends on IDE). Returns int icon index, or None if cannot load.
  • IMAGELIST_DELETE: Deletes one icon. Param "value" is int icon index (0-based).
  • IMAGELIST_DELETE_ALL: Deletes all icons.
  • IMAGELIST_PAINT: Paints single icon on given canvas, at given coords. Param "value" must be tuple (canvas_id, x, y, icon_index). Value canvas_id can be 0 for testing paintbox in CudaText.

image_proc

image_proc(id_image, id_action, value="")

Perform action on image object.

Param "id_image" is int handle of image. It is required for all actions, except IMAGE_CREATE, where it should be 0.

Possible values of "id_action":

  • IMAGE_CREATE: Creates new image object. Returns int handle of this image. Param "value" must be int handle of owner form of object.
    • If it is form handle from dlg_proc, object will be deleted after deletion of this form.
    • If it is 0, main application form is used as owner, and object will be persistent.
  • IMAGE_GET_SIZE: Returns current image size as 2-tuple (width, height).
  • IMAGE_LOAD: Reads picture file into image object. Param "value" must be full file path. Supported formats: PNG, JPEG (extensions: jpg/jpeg/jfif), BMP, GIF, ICO, WEBP.
  • IMAGE_PAINT: Paints image object on given canvas, at given coords. Param "value" must be tuple (canvas_id, x, y). Value canvas_id can be 0, for testing paintbox in CudaText.
  • IMAGE_PAINT_SIZED: Paints image object on given canvas, resized to given rectangle. Param "value" must be tuple (canvas_id, x1, y1, x2, y2).

button_proc

button_proc(id_button, id_action, value="")

Perform action on extended button (control type "button_ex").

Param "id_button" is int handle of button.

Possible values of "id_action":

  • BTN_UPDATE: Repaints button.
  • BTN_GET_TEXT: Returns caption string.
  • BTN_SET_TEXT: Sets caption string.
  • BTN_GET_HINT: Returns hint (tooltip) string.
  • BTN_SET_HINT: Sets hint string.
  • BTN_GET_ENABLED: Returns enabled state, bool.
  • BTN_SET_ENABLED: Sets enabled state. Param "value" must be bool.
  • BTN_GET_VISIBLE: Returns visible state, bool.
  • BTN_SET_VISIBLE: Sets visible state. Param "value" must be bool.
  • BTN_GET_CHECKED: Returns checked state, bool.
  • BTN_SET_CHECKED: Sets checked state. Param "value" must be bool.
  • BTN_GET_IMAGELIST: Returns handle of imagelist for button.
  • BTN_SET_IMAGELIST: Sets handle of imagelist. Param "value" must be int handle.
  • BTN_GET_IMAGEINDEX: Returns icon index (in attached imagelist).
  • BTN_SET_IMAGEINDEX: Sets icon index. Param "value" must be int index (0-based), or -1 for none. To show icon, you must also set appropriate kind of button.
  • BTN_GET_MENU: Returns int handle of submenu. It can be passed to menu_proc(h, MENU_SHOW).
  • BTN_SET_MENU: Sets int handle of submenu. It can be handle created by menu_proc(0, MENU_CREATE).
  • BTN_GET_KIND: Returns kind of button. Int value, one of BTNKIND_nnn constants.
  • BTN_SET_KIND: Sets kind of button.
  • BTN_GET_BOLD: Returns bold-style of button, bool.
  • BTN_SET_BOLD: Sets bold-style. Param "value" must be bool.
  • BTN_GET_ARROW: Returns dropdown arrow visible flag, bool.
  • BTN_SET_ARROW: Sets dropdown arrow visible flag. Param "value" must be bool.
  • BTN_GET_ARROW_ALIGN: Returns alignment of dropdown arrow, as str: "L", "R", "C".
  • BTN_SET_ARROW_ALIGN: Sets alignment of dropdown arrow. Param "value" must be str: "L", "R", "C".
  • BTN_GET_FOCUSABLE: Returns focusable state, bool.
  • BTN_SET_FOCUSABLE: Sets focusable state. Param "value" must be bool.
  • BTN_GET_FLAT: Returns flat state, bool.
  • BTN_SET_FLAT: Sets flat state. Param "value" must be bool.
  • BTN_GET_DATA1: Returns data1 string.
  • BTN_SET_DATA1: Sets data1 string. It must contain one of the following:
    • str(command_code) to run command by its integer code, like Editor.cmd() API does.
    • string with #Callback_parameter. Note: only string callback forms are allowed here, ie callable form is not allowed.
  • BTN_GET_DATA2: Returns data2 string. This string is not used by CudaText, but is used by plugins.
  • BTN_SET_DATA2: Sets data2 string.
  • BTN_GET_WIDTH: Returns width (in pixels).
  • BTN_SET_WIDTH: Sets width.
  • BTN_GET_ITEMS: Returns choice items, used for kind=BTNKIND_TEXT_CHOICE, as "\n"-separated strings.
  • BTN_SET_ITEMS: Sets choice items. Param "value" must be str, "\n"-separated strings.
  • BTN_GET_ITEMINDEX: Returns choice index, used for kind=BTNKIND_TEXT_CHOICE.
  • BTN_SET_ITEMINDEX: Sets choice index. Param "value" must be int >=0, or -1 for none.
  • BTN_GET_OVERLAY: Returns overlay text.
  • BTN_SET_OVERLAY: Sets overlay text.
  • BTN_GET_COLOR_LINE: Returns color of line-top.
  • BTN_SET_COLOR_LINE: Sets color of line-top.
  • BTN_GET_COLOR_LINE2: Returns color of line-bottom.
  • BTN_SET_COLOR_LINE2: Sets color of line-bottom.

Note: Toolbars contain several "button_ex" objects, which are anchored one to another (horizontally or vertically). You can also construct such toolbar by hands. API toolbar_proc() don't allow to specify kind of buttons, it sets kind from button properties.

more

Editor class

Editor class has methods to work with editor-controls.

  • Editor(0), the same as global object "ed", refers to the currently focused editor in UI-tabs.
  • Editor(1) refers the editor of right-clicked UI-tab.

Notes:

  • Most of Editor APIs work for editor-controls in the UI-tabs and for editor-controls created by dlg_proc(). But not all the APIs, some of them require the editor-control in the UI-tab. For example, some get_prop()/set_prop() properties need the editor in UI-tab.
  • While CudaText has the file viewer active (not the editor, only binary/hex viewer), the editor is hidden and empty, so Editor APIs don't work.

Carets

Editor.get_carets

get_carets()

Returns list of 4-tuples, each item is info about one caret: (PosX, PosY, EndX, EndY).

  • PosX is caret's column (0-base). Tab-chars give x increment 1, like others.
  • PosY is caret's line (0-base).
  • EndX/EndY is position of selection edge for this caret. Both -1 if no selection for caret.

Example shows text of first caret's selection:

    carets = ed.get_carets()
    x1, y1, x2, y2 = carets[0]
    if y2>=0:
        # sort (y,x) pairs
        if (y1, x1)>(y2, x2):
            x1, y1, x2, y2 = x2, y2, x1, y1
        s = ed.get_text_substr(x1, y1, x2, y2)
        msg_status('Selection: '+s)

Editor.set_caret

set_caret(posx, posy, endx=-1, endy=-1, id=CARET_SET_ONE, options=0)

Controls carets. Possible values of "id":

  • CARET_SET_ONE: Removes multi-carets and sets single caret to the given position (posx, posy, endx, endy). To place caret without selection, set both "endx", "endy" to -1.
  • CARET_ADD: Adds caret (multi-carets feature) with given position (posx, posy, endx, endy). Returns number of carets after that.
  • CARET_DELETE_ALL: Deletes all carets. Parameters "posx", "posy", "endx", "endy" are ignored here. Note: you must add caret(s) later, to enable text editing to user.
  • CARET_SET_INDEX + N, where N is 0...1e6: Places single caret, with index N, to the given position (posx, posy, endx, endy).
  • CARET_DELETE_INDEX + N, where N is 0...1e6: Deletes single caret, with index N. Parameters "posx", "posy", "endx", "endy" are ignored here.

Param "options" must be 0 or sum of the following flags:

  • CARET_OPTION_NO_SCROLL: Don't scroll to new caret position. For id=CARET_SET_ONE.

Text read/write

Editor.get_text_all

get_text_all()

Returns the entire editor text as string.

Notes:

  • All line breaks are returned as LF, ie "\n".

Editor.set_text_all

set_text_all(text)

Sets the entire editor text, from given string. Text can have any line-breaks (LF, CRLF, CR, mixed).

Notes:

  • Function cannot work with read-only editor (see Editor.get_prop, Editor.set_prop and PROP_RO).
  • Function looses Undo information. To support Undo, use another API to set text, e.g. Editor.replace().

Editor.get_line_len

get_line_len(index)

Returns length of internal line UTF-16 (without BOM) representation. It is not the same as len(ed.get_text_line(index)), if internal UTF-16 representation has surrogate-pairs. Returns None if index is incorrect.

Editor.get_text_line

get_text_line(index, max_len=0)

Returns single line (str) with given index (0-based). Without ending line-break char(s). Returns None if index is incorrect.

If param "max_len" is non-zero, and UTF-8 length of given line is greater than "max_len", function returns empty str. This allows to skip huge lines.

Editor.set_text_line

set_text_line(index, text)

Changes single line with given index (0-based) to given text. Text should be without line-breaks, because "\n" and "\r" chars will be replaced with "_".

Special "index" values:

  • -1: Append new line, with final end-of-line.
  • -2: Append new line, but without final end-of-line.

Editor.get_text_substr

get_text_substr(x1, y1, x2, y2)

Returns substring from position (x1, y1) to bigger position (x2, y2). Coordinates x1 / x2 are in the UTF-16 internal representation of line.

Editor.delete

delete(x1, y1, x2, y2)

Deletes range from position (x1, y1) to bigger position (x2, y2). Coordinates x1 / x2 are in the UTF-16 internal representation of line.

  • Too big x1/x2 are allowed (after line-end)
  • Too big y2 means delete to end of file

Note: don't pass tuple from get_carets()[0], this tuple has not sorted positions (x1, y1) and (x2, y2), you need to sort them (first sort by y, then by x).

Example replaces selection of 1st caret with text:

        x0, y0, x1, y1 = ed.get_carets()[0]
        if (y0, x0) >= (y1, x1): #note that y first
            x0, y0, x1, y1 = x1, y1, x0, y0

        ed.set_caret(x0, y0)
        ed.delete(x0, y0, x1, y1)
        ed.insert(x0, y0, text)

Editor.insert

insert(x, y, text)

Inserts given text at position (x, y). If param "y" is after the actual line-count, appends block to the end (even to final line without line-ending). Coordinate "x" is in the UTF-16 internal representation of line. Text can be multi-line, all CR LF will be converted to currently used line-breaks.

Returns 2-tuple (x, y) of position after inserted text. It is on the same line, if text is single line. Returns None if cannot insert.

Editor.replace

replace(x1, y1, x2, y2, text)

Replaces range from position (x1, y1) to bigger position (x2, y2), with new text. Coordinates x1 / x2 are in the UTF-16 internal representation of line.

  • Too big x1/x2 are allowed (after line-end)
  • Too big y2 means delete to end of file

Function does the same as delete+insert, but

  • optimized for replace inside one line (when y1==y2 and no line-breaks in text)
  • for multi-line it also makes grouped-undo for delete+insert

Returns 2-tuple (x, y) of position after inserted text.

Editor.replace_lines

replace_lines(y1, y2, lines)

Deletes whole lines from index y1 to y2, then inserts new lines from specified list.

  • Index y1 must be valid index (0 to count-1)
  • Index y2 can be less than y1 (to not delete), and can be too big (to delete lines to end)
  • Param lines is list/tuple of str. Can be empty list to just delete lines. Inside items should not be "\n" and "\r": "\n" will generate additional lines, "\r" not handled.

Returns bool: index y1 correct, replace done.

Selection

Editor.get_text_sel

get_text_sel()

Returns selected text for 1st caret (empty, if no selection).

Editor.get_sel_mode

get_sel_mode()

Returns current selection mode:

  • SEL_NORMAL: normal (stream) selection; it doesn't mean that selection exists.
  • SEL_COLUMN: column (vertical) selection.

Editor.get_sel_lines

get_sel_lines()

Returns 2-tuple, indexes of first and last lines affected by first caret selection. Returns (-1,-1) if no selection.

Editor.get_sel_rect, Editor.set_sel_rect

get_sel_rect()
set_sel_rect(x1, y1, x2, y2)

Returns/sets coords of column selection.

Returns 4-tuple (x1, y1, x2, y2). All 0 if no column selection.

Properties

Editor.get_line_count

get_line_count()

Returns number of lines.

Editor.get_char_count

get_char_count(max_chars, max_time)

Returns number of UTF-16 characters.

Each UTF-16 character in internal storage is counted as 1. Line-break is counted as 1, even for CR LF endings.

  • Param "max_chars": If result becomes (in internal loop) bigger than param value, stop counting and return -1. Pass very big value, for example 0x7fffFFFF, to avoid the limit.
  • Param "max_time": If method working time becomes bigger than param value (in milliseconds), stop counting and return -2. Pass 0x7fffFFFF to avoid time checking.
    • Example: on CPU Intel Core i3 3GHz, with file "torrent.cpp" with 5K lines with 414K chars, "max_time" must be >=10 to count all content.

Editor.get_filename

get_filename(options="")

Returns filename (string) of the editor.

  • Returns empty string for untitled tab.
  • Returns string "?" if ui-tab contains not normal text editor, but picture viewer or binary viewer. You can detect the kind of ui-tab: Editor.get_prop(PROP_KIND).

If param "options" contains char "*", the real file name is always returned, even in picture/binary viewer mode.

Editor.get_prop

get_prop(id, value="")

Returns editor's property.

Param "value" can be: str, number, bool (for bool it can be also "0"/"1"). Possible values of "id":

  • PROP_GUTTER_ALL: bool: gutter (container for all gutter columns) is visible.
  • PROP_GUTTER_STATES: bool: show gutter column "line states".
  • PROP_GUTTER_NUM: bool: show gutter column "line numbers".
  • PROP_GUTTER_FOLD: bool: show gutter column "folding".
  • PROP_GUTTER_BM: bool: show gutter column "bookmarks".
  • PROP_GUTTER_EMPTY: bool: show gutter column "empty padding".
  • PROP_GUTTER_EMPTY_WIDTH: int: width of gutter column "empty padding".
  • PROP_NEWLINE: str: kind of line endings. One of values "lf", "crlf", "cr".
  • PROP_WRAP: int: word-wrap mode. One of WRAP_nnn values.
  • PROP_RO: bool: read-only mode.
  • PROP_MARGIN: int: position of fixed margin.
  • PROP_MARGIN_STRING: str: user-defined margins positions, e.g. "20 25".
  • PROP_INSERT: bool: insert/overwrite mode.
  • PROP_MODIFIED: bool: editor is modified.
  • PROP_MODIFIED_VERSION: int: counter which is incremented on each text change.
  • PROP_RULER: bool: show 'ruler' horizontal band.
  • PROP_RULER_TEXT: str: text of one line or several "\n"-separated lines, which is rendered on 'ruler' band. #HTML formatting is allowed if "<html>" prefix is used.
  • PROP_LINE_STATE: int: state of the line with given index. One of LINESTATE_nnn values.
  • PROP_LINE_STATES: list of int: list of line states (LINESTATE_nnn values) for all lines.
  • PROP_LINE_STATES_UPDATED: list of bool: list of "updated" flags for all lines, each flag shows that its line was added/changed since the last clearing of this "updated" flag.
  • PROP_LINE_NUMBERS: int: style of line numbers. One of LINENUM_nnn values.
  • PROP_LINE_TOP: int: index of line visible at the top of editor.
    • Note: If you set PROP_LINE_TOP immediately after file_open(), it may not work, you need to call app_idle(True) first.
  • PROP_LINE_BOTTOM: int: index of line visible at the bottom of editor (considers word wrap).
  • PROP_SCROLL_VERT: int: approximate vertical scroll position. Index in WrapInfo list, you can read this list via get_wrapinfo().
  • PROP_SCROLL_HORZ: int: approximate horizontal scroll position.
  • PROP_SCROLL_VERT_SMOOTH: int: smooth vertical scroll position. In pixels.
  • PROP_SCROLL_HORZ_SMOOTH: int: smooth horizontal scroll position. In pixels.
  • PROP_SCROLL_VERT_INFO: int: dict with all available info about vertical scroll.
  • PROP_SCROLL_HORZ_INFO: int: dict with all available info about horizontal scroll.
  • PROP_SCROLLSTYLE_HORZ: int: style of horizontal scrollbar, one of SCROLLSTYLE_ constants.
  • PROP_SCROLLSTYLE_VERT: int: style of vertical scrollbar, one of SCROLLSTYLE_ constants.
  • PROP_CORNER_TEXT: str: short text (multi-line is allowed, separator chr(10)) in the right-bottom corner (rendered above editor text).
  • PROP_CORNER_COLOR_FONT: int: font-color for PROP_CORNER_TEXT; can be COLOR_NONE.
  • PROP_CORNER_COLOR_BACK: int: background-color for PROP_CORNER_TEXT; can be COLOR_NONE.
  • PROP_CORNER_COLOR_BORDER: int: border-color for PROP_CORNER_TEXT; can be COLOR_NONE.
  • PROP_CORNER_FONT_NAME: str: if not empty, specifies font name for PROP_CORNER_TEXT. If empty, editor font name is used.
  • PROP_CORNER_FONT_SIZE: int: if >0, specifies font size for PROP_CORNER_TEXT. If 0, editor font size is used.
  • PROP_CORNER2_TEXT: like PROP_CORNER_TEXT but for the right-top corner.
  • PROP_CORNER2_COLOR_FONT: like PROP_CORNER_COLOR_FONT but for the right-top corner.
  • PROP_CORNER2_COLOR_BACK: like PROP_CORNER_COLOR_BACK but for the right-top corner.
  • PROP_CORNER2_COLOR_BORDER: like PROP_CORNER_COLOR_BORDER but for the right-top corner.
  • PROP_CORNER2_FONT_NAME: like PROP_CORNER_FONT_NAME but for the right-top corner.
  • PROP_CORNER2_FONT_SIZE: like PROP_CORNER_FONT_SIZE but for the right-top corner.
  • PROP_BORDER_COLOR: int: if active, ie value not equals to COLOR_NONE, specifies color of border around the editor (like with macro-recording active).
  • PROP_BORDER_COLOR_WIDTH: int: border width for PROP_BORDER_COLOR.
  • PROP_WHEEL_ZOOMS: bool: enable zooming by Ctrl+[mouse wheel up/down].
  • PROP_SCALE_FONT: int: scale of editor's font in percents, or 0 to use global app font scale.
  • PROP_COLOR: int: color property. Value must be one of COLOR_ID_nnn values. Returns None for incorrect id.
  • PROP_ENC: str: encoding name. Names are listed at CudaText#Encodings.
  • PROP_LEXER_FILE: str: name of lexer for entire file (empty str if none is active).
  • PROP_LEXER_POS: str: name of lexer at specified position. Param "value" must be 2-tuple (column, line), or string str(column)+','+str(line), with 0-based indexes.
  • PROP_LEXER_CARET: str: name of lexer at the position of 1st caret.
  • PROP_INDEX_GROUP: int: index of group with editor's tab, 0-based.
  • PROP_INDEX_TAB: int: index of editor's tab in group, 0-based.
  • PROP_UNPRINTED_SHOW: bool: unprinted chars: global enable-flag.
  • PROP_UNPRINTED_SPACES: bool: unprinted chars: show spaces/tabs.
  • PROP_UNPRINTED_SPACES_TRAILING: bool: unprinted chars: show spaces/tabs only at end of lines.
  • PROP_UNPRINTED_ENDS: bool: unprinted chars: show line ends.
  • PROP_UNPRINTED_END_DETAILS: bool: unprinted chars: show line end details.
  • PROP_TAG: str: some string attached to editor. Value must be "key:defvalue" or simply "defvalue". Saved value for "key" is returned, or "defvalue" returned if value for key was not set. Empty key means key "_".
  • PROP_CARET_VIEW: 3-tuple: shape of caret, normal mode. Tuple contents is (int_width, int_height, bool_empty_inside). Width/height<0 means value in percents.
  • PROP_CARET_VIEW_OVR: 3-tuple: shape of caret, overwrite mode.
  • PROP_CARET_VIEW_RO: 3-tuple: shape of caret, read-only mode.
  • PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
  • PROP_CARET_STOP_UNFOCUSED: bool: caret blinks only when editor is focused.
  • PROP_CARET_MULTI: bool: allow multi-carets.
  • PROP_MACRO_REC: bool: currently macro is recording.
  • PROP_MARKED_RANGE: 2-tuple with line indexes of "marked range"; (-1, -1) if range not set.
  • PROP_VISIBLE_LINES: int: max count of lines that fit to window (doesn't consider word wrap).
  • PROP_VISIBLE_COLUMNS: int: max count of columns that fit to window.
  • PROP_PICTURE: properties of picture file as 3-tuple: (picture_filename, size_x, size_y), or None if not picture loaded in tab. For picture ed.get_filename() returns "?".
  • PROP_MINIMAP: bool: minimap is visible.
  • PROP_MINIMAP_CHAR_WIDTH: int: minimap width, in average chars.
  • PROP_MINIMAP_SCALE: int: minimap custom scale, in percents; if value<=100: auto-detect.
  • PROP_MINIMAP_AT_LEFT: bool: minimap is shown on the left side.
  • PROP_MICROMAP: bool: micromap is visible.
  • PROP_LINK_AT_POS: str: hyperlink string in the document, at given position. Value must be 2-tuple: (pos_x, pos_y).
  • PROP_LINKS_SHOW: bool: enable hyperlinks underlining.
  • PROP_LINKS_REGEX: str: regular expression for hyperlinks.
  • PROP_LINKS_CLICKS: int: how mouse clicks activate hyperlinks. 0: disabled, 1: single click, 2: double click.
  • PROP_IN_SESSION: bool: document was loaded from "session".
  • PROP_IN_HISTORY: bool: document history was loaded from history file (history embedded to "session" or main history file).
  • PROP_TAB_SPACES: bool: tab-key inserts spaces, not tab-char.
  • PROP_TAB_SIZE: int: size of tab-char.
  • PROP_TAB_SMART: bool: smart-tabs option, known from many text editors.
  • PROP_TAB_COLLECT_MARKERS: bool: tab-key collects (jumps to and deletes) markers (if markers placed).
  • PROP_TAB_TITLE: str: custom title of ui-tab; setting to empty string removes the custom title.
  • PROP_TAB_TITLE_REASON: str (1 char): reason of current ui-tab title.
    • "u": Usual untitled tab
    • "s": App-special untitled tab, e.g. "RegEx search", "Welcome"
    • "f": Title was calculated from filename
    • "p": Title was set by plugin API
  • PROP_TAB_COLOR: int: color of ui-tab title background, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
  • PROP_TAB_COLOR_FONT: int: color of ui-tab title font, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
  • PROP_TAB_ICON: int: index of ui-tab icon, ie index in imagelist, which handle you can get via app_proc(PROC_GET_TAB_IMAGELIST).
  • PROP_TAB_PINNED: bool: ui-tab is "pinned" (shows additional confirmation on closing).
  • PROP_TAB_UI_SHOW: bool: ui-tab header is visible on the tabs-bar.
  • PROP_TAB_ID: int: ui-tab's unique identifier (single value for primary/secondary editors in tab); it is not changed when tab is moved to another position/group.
  • PROP_INDENT_SIZE: int: size of indent for Indent/Unindent commands. N>0: indent in spaces, N<0: indent in tabs, N=0: indent from PROP_TAB_SIZE/PROP_TAB_SPACES.
  • PROP_INDENT_KEEP_ALIGN: bool: command Unindent keeps alignment of block edge, ie don't unindent if any line reached column 0.
  • PROP_INDENT_AUTO: bool: makes next line also indented on Enter command.
  • PROP_INDENT_KIND: int: kind of auto-indented line, see description of app option "indent_kind".
  • PROP_FOLD_ALWAYS: bool: always show icons on "folding" gutter bar, otherwise show them only on mouse over.
  • PROP_FOLD_ICONS: int: icon set for "folding" gutter bar. Possible values: 0, 1.
  • PROP_FOLD_TOOLTIP_SHOW: bool: show floating tooltip when mouse hovers [...] mark for folded block.
  • PROP_LAST_LINE_ON_TOP: bool: allow to scroll control, so last line shows on top.
  • PROP_FOCUSED: bool: editor is focused. When changing: for editor in UI-tab it focuses also editor's tab. Cannot change True to False.
  • PROP_HILITE_CUR_COL: bool: highlight current column.
  • PROP_HILITE_CUR_LINE: bool: highlight current line.
  • PROP_HILITE_CUR_LINE_MINIMAL: bool: highlight current line, only minimal part of line.
  • PROP_HILITE_CUR_LINE_IF_FOCUS: bool: highlight current line, only when editor focused.
  • PROP_CODETREE: bool: enable standard code-tree filling.
  • PROP_CODETREE_MODIFIED_VERSION: modification version of the editor for the moment of code-tree filling. See PROP_MODIFIED_VERSION.
  • PROP_CODETREE_SUBLEXER: bool: enable code-tree to show nodes from sublexer(s) of current lexer.
  • PROP_EDITORS_LINKED: bool: enable sharing of the same text by primary/secondary editors in file tab.
  • PROP_CELL_SIZE: 2-tuple of int: size in pixels of average char cell.
  • PROP_ONE_LINE: bool: editor has single-line mode. (Usual editors are multi-line.)
  • PROP_MODERN_SCROLLBAR: bool: use custom-drawn themed scrollbars.
  • PROP_SAVE_HISTORY: bool: allows to save history (caret, scroll pos, folding etc) on file closing.
  • PROP_PREVIEW: bool: editor is inside "Preview tab" (it has italic caption).
  • PROP_UNDO_GROUPED: bool: editor undo/redo is grouped.
  • PROP_UNDO_LIMIT: int: max count of simple actions, which can be undone.
  • PROP_UNDO_DATA: str: string representation of Undo data. See #Format_of_serialized_Undo.
  • PROP_REDO_DATA: str: string representation of Redo data.
  • PROP_ZEBRA: int: if 0, "zebra" mode is not active; if >0, it is alpha-blend value (1..255) of active zebra mode.
  • PROP_ZEBRA_STEP: int: step (in lines) of "zebra" mode.
  • PROP_FONT: 2-tuple (str, int): normal font: name, size.
  • PROP_FONT_B: 2-tuple (str, int): bold font: name, size. Empty name: not used.
  • PROP_FONT_I: 2-tuple (str, int): italic font: name, size. Empty name: not used.
  • PROP_FONT_BI: 2-tuple (str, int): bold+italic font: name, size. Empty name: not used.
  • PROP_ACTIVATION_TIME: int: time (in milliseconds since OS start) when editor was last focused. It's 0 for not yet focused editors.
  • PROP_KIND: str: kind of UI control in the tab.
    • "text": normal editor.
    • "bin": text/binary/hex viewer.
    • "pic": picture viewer.
  • PROP_SPLIT: 2-tuple: information about primary/secondary editors splitting as tuple (split_kind, split_pos).
    • "split_kind": str: "-" (not splitted), "v" (splitted vertically), "h" (splitted horizontally).
    • "split_pos": int: part of entire size for secondary editor, multiplied by 1000 (e.g. 500 is half of size).
  • PROP_SAVING_FORCE_FINAL_EOL: bool: on saving file, ensure the newline at end of document.
  • PROP_SAVING_TRIM_SPACES: bool: on saving file, trim trailing whitespaces.
  • PROP_SAVING_TRIM_FINAL_EMPTY_LINES: bool: on saving file, trim redundant empty lines at end of document.
  • PROP_HANDLE_SELF: int: handle of editor object, for which get_prop() is called. This handle is unique among all objects in program (it is memory address). Why not just use "ed.h"? Because: 1) For "ed" object its handle "ed.h" is zero - zero handle is virtual handle pointing to the focused editor. 2) For "ed_handles()" result, handles are also virtual, they are some small integer numbers, not memory addresses. Note: to get editor object from handle, use "Editor(handle_value)".
  • PROP_HANDLE_PRIMARY: int: handle of editor object, which is primary editor in ui-tab (primary editor is always visible). It's None for editor objects created from dlg_proc().
  • PROP_HANDLE_SECONDARY: int: handle of editor object, which is secondary editor in ui-tab (secondary editor is visible only when ui-tab is splitted). It's None for editor objects created from dlg_proc().
  • PROP_HANDLE_PARENT: int: handle of parent of editor object, or 0 if no such parent. This is handle of dialog containing the editor, it can be passed to dlg_proc(). This handle is needed to dock custom dialogs into the editor, again via dlg_proc().
  • PROP_COORDS: 4-tuple of int: rectangle of entire editor area, relative to screen.
  • PROP_RECT_CLIENT: 4-tuple of int: rectangle of entire editor area, relative to editor.
  • PROP_RECT_TEXT: 4-tuple of int: rectangle of "main text" editor area (excluding gutter/minimap/micromap/ruler), relative to editor.
  • PROP_RECT_GUTTER: 4-tuple of int: rectangle of "gutter" editor area (all gutter columns at once), relative to editor. It is (0,0,0,0) if area is hidden.
  • PROP_RECT_MINIMAP: 4-tuple of int: rectangle of "minimap" editor area, relative to editor. It is (0,0,0,0) if area is hidden.
  • PROP_RECT_MICROMAP: 4-tuple of int: rectangle of "micromap" editor area, relative to editor. It is (0,0,0,0) if area is hidden.
  • PROP_RECT_RULER: 4-tuple of int: rectangle of "horizontal ruler" editor area, relative to editor. It is (0,0,0,0) if area is hidden.
  • PROP_THEMED: bool: for editors out of UI-tabs, allows to automatically apply current theme on app theme changing.
  • PROP_COMBO_ITEMS: only for "editor_combo" control, contents of drop-down list. On getting: list of str. On setting: value must be str with '\n'-separated items.
  • PROP_MASKCHAR: str: character to show in masked-mode.
  • PROP_MASKCHAR_USED: bool: masked-mode is activated.
  • PROP_NUMBERS_ONLY: bool: allow to input only numbers.
  • PROP_NUMBERS_NEGATIVE: bool: additional to PROP_NUMBERS_ONLY, allow negative numbers<0.
  • PROP_COMMAND_LOG: list of last executed commands, as list of dict. Dict keys are:
    • "code": Integer command code.
      • Special codes: value cmd_PluginRun means 'plugin started', value cmd_PluginEnd means 'plugin returned'. For these codes, "text" key has the value "py:module,method," or "py:module,method,param".
    • "invoke": String, how the command was invoked. One of values:
      • "int": Internal calling from core components.
      • "int_ime": Internal calling via OS IME dialog.
      • "key": Calling via some hotkey.
      • "menu_ctx": Calling from some context menu.
      • "menu_main": Calling from the main menu.
      • "app_int": Internal calling from high-level CudaText code.
      • "app_pal": Calling from the Command Palette.
      • "app_toolbar": Calling via toolbar buttons.
      • "app_sidebar": Calling via sidebar buttons.
      • "app_charmap": Calling via Char Map dialog.
      • "app_dragdrop": Calling via drag-and-drop.
      • "app_api": Calling from some Python API handler.
    • "text": Text of command. It's not empty only in few cases, e.g. for command codes cCommand_TextInsert / cmd_PluginRun / cmd_PluginEnd.
  • PROP_COMMAND_LOG_LIMIT: int: maximal count of items in the list returned by PROP_COMMAND_LOG.
  • PROP_DIM_UNFOCUSED: int: for unfocused editor, dim the background color by specified percents (ranges is -250...250, 0: disabled).
  • PROP_V_MODE: int: mode of binary viewer. Reading it for editor, returns VMODE_NONE. Reading it for viewer, returns one of: VMODE_TEXT, VMODE_BINARY, VMODE_HEX, VMODE_UNICODE, VMODE_UNICODE_HEX.
  • PROP_V_POS: int: for binary viewer, scroll position.
  • PROP_V_SEL_START: int: for binary viewer, selection start offset.
  • PROP_V_SEL_LEN: int: for binary viewer, selection length.
  • PROP_V_WIDTH: int: for binary viewer, width of text in mode VMODE_BINARY.
  • PROP_V_WIDTH_HEX: int: for binary viewer, width of text in mode VMODE_HEX.
  • PROP_V_WIDTH_UHEX: int: for binary viewer, width of text in mode VMODE_UNICODE_HEX.
  • PROP_V_ENC: str: for binary viewer, its encoding.

Editor.set_prop

set_prop(id, value)

Sets editor's property.

Param "value" can be: str, number, bool (for bool it can be also "0"/"1"), tuple of simple type. Possible values of "id":

  • PROP_GUTTER_ALL: bool: gutter (container for all gutter columns) is visible.
  • PROP_GUTTER_STATES: bool: show gutter column "line states".
  • PROP_GUTTER_NUM: bool: show gutter column "line numbers".
  • PROP_GUTTER_FOLD: bool: show gutter column "folding".
  • PROP_GUTTER_BM: bool: show gutter column "bookmarks".
  • PROP_GUTTER_EMPTY: bool: show gutter column "empty padding".
  • PROP_GUTTER_EMPTY_WIDTH: int: width of gutter column "empty padding".
  • PROP_WRAP: int: word-wrap mode. One of WRAP_nnn values.
  • PROP_RO: bool: read-only mode.
  • PROP_NEWLINE: str: kind of line endings. One of values "lf", "crlf", "cr".
  • PROP_MARGIN: int: position of fixed margin.
  • PROP_MARGIN_STRING: str: space-separated user-margins columns.
  • PROP_INSERT: bool: insert/overwrite mode.
  • PROP_MODIFIED: bool: editor is modified.
  • PROP_RULER: bool: show 'ruler' horizontal band.
  • PROP_RULER_TEXT: str: text of one line or several "\n"-separated lines, which is rendered on 'ruler' band. #HTML formatting is allowed if "<html>" prefix is used.
  • PROP_COLOR: color property, value must be 2-tuple (COLOR_ID_nnnn, int_color_value).
  • PROP_LINE_TOP: int: index of line visible at the editor top.
    • Note: If you set PROP_LINE_TOP immediately after file_open(), it may not work, you need to call app_idle(True) first.
  • PROP_LINE_NUMBERS: int: style of line numbers. One of LINENUM_nnn values.
  • PROP_LINE_STATE: 2-tuple: state of the line with given index. 2-tuple (line_index, LINESTATE_nnn).
  • PROP_LINE_STATES_UPDATED: currently supports writing only empty string value, writing it means clearing of "updated" flags for all lines.
  • PROP_SCROLL_VERT: int: approximate vertical scroll position. Index in WrapInfo list, you can read this list via get_wrapinfo().
  • PROP_SCROLL_HORZ: int: approximate horizontal scroll position.
  • PROP_SCROLL_VERT_SMOOTH: int: smooth vertical scroll position. In pixels.
  • PROP_SCROLL_HORZ_SMOOTH: int: smooth horizontal scroll position. In pixels.
  • PROP_SCROLLSTYLE_HORZ: int: style of horizontal scrollbar, one of SCROLLSTYLE_ constants.
  • PROP_SCROLLSTYLE_VERT: int: style of vertical scrollbar, one of SCROLLSTYLE_ constants.
  • PROP_CORNER_TEXT: str: short text (multi-line is allowed, separator chr(10)) in the right-bottom corner (rendered above editor text).
  • PROP_CORNER_COLOR_FONT: int: font-color for PROP_CORNER_TEXT; can be COLOR_NONE.
  • PROP_CORNER_COLOR_BACK: int: background-color for PROP_CORNER_TEXT; can be COLOR_NONE.
  • PROP_CORNER_COLOR_BORDER: int: border-color for PROP_CORNER_TEXT; can be COLOR_NONE.
  • PROP_CORNER_FONT_NAME: str: if not empty, specifies font name for PROP_CORNER_TEXT. If empty, editor font name is used.
  • PROP_CORNER_FONT_SIZE: int: if >0, specifies font size for PROP_CORNER_TEXT. If 0, editor font size is used.
  • PROP_CORNER2_TEXT: like PROP_CORNER_TEXT but for the right-top corner.
  • PROP_CORNER2_COLOR_FONT: like PROP_CORNER_COLOR_FONT but for the right-top corner.
  • PROP_CORNER2_COLOR_BACK: like PROP_CORNER_COLOR_BACK but for the right-top corner.
  • PROP_CORNER2_COLOR_BORDER: like PROP_CORNER_COLOR_BORDER but for the right-top corner.
  • PROP_CORNER2_FONT_NAME: like PROP_CORNER_FONT_NAME but for the right-top corner.
  • PROP_CORNER2_FONT_SIZE: like PROP_CORNER_FONT_SIZE but for the right-top corner.
  • PROP_BORDER_COLOR: int: if active, ie value not equals to COLOR_NONE, specifies color of border around the editor (like with macro-recording active).
  • PROP_BORDER_COLOR_WIDTH: int: border width for PROP_BORDER_COLOR.
  • PROP_WHEEL_ZOOMS: bool: enable zooming by Ctrl+[mouse wheel up/down].
  • PROP_SCALE_FONT: int: scale of editor's font in percents, or 0 to use global app font scale.
  • PROP_ENC: str: encoding name. Names listed at CudaText#Encodings.
  • PROP_ENC_RELOAD: str: like PROP_ENC, but setting this property also reloads file in new encoding (if it's not modified). Supported only for editors embedded in ui-tabs.
  • PROP_LEXER_FILE: str: name of lexer.
  • PROP_INDEX_GROUP: int: index of group with editor's tab, 0-based.
  • PROP_INDEX_TAB: int: index of editor's tab in group, 0-based.
  • PROP_UNPRINTED_SHOW: bool: unprinted chars: global enable-flag.
  • PROP_UNPRINTED_SPACES: bool: unprinted chars: show spaces/tabs.
  • PROP_UNPRINTED_SPACES_TRAILING: bool: unprinted chars: show spaces/tabs only at end of lines.
  • PROP_UNPRINTED_ENDS: bool: unprinted chars: show line ends.
  • PROP_UNPRINTED_END_DETAILS: bool: unprinted chars: show line end details.
  • PROP_TAG: str: some string attached to editor. Param text must be pair "key:value" or simply "value", this sets value for specified key (internally it is dictionary). Empty key means key "_".
  • PROP_CARET_VIEW: 3-tuple: shape of caret, normal mode. Tuple contents is (int_width, int_height, bool_empty_inside). Width/height<0 means value in percents.
  • PROP_CARET_VIEW_OVR: 3-tuple: shape of caret, overwrite mode.
  • PROP_CARET_VIEW_RO: 3-tuple: shape of caret, read-only mode.
  • PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
  • PROP_CARET_STOP_UNFOCUSED: bool: caret blinks only when editor is focused.
  • PROP_CARET_MULTI: bool: allow multi-carets.
  • PROP_MARKED_RANGE: line indexes of "marked range", value is 2-tuple (index1, index2) or (-1, -1) to remove this range.
  • PROP_MINIMAP: bool: minimap is visible.
  • PROP_MINIMAP_CHAR_WIDTH: int: minimap width, in average chars.
  • PROP_MINIMAP_SCALE: int: minimap custom scale, in percents; if value<=100: auto-detect.
  • PROP_MINIMAP_AT_LEFT: bool: minimap is shown on the left side.
  • PROP_MICROMAP: bool: micromap is visible.
  • PROP_LINKS_SHOW: bool: enable hyperlinks underlining.
  • PROP_LINKS_REGEX: str: regular expression for hyperlinks.
  • PROP_LINKS_CLICKS: int: how mouse clicks activate hyperlinks. 0: disabled, 1: single click, 2: double click.
  • PROP_TAB_SPACES: bool: tab-key inserts spaces, not tab-char.
  • PROP_TAB_SIZE: int: size of tab-char.
  • PROP_TAB_SMART: bool: smart-tabs option, known from many text editors.
  • PROP_TAB_COLLECT_MARKERS: bool: tab-key collects (jumps to and deletes) markers.
  • PROP_TAB_COLOR: int: color of ui-tab title background, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
  • PROP_TAB_COLOR_FONT: int: color of ui-tab title font, integer RGB value (e.g. 0x00FF00 is green); COLOR_NONE if not set.
  • PROP_TAB_TITLE: str: custom title of ui-tab; setting to empty string removes the custom title.
  • PROP_TAB_TITLE_REASON: str (1 char): reason of current ui-tab title.
    • "u": Usual untitled tab
    • "s": App-special untitled tab, e.g. "RegEx search", "Welcome"
    • "f": Title was calculated from filename
    • "p": Title was set by plugin API
  • PROP_TAB_ICON: int: index of ui-tab icon, ie index in imagelist, which handle you can get via app_proc(PROC_GET_TAB_IMAGELIST).
  • PROP_TAB_PINNED: bool: ui-tab is "pinned" (shows additional confirmation on closing).
  • PROP_TAB_UI_SHOW: bool: ui-tab header is visible on the tabs-bar.
  • PROP_INDENT_SIZE: int: size of indent for Indent/Unindent commands. N>0: indent in spaces, N<0: indent in tabs, N=0: indent from PROP_TAB_SIZE/PROP_TAB_SPACES.
  • PROP_INDENT_KEEP_ALIGN: bool: command Unindent keeps alignment of block edge, ie don't unindent if any line reached column 0.
  • PROP_INDENT_AUTO: bool: makes next line also indented on Enter command.
  • PROP_INDENT_KIND: int: kind of auto-indented line, see description of app option "indent_kind".
  • PROP_FOLD_ALWAYS: bool: always show icons on "folding" gutter bar, otherwise show them only on mouse over.
  • PROP_FOLD_ICONS: int: icon set for "folding" gutter bar. Possible values: 0, 1.
  • PROP_FOLD_TOOLTIP_SHOW: bool: show floating tooltip when mouse hovers [...] mark for folded block.
  • PROP_LAST_LINE_ON_TOP: bool: allow to scroll control, so last line shows on top.
  • PROP_FOCUSED: bool: editor is focused. When changing: for editor in UI-tab it focuses also editor's tab. Cannot change True to False.
  • PROP_HILITE_CUR_COL: bool: highlight current column.
  • PROP_HILITE_CUR_LINE: bool: highlight current line.
  • PROP_HILITE_CUR_LINE_MINIMAL: bool: highlight current line, only minimal part of line.
  • PROP_HILITE_CUR_LINE_IF_FOCUS: bool: highlight current line, only when editor focused.
  • PROP_CODETREE: bool: enable standard code-tree filling.
  • PROP_CODETREE_SUBLEXER: bool: enable code-tree to show nodes from sublexer(s) of current lexer.
  • PROP_EDITORS_LINKED: bool: enable sharing of the same text by primary/secondary editors in file tab.
  • PROP_ONE_LINE: bool: editor has single-line mode.
  • PROP_MODERN_SCROLLBAR: bool: use custom-drawn themed scrollbars.
  • PROP_SAVE_HISTORY: bool: allows to save history (caret, scroll pos, folding etc) on file closing.
  • PROP_PREVIEW: bool: editor is inside "Preview tab" (it has italic caption). Currently only False value can be written.
  • PROP_UNDO_GROUPED: bool: editor undo/redo is grouped.
  • PROP_UNDO_LIMIT: int: max count of simple actions, which can be undone.
  • PROP_UNDO_DATA: str: string representation of Undo data. See #Format_of_serialized_Undo.
  • PROP_REDO_DATA: str: string representation of Redo data.
  • PROP_ZEBRA: int: if 0, "zebra" mode is not active; if >0, it is alpha-blend value (1..255) of active zebra mode.
  • PROP_ZEBRA_STEP: int: step (in lines) of "zebra" mode.
  • PROP_FONT: 2-tuple (str, int): normal font: name, size.
  • PROP_FONT_B: 2-tuple (str, int): bold font: name, size. Empty name: not used.
  • PROP_FONT_I: 2-tuple (str, int): italic font: name, size. Empty name: not used.
  • PROP_FONT_BI: 2-tuple (str, int): bold+italic font: name, size. Empty name: not used.
  • PROP_SPLIT: 2-tuple: information about primary/secondary editors splitting as tuple (split_kind, split_pos).
    • "split_kind": str: "-" (not splitted), "v" (splitted vertically), "h" (splitted horizontally).
    • "split_pos": int: part of entire size for secondary editor, multiplied by 1000 (e.g. 500 is half of size).
  • PROP_SAVING_FORCE_FINAL_EOL: bool: on saving file, ensure the newline at end of document.
  • PROP_SAVING_TRIM_SPACES: bool: on saving file, trim trailing whitespaces.
  • PROP_SAVING_TRIM_FINAL_EMPTY_LINES: bool: on saving file, trim redundant empty lines at end of document.
  • PROP_THEMED: bool: for editors out of UI-tabs, allows to automatically apply current theme on app theme changing.
  • PROP_COMBO_ITEMS: only for "editor_combo" control, contents of drop-down list. On getting: list of str. On setting: value must be str with '\n'-separated items.
  • PROP_MASKCHAR: str: character to show in masked-mode.
  • PROP_MASKCHAR_USED: bool: masked-mode is activated.
  • PROP_NUMBERS_ONLY: bool: allow to input only numbers.
  • PROP_NUMBERS_NEGATIVE: bool: additional to PROP_NUMBERS_ONLY, allow negative numbers<0.
  • PROP_COMMAND_LOG_LIMIT: int: maximal count of items in the list returned by PROP_COMMAND_LOG.
  • PROP_DIM_UNFOCUSED: int: for unfocused editor, dim the background color by specified percents (ranges is -250...250, 0: disabled).
  • PROP_V_MODE: int: mode of binary viewer. Setting it for viewer to one of VMODE_ values, changes viewer mode. Setting it for editor to one of VMODE_ values, switches editor to viewer in the given mode. Setting it for viewer to VMODE_NONE, switches viewer to editor.
  • PROP_V_POS: int: for binary viewer, scroll position.
  • PROP_V_SEL_START: int: for binary viewer, selection start offset.
  • PROP_V_SEL_LEN: int: for binary viewer, selection length.
  • PROP_V_WIDTH: int: for binary viewer, width of text in mode VMODE_BINARY.
  • PROP_V_WIDTH_HEX: int: for binary viewer, width of text in mode VMODE_HEX.
  • PROP_V_WIDTH_UHEX: int: for binary viewer, width of text in mode VMODE_UNICODE_HEX.
  • PROP_V_ENC: str: for binary viewer, its encoding.

props vs options

Many get_prop/set_prop ids correspond to CudaText options. List of corresponding pairs:

  • PROP_CARET_VIRTUAL - "caret_after_end"
  • PROP_GUTTER_ALL - "gutter_show"
  • PROP_GUTTER_BM - "gutter_bookmarks"
  • PROP_GUTTER_FOLD - "gutter_fold"
  • PROP_HILITE_CUR_COL - "show_cur_column"
  • PROP_HILITE_CUR_LINE - "show_cur_line"
  • PROP_HILITE_CUR_LINE_MINIMAL - "show_cur_line_minimal"
  • PROP_HILITE_CUR_LINE_IF_FOCUS - "show_cur_line_only_focused"
  • PROP_INDENT_AUTO - "indent_auto"
  • PROP_INDENT_KEEP_ALIGN - "unindent_keeps_align"
  • PROP_INDENT_KIND - "indent_kind"
  • PROP_INDENT_SIZE - "indent_size"
  • PROP_LAST_LINE_ON_TOP - "show_last_line_on_top"
  • PROP_MARGIN - "margin"
  • PROP_MARGIN_STRING - "margin_string"
  • PROP_MICROMAP - "micromap_show"
  • PROP_MINIMAP - "minimap_show"
  • PROP_RULER - "ruler_show"
  • PROP_TAB_SIZE - "tab_size"
  • PROP_TAB_SPACES - "tab_spaces"
  • PROP_UNPRINTED_ENDS - "unprinted_ends"
  • PROP_UNPRINTED_END_DETAILS - "unprinted_end_details"
  • PROP_UNPRINTED_SHOW - "unprinted_show"
  • PROP_UNPRINTED_SPACES - "unprinted_spaces"
  • PROP_UNPRINTED_SPACES_TRAILING - "unprinted_spaces_trailing"
  • PROP_WRAP - "wrap_mode"

Editor.bookmark

bookmark(id, nline, nkind=1, ncolor=-1, text="", auto_del=True, show=True, tag=0)

Controls bookmarks. Possible values of "id":

  • BOOKMARK_GET_ALL: Returns list of bookmarks, as list of dict. Param "nline" ignored. Dict keys are:
    • "line": int
    • "kind": int
    • "tag": int
    • "hint": str
    • "auto_delx": enum, 0: don't auto-delete; 1: auto-delete; 2: auto-delete if global option is set
    • "show_in_list": bool
  • BOOKMARK_GET_LIST: Returns list of line indexes, which have bookmarks. Param "nline" ignored.
  • BOOKMARK_GET_PROP: Returns properties of bookmark at line index, given by param "nline". Returns dict, like for BOOKMARK_GET_ALL, or None.
  • BOOKMARK_SET: Sets bookmark.
    • Param "nline": int: line index of bookmark.
    • Param "nkind": int: kind of bookmark: 1 means usual bookmark with usual color and icon. Other kind values mean custom bookmark, which must be setup via BOOKMARK_SETUP.
    • Param "text": str: tooltip, shown when mouse moves over bookmark gutter icon.
    • Param "auto_del": bool: auto delete bookmark on deleting its text line.
    • Param "show": bool: show bookmark in "Go to bookmark" dialog.
    • Param "tag": int: some value attached to bookmark.
  • BOOKMARK_CLEAR: Removes bookmark from line, specified by "nline" param.
  • BOOKMARK_CLEAR_ALL: Removes all bookmarks ("nline" ignored).
  • BOOKMARK_DELETE_BY_TAG: Removes all bookmarks, which have the tag, given by "tag" param.
  • BOOKMARK_SETUP: Configures bookmarks background color and icon for the given "kind". This setup is global, ie it is shared by all editors in UI-tabs. Once you applied some color and/or icon here, it will be shared by bookmarks in all editors in UI-tabs.
    • Param "nkind": Integer kind of bookmarks which will be configured.
    • Param "ncolor": Color of bookmarked line.
      • Can be COLOR_NONE to not use background color.
      • Can be COLOR_DEFAULT to use current themed color.
    • Param "text": Path to icon file for gutter, 16x16 .bmp or .png file. Empty str: don't show icon.

Additional internal list Bookmarks2 exists, which holds list of background bookmarks. They have lower paint priority than usual bookmarks, so background bookmark is painted only if usual bookmark not exists. Actions BOOKMARK2_* are used for Bookmarks2 list, actions have the same meaning. Background bookmarks don't have gutter icon and mouse-over tooltip. They share the single setup with usual bookmarks.

  • BOOKMARK2_GET_ALL
  • BOOKMARK2_GET_PROP
  • BOOKMARK2_SET
  • BOOKMARK2_CLEAR
  • BOOKMARK2_CLEAR_ALL
  • BOOKMARK2_DELETE_BY_TAG

Notes:

  • Param "nkind" must be in the range 1..63.
  • Param "nkind" values 2..9 have setup by default: they have blue icons "1" to "8".

Editor.decor

decor(id, line=-1, tag=0, text="", color=0, bold=False, italic=False, image=-1, auto_del=True)

Controls decorations on gutter. It is used to show some visual marks, which look like bookmark icons, but independent of bookmarks. Possible values of "id":

  • DECOR_GET_ALL:
    • If param "line" <0: returns list of all decorations, as list of dict.
    • If param "line" >=0: return list of decorations for the given line index, as list of dict.
  • DECOR_GET: Returns decoration for given line, as dict. Params used: "line".
  • DECOR_SET: Sets decoration for given line. Returns bool: line index correct, item added. Params used:
    • "line": int, line index.
    • "tag": int, some value attached to item.
    • "text": str, text to show.
      • If "text" is not empty, decoration will be text.
      • If "text" is empty, decoration depends on "image" value, see below.
    • "color": int, color of text decoration.
    • "bold": bool, use bold font for text decoration.
    • "italic": bool, use italic font for text decoration.
    • "image": int, icon index from decoration imagelist.
      • If "text" is empty and "image" is >=0, decoration will be icon.
      • If "text" is empty and "image" is -1, decoratiton will be cell background filled with "color".
    • "auto_del": bool, auto-delete decoration, when its line is deleted.
  • DECOR_DELETE_BY_LINE: Deletes single decoration for given line. Params used: "line".
  • DECOR_DELETE_BY_TAG: Deletes all decorations with the given tag. Param used: "tag".
  • DECOR_DELETE_ALL: Deletes all decorations.
  • DECOR_GET_IMAGELIST: Returns int handle of decoration imagelist (default size is 16x16).

Notes:

  • Decor item's "text" can contain 2 items if you use chr(1): caption + chr(1) + tooltip.
  • Decoration list allows 2 items for the same line number. One of items (it can be added first or last) must be "background filler" (ie empty "text" and "image" is -1), and another one must be "not background filler".

Editor.folding

folding(id, index=-1, item_x=-1, item_y=-1, item_y2=-1, item_staple=False, item_hint="", item_x2=0, item_tag=0)

Performs action on folding ranges. Possible values of "id":

  • FOLDING_ENUM: Returns list of folding ranges. If param "item_y"<0, returns list of all ranges; otherwise makes filtering of ranges by params "item_y" and "item_y2" - ie, gets only ranges which contain line indexes from "item_y" to "item_y2" inclusive. Each list item is dict with fields:
    • "x": int, column index of range beginning.
    • "y": int, line index of range beginning.
    • "x2": int, column index of range ending.
    • "y2": int, line index of range ending.
    • "staple": bool, indicates that range has 'block staple'.
    • "folded": bool, indicates that range is folded.
    • "hint": string, hint of range (it is rendered when range is folded).
    • "tag": int 64-bit, tag value. For example, it is -1 for ranges created by CudaText command "fold selected lines".
  • FOLDING_FOLD: Folds range with given index (index in unfiltered list returned by FOLDING_ENUM). Params used: "index".
  • FOLDING_FOLD_ALL: Folds all ranges.
  • FOLDING_FOLD_LEVEL: Unfolds all ranges, then folds ranges starting with given nesting level. Params used: "index": nesting level, 0..9.
  • FOLDING_UNFOLD: Unfolds range with given index (index in unfiltered list returned by FOLDING_ENUM). Params used: "index".
  • FOLDING_UNFOLD_ALL: Unfolds all ranges.
  • FOLDING_UNFOLD_LINE: Unfolds all ranges containing editor line with given index. Params used: "index".
  • FOLDING_ADD: Adds folding range. Life time of this range is until lexer analisys runs (it clears ranges and adds ranges from lexer), which runs after any text change. Params used:
    • "item_x": column index (offset in line) of range start.
    • "item_y": line index of range start.
    • "item_x2" (optional): column index (offset in line) of range ending.
    • "item_y2": line index of range ending.
    • "item_staple" (optional): bool, indicates that range has 'block staple'.
    • "item_hint" (optional): str, hint which is shown when range is folded.
    • "item_tag" (optional): int 64-bit, tag value. For example, it is -1 for ranges created by CudaText command "fold selected lines".
    • "index": if it's valid range index (0-based), range inserts at this index, otherwise range appends.
  • FOLDING_DELETE: Deletes folding range with given index (index in unfiltered list returned by FOLDING_ENUM). Params used: "index".
  • FOLDING_DELETE_ALL: Deletes all folding ranges. Params used: none except "id".
  • FOLDING_FIND: Finds index of range (index in unfiltered list returned by FOLDING_ENUM). Returns None if not found. Params used: "item_y" is line index at which range begins.
  • FOLDING_CHECK_RANGE_INSIDE: For 2 ranges, which indexes given by "index" and "item_x", detects: 1st range is inside 2nd range. Returns bool. Returns False if indexes incorrect.
  • FOLDING_CHECK_RANGES_SAME: For 2 ranges, which indexes given by "index" and "item_x", detects: ranges are "equal" (x, y, y2 in ranges may differ). Returns bool. Returns False if indexes incorrect.

Editor.get_sublexer_ranges

get_sublexer_ranges()

Returns list of ranges which belong to nested lexers (sublexers of current lexer for entire file, e.g. "JavaScript" inside "PHP", "CSS" inside "HTML"). Returns list of 5-tuples, or None if no ranges. Each tuple is:

  • str: sublexer name
  • int: start column (0-based)
  • int: start line (0-based)
  • int: end column
  • int: end line

Editor.get_token

get_token(id, index1=0, index2=0)

Returns info about lexer "tokens". "Token" is minimal text fragment for lexer, e.g. one identifier, one operator, one whole comment, one whole string. Each token has its color from lexer properties or color theme. Function returns None if no lexer is active in editor.

Possible values of "id":

  • TOKEN_GET_KIND: For text position given by "index1" (column) and "index2" (line), returns kind of lexer token:
    • "c": syntax comment
    • "s": syntax string
    • "a": any other kind
  • TOKEN_LIST: Returns all tokens, as list of dict. Params "index1", "index2" are ignored. Returns None if no lexer active. Dict keys are:
    • "x1": start column (0-based)
    • "y1": start line (0-based)
    • "x2": end column
    • "y2": end line
    • "str": text of token (can be multi-line with "\n")
    • "style": lexer style of token (lexer dependent)
    • "ki": index of token kind (0-based), in the list returned by lexer_proc()
    • "ks": kind of syntax element: "c" - comment, "s" - string, "a" - any other
  • TOKEN_LIST_SUB: Like TOKEN_LIST, but returns tokens only for given lines range, from "index1" to "index2" inclusive. Index in "index2" can be too big, this makes list until end of file.

Editor.get_wrapinfo

get_wrapinfo(param1=-1, param2=-1)

Gets info about wrapping of lines on screen. It allows to calculate, at which positions long lines are wrapped (when "word wrap mode" is on). It allows to see, which text parts are folded.

Returns list of dict, for specified lines range. Dict items has keys:

  • "line": int: Original line index, for this part.
  • "char": int: Char index (1-based, for UTF-16 stream of chars), at which this part starts. It is >1, for next parts of long wrapped line.
  • "len": int: Length of this part. It equals to entire line length, if line is not wrapped.
  • "indent": int: Screen indent in spaces, for this part, it's used in rendering when option "Show wrapped parts indented" is on.
  • "final": int: State of this part. 0: final part of the entire line; 1: partially folded part; 2: first or middle part of the entire line.
  • "initial": bool: True if part is initial for the entire (wrapped) line, False if it is continuation (ie, wrapped) part.

Parameter "param1" is the minimal line index (0-based) for which to return the information. Parameter "param2" is the maximal line index. Notes:

  • If both "param1" and "param2" are default, returns entire document information.
  • If "param2" < "param1", returns empty list.
  • If "param1" < 0, its value is replaced to the minimal possible index.
  • If "param1" specifies incorrect line index, returns empty list.
  • If "param2" is < 0 or specifies incorrect line index, its value is replaced to the maximal possible index.
  • Length of resulting list equals the lines count for non-wrapped document. For wrapped document, you get 1 or more list items per each document line.

Editor.markers

markers(id, x=0, y=0, tag=0, len_x=0, len_y=0, line_len=0)

Controls markers (used e.g. in Snippets plugin). Possible values of "id":

  • MARKERS_GET: Returns list of markers. Each list item is [x, y, len_x, len_y, tag]. Returns None if no markers.
  • MARKERS_GET_DICT: Returns list of markers. Each list item is dict with the following keys:
    • "x", "y": Position of markers.
    • "len_x", "len_y": Length of selection, which is applied when this marker is "collected". See description of MARKERS_ADD.
    • "tag": Tag of marker.
    • "line_len": Line-length of marker. If <0, line is painted to the left. If >0, line is painted to the right.
    • "micromap": Marker is shown only on micromap.
  • MARKERS_ADD: Adds marker. Also returns number of markers. Params:
    • "x", "y": Position of marker (like caret position).
    • "tag": Some int value attached to marker. Value>0 is needed if you want to place multi-carets when command "goto last marker (and delete)" runs. All markers with the same tag>0 will get multi-carets (after markers will be deleted).
    • "len_x", "len_y": Selection length. It's applied when marker is "collected" by command "goto last marker".
      • if len_y==0: len_x is length of selection (single line),
      • if len_y>0: len_y is y-delta of selection-end, and len_x is absolute x-pos of selection-end.
    • "line_len": Line length, in chars. If 0, not used. If <0, line is painted to the left. If >0, line is painted to the right.
  • MARKERS_DELETE_ALL: Deletes all markers.
  • MARKERS_DELETE_LAST: Deletes last added marker.
  • MARKERS_DELETE_BY_TAG: Deletes all markers with the given tag. Param "tag": tag value.
  • MARKERS_DELETE_BY_INDEX: Deletes marker by its index in the markers list. Param "tag": index (0-based).
  • MARKERS_DELETE_BY_POS: Deletes markers for specified text position.
    • If param "x">=0, deletes markers for position given by "x" and "y"
    • If param "x"<0, deletes all markers for line given by param "y"
  • MARKERS_GET_DUPS: Gets "duplicates for the same x/y are allowed" flag, bool value.
  • MARKERS_SET_DUPS: Sets "duplicates for the same x/y are allowed" flag (it will be used on next item adding). Param "tag": 0 or 1.

Editor.attr

attr(id, tag=0, x=0, y=0, len=1,
     color_font=COLOR_NONE, color_bg=COLOR_NONE, color_border=COLOR_NONE,
     font_bold=0, font_italic=0, font_strikeout=0,
     border_left=0, border_right=0, border_down=0, border_up=0,
     show_on_map=False, map_only=0 )

Controls additional color attributes. Possible values of "id":

  • MARKERS_ADD: Adds fragment with specified properties. Also returns number of fragments. Parameters:
    • "tag": Some int value attached to fragment (different plugins should add fragments with different tags).
    • "x", "y": Position of fragment start (text position like caret).
    • "len": Length of fragment in chars.
      • If len<0, and "show_on_map" is set, it will be multi-line micromap fragment with specified height=-len.
    • "color_*": Color values (RGB) for font, background, borders.
    • "font_*": Font attributes: 0 - off, 1 - on.
    • "border_*": Border types for edges, int value 0..6: none, solid, dash, solid 2pixel, dotted, rounded, wave.
    • "show_on_map": How to show this fragment on micromap:
      • int value>=0: Show on micromap column with given tag. Don't pass value=0, because micromap column with tag=0 is reserved.
      • int value=-1: Don't show on micromap.
      • int value=-2: Show on micromap as full-width fragment (over full micromap width). Fragment color will be XOR'ed with colors of all micromap columns.
      • True: Show on micromap column 1.
      • False: Don't show on micromap.
    • "map_only": int: 0: Show on text area only; 1: Show on micromap only; 2: Show both on text area and micromap.
  • MARKERS_ADD_MANY: Adds one or multiple fragments at once. Also returns number of fragments. Parameters:
    • "x", "y", "len": The same as for MARKERS_ADD, but can be also list/tuple of int. Lists/tuples must contain the equal number of elements (otherwise the minimal number of elements will be used).
    • "color_*": Can be one value or list/tuple of values. Length of list/tuple is not limited.
    • "font_*": Can be one value or list/tuple of values. Length of list/tuple is not limited.
    • other parameters: The same as for MARKERS_ADD.
  • MARKERS_GET: Returns list of fragments, or None. Each item is list of int, corresponding to Editor.attr() params (bool values will be 0 or 1).
  • MARKERS_GET_DICT: Returns list of fragments. Each item is dict, with keys named like parameters of Editor.attr.
  • MARKERS_DELETE_ALL: Deletes all fragments.
  • MARKERS_DELETE_LAST: Deletes last added fragment.
  • MARKERS_DELETE_BY_TAG: Deletes all fragments with the given tag. Param "tag": tag value.
  • MARKERS_DELETE_BY_INDEX: Deletes fragment by its index in the list. Param "tag": index (0-based).
  • MARKERS_DELETE_BY_POS: Deletes fragments for specified text position.
    • If param "x">=0, deletes fragments for position given by "x" and "y"
    • If param "x"<0, deletes all fragments for line given by param "y"
  • MARKERS_GET_DUPS: Gets "duplicates for the same x/y are allowed" flag, bool value.
  • MARKERS_SET_DUPS: Sets "duplicates for the same x/y are allowed" flag (it will be used on next item adding). Param "tag": 0 or 1.

Notes:

  • Fragment list is sorted by (x, y) pair.
  • Duplicate fragments, ie with the same (x, y) pair, are allowed. Last added fragments go to the later indexes, and all fragments are painted in their order in the fragment list, so last added fragments are painted over previous ones.
  • Param "color_bg" can be COLOR_NONE: it uses usual back-color.
  • Params "color_font", "color_border" can be COLOR_NONE: it uses usual text-color.

Editor.hotspots

hotspots(id, tag=0, tag_str="", pos="")

Controls hotspot ranges. When mouse cursor moves in/out of hotspot, event on_hotspot is called.

Possible values of "id":

  • HOTSPOT_ADD: Adds hotspot. Returns bool: params correct, hotspot added. Params:
    • "pos": 4-tuple of int, text coords: (x_start, y_start, x_end, y_end)
    • "tag": optional int value
    • "tag_str": optional str value
  • HOTSPOT_GET_LIST: Returns list of hotspots. Each item is dict with keys:
    • "pos": 4-tuple of int
    • "tag": int
    • "tag_str": str
  • HOTSPOT_DELETE_ALL: Deletes all hotspots.
  • HOTSPOT_DELETE_LAST: Deletes last hotspot.
  • HOTSPOT_DELETE_BY_TAG: Deletes all hotspots with the given tag, "tag" param.

Misc

Editor.save

save(filename="", as_copy=False)

Saves editor's text to file. Returns bool: file was saved without errors.

Param "filename" (str): suggested filename to save to.

Param "as_copy" (bool):

  • False: Editor uses new filename (if it's not empty). Untitled document becomes titled. If filename is empty and document is untitled, function shows "Save as" dialog first.
  • True: Creates the file but editor doesn't use new filename. Filename must be not empty, otherwise function will return False.

Notes:

  • Function can be used for editor created in dlg_proc() only if param "as_copy" is False, otherwise it will return None.
  • For "as_copy" = False, code performs more detailed write-error checks.

Editor.cmd

cmd(code, text="")

Runs any command in editor by its integer code. See possible codes in module "cudatext_cmd".

Param "text" is needed only for rare commands, mainly for "cCommand_TextInsert".

Notes:

  • When you perform some caret-positioning command (e.g. "cCommand_GotoTextEnd") in not yet painted editor-control, it doesn't run OK. Reason: editor must be properly inited which happens on first painting. If you need to place the caret on form showing ("dlg_proc" API), do it in form's "on_show" event. Maybe you need also to start a timer ("timer_proc" API) which will run the caret command.

Editor.focus

focus()

Activates editor's tab and focuses editor itself. It's needed when you want to activate inactive tab. You can get Editor objects of inactive tabs using ed_handles().

Editor.lock, Editor.unlock

lock()
unlock()

Functions lock, then unlock editor. "Locked" editor is not painted and shows only hourglass (or another) icon.

Call "lock" increases counter, "unlock" decreases this counter (it's safe to call "unlock" more times, counter will be 0). When counter is >0, editor is locked.

Editor.convert

convert(id, x, y, text="")

Converts something in editor. Possible values of "id":

  • CONVERT_CHAR_TO_COL: Convert char coordinates (x,y) to column coordinates (column,y), using current tabulation size. Param "text" is ignored. Returns 2-tuple of int.
  • CONVERT_COL_TO_CHAR: Convert column coordinates (x,y) to char coordinates (chars,y). Param "text" is ignored. Returns 2-tuple of int.
  • CONVERT_LINE_TABS_TO_SPACES: Convert line, given in param "text", from tabulation-chars to spaces, using current tabulation size. Returns string. Returns original line, if it does not contain tabulation-chars.
  • CONVERT_SCREEN_TO_LOCAL: Convert pixel coordinates (x,y), from screen-related to control-related. Param "text" is ignored. Returns 2-tuple of int.
  • CONVERT_LOCAL_TO_SCREEN: Convert pixel coordinates (x,y), from control-related to screen-related. Param "text" is ignored. Returns 2-tuple of int.
  • CONVERT_PIXELS_TO_CARET: Convert pixel control-related coords (x,y) to text position (column,line). Param "text" is ignored. Returns 2-tuple of int.
  • CONVERT_CARET_TO_PIXELS: Convert text position (x,y) to pixel control-related coords (x,y). Param "text" is ignored. Returns 2-tuple of int.
  • CONVERT_OFFSET_TO_CARET: Convert absolute offset (0-based) given by param "x", to text position (column,line). Params "y", "text" are ignored. Returns 2-tuple of int.
  • CONVERT_CARET_TO_OFFSET: Convert text position (x,y) to absolute text offset (0-based). Param "text" is ignored. Returns int.

Returns None if params are incorrect, or cannot calculate the result.

Editor.complete

complete(text, len1, len2, selected=0, alt_order=False)

Shows auto-completion listbox with given items.

Function returns None and listbox stays open. When user chooses listbox item, its data is inserted.

  • Param "text": string with items, must be formatted as shown in the ATSynEdit#Auto-completion_lists.
  • Param "len1": count of chars to the left of the caret, to be replaced.
  • Param "len2": count of chars to the right of the caret, to be replaced.
  • Param "selected": index of initially selected listbox item (0-based).
  • Param "alt_order":
    • alt_order=False: pass items in each line: prefix, id, desc. Listbox shows prefix at the left edge.
    • alt_order=True: pass items in each line in such order: id, prefix, desc. Listbox shows id at the left edge. Use it if plugin needs to show long "prefixes".

Note:

  • Listbox disappears if you move caret or type text, unlike usual auto-completion listboxes (they can recalculate items for new caret pos).

If an item begins with "<html>", #HTML formatting is allowed in this item.

Editor.complete_alt

complete_alt(text, snippet_id, len_chars, selected=0)

Shows alternative completion listbox. This allows to insert complex snippets, not only simple words.

Function returns None and listbox stays open. When user chooses listbox item, event "on_snippet" is called in plugin.

Function params:

  • Param "text": "\n"-separated lines, one line per snippet. Each line has 3 columns "\t"-separated.
    • Column 1 is shown on left side of listbox (good to show here name of function)
    • Column 2 is shown on right side of listbox (good to show here type of function)
    • Column 3 is snippet text in any format. Can contain "\t" but not "\n". Can have any chars escaped in any form.
  • Param "snippet_id": Some short string just to identify snippet between different plugins. Different plugins provide snippets in different formats, they must insert only their own snippets, so each plugin must check kind of the snippet, passed to "on_snippet" event.
  • Param "len_chars": Listbox is shown lefter than the caret, by specified count of chars.
  • Param "selected": Index of initially selected listbox item (0-based).

After user has chosen some item in the completion listbox, event "on_snippet" will be called with parameters:

  • Param "snippet_id": Value from complete_alt() call.
  • Param "snippet_text": Text of chosen snippet.

If an item begins with "<html>", #HTML formatting is allowed in this item.

Editor.gap

gap(id, num1, num2, tag=-1, size=0, color=COLOR_NONE)

Performs action on inter-line gaps (they don't overlap text above/below). Possible values of "id":

  • GAP_GET_ALL: Returns list of gaps, as list of dict. Dict keys are:
    • "line": int: Line index; or -1 for gap before the first line.
    • "tag": int: Tag.
    • "size": int: Height in pixels.
    • "color": int: Color.
    • "bitmap": 2-tuple of int: Size of bitmap, or (0, 0) if no bitmap.
  • GAP_MAKE_BITMAP: Action is needed only if you want to paint bitmap in gap, it's not needed for empty gaps. Makes new bitmap for future gap. Size of bitmap is (num1, num2). Returns 2-tuple (id_bitmap, id_canvas).
    • "id_bitmap": bitmap handle, needed to later call GAP_ADD.
    • "id_canvas": canvas handle, needed to paint on bitmap, by canvas_proc().
  • GAP_ADD: Adds gap to editor. Returns bool: params correct, gap added. Params:
    • "num1": int: Line index; can be -1 for gap before the first line.
    • "num2": int: Can be:
      • 0: gap is empty, filled with specified color;
      • handle of bitmap (created via GAP_MAKE_BITMAP): place bitmap in the gap;
      • handle of dialog (created via dlg_proc()): place dialog in the gap.
    • "tag": int: Some value, to separate gaps from several plugins.
    • "size": int: If >0, it is gap height in pixels. If 0, gap height is calculated from bitmap handle.
    • "color": int: If not COLOR_NONE, then it's gap background color.
  • GAP_DELETE_ALL: Deletes all gaps.
  • GAP_DELETE: Deletes gaps for the given line indexes range, from value of "num1" to value of "num2" (inclusive).
  • GAP_DELETE_BY_TAG: Deletes gaps which have the tag, given by param "tag".

Example plugin:

from cudatext import *
class Command:
    def run(self):
        for i in range(ed.get_line_count()//2):
            self.do_gap(i*2)

    def do_gap(self, num):
        id_bitmap, id_canvas = ed.gap(GAP_MAKE_BITMAP, 600, 50)
        canvas_proc(id_canvas, CANVAS_SET_BRUSH, color=0xa0ffa0)
        canvas_proc(id_canvas, CANVAS_POLYGON, '200,0,300,30,200,50')
        canvas_proc(id_canvas, CANVAS_SET_BRUSH, color=0xffffff, style=BRUSH_CLEAR)
        canvas_proc(id_canvas, CANVAS_TEXT, x=230, y=10, text='gap %d'%(num+1))
        canvas_proc(id_canvas, CANVAS_SET_BRUSH, color=0xffffff, style=BRUSH_SOLID)
        ed.gap(GAP_ADD, num, id_bitmap)

Editor.dim

dim(id, index=0, index2=0, value=100)

Controls dim (shade, fade) ranges, which blend text font color with background color. Dim value is 0..255, 0 means "no effect", 255 means "text is transparent".

Possible values of "id":

  • DIM_ADD: Adds new range.
    • Param "index": index of first range line (0-base).
    • Param "index2": index if last range line (value bigger than line count is allowed).
    • Param "value": dim value.
  • DIM_DELETE: Deletes one range. Param "index" is index of range (0-base).
  • DIM_DELETE_ALL: Deletes all ranges.
  • DIM_ENUM: Enumerates ranges. Gives list of 3-tuples (line_from, line_to, dim_value).

Editor.action

action(id, param1="", param2="", param3="")

Performs some action in editor. Possible values of "id":

  • EDACTION_UPDATE: Repaint editor.
    • "param1": Can be empty or "0" or "1". If "1", WrapInfo internal structure will be updated. WrapInfo update is needed after text changes, if program did not detect that changes automatically (in this case simple repaint will be incorrect).
  • EDACTION_UNDOGROUP_BEGIN, EDACTION_UNDOGROUP_END: Begins/ends an undo-group. Text editions, which are enclosed in undo-group, are handled by Undo/Redo command in a single step. Other text editions are handled in a single or multiple steps, it depends on CudaText option.
  • EDACTION_FIND_ONE: Perform text search, get match as 4-tuple of int (start_x, start_y, end_x, end_y) or None if not found. This uses finder independent from CudaText Find/Replace dialog, you must configure this finder via options string.
  • EDACTION_REPLACE_ONE: Perform text search+replace, get match as 4-tuple of int (start_x, start_y, end_x, end_y) or None if not found. This uses finder independent from CudaText Find/Replace dialog, you must configure this finder via options string.
    • "param1": String to find.
    • "param2": String to replace with.
    • "param3": Search options, see #Finder_options_as_string.
    • Note: returns False for incorrect RegEx.
  • EDACTION_REPLACE_ALL: Perform text search+replace in the entire document (note: ignoring caret position), get count of replacements. This uses finder independent from CudaText Find/Replace dialog, you must configure this finder via options string.
    • "param1": String to find.
    • "param2": String to replace with.
    • "param3": Search options, see #Finder_options_as_string.
    • Note: returns False for incorrect RegEx.
  • EDACTION_FIND_ALL: Perform text search and get all matches in a list. Result list items are 4-tuples of int: (start_x, start_y, end_x, end_y). This uses finder independent from CudaText Find/Replace dialog, you must configure this finder via options string.
    • "param1": Search string.
    • "param2": Search options, see #Finder_options_as_string.
    • "param3": Optional. Maximal line length, 32-bit signed integer, default is 0x7FFFFFFF. Lines longer than this value will be skipped during search.
    • Note: returns False for incorrect RegEx.
  • EDACTION_FIND_BRACKETS: Find position of nearest opening bracket with its pair bracket. Returns 4-tuple (col_start, line_start, col_end, line_end), where line_end<0 if brackets not found.
    • "param1": Text position as 2-tuple (column, line).
    • "param2": String with allowed bracket pairs. Can have these pairs: () [] {} <>.
    • "param3": Max distance, in lines, to the pair bracket. Must be 32-bit signed int.
  • EDACTION_SHOW_POS: Make text position visible without caret moving. Returns True if params correct and scrolling occurred, returns False if params correct and no scrolling occurred, returns None if params not correct.
    • "param1": Text position as 2-tuple (column, line).
    • "param2": Indentation of text position from edges as 2-tuple (indent_horz, indent_vert). Values meaning is like for CudaText options "find_indent_horz", "find_indent_vert".
  • EDACTION_CODETREE_FILL: Fill some visual TreeView control (it can be standard code-tree control, or TreeView control in some form) with editor's code-tree information. Param "param1" must be TreeView handle (to use with tree_proc()). Returns True if lexer is set and information is read, otherwise False.
  • EDACTION_LEXER_SCAN: Run lexer parsing (if lexer is set) from line index, given by "param1". Waits until parsing finishes.
  • EDACTION_APPLY_THEME: Apply current UI-theme colors to editor control. So you don't have to apply all COLOR_ID_nnn properties via Editor.set_prop().
  • EDACTION_EXPORT_HTML: Create HTML file or buffer from editor's text with syntax highlighting. For file, returns bool: file is created. Param "param1" must be dict with the following optional keys:
    • "file_name": str: Full path of file, or special value "-" to return HTML text as function result. This key is mandatory, empty value is not allowed.
    • "title": str: Title of HTML page.
    • "font_name": str: Font name. Empty value is allowed, some standard monospaced font will be used.
    • "font_size": int: Font size, in HTML "px".
    • "with_numbers": bool: Make additional table cell with line numbers.
    • "color_back": int: RGB color of page background.
    • "color_numbers": int: RGB color of line numbers.
    • "line_begin": int: Index of beginning line (0-based). Default is 0.
    • "line_end": int: Index of ending line (0-based). Value after maximal line index is allowed, it is auto-limited. Default is "count of lines".
    • "col_begin": int: Beginning offset in beginning line (0-based). Default is 0.
    • "col_end": int: Ending offset in ending line (0-based). Default is 0 (works OK with default of "line_end").

Editor.micromap

micromap(id, param1=0, param2=0, param3=0)

Controls editor's micromap. Possible values of "id":

  • MICROMAP_GET: Get list of micromap columns, as list of dict. Dict keys are:
    • "size_perc": Width of column in percents of average char width.
    • "size_px": Width of column in pixels.
    • "tag": Int tag of column. CudaText has 2 default columns with tag 0 and 1.
    • "color": RGB color of column background. Can be COLOR_NONE.
  • MICROMAP_ADD: Add micromap column. Returns bool: tag was not used, column was added.
    • "param1": Int (64 bit) tag of column.
    • "param2": Width of column in percents of average char width.
    • "param3": RGB color of column background, or COLOR_NONE for default themed color.
  • MICROMAP_DELETE: Delete micromap column by its tag. Param "param1": tag. Returns bool: column was found and deleted.

HTML formatting

Several APIs support rendering of HTML-formatted strings. Small subset of HTML tags is supported:

<b>bold style</b>
<i>italic style</i>
<u>underline style</u>
<s>strikeout style</s>
<font color="#AABBCC">colored font</font>
<font color="#ABC">colored font</font>

TreeHelpers

CudaText contains built-in support for TreeHelpers. They build code-tree for additional lexers. TreeHelpers must be plugins, which have special install.inf file (Ini format).

Section "info":

  • key "subdir" must begin with "cuda_tree_"

Section(s) "treehelper" followed by any string (e.g. "treehelper1"):

  • key "lexers" is comma-separated lexers list (can contain lite lexer with suffix)
  • key "method" is name of getter method in __init__.py
  • key "fold" (value 0/1) is deprecated, not handled anymore

File __init__.py must contain getter method(s), referenced by install.inf. Getter has signature (with any name):

def get_headers(filename, lines)
  • param "lines" is list of str, editor contents in CudaText.
  • param "filename" is full file path, it is to support included files or something.

Getter must return list of tuples: (pos, level, caption, icon).

  • field "pos": tuple of int (x1, y1, x2, y2): range for tree node.
  • field "level": 1-based level of node, node of level K+1 is nested into (nearest upper) node of level K.
  • field "caption": caption of node.
  • field "icon": 0-based index of icon from standard imagelist, or -1 if icon not used.
    • 0: folder
    • 1: parts1
    • 2: parts2
    • 3: parts3
    • 4: box
    • 5: func
    • 6: arrow1
    • 7: arrow2

Getter can also return value not of "list" type, in this case CudaText will not update the code-tree.

TreeHelpers can be written in Pascal too. This way they will work much faster. To write/debug a TreeHelper in Pascal, use the project "treehelpertester" in the CudaText GitHub repo. These TreeHelpers were rewritten from Python to Pascal and are built-in now:

  • Markdown
  • MediaWiki
  • reST

Linters

Linters are 2nd-level plugins for CudaLint plugin. CudaLint was ported from SublimeLinter 3, and its linters should be ported from SublimeLinter linters. Here is example:

To see how to port, compare files "linter.py". Other files must be added like in other CudaLint linters.

Tech info

Format of text for cmd_MouseClick

Text is "X,Y" where X/Y are position of caret relative to top-caret (other carets removed when command runs). If Y is 0, X is addition to caret's x. If Y not 0, Y is addition to caret's y, and X is absolute caret's x.

Finder options as string

Some APIs allow to specify finder options as a string. Such string can have the following chars:

  • "b": Backward search
  • "c": Case sensitive
  • "r": Regular expression
  • "w": Whole words
  • "f": Search from caret
  • "s": Search in selection
  • "o": Confirm replaces
  • "a": Wrap search at edge of text
  • "A": When "wrap search at edge of text" is off, and search reaches the document edge, show confirmation to continue search from the opposite edge
  • "T" followed by a digit: Allowed syntax elements. Digit can be:
    • "0": any
    • "1": only comments
    • "2": only strings
    • "3": only comments/string
    • "4": except comments
    • "5": except strings
    • "6": except comments/strings

Format of text for cmd_FinderAction

Text is chr(1) separated items:

  • item 0: Finder action, one of:
    • "findfirst": Find first
    • "findnext": Find next
    • "findprev": Find previous
    • "rep": Replace next, and find next
    • "repstop": Replace next, and don't find
    • "repall": Replace all
    • "findcnt": Count all
    • "findsel": Find all, make selections
    • "findmark": Find all, place markers
  • item 1: Text to find
  • item 2: Text to replace with
  • item 3: Options string, see #Finder_options_as_string

Format of serialized Undo

Text is "\n"-separated undo/redo items. Each line is tab-separated elements:

  • editing action, number 0..5:
    • 0: line changed
    • 1: end-of-line mark changed
    • 2: line inserted
    • 3: line deleted
    • 4: cleared document "modified" flag
    • 5: mouse clicked
  • index of changed line (not for mouse clicks), 0-based.
  • end-of-line kind, number 0..3:
    • 0: none
    • 1: CR LF
    • 2: LF
    • 3: CR
  • line state, number 0..3:
    • 0: none
    • 1: changed
    • 2: added
    • 3: saved
  • caret position(s); carets are ";"-separated and x/y coords (32-bit) are ","-separated; for example "x0,y0;x1,y1;" for 2 carets;
    • plus chr(1) and marker position(s), 64-bit numbers ","-separated, where each marker is encoded as 7 numbers:
      • position x,
      • position y,
      • selection-end x,
      • selection-end y,
      • tab-stop index,
      • some value attached to marker,
      • marker show mode, enum 0..2; 0: show in text only; 1: show in micromap only; 2: show in text and micromap.
    • plus chr(1) and global undo counter, 32-bit integer;
    • plus chr(1) and OS tick counter, 64-bit integer, in milliseconds (shows how much time is passed betweem items).
  • soft mark flag, number 0/1 (boolean). Logic of soft/hard marks is described in wiki page ATSynEdit.
  • hard mark flag, number 0/1.
  • line text, in UTF8. This text can have tab-chars, tab-char is not separator.

Note that field "line state" was inserted in API 1.0.328, new format of data became incompatible with old format.

API of 3rd-party plugins

API of Options Editor

Options Editor plugin (preinstalled in CudaText) has API which allows to call its dialog with custom options. Example shows dialog with 4 custom options, with custom title. Options which user changed in dialog will be saved to user.json or lexer-specific config.

import os
import cudax_lib as appx
import cuda_options_editor as op_ed

fn_config = 'cuda_my_plugin.json' # without path!
meta_info = [
        {
            "opt": "my_opt_1",
            "cmt": ["Comment line 1",
                    "Comment line 2",
                    "Comment line 3"],
            "def": True,        # Default value
            "frm": "bool",      # Value type from
                                #   bool float int str - simple types
                                #   font - font name
                                #   font-e - font name or empty
                                #   hotk - hotkey
                                #   file - file path
                                #   strs  - list of str
                                #   int2s - dict int to str
                                #   str2s - dict str to str
            "chp": "MySection"  # Section (can be empty)
        },
        {   "opt": "my_opt_2",
            "cmt": ["Comment"],
            "def": "v1",
            "frm": "strs",
            "lst": ["v1", "v2"]
        },
        {   "opt": "my_opt_3",
            "cmt": ["Comment"],
            "def": 11,
            "frm": "int2s",
            "dct": [[11, "value for 11"], [22, "value for 22"]]
        },
        {   "opt": "my_opt_4",
            "cmt": ["Comment"],
            "def": "a",
            "frm": "int2s",
            "dct": [["a", "value for a"], ["b", "value for b"]]
        }
        ]

class Command:
    def get_opt(path, val):
        return appx.get_opt(path, val, user_json=fn_config)

    def config(self):
        subset = '' # section in user.json, if user.json is used
        title = 'My Plugin Options'
        how = {'hide_lex_fil': True, 'stor_json': fn_config}
        op_ed.OptEdD(
            path_keys_info = meta_info,
            subset = subset,
            how = how
            ).show(title)
        do_load_plugin_options() # some plugin function to reread options

This will show:

cudatext options editor.png

Options Editor stores values in JSON with trailing comma, so to read these options, plugin must use cudax_lib.get_opt() instead of json.load().

API of Project Manager

Opening project from plugin

To open a project, you need to call the Project Manager's method Command.action_open_project, which can be done via action PROC_EXEC_PLUGIN. For example, this code loads the project "/home/user/tt.cuda-proj":

app_proc(PROC_EXEC_PLUGIN, 'cuda_project_man,action_open_project,/home/user/tt.cuda-proj')

Getting current project info

Project Manager plugin (preinstalled in CudaText) gives API to read properties of currently opened project. It has global variable global_project_info, which is dict with keys:

  • "filename": Path of project file (*.cuda-proj), or empty string if project is not saved.
  • "mainfile": Path of "main file" (which must be set by user from Project Manager context menu).
  • "nodes": List of root project nodes, ie folder and file paths in the root level.
  • "vars": List of variables defined in the Project Properties dialog. List of strings in the form "name=value".

Example gets list of root project items:

     import cuda_project_man as p
     nodes = p.global_project_info['nodes']

Result without opened project:

  >>> p.global_project_info
  {'filename': '', 'nodes': [], 'vars': [], 'mainfile': ''}

Result with opened folder in unsaved project:

  >>> p.global_project_info
  {'filename': '', 'nodes': ['/home/name/datadir'], 'vars': [], 'mainfile': ''}

Result with opened folder in saved project:

  >>> p.global_project_info
  {'filename': '/home/name/test.cuda-proj', 'nodes': ['/home/name/datadir'], 'vars': [], 'mainfile': ''}

Also global function project_variables() exists, which is handy wrapper around global_project_info. It returns dict with keys:

  • "ProjDir": Folder of project file (*.cuda-proj).
  • "ProjMainFile": Path of "main file".
  • "ProjMainFileNameOnly": Only name of "main file", without path.
  • "ProjMainFileNameNoExt": Name of "main file", without path and extension.
  • Additional keys for project variables.

Its code currently is:

def project_variables():
    res = collections.OrderedDict()
    data = global_project_info
    res['ProjDir'] = os.path.dirname(data.get('filename', ''))

    fn = data.get('mainfile', '')
    res['ProjMainFile'] = fn
    res['ProjMainFileNameOnly'] = os.path.basename(fn)
    res['ProjMainFileNameNoExt'] = '.'.join(os.path.basename(fn).split('.')[0:-1])

    data = global_project_info.get('vars', [])
    for item in data:
        s1, s2 = item.split('=', maxsplit=1)
        res[s1] = s2
    return res

Questions

How plugin can fill code-tree

  • Handle events on_open, on_focus, on_change_slow (better don't use on_change, it slows down the app)
  • Get handle of code-tree: h_tree = app_proc(PROC_GET_CODETREE, "")
  • Fill tree via tree_proc(h_tree, ...)
    • Disable standard tree filling via ed.set_prop(PROP_CODETREE, False)
    • Clear tree via tree_proc(h_tree, TREE_ITEM_DELETE, id_item=0)
    • On adding tree items, set range for them via tree_proc(h_tree, TREE_ITEM_SET_RANGE...)

How plugin can show tooltips on mouse-over

  • Create dialog for tooltip, via dlg_proc()
  • Handle events on_open, on_focus, on_change_slow (better don't use on_change, it will slow down the app)
    • Find text regions which need tooltip
    • Delete old hotspots via ed.hotspot(HOTSPOT_DELETE_BY_TAG...)
    • Add hotspots via ed.hotspots(HOTSPOT_ADD...)
  • Handle event on_hotspot
    • Find which text region is under cursor
    • Fill dialog via dlg_proc()
    • Set dialog prop "p" to the handle of editor, ed_self.h. Don't use ed.h, because it is virtual handle 0.
    • Set dialog pos (props "x", "y") to editor-related pixel coords. It is complex. See example: plugin HTML Tooltips.
    • Show dialog via dlg_proc(..., DLG_SHOW_NONMODAL)
  • On exiting hotspot, hide dialog

How to make auto-completion plugin

Good example is "HTML Class Complete": https://github.com/CudaText-addons/cuda_html_class_complete

  • Use CudaText menu item "Plugins / Make Plugin" to create empty plugin. In the "Make Plugin" dialog, check event "on_complete", so method Command.on_complete is called when user pressed Ctrl+Space.
  • Plugin files are located in the "py/cuda_nnnn" folder. In install.inf, add line "lexers=NNNN" for the event on_complete, so event is called only for lexer NNN.
  • In plugin .py file, in method on_complete, read editor text via ed.get_text_all() or ed.get_text_line(), read caret position via ed.get_carets(), make the completions list.
  • Call ed.complete() or ed.complete_alt() to show completions list.

Show me the template of complex plugin with side-panel and bottom-panel

Here is the example plugin: https://github.com/CudaText-addons/cuda_r_plugin . It provides:

  • Main toolbar, separate from the CudaText toolbar. Contains 2 dummy buttons.
  • Side-panel, which contains the small toolbar (with 2 dummy buttons) and listbox (filled with dummy data). Double-click on listbox - inserts clicked item to the current editor.
  • Bottom-panel, which contains the "console input" control and "console log" multi-line control. You can enter commands in the "input" and they will show in the log. Entered commands (last 10) are also stored to the file "[CudaText]/settings/cuda_r_plugin.ini" and re-read on start, you can recall them by clicking the down arrow in the "input" combobox.
  • Plugin supports few options. Saved in the file "[CudaText]/settings/cuda_r_plugin.ini".
  • Menu items in "Plugins / R Plugin", to open side-panel and bottom-panel.
  • Menu item in the "Options / Settings-plugins / R Plugin", to open the config file.
  • Predefined red buttons "R" in the CudaText sidebar and bottom bar. Visible even before the plugin is activated from Plugins menu.

History

1.0.167

  • add: timer_proc.

1.0.168

  • add: app_proc: PROC_SAVE_SESSION/ PROC_LOAD_SESSION get bool (session was saved/loaded)
  • add: dlg_custom: "label" has prop to right-align
  • add: ed.get_prop/set_prop: value can be int/bool too

1.0.169

  • add: ed.insert does append, if y too big
  • add: ed.delete can use too big y2

1.0.170

  • add: app_proc: PROC_SET_CLIP_ALT

1.0.171

  • add: app_proc: PROC_SIDEPANEL_ADD takes additional value icon_filename
  • deprecated: app_log: LOG_PANEL_ADD
  • deprecated: app_log: LOG_PANEL_DELETE
  • deprecated: app_log: LOG_PANEL_FOCUS

1.0.172

  • add: menu_proc()
  • deprecated: app_proc actions: PROC_MENU_*
  • change: PROP_ENC now uses short names, see CudaText#Encodings

1.0.173

  • add: dlg_commands()
  • add: toolbar_proc()
  • deprecated: app_proc actions: PROC_TOOLBAR_*

1.0.174

  • add: dlg_custom: "name=" (not required)
  • add: dlg_custom: "font="
  • add: dlg_custom: "type=filter_listbox", "type=filter_listview". To setup these filter controls, you must set "name=" for filter and its listbox/listview
  • add: app_proc: PROC_ENUM_FONTS

1.0.175

  • add: dlg_proc()
  • add: dlg_custom: added props x= y= w= h= vis= color= font_name= font_size= font_color=
  • add: timer_proc: can also use callbacks "module=nnn;cmd=nnn;" and "module=nnn;func=nnn;"
  • add: timer_proc: added param "tag"
  • add: menu_proc: actions MENU_CREATE, MENU_SHOW

1.0.176

  • reworked dlg_proc, many form props+events added
  • add: dlg_proc/dlg_custom: control type "treeview"
  • add: dlg_proc/dlg_custom: control type "listbox_ex"
  • add: dlg_proc/dlg_custom: control type "trackbar"
  • add: dlg_proc/dlg_custom: control type "progressbar"
  • add: dlg_proc/dlg_custom: control type "progressbar_ex"
  • add: dlg_proc/dlg_custom: control type "bevel"
  • add: file_open: added param "args"
  • add: toolbar_proc: TOOLBAR_GET_CHECKED, TOOLBAR_SET_CHECKED
  • delete: event on_dlg
  • delete: dlg_proc/dlg_custom: prop "font" (use font_name, font_size, font_color)
  • delete: deprecated APIs LOG_PANEL_ADD LOG_PANEL_DELETE LOG_PANEL_FOCUS
  • delete: deprecated APIs PROC_TOOLBAR_*

1.0.177

  • add: ed.replace
  • add: ed.replace_lines
  • add: dlg_custom: parameter "get_dict" to get new dict result (not tuple)
  • add: dlg_proc: action DLG_SCALE
  • add: app_proc: action PROC_GET_SYSTEM_PPI

1.0.178

  • add: dlg_proc: control props for anchors/spacing: "a_*", "sp_*"
  • add: dlg_proc: param "name" to specify controls by name
  • add: dlg_proc: form prop "color"
  • add: dlg_proc: form prop "autosize"
  • add: dlg_proc: actions DLG_DOCK, DLG_UNDOCK
  • add: dlg_custom/dlg_proc: control type "paintbox"

1.0.179

  • add: dlg_proc/timer_proc/menu_proc: callbacks can be "callable", ie function names
  • add: dlg_proc/timer_proc: callbacks can be with "info=...;" at end
  • add: menu_proc: can use new-style callbacks like in dlg_proc
  • deprecated: menu_proc old-style callbacks "module,method[,param]"

1.0.180

  • add: app_proc: PROC_SHOW_SIDEBAR_GET, PROC_SHOW_SIDEBAR_SET
  • add: app_proc: can pass not only string value
  • add: ed.get_prop: PROP_COORDS
  • add: dlg_proc/dlg_custom: type "panel", type "group"
  • add: dlg_proc: control prop "p" (parent)

1.0.181

  • add: dlg_proc/dlg_custom: type "pages"
  • add: dlg_proc: control "paintbox" has sub-event "on_click" with info="x,y"

1.0.182

  • add: dlg_proc: type "toolbar"
  • add: app_proc: PROC_PROGRESSBAR
  • add: app_proc: PROC_SPLITTER_GET, PROC_SPLITTER_SET
  • deprecated: app_proc: PROC_GET_SPLIT, PROC_SET_SPLIT
  • add: app_log: LOG_CONSOLE_GET_COMBO_LINES
  • add: app_log: LOG_CONSOLE_GET_MEMO_LINES
  • add: app_log: LOG_GET_LINES_LIST
  • deprecated: app_log: LOG_CONSOLE_GET, LOG_CONSOLE_GET_LOG, LOG_GET_LINES

1.0.183

  • big changes in dlg_proc:
    • deleted: parameter 'id_event'
    • deleted: props 'callback', 'events'
    • form events is not called for controls (forms have own events, controls have own events)
    • add: events for forms: 'on_resize', 'on_close', 'on_close_query', 'on_key_down', 'on_key_up'
    • add: events for controls: 'on_change', 'on_click', 'on_click_dbl', 'on_select', 'on_menu'
    • add: events for 'treeview' control: 'on_fold', 'on_unfold'

1.0.184

  • deprecated: app_proc: PROC_SIDEPANEL_ADD, PROC_BOTTOMPANEL_ADD
  • deprecated: on_panel event
  • add: app_proc: PROC_SIDEPANEL_ADD_DIALOG, PROC_BOTTOMPANEL_ADD_DIALOG
  • add: tree_proc: TREE_ITEM_FOLD_LEVEL
  • add: tree_proc: TREE_THEME
  • add: listbox_proc: LISTBOX_THEME
  • add: toolbar_proc: TOOLBAR_THEME
  • add: toolbar_proc: used new callback form
  • add: menu_proc: MENU_SHOW with command="" to show at cursor
  • add: menu_proc: added param "hotkey" for MENU_ADD, "hotkey" returned from MENU_ENUM
  • deleted deprecated: PROC_GET_SPLIT, PROC_SET_SPLIT
  • deleted deprecated: LOG_GET_LINES
  • deleted deprecated: LOG_CONSOLE_GET, LOG_CONSOLE_GET_LOG

1.0.185 (app 1.11.0)

  • add: menu_proc: for MENU_ADD added param "tag"
  • add: menu_proc: MENU_SHOW can use 2-tuple (x,y)
  • add: menu_proc: MENU_ENUM gives additional dict key "command"
  • deprecated: menu_proc command values: "recents", "enc", "langs", "lexers", "plugins", "themes-ui", "themes-syntax"

1.0.186 (app 1.12.0)

  • add: tree_proc: TREE_ICON_GET_SIZES, TREE_ICON_SET_SIZES
  • deleted deprecated: app_proc: PROC_MENU_* actions
  • deleted deprecated: app_proc: PROC_SIDEPANEL_ADD, PROC_BOTTOMPANEL_ADD

1.0.187 (app 1.12.2)

  • add: lexer_proc: LEXER_GET_PROP
  • deprecated: lexer_proc: LEXER_GET_EXT, LEXER_GET_ENABLED, LEXER_GET_COMMENT, LEXER_GET_COMMENT_STREAM, LEXER_GET_COMMENT_LINED, LEXER_GET_LINKS, LEXER_GET_STYLES, LEXER_GET_STYLES_COMMENTS, LEXER_GET_STYLES_STRINGS
  • deleted: lexer_proc: actions didnt work, lexer files were not saved: LEXER_SET_*, LEXER_DELETE, LEXER_IMPORT
  • add: dlg_proc: control "listview" on_select returns "data" param with 2-tuple

1.0.188 (app 1.13.0)

  • add: imagelist_proc()
  • add: tree_proc: TREE_GET_IMAGELIST
  • add: toolbar_proc: TOOLBAR_GET_IMAGELIST
  • add: lexer_proc: LEXER_GET_LEXERS
  • deprecated: tree_proc: TREE_ICON_ADD, TREE_ICON_DELETE, TREE_ICON_GET_SIZES, TREE_ICON_SET_SIZES
  • deprecated: toolbar_proc: TOOLBAR_GET_ICON_SIZES, TOOLBAR_SET_ICON_SIZES, TOOLBAR_ADD_ICON
  • deprecated: lexer_proc: LEXER_GET_LIST

1.0.189 (app 1.13.1)

  • add: tree_proc: TREE_ITEM_SHOW

1.0.190 (app 1.14.0)

  • add: app_proc: PROC_GET_TAB_IMAGELIST
  • add: ed.get_prop/ed.set_prop: PROP_TAB_ICON
  • add: imagelist_proc: IMAGELIST_PAINT

1.0.191 (app 1.14.2)

  • add: dlg_proc: form property "border"
  • add: dlg_proc: control type "button_ex"
  • add: button_proc() to work with "button_ex"

1.0.192 (app 1.14.8)

  • add: dlg_proc: control type "splitter"
  • add: dlg_proc: control prop "align"
  • add: dlg_proc: control "listbox_ex" has event "on_draw_item"
  • add: listbox_proc: actions LISTBOX_GET_ITEM_H, LISTBOX_SET_ITEM_H
  • add: listbox_proc: actions LISTBOX_GET_DRAWN, LISTBOX_SET_DRAWN
  • add: event on_paste
  • deleted deprecated: event on_panel
  • deleted deprecated: menu_proc spec strings: "recents", "enc", "langs", "lexers", "plugins", "themes-ui", "themes-syntax"

1.0.193 (app 1.15.0)

  • add: image_proc()
  • deleted: canvas_proc actions: CANVAS_IMAGE, CANVAS_IMAGE_SIZED (use image_proc instead)
  • add: dlg_menu can have argument of type list/tuple
  • add: dlg_menu can have argument "caption"

1.0.194 (app 1.15.4)

  • add: app_proc: PROC_SIDEPANEL_ACTIVATE has 2nd param
  • add: menu_proc: MENU_GET_PROP
  • add: menu_proc: MENU_SET_CAPTION
  • add: menu_proc: MENU_SET_VISIBLE
  • add: menu_proc: MENU_SET_ENABLED
  • add: menu_proc: MENU_SET_CHECKED
  • add: menu_proc: MENU_SET_RADIOITEM
  • add: menu_proc: MENU_SET_HOTKEY
  • add: tree_proc: TREE_ITEM_GET_PROPS
  • deprecated: tree_proc: TREE_ITEM_GET_PROP, TREE_ITEM_GET_PARENT

1.0.195 (app 1.15.5)

  • add: dlg_proc: control prop "border"
  • add: dlg_proc: control "linklabel" uses "on_click" (after opening URL if it's valid)

1.0.196 (app 1.16.2)

  • add: ed.dim()

1.0.197 (app 1.17.2)

  • add: dlg_proc: type "editor"
  • add: object ed_goto
  • add: objects ed_con_log, ed_con_in
  • add: events: on_goto_enter, on_goto_change, on_goto_caret, on_goto_key, on_goto_key_up
  • add: ed.get_prop/set_prop: PROP_ONE_LINE
  • add: ed.get_prop/set_prop: PROP_LINE_NUMBERS

1.0.198 (app 1.18.0)

  • add: constants WRAP_nnn
  • add: ed.set_prop works for PROP_LINE_STATE

1.0.199 (app 1.19.2)

  • add: toolbar_proc: TOOLBAR_GET_VERTICAL, TOOLBAR_SET_VERTICAL
  • add: toolbar_proc: TOOLBAR_GET_WRAP, TOOLBAR_SET_WRAP
  • deleted deprecated: TOOLBAR_GET_ICON_SIZES, TOOLBAR_SET_ICON_SIZES, TOOLBAR_ADD_ICON
  • deleted deprecated: TREE_ITEM_GET_PROP, TREE_ITEM_GET_PARENT
  • deleted deprecated: TREE_ICON_ADD, TREE_ICON_DELETE, TREE_ICON_GET_SIZES, TREE_ICON_SET_SIZES
  • deleted deprecated: LEXER_GET_LIST, LEXER_GET_EXT, LEXER_GET_ENABLED, LEXER_GET_COMMENT, LEXER_GET_COMMENT_STREAM, LEXER_GET_COMMENT_LINED, LEXER_GET_LINKS, LEXER_GET_STYLES, LEXER_GET_STYLES_COMMENTS, LEXER_GET_STYLES_STRINGS

1.0.200 (app 1.20.2)

  • add: event on_insert

1.0.201 (app 1.21.0)

  • add: several commands in cudatext_cmd.py: simple word jump, goto abs line begin/end

1.0.202 (app 1.23.0)

  • add: file_open: can open preview-tab
  • add: file_open: can open file ignoring history
  • change: renamed file_open param "args" to "options"

1.0.203 (app 1.23.4)

  • add: event on_scroll
  • add: event on_group
  • add: file_open: options can have "/noevent"

1.0.204 (app 1.23.5)

  • add: ed.get_wrapinfo()
  • add: ed.get_prop/ed.set_prop: PROP_SCROLL_VERT, PROP_SCROLL_HORZ
  • add: ed.export_html()
  • deleted: ed.set_prop: PROP_EXPORT_HTML

1.0.205 (app 1.24.1)

  • add: dlg_proc: ctl "edit" supports "on_change" (if "act":True)

1.0.206 (app 1.24.2)

  • add: dlg_proc: added ctl property "focused"
  • add: dlg_proc: added form events "on_act", "on_deact"

1.0.207 (app 1.25.1)

  • add: app_proc: PROC_GET_COMMANDS

1.0.208 (app 1.26.2)

  • add: lexer_proc supports lite lexers too (their names have " ^" suffix)

1.0.208 (app 1.27.2)

  • add: menu_proc: added MENU_SET_IMAGELIST, MENU_SET_IMAGEINDEX
  • add: file_open: for zip files, returns True if zip installation completed

1.0.210 (app 1.29.0)

  • add: file_open: for binary viewer, pass options='/binary'
  • add: ed.get_prop/set_prop: PROP_KIND, PROP_V_MODE, PROP_V_POS, PROP_V_SEL_START, PROP_V_SEL_LEN

1.0.211 (app 1.32.0)

  • add: statusbar_proc()
  • add: dlg_proc: added type "statusbar"
  • add: toolbar_proc: TOOLBAR_UPDATE

1.0.212 (app 1.32.2)

  • add: toolbar_proc: TOOLBAR_GET_COUNT
  • add: toolbar_proc: TOOLBAR_GET_BUTTON_HANDLE
  • add: button_proc: BTN_GET_TEXT, BTN_SET_TEXT
  • add: button_proc: BTN_GET_ENABLED, BTN_SET_ENABLED
  • add: button_proc: BTN_GET_VISIBLE, BTN_SET_VISIBLE
  • add: button_proc: BTN_GET_HINT, BTN_SET_HINT
  • add: button_proc: BTN_GET_DATA1, BTN_SET_DATA1, BTN_GET_DATA2, BTN_SET_DATA2
  • change: toolbar_proc: TOOLBAR_ENUM returns int value of "kind", before it was str
  • deprecated: TOOLBAR_GET_CHECKED, TOOLBAR_SET_CHECKED - now use TOOLBAR_GET_BUTTON_HANDLE + button_proc()
  • deprecated: PROC_GET_COMMAND, PROC_GET_COMMAND_INITIAL, PROC_GET_COMMAND_PLUGIN - now use PROC_GET_COMMANDS instead

1.0.213 (app 1.32.3)

  • add: button_proc: BTN_GET_MENU, BTN_SET_MENU
  • add: button_proc: BTN_GET_ARROW, BTN_SET_ARROW
  • add: button_proc: BTN_GET_FOCUSABLE, BTN_SET_FOCUSABLE
  • add: button_proc: BTN_GET_FLAT, BTN_SET_FLAT
  • add: toolbar_proc: TOOLBAR_ADD_ITEM, TOOLBAR_ADD_MENU
  • deprecated: toolbar_proc: TOOLBAR_ADD_BUTTON - now use TOOLBAR_ADD_ITEM/TOOLBAR_ADD_MENU + button_proc()
  • deprecated: toolbar_proc: TOOLBAR_SET_BUTTON - now use TOOLBAR_GET_BUTTON_HANDLE + button_proc()
  • deprecated: toolbar_proc: TOOLBAR_ENUM - now use TOOLBAR_GET_COUNT + TOOLBAR_GET_BUTTON_HANDLE + button_proc()

1.0.214 (app 1.32.4)

  • add: button_proc supports callable param "value"

1.0.215 (app 1.34.1)

  • add: dlg_proc: DLG_CTL_PROP_GET returns key "items" for controls "listview", "checklistview", "listbox", "checklistbox"

1.0.216 (app 1.34.2)

  • add: statusbar_proc: STATUSBAR_GET_CELL_AUTOSIZE, STATUSBAR_SET_CELL_AUTOSIZE
  • add: statusbar_proc: STATUSBAR_GET_CELL_AUTOSTRETCH, STATUSBAR_SET_CELL_AUTOSTRETCH
  • add: statusbar_proc: 10 actions to get/set colors, STATUSBAR_GET/SET_COLOR_*
  • deleted: STATUSBAR_GET_COLOR_BORDER, STATUSBAR_SET_COLOR_BORDER
  • deleted: STATUSBAR_AUTOSIZE_CELL - now use STATUSBAR_SET_CELL_AUTOSTRETCH

1.0.217 (app 1.34.4)

  • add: button_proc: const BTNKIND_TEXT_CHOICE
  • add: button_proc: BTN_GET_WIDTH, BTN_SET_WIDTH
  • add: button_proc: BTN_GET_ITEMS, BTN_SET_ITEMS
  • add: button_proc: BTN_GET_ITEMINDEX, BTN_SET_ITEMINDEX
  • add: button_proc: BTN_GET_ARROW_ALIGN, BTN_SET_ARROW_ALIGN
  • add: button_proc: BTN_UPDATE

1.0.218 (app 1.38.0)

  • add: Editor.hotspots()
  • add: event on_hotspot
  • add: app_proc: PROC_GET_MOUSE_POS
  • add: dlg_proc: DLG_PROP_SET supports prop "p" (parent of form)
  • add: Editor.convert: CONVERT_SCREEN_TO_LOCAL, CONVERT_LOCAL_TO_SCREEN
  • add: Editor.convert: CONVERT_PIXELS_TO_CARET, CONVERT_CARET_TO_PIXELS
  • add: Editor.markers: MARKERS_DELETE_BY_TAG
  • add: Editor.get_prop: PROP_CELL_SIZE

1.0.219 (app 1.38.1)

  • add: app_proc: PROC_THEME_UI_DATA_GET
  • add: app_proc: PROC_THEME_SYNTAX_DATA_GET

1.0.220 (app 1.38.2)

  • add: on_state supports new constants APPSTATE_nnnn

1.0.221 (app 1.38.3)

  • add: Editor.get_prop/set_prop: PROP_INDENT_SIZE, PROP_INDENT_KEEP_ALIGN, PROP_INDENT_AUTO, PROP_INDENT_KIND

1.0.222 (app 1.38.5)

  • add: dlg_proc: form events "on_mouse_enter", "on_mouse_exit"
  • add: dlg_proc: form events "on_show", "on_hide"
  • add: dlg_proc: control events "on_mouse_enter", "on_mouse_exit", "on_mouse_down", "on_mouse_up"

1.0.223 (app 1.39.1)

  • add: install.inf supports param [info] os=, value is comma separated strings: win, linux, macos
  • add: menu_proc: support for spec menu id "_oplugins"

1.0.224 (app 1.39.5)

  • add: dlg_proc: control prop "ex"
  • deprecated: dlg_proc/dlg_custom prop "props" - now use "ex0"..."ex9"
  • deprecated: BOOKMARK_CLEAR_HINTS

1.0.225 (app 1.40.0)

  • add: app_proc: PROC_SEND_MESSAGE

1.0.226 (app 1.40.1)

  • add: app_proc: PROC_GET_CODETREE
  • add: Editor.get_prop/set_prop: PROP_CODETREE
  • add: tree_proc: TREE_ITEM_GET_RANGE, TREE_ITEM_SET_RANGE
  • deprecated: tree_proc: TREE_ITEM_GET_SYNTAX_RANGE
  • change: changed Code-Tree button caption from "Tree" to "Code tree"

1.0.227 (app 1.40.2)

  • add: file_open: added options "/passive", "/nonear"

1.0.228 (app 1.40.7)

  • add: event on_tab_change

1.0.229 (app 1.43.0)

  • add: plugins can force show sidebar button, even if they don't run on start. New install.inf sections [sidebar1] .. [sidebar3]. Examples: ProjectManager, TabsList.

1.0.230 (app 1.44.0)

  • add: dlg_proc: control "listview"/"checklistview" has event "on_click_header"
  • add: install.inf: allow os= values with bitness: win32, win64, linux32, linux64, freebsd32, freebsd64
  • deleted deprecated: PROC_GET_COMMAND
  • deleted deprecated: PROC_GET_COMMAND_INITIAL
  • deleted deprecated: PROC_GET_COMMAND_PLUGIN

1.0.231 (app 1.45.5)

  • add: dlg_proc: control "listview" has prop "columns"
  • removed: on_group; on_state(..., APPSTATE_GROUPS) called instead

1.0.232 (app 1.46.2)

  • add: dlg_proc: control "radiogroup" has prop "columns"
  • add: dlg_proc: control "radiogroup" has prop "ex0"
  • add: Editor.get_prop/set_prop: PROP_GUTTER_ALL, PROP_GUTTER_STATES

1.0.233 (app 1.47.0)

  • add: dlg_menu: option MENU_NO_FUZZY
  • add: dlg_menu: option MENU_NO_FULLFILTER

1.0.233 (app 1.47.1)

  • add: app_proc: PROC_GET_GUI_HEIGHT supports name "scrollbar"

1.0.234 (app 1.47.5)

  • add: event on_exit
  • add: ed.get_prop/set_prop: PROP_UNPRINTED_SPACES_TRAILING
  • add: ed.get_prop/set_prop: PROP_LAST_LINE_ON_TOP
  • add: ed.get_prop/set_prop: PROP_HILITE_CUR_COL
  • add: ed.get_prop/set_prop: PROP_HILITE_CUR_LINE
  • add: ed.get_prop/set_prop: PROP_HILITE_CUR_LINE_MINIMAL
  • add: ed.get_prop/set_prop: PROP_HILITE_CUR_LINE_IF_FOCUS
  • add: ed.get_prop/set_prop: PROP_MODERN_SCROLLBAR

1.0.235 (app 1.48.2)

  • add: support for "lazy events"
  • add: event on_console_print
  • add: lexer_proc: LEXER_REREAD_LIB

1.0.236 (app 1.48.3)

  • add: dlg_proc: controls have props "w_min/w_max/h_min/h_max", like forms
  • fix: bug in dlg_proc/dlg_custom: controls with changed parent become not findable by name/index (and count of controls becomes smaller)

1.0.237 (app 1.49.1)

  • add: statusbar_proc: STATUSBAR_GET_CELL_HINT, STATUSBAR_SET_CELL_HINT

1.0.238 (app 1.49.5)

  • add: dlg_proc/dlg_custom: controls have prop "font_style"
  • add: file_open: options "/view-text", "/view-binary", "/view-hex", "/view-unicode"
  • change: file_open: deleted option "/binary"

1.0.239 (app 1.51.2)

  • add: event on_mouse_stop

1.0.240 (app 1.52.1)

  • add: ed.bookmark: BOOKMARK_SET can specify "delete bookmark on deleting line"
  • deleted deprecated: BOOKMARK_CLEAR_HINTS
  • deleted deprecated: TREE_ITEM_GET_SYNTAX_RANGE

1.0.242 (app 1.53.6)

  • add/change: dlg_proc: form property "border" is now enum, with DBORDER_nnn values
  • deprecated: dlg_proc: form property "resize"
  • deleted deprecated: TOOLBAR_SET_BUTTON, TOOLBAR_ADD_BUTTON, TOOLBAR_ENUM, TOOLBAR_GET_CHECKED, TOOLBAR_SET_CHECKED

1.0.243 (app 1.55.0)

  • add: event on_click_gutter
  • deleted: events on_goto_enter, on_goto_change, on_goto_caret, on_goto_key, on_goto_key_up
  • add: additional group indexes 6..8 for floating groups
  • add: app_proc: PROC_SHOW_FLOATGROUP1_GET, PROC_SHOW_FLOATGROUP1_SET
  • add: app_proc: PROC_SHOW_FLOATGROUP2_GET, PROC_SHOW_FLOATGROUP2_SET
  • add: app_proc: PROC_SHOW_FLOATGROUP3_GET, PROC_SHOW_FLOATGROUP3_SET
  • add: app_proc: PROC_FLOAT_SIDE_GET, PROC_FLOAT_SIDE_SET
  • add: app_proc: PROC_FLOAT_BOTTOM_GET, PROC_FLOAT_BOTTOM_SET

1.0.244 (app 1.55.1)

  • deleted: object ed_goto

1.0.245 (app 1.55.3)

  • add: Editor.get_prop/set_prop: PROP_CARET_STOP_UNFOCUSED
  • add: addon can require other addon(s) via install.inf: [info] req=cuda_aa,cuda_bb

1.0.246 (app 1.56.1)

  • add: dlg_proc: controls have prop "autosize"
  • add: dlg_proc: added events for control "editor": on_change, on_caret, on_scroll, on_key_down, on_key_up, on_click_gutter, on_click_gap, on_paste
  • add: addon can require lexer(s) via install.inf: [info] reqlexer=Name1,Name2

1.0.247 (app 1.56.3)

  • add: event on_close_pre
  • add: ed.get_prop/set_prop: PROP_FOLD_ALWAYS
  • add: ed.get_prop/set_prop: PROP_FOLD_ICONS
  • add: ed.get_prop/set_prop: PROP_FOLD_TOOLTIP_SHOW

1.0.248 (app 1.56.6)

  • add: app_proc: PROC_GET_FINDER_PROP
  • add: app_proc: PROC_SET_FINDER_PROP
  • deprecated: app_proc: PROC_GET_FIND_OPTIONS
  • deprecated: app_proc: PROC_SET_FIND_OPTIONS
  • deprecated: app_proc: PROC_GET_FIND_STRINGS

1.0.249 (app 1.57.5)

  • add: dlg_proc: control "pages" supports prop "val"
  • add: dlg_proc: control event "on_menu" can return False to disable default menu
  • add: Editor.get_token: TOKEN_LIST, TOKEN_LIST_SUB
  • add: Editor.get_token: index params are optional now
  • deprecated: Editor.get_token: TOKEN_AT_POS, TOKEN_INDEX (now use TOKEN_LIST, TOKEN_LIST_SUB)

1.0.250 (app 1.57.7)

  • add: event "on_open_none"
  • add: dlg_proc: event "on_menu" has filled param "data" like in "on_mouse_down"

1.0.251 (app 1.57.8)

  • add: Editor.get_prop: PROP_ACTIVATION_TIME

1.0.252 (app 1.58.1)

  • add: app_log: added optional param "panel"
  • add: Editor.bookmark: added 3 optional params: "auto_del", "show", "tag"
  • add: Editor.bookmark: BOOKMARK_GET_ALL
  • add: Editor.bookmark: BOOKMARK_GET_PROP
  • add: Editor.bookmark: BOOKMARK_DELETE_BY_TAG
  • change: Editor.bookmark: BOOKMARK_SET sets flag "delete on deleting line" from new param "auto_del" now (before: from "ncolor=1")
  • change: on_change/on_change_slow now isn't called on file opening
  • deprecated: app_log: LOG_SET_PANEL (now use parameter "panel")
  • deprecated: Editor.bookmark: BOOKMARK_GET (now use BOOKMARK_GET_PROP)

1.0.253 (app 1.59.0)

  • add: Editor.attr: added optional param "show_on_map"
  • add: Editor.get_prop(PROP_ACTIVATION_TIME) is 0 for not yet focused tabs
  • add: app_proc: PROC_BOTTOMPANEL_ACTIVATE now handles tuple like PROC_SIDEPANEL_ACTIVATE

1.0.254 (app 1.60.1)

  • add: event on_tab_switch

1.0.255 (app 1.60.5)

  • add: module cudax_nodejs
  • add: menu_proc: support menu id "tab"
  • add: menu_proc: MENU_REMOVE
  • add: Editor.folding: FOLDING_FOLD_ALL
  • add: Editor.folding: FOLDING_FOLD_LEVEL
  • add: Editor.folding: FOLDING_UNFOLD_ALL
  • add: Editor.folding: FOLDING_UNFOLD_LINE

1.0.256 (app 1.60.7)

  • add: Editor.decor()

1.0.257 (app 1.62.0)

  • deleted deprecated: TOKEN_AT_POS, TOKEN_INDEX (now use TOKEN_LIST, TOKEN_LIST_SUB)
  • deleted deprecated: BOOKMARK_GET (now use BOOKMARK_GET_PROP)
  • deleted deprecated: LOG_SET_PANEL (now use parameter "panel")

1.0.258 (app 1.62.5)

  • deleted deprecated: PROC_GET_FIND_OPTIONS, PROC_GET_FIND_STRINGS (now use PROC_GET_FINDER_PROP)
  • deleted deprecated: PROC_SET_FIND_OPTIONS (now use PROC_SET_FINDER_PROP)

1.0.259 (app 1.63.5)

  • add: Editor.get_prop/set_prop: PROP_SAVE_HISTORY
  • add: Editor.get_prop/set_prop: PROP_PREVIEW

1.0.260 (app 1.63.6)

  • deleted event "on_console"
  • deleted event "on_console_print"

1.0.261 (app 1.64.2)

  • add: event on_goto_enter
  • add: Editor.get_prop/set_prop: PROP_CARET_VIEW, PROP_CARET_VIEW_OVR, PROP_CARET_VIEW_RO
  • deleted: Editor.get_prop/set_prop: PROP_CARET_SHAPE, PROP_CARET_SHAPE_OVR, PROP_CARET_SHAPE_RO

1.0.262 (app 1.64.4)

  • add: ini_proc()
  • add: app_proc: PROC_GET_KEYSTATE returns also state of pressed mouse buttons

1.0.263 (app 1.65.6)

  • add: event on_lexer_parsed

1.0.264 (app 1.66.7)

  • add: app_proc: PROC_SHOW_TREEFILTER_GET, _SET
  • add: Editor.get_prop/set_prop: PROP_UNDO_GROUPED
  • add: Editor.get_prop/set_prop: PROP_UNDO_LIMIT

1.0.265 (app 1.66.9)

  • add: Editor.get_prop/set_prop: PROP_UNDO_DATA
  • add: Editor.get_prop/set_prop: PROP_REDO_DATA
  • add: Editor.folding: FOLDING_GET_LIST_FILTERED

1.0.266 (app 1.67.0)

  • add: dlg_commands: add COMMANDS_CENTERED
  • add: dlg_commands: add "title" param

1.0.267 (app 1.70.3)

  • add: on_state supports also APPSTATE_CONFIG_REREAD
  • add: on_state supports also APPSTATE_SESSION_LOAD

1.0.268 (app 1.71.5)

  • add: event on_save_naming

1.0.269 (app 1.71.6)

  • add: Editor.gap: allowed gap before the first line (line index = -1)
  • add: file_open: options "/nontext-view-text", "/nontext-view-binary", "/nontext-view-hex", "/nontext-view-unicode", "/nontext-cancel"
  • add: file_open: options "/nozip", "/nopictures"

1.0.270 (app 1.72.1)

  • add: app_proc: PROC_WINDOW_TOPMOST_GET, PROC_WINDOW_TOPMOST_SET

1.0.271 (app 1.73.1)

  • add: Editor.bookmark: added actions BOOKMARK2_*

1.0.272 (app 1.74.0)

  • add: file_open: can open 2 files in a single tab
  • add: Editor.get_prop/set_prop: PROP_EDITORS_LINKED
  • add: Editor.get_prop/set_prop: PROP_SPLIT
  • add: Editor.get_prop: PROP_HANDLE_SELF, PROP_HANDLE_PRIMARY, PROP_HANDLE_SECONDARY
  • add: Editor.get_prop: PROP_RECT_CLIENT, PROP_RECT_TEXT
  • change: deleted object "ed_bro"
  • deprecated: file_save(); use ed.save() instead
  • deprecated: Editor.get_split, Editor.set_split; use PROP_SPLIT instead

1.0.273 (app 1.74.1)

  • add: Editor.gap: added params "size", "color"
  • add: app_proc: PROC_SIDEPANEL_GET
  • add: app_proc: PROC_BOTTOMPANEL_GET

1.0.274 (app 1.74.7)

  • deleted deprecated: file_save()
  • deleted deprecated: Editor.get_split, Editor.set_split
  • add: Editor.gap: no limit for gap height

1.0.275 (app 1.76.0)

  • add: Editor.get_text_line has optional param "max_len"
  • add: dlg_menu: added MENU_CENTERED

1.0.276 (app 1.76.6)

  • add: dlg_proc: form has property "p" (handle of parent form)

1.0.277 (app 1.77.2)

  • change: dlg_proc: "memo" value must encode tab as chr(3) now (was chr(2))
  • add: get_prop: PROP_CODETREE_MODIFIED_VERSION

1.0.278 (app 1.77.4)

  • add: Editor.get_prop/set_prop: PROP_SAVING_FORCE_FINAL_EOL
  • add: Editor.get_prop/set_prop: PROP_SAVING_TRIM_SPACES
  • add: Editor.get_prop/set_prop: PROP_SAVING_TRIM_FINAL_EMPTY_LINES

1.0.279 (app 1.77.6)

  • add: app_proc: PROC_CONFIG_READ
  • add: app_proc: PROC_CONFIG_NEWDOC_EOL_GET
  • add: app_proc: PROC_CONFIG_NEWDOC_EOL_SET
  • add: app_proc: PROC_CONFIG_NEWDOC_ENC_GET
  • add: app_proc: PROC_CONFIG_NEWDOC_ENC_SET

1.0.280 (app 1.77.6)

  • add: Editor.get_prop/set_prop: PROP_NEWLINE
  • deprecated: PROP_EOL

1.0.281 (app 1.78.5)

  • add: Editor.get_prop/set_prop: PROP_SCROLL_VERT_SMOOTH, PROP_SCROLL_HORZ_SMOOTH
  • add: Editor.get_prop: PROP_SCROLL_VERT_INFO, PROP_SCROLL_HORZ_INFO
  • add: Editor.get_wrapinfo: dict result has additional "initial" field
  • deprecated: PROP_COLUMN_LEFT; use PROP_SCROLL_HORZ instead

1.0.282 (app 1.78.6)

  • add: Editor.get_prop: PROP_LINE_STATES
  • add: Editor.get_prop: PROP_LINE_STATES_UPDATED
  • change: PROP_TAG is now stored per Editor object, so primary and secondary editors (in the same tab) have different PROP_TAG values
  • add: TreeHelper getter can return not "list" type, to not refresh code tree

1.0.283 (app 1.78.7)

  • add: Editor.get_prop/set_prop: PROP_ZEBRA

1.0.284 (app 1.79.0)

  • add: msg_box_ex()
  • add: Editor.get_prop/set_prop: COLOR_ID_BorderFocused, COLOR_ID_MinimapTooltipBg, COLOR_ID_MinimapTooltipBorder, COLOR_ID_BlockStapleActive
  • add: app_proc: ids SPLITTER_G4, SPLITTER_G5

1.0.285 (app 1.79.1)

  • add: Editor.gap: GAP_GET_ALL
  • deprecated: GAP_GET_LIST

1.0.286 (app 1.79.2)

  • add: Editor.get_prop: PROP_HANDLE_PARENT
  • add: const COLOR_DEFAULT

1.0.287 (app 1.79.3)

  • add: Editor.set_caret: param "options"
  • add: Editor.set_caret: CARET_DELETE_INDEX
  • add: Editor.get_filename: param "options"
  • add: toolbar_proc: TOOLBAR_GET_BUTTON_HANDLES

1.0.288 (app 1.81.0)

  • add: for BOOKMARK_SETUP it's allowed to use COLOR_DEFAULT
  • change: removed menu id "_langs"
  • change: removed menu id "_themes-ui"
  • change: removed menu id "_themes-syntax"

1.0.289 (app 1.81.2)

  • add: Editor.action()
  • deprecated: Editor.lexer_scan()
  • deprecated: Editor.export_html()

1.0.290 (app 1.81.3)

  • add: listbox_proc: LISTBOX_GET_COLUMN_SEP, LISTBOX_SET_COLUMN_SEP
  • add: listbox_proc: LISTBOX_GET_COLUMNS, LISTBOX_SET_COLUMNS
  • removed: LISTBOX_THEME
  • removed: event "on_tab_switch"

1.0.291 (app 1.83.0)

  • add: emmet()
  • add: app_proc: PROC_GET_FINDER_PROP dict has keys for option "Allowed syntax elements"

1.0.292 (app 1.83.2)

  • add: Editor.action: EDACTION_UPDATE
  • add: Editor.action: EDACTION_SHOW_POS

1.0.293 (app 1.84.2)

  • removed deprecated: Editor.lexer_scan
  • removed deprecated: Editor.export_html
  • removed deprecated: PROP_COLUMN_LEFT
  • removed deprecated: GAP_GET_LIST
  • removed deprecated: PROP_EOL
  • add: install.inf support for data with empty "subdir"
  • add: install.inf support for "type=cudatext-package"

1.0.294 (app 1.84.5)

  • add: timer_proc: behaviour when TIMER_START* restarts existing timer: now action updates old timer's tag to new value

1.0.295 (app 1.84.6)

  • change: msg_status_alt now shows floating tooltip on the top (before: was statusbar on the bottom)

1.0.296 (app 1.85.1)

  • add: dlg_proc: control property "texthint"

1.0.297 (app 1.85.1)

  • add: dlg_dir: param "caption"
  • add: dlg_file: param "caption"

1.0.298 (app 1.85.2)

  • add: dlg_proc: control events "on_focus_enter", "on_focus_exit"

1.0.299 (app 1.86.0)

  • change: Windows: embedded Python updated to 3.6
  • change: Editor.set_text_all now looses Undo information

1.0.300 (app 1.86.2)

  • deleted: STATUSBAR_GET_COLOR_FONT, STATUSBAR_SET_COLOR_FONT (other actions allow to get/set it)
  • add: statusbar_proc: STATUSBAR_SET_CELL_FONT_NAME, STATUSBAR_GET_CELL_FONT_NAME
  • add: statusbar_proc: STATUSBAR_SET_CELL_FONT_SIZE, STATUSBAR_GET_CELL_FONT_SIZE
  • add: dlg_proc: DLG_LOCK, DLG_UNLOCK

1.0.301 (app 1.86.2)

  • add: lexer_proc: LEXER_GET_STYLES

1.0.302 (app 1.86.3)

  • add: app_proc: PROC_THEME_UI_DICT_GET
  • add: app_proc: PROC_THEME_SYNTAX_DICT_GET
  • deprecated: PROC_THEME_UI_DATA_GET
  • deprecated: PROC_THEME_SYNTAX_DATA_GET

1.0.303 (app 1.87.5)

  • add: listbox_proc: LISTBOX_GET_SHOW_X, LISTBOX_SET_SHOW_X
  • add: listbox_proc: LISTBOX_GET_HOTTRACK, LISTBOX_SET_HOTTRACK
  • add: listbox_proc: LISTBOX_GET_ITEM_PROP, LISTBOX_SET_ITEM_PROP
  • add: listbox_proc: LISTBOX_ADD returns count of items
  • add: dlg_proc: control "listbox_ex" has new event "on_click_x"

1.0.304 (app 1.87.5)

  • add: listbox_proc: LISTBOX_ADD_PROP

1.0.305 (app 1.87.6)

  • add: Editor.markers, Editor.attr: MARKERS_DELETE_BY_INDEX
  • add: Editor.markers, Editor.attr: list allows "duplicate" items with the same x:y pos; attr list applies all "duplicate" items, left to right

1.0.306 (app 1.88.2)

  • change: menu_proc: removed special menu id "_lexers"

1.0.307 (app 1.88.6)

  • add: Editor.get_token: add TOKEN_GET_KIND
  • add: Editor.action: add EDACTION_FIND_BRACKET

1.0.310 (app 1.88.8)

  • add: Editor.attr: param "show_on_map" can be int
  • add: Editor.attr: param "len" can be <0 to paint multiline micromap mark
  • add: Editor.attr: added param "map_only"
  • add: Editor.attr: MARKERS_ADD_MANY
  • change: Editor.attr: added tuple item in MARKERS_GET
  • add: Editor.action: EDACTION_MICROMAPCOL_GET
  • add: Editor.action: EDACTION_MICROMAPCOL_ADD
  • add: Editor.action: EDACTION_MICROMAPCOL_DELETE

1.0.312 (app 1.89.1)

  • add: listbox_proc: LISTBOX_GET_SCROLLPOS_HORZ
  • add: listbox_proc: LISTBOX_SET_SCROLLPOS_HORZ
  • add: listbox_proc: LISTBOX_GET_SCROLLSTYLE_HORZ
  • add: listbox_proc: LISTBOX_SET_SCROLLSTYLE_HORZ
  • add: listbox_proc: LISTBOX_GET_SCROLLSTYLE_VERT
  • add: listbox_proc: LISTBOX_SET_SCROLLSTYLE_VERT

1.0.313 (app 1.89.2)

  • add: Editor.get_prop/set_prop: PROP_SCROLLSTYLE_HORZ, PROP_SCROLLSTYLE_VERT
  • add: Editor.attr: MARKERS_GET_DICT

1.0.314 (app 1.89.4)

  • add: Editor.action: EDACTION_FIND_BRACKETS
  • deleted: EDACTION_FIND_BRACKET
  • deleted deprecated: PROC_THEME_UI_DATA_GET
  • deleted deprecated: PROC_THEME_SYNTAX_DATA_GET

1.0.315 (app 1.89.6)

  • add: Editor.get_prop/set_prop: PROP_CODETREE_SUBLEXER
  • add: dlg_commands: COMMANDS_FILES
  • add: dlg_commands: COMMANDS_RECENTS

1.0.316 (app 1.90.0)

  • add: app_proc: PROC_GET_COMMANDS returns new kinds "openedfile", "recentfile"

1.0.317 (app 1.91.1)

  • add: supported encodings UTF-32 (LE and BE, with and without BOM)

1.0.318 (app 1.92.0)

  • add: Editor.action: EDACTION_FIND_ONE
  • add: Editor.action: EDACTION_FIND_ALL

1.0.319 (app 1.92.5)

  • removed: menu_proc special constant "_enc"

1.0.320 (app 1.94.0)

  • change: event on_state does not support EDSTATE_ values
  • change: events are now called with ed_self==None: on_state, on_start, on_exit, on_output_nav, on_console_nav
  • add: event on_state_ed

1.0.321 (app 1.94.5)

  • add: events on_open / on_open_pre support filtering via "keys=" in install.inf like on_key

1.0.322 (app 1.96.2)

  • add: Editor.action: EDACTION_FIND_ALL supports param3
  • add: lexer_proc: LEXER_DETECT can give tuple result

1.0.323 (app 1.97.1)

  • add: Editor.get_prop/set_prop: PROP_SCALE_FONT

1.0.324 (app 1.97.2)

  • add: app_proc: PROC_SET_FOLDER
  • add: file_open: added option "/nolexerdetect"
  • add: file_open: added option "/noopenedevent"
  • add: file_open: added option "/nononeevent"

1.0.325 (app 1.97.5.2)

  • add: Editor.get_prop: PROP_IN_SESSION
  • add: Editor.get_prop: PROP_IN_HISTORY

1.0.326 (app 1.98.3)

  • add: dlg_proc: DLG_CTL_PROP_GET returns also the parent info in key "p"

1.0.327 (app 1.99.5)

  • add: event "on_click_link"
  • add: install.inf supports sections "bottombar*" to show button on sidebar near Console/Output, without loading the plugin
  • change: install.inf supports sections "item*", earlier allowed sections were limited by regex "item\d+"
  • change: install.inf supports sections "sidebar*", earlier allowed sections were limited by regex "sidebar\d+"
  • change: install.inf supports sections "treehelper*", earlier allowed sections were limited by regex "treehelper\d+"
  • add: dlg_proc: control "radiogroup" supports event "on_change"
  • add: dlg_proc: control "checkgroup" supports event "on_change"

1.0.328 (app 1.100.5)

  • change: changed format of string in PROP_UNDO_DATA, PROP_REDO_DATA (field "line state" was inserted in the middle of lines, could not append it to the end)

1.0.329 (app 1.101.0)

  • add: event "on_message"

1.0.330 (app 1.102.2)

  • add: Editor.get_prop/set_prop: PROP_FONT, PROP_FONT_B, PROP_FONT_I, PROP_FONT_BI
  • add: Editor.get_prop/set_prop: PROP_ZEBRA_STEP
  • add: Editor.get_prop/set_prop: PROP_LINKS_SHOW
  • add: Editor.get_prop/set_prop: PROP_LINKS_REGEX
  • add: Editor.get_prop/set_prop: PROP_LINKS_CLICKS
  • add: dlg_proc: editor event "on_click_link"

1.0.331 (app 1.102.6)

  • add: Editor.micromap()
  • change: Editor.action: deleted actions EDACTION_MICROMAPCOL_*
  • add: constant "cudatext.API", which will replace "cudatext.app_api_version" later

1.0.332 (app 1.102.7)

  • add: lexer_proc: LEXER_ADD_VIRTUAL
  • add: finder options as string (several APIs): support also "b" for backward search
  • add: Editor.action: EDACTION_REPLACE_ONE

1.0.333 (app 1.103.2)

  • add: Editor.action: EDACTION_REPLACE_ALL

1.0.334 (app 1.104.1)

  • add: dlg_menu: params "clip", "w", "h"
  • add: dlg_commands: COMMANDS_CONFIG_LEXER

1.0.335 (app 1.104.5)

  • add: dlg_commands: params "w", "h"
  • add: support encodings "koi8r", "koi8u", "koi8ru"

1.0.336 (app 1.105.1)

  • add: Editor.set_prop: PROP_ENC_RELOAD

1.0.337 (app 1.105.1)

  • fix: lexer_proc: LEXER_GET_PROP didn't return "sub" key
  • add: lexer_proc: LEXER_GET_PROP returns new "kinds" key
  • add: Editor.get_token: TOKEN_LIST_ALT

1.0.338 (app 1.105.2)

  • add: msg_box_ex: added param "focused"

1.0.339 (app 1.105.3)

  • deleted: Editor.get_token: TOKEN_LIST_ALT
  • add: Editor.get_token: TOKEN_LIST* return additional keys "ki", "ks"
  • add: lexer_proc: LEXER_GET_STYLES returns additional key "tkind"

1.0.340 (app 1.105.3)

  • add: Editor.get_prop/set_prop: PROP_V_WIDTH_HEX, PROP_V_WIDTH_UHEX
  • add: Editor.set_prop: setting PROP_V_MODE for usual editor switches editor to viewer, with given mode
  • add: Editor.get_prop/set_prop: can switch from viewer to editor using new value VMODE_NONE

1.0.341 (app 1.105.6)

  • add: Editor.action: EDACTION_UPDATE handles "param1"

1.0.342 (app 1.106.1)

  • add: support loading plugin events also from settings/plugins.ini [events] cuda_modulename=comma_separated_events
  • change: Editor.action: EDACTION_FIND* and EDACTION_REPLACE* return False for incorrect RegEx
  • add: Editor.set_prop: PROP_PREVIEW is writable now

1.0.343 (app 1.106.8)

  • add: app_proc: PROC_CONFIG_SCALE_GET, PROC_CONFIG_SCALE_SET
  • add: finder_proc()

1.0.344 (app 1.106.8)

  • add: dlg_proc: controls "editor_edit", "editor_combo"
  • add: Editor.get_prop/set_prop: PROP_COMBO_ITEMS

1.0.345 (app 1.107.0)

  • add: override Python's builtins.input() with CudaText implementation

1.0.346 (app 1.107.2)

  • add: dlg_menu: option MENU_EDITORFONT

1.0.347 (app 1.107.6)

  • add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new keys: "find_h", "rep_h"

1.0.348 (app 1.108.0)

  • add: Editor.action: EDACTION_UNDOGROUP_BEGIN, EDACTION_UNDOGROUP_END

1.0.349 (app 1.108.6)

  • add: dlg_proc: DLG_POS_GET_STR, DLG_POS_SET_FROM_STR

1.0.350 (app 1.110.0)

  • add: toolbar_proc: actions TOOLBAR_ADD_ITEM, TOOLBAR_ADD_MENU return handle of new button
  • change: Editor.complete: "tooltip" line part is now shown only in tooltip, but not in listbox
  • add: Editor.complete: "tooltip" line part can be multi-line, separator is chr(2)

1.0.351 (app 1.114.0)

  • add: event on_app_activate
  • add: event on_app_deactivate

1.0.352 (app 1.115.6)

  • add: app_path: APP_DIR_SETTINGS_DEF
  • add: file_open: added option "/nontext-view-uhex"

1.0.353 (app 1.115.7)

  • add: Editor.markers: add param "line_len"
  • add: Editor.markers: MARKERS_GET_DICT

1.0.354 (app 1.117.2)

  • add: Editor.bookmark: BOOKMARK_GET_ALL gets additional dict key "auto_delx"

1.0.355 (app 1.119.5)

  • change: Editor.attr: change param 'map_only' type from bool to int (enum)

1.0.357 (app 1.121.4)

  • add: statusbar_proc: STATUSBAR_SET_CELL_CALLBACK, STATUSBAR_GET_CELL_CALLBACK
  • add: app_proc: PROC_GET_UNIQUE_TAG

1.0.358 (app 1.123.0)

  • add: dlg_proc: added props for control "listview": "imagelist_small", "imagelist_large", "imageindexes"
  • add: tree_proc: added param "data" for TREE_ITEM_ADD
  • add: tree_proc: added result key "data" for TREE_ITEM_GET_PROPS
  • add: tree_proc: added TREE_ITEM_ENUM_EX

1.0.360 (app 1.123.0)

  • add: dlg_proc: controls "tabs"/"pages" give property "tab_hovered"
  • add: dlg_proc: control "pages" gives property "ex0" for tab-position
  • change: dlg_proc: control "tabs" gives prop "ex0" with 4 values '0'..'3', previously it was bool '0'/'1'
  • add: toolbar_proc: add TOOLBAR_GET_INDEX_HOVERED

1.0.362 (app 1.123.2)

  • add: dlg_proc: DLG_PROP_GET returns also events, if they are set: 'on_close', 'on_close_query', 'on_key_down', 'on_key_up', 'on_resize', 'on_mouse_enter', 'on_mouse_exit', 'on_show', 'on_hide'
  • add: dlg_proc: DLG_CTL_PROP_GET returns also events, if they are set: 'on_change', 'on_click', 'on_click_dbl', 'on_focus_enter', 'on_focus_exit', 'on_menu', 'on_select', 'on_fold', 'on_unfold', 'on_listbox_draw_item', 'on_mouse_enter', 'on_mouse_exit', 'on_mouse_down', 'on_mouse_up', 'on_editor_caret', 'on_editor_scroll', 'on_editor_key_down', 'on_editor_key_up', 'on_editor_click_gutter', 'on_editor_click_gap', 'on_editor_click_link', 'on_editor_paste'
  • add: app_proc: add PROC_GET_CONSOLE_FORM
  • deleted: editor objects "ed_con_log", "ed_con_in"

1.0.364 (app 1.123.5)

  • change: dlg_menu: make aliases of MENU_* constants to DMENU_*; old MENU_ names are deprecated
  • add: app_proc: PROC_CLIP_ENUM
  • add: app_proc: PROC_CLIP_SAVE_PIC

1.0.365 (app 1.124.1)

  • add: dlg_proc: property 'tab_hovered' is now returned also for controls 'toolbar', 'statusbar'
  • add: dlg_proc: DLG_TO_FRONT
  • add: dlg_proc: DLG_CTL_TO_FRONT, DLG_CTL_TO_BACK
  • add: Editor.get_prop: PROP_RECT_GUTTER, PROP_RECT_MINIMAP, PROP_RECT_MICROMAP, PROP_RECT_RULER
  • add: app_proc: PROC_SIDEPANEL_SET_PROP
  • add: app_proc: PROC_BOTTOMPANEL_SET_PROP
  • add: app_proc: PROC_SIDEPANEL_GET_IMAGELIST

1.0.366 (app 1.124.1)

  • add: app_proc: PROC_SIDEPANEL_ENUM_ALL
  • add: app_proc: PROC_BOTTOMPANEL_ENUM_ALL
  • deprecated: app_proc: PROC_SIDEPANEL_ENUM
  • deprecated: app_proc: PROC_BOTTOMPANEL_ENUM

1.0.367 (app 1.124.3)

  • add: Editor.get_prop/set_prop: PROP_FOCUSED
  • fix: control 'statusbar' crashed with "align" left/right/client

1.0.368 (app 1.125.0)

  • add: can compare Editor objects by ==, it will be correct now because tests PROP_HANDLE_SELF values

1.0.369 (app 1.125.0)

  • add: statusbar_proc: STATUSBAR_GET_CELL_COLOR_LINE
  • add: statusbar_proc: STATUSBAR_SET_CELL_COLOR_LINE
  • add: statusbar_proc: STATUSBAR_GET_CELL_COLOR_LINE2
  • add: statusbar_proc: STATUSBAR_SET_CELL_COLOR_LINE2
  • add: statusbar_proc: STATUSBAR_GET_CELL_OVERLAY
  • add: statusbar_proc: STATUSBAR_SET_CELL_OVERLAY
  • add: button_proc: BTN_GET_OVERLAY
  • add: button_proc: BTN_SET_OVERLAY
  • add: button_proc: BTN_GET_COLOR_LINE
  • add: button_proc: BTN_SET_COLOR_LINE
  • add: button_proc: BTN_GET_COLOR_LINE2
  • add: button_proc: BTN_SET_COLOR_LINE2

1.0.370 (app 1.128.1)

  • deleted deprecated API: dlg_proc/dlg_custom "props" - now use "ex0"..."ex9"

1.0.371 (app 1.128.5)

  • add: Editor.get_prop/set_prop: PROP_MASKCHAR
  • add: Editor.get_prop/set_prop: PROP_MASKCHAR_USED

1.0.372 (app 1.128.5)

  • add: Editor.get_prop/set_prop: PROP_NUMBERS_ONLY
  • add: Editor.get_prop/set_prop: PROP_NUMBERS_NEGATIVE

1.0.373 (app 1.129.4)

  • change: timer_proc: minimal interval is now 10 msec
  • change: timer_proc: specifying interval<10 will run timer with value 10

1.0.374 (app 1.129.7)

  • change: Editor.get_carets() returns [] if no items
  • change: Editor.markers(MARKERS_GET) returns [] if no items
  • change: Editor.attr(MARKERS_GET) returns [] if no items

1.0.375 (app 1.129.8)

  • add: Editor.get_prop/set_prop: PROP_TAB_PINNED
  • add: on_state_ed: new flag EDSTATE_PINNED
  • add: on_state_ed: new flag EDSTATE_READONLY
  • add: on_state_ed: new flag EDSTATE_WRAP

1.0.376 (app 1.130.1)

  • add: on_func_hint() propagation can be stopped by returning True
  • change: Editor.bookmark returns [] if no items
  • change: Editor.hotspots returns [] if no items
  • change: Editor.decor returns [] if no items
  • change: Editor.get_wrapinfo returns [] if no items
  • change: Editor.folding returns [] if no items
  • change: Editor.dim returns [] if no items
  • change: Editor.gap returns [] if no items

1.0.377 (app 1.130.5)

  • change: changed values of cCommand_MoveSelection* commands

1.0.379 (app 1.131.0)

  • add: file_open: added option "/noloadundo"
  • add: app_proc: PROC_GET_OUTPUT_FORM
  • add: app_proc: PROC_GET_VALIDATE_FORM

1.0.381 (app 1.131.1)

  • change: app_log: param "tag" is now ignored
  • add: on_state supports also APPSTATE_SESSION_LOAD_BEGIN, APPSTATE_SESSION_LOAD_FAIL

1.0.383 (app 1.132.0)

  • add: msg_status_alt: added params "pos", "x", "y"
  • add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new key "op_hi_d"

1.0.385 (app 1.132.0)

  • add: app_proc: PROC_SET_PROJECT
  • add: event on_state supports also APPSTATE_PROJECT
  • add: event on_console_nav: also it's called when Console input is changed

1.0.388 (app 1.132.9)

  • add: dlg_proc: control "splitter" supports property "color"
  • add: dlg_proc: control "listbox_ex" supports event "on_click_header"
  • add: listbox_proc: LISTBOX_GET_HEADER, LISTBOX_SET_HEADER
  • add: listbox_proc: LISTBOX_GET_HEADER_IMAGELIST, LISTBOX_SET_HEADER_IMAGELIST
  • add: listbox_proc: LISTBOX_GET_HEADER_IMAGEINDEXES, LISTBOX_SET_HEADER_IMAGEINDEXES
  • fix: controls "editor_edit" and "editor_combo" didn't support PROP_RO

1.0.390 (app 1.133.0)

  • change: listbox_proc: LISTBOX_SET_COLUMNS calcs "percent values" (value<0) after the counting "pixel values" (value>0)
  • add: dlg_proc: control "listbox_ex" border is themed now
  • add: app_proc: PROC_GET_OS_SUFFIX

1.0.391 (app 1.133.1)

  • add: tree_proc: TREE_ITEM_SELECT with id_item=0 removes the selection

1.0.392 (app 1.133.2)

  • add: event on_state supports also APPSTATE_CODETREE_*
  • add: app_proc: PROC_SIDEPANEL_ENUM_ALL/PROC_BOTTOMPANEL_ENUM_ALL gets also button handles

1.0.393 (app 1.133.6)

  • add: Editor.gap: add GAP_DELETE_BY_TAG
  • add: Editor.gap: GAP_ADD can also add the dialog, using its handle

1.0.394 (app 1.134.1.2)

  • add: app_proc: PROC_GET_MAIN_TOOLBAR
  • add: app_proc: PROC_GET_MAIN_STATUSBAR
  • delete: redundant "API" constant which had the API version (seems no one used it)
  • deprecate: toolbar_proc() special string handle "top"
  • deprecate: statusbar_proc() special string handle "main"

1.0.397 (app 1.135.2)

  • add: Editor.get_wrapinfo: add optional params to specify lines range
  • add: Editor.convert: CONVERT_OFFSET_TO_CARET
  • add: Editor.convert: CONVERT_CARET_TO_OFFSET
  • add: Editor.get_prop/set_prop: PROP_TAB_UI_SHOW
  • add: editors in ui-tabs are now placed on a hidden form to support dlg_proc() API, you can get this form's handle via PROP_HANDLE_PARENT

1.0.398 (app 1.136.1)

  • add: tree_proc: TREE_FIND_FOR_TEXT_POS

1.0.399 (app 1.136.2)

  • add: statusbar_proc: STATUSBAR_GET_PADDING
  • add: statusbar_proc: STATUSBAR_SET_PADDING

1.0.401 (app 1.137.1)

  • add: statusbar_proc: STATUSBAR_GET_SEPARATOR
  • add: statusbar_proc: STATUSBAR_SET_SEPARATOR
  • add: statusbar_proc: STATUSBAR_GET_COLOR_BORDER_BOTTOM
  • add: statusbar_proc: STATUSBAR_SET_COLOR_BORDER_BOTTOM
  • add: statusbar_proc: STATUSBAR_GET_OVERFLOW_LEFT
  • add: statusbar_proc: STATUSBAR_SET_OVERFLOW_LEFT
  • add: statusbar_proc: STATUSBAR_GET_CELL_RECT

1.0.402 (app 1.137.3)

  • add: dlg_proc: forms have the "on_form_state" event
  • add: dlg_proc: forms have additional property "form_state"
  • deleted deprecated: MENU_LIST, MENU_LIST_ALT, MENU_NO_FUZZY, MENU_NO_FULLFILTER, MENU_CENTERED, MENU_EDITORFONT

1.0.403 (app 1.137.3)

  • add: code-tree is compatible with dlg_proc() API, you can get its form handle via app_proc(PROC_SIDEPANEL_GET_CONTROL, 'Code tree')
  • add: tree_proc: TREE_SET_IMAGELIST
  • add: file_open: option "/donear"

1.0.404 (app 1.137.7)

  • add: forms now have "on_key_press" event

1.0.405 (app 1.139.0)

  • add: Editor.action: EDACTION_APPLY_THEME

1.0.406 (app 1.139.1)

  • add: on_state_ed is fired with EDSTATE_ZOOM
  • add: on_state_ed is fired with EDSTATE_BOOKMARK

1.0.407 (app 1.139.2)

  • add: Editor.get_prop/set_prop: PROP_THEMED
  • add: app_proc: PROC_GET_KEYSTATE returns flags for 4th/5th mouse buttons

1.0.408 (app 1.140.6)

  • add: Editor.get_prop: PROP_COMMAND_LOG
  • add: Editor.get_prop/set_prop: PROP_COMMAND_LOG_LIMIT

1.0.409 (app 1.142.0)

  • change: auto-completion is allowed in comments, if lexer name has 'HTML'
  • add: event "on_cli"

1.0.410 (app 1.142.1)

  • deprecate: option CARET_OPTION_UNFOLD (it's always On now)
  • add: event on_state supports also APPSTATE_API_SUBCOMMANDS, APPSTATE_API_MENU_xxxx

1.0.411 (app 1.145.1)

  • add: callbacks (e.g. in toolbar buttons) can have form "exec=command_line_here"
  • add: app_proc: PROC_PARSE_COMMAND_LINE

1.0.412 (app 1.146.1)

  • change: command "macros: start recording" is renamed to "start/stop recording", commands "stop recording" and "cancel recording" are deprecated

1.0.413 (app 1.148.1)

  • add: dlg_proc: new control "scrollbox"

1.0.414 (app 1.149.4)

  • add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new keys "op_regex_subst", "op_regex_subst_d"

1.0.415 (app 1.153.1)

  • add: app_proc: PROC_SAVE_SESSION supports additional parameters

1.0.416 (app 1.157.2)

  • add: app_proc: PROC_GET_CLIP_EX
  • add: app_proc: additional chars in result of PROC_CLIP_ENUM
  • deleted deprecated: "resize" property of forms in dlg_proc()

1.0.417 (app 1.157.6)

  • add: app_proc: PROC_GET_COMPILER_INFO

1.0.418 (app 1.158.3)

  • add: app_proc: session-related actions support specifying of JSON path for sessions

1.0.419 (app 1.159.0)

  • add: event on_delete_file

1.0.420 (app 1.159.3)

  • add: Editor.decor: allow to fill cell background, if "text" is empty and "image" is -1
  • add: Editor.decor: allow 2 decor items for the same line index

1.0.421 (app 1.163.2)

  • add: tree_proc: TREE_GET_MULSELECT, TREE_SET_MULSELECT
  • add: tree_proc: TREE_GET_SELECTIONS

1.0.422 (app 1.166.0)

  • add: ed.get_prop/set_prop: PROP_V_ENC
  • add: app_proc: PROC_ENUM_ENCODINGS

1.0.423 (app 1.166.1)

  • add: Editor.cmd: cmd(cmd_DialogCommands, text) now sets text as initial filter of Command Palette
  • add: Editor.set_text_line: support special value -2

1.0.424 (app 1.166.4)

  • add: Editor.markers: MARKERS_DELETE_BY_POS
  • add: Editor.attr: MARKERS_DELETE_BY_POS

1.0.425 (app 1.166.6)

  • add: Editor.get_prop/set_prop: PROP_GUTTER_EMPTY
  • add: Editor.get_prop/set_prop: PROP_GUTTER_EMPTY_WIDTH
  • add: Editor.attr: MARKERS_ADD_MANY allows lists for params "color_*" and "font_*"
  • add: Editor.markers/attr: MARKERS_GET_DUPS
  • add: Editor.markers/attr: MARKERS_SET_DUPS
  • add: event "on_sidebar_popup"

1.0.426 (app 1.167.2)

  • add: Editor.get_prop/set_prop: PROP_WHEEL_ZOOMS

1.0.427 (app 1.169.1)

  • add: Editor.decor: item "text" can contain tooltip after chr(1)

1.0.428 (app 1.169.5)

  • add: event "on_caret_slow"
  • add: app_proc: PROC_GET_AUTOCOMPLETION_INVOKE
  • add: Editor.get_prop/set_prop: PROP_TAB_COLOR_FONT

1.0.429 (app 1.170.1)

  • add: dlg_proc: form property "taskbar"
  • add: Editor.get_prop/set_prop: PROP_DIM_UNFOCUSED

1.0.430 (app 1.171.0)

  • delete deprecated: statusbar_proc special handle 'main'
  • delete depreacted: toolbar_proc special handle 'top'
  • add: statusbar_proc: STATUSBAR_MOVE_CELL
  • add: Editor.get_prop/set_prop: PROP_CARET_MULTI
  • add: Editor.set_prop: PROP_TAB_TITLE setting to empty str, resets the caption
  • fix: Editor.action: EDACTION_UPDATE did not work sometimes (cmd_RepaintEditor worked better)

1.0.431 (app 1.171.5)

  • add: Editor.complete, Editor.complete_alt: if cell begins with "<html>", HTML tags are allowed: b, i, u, s
  • add: Editor.get_prop/set_prop: PROP_MINIMAP_CHAR_WIDTH
  • add: Editor.get_prop/set_prop: PROP_MINIMAP_SCALE
  • add: Editor.get_prop/set_prop: PROP_MINIMAP_AT_LEFT

1.0.432 (app 1.172.1)

  • delete deprecated: PROC_SIDEPANEL_ENUM
  • delete deprecated: PROC_BOTTOMPANEL_ENUM

1.0.433 (app 1.173.0)

  • add: Editor.complete, Editor.complete_alt: support HTML tag "font color=..."

1.0.435 (app 1.176.5)

  • add: event on_start2
  • add: Editor() supports handle==1 to get editor from right-clicked tab

1.0.436 (app 1.178.0)

  • add: event on_tab_menu

1.0.437 (app 1.180.5)

  • add: event on_click_right

1.0.438 (app 1.182.0)

  • add: Editor.action: EDACTION_EXPORT_HTML: added optional params "line_begin", "line_end", "col_begin", "col_end"
  • add: Editor.action: EDACTION_EXPORT_HTML: allow to export to memory by specifying "file_name" as "-"
  • add: app_proc: PROC_SET_CLIP_HTML
  • add: Editor.get_prop/set_prop: PROP_TAB_TITLE_REASON

1.0.439 (app 1.184.0)

  • add: Editor.get_prop/set_prop: PROP_RULER_TEXT (it allows HTML formatting too)

1.0.441 (app 1.185.5)

  • add: app_proc: PROC_GET_FINDER_PROP/PROC_SET_FINDER_PROP support new keys "op_prescase", "op_prescase_d"
  • add: menu_proc: MENU_SET_AUTO_HOTKEY, MENU_SET_AUTO_HOTKEY_DEEP

1.0.442 (app 1.186.1)

  • add: event on_caret_line
  • add: Editor.get_line_len()

1.0.443 (app 1.186.5)

  • add: app_proc: PROC_GET_WINDOW_STATE
  • add: event on_state supports also APPSTATE_WINDOW
  • fix: event on_click_gutter was not called for gutter bands "line numbers" and "folding"
  • add: event on_click_gutter was not able to block default processing

1.0.444 (app 1.189.0)

  • add: event on_console_complete
  • add: Editor(h).cmd(cmd_FileClose) now closes the handle's ui-tab (before it closed the active tab)

1.0.445 (app 1.190.1)

  • add: Editor.get_prop/set_prop: PROP_TAB_SMART

1.0.446 (app 1.195.1)

  • delete event on_caret_line

1.0.447 (app 1.196.3)

  • add: PROC_GET_FINDER_PROP new option "op_wrap_c", and new option "A" in the string form of search options

1.0.448 (app 1.197.0)

  • add: Editor.folding: FOLDING_ENUM
  • add: Editor.folding: add optional params "item_x2", "item_tag"
  • deprecate FOLDING_GET_LIST and FOLDING_GET_LIST_FILTERED (use FOLDING_ENUM instead of them)
  • add: Editor.get_prop/set_prop: PROP_BORDER_COLOR
  • add: Editor.get_prop/set_prop: PROP_BORDER_COLOR_WIDTH
  • add: Editor.get_prop/set_prop: PROP_CORNER_TEXT
  • add: Editor.get_prop/set_prop: PROP_CORNER_COLOR_FONT
  • add: Editor.get_prop/set_prop: PROP_CORNER_COLOR_BACK
  • add: Editor.get_prop/set_prop: PROP_CORNER_COLOR_BORDER
  • add: Editor.get_prop/set_prop: PROP_CORNER2_TEXT
  • add: Editor.get_prop/set_prop: PROP_CORNER2_COLOR_FONT
  • add: Editor.get_prop/set_prop: PROP_CORNER2_COLOR_BACK
  • add: Editor.get_prop/set_prop: PROP_CORNER2_COLOR_BORDER

1.0.449 (app 1.206.0)

  • add: event on_init_plugins_menu
  • change: initing of "Plugins" menu is now performed _after_ on_start2, before on_init_plugins_menu
  • change: menu_proc: don't return redundant dict key 'command'
  • change: menu_proc: don't return dict keys if they are defaults: 'vis', 'en', 'checked', 'radio', 'hotkey', 'hint', 'tag'
  • add: menu items in "Plugins" menu support introspection by menu_proc() better: "hint" property is filled for them now

1.0.450 (app 1.206.4)

  • delete deprecated actions FOLDING_GET_LIST and FOLDING_GET_LIST_FILTERED (use FOLDING_ENUM instead of them)
  • add: file_open: option "/noupdateaddons"

1.0.451 (app 1.206.6)

  • delete deprecated key "auto_del" in results of BOOKMARK_GET_ALL
  • change: Editor.get_prop/set_prop: PROP_ACTIVATION_TIME is now available for editors created via dlg_proc; it is different now for primary/secondary editor in the same ui-tab

1.0.452 (app 1.209.0)

  • add: Editor.decor: DECOR_GET_ALL now can return all items for given line, if "line">=0
  • add: Editor.save: add optional parameter "as_copy"
  • add: PROP_CORNER_TEXT supports multi-line text
  • add: Editor.get_prop/set_prop: PROP_CORNER_FONT_NAME
  • add: Editor.get_prop/set_prop: PROP_CORNER_FONT_SIZE
  • add: Editor.get_prop/set_prop: PROP_CORNER2_FONT_NAME
  • add: Editor.get_prop/set_prop: PROP_CORNER2_FONT_SIZE

1.0.453 (app 1.210.5)

  • add: image_proc: support WEBP format

1.0.454 (app 1.211.3)

  • add: Editor.get_char_count
  • add: Editor.action: EDACTION_FIND_ALL supports multi-selections when searching with 's' option (before it handled only first selection)
  • delete deprecated CARET_OPTION_UNFOLD