Difference between revisions of "CudaText"

From Free Pascal wiki
Jump to navigationJump to search
Line 257: Line 257:
 
== File-types config ==
 
== File-types config ==
  
Menu item "Options / Settings - more / Settings - file-types" allows to edit file-types config. It specifies mapping from "file name" to "lexer name".
+
Menu item "Options / Settings - more / Settings - file types" allows to edit file-types config. It specifies mapping from "file name" to "lexer name".
 
Example of file:
 
Example of file:
  

Revision as of 14:41, 18 January 2018

About

CudaText is a cross-platform text editor, written in Lazarus.

  • Syntax highlight for many languages: C, C++, Java, JavaScript, HTML, CSS, PHP, Python, Pascal, XML; more than 160 lexers exist
  • Code folding
  • Code tree structure
  • Multi-carets
  • Multi-selections
  • Search/replace with regex
  • Supports many encodings
  • Simple auto-completion (fixed list) for some lexers
  • Extendable via Python plugins
  • Command palette (Sublime style)
  • Configs in JSON
  • Made on ATSynEdit engine

Features for HTML/CSS coding:

  • Smart auto-completion for HTML, CSS.
  • HTML tags completion with Tab-key (Snippets plugin).
  • HTML color codes underline.
  • View pictures (jpeg/png/bmp/ico).

Screenshot:

cudatext.png

Download

Versions for Windows, macOS, Linux, Linux-ARM (for Raspberry Pi 3).

Configs

Editor has config system in JSON files: call menu item "Settings-default" and you'll see default config - it's only example. Copy any lines to config called by "Settings-user" and edit lines in this user config - it's actial config file. You can copy comments near options too, they will be ignored. Default config is not read by program, it's only to show possible options.

Lexer-specific config: settings which are read when some lexer activates. E.g., if you open Pascal file, config for Pascal is read after user config. You should not write "ui_" options to lexer-override config (it will give some weird effects on changing lexers), and few others, like option "lexlib" (it is read only once).

File-types config: specify in it mapping between file names (name or extension) and lexer names. Such mapping exists in lexer-library, this config overrides it.

Themes: UI themes and syntax themes. They specify interface colors in app (UI themes) and colors of text/syntax elements in the editor (syntax themes). You can change preinstalled themes, and create new themes, e.g. based on preinstalled.

Keys config. Special dialog allows to change all hotkeys in app. You should not edit config file here. Dialog is called from "Help--Commands" list by key F9. Dialog allows to set hotkey-1 and hotkey-2 for any command (except dynamically added commands to change lexer).

Help topics

Command line parameters

Usage:

  • cudatext [ key ... ] filename ...

Supported keys:

  • -h, --help - Show command-line help
  • -v, --version - Show application version
  • -n, --new - Ignore option "ui_one_instance", and force new app window
  • -r, --readonly - Open all files from command line in read-only mode
  • -e, --enc=value - Open all files from command line in given encoding
  • -el, --enclist - Show possible encoding names
  • -w, --window=left,top,width,height - Set position/size of app window, 4 numbers specified, any can be missed to keep previous value

Notes:

  • Filenames can be with ":line" or ":line:column" suffix to place caret.
  • Folders can be specified too. They will be opened as a "project" in the Project Manager.
  • Project files (.cuda-proj) can be loaded.
  • Session files (.cuda-session) can be loaded, if Session Manager installed.
  • Non-existing file name can be specified, program will ask to create it.

macOS

On macOS you cannot run "cudatext", but you can open Terminal and create the alias for "cudatext":

alias cudatext=open\ /Applications/CudaText.app\ --args

This allows to open in Terminal commands like "cudatext ~/filename.html".

Mouse shortcuts

Multi-carets:

  • Ctrl+click - add/remove caret.
  • Ctrl+drag - add caret with selection.
  • Ctrl+Shift+click - add carets column in several lines (from previous caret to clicked line).

Select:

  • Alt+drag - select column of text. (Note: it may look weird if word-wrap on, because wrap is not considered here at all. Simple rectangle of coordinates [x1,y1]-[x2,y2] is always selected, even if this gives bad looking screen.)
  • drag on gutter's line numbers - select by entire lines.
  • double-click and immediately drag - select text by words.

Clicks:

  • double-click - select clicked word (see option word_chars).
  • triple-click - select entire line (limited by end-of-lines).
  • middle-button click (with option mouse_mid_click_scroll) - start "Browser Scroll" mode: circle mark appears and mouse moving around this mark auto-scrolls text in 4 directions; speed of scrolling depends on distance of cursor from circle mark (any click to turn off).
  • middle-button click (with option mouse_mid_click_paste) - paste from clipboard. This is like in Linux. Additionally it's good to install plugin "Auto-Copy to Clipboard".

Misc:

  • Alt+click (with option mouse_goto_definition) - call "Goto definition" command (if plugin installed).
  • Shift+ scroll mouse wheel - scroll text horizontally.
  • Ctrl+ scroll mouse wheel (with option mouse_wheel_zoom) - zoom text in/out.

Multi-carets

Multi-carets are several carets at once. All carets work together for many editing commands: caret moving, text typing, deleting, selection with keyboard. See "Mouse shortcuts", how to add/remove carets.

Animation:

atsynedit-carets.gif

Multi-selections

If you add caret with Ctrl+click, caret has no selection. If you add caret with Ctrl+drag, caret will have selection. You can add selections to carets later, by Shift+arrows, Shift+Home, Shift+End etc.

