CudaText API

From Free Pascal wiki
Jump to: navigation, search

Contents

Intro

This is API for CudaText in Python.

  • Main module: cudatext. Has constants, funcs, class Editor, objects of class Editor.
  • Additional module: cudatext_cmd, constants for ed.cmd().
  • Additional module: cudatext_keys, constants for on_key.
  • Additional module: cudax_lib, some high-level functions for plugins.

Event plugins

To make plugin react to events, add method to class Command (like methods of command plugin). E.g. method "on_save" will be called by editor event "on_save". Event methods have param "ed_self": Editor object in which event occured (this object is the same as "ed" in 99% cases, but in some cases event occurs in inactive editor, e.g. "Save all tabs" calls "on_save" for inactive tabs).

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_close(self, ed_self): Called just before closing tab (closing editor is still active).
  • on_save_pre(self, ed_self): Called before saving file. Method can return False to disable saving, other value is ignored.
  • on_save(self, ed_self): Called after saving file.
  • on_start(self, ed_self): Called once on program start (ignore ed_self).
  • 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).

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 few seconds (option) passed. Used in CudaLint plugin, it needs to react to change after a delay.
  • on_caret(self, ed_self): Called after editor caret position and/or selection is changed.
  • 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 any editor's lexer is changed.
  • 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_state(self, ed_self, state): Called after some app 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_group(self, ed_self): Called after tab-grouping mode is changed.

Editor clicks

  • on_click(self, ed_self, state): Called after mouse click. Param "state": same meaning as in on_key.
  • on_click_dbl(self, ed_self, state): Called after mouse double-click. Param "state": same meaning as in on_key. 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.

Smart commands

  • on_complete(self, ed_self): Called by auto-completion command (default hotkey: Ctrl+Space). Method should call Editor.complete API. Method must return True if it handled command, otherwise None.
  • on_func_hint(self, ed_self): Called by function-hint command (default hotkey: Ctrl+Shift+Space). Method must return function-hint string (comma-separated parameters, brackets are optional). Empty str or None means no hint found.
  • on_goto_def(self, ed_self): Called by go-to-definition command (in editor context menu). Method must return True if it handled command, otherwise None.

Panels

  • on_console(self, ed_self, text): Called on entering text command in Python Console panel. Method can return False to disable internal command processing, other value is ignored. Ignore ed_self.
  • on_console_nav(self, ed_self, text): Called on dbl-clicking line, or calling context menu item "Navigate", in Python Console panel. Ignore ed_self. Text is line with caret.
  • on_output_nav(self, ed_self, text, tag): Called on clicking line, or pressing Enter, in Output or Validate panel. Ignore ed_self. Text is clicked line, tag is int value associated with line. Event is called only if app cannot parse output line by itself using given regex (or regex isn't set at all).

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".
    • if item is "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 "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.

Dialog "Go to"

  • on_goto_enter(self, ed_self, text): Called when user entered (via button or Enter key) text in the "Go to" dialog. Plugin can perform custom action for parameter "text" (e.g. if it has some prefix/suffix). Method can return False to disable default action "go to line number".
  • on_goto_change(self, ed_self): Called when text is changed in the "Go to" dialog input. Param "ed_self" is the same as ed_goto object.
  • on_goto_caret(self, ed_self): Called when caret/selection is moved in the "Go to" dialog input. Param "ed_self" is the same as ed_goto object.
  • on_goto_key(self, ed_self, key, state): Called when a key is pressed in the "Go to" dialog input. Param "ed_self" is the same as ed_goto object. Params "key", "state" have the same meaning as in the "on_key" event. Method can return False to disable default key processing.
  • on_goto_key_up(self, ed_self, key, state): Called when a key is depressed in the "Go to" dialog input. Params: the same as in the "on_goto_key".

Events priority

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

You may want to handle some event first. To change prior 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 prior. So first called "on_key" with maximal number of "+", last called "on_key" w/o "+".

Callback param

Callback parameter is supported in several API functions: dlg_proc, timer_proc, menu_proc (maybe more later).

Parameter can be in these forms:

  • callable, i.e. name of a function
  • 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

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 funcs

version

app_exe_version()

Gets version of program (string).

app_api_version()

Gets version of API (string, contains 3 numbers, dot-separated).

Example of version check:

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

app_path

app_path(id)

Gets some path. Possible values of id:

  • APP_DIR_EXE: Dir of program executable.
  • APP_DIR_SETTINGS: Dir "settings".
  • APP_DIR_DATA: Dir "data".
  • APP_DIR_PY: Dir "py" with Python files.
  • APP_DIR_INSTALLED_ADDON: Dir 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_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_RECENTS: Str: "\n"-separated filenames of recent files.

Note: to get path of dir "settings_default", use base dir of "settings".

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).

Misc properties

  • PROC_GET_LANG: Gets string id of active translation. E.g. "ru_RU" if translation file is "ru_RU.ini". Or "translation template" if such file is used. Empty string if built-in English translation is used.
  • PROC_GET_GROUPING: Gets grouping mode in program, it's one of GROUPS_nnnn int contants.
  • PROC_SET_GROUPING: Sets grouping mode in program, pass str(value) where value is one of GROUPS_nnnn int contants.
  • PROC_GET_FIND_OPTIONS: Gets options of finder-object as string.
  • PROC_SET_FIND_OPTIONS: Sets options of finder-object from string. Note: Find dialog don't apply these opts immediately.
  • PROC_GET_FIND_STRINGS: Gets strings of finder-object, 2-tuple, (str_search_for, str_replace_with), or None if finder-object not inited.
  • PROC_PROGRESSBAR: Change state of the progress-bar, which is located on the status-bar (hidden by default). If passed int value<0, progressbar hides, else it shows with the given value 0..100.
  • PROC_GET_TAB_IMAGELIST: Gets int handle of imagelist, for file tabs. Use imagelist_proc() to work with it. Use PROP_TAB_ICON editor property to get/set icons of file tabs.

System

  • PROC_ENUM_FONTS: Gets 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_GET_SYSTEM_PPI: Gets 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: Gets height (pixels) of GUI element for dlg_custom(). Possible values of text: 'button', 'label', 'combo', 'combo_ro', 'edit', 'spinedit', 'check', 'radio', 'checkbutton', 'filter_listbox', 'filter_listview'. Gets None for other values.

Clipboard

  • PROC_GET_CLIP: Gets clipboard text.
  • PROC_SET_CLIP: Copies text to clipboard (usual).
  • PROC_SET_CLIP_ALT: Copies text to alternate clipboard on Linux gtk2, called "primary selection" (also "secondary selection" exists, but no API for it here).
    • CudaText copy commands put text to usual clipboard + primary selection.
    • CudaText paste commands get text from usual clipboard.
    • CudaText option "mouse_mid_click_paste" gets text from primary selection.

Plugin calls

  • PROC_SET_EVENTS: Subscribe plugin to events. Param text must be 4 values ";"-separated: "module_name;event_list;lexer_list;keycode_list".
    • event_list is comma-separated event names. e.g. "on_open,on_save", or empty str to unsubscribe from all.
    • lexer_list is comma-separated lexer names.
    • keycode_list is comma-separated int key codes, it can be used when on_key event was specified (event will fire only for specified key codes).
  • PROC_GET_LAST_PLUGIN: Gets 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 for plugin (for fixed module/method). Param text must be ";"-separated: "module_name;method_name;param_list". Param_list is "\n"-separated items. Each item is s_caption+"\t"+s_param_value. s_caption is caption for Commands dialog item, s_param_value is parameter for Python method (it can be any primitive type: 20, None, False, 'Test here', or expression).
  • PROC_GET_COMMAND: Gets info about item from application commands-list, with index int(text), 0-based. Gets tuple: (command_int_code, command_name, hotkey_str_1, hotkey_str_2), or None if index not correct. To enumerate all commands: call it from index "0", until you get None result.
  • PROC_GET_COMMAND_INITIAL: Same as PROC_GET_COMMAND, but gets info only about "initial state", which was before reading hotkey configs (main config and lexer-specific configs).
  • PROC_GET_COMMAND_PLUGIN: Allows to enumerate all command plugins (and items which were set in PROC_SET_SUBCOMMANDS). Call it with str(N), from N=0, until you get None. Gets 5-tuple about N-th item (caption, module, method, param, lexers).
  • PROC_GET_COMMANDS: Gets list of all commands, as list of dict. Dict keys are:
    • "type": str: Possible values: "cmd" (usual command), "lexer" (dynamically added command to activate lexer), "plugin" (dynamically added plugin command).
    • "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.