Multi-selections are handled specially on copy/paste. If you copy selections, then move carets, then paste, paste will insert clipboard lines into carets: line-1 at caret-1, line-2 at caret-2 etc (only if carets count equals to lines count in clipboard, otherwise result is different).

Animation shows this:

atsynedit-sel.gif

Clipboard commands with selections

Clipboard-related commands work with carets, both with selections and without them. Some details about this:

Command Behaviour, when there're no selections Behaviour, when at last one selection present
Copy to clipboard Copies entire lines, containing carets. (Ignores multiple carets on same line.) Copies only selections text. (Ignores carets without selections.)
Cut to clipboard Similarly to "Copy" w/o selections. Similarly to "Copy" with selections.
Paste from clipboard First, selections are cleared (deleted). Then, command pastes text into each caret position. Special case is when clipboard lines count equals to carets count - in this case, first line is inserted at first caret, second line is inserted at 2nd caret, etc.
Delete char Deletes one char at each caret position. Deletes only selections text. (Ignores carets without selections.)

Lexers

Lexers (syntax highlighters) from SynWrite editor are used. Used EControl.ru syntax parser with mods. Main mod is support for folding in Python (and other lexers with indent-based folding).

  • Dialog "Lexer properties" allows to config props of current lexer (selected via statusbar panel in CudaText). You can config: lexer name, file types, commenting for language, colors of tokens, font-styles (bold/italic/underline), borders around tokens.
  • Dialog "Lexer library" shows list of installed lexers. Dialog shows lexers which are in the folder "data/lexlib".

cudatext-lexer-library.png

Dialog "Lexer library" has hotkeys:

  • Enter: same as "Configure" button
  • Delete: same as "Delete" button
  • Space: same as "Hide/Show" button
  • Esc: close dialog

Lexers at sf.net

Lexer library file has only subset of lexers. Other lexers, from SynWrite, are here: http://sourceforge.net/projects/synwrite-addons/files/Lexers/

These zip packages can be installed in CudaText: open any zip file via "File--Open" and confirm installation.

Lexers editing

You can modify/create lexers. But not in CudaText. Install SynWrite (needed Wine on Linux) and in it you have lexer editor dialog.

  • In Synwrite call menu "Options--Addons manager--Install", install needed lexer from web. Synwrite lexer-library must have lexer before you edit it.
  • In Synwrite call "Lexer prop" dialog and edit all you need. Or make new lexer.
  • In Synwrite install "ExLexer" addon. Call it in "Plugins" menu, select needed lexer. You have exported zip file.
  • In CudaText open this zip file. Confirm installation of lexer.

Screenshot of SynWrite dialog:

synwrite-lexer-editor.png

Why Comments-plugin dont comment blocks in lexer?

Plugin "Comments" can comment

  • line comments (to end of line): comment-chars are configured inside lexer .lcf file, no need to change usually
  • stream comments (from offset to offset): some lexers are configured with stream-comment-chars, and some are not.

To configure stream-comment-chars, open CudaText dialog "Lexer properties" for lexer, and dialog tab "Commenting" shows inputs for these chars.

  • Comment to line-end (usually this is configured)
  • Comment range (often not configured)
  • Comment range, for full lines (this is very rarely supported by lexers)

Stream-comment-chars are saved to separate file, lexername.cuda-lexmap. If plugin cannot comment, your lexer misses this file, or file misses the option. Check that file is absent in folder "data/lexlib". If it's absent, create file via "Lexer properties" dialog. To share file, put it to lexer's ZIP file. You can make ZIP file from SynWrite, from plugin "ExLexer", then add to it .cuda-lexmap file. CudaText and SynWrite both install this .cuda-lexmap file on installing lexer's zip file.

How to setup styles of hidden sublexer?

Some lexers are distributed in packages together with sub-lexer, and sub-lexer is hidden. Example: "HTML Django" with sub-lexer "HTML Django internal" (the 2nd isn't visible in the Lexers menu, so it's called hidden). Users, which have option "ui_lexer_themes" off, want to configure styles of all lexers. How to access hidden ones?

  • Open "Lexer library" dialog (Options - Lexer - Lexer library).
  • In dialog you see all lexers, focus needed lexer, press "Config"
  • Dialog "Lexer properties" will open for selected lexer
  • In dialog's "Styles" tab, configure all you need

You can make lexer hidden/visible, by toggling its check-box in the "Lexer library" dialog.

I have made new lexer - how to distribute it?

In SynWrite, you've created .lcf file in folder SynWrite/Data/LexLib. If you configured "Commenting" options, also file .cuda-lexmap is created. Now you need to create .zip installation of lexer, for both editors: SynWrite, CudaText.

  • In lexer file, replace system colors to usual colors: replace "clWindowText" to "clBlack" (clWindowText may be light on CudaText on Linux); replace "clInfoText" and "clInfoBk" too.
  • In SynWrite, in Addon Manager, install plugin "ExLexer".
  • In SynWrite, run menu item "Plugins - ExLexer", to create .zip for your lexer.
  • In CudaText, open this new zip file, this installs lexer to CudaText.
  • In CudaText, activate your lexer, dialog should show: "Lexer style mapping". Fill items in this dialog.
  • In CudaText, test this "lexer style map" in action: open file with your lexer active, and activate "default" UI theme, then activate "sub" UI theme. Main themes must show nice colors in your syntax file. Call dialog "Options - Lexers - Lexer style mapping" to fix colors.
  • In prev step, you configured .cuda-lexmap file, in folder CudaText/data/lexlib. Copy this file to zip installation of your lexer.
  • Zip must contain: install.inf, .lcf file(s), .cuda-lexmap file per each lexer.