Hotkeys

Notes:

  • command_id can be: str(int_command_code) or "module,method" or "module,method,param".

Actions:

  • PROC_GET_ESCAPE: Gets Esc-key state (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. Text must be "0"/"1".
  • PROC_GET_HOTKEY: Gets 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). Gets 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. Gets bool: command_id exists, changed.
  • PROC_GET_KEYSTATE: Gets state of pressed special keys. String has "c" for Ctrl pressed, "a" for Alt, "s" for Shift, "m" for Meta (Windows key).
  • PROC_HOTKEY_INT_TO_STR: Converts given int hotkey to string. Gets empty str for unknown code.
  • PROC_HOTKEY_STR_TO_INT: Converts given string hotkey to int. Gets 0 for incorrect string. Example: converts "alt+shift+z" to "41050", which is then converted to "Shift+Alt+Z".

Python

  • PROC_EXEC_PYTHON: Runs Python string in the context of Console (it is not the same as exec() call). Also gets string: result of command.
  • PROC_EXEC_PLUGIN: Runs Python plugin's method. Text must be ","-separated: "module_name,method_name,param_string", where param_string can be missed, this is parameter(s) for method.

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: Gets UI-theme name.
  • PROC_THEME_UI_SET: Sets UI-theme name.
  • PROC_THEME_SYNTAX_GET: Gets syntax-theme name.
  • PROC_THEME_SYNTAX_SET: Sets syntax-theme name.

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. Gets bool: session was saved.
  • PROC_LOAD_SESSION: Loads session from file with given name (closes all tabs first). Gets bool: tabs closed w/o 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.

Side panel

  • PROC_SIDEPANEL_ADD_DIALOG: Adds tab, with embedded dialog, to sidebar. Gets bool: params ok, tab was added. Text is 3-tuple (tab_caption, id_dlg, icon_filename):
    • Caption of tab (must not contain ",")
    • Handle of dialog, from dlg_proc()
    • Name of icon file (must not contain ",")
  • PROC_SIDEPANEL_REMOVE: Removes tab. Text is caption of tab. (Note: actually it hides tab, dialog for this tab is still in memory). Gets bool: tab was found/removed.
  • PROC_SIDEPANEL_ACTIVATE: Activates tab in sidebar. Text must be a) tab caption or b) tuple (tab_caption, bool_set_focus). Default for bool_set_focus is False. Gets bool: tab was found/activated.
  • PROC_SIDEPANEL_ENUM: Enumerates tabs. Gets str, "\n"-separated captions of tabs.
  • PROC_SIDEPANEL_GET_CONTROL: Gets int handle of dialog, inserted into tab. Text is caption of tab. Gets None if cannot find tab.

Notes:

  • Name of icon file: name of .png or .bmp file. Icon size should be equal to size of current sidebar theme, it's default is 20x20. If filename is without path, CudaText sub-dir "data/sideicons" is used.

Bottom panel

  • 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: Enumerates tabs. Same as for PROC_SIDEPANEL_ENUM.
  • PROC_BOTTOMPANEL_GET_CONTROL: Gets int handle of control. Same as for PROC_SIDEPANEL_GET_CONTROL.

Splitters

Splitter id:

  • SPLITTER_SIDE: splitter near side panel.
  • SPLITTER_BOTTOM: splitter above bottom panel.
  • SPLITTER_G1, SPLITTER_G2, SPLITTER_G3: splitters between groups.

Actions:

  • PROC_SPLITTER_GET: Gets 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) 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          
6GRID     t G1 t G2 t     
          G3              
          t G1 t G2 t     

Show/Hide UI elements

Actions can get/set show state of UI elements (pass "0"/"1" or False/True):

  • PROC_SHOW_STATUSBAR_GET
  • PROC_SHOW_STATUSBAR_SET
  • PROC_SHOW_TOOLBAR_GET
  • PROC_SHOW_TOOLBAR_SET
  • PROC_SHOW_SIDEBAR_GET
  • PROC_SHOW_SIDEBAR_SET
  • PROC_SHOW_SIDEPANEL_GET
  • PROC_SHOW_SIDEPANEL_SET
  • PROC_SHOW_BOTTOMPANEL_GET
  • PROC_SHOW_BOTTOMPANEL_SET
  • PROC_SHOW_TABS_GET
  • PROC_SHOW_TABS_SET

Screen coordinates

Notes:

  • When getting or setting coords, you get/set 4-tuple of int: (left, top, right, bottom).

Actions:

  • PROC_COORD_WINDOW_GET: Gets coords of app window.
  • PROC_COORD_WINDOW_SET: Sets coords of app window.
  • PROC_COORD_DESKTOP: Gets coords of virtual desktop, which includes all monitors.
  • PROC_COORD_MONITOR: Gets coords of monitor with app window.
  • PROC_COORD_MONITOR0: Gets coords of 1st monitor.
  • PROC_COORD_MONITOR1: Gets coords of 2nd monitor, or None if no such monitor.
  • PROC_COORD_MONITOR2: Gets coords of 3rd monitor, or None if no such monitor.
  • PROC_COORD_MONITOR3: Gets coords of 4th monitor, or None if no such monitor.

app_log

app_log(id, text, tag=0)

Controls standard panels in the bottom panel: Console, Output, Validate.

Possible values of id:

  • LOG_CLEAR: Clears active log panel, text is ignored.
  • LOG_ADD: Adds line to active log panel. Param "tag" is used here: int value associated with line, it's passed in on_output_nav.
  • LOG_SET_PANEL: Sets active log panel. Text must be name of panel: LOG_PANEL_OUTPUT or LOG_PANEL_VALIDATE. Incorrect text will stop next operations with panels, until correct value is set.
  • LOG_SET_REGEX: Sets parsing regex for active log panel. 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".
  • LOG_SET_NAME_ID: Sets index of regex group for file-name. Param "text".
  • LOG_SET_FILENAME: Sets default file name, which will be used when regex cannot find file name in a string. Param "text".
  • 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_GET_LINES_LIST: Gets items in panel's listbox, as list of 2-tuples (line, tag).
  • LOG_GET_LINEINDEX: Gets index of selected line in panel's listbox.
  • LOG_SET_LINEINDEX: Sets index of selected line in panel's listbox.

For "Python 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: Gets list of lines in combobox-control.
  • LOG_CONSOLE_GET_MEMO_LINES: Gets list of lines in memo-control.

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.

msg_box

msg_box(text, flags)

Shows modal message-box with given text.

Param flags is sum of button-value (OK, OK/Cancel, Yes/No etc) and icon-value (Info, Warning, Error, Question):

  • MB_OK
  • MB_OKCANCEL
  • MB_ABORTRETRYIGNORE
  • MB_YESNOCANCEL
  • MB_YESNO
  • MB_RETRYCANCEL
  • MB_ICONERROR
  • MB_ICONQUESTION
  • MB_ICONWARNING
  • MB_ICONINFO

Gets int code of button pressed:

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

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, else plugin gets old state, until UI messages are processed.

msg_status_alt

msg_status_alt(text, seconds)

Shows given text in alternative statusbar; it has yellowish color and shows on the bottom of current editor.

Time in seconds: 1..30; seconds<=0 hides statusbar (if shown before).

dlg_input

dlg_input(label, defvalue)

Shows modal dialog to input one string.

Gets entered string or None of cancelled.

dlg_input_ex

dlg_input_ex(number, caption,
              label1   , text1="", label2="", text2="", label3="", text3="",
              label4="", text4="", label5="", text5="", label6="", text6="",
              label7="", text7="", label8="", text8="", label9="", text9="",
              label10="", text10="")

Shows modal dialog to enter 1 to 10 strings. Param number is count of strings.

Gets list of entered strings or None if cancelled.

dlg_file

dlg_file(is_open, init_filename, init_dir, filters)

Shows file-open or file-save-as modal dialog.

Gets filename (str) or None if cancelled. Params:

  • is_open: True for open dialog, False for save-as dialog.
  • init_filename: Initial filename for save-as dialog. Can be empty.
  • init_dir: Initial dir for dialog. Can be empty.
  • filters: Sets file filters for dialog. Can be empty. Example, 2 filters: "Texts|*.pas;*.txt|Include|*.inc"