Lite lexers

Lite lexers are lexers is special format (internally it's JSON file), with very limited features. They don't support code-tree, folding, don't support multi-line comments, don't have rich highlighting (e.g. background hilite of string `12+$var` with additional hilite for 12 and $var inside). And they don't keep tokens information in memory (positions of found tokens in text). But they work very fast for any file size (with average line length). Lite lexers have " ^" suffix in name. Currently few lite lexers are made: XML ^, JSON ^, Log files ^, SQL ^. You can also choose them, from the usual lexers menu (they are visible by suffix).

Lite lexers are auto used for big files, if file size is bigger than option "ui_max_size_lexer". And for small files, if normal lexer not found.

Add-on types

  • "plugins". These are addons with Python code. They add python events and/or python commands. Commands can be called then via "Plugins" top menu, but only if plugin's install.inf file doesn't hide menuitems in "Plugins". For example, install.inf in CudaExt hides all menuitems in "Plugins". In all cases, all commands can be called via Commands (F1) dialog.
  • "lexers". These are syntax hiliting support. For ex, Arduino lexer adds menuitem "Arduino" to the lexer menu. Some addons can add 2 lexers (or more), for ex "HTML nnnnnn" addons often add 2 lexers: one is visible in the lexer menu, another one is hidden (it supports embedded blocks hiliting).
  • "linters". These are Python modules for CudaLint plugin. Each supports some lexer (or several similar lexers). To use them, install CudaLint plugin, open your work file, and call CudaLint commands: it calls appropriate linter and shows colored bookmarks on error/warning lines.
  • "snippets". These are collections of text fragments, for Snippets plugin. Install Snippets plugin first. Each addon supports some lexer(s). See details in the #Snippets topic.
  • "translations". These are CudaText UI translations. For ex, JP translation changes all menuitems + dialogs to JP language. Dialogs of plugins are not affected (but authors can support translation in their plugins).
  • "themes". These are UI/syntax themes for the "Options - Color themes" menu. UI themes change colors of CudaText interface. Syntax themes change colors of words in syntax hilited files.
  • "sidebar themes": These are icon sets for the sidebar (vertical bar on the left side).
  • "file type icons": These are icon sets for the "Project Manager" file list. Most popular lexers have icons here.

File-types config

Menu item "Options / Settings - more / Settings - file types" allows to edit file-types config. It specifies mapping from "file name" to "lexer name". Example of file:

{
  "*.mht": "HTML",
  "myconfig.conf": "Nginx",
  ".profile": "Bash script",
}

This allows to open file mask (name of JSON key) with custom lexer (value of JSON key). File mask can have symbols "*", "?". Value "-" means "don't activate lexer".

Another method to specify this mapping is dialog "Lexer properties", in which you can add extension or name+extension to a lexer. But dialog is more limited:

  • It saves option to the lexer file (data/lexlib/lexername.lcf), so setting will be reset on reinstalling lexer.
  • It can specify file extension, or name+extension, but cannot set complex file mask with "*".

Encodings

You can change encoding of file using click on statusbar item. Menu will give list of encodings. Also menu gives 2 choices:

  • reload file in given encoding from disk
  • change encoding in memory only (this doesn't save file)

If you change enc for untitled tab, then enc is changed only in-memory (next file save will use this encoding). If you change enc for named tab, then additional confirmation shows: "Do you also want to reload file?". Choose Ok to reload file from disk; choose Cancel to change encoding in memory.

Encoding names for command-line:

  • ansi
  • utf8
  • utf8_bom
  • utf16le
  • utf16le_bom
  • utf16be
  • utf16be_bom
  • cp1250
  • cp1251
  • cp1252
  • cp1253
  • cp1254
  • cp1255
  • cp1256
  • cp1257
  • cp1258
  • cp437
  • cp850
  • cp852
  • cp866
  • cp874
  • cp932
  • cp936
  • cp949
  • cp950
  • iso-8859-1
  • iso-8859-2
  • mac

Line ends

Main types of line-ends are supported:

  • CR LF (Windows)
  • LF (Unix)
  • CR (Mac OS 9)

To change line-ends for current file, click statusbar item. You need to save file then. Changed line-ends can be undone via "Undo".

Mixed line-ends in one file are supported. To see ends for all lines, set to "true" these options:

  • unprinted_show
  • unprinted_ends
  • unprinted_end_details

Groups of tabs

Groups are tab sets, each tab with an editor control. By default only the first group is shown. Totally 6 groups can be shown at once, see menu "View--Groups", which allows to choose the grouping mode:

  • one group
  • 2 groups: vertically or horizontally
  • 3 groups: vertically, horizontally or 1+2
  • 4 groups: vertically, horizontally or grid
  • 6 groups: grid

First group cannot be empty, at last one tab exists in it. Other groups can be empty: on closing last tab, if it's active, the first group activates.

  • You can drag-drop tabs from any group to any other visible group (drop only on tabs area).
  • You can move tabs to other groups (by group number or to the next/previous), using commands in tab headers context menu.
  • In grouping modes "2 groups" and "1+2" there's a context menu for splitter, to choose splitting 50/50, 40/60 etc.

Auto-completion

Command Ctrl+Space shows auto-completion listbox for file, if app has autocompletion file for current lexer. Such files exist for many lexers: they are in dir "data/autocomplete", and additional lexers may have such files.

Example for PHP lexer:

cudatext-php-complete.png

Lexer HTML is handled specially, its completion listbox has 3 modes:

  • caret is on tag (opening/closing): list of tags is shown
  • caret is after tag on attribute place, before "=": list if attributes for found tag is shown
  • caret is after tag, after attribute, after "=": list of values for found attribute is shown

cudatext-html-complete.png

Lexer CSS is handled specially too, its listbox has 2 modes:

  • caret is on property name: list of properties is shown
  • caret is after property name and ":": list of values is shown

cudatext-css-complete.png

Syntax tree

To show syntax tree, activate side-panel (default hotkey: F12). Many lexers support this tree: most C-based, HTML, XML, CSS, JS etc. This tree is configured inside each lexer properties (see how to edit lexers). Example of tree for Pascal:

atsynedit tree.png

  • Double-click on a tree node moves caret to its text.
  • Tree is filled after few seconds after file opening (search for options ui_tree* to change this pause).
  • When you move caret, tree shows tree node for caret position, after a pause (search for options ui_tree* to change this).

Console panel

Panel is called by key Ctrl+tilde (Ctrl+`). It has read-only memo with output and edit field. You can type Python commands in the edit field, they will run and show output in the memo. E.g. enter "print(10+12)" and you'll see output "22". Can enter complex commands: e.g. "for i in range(10): print(i)".

cudatext con.png

  • If you enter command beginning with "=", then it's the same as you enterted "print()". E.g. command "=10+12" will give "22".
  • If you end command with ";", it won't add to dropdown history.
  • Double-click on memo lines starting with ">>>" repeats entered command (which is after ">>>").

Can enter commands from CudaText API. Example clears all bookmarks and sets bookmark on line 11 (these are several commands, run one by one):

ed.bookmark(BOOKMARK_CLEAR_ALL, 0)
ed.bookmark(BOOKMARK_SET, 10)

How to use Console as calculator

Call Console panel with Ctrl+` (Ctrl+tilde). In its input field, enter valid Python expressions with leading "=" char. To use "sin", "cos", "pi" etc, first enter command "from math import *".

Example of 3 entered lines and their log in console:

 >>> from math import *
 >>> =pi
 3.141592653589793
 >>> =100/5+2
 22.0

Search in Commands dialog

Commands dialog (and menu dialog in Python API) has filter field. Filter has fuzzy search, if option (search for "fuzzy") is on. Fuzzy means that filter leaves only those listbox items, which contain all filter chars in ascending order. Example of fuzzy matches:

  • "fop" matches "file: open file"
  • "gttb" matches "goto text begin"

If option is off, filter has normal search. Normal means that filter leaves only those listbox items, which contain all words from the filter (in any order).

Filter field can find hotkeys too. Enter only hotkey substring, with first "@" char. E.g. "@ho" finds "Ctrl+Home". This search is not fuzzy.

cudatext cmd dlg.png

Regular expressions

Lexer engine uses regex from EControl package. Groups must be referenced as \0 .. \9. It has custom features:

  • classes \A, \Z: begin/end of file
  • look ahead/behind can find variable length
  • doesn't support non-capturing groups, big drawback when you want to do complex replacements
  • new modifiers (?r), (?g)

Search/replace uses TRegExpr engine (by Sorokin), almost fully Perl compatible, syntax is documented here: http://regexpstudio.com/TRegExpr/Help/regexp_syntax.html . Groups must be referenced as $0 .. $9. Engine is more reliable, fast.

Change case on replaces

With regex, you can change case of found fragments, use modifiers in replace-with field:

  • \l - First char to lower
  • \L - All chars to lower
  • \u - First char to upper
  • \U - All chars to upper

E.g. if found a word, use replace-with field "\L$0" to change word to lowercase (here $0 is group 0, found text).

Modifiers affect only element after them, element is:

  • one char (not string), so "\Uabc" and "\uabc" give same result "Abc" (only one char changed),
  • or group $0 ... $9, so modifier changes case of this group (not only one char).

How to restore lexers styles/colors after reinstalling app?

When you customize lexers styles/colors (in the Lexer Properties dialog) and press OK in dialog, your styles/colors are saved to the lexer file (in "data/lexlib") and also to file "settings/lexer styles backup.ini". If you reinstall app, you overwrite standard lexers. But you don't overwrite "lexer styles backup.ini" - you can restore your styles from this file. To do it, call Commands dialog, search for command "restore lexer styles", run it. You'll see dialog in which you can choose which lexer props to restore (from ini file).

cudatext restore styles.png

Snippets

To use snippets you need:

  • plugin Snippets
  • snippets for particular lexer: install them in Addon Manager

Each snippet has name (shown in menu dialog) and short id (letters, digits, '_', dot). You can type id in text and press Tab key: snippet for this id will be inserted into text. You can insert snippets also from dialog: call "Plugins - Snippets".

Only those snippets are inserted and shown in dialog, which are for current lexer. E.g. snippet may be for lexers "C,C++,Objective C"-- it will be used only when these lexers are active. Rare snippets have no lexer field, they are used always.

Menu of Snippets plugin:

cudatext snippets menu.png

Snippets have markers in them. Markers placed in editor (small red/blue triangles), and caret jumps to 1st marker, then you type text at this marker and press Tab key - caret jumps to next marker. Markers may give multi-carets too (if same text is needed at several places of snippet). While markers are shown, Tab key works special (jumps to next marker). After you collect all markers by Tab, Tab key will work as usual.

Snippets for HTML tags

CudaText has preinstalled 120+ snippets for HTML tags. (You also need to install Snippets plugin.) They work in lexers HTML, HTML_ (alternate HTML lexer in Addon Manager). Just type tag name without a bracket, press Tab, and snippet is inserted. E.g. "a"[Tab] will give:

 <a href="http" title="Title" target="_blank"></a>

These snippets have markers and Tab-key jumps to next marker, ie next parameter/value of tag. Last marker is usually after entire tag, after ">" bracket.

Output/Validate panels

These lists allow to hilite (e.g. in blue) lines which match some regex. This regex is set by plugin which uses these panels. E.g. plugin HTML Tidy uses panel Validate and sets regex for Tidy result lines. If a line matches regex and hilited, dbl-click on line navigates to source file.

These panels have hotkeys:

  • Up/Down/PgUp/PgDown/Home/End: move selection in list
  • Enter: navigate to source file, like dbl-click
  • Ctrl+Del: clear entire list
  • Ctrl+C: copy to clipboard entire list
  • Ctrl+D: copy to clipboard selected line
  • Esc: focus editor

Dialogs Find/Replace

Dialog has hotkeys:

  • Alt+Enter: Find first
  • Enter: Find next/ Replace next (depends of focused input)
  • Shift+Enter: Find previous
  • Ctrl+Enter: Add new line in multi-line input
  • Alt+Z: Replace, and find next
  • Ctrl+Alt+Z: Replace, and don't find next
  • Alt+A: Replace all
  • Alt+O: Count all
  • Alt+E: Select all
  • Alt+K: Mark all

Option buttons have hotkeys too, hover mouse over them to see hints:

  • ".*" - Regular expressions - Alt+R
  • "aA" - Case sensitive search - Alt+C
  • "w" - Search for whole words only - Alt+W
  • "O" - Wrap search, ie search from beginning after reaching the end, and vice versa - Alt+N
  • "[..]" - Search in selection only - Alt+X
  • "+" - Toggle multi-line mode: input boxes have double height and show several lines - Alt+M
  • "?!" - Show confirmation on each replace - Alt+Y

Dialog "Go to"

Dialog allows to enter text in formats:

  • Line: jump to given line number (to line start)
  • Line:Col: jump to given line and column numbers

More formats can be added by plugins (they can handle appropriate event).

Comments

You can add/remove code comments, via "Comments" plugin. Plugin is preinstalled in CudaText. It gives about 6 commands in menu "Plugins - Comments - ...". Plugin supports only adding/removing of comments, not syntax highlighting for them.

  • Line comments: from substring to line-end. E.g. in C lexer: "//text here", in Python lexer: "# text here".
  • Comments for range (Stream comments): from substring-1 to substring-2. E.g. in C lexer: "/* text here */".
  • Comments for full lines: from newline to another newline. E.g. used in PowerShell.

For ex, Python lexer supports only line comment, and don't support stream comments. PowerShell lexer supports comments for full lines, while don't support comments for any block.

Comment chars are editable in dialog "Lexer properties" (after you called needed lexer), in tab "Commenting" you see few input fields. Command "Toggle stream comment" in plugin adds/removes comments of last 2 types: for range, for full lines (plugin chooses needed kind).

Comment chars are saved:

  • Line comments: in lexer file (data/lexlib/lexername.lcf)
  • Comments for range/ for full lines: in separate files (data/lexlib/lexername.cuda-lexmap), which not exist for many lexers yet. On installing a lexer without .cuda-lexmap file, you'll see a warning about it in "Addon installed" dialog. In this case, open "Lexer properties" dialog and configure these chars.

Char map

Char-map dialog can be called in Edit menu. It has 2 modes:

  • ANSI: Shows ANSI char codes from 0 to 255 (codes 128..255 map to different Unicode codes, this depends on active OS locale).
  • Unicode: Shows almost all Unicode code points, they are divided to groups. Change active group using combobox at the bottom.

Click any cell in the grid to insert this char at caret position. Or select a cell with arrow keys and press Enter.

cudatext-charmap.png

Tab-switcher using history

SynWrite has the option "Use modern Tab-switcher" which makes special mode for Ctrl+Tab keys (switch to next tab). This mode shows special dialog which allows to switch tab using visit-history; ie press Ctrl, Tab+Tab+Tab, release Ctrl: this goes 3 steps back in visit-history. Visit-history is updated on activation of tabs (activated tab moves to the top of history).

CudaText can do this with Ctrl+Tab, but without dialog. To do it, install CudaExt addon. It has file in readme dir, which shows what to do.

Minimap, Micromap

Minimap is wide vertical bar near editor's right (default) or left side. To show it, set option "minimap_show", or use menu item "View - Toggle minimap". If you drag mouse over minimap, editor will scroll entirely from top to bottom, even for huge files (it's made like in Sublime). Text in minimap is painted by 1-2 pixels per char, not by font rendering, so scale of minimap cannot change.

Micromap is thin (about 12 pixels) vertical bar near editor's right side (near vert scrollbar). To show it, set option "micromap_show".

Colored marks on micromap:

  • wide+tall mark: current visible area of editor
  • on left side: line-states marks (3 states: line changed, line added, line saved)
  • on right side: marks for selections (made e.g. by "Find/ Select all", usually blue)
  • on right side: marks from Spell Checker plugin (usually red)

Paste with middle-button-click

To paste like in Linux, with middle-click, you need

  • set option "mouse_mid_click_paste"
  • install plugin "Auto-Copy to Clipboard"

This activates auto-copy of selection (copy to clipboard after text selection changes), and paste to position of mouse cursor on middle-click. But it works only for "editor frame", and don't work for: Console read-only editor, single-line inputs. So this method is limited.

Full-screen

There are two menu items in the View menu:

  • Toggle Full-screen. This maximizes app window (in a special way, OS-dependant, even OS taskbar hides), and also, optionally, turns off some UI elements: toolbar, statusbar, sidebar, side panels (Tree, Project, FTP), bottom panels (Console) etc. Option "ui_fullscreen" has set of chars, each char for one UI element to hide. E.g. option value "tp" hides 2 UI elements ("t" for toolbar, "p" for side panels).
  • Toggle Distraction-free. Like full-screen, but all UI elements hide. No option currently to configure which elements.

Notes:

  • On macOS full-screen modes hide top menu. To show it w/o returning back, just move the mouse cursor to the top of the screen and hold a little.

Python integration

Python on Windows

For Windows builds, Python engine is preinstalled.

For old Windows XP, Python 3.4 or 3.3 must be used, you can get its files from SynWrite.SF.net, from archived versions of SynWrite. Before copying these files, first delete current Python files (*.dll, python*.zip, folder DLLs). And write option "pylib" in the user.json:

"pylib": "python33.dll",

Python on Linux

Linux version uses Python library from OS. Install Python 3.x into OS (usually already installed). Instruction for Linux, if Python engine not found:

  • Open file manager, go to /usr
  • Search for "libpython3.*so*",

Terminal command:

$ find /usr -name 'libpython3.*so*' 2>/dev/null
  • If not found, install Python 3.x, go to search-step
  • Set "pylib__linux" in the "user.json" config, to one of the found filenames. Write option to the "user.json" or course - it is called by menu item "Options / Settings-user".

Python on macOS

On macOS you must install Python 3.x, from official site python.org. Versions 3.6...3.9 are ok. CudaText will find Python then.

Python installed from Homebrew cannot be used by CudaText: it misses 32-bit .dylib file.

Line states

In the gutter bar, you can see colored thin bars next to line numbers: green, yellow. It is line states. They show state of lines:

  • usual lines (not changed)
  • changed lines
  • newly added lines
  • changed or added, and file was saved after it

Line states help to see which lines were edited in the last time. Also CudaExt plugin gives few commands to jump over lines with some line states (go to next/previous for several states: for changed, for added, for changed+added).

Project Manager

This plugin is preinstalled in CudaText. It shows panel "Project" in the sidebar (to show this panel, call plugin by any command, or set plugin's option "Load on program start" and restart, CudaText sidebar will have Project button). On the project panel, on its tree-view, you can add several "root nodes", each node must be existing file or folder. For folder nodes, plugin auto shows all nested folders. You cannot add nodes on other levels (like SynWrite editor does).

Plugin has context menu on its panel, with items:

  • Project file
    • New project
    • Open project
    • Recent projects
    • Save project as...
    • Go to file... - this shows menu with all project files, and then tree-view selection jumps on selected file
    • Project properties... - this shows dialog with current project's options
    • Config... - this shows dialog with global Project Manager options
  • Root nodes - commands for nodes on the project's root level
    • Add folder...
    • Add file...
    • Clear project
    • Remove node
  • Selected file - it's shown only for files
  • Selected directory - it's shown only for folders
  • Refresh - it re-reads state of files/folders from disk

Any project can have "main file", you can choose it in the context menu: "Selected file - Set as main file". Main file's path is used by plugin External Tools, when some tool is configured with macro {ProjMainFile}. This allows tools to run compilation of the main file.

Project Manager shows file/folder icons, using default file-type-icons theme. You can change this theme in the plugin's Config dialog. But first, you must install additional file-type-icons theme from Addons Manager. Example of such theme: VSCode Material 24x24.

more

Tech topics

How to compile program

  • install .lpk packages into Lazarus IDE (find all .lpk files, open them in IDE, install from Packages dialog)
  • in IDE, in component palette, you must see:
    • in Misc tab: TATButton, TATButtonsToolbar, TATListbox, TATFileNotif, TATScroll, TATSynEdit, TATLabelLink, TGauge
    • in System tab: TUniqueInstance
  • in IDE, open "cudatext.lpi" Lazarus project, compile it

Python API

Separate big page about Python API is CudaText API.

Linux installation

On Linux you can install program, not using installers, in such way:

  • copy file "cudatext" to folder /usr/bin
  • copy dirs [data, readme, settings_default] to "~/.cudatext"
  • dir "~/.cudatext/settings" will appear automatically on run

If program runs and cannot find "data/lexlib" near executable, it opens dirs from "~/.cudatext". This allows to install binary to PATH, and data dirs to homedir.

Linux Qt

For CudaText Qt version, library libQt4Pas needed.

  • For Ubuntu: run
 sudo apt-get install libqt4pas-dev

How to make translation

Translation template-file is in dir "data/lang". How to make translation zip package:

  • make file "nn_NN.ini" (utf-8 with bom)
  • use standard locale names in filename, e.g. ru_RU pt_PT ja_JP (needed for plugins which uses Python translation API)
  • write your contacts in first commented lines. Comments must begin with ";" at line start. Also you can add other comments.
  • to set accelerator-chars for menus/dialogs, use "&" char (e.g. "Open &file"). If needed "&" as is, write "&&".
  • note: Linux Ubuntu font is 1.3x times wider (than WinXP)
  • make "install.inf" with such text:
[info]
title=LangName translation (by AuthorName)
type=cudatext-data
subdir=lang
  • make zip file "translation.nn_NN.zip" with files nn_NN.ini, install.inf
  • test this zip: open it in CudaText, and check it's installed
  • publish zip at CudaText forum or https://github.com/Alexey-T/CudaText/issues
  • if package ok, it will be at SF.net downloads, and in Addon Manager

Color themes

Two kinds of themes exist:

  • UI themes, file extension .cuda-theme-ui
  • Syntax themes, file extension .cuda-theme-syntax

Two dialogs allow to paint these kinds of themes. To paint a theme:

  • Call dialog: "Options/ Settings - more/ Settings - theme - nnnnn"
  • For UI themes: customize colors in dialog
  • For syntax themes: customize lexer-styles in dialog
  • For syntax themes: test theme at last on JS/HTML/CSS/C/Pascal/Ini/Markdown/Go lexers.
  • New theme files are saved in the subdir "data/themes"

Don't configure custom lexer styles in Lexer Properties dialog, if option "ui_lexer_themes" is on, because syntax-theme will override all your colors from that dialog. You can config these colors though, if option is off.


How to make theme package

  • Make such file "install.inf":
 [info]
 title=MyName UI theme (by AuthorName)
 type=cudatext-data
 subdir=themes
 homepage=https://github.com/nnnn/pppp
  • Make zip file "theme.MyName.zip" with files "MyTheme.cuda-theme-nnnnn" and "install.inf"
  • Test zip file: open zip file in CudaText, confirm installation
  • Publish file at forum or https://github.com/Alexey-T/CudaText/issues

How to see all UI theme items

  • "editor, font" - color of font when no lexer is active. Click statusbar field with lexer-name, call "none".
  • "editor, disabled state, font/bg" - editor shown with this bg-color when Replace dialog runs action, with option "confirm on replace" (during confirm message editor is disabled), if none lexer active
  • "statusbar alt" - shown on 2nd statusbar, run in console:
    msg_status_alt('dd', 8)
  • "search progressbar" - to see it, call Replace dlg, with regex, with confirmation (2 options in Replace dlg), replace "." (any char) to "www"
  • "editor, marked range bg" - shows for marked-range, to set marked range from line 5 to 10 use console:
    ed.set_prop(PROP_MARKED_RANGE, '5,10')
  • "editor, markers" - to see markers, call Commands dlg (F1), command "drop marker at caret".
  • "editor, separator lines" - lines show eg for lexer Pascal, above "function"/"procedure".
  • "listbox, ..." - call Commands dlg (F1 key)
  • "listbox, ..., auto-complete..." - call C or Pascal lexer, then press Ctrl+Space to call auto-completion (listbox has 3 columns, 3rd shows not for all items)
  • "splitters, main" - shown near Sidebar (vertical) and above Bottom panel (horizontal)
  • "splitters, groups" - shown between groups (vert/horz), activate 2-3 groups using "View" menu

How to use on Windows XP

Q: I have Windows XP, what version of CudaText (SynWrite) and Python should I have to have plugins working?

A: You need any version of CudaText (after 1.7), but older Python 3.4 DLLs. You must replace these Python files:

  • *.dll
  • *.zip
  • folder DLLs

With Python files from this WinXP build: https://sourceforge.net/projects/cudatextbuildlinuxi386/files/release/

Then open config "user.json" and write option:

 "pylib": "python34.dll",

How to copy to clipboard word under caret

A1: Install "Macros" plugin. In its dialog start recording a macro, and call these commands (in F1-Commands dialog), later assign to this macro a hotkey:

  • command "select words at carets"
  • command "copy to clipboard"
  • command "cancel carets", i.e. unselect

A2: Plugin CudaExt has commands:

  • plugin: CudaExt: Copy word or [expression] or 'expression' without selection
  • plugin: CudaExt: Replace word or [expression] or 'expression' with clip

I use these commands with hotkeys Alt+Left and Alt+Right.

Why on Linux, chars are duplicated

This is known problem, related to some Input Methods (IM) in Linux. To see what is your active IM, open Terminal and enter:

echo $GTK_IM_MODULE

Known IMs with problems: scim, xim. To fix: change IM from e.g."XIM" to "none" in the Language Support settings, then chars should not duplicate.

What SynWrite features not implemented

  • Sync-Editing, ie auto editing of name (identifier) in all places of selected block (sync range), w/o clicking each place of name
  • Tooltips (hints) with pictures preview in HTML
  • Tooltips with HTML color preview
  • Drag-drop of panels from sidebar and bottom bar
  • Panel "Clips" from right side (CudaText has snippets w/o panel)
  • Panel "Clipboard" from right side
  • Quick-search input box on toolbar

More

Formats of files

Format of auto-completion acp file

Common auto-completion file format is ANSI text file, it contains list of lines in forms:

Type Id |Hint
Type Id (Param1; Param2; ...) |Hint
Type Id (Param1; Param2; ...): ResultType |Hint
  • Strings "Type", "Id", "Params", "Hint" are shown in separate columns of completion listbox, with separate colors. "Id" is the text which is inserted for a line.
  • Both ";" and "," chars can be params delimiters. "|Hint" part is optional.
  • If "\" char is present in hint part, then it must be escaped: "\\".
  • If space is needed in id part, it must be written as "%20" (it's allowed for any char in range 0x20..0x2F).

First line in the file can be the "control" line: it specifies what chars are "word chars" for the used syntax. For example, if word chars are minus, dot, and # sign, the control line should be:

#chars .-#

Format of install.inf files

User can open addons in zip files (using "File-Open") and install them. To make such zip file, pack into zip also "install.inf" with meta-info.

  • "title" field (required)
  • "desc" field, long text for install prompt dialog
  • "type" field (required) must be one of:
    • cudatext-plugin: to install plugin to subdir of "py" dir
    • cudatext-data: to copy any files into subdir of "data" dir
    • lexer: to install lexers (zip must be made by SynWrite's ExLexer addon)
    • lexer-lite: to install lite lexer
  • "subdir" field (required)
    • for plugins it should begin with prefix "cuda_"
    • for lexers it should be "-"
  • "homepage" field, repo URL on GitHub or another site
  • "api" field, optional string of required API version, specify if plugin cannot work on older API


Plugins

Example of install.inf for plugin (plugin adds 2 menu items with menu separator between):

[info]
title=MyName
desc=Plugin allows smth
type=cudatext-plugin
subdir=cuda_test
homepage=http://github.com/some/name/
api=1.0.200

[item1]
section=commands
caption=MyPlugin\Cmd one
method=run
lexers=CSS,HTML
hotkey=Alt+F

[item2]
section=commands
caption=MyPlugin\-
method=nnnn

[item3]
section=commands
caption=MyPlugin\Cmd other
method=run_more
menu=0

Section names: from "item1" to "item400", any numbers can be skipped.

  • Line "homepage=": optional, it allows to go to homepage via Addon Manager command "Visit plugin's homepage".
  • Line "api=": optional, it allows to disable installing of addon on older CudaText versions.
  • Line "lexers=": comma-separated lexer names, means that command can be run only when such lexer(s) active.
  • Line "hotkey=": value must be simple hotkey string (e.g. "Alt+F", "Ctrl+Shift+F1") or key combo separated by "|" (e.g. "Alt+F|F|G").
    • If "lexers=" param missed, then hotkey saves to file "keys.json" for all lexers.
    • If "lexers=" param present, then hotkey saves to "keys lexer NNNN.json" for each mentioned lexer.
  • Line "menu=": optional. Possible values:
    • "" (empty, default): menu item will be put to "Plugins".
    • "0": hide menu item.
    • "o": menu item will be put to "Options / Settings-plugins".
    • "op": menu item will be put both to "Plugins" and "Options / Settings-plugins".

Lexer lists

If plugin has many [itemN] sections, it is possible to set list of lexers using vairable (not to write each time "lexers=name,name2,name3"). Declare list of lexers in [info] section like this, any variable name:

[info]
$var=Name1,Name2,Name3

In [itemN] sections set lexers like this:

[itemN]
lexers=$var

You can set lexers by reg-ex, e.g. reg-ex ".*SQL.*" means all names with substring "SQL". To do it, write variable with prefix:

[info]
$var=regex:.*SQL.*

Data-files

Example of install.inf for data files, to be copied into subdir of "data" dir. Name of subdir can be any, for example "themes".

[info]
title=NiceDarkTheme
desc=Nice Dark theme (by AuthorName)
type=cudatext-data
subdir=themes

Lexers

To see example of install.inf for lexers, download any lexer. To see complex example, download lexer zip for "HTML Smarty" which has 2 lexers inside, one lexer is linked to another.

[info]
title=HTML Smarty
type=lexer
subdir=-

[lexer1]
file=HTML Smarty internal
[lexer2]
file=HTML Smarty
link1=CSS
link2=VBScript
link3=JavaScript
link4=JavaScript
link5=VBScript
link6=PHP
link7=PHP
link8=HTML Smarty internal

Lite lexers

Example of install.inf for lite lexer. Note that "^" suffix not needed here.

[info]
title=MyLexer
type=lexer-lite
subdir=-

Format of snippet files

Contents

To specify markers:

  • ${NN}
  • ${NN:default text}

These place markers in text, marker index NN is 0 to 40. After snippet insertion, tab-key goes to markers (and deletes them).

  • Markers can be in any order in snippet (e.g. marker 4 can be between 1 and 2)
  • Tab-key goes first to marker 1, 2, 3... and marker 0 is always last by tab-key.
  • Markers with the same index will place multi-carets, when tab-key goes to them.
  • Nested markers with def-text allowed, but only 1 level: ${2:text is {$3:here}}.
  • Macro ${NN:...} with def-text can take n lines (ending "}" on next lines, so selection will be multi-line).

The following macros are allowed in snippets text:

  • ${sel} - Replaced with text selected before snippet insertion. (If snippet called with Tab key, it's empty string.)
  • ${cp} - Replaced with clipboard text.
  • ${fname} - Replaced with current file name (w/out path and extension).
  • ${date:nnnnnn} - Replaced with current date/time formatted by string nnnnnn. See Python doc.

File names

Snippets are stored in separate files with extension ".synw-snippet". Encoding is UTF8 no BOM. They can be placed in any subdir of "data/snippets" dir, file names and dir names have no meaning, but it's good to name subdirs like AuthorName.SyntaxName, so users can easily find newly installed snippets.

File format

First lines have format "str=value" (no spaces around "="), where "str" is one of strings:

  • name - snippet full name (any non-empty string).
  • id - snippet short alias/id for Tab-key (latin letters, digits, "_", dot), line is optional.
  • lex - lexers list, comma-separated, for which snippet is active, line is optional, empty means snippet always active.

Then follows the line "text=" without value, and all next lines - are snippet text.

  • Trailing blank lines are discarded.
  • Use tab-chars in text indents, they are auto replaced to spaces if current editor configured so.

More