To allow multi-select in open dialog, pass init_filename="*". If single filename selected, result is str. If several filenames selected, result is list of str.

To disable check "filename exists" in open dialog, start init_filename with "!".

dlg_dir

dlg_dir(init_dir)

Shows dialog to select folder. Gets folder path, or None if cancelled.

dlg_menu

dlg_menu(id, items, focused=0, caption="")

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

Possible values of id:

  • MENU_LIST: Dialog with listbox and filter field.
  • MENU_LIST_ALT: Like MENU_LIST, but each item has double height, and instead of right-aligning, part of an item shows below.

Parameters:

  • Param "items": list of str, tuple of str, or string from joined items "\n".join(str_items). Each str item can be simple str or str1+"\t"+str2 (str2 shows right-aligned or below).
  • Param "focused": index of initially selected item.
  • Param "caption": if not empty str, caption will be shown above input box.

dlg_color

dlg_color(value)

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

Gets int color, or None if cancelled.

dlg_hotkey

dlg_hotkey(title="")

Shows dialog to press single hotkey.

Gets 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. Gets 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) can save hotkey to "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.

Types

Possible types of controls:

  • "button": simple button
  • "button_ex": button, but application-themed
  • "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
  • "editor": full featured editor (multi-line by default)
  • "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
  • "listbox_ex": like listbox, but application-themed, and works via listbox_proc()
  • "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
  • "treeview": tree structure with nodes and nested nodes, works via tree_proc()
  • "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
  • "paintbox": control which must be painted by plugin via canvas_proc()
  • "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)
  • "toolbar": ToolBar: panel which holds buttons with icons
  • "splitter": divider bar, which can be moved by mouse, it resizes control with "align" set, with the same "align" which splitter has.

Notes:

  • Control property "name" is required for filter_ controls: must set name of listbox/listview, and name of its filter - to the same name with prefix "f_" (e.g. "name=mylistbox" with "name=f_mylistbox").
  • 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 "editor" 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().

Properties

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

  • "type": type of control; must be specified first
  • "cap": caption
  • "x", "y": position, left/top
  • "w", "h": size, width/height
  • "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.
  • "color": background color
  • "font_name": font name
  • "font_size": font size
  • "font_color": font color
  • "name": optional name of control. It may be not unique for all controls.
  • "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).
  • "props": advanced control-specific properties. Described below.
  • "val": value of control. Described below.
  • "items": list of items. Described below.

Items

Possible values of "items":

  • combo, combo_ro, listbox, checkgroup, radiogroup, checklistbox, tabs: "\t"-separated lines
  • 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)
  • image: full path of picture file (png/gif/jpg/bmp)

Control values

  • check: "0", "1" or "?" (grayed state)
  • radio, checkbutton: "0", "1"
  • edit, edit_pwd, spinedit, combo, filter_*: text
  • memo: "\t"-separated lines, in lines "\t" must be replaced to chr(2)
  • combo_ro, listbox, radiogroup, listview: current index
  • checkgroup: ","-separated checked states ("0", "1")
  • checklistbox, checklistview: index + ";" + checked_states
  • tabs: index of active tab
  • trackbar, progressbar: int position

Advanced properties

Advanced control-specific properties, set by "props".

  • For dlg_custom, must be str with items ","-separated, "0"/"1" for bool.
  • For dlg_proc, can also use simple types bool/int/str or tuple of simple types, e.g. (True,False) instead of "1,0".

Props:

  • button: bool_default_for_enter
  • edit, memo:
    • bool_read_only
    • bool_font_monospaced
    • bool_show_border
  • spinedit:
    • int_min_value
    • int_max_value
    • int_increment
  • label: bool_right_aligned
  • linklabel: URL (clicking on "http:" or "mailto:" should work, result of clicking on other kinds depends on OS)
  • listview: bool_show_grid
  • tabs: bool_tabs_at_bottom
  • colorpanel:
    • int_border_width_from_0
    • int_color_fill
    • int_color_font
    • int_color_border
  • filter_listview: bool_filter_by_all_columns
  • image:
    • bool_center
    • bool_stretch
    • bool_stretch_in_enabled
    • bool_stretch_out_enabled
    • bool_keep_origin_x_when_clipped
    • bool_keep_origin_y_when_clipped
  • trackbar:
    • int_orientation (0: horz, 1: vert)
    • int_min
    • int_max
    • int_line_size
    • int_page_size
    • bool_reversed
    • int_tick_marks (0: bottom-right, 1: top-left, 2: both)
    • int_tick_style (0: none, 1: auto, 2: manual)
  • progressbar:
    • int_orientation (0: horz, 1: vert, 2: right-to-left, 3: top-down)
    • int_min
    • int_max
    • bool_smooth
    • int_step
    • int_style (0: normal, 1: marquee)
    • bool_show_text (only some OSes)
  • progressbar_ex:
    • int_style (0: text only, 1: horz bar, 2: vert bar, 3: pie, 4: needle, 5: half-pie)
    • int_min
    • int_max
    • bool_show_text
    • int_color_back
    • int_color_fore
    • int_color_border
  • bevel:
    • 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:
    • bool_beveled
    • bool_instant_repaint
    • bool_auto_snap_to_edge
    • int_min_size

Result

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

  • If cancelled, gets None
  • If get_dict=True, gets dict: {0: str_value_0, 1: str_value_1, ..., 'clicked': N, 'focused': N}
  • If get_dict=False, gets 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.

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 modal/nonmodal, controls can change value during form showing.

If an action needs control, you can use 2 ways:

  • set param "name" to control's name (name is searched if not empty),
  • set param "index" to control's index (you should use DLG_CTL_FIND to find it).

Types

Described in dlg_custom, see #Types.

Form 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.
  • "tag": str: Any string, set by plugin.
  • "resize": bool: Allows form to resize.
  • "topmost": bool: Makes form stay on top of other forms in CudaText.
  • "vis": bool: Visible state.
  • "color": int: Background color.
  • "autosize": bool: Form resizes to minimal size, which shows all visible controls. Don't use it together with "resize".
  • "border": bool: Enables OS-themed form border (set to false, to make form border-less).
  • "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.

Form 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, it is allowed to close form (in any way: x-icon, Alt+F4, Esc etc). If plugin returns False: not allowed, other value: allowed.
  • "on_act": Called when form is activated.
  • "on_deact": Called when form is deactivated.
  • "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.

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)

Control properties

  • "name": str: Optional name of control, to find control later by name. May be not unique for controls.
  • "cap": str: Caption.
  • "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".
  • "props": str: 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 #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, or empty to use the form. Coordinates x/y of control are relative to the current parent. If parent's position changes, control's position don't change. To place control on PageControl's page with index N, specify such parent name: pages_name+"."+str(N).

Control events

These are also properties of controls.

  • "on_change": Called after "value" of control is changed.
  • "on_click": Called after 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 double-click on control. Param "data" is tuple (x, y) with control-related coordinates.
  • "on_menu": Called before showing context menu after right click.
  • "on_select": Called after selection is changed. For these controls: "treeview", "listview". For "listview", param "data" is 2-tuple (int_item_index, bool_item_selected).
  • "on_fold", "on_unfold": Called for control "treeview", before treeview node is folded/unfolded. Param "data" is int handle of treeview node.
  • "on_draw_item": Called for control "listbox_ex", if it is owner-drawn. Param "data" is dict: { "canvas": canvas_id, "index": int_item_index, "rect": item_rectangle_4_tuple }.

Callbacks

Values of events are callbacks, must be in one of these forms: #Callback_param.

Callbacks for dlg_proc must be declared as:

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

Parameters:

  • id_dlg: Int handle of form.
  • id_ctl: Int index of control. Used only for control events.
  • data: Value, specific to event.
  • info: Value from extended form of callback string.

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 (pass 0).

Possible values of id_action:

  • DLG_CREATE: Creates new form, gets form handle.
  • 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_PROP_GET: Gets 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_CTL_COUNT: Gets count of controls on form.
  • DLG_CTL_ADD: Adds new control to form, gets its index, or None if cannot add. Param "prop" is type of control. See description in dlg_custom.
  • DLG_CTL_PROP_GET: Gets 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: Gets index of control by name, or -1 if cannot find. Param "prop" is name.
  • DLG_CTL_HANDLE: Gets int handle of control. Control must be specified by name or index. This handle is currently useful for types:
    • type "treeview": pass handle to tree_proc()
    • type "listbox_ex": pass handle to listbox_proc()
    • type "paintbox": pass handle to canvas_proc()
  • DLG_COORD_LOCAL_TO_SCREEN: Converts x/y coordinates from form-related, to screen-related. Param "index" is x, "index2" is y. Gets 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. Gets tuple (x,y).

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    |
       +--------------+

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  } )

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)

Show commands dialog, which is like customizable version of F1 dialog in CudaText.

Param options is sum of int flags:

  • COMMANDS_USUAL - Show usual commands, which have int codes. Function gets "c:"+str(int_command) for them.
  • COMMANDS_PLUGINS - Show plugins commands. Function gets "p:"+callback_string for them.
  • COMMANDS_LEXERS - Show lexers pseudo-commands. Function gets "l:"+lexer_name for them.
  • COMMANDS_CONFIG - Allow to call Configure Hotkeys dialog by F9 key.

Gets string if command selected, or None if cancelled.

file_open

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

Opens editor tab with given filename. If filename already opened, activates its tab. Pass empty str to open untitled tab. Gets bool: filename is empty or file successfully opened. For zip files, gets True only if add-on (in zip file) 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 "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 history (caret, scroll pos, etc) won't be used.
    • If it has "/noevent", then on_open_pre event won't fire.
    • If it has "/silent", then zipped add-on will install w/o prompt and report.

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)

file_save

file_save(filename="")

Saves current tab to disk.

Shows save-as dialog for untitled tab. If param "filename" not empty, it overrides current file name, and untitled tab becomes titled. Gets bool: file was saved.

ed_handles

ed_handles()

Gets range object: it contains int handles of all editor tabs. Pass each handle to Editor() to make editor object from handle.

Example code, which shows filenames of all tabs:

    #show all file names in console
    for h in ed_handles():
        e = Editor(h)
        print(e.get_filename())

ed_group

ed_group(index)

Gets Editor object for active editor in tab-group with given group-index. Group-index: currently 0..5. Gets None for incorrect index, or if no tabs in this group.

ini_read/ini_write

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

Reads or writes single string to ini file. Params:

  • filename: Path of ini file. Can be name w/o 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: gets string value. On write: gets None.

lexer_proc

lexer_proc(id, value)

Perform some lexer-related action.

Possible values of id:

  • LEXER_GET_LEXERS: Gets list of lexers. Param "value" must be bool: allow to include also hidden lexers (unchecked in the Lexer Library dialog).
  • LEXER_GET_PROP: For given lexer name, gets its properties as dict. For incorrect lexer name, gets 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).
    • "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_DETECT: Detects lexer name by given file name. Gets None if cannot detect. Function sees file extension, or even filename before extension (e.g. "/path/makefile.gcc" gives "Makefile").

tree_proc

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

Perform action on treeview UI-control.

  • Param id_tree is int handle of treeview.
  • Param id_item is 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 on given item. Param id_item. Gets list of 2-tuples: (int_handle, str_caption), or None.
  • TREE_ITEM_ADD: Adds subitem as item's child. Param id_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. Gets int handle of subitem.
  • TREE_ITEM_DELETE: Deletes item (with all subitems). Param 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 item.
  • TREE_ITEM_SHOW: Makes item visible, ie scrolls control to this item.
  • TREE_ITEM_GET_SELECTED: Gets int handle of selected item (id_item ignored). Gets None if none selected.
  • TREE_ITEM_GET_PROPS: Gets props of item, as dict. Dict keys are:
    • "text": str: caption 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_ITEM_GET_SYNTAX_RANGE: Only for Code Tree panel's treeview. Gets range, associated with tree-item, as 4-tuple (start_x, start_y, end_x, end_y).
  • TREE_GET_IMAGELIST: Gets int handle of image-list 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_LOCK: Disables repainting of control.
  • TREE_UNLOCK: Enables repainting of control.
  • TREE_THEME: Applies current color theme to control.

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: Gets number if items.
  • LISTBOX_ADD: Adds item (str) with associated tag (int). Param index: at which index to add, -1 to append.
  • LISTBOX_DELETE: Deletes item with given index.
  • LISTBOX_DELETE_ALL: Deletes all items.
  • LISTBOX_GET_ITEM: Gets item with given index as 2-tuple (text, tag). Gets None if index incorrect.
  • LISTBOX_SET_ITEM: Sets item with given index, to given text and tag.
  • LISTBOX_GET_ITEM_H: Gets height of items (pixels).
  • LISTBOX_SET_ITEM_H: Sets height of items. Param index: size in pixels.
  • LISTBOX_GET_SEL: Gets selected index. -1 for none.
  • LISTBOX_SET_SEL: Sets selected index. -1 for none.
  • LISTBOX_GET_TOP: Gets index of top visible item.
  • LISTBOX_SET_TOP: Sets index of top visible item.
  • LISTBOX_GET_DRAWN: Gets bool: listbox is owner-drawn, ie it don't paint itself, but plugin must paint it via event on_draw_item.
  • LISTBOX_SET_DRAWN: Sets owner-drawn state. Param index should be 0 or 1 (off/on).
  • LISTBOX_THEME: Applies current color theme to control.

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 (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.

Possible values of id_action:

  • CANVAS_SET_FONT: Sets props of font. Params:
    • 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:
    • 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:
    • 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: style - ANTIALIAS_NONE, _ON, _OFF.
  • CANVAS_GET_TEXT_SIZE: Gets size of text on canvas, as 2-tuple (size_x, size_y). Uses font. Params: text.
  • CANVAS_TEXT: Paints text at given coords. Uses font and brush. Params: text, x, y.
  • CANVAS_LINE: Paints line at given coords. Uses pen. Params: x, y, x2, y2.
  • CANVAS_PIXEL: Paints one pixel at given coords. Params: x, y, color.
  • CANVAS_RECT: Paints rectangle. Uses pen and brush. Params: x, y, x2, y2.
  • CANVAS_RECT_FRAME: Paints rectangle. Uses only pen. Params: x, y, x2, y2.
  • CANVAS_RECT_FILL: Paints rectangle. Uses only brush. Params: x, y, x2, y2.
  • CANVAS_RECT_ROUND: Paints rounded rectangle. Uses pen and brush. Params: x, y, x2, y2, style - radius of corners.
  • CANVAS_ELLIPSE: Paints ellipse or circle. Uses pen and brush. Params: 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_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.

timer_proc

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

Perform action on timers. Many different timers allowed, they work at the same time, each uniq callback - makes new timer with its own interval. To stop some timer, you must specify same callback as on start.

  • callback: Callback string, see below.
  • interval: Timer delay in msec, 150 or bigger. Specify it only on starting (ignored on stopping).
  • tag: Some string, if not empty, it will be parameter to callback. If it's empty, callback is called without params.

Possible values of id:

  • TIMER_START - Create (if needed) and start timer, infinite ticks. If timer already created, then it's restated.
  • TIMER_START_ONE - Create (if needed) and start timer, for single tick.
  • 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 ok; False if params not ok (callback str incorrect, interval incorrect, not created callback on stopping); or None (for unknown id).

Callbacks

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

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 id

Value of "id_menu" param can be:

  • int_value or str(int_value) - to specify menu item by unique int value
  • "top" - to specify top menu
  • "top-file", "top-edit", "top-sel", "top-sr", "top-view", "top-op", "top-help" - to specify submenus of the main menu: File, Edit, Selection, Search, View, Options, Help
  • "text" - to specify editor context menu
  • "side:"+tab_caption - to specify context menu of sidebar panel (e.g. "side:Tree", "side:Project")
  • "btm:"+tab_caption - to specify context menu of bottom panel
  • "toolmenu:"+name - to specify drop-down sub-menu of toolbar button

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_param.
  • (deprecated callback form) callback in the form "module,method" or "module,method,param" (param can be of any primitive type).
  • to create standatd special sub-menus, special values:
    • "_recents": Recent-files submenu
    • "_enc": Encodings submenu (has subitems "reload as", "convert to")
    • "_langs": Translations submenu
    • "_lexers": Lexers submenu
    • "_plugins": Plugins submenu
    • "_themes-ui": UI-themes submenu
    • "_themes-syntax": Syntax-themes submenu
  • empty string, if item will be used as submenu (item is a submenu, if any subitems are added to it)

Actions

Possible values of id_action:

  • MENU_CLEAR: Removes all sub-items from menu item. Params used: id_menu.
  • MENU_ENUM: Enumerates sub-items in menu item. Params used: id_menu. If id_menu valid, gets list of dict, else gets None. Dict items are: {"id": int_id_menu; "cap": str_caption; "cmd": int_command; "hint": str_command; "hotkey": str_hotkey; "command": int_or_str}.
    • for separator items: "cap" is "-"
    • for usual command items: "cmd" value is >0
    • for plugin command items: "cmd" value is <=0; "hint" is callback string
    • for sub-menu items: "cmd" value is <=0; "hint" value is some string
    • "command": has int value of "cmd" (if >0), or str value of "hint" (otherwise)
  • MENU_GET_PROP: Gets properties of menu item, as dict, in the same format as MENU_ENUM.
  • MENU_ADD: Adds sub-item to menu item. Gets string, menu_id for newly added sub-item. Params used:
    • 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_CREATE: Creates new popup-menu, independant 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 image-list object of menu, which contains menu item. Param "command" must be image-list handle.
  • MENU_SET_IMAGEINDEX: Changes icon index of menu item (index in image-list). Param "index" must be icon index.

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_toolbar, id_action, text="", text2="", command=0, index=-1, index2=-1)

Perform action on some toolbar.

Param id_toolbar: currently can be "top" for main toolbar. Function gets None, if id_toolbar not correct.

Param id_action possible values:

  • TOOLBAR_GET_IMAGELIST: Gets int handle of image-list object.
  • TOOLBAR_SET_BUTTON: Change properties of one button. Gets bool: params ok and changed. Params:
    • index - index of button
    • index2 - new icon index, or -1 for none
    • text - new button caption, or empty str to not change
    • text2 - new button hint, or empty str to not change
  • TOOLBAR_DELETE_ALL: Delete all buttons.
  • TOOLBAR_DELETE_BUTTON: Delete one button. Params: index - button index.
  • TOOLBAR_ADD_BUTTON: Add one button. Params:
    • text - button caption, use "-" for separator
    • text2 - button hint (tooltip)
    • index - button index, >=0 to insert or -1 to append
    • index2 - icon index, or -1 for none
    • command - one of:
      • int_command or str(int_command)
      • callback in one of these forms: #Callback_param
      • "toolmenu:"+str_name - to create button with dropdown menu, this menu can be handled by menu_proc() with menu_id="toolmenu:"+str_name
  • TOOLBAR_ENUM: Enumerates buttons. Gets list of dict, each dict item is: {"cap": str; "hint": str; "cmd": str; "icon": int; "kind": str}. Here "kind" is one of strings: "text", "icon", "text_icon", "text_arrow", "arrow", "sep".
  • TOOLBAR_GET_CHECKED: Gets checked-state of button. Params: index - button index.
  • TOOLBAR_SET_CHECKED: Sets checked-state of button. Params: index - button index, index2 - bool value.
  • TOOLBAR_GET_VERTICAL: Gets vertical state of toolbar.
  • TOOLBAR_SET_VERTICAL: Sets vertical state of toolbar. Params: index - bool value.
  • TOOLBAR_GET_WRAP: Gets wrappable state of toolbar.
  • TOOLBAR_SET_WRAP: Sets wrappable state of toolbar (implemented for horizontal toolbar only). Params: index - bool value.
  • TOOLBAR_THEME: Applies current UI theme to toolbar.

Example

Example adds button to show About dialog:

toolbar_proc('top', TOOLBAR_ADD_BUTTON, text='About', text2='about program...', index2=4, command=2700)

Example adds button with dropdown submenu, which has 2 items:

toolbar_proc('top', TOOLBAR_ADD_BUTTON, text='Dropdown', index2=4, command="toolmenu:drop")
menu_proc('toolmenu:drop', MENU_CLEAR)
menu_proc('toolmenu:drop', MENU_ADD, caption='About...', command=2700)
menu_proc('toolmenu:drop', MENU_ADD, caption='Edit plugin...', command="cuda_addonman,do_edit")

imagelist_proc

imagelist_proc(id_list, id_action, value="")

Perform action on image-list object.

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

Possible values of id_action:

  • IMAGELIST_CREATE: Creates new image-list object with default icon size 16x16. Gets int handle of this image-list. 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: Gets int number of icons in image-list.
  • IMAGELIST_GET_SIZE: Gets current icon size as 2-tuple (width, height).
  • IMAGELIST_SET_SIZE: Sets new icon size, and clears image-list. Param "value" must be 2-tuple of int (width, height). Gets new icon size (corrected by minimal value) as 2-tuple.
  • IMAGELIST_ADD: Loads image into image-list. Param "value" must be full path to png/bmp image file. Image size should be the same as size in image-list (but not required). Gets 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. Gets 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: Gets 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_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_GET_CHECKED: Gets checked state, bool.
  • BTN_SET_CHECKED: Sets checked state. Param "value" must be bool.
  • BTN_GET_IMAGELIST: Gets handle of imagelist, attached to button.
  • BTN_SET_IMAGELIST: Sets handle of imagelist. Param "value" must be int imagelist handle.
  • BTN_GET_IMAGEINDEX: Gets 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_KIND: Gets kind of button. Int value, one of BTNKIND_nnn constants.
  • BTN_SET_KIND: Sets kind of button.
  • BTN_GET_BOLD: Gets bold-style of button, bool.
  • BTN_SET_BOLD: Sets bold-style. Param "value" must be bool.

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. Global objects of Editor exist:

  • ed: refers to currently focused editor (in any tab).
  • ed_bro: refers to "brother" of ed. If tab is splitted, 2 editors are shown: 1st/2nd. 1st and 2nd are "brother" editors.
  • ed_goto: refers to input field in the "Go to" dialog.
  • ed_con_log: refers to log field (multi-line) in the "Console" panel.
  • ed_con_in: refers to input field (single line) in the "Console" panel.

Carets

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.

set_caret

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

Controls carets. Possible values of id:

  • CARET_SET_ONE: Removes multi-carets and sets single caret with given coords (posx, posy, endx, endy).
  • CARET_ADD: Adds caret (multi-carets feature) with given coords. Also gets count of carets after that (same as len(get_carets()) ).
  • CARET_DELETE_ALL: Removes all carets. (Note: you must add caret then to enable text editing to user.)
  • CARET_SET_INDEX + N (any N>=0): Changes single caret with index N to given coords.

Text read/write

get_text_all/set_text_all

get_text_all()
set_text_all(text)

Gets/sets entire text in the editor (str).

Note: get_text_all is simple wrapper around get_text_line/get_line_count, it uses "\n" as line sep.

get_text_line/set_text_line

get_text_line(num)
set_text_line(num, text)

Gets/sets single line (str) with given index (0-base).

Line must be w/o CR LF. Gets None if index incorrect.

To add new line, call set with num=-1.

get_text_substr

get_text_substr(x1, y1, x2, y2)

Gets substring from position (x1, y1) to position (x2, y2). Second position must be bigger than first.

delete

delete(x1, y1, x2, y2)

Deletes range from position (x1, y1) to bigger position (x2, y2).

  • 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 pos=(x1, y1), end=(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)

insert

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). Text can be multi-line, all CR LF are converted to currently used line-ends.

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

replace

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

Replaces range from position (x1, y1) to bigger position (x2, y2), with new text.

  • 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 EOLs in text)
  • for multi-line it also makes grouped-undo for delete+insert

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

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 additonal lines, "\r" not handled.

Gets bool: index y1 correct, replace done.

Selection

get_text_sel

get_text_sel()

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

get_sel_mode

get_sel_mode()

Gets kind of selection: normal or column selection: SEL_NORMAL, SEL_COLUMN.

get_sel_lines

get_sel_lines()

Gets 2-tuple, indexes of 1st and last lines affected by 1st caret selection. Both -1 if no selection.

get_sel_rect/set_sel_rect

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

Gets/sets coords of column selection.

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

Properties

get_line_count

get_line_count()

Gets number of lines.

get_filename

get_filename()

Gets filename (str) of the editor's tab.

  • Empty str for untitled tab.
  • String "?" if picture file loaded in tab.

get_split

get_split()

Gets tab splitting: each tab can be splitted to primary/second editors.

Gets 2-tuple: (state, percent):

  • int: state of splitting, one of the values
    • TAB_SPLIT_NO: tab is not splitted
    • TAB_SPLIT_HORZ: tab is splitted horizontally
    • TAB_SPLIT_VERT: tab is splitted vertically
  • float: percent of splitting, e.g. it's 0.5 if tab splitted 50/50.

set_split

set_split(state, percent)

Sets tab splitting. Meaning of params is the same as for get_split().

get_prop

get_prop(id, value="")

Gets editor's property.

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

  • PROP_GUTTER_NUM: bool: is gutter column for line numbers shown.
  • PROP_GUTTER_FOLD: bool: is gutter column for folding shown.
  • PROP_GUTTER_BM: bool: is gutter column for bookmarks shown.
  • PROP_EOL: str: end-of-line chars. Currently always gets "\n" since it's ignored in "insert" method.
  • 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: horz ruler is shown.
  • PROP_LINE_STATE: int: state of the line with given index. One of LINESTATE_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_BOTTOM: int: index of line visible at the bottom of editor (considers word wrap).
  • PROP_COLUMN_LEFT: int: index of left visible column (horiz scroll pos).
  • PROP_SCROLL_VERT: int: precise vert scroll position. It is index in WrapInfo list, which you can read via get_wrapinfo().
  • PROP_SCROLL_HORZ: int: precise horz scroll position. Same as PROP_COLUMN_LEFT.
  • PROP_COLOR: int: color property. Value must be one of COLOR_ID_nnn values. Gets 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: value must be str(column)+","+str(line), column/line 0-based.
  • 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_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's tab. 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_SHAPE: int: shape of caret, normal mode.
  • PROP_CARET_SHAPE_OVR: int: shape of caret, overwrite mode.
  • PROP_CARET_SHAPE_RO: int: shape of caret, read-only mode.
  • PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
  • 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() gets "?".
  • PROP_MINIMAP: bool: minimap is visible.
  • PROP_MICROMAP: bool: micromap is visible.
  • PROP_LINK_AT_POS: str: URL in the document, at given position. Value must be str(pos_x)+","+str(pos_y).
  • PROP_TAB_SPACES: bool: tab-key inserts spaces (not tab-char).
  • PROP_TAB_SIZE: int: size of tab-char.
  • 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_COLOR: int: color of tab containing editor; 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_ID: int: unique tab's identifier (one number for main/secondary editors in tab), it is not changed when tab is moved.
  • PROP_COORDS: 4-tuple of int: screen coordinates of editor UI control, (left, top, right, bottom).
  • PROP_ONE_LINE: bool: editor has single-line mode. (Usual editors are multi-line, ed_goto is single-line.)

set_prop

set_prop(id, value)

Sets editor's property.

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

  • PROP_GUTTER_NUM: bool: show gutter column "line numbers".
  • PROP_GUTTER_FOLD: bool: show gutter column "folding". This don't enable/disable folding conmands, only showing of area.
  • PROP_GUTTER_BM: bool: show gutter column "bookmarks".
  • 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: space-separated user-margins columns.
  • PROP_INSERT: bool: insert/overwrite mode.
  • PROP_MODIFIED: bool: editor is modified.
  • PROP_RULER: bool: show ruler.
  • 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 top of editor (allows to scroll editor).
  • 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_COLUMN_LEFT: int: index of left visible column (horiz scroll pos).
  • PROP_SCROLL_VERT: int: precise vert scroll position. It is index in WrapInfo list, which you can read via get_wrapinfo().
  • PROP_SCROLL_HORZ: int: precise horz scroll position. Same as PROP_COLUMN_LEFT.
  • PROP_ENC: str: encoding name. Names listed at CudaText#Encodings.
  • 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_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's tab. 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_SHAPE: int: shape of caret, normal mode.
  • PROP_CARET_SHAPE_OVR: int: shape of caret, overwrite mode.
  • PROP_CARET_SHAPE_RO: int: shape of caret, read-only mode.
  • PROP_CARET_VIRTUAL: bool: caret position is allowed after line-ends.
  • 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_MICROMAP: bool: micromap is visible.
  • PROP_TAB_SPACES: bool: tab-key inserts spaces.
  • PROP_TAB_SIZE: int: size of tab-char.
  • 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_TITLE: str: title of tab, useful for untitled tabs.
  • 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_ONE_LINE: bool: editor has single-line mode.

bookmark

bookmark(id, nline, nkind=1, ncolor=-1, text="")

Controls bookmarks. Possible values of id:

  • BOOKMARK_GET: Gets kind of bookmark at line=nline. 0 means no bookmark, 1 means usual bookmark.
  • BOOKMARK_SET: Sets bookmark with kind=nkind at line=nline. 1 means usual bookmark with usual color and icon. Other kind values mean custom bookmark, which must be setup via BOOKMARK_SETUP. Param text: hint, shown when mouse is over bookmark gutter icon.
  • BOOKMARK_CLEAR: Removes bookmark from line=nline (nkind ignored).
  • BOOKMARK_CLEAR_ALL: Removes all bookmarks (nline, nkind ignored).
  • BOOKMARK_SETUP: Setup custom bookmarks with kind=nkind (nline ignored). Setup is:
    • ncolor: Color of bookmarked line. Can be COLOR_NONE to not show bg-color.
    • text: Path to icon file for gutter, 16x16 .bmp or .png file. Empty str: don't show icon.
  • BOOKMARK_GET_LIST: Gets list of line indexes with bookmarks (nline, nkind ignored).
  • BOOKMARK_CLEAR_HINTS: Clears all bookmark hints. Maximum about 250 separate lines can have hints, later hints will not show, so you need to clear hints before adding bunch of bookmarks to editor.

Notes:

  • nkind must be 1..255.
  • nkind values 240..249 have setup by default: they have blue icons "0" to "9".

folding

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

Performs action on folding ranges. Values of id:

  • FOLDING_GET_LIST: Gets list of folding ranges. List of 5-tuples (y, y2, x, staple, folded), or None.
    • y: int: line of range start.
    • y2: int: line of range end. If y==y2, then range is simple and don't have gutter-mark and staple.
    • x: int: x-offset of range start (char index in start line).
    • staple: bool: range has block staple.
    • folded: bool: range is currently folded.
  • FOLDING_FOLD: Folds range with given index (index in list from FOLDING_GET_LIST).
  • FOLDING_UNFOLD: Unfolds range with given 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.
    • item_x: x-offset of range start.
    • item_y: line of range start.
    • item_y2: line of range end.
    • (optional) item_staple: range has block staple.
    • (optional) item_hint: hint string which shows when range is folded.
    • index: if it's valid range index (0-based), range inserts at this index, else range appends.
  • FOLDING_DELETE: Deletes folding range with given index.
  • FOLDING_DELETE_ALL: Deletes all folding ranges.
  • FOLDING_FIND: Gets index of range, which starts at line index =item_y, or None.
  • FOLDING_CHECK_RANGE_INSIDE: For 2 ranges with indexes [index, item_x], detects: 1st range is inside 2nd. Gets bool. Gets False if indexes incorrect.
  • FOLDING_CHECK_RANGES_SAME: For 2 ranges with indexes [index, item_x], detects: ranges are same (x/y/y2 may differ). Gets bool. Gets False if indexes incorrect.

get_sublexer_ranges

get_sublexer_ranges()

Gets list of ranges which belong to nested lexers (sublexers of current lexer for entire file, e.g. "HTML" inside "PHP", or "CSS" inside "HTML"). Gets 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

get_token

get_token(id, index1, index2)

Gets info about one token ("token" is minimal text fragment for syntax parser).

Gets 4-tuple, or None if no such token. Tuple is:

  • (start_x, start_y)
  • (end_x, end_y)
  • string_token_type
  • string_style_name

Possible values of id:

  • TOKEN_AT_POS: Token at position (x=index1, y=index2).
  • TOKEN_INDEX: Token with index=index1 (in tokens collection), 0-based.

get_wrapinfo

get_wrapinfo()

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 list of dict, or None. Dict items has keys:

  • "line": Original line index, for this part.
  • "char": 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": Length of this part. It equals to entire line length, if line is not wrapped.
  • "indent": Screen indent in spaces, for this part, it's used in rendering when option "Show wrapped parts indented" is on.
  • "final": Enum, state of this part. 0: final part of entire line; 1: folded (hidden) part; 2: first or middle part of entire line.

markers

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

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

  • MARKERS_GET: Gets list of markers. Each list item is [x, y, len_x, len_y, tag]. Gets None if no markers.
  • MARKERS_ADD: Adds marker. Also gets number of markers. Params are used here:
    • x, y: Start of marker (like caret pos).
    • Param tag>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).
    • Params len_x, len_y are needed if you want to place selection at marker, when "goto last marker" command goes to this 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.
  • MARKERS_DELETE_ALL: Deletes all markers.
  • MARKERS_DELETE_LAST: Deletes last added marker.

attr

attr(id, tag=0, x=0, y=0, len=0,
     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 )

Controls additional color attributes. Possible values of id:

  • MARKERS_ADD: Adds fragment with specified properties. Also gets number of fragments. Props:
    • tag: any int value attached to fragment (several plugins must add fragments with different tags, to be able to remove only fragments for them)
    • x, y: position of fragment start (like caret).
    • len: length of fragment.
    • color_nnnn: RGB color values for font, background, borders. E.g. 0x0000FF is red, 0x00FF00 is green.
    • font_nnnn: font attributes: 0 - off, 1 - on.
    • border_nnnn: border types for edges, values from 0: none, solid, dash, solid 2pixel, dotted, rounded, wave.
  • MARKERS_GET: Gets list of fragments, each item is list, int fields, same as function params.
  • MARKERS_DELETE_ALL: Deletes all fragments.
  • MARKERS_DELETE_LAST: Deletes last added fragment.
  • MARKERS_DELETE_BY_TAG: Deletes all fragments for specified tag value.

Note:

  • color_bg value can be COLOR_NONE: it uses usual back-color.
  • color_font, color_border value can be COLOR_NONE: it uses usual text-color.

Misc

save

save(filename="")

Saves editor's tab to disk.

Shows save-as dialog for untitled tab. If param filename not empty, uses it (untitled tab becomes titled). Gets bool: file was saved.

cmd

cmd(code, text="")

Command runner, it runs any command in editor by its int code.

See codes in module cudatext_cmd. Param text is needed for rare commands (e.g. by cCommand_TextInsert).

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().

lock/unlock

lock()
unlock()

These lock, then unlock editor. Locked editor is not painted and shows text label "Wait...".

convert

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

Converts coordinates in editor. Possible values of id:

  • CONVERT_CHAR_TO_COL: Convert char-coordinates (x,y) to column-coordinates 2-tuple (column,y).
  • CONVERT_COL_TO_CHAR: Convert column-coordinates (x,y) to char-coordinates 2-tuple (chars,y).
  • CONVERT_LINE_TABS_TO_SPACES: Convert line (parameter text) from tab-chars to spaces (line not changed if no tab-chars in it), gets str.

Gets None if coordinates incorrect (e.g. x<0).

complete

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

Shows auto-completion listbox with given items.

Function gets 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).

complete_alt

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

Shows alternative completion listbox. This listbox allows to insert complex snippets, not only simple words. E.g. snippet text like "myobj.myfunc(${1:value1}, ${2:value2});".

Function gets None and listbox stays open. When user chooses listbox item, event on_snippet is called, with params:

  • Param "snippet_id": value from complete_alt() call; on_snippet should handle only known value of snippet_id.
  • Param "snippet_text": text of selected item (last column).

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": any short string just to identify snippet kind between all plugins. E.g. plugin1/plugin2 may have snippets in different formats, they must handle only their snippets.
  • Param "len_chars": listbox shows lefter than caret, by this count of chars.
  • Param "selected": index of initially selected listbox item (0-based).

gap

gap(id, num1, num2, tag=-1)

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

  • GAP_GET_LIST: Gets list of gaps. List of 4-tuples (nline, ntag, bitmap_size_x, bitmap_size_y), or None.
  • GAP_MAKE_BITMAP: Makes new bitmap for future gap. Size of bitmap is num1 x num2. Gets 2-tuple (id_bitmap, id_canvas).
    • id_bitmap is needed to later call GAP_ADD.
    • id_canvas is needed to paint an image on bitmap, by canvas_proc().
  • GAP_ADD: Adds gap to editor, with ready bitmap. Gets bool: params correct, gap added. Params:
    • num1 - line index
    • num2 - id_bitmap you got before
    • tag - int value (signed 64 bit) to separate gaps from several plugins.
  • GAP_DELETE: Deletes gaps, for line indexes from num1 to num2.
  • GAP_DELETE_ALL: Deletes all gaps.

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)

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) or None.

lexer_scan

lexer_scan(nline)

Runs lexer analysis (if lexer active) from given line index. Waits until analysis finishes.

Use case: plugin appends n lines to text (line by line), then lexer needs to rescan text from 1st added line, else folding won't appear for these lines.

export_html

export_html(file_name, title, font_name, font_size, with_nums, color_bg, color_nums)

Makes HTML file from source text with syntax highlighting. Gets bool: file is created. Params:

  • file_name: str: Path of file.
  • title: str: HTML page title.
  • font_name: str: Font name.
  • int: Font size, in HTML points.
  • with_nums: bool: Make column with line numbers.
  • color_bg: int: RGB color of page background.
  • color_nums: int: RGB color of line numbers.

more

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.

Format of text for cmd_FinderAction

Text is chr(1) separated items:

  • item 0: find-action, one of:
    • 'findfirst'- find first
    • 'findnext'- find next
    • 'findprev'- find prev
    • 'rep'- replace next, find
    • 'repstop'- replace next, 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: several chars, each char is find-option:
    • 'c' for case-sens
    • 'r' for regex
    • 'w' for whole-words
    • 'f' for from-caret
    • 'o' for confirm-replaces
    • 'a' for wrapped-search
    • 's' for search in selection

History

1.0.208 (app 1.27.2)

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

1.0.208 (app 1.26.2)

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

1.0.207 (app 1.25.1)

  • add: app_proc: PROC_GET_COMMANDS

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.205 (app 1.24.1)

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

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.203 (app 1.23.4)

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

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.201 (app 1.21.0)

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

1.0.200 (app 1.20.2)

  • add: event on_insert

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.198 (app 1.18.0)

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

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.196 (app 1.16.2)

  • add: ed.dim()

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.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.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.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.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.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.189 (app 1.13.1)

  • add: tree_proc: TREE_ITEM_SHOW

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.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 gets "data" param with 2-tuple

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.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.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.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.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.181

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

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.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.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.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.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.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.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.173

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

1.0.172

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

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.170

  • add: app_proc: PROC_SET_CLIP_ALT

1.0.169

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

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.167

  • add: timer_proc.

1.0.166

  • chg: dlg_custom: "image" uses "items=" now

1.0.165

  • add: find/replace in selection, flag in cmd_FinderAction
  • add: msg_status_alt: allowed seconds<=0
  • add: dlg_custom: type "edit_pwd" (password input)
  • add: dlg_custom: type "image"

1.0.164

  • change: ed.gap: tag is 64-bit signed (was 32-bit)

1.0.163

  • change: app_proc toolbar api: _add allows to set caption; _enum gets also captions

1.0.162

  • add: ed.gap (Gaps api)
  • add: ed.folding (Folding api)
  • add: ed.lexer_scan
  • add: canvas_proc
  • add: on_click_gap
  • delete: ed.get_ranges (use ed.folding)

1.0.161

  • add: dlg_custom: colorpanel has new "props" value, color_border

1.0.160

  • add: can add to side/bottom panel UI-control "listbox"
  • add: listbox_proc func
  • add: menu api prefix "btm:"

1.0.159

  • add: app_proc: PROC_GET_GUI_HEIGHT

1.0.158

  • add: events priority (e.g. "on_key++")
  • add: app_proc: PROC_BOTTOMPANEL_ADD, PROC_BOTTOMPANEL_REMOVE, PROC_BOTTOMPANEL_ACTIVATE, PROC_BOTTOMPANEL_ENUM

1.0.157

  • add: lexer_proc: LEXER_DETECT

1.0.156

  • add: ed.complete: added param alt_order
  • add: app_proc: PROC_HOTKEY_INT_TO_STR, PROC_HOTKEY_STR_TO_INT
  • add: dlg_custom: "type=colorpanel"
  • add: dlg_custom: result has additional line "focused=N"
  • add: file_open can install addons, where files are not in root, but in subdir
  • add: install.inf: can write lexers list in [info] $var=Name1,Name2,Name3 ; use it like "lexers=$var"
  • add: install.inf: can write lexers list with regex, e.g. [info] $var=regex:.*SQL.*

1.0.155

  • add: lexer_proc:
    • LEXER_GET_COMMENT_STREAM
    • LEXER_GET_COMMENT_LINED
    • LEXER_GET_STYLES_COMMENTS
    • LEXER_GET_STYLES_STRINGS
  • add: app_proc:
    • PROC_GET_COMMAND_INITIAL
    • PROC_SHOW_STATUSBAR_GET, PROC_SHOW_STATUSBAR_SET
    • PROC_SHOW_TOOLBAR_GET, PROC_SHOW_TOOLBAR_SET
    • PROC_SHOW_SIDEPANEL_GET, PROC_SHOW_SIDEPANEL_SET
    • PROC_SHOW_BOTTOMPANEL_GET, PROC_SHOW_BOTTOMPANEL_SET
    • PROC_SHOW_TABS_GET, PROC_SHOW_TABS_SET
    • PROC_COORD_WINDOW_GET, PROC_COORD_WINDOW_SET
    • PROC_COORD_DESKTOP
    • PROC_COORD_MONITOR*
  • add: app_path: APP_FILE_RECENTS
  • delete: lexer_proc: LEXER_GET_MODIFIED

1.0.154

  • add: app_proc: PROC_THEME_UI_*, PROC_THEME_SYNTAX_*
  • add: ed.get_prop/set_prop: PROP_CARET_VIRTUAL

1.0.153

  • add: app_path: APP_DIR_INSTALLED_ADDON

1.0.152

  • add: ed.get_prop/set_prop: PROP_COLUMN_LEFT

1.0.151

  • add: on_state called with EDSTATE_MODIFIED (when ed modifies)

1.0.150

  • add: ed.markers(MARKERS_ADD, ...) has param len_y
  • change: ed.markers(MARKERS_GET, ...) gets items with value len_y

1.0.149

  • add: on_open_pre

1.0.148

  • add: app_proc: PROC_SIDEPANEL_REMOVE
  • add: dlg_hotkeys: added param "lexer"

1.0.147

  • add: ed.get_sublexer_ranges()

1.0.146

  • add: dlg_custom: "type=tabs"

1.0.145

  • add: dlg_custom: "check" has 3rd value "?"

1.0.144

  • add: ed.complete, ed.complete_alt: added param "selected"
  • add: app_proc: PROC_GET_FIND_STRINGS

1.0.143

  • add: ed.convert: CONVERT_LINE_TABS_TO_SPACES
  • add: app_proc: PROC_GET_KEYSTATE
  • chg: app_proc(PROC_GET_COMMAND..) dont give plugin/lexer items

1.0.142

  • add: on_key_up

1.0.141

  • add: dlg_hotkey: title

1.0.140

  • add: ed.get_prop: PROP_TAB_ID
  • add: ed.get_prop/set_prop: PROP_TAG extended, it has values for keys
  • add: dlg_custom: prop "act=1"
  • add: app_idle()
  • add: tree_proc: TREE_ITEM_GET_SYNTAX_RANGE

1.0.139

  • add: on_state
  • add: ed_group()
  • change: msg_status default process_messages=False

1.0.138

  • add: on_snippet
  • add: ed.complete_alt (uses on_snippet)
  • add: msg_status has param process_messages
  • add: ed.set_prop: PROP_TAB_TITLE writable

1.0.137

  • change: cudatext_colors.py deleted, moved to cudatext.py
  • add: ed.attr: color_font, color_border can be COLOR_NONE

1.0.136

  • add: dlg_hotkey
  • add: dlg_custom: listview props=
  • add: app_proc: PROC_GET_HOTKEY, PROC_SET_HOTKEY
  • add: app_log: LOG_CONSOLE_GET_LOG

1.0.135

  • add: ed.get_prop: PROP_MODIFIED_VERSION

1.0.134

  • add: app_proc: menu_id can be with "_": "_recents/_themes/_langs/_plugins"
  • add: app_proc: menu_id "lexers/_lexers"
  • add: app_proc: menu_id "enc/_enc"

1.0.133

  • lexer-lib file not used, used .lcf files
  • delete: LEXER_SAVE_LIB, LEXER_EXPORT

1.0.132

  • change: app_proc:
    • result of PROC_MENU_ENUM has item_id
    • result of PROC_TOOLBAR_ENUM has string_id for std buttons
  • add: can load .png icons (was: only .bmp)
  • add: app_proc: PROC_TOOLBAR_ICON_GET_SIZE, PROC_TOOLBAR_ICON_SET_SIZE

1.0.131

  • add: app_proc: PROC_GET_LANG
  • add: app_proc: PROC_MENU_ENUM gives also hints for menu "top"

1.0.130

  • add: dlg_dir
  • add: dlg_custom: type=checkbutton

1.0.129

  • add: ed.set_prop: can use PROP_MODIFIED

1.0.128

  • add: ed.get_prop: PROP_LINK_AT_POS

1.0.127

  • add: on_tab_move
  • add: on_panel: id_event="on_menu"
  • add: tree_proc: TREE_LOCK, TREE_UNLOCK
  • add: ed.bookmark: BOOKMARK_SET specifies hint
  • add: ed.bookmark: BOOKMARK_CLEAR_HINTS

1.0.126

  • change: deleted get_top/set_top/get_enc/set_enc/get_tabcolor/set_tabcolor; instead use get_prop/set_prop: PROP_LINE_TOP, PROP_ENC, PROP_TAB_COLOR
  • add: get_prop: PROP_TAB_TITLE

1.0.125

  • add: app_proc: PROC_TOOLBAR_nnnnn
  • add: app_proc: PROC_BOTTOMPANEL_GET_CONTROL

1.0.124

  • add: get_prop/set_prop: PROP_MINIMAP, PROP_MICROMAP

1.0.123

  • add: ed.get_filename() can be "?" for picture
  • add: ed.get_prop PROP_PICTURE

1.0.122

  • add: ed.get_prop PROP_VISIBLE_LINES, PROP_VISIBLE_COLUMNS
  • add: ed.get_prop PROP_LINE_BOTTOM

1.0.121

  • add: app_proc: PROC_SIDEPANEL_*
  • add: tree_proc
  • add: on_panel
  • add: on_close
  • add: on_click_dbl
  • add: Editor.get_token
  • add: optional param in file_save, ed.save

1.0.120

  • add: dlg_custom: type=linklabel, hint=
  • add: app_log: LOG_CONSOLE_CLEAR can have text "m","e","h"

1.0.119

  • add: msg_status_alt
  • add: on_func_hint
  • add: app_proc: PROC_GET/SET_FIND_OPTIONS
  • change: app_log: LOG_GET_LINES result

1.0.118

  • add: on_click
  • add: on_lexer
  • add: ed.set_prop/get_prop PROP_COLOR
  • add: ed.set_prop/get_prop PROP_MARKED_RANGE
  • add: ed.set_prop/get_prop PROP_CARET_SHAPE*
  • delete: dlg_checklist

1.0.117

  • add: app_log: LOG_PANEL_ADD, LOG_PANEL_DELETE, LOG_PANEL_FOCUS
  • add: app_log: LOG_GET_LINES, LOG_GET_LINEINDEX, LOG_SET_LINEINDEX
  • add: ed.set_prop: PROP_EXPORT_HTML
  • add: app_proc: PROC_SET_SPLIT, PROC_GET_SPLIT

1.0.116

  • add: on_output_nav
  • add: app_log: param tag for LOG_ADD
  • add: app_proc: PROC_GET_COMMAND_PLUGIN

1.0.115

  • add: dlg_custom: props for "edit"; align-chars for "listview"
  • add: app_proc: PROC_GET_ESCAPE PROC_SET_ESCAPE

1.0.114

  • change: attr() has param "tag"
  • add: dlg_custom: some props, added "listview", "checklistview"

1.0.113

  • add: dlg_custom
  • add: dlg_menu(.., focused)
  • add: set_prop PROP_INDEX_GROUP, PROP_INDEX_TAB
  • add: result for ed.save(), file_save()

1.0.112

  • add: Editor.attr()
  • add: app_proc PROC_SET_SUBCOMMANDS
  • add: app_proc PROC_EXEC_PLUGIN
  • add: get_prop PROP_MACRO_REC
  • add: dlg_hotkeys()

1.0.111

  • add: Editor.markers()
  • add: Editor.save()
  • add: get/set_prop PROP_TAB_COLLECT_MARKERS
  • add: get/set_prop PROP_TAG
  • add: app_proc PROC_GET_LAST_PLUGIN
  • add: app_proc PROC_GET_GROUPING, PROC_SET_GROUPING
  • add: app_proc PROC_EXEC_PYTHON