=Introduction=

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

* Syntax highlighting for a lot of languages: [[#List_of_lexers|230+ lexers]]
* Code folding
* Code tree (list of functions/classes/etc, if lexer supports this)
* Multi-carets, multi-selections
* Search/replace with regular expressions
* Support for many encodings
* Extendable by Python add-ons
* Command palette
* Configs in JSON files
* Interface and syntax themes
* Based on the [[ATSynEdit]] engine

Features for HTML/CSS coding:

* Built-in HTML and CSS auto-completion
* HTML tags completion with Tab-key
* HTML color code underlining
* HTML tooltips on mouse-over
* Viewer for picture files (jpeg, png, gif, bmp, ico)

Screenshot on Windows:

[[File:cudatext.png]]

=Advantages over Sublime Text 3=

* Open source, more operating systems
* The Python API is easier to use
* The Python API allows management of dialogs and UI-controls, including the CudaText editor control
* Code-Tree for most of lexers (ST has only plugin for very limited set of languages)
* Powerful EControl lexer format, and easier to configure (GUI in external program)
* Floating (separate window) mode of side panel and bottom panel
* Floating (separate window) groups of UI-tabs (in addition to normal 6 groups)
* [[#Toolbar|Toolbar]], configurable via plugin 
* [[#Configurable_statusbar|Configurable statusbar]]
* Horizontal ruler above text
* [[#Micromap|Micromap]]
* [[#Markers|Markers in editor]]
* [[#Sessions|Sessions system]] 
* Caret position after end of line
* Better support for encodings, including UTF-32
* Better support national keyboards on Linux
* Correctly saves binary files
* [[#File_viewer|Viewer for files of unlimited size]]
* [[#Program_perfomance|Program performance]]
* [[#Hex_display_of_special_chars|Hex display of special chars]]
* [[#Tabs_features|Colored UI tabs]]
* Plugin "Options Editor" to configure CudaText via GUI
* [[#Char_map|Character Map dialog]]
* UI can be scaled by option (up to 500%)
* Single-instance mode is supported on all OS'es
* Scrolling after middle-button click (called "Autoscrolling" in Firefox)
* [[#Show_pictures_in_the_text|Show pictures in the text]]
* [[#Activating_internet_links|Activating internet links]]
* [[#Automatic_folding_of_comments|Automatic folding of comments]]
* [[#Special_HTML_auto-completion|HTML auto-completion suggests file/folder names]]
* [[#File_URI_auto-completion|File URI file:/// auto-completion]]
* [[#HTML_color_codes_underlining|HTML color codes underlining]]
* [[CudaText_plugins#Macros|Macros plugin]] also records actions performed in the Find/Replace dialog, and mouse clicks
* CudaText and its plugins support i18n (text strings can be translated)
* Function "Find in files" is [[CudaText_plugins#FindInFiles|implemented in plugin]], with much more features
* [[#Tab_switcher|Tab switcher]] dialog
* Can split single UI-tab, for single file or 2 different files (helps to work with Differ plugin)
* Option for "zebra mode"
* Can plug-in a different Python engine (packages in add-ons)
* Add-ons do not disappear due to GitHub repository deletions

= Download =

* Homepage: http://uvviewsoft.com/cudatext/
* Downloads: https://www.fosshub.com/CudaText.html . It has builds for Windows, Linux (x32, x64, ARM, AArch64), macOS, FreeBSD, NetBSD, Solaris.
* GitHub repository: https://github.com/Alexey-T/CudaText . That account https://github.com/Alexey-T contains other packages needed to compile the app.

= Configs =

CudaText has configuration system in JSON files: call menu item "Options / Settings - default" and you'll see the '''default config'''. You should copy lines from this file to the file from "Options / Settings - user" and edit this '''user config''' - this is the actial config file. Default config is not read by CudaText, it's only to show possible options.

You can copy JSON comments too. In the user config, include useful lines in the curly braces "{ }", this is JSON format. Trailing comma before "}" is allowed here.

* '''User config'''. File "settings/user.json". Can be opened via menu item "Options / Settings-user".
* '''Default config'''. File "settings_default/default.json". Can be opened via menu item "Options / Settings-default". CudaText doesn't use this file, it's only for user reference. CudaText only opens this file by the command, and this file is parsed by plugin "Options Editor".
* '''Lexer specific configs'''. Files "settings/lexer NNN.json". It is layer which is read after user config, when user activates some lexer. E.g. if you open C file, config file "lexer C.json" is read. You should not write "ui_" options to lexer specific configs (it may give weird effects on changing lexer), and some other global options.
** For (None) lexer, config file is named "lexer -.json".
** For lite lexers, config files are named with suffix, e.g. "lexer XML ^.json".
* '''Default lexer specific configs'''. Files "settings_default/lexer NNN.json". It is layer which is read after user config, but before lexer specific config. CudaText provides several such files, with useful defaults.
* '''Hotkeys config'''. File "settings/keys.json". Special dialog allows to change all hotkeys in CudaText. You should not edit this config file. Dialog is called from "Help / Command palette" by F9. Dialog allows to set 1st and 2nd hotkeys for any command (except dynamically added commands to change lexer).
* '''Plugin configs'''. Files "settings/cuda_*". Plugins store their settings in there, and files can be in any format (most used are JSON and INI). Good quality plugins provide menu items in "Options / Settings-plugins" to open their config file, or to show configuration dialog.
* '''History files'''. Files "settings/history*.json". Don't edit them. Mentioned here because sometimes users need to delete their history files (dialog positions, recent files list etc, recent search strings etc).

== File types config ==

Section "detect" in user.json. Specifies mapping from "file name" to "lexer name".

<syntaxhighlight lang="javascript">
  "detect": {
    "*.mht": "HTML",
    "myconfig.conf": "Nginx",
    ".profile": "Bash script",
  },
</syntaxhighlight>

* Key name: File mask. Must be full name (without path), or extension after "*." chars. More complex masks are not yet supported.
* Key value: Lexer name. 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.

Section "detect_line" in user.json. Allows to detect lexer by first line of file.

<syntaxhighlight lang="javascript">
  "detect_line": {
    "<html.*": "HTML",
    "<!DOCTYPE.*": "HTML",
    "<\\?xml.*": "XML",
  },
</syntaxhighlight>

* Key name: Reg-ex for first line. Case sensitive, but you can use (?i) modifier in reg-ex.
* Key value: Lexer name. Value "-" means "don't activate lexer".

== Plugin groups config ==

Section "plugin_groups" in user.json. Allows to add grouping to the Plugins menu, e.g. to put all "HTML ..." and "CSS ..." menu items into "Web" submenu. Example:

<syntaxhighlight lang="javascript">
  "plugin_groups": {
    "CSS .+": "Web",
    "HTML .+": "Web",
    "JS .+": "Web",
    "Config.+": "Config",
    "Option.+": "Config",
  },
</syntaxhighlight>

* Key name: regular expression for the first part of menu name. E.g. if menu name in install.inf is "CSS Utils\Misc\Action", then first part is "CSS Utils".
* Key value: group name, it can be with "\" char to make several levels.

= Help topics =
== Command line parameters ==

Usage:

* cudatext [ key ... ] filename ...

Supported keys:

* -h, --help - Show command-line help and exit
* -v, --version - Show application version and exit
* -z=value - Open files from command-line in internal viewer, using given viewer mode
** -z=text - Text mode with variable line length, single-byte encodings
** -z=binary - Text mode with fixed line length, single-byte encodings
** -z=hex - Hexadecimal mode, single-byte encodings
** -z=unicode - Text mode with variable line length, UTF-16 LE/BE encodings
** -z=uhex - Hexadecimal mode, UTF-16 LE/BE encodings
* -r - Open files from command-line in read-only mode
* -e=value - Open all files from command-line in given encoding
* -el - Show possible encoding names and exit
* -n - Ignore option "ui_one_instance", and open new app window
* -nsl - Don't load last session on start
* -nss - Don't save last session on exit
* -ns - Shortcut to -nsl with -nss
* -nh - Don't load saved file history (caret, selection, scroll position, etc)
* -nn - Don't suggest to create new file if command-line filename is not found
* -s=folder - Specify full path of "settings" folder, which contains all config files
* -i - Read the contents of stdin to a new document. Unix only. It can be used in Unix shell like: "ls -l | cudatext -i"
* -id=name - Set "group" for single-instance mode, so that program with one "group" will not interfere and find instances with another "group". Unix only. Default value is "cudatext.0".
* -w=left,top,width,height - Set position/size of window (up to 4 numbers should be specified, any can be skipped 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.
* File masks with "*" symbol are supported, e.g. command "cudatext test/t*.htm*" will work.

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

Note for macOS: use Cmd key instead of Ctrl key, in all commands listed here.

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

Dragging:

* 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.
* drag-drop of selected text block is supported. If Ctrl is pressed during the drop (you should press Ctrl after drag is started), block will be copied (not moved) to pointed position.

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+Alt+click - make vertical (column) selection, from first caret to clicked position.
* Shift+ scroll mouse wheel - scroll text horizontally.
* Ctrl+ scroll mouse wheel (with option mouse_wheel_zoom) - zoom text in/out.
* Ctrl+ scroll mouse wheel (on picture preview panel) - zoom picture 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:

[[File: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:

[[File:atsynedit-sel.gif]]

===Commands with selections===

Clipboard commands work with multi-carets and multi-selections the special way.
Also "Delete char" commands (Delete/Backspace keys) works the special way.

{| class="wikitable"
|-
! Command
! Behaviour, when there're no selections
! Behaviour, when at least one selection present
|-
| Copy to clipboard
| Copies entire lines, containing carets. Ignores multiple carets on a same line.
| Copies only selections text. Ignores carets without selections.
|-
| Cut to clipboard
| Similarly to "Copy" without selections.
| Similarly to "Copy" with selections.
|-
| Paste from clipboard
| colspan="2" | 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 left (Backspace) / Delete char right
| Deletes one char at each caret position.
| Deletes only selections text. Ignores carets without selections.
|}

== Lexers ==

Syntax highlighters in CudaText are called lexers. Lexers are compatible with SynWrite editor (which is frozen). Lexer engine by EControl.ru is used, with modifications by Alexey Torgashin. Main modification is support for folding in Python and other syntaxes with indentation-based folding. Other modifications are porting from Delphi to Free Pascal and optimizations. EControl.ru's original lexer engine is closed source, but CudaText's version is open source, with the permission from EControl.ru.

* 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".

[[File: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 on SourceForge ===

Preinstalled lexer library has limited set of lexers.
Other lexers, which are compatiable with SynWrite editor, are hosted on SF.net:
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.

=== List of lexers ===

The following lexers (counting only important ones) exist for SynWrite and CudaText.
Most of them are located in Addons Manager "Install" list.

* ABAP
* Abaqus Keywords
* ABC Notation
* ActionScript
* Acu Cobol
* Ada
* Adobe Flash
* Amazon Ion
* Apache config
* Apache Hive
* Apache Pig
* AppleScript
* Arduino
* AsciiDoc
* Assembly
* Assembly ARM
* Assembly AVR
* Assembly FASM
* Assembly JWASM
* Assembly MASM x86
* Assembly MIPS
* Assembly Motorola 68k
* Assembly NASM x86
* Assembly PowerPC
* Assembly RISC-V
* Assembly SHARC DSP
* Assembly SPARC
* Assembly STM32
* Assembly Z80 SjASM
* Assembly Z80 RGBDS
* Asymptote
* Autoconf M4
* AutoHotkey
* AutoIt
* Automake
* AviSynth
* AWK
* Ballerina
* Bash script
* Batch files
* BibTeX
* Bitsquid SJSON
* Bohemia SQF
* Boo
* Brainfuck
* C
* C#
* C++
* Caffe Prototxt
* Caml
* Clarion
* Clavier
* Clipper
* Clojure
* CMake
* Cobol
* CodeVisionAVR
* CoffeeScript
* ColdFusion
* CRF files
* CSS
* CUDA C++
* D
* Dart
* Delphi resources
* Dhall
* Diff
* Dockerfile
* Eiffel
* Elixir
* Elm
* Erlang
* etlua Template
* Euphoria
* F#
* Factor
* Falcon
* Fish
* Forth
* Fortran
* FoxPro
* FreeBASIC
* GAMS
* GDScript
* Gherkin (Cucumber; Behat)
* GHS.com MULTI IDE (3 lexers)
* GLSL
* Gnuplot
* Go
* Gold Parser
* Graphviz DOT
* GraphQL
* Great Cow Basic
* Groovy (Gradle)
* Grub4Dos
* Haml
* Harbour
* Haskell
* Haxe
* HJSON
* HLSL
* HTML
* HTML Diafan
* HTML Django DTL
* HTML Embedded JS
* HTML Handlebars
* HTML Laravel Blade
* HTML Liquid
* HTML Mustache
* HTML Ruby-ERB
* HTML Smarty
* IDL files
* IDL language
* Informix 4GL
* Ini files
* Inno Setup
* Intel HEX
* Jade
* Jasmine JVM Assembler
* Java
* Java Velocity
* JavaScript
* JavaScript Babel/ React JSX
* JCL
* Jinja2
* JQ
* JSON
* Jsonnet
* Julia
* Kivy
* KiXtart
* Kontakt Script Processor (KSP)
* Kotlin
* LaTeX
* LESS
* Lisp
* LiveCode script
* Log files
* Logstash DSL
* Lola-2
* LS-DYNA
* Lua
* Macro Scheduler script
* Makefile
* Markdown
* MATLAB
* Maya
* MediaWiki
* Metafont
* MIB files
* MikroTik Script
* MiniZinc
* Modelica
* Modula 2
* Monkey
* MSVS Solution
* MusicBrainz Picard Tagger Script
* MySQL
* Nemerle
* Nginx
* Nim
* Nix
* nnCron
* NSIS
* NSL Assembler
* Oberon
* Objective-C
* OpenCL
* OpenEdge
* OpenSCAD
* Org-mode
* Papyrus (for Skyrim game)
* Parser3
* Pascal
* Pawn
* PECmd script
* Perl
* PHP
* PICL
* Pike
* PKGBUILD
* PL/SQL
* PlantUML
* Pony
* PostScript
* Power Query M
* PowerShell
* Prolog
* Properties
* Pug
* Puppet
* PyMOL
* Python
* R
* R Markdown
* Racket
* Rainmeter
* Ragel
* Raku (Perl 6)
* Razor
* reStructuredText
* RON
* RPG/IV
* RTF (RichText)
* Ruby
* Rust
* Sass
* Scala
* Scheme
* Scilab
* SCSS
* SFZ Format
* Singularity
* Slim
* Smalltalk
* Snowflake SQL
* Solidity (Ethereum)
* Specman
* SPICE (PSpice, HSPICE)
* SPIR
* SQL
* Squirrel
* SRT Subtitles
* Standard ML
* Stata
* Strace
* Stylus
* Swift
* T-SQL
* TAGML
* TakeCommand
* Tcl/Tk
* Textile
* TOML
* Tree
* Twig
* TypeScript
* V
* Vala
* VBScript
* Verilog HDL
* VHDL
* VimL (Vimscript)
* Virgil
* Visual Basic
* Visual dBase
* Vue
* WikidPad
* WinBuilder script
* Windows Resource Script
* WSH script
* XML
* XSLT
* Yacc (Bison)
* YAML 
* ZenScript (MineTweaker)
* Zephir
* Zig

=== 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:

[[File:cudatext-lexer-editor-dlg.png]]

=== 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 second one 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 (menu: Options / Lexer / Lexer library).
* In dialog, focus needed lexer, press "Configure" button
* Dialog "Lexer properties" will open for selected lexer
* In dialog's "Styles" tab, configure all you need

You can change visibility of lexer in SynWrite lexer editor (the checkbox will write line "Internal = True" at the end of .lcf file).

===How to create distributive of new lexer===

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 highlight of string `12+$var` with additional highlight 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.

===Differences in lexer support in CudaText/SynWrite===

* SynWrite has lexer engine with old code for indentation-based folding, so all lexers with indentation-based folding must be different in CudaText and SynWrite.
* SynWrite lexers need constructs like \x0D\x0A or \z (any line-break), while CudaText lexers are OK with simple \n (because internal buffer never has CR char).
* Some lexers need to find equal identifiers at begin/end of blocks: HTML, Bash, others. Bash lexer needs extended feature: to see NAME and 'NAME' and "NAME" as equal identifiers (word and quoted word). Only CudaText has this extended feature, not SynWrite.
* For CudaText you must avoid "system colors" in lexer styles (e.g. "window background", "window text", "hint background"), because OS'es have different system colors.
* SynWrite lexer settings are not used in CudaText:
** Option "Restart analysis from the line start" has no effect, it is forced to On in CudaText
** Default style
** Selection mark style
** Search mark style
** Current line style
** Collapse mark style
** Character set
** Multiline border
** Options in groups "Syntax tree decoration", "Pen"

===How to make editor re-scan entire document on editing===

The question makes sense, because when user types the block ending (e.g. "}" in C syntax), editor re-scans the document from the last changed line, and cannot detect that new block is just appeared.

Find the lexer file, .lcf file in the folder data/lexlib. This file has the ending with "end", before "end" you see several lexer settings. You can add there:

 FullRefreshSize = 5000

This tells lexer to re-scan entire document, on editing in any document place, when document size is less than 5000 chars.

===How to support Spell Checker in lexer===

Plugin "Spell Checker" checks text, which is inside "strings" and "comments". So you must configure lexer and set there, which lexer elements (tokens) are "strings" and "comments". It is options in the "Lexer properties" dialog of SynWrite, in the "Commenting" tab of dialog. You can change these options without SynWrite too - they are in the data/lexlib/LexerName.cuda-lexmap file, both options are comma-separated names of lexer styles. 

For example, let's see XML lexer. We must specify styles:

* style applied to XML/HTML comments
* style applied to quoted strings in XML tags
* style applied to usual text out of angle brackets

If you see lexer config in SynWrite, you will find that we need styles "Comment", "Text" and "Tag val". So we specify in the file data/lexlib/XML.cuda-lexmap:

 styles_cmt=Comment
 styles_str=Text,Tag val

===Automatic folding of comments===

There is an option "auto_fold_comments" (default is 5) which allows to automatically
create folding ranges from N consecutive lines, which are all "syntax comments".
This works for both line-comments and stream-comments, they can be even mixed
(one comment after another, with any amount of blank lines in between,
but not for several stream-comments on a single line).

[[File:cudatext-fold-comments.png]]

Previously, CudaText allowed something like this, via lexer configuration: all needed lexers must have
special settings inside them, and this worked for 2+ lines, not for custom value.
After the option "auto_fold_comments" appeared, all 3rd-party lexers should be stripped of those old settings.

==Location of folders 'settings', 'py', 'data'==

Non-portable CudaText installation exists

* for Linux - .deb package, which copies several folders to system folder
* for macOS

All other CudaText packages are portable. When program runs, it first detects "am I in portable mode?" (executable file is located near folder "data"). And if "not portable", these locations of 'data' and 'py' folders are used:

* Linux, *BSD, Solaris: ~/.config/cudatext, or $XDG_CONFIG_HOME/cudatext if this OS variable is set
* macOS: ~/Library/Application Support/CudaText

==Encodings==

You can change encoding of document by clicking on statusbar item, or by using menu "File / Encoding". Menu will give list of encodings. Menu gives 2 sub-menus:

* "Reload as": Reload file in given encoding from disk.
* "Convert to": Change encoding in memory only (this doesn't save the file).

Possible encoding names for command-line usage:

* utf8
* utf8_bom
* utf16le
* utf16le_bom
* utf16be
* utf16be_bom
* utf32le
* utf32le_bom
* utf32be
* utf32be_bom
* cp1250
* cp1251
* cp1252
* cp1253
* cp1254
* cp1255
* cp1256
* cp1257
* cp1258
* cp437
* cp850
* cp852
* cp866
* cp874
* cp932
* cp936
* cp949
* cp950
* iso88591
* iso88592
* iso885915
* mac

==Line ends==

All major types of line-ends are supported:

* CR LF (usual for Windows)
* LF (usual for Unix)
* CR (usual for Mac OS 9, now almost not used)

Mixed line-ends (CR with LF with CR LF) in one file are supported. Because of this feature, CudaText saves binary files to disk without corrupting them. To see mixed line-ends, use application option "unprinted_content", which can show text marks ("lf" etc) at line-ends.

To change line-ends for all lines in the current document, click statusbar cell for line-ends, menu will appear. You need to save file then. Changed line-ends can be undone via "Undo".

==Groups of tabs==

"Groups" are tab sets, each tab has attached editor control. By default only the first group is shown. Totally 6 groups can be shown at once. Menu item "=" (rightmost item in the top menu) allows to choose grouping mode:

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

First group cannot be empty, at least 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.
* On changing grouping mode, tabs from disappearing group(s) are moved to still visible group.

"Floating" groups are available, besides "fixed" 6 groups, they are inside separate windows (so can be moved to separate monitor). To place some tab to a floating group (1, 2, 3), call context menu over a tab title, "Move tab to group / Floating n" (n=1, 2, 3).

==Auto-completion==

Command "auto-completion menu" (default hotkey: Ctrl+Space) shows auto-completion listbox. It works in several sutiations differently.

====IntelliSense====

Intelligent completion is supported via plugins. For the end of 2020 year, such plugins exist for: Python (plugin "Python IntelliSense"), AutoIt ("AutoIt Helper"), SPIR ("SPIR Helper").

Microsoft LSP protocol is not yet supported by CudaText nor by plugins.

====Static auto-completion files====

Some lexers (e.g. PHP, Pascal, Clojure) provide .acp files, which are fixed set of special words, to show in completion listbox. This is very simple completion, which ignores current context, it only suggests matching strings for the word (or string) under caret. These .acp files are stored in the folder "data/autocomplete".

====Special HTML auto-completion====

Lexer HTML (and lexers with "HTML" in name, see the option "autocomplete_html_lexers") has its special logic, which is built-in in CudaText. It uses data files in the folder "data/autocompletespec". Completion listbox shows different information depending on context: 

* Caret is on empty space or after "<". Listbox show list of tags.
* Caret is on tag name (opening or closing). Listbox shows list of tags (beginning with typed tag).
* Caret is after opening tag, before closing bracket, on empty space. Listbox shows list of tag's attributes.
* Caret is on tag's attribute, before "=". Listbox shows list of attributes (beginning with typed attribute).
* Caret is after tag's attribute, after "=". Listbox shows list of possible values of attribute, for fixed set of values.
* Caret is inside attribute's quoted value. Possible cases:
** Some tag/attribute with fixed set of values. Listbox shows list of possible values (beginning with typed value).
** Tag A, attribute HREF. Listbox shows list of folders and all files (all files can be hyper-linked). 
** Tag LINK, attribute HREF. Listbox shows list of folders and CSS files.
** Tag SCRIPT, attribute SRC. Listbox shows list of folders and JS files.
** Tag IMG/INPUT, attribute SRC. Listbox shows list of folders and picture files.
** Tag FRAME/IFRAME, attribute SRC. Listbox shows list of folders and HTML/PHP/ASP files.
** Tag AUDIO, attribute SRC. Listbox shows list of folders and audio files (HTML supports few extensions).
** Tag VIDEO, attribute SRC. Listbox shows list of folders and video files (HTML supports few extensions).
** Tag SOURCE, attribute SRC. Listbox shows list of folders and audio+video files (code doesn't detect the outer tag: audio, video etc).

[[File:cudatext-complete-pics.png]]

About folders/filenames completion. Listbox items list depends on part of the quoted value before the caret. Folder/file names are taken from the folder/subfolder/up-folder of the current editor's document. Some examples, where caret is shown as "|".

* Value "|end": All filenames.
* Value "ab|end": Filenames beginning with "ab".
* Value "bar/foo/|end": All filenames, from subfolder "bar/foo".
* Value "../foo/bar/ab|end": Filenames beginning with "ab", from relative folder "../foo/bar".

[[File:cudatext-complete-filenames.png]]

To use auto-completion of CLASS= and ID= names (ie suggest mentioned names for partially typed names), you need the plugin "HTML Completion".

====Special CSS auto-completion====

Lexer CSS (see the option "autocomplete_css_lexers") has its special logic, which is built-in in CudaText. It uses data files in the folder "data/autocompletespec".

* Caret is on CSS property name, inside {} brackets. Listbox shows list of properties (beginning with typed value).
* Caret is after CSS property (with fixed set of values) and ":", inside {} brackets. Listbox shows list of values for that property (beginning with typed value).
* Caret is after tag name with char "@". Listbox shows list of CSS at-rules.
* Caret is after tag name with char ":". Listbox shows list of CSS pseudo-elements, beginning with ":" and "::".

====File URI auto-completion====

File URI is file path in the form like 'file://localhost/dir/filename' or 'file:///dir/filename' (host name 'localhost' is often missed).
On Windows URI can look like 'file:///c:/dir/filename'.

CudaText supports auto-completion for file URIs, when caret is on 'dir/filename' part,
and file path exists on local user's PC.

[[File:cudatext-complete-fileuri.png]]

Auto-completion behaviour for this case is described in the
[[#Special_HTML_auto-completion|topic about HTML completion]], see "folders/filenames completion".

== Code Tree ==

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

[[File: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)".

[[File:cudatext-console.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 be added to dropdown history.
* Double-click on memo lines starting with ">>>" repeats entered command (after ">>>" symbols).

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

<syntaxhighlight lang="python">
from cudatext import *
ed.bookmark(BOOKMARK_CLEAR_ALL, 0)
ed.bookmark(BOOKMARK_SET, 10)
</syntaxhighlight>

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

== Command Palette ==

Command Palette is a dialog which shows all embedded and external (plugin) commands in a single list. To call it, use hotkey Ctrl+Shift+P (or alias hotkey F1). To configure hotkey for some command in Palette, focus this command in listbox and press F9 - additional dialog will appear. CudaText remembers last chosen listbox item in the history file.

Command Palette (and menu-like dialog in Python API) has the filter field. Filter supports fuzzy search, if the option "ui_listbox_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 "<font color=red>f</font>ile: <font color=red>op</font>en file"
* "gttb" matches "<font color=red>g</font>o<font color=red>t</font>o <font color=red>t</font>ext <font color=red>b</font>egin"

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

Screenshot shows two Command Palette calls with some filtering: one when the "fuzzy" is on, and another when it's off.

[[File:cudatext-fuzzy-and-normal.png]]

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

Command Palette lists all internal CudaText commands, all plugin commands (prefixed with "plugin:"), all lexers (prefixed with "lexer:"), and currently opened files (prefixed with "opened file:"). Filter field allows to type hash symbol "#" followed by a letter, to make filtering by category:

* #p - plugins
* #l - lexers
* #f - opened files
* #r - recently used files

You can type those "hash tags" at begin or end of the field, even without separating space. E.g. "bar#p" will show only plugin commands containing "bar", "#f.md" will show only Markdown files (with .md extension).

==Regular expressions==

Lexer parser uses EControl regex engine. You use this regex syntax only in the "Lexer Properties" dialog in SynWrite, not in the CudaText normal usage. EControl regex has custom features:

* classes \A, \Z: begin/end of document
* lookahead/lookbehind can find match of variable length
* modifier (?r): treat \w as all national characters too
* modifier (?g): greedy

CudaText search/replace uses [https://regex.sorokin.engineer/en/latest/regular_expressions.html TRegExpr engine] (by Sorokin, later improved by Alexey Torgashin).

* To refer to regex groups in the regular expression itself, in the "Find what" field, use syntax \1 ... \9 (and \0 for entire match).
* To perform replacements with groups, in the "Replace with" field, use syntax $1 ... $9 (and $0 for entire match).

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

==Output/Validate panels==

These lists allow to highlight (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 highlighted, 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

==Dialog Find/Replace==

Find/Replace dialog has hotkeys, which work only when this dialog is focused. Hotkeys can be customized via options "find_hotkey_nnnn".

* 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 (multi-line mode is activated by "+" button)
* 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
* Alt+Q: Extract

[[File:cudatext-find-dlg.png]]

Option buttons have hotkeys too. Hover mouse over them to see floating tooltips about button functions.

* ".*" - Regular expressions - Alt+R
* "aA" - Case sensitive search - Alt+C
* "w" - Search for whole words only, ie both sides of found match must be "word boundaries" - Alt+W
* "O" - Wrapped search: search from beginning after reaching the end (with forward search), and search from end after reaching the beginning (with backward search) - Alt+N
* "[..]" - Search in selection only - Alt+X
* "+" - Toggle multi-line mode for both dialog input fields (to add a newline in multi-line fields, press Ctrl+Enter) - Alt+M
* "?!" - Show confirmation on each replace - Alt+Y
* "*" - Choose allowed syntax elements: Any / Only comments / Only strings / Only comments+strings / etc. This feature must be supported by lexer (and some lexers are limited, support only "comments" or only "strings" syntax elements). Syntax element is detected from left edge position of a found match.
* "Hi" - Find and highlight all matches for the current search options. Matches are highlighted in the current editor, with the rounded borders, using the color of "SeparLine" syntax theme item. This highlight is updated on changing the "find what" text, so it is incremental. Editor auto-scrolls to the first found match (pretty much like ST3 editor). The limitation of this feature: a highlighted match has the single font color for the entire match, so if a match lays over several syntax tokens (e.g. number, dot, normal word), the entire match will have the single font color anyway. This "Hi" button is disabled, when current document has too many lines, see the option "find_hi_max_lines".

Action buttons in dialog:

* Button "|<". Starts the search from document beginning, ignoring the caret position.

* Button ">". Finds next match, ie continues search forward.

* Button "<". Finds previous match, ie continues search backward.

* Button "...". Shows menu with additional actions:
** "Count all". Count all matches and show the number in the statusbar.
** "Extract RegEx matches". It's enabled only with RegEx option. Finds all matches, all found matches are put to an internal  list, list is sorted, duplicates are discarded, and list is put to a new document. Plugin "Extract Strings" does the same task but using the Python RegEx engine.
** "Select all". Finds all matches in a document and places multi-seletions on them.
** "Mark all". Finds all matches in a document and places [[#Markers]] on them.

* Button "Replace". If some fragment was found/selected already, it replaces this fragment (by contents of "Replace with" field). If not, it finds next fragment and selects it. If replacement was performed, it finds/selects the next fragment.

* Button "Rep all". Performs replacement of all matches in the current document.

* Button "Rep global". Performs replacement of all matches in all opened documents in all editor groups. After showing the additional confirmation.

===Text searcher features===

Search engine supports actions with multi-selections. This makes sense mainly for mass-search actions (Find all, Select all, Mark all, Replace all).

Search engine has the feature, which is rarely implemented in text editors. When invoked on text selection(s) with the option "Search in selection only", engine doesn't place caret+selection on found match, instead it places marker ([[#Markers]]). The marker is placed with the underline (triangle with a line to the left), which shows the length of the found match. Actions "Find next"/"Find previuos"/"Replace" support "in selection only" too, they move that mentioned marker. Note that this feature checks the presence of a single marker in text, it may not work OK if you have some markers already placed.

[[File:cudatext-find-markers.png]]

Second click on the "Search" sidebar button toggles dialog between Find and Replace modes.

==Dialog "Go to"==

Dialog allows to enter text in formats:

* 10 (decimal number): Jump to given line number (to line start)
* 10:10 (two decimal numbers): Jump to given line and column numbers
* 10% (decimal with trailing "%"): Jump to percents of total line count
* d100 (decimal with leading "d"): Jump to absolute decimal offset
* xFFF (hex number with leading "x"): Jump to absolute hex offset
* value with trailing "+": Extend selection to this position, ie, enlarge previous selection so it overlaps the new position

Also it is possible to show Go To dialog by clicking the statusbar's first cell.

==Sessions==

"Session" is a set of opened documents, with properties of each document.
CudaText sessions are stored in JSON files with .json and .cuda-session extensions.
Default session file name is "history session.json" in the "settings" folder.
CudaText shows name of current session in its window title like "filename.txt {session_name} - CudaText".

Program has options:

* "ui_reopen_session": Save last session on closing, and restore it on start.
* "ui_reopen_session_cmdline": Allow to restore last session even if some file/folder was passed in the command line (or from the Windows Shell Extension). Note, this gives weird behaviour: N program instances will reopen the same last session + passed command-line file. So this option is mainly for the single instance mode.
* "ui_auto_save_session": On program closing, save current session without asking.

If some session is opened, program stores document states, on program closing, to session file.
If no session is opened, program stores document states to "history files.json" in the "settings" folder.

Session file contains data:

* List of named documents (file names), and unnamed documents
* For each document:
** kind of document: text in editor, picture file, text in viewer (and viewer mode: text/binary/hex/unicode)
** read-only state
** first caret position
** encoding
** word-wrap mode
** lexer
** bookmarks
** index of top visible line
** tab size and "tab as spaces" state
** minimap and micromap visible state
** ruler visible state
** non-printable characters visible state
** line numbers visible state
** scale factor
** list of folded ranges (if lexer supports folding)
** color of ui-tab (if not default)
** tab title (if not default)
** modified state
** code-tree filter string and history of last filters
** splitting to 2 editors: on/off, vertical/horizontal, percents of size
* For each modified document: date of modification, full document text
* Layout/sizes of side panel and bottom panel
* Layout/sizes of editor groups
* Index of active editor group and active tab in each group

Plugin "Session Manager" is present in Addon Manager, it gives commands to control sessions:
open session file, save session, show list of recent sessions, etc.
Session Manager also supports files from SynWrite, with .synw-session extension.

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

[[File:cudatext-charmap.png]]

== Tab switcher ==

CudaText has option "ui_tab_switcher_dialog", which activates modern tab switcher for Ctrl+Tab hotkey. This is dialog which allows to switch tab using visit history. For example: press Ctrl, Tab, Tab, Tab, release Ctrl: this goes 3 steps back in the visit history. Visit history is updated on tabs activation (activated tab moves to the top of history).

Dialog lists documents from all tab-groups, with prefixes: "[3-1] /home/user/filename.cpp" for 1st tab in 3rd group.

[[File:cudatext-tab-switcher.png]]

Alternative way is plugin CudaExt. Plugin gives the command "Choose tab to switch to". You need to assign hotkey Ctrl+Tab to this command (hotkey will be removed from built-in tab switcher). Plugin's dialog is richer than CudaText's dialog: it allows to switch to Console/Output/Validate panels, it allows to cancel the operation.

* When plugin's switcher is called with pressed Ctrl-key, it shows the dialog. 
* When plugin's swithcer is called without Ctrl-key pressed, it immediately switches to previous tab. 

[[File:cudatext-tab-switcher-cudaext.png]]

==Minimap==
Minimap is wide vertical bar near editor's right side (it can be shown on the left side too, by the option). To show it:

* Set the option "minimap_show" (show permamently)
* Use menu item "View / Toggle minimap" (show temporary, for the current document only)

If you drag mouse over minimap, editor will scroll entirely from top to bottom, even for huge documents (mimics Sublime Text behaviour).
Text in minimap is painted by pixels, not by font rendering. Minimap is scaled according to CudaText UI, but can be scaled separately too (option "minimap_scale"). Screenshot shows 2 windows with different minimap scale.

[[File:cudatext-minimap.png]]

==Micromap==
Micromap is thin (about 12 pixels) vertical bar near editor's right side. It is not scrollable, it shows overview of entire document from top to bottom. To show it:

* set the option "micromap_show" (show permanently)
* use menu item "View / Toggle micromap" (show temporary, for the current document only)

Micromap shows tiny colored marks:

* wide+tall mark: current visible area of editor
* on the left side: line-states marks ([[#Line_states]])
* on the right side: marks for selections (made e.g. by "Find / Select all", usually blue)
* on the right side: marks from Spell Checker plugin (usually red)

[[File:cudatext-micromap.png]]

Plugins can place marks on micromap, e.g. plugin "Highlight Occurrences" places marks for highlighted fragments, plugin "Spell Checker" places marks for misspelled words.

== 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 also all UI elements hide (gutter, statusbar, toolbar, sidebar, side panels). No option currently to configure which elements hide.

Notes:

* In the Distraction-free mode, app uses option "centering_for_distraction_free" to center the text visually. If you want this centering w/o Distraction-free mode, use the option "centering_width". 
* On macOS full-screen modes hide the top menu bar. To show it w/o returning back, just move the mouse cursor to the top of the screen and hold there for few seconds.

==Python integration==
===Python on Windows===
On Windows, Python engine (currently 3.6) is preinstalled. CudaText finds files "python3*.dll" in its folder, and uses file with the latest version number. No options are used to configure this.

You can use not only version 3.6. From CudaText's Addon Manager, install appropriate package, e.g. "Windows_Python37_64bit", and restart the program.

Python engine requires Visual C++ Redistributable for Visual Studio 2015 (32-bit or 64-bit, same as CudaText). Download it from Microsoft site.

Note for Windows 7. You also need the Update for Universal C Runtime in Windows (KB2999226). Download it from the Microsoft site.

===Python on Windows XP===
You need CudaText 1.122.0 or newer, and you must install (from Addons Manager) the package named "Windows Python34 32bit". No options are needed to configure, but you need to delete all newer Pythons from CudaText folder:
                                                                                                   
* python*.dll - must be deleted
* python*.zip - can be left as is
* *.pyd - can be left as is

===Python on Linux, BSD, Solaris===
Linux/*BSD/Solaris version uses Python library from OS. Install Python 3.x (usually already installed). Instruction, if Python library was not automatically used:

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

Or use the terminal command:

 $ find /usr -name 'libpython3.*so*' 2>/dev/null

* If not found, install Python 3.x, and search again.
* Set option "pylib__linux" ("pylib__freebsd", "pylib__solaris") in the "user.json" config, to one of the found filenames. Write option to the "user.json" or course, not "default.json".

Typical value for Solaris 11.4 x86:

   "pylib__solaris" : "/usr/lib/amd64/libpython3.5m.so",

===Python on macOS===
On macOS you must install Python 3, from official site python.org. Versions 3.6...3.9 are ok. CudaText will detect this Python. CudaText has option "pylib__mac" with such default value (actual version number is auto-detected):

   "pylib__mac": "/Library/Frameworks/Python.framework/Versions/3.5/lib/libpython3.5.dylib",

If you use Homebrew to install Python on MacOS, CudaText cannot detect it,
so you need to write to the "user.json" option "pylib__mac" by hands. Example:

   "pylib__mac": "/usr/local/Cellar/python@3.9/3.9.1_3/Frameworks/Python.framework/Versions/3.9/lib/libpython3.9.dylib",

If you use "virtualenv" from Anaconda with isolated Python, CudaText cannot detect it, so you need to write to the "user.json" option "pylib__mac" by hands. Example:

   "pylib__mac": "/miniconda2/envs/py3/lib/libpython3.7m.dylib",

Note: Please remember to change your version in the variable string to match the version you have installed.

==Line states==

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

* normal lines (not changed since last saving)
* changed lines (edited since last saving)
* newly inserted/added lines

[[File:cudatext-line-states.png]]

Line states help to see which lines were edited since the last opening of a file / last saving of a file. CudaExt plugin gives few commands for line states:

* "Jump: to next/previous changed lines"
* "Jump: to next/previous working lines"
* "Jump: to next/previous saved lines"

==How to change icons==

Screenshot with icons of main toolbar, sidebar, Project Manager toolbar:

[[File:cudatext_all_icons.png]]

* Icons in the main toolbar. To change them:
** (Optional) Install add-on(s) of kind "toolbar theme" (each add-on gives additional icon set or several sets).
** Change option "ui_toolbar_theme" in user.json. Option value is some subfolder in [cudatext]/data/toolbaricons.
** Restart CudaText.

* Icons in the sidebar (vertical band on the left). To change them:
** (Optional) Install add-on(s) of kind "sidebar theme".
** Change option "ui_sidebar_theme" in user.json. Option value is some subfolder in [cudatext]/data/sideicons.
** Restart CudaText.

* Icons in the Project Manager toolbar. To change them:
** (Optional) Install add-on(s) of kind "proj toolbar theme".
** Change option in the dialog: Options/ Settings-plugins/ Project Manager/ Config.
** Restart CudaText.

* Icons in the Project Manager file list, and on file tab headers. To change them:
** (Optional) Install add-on(s) of kind "file type icons".
** Change option in the dialog: Options/ Settings-plugins/ Project Manager/ Config.
** Restart CudaText.

==Toolbar==
CudaText has toolbar on the top, which can be shown by menu item "View / Toggle toolbar".

[[File:cudatext-toolbar.png]]

To customize it, install plugin "Config Toolbar" from Addon Manager. Plugin gives command (menu "Plugins / Config Toolbar / Customize buttons") to customize toolbar contents: simple buttons, buttons with dropdown menus, separators,  icons for buttons.

Plugin also gives command "Hide standard buttons" which allows to hide default CudaText buttons from toolbar. This command shows input box for space-separated indexes of buttons. What are these indexes? Indexes are 0-based numbers of all toolbar items: first button (New File) is index 0, next item (dropdown near New File) is index 1, next item (Open File) is index 2, etc (all separators also have index). So for example, to hide 3rd + 10th items, enter "2 9" into that input box.

==Configurable statusbar==

Statusbar is fully configurable: you can change order/visibility of cells, width and alignment of cells. Option "ui_statusbar_panels" configures set of cells. Predefined cells are:

* Caret(s) info. Click on it shows Go To dialog.
* Encoding name. Click on it shows menu to change encoding of document.
* Line ends characters. Click on it shows menu to change line-ends in entire document.
* Lexer name. Click on it shows lexers menu.
* Tab-char size. Click on it shows menu to change current document tab-size, change "tab as spaces", etc.
* Text insert/overwrite mode (toggled by Ins key)
* Mouse selection mode: "-" for normal mode, "||" for column mode (mouse dragging makes column selection even without Alt+ key)
* Word-wrap mode: off, wrap at window edge, wrap at fixed margin
* Message from program or plugins (usually it's last auto-sized cell)

The cell "carets info" shows value of one of options:

* "ui_statusbar_no_sel": Used when there is no selection
* "ui_statusbar_small_sel": Used when there is single-line selection
* "ui_statusbar_str_sel": Used when selection is multi-line
* "ui_statusbar_col_sel": Used for column-selection mode
* "ui_statusbar_carets": Used when 2 or more carets are placed

In the above "ui_statusbar_" options, macros are supported:

* {y}: line index of first caret
* {y2}: line index of last caret
* {yb}: line index of first selection beginning
* {ye}: line index of first selection ending
* {x}: column index of first caret, tab-chars counted as 1
* {xx}: column index of last caret, tab-chars expanded
* {count}: total number of lines
* {carets}: total number of carets
* {sel}: number of lines affected by selection(s)
* {selchars}: number of selected characters, for all kinds of selections
* {cols}: number of columns in column selection
* {char}: character at first caret (empty if no char)
* {char_dec}: character at first caret - decimal code (empty if no char)
* {char_hex}: character at first caret - 2...4-digit hex code (empty if no char)
* {char_hex4}: character at first caret - 4-digit hex code (empty if no char)
* {_ln}: localized string "Ln"
* {_col}: localized string "Col"
* {_sel}: localized string "sel"
* {_linesel}: localized string "lines sel"
* {_carets}: localized string "carets"

Also the option exists to change the delay for showing messages in statusbar. Plugin API allows to colorize statusbar cells (used in Vim Mode plugin), and to show icons there.

==File viewer==
CudaText has internal file viewer, for files on unlimited size. Only visible portion of file is loaded into memory, so viewer is fast for all files. Viewer has several modes:

* Text: 1-byte encoding, variable line length
* Binary: 1-byte encoding, fixed width (line breaks are ignored)
* Hex: 1-byte encoding, fixed width
* Unicode: like Text, but in UTF-16 encoding
* Unicode/Hex: like Hex, but in UTF-16 encoding

[[File:cudatext-viewer-hex.png]]

CudaText suggests to use viewer for files of too big size (bigger than option "ui_max_size_open"). And for files with binary contents.

[[File:cudatext-viewer-asking.png]]

Viewer has simple search support (without reg.ex.), and allows to use "Go to" dialog. In the "Go to" dialog, you can enter "2000" to jump to hex offset 0x2000 (in hex mode, rounded to 16 bytes). If you enter "50%", viewer will jump to the middle. Viewer supports selection of block by mouse, and hotkeys Ctrl+A, Ctrl+C. Viewer supports double-click to select whole word.

In viewer mode, you can click statusbar fields:
* Encoding field. You can change viewer encoding only in non-Unicode modes.
* Mode field, to change view mode: Text, Binary, Hex, Unciode, Unicode/Hex.

==Pair brackets==
CudaText has built-in pair bracket finder. Before that you needed the plugin Bracket Helper, and now plugin should not be used - it is much slower that built-in code. Bracket finder can highlight pair brackets, when there is only single caret, no selection. It finds symbols "()[]{}<>" (configurable per lexer). Bracket finder respects lexer context, it skips symbols inside syntax comments/strings. If caret is placed not directly on/after a bracket, program will find nearest surrounding brackets.

There are several options:
* "bracket_highlight"
* "bracket_symbols" (includes only symbols ()[]{} by default, but you can enable symbols <> for example in HTML lexer specific config)
* "bracket_distance"
* "auto_close_brackets"

There are several commands in the Command Palette:
* brackets: pair highlight: on
* brackets: pair highlight: off
* brackets: pair highlight: toggle
* brackets: jump to pair
* brackets: select to pair
* brackets: select to pair, inside (it makes selection smaller by 2 characters)

==Word jump commands==
CudaText provides several word-jump commands, see them in the Command Palette by entering "go to word":

* go to word next
* go to word next + select
* go to word next, simple
* go to word next, simple + select
* go to word previous
* go to word previous + select
* go to word previous, simple
* go to word previous, simple + select
* go to word end
* go to word end + select

"Go to word next" vs "Go to word end"? "...end" first jumps to the end of the current word (right word boundary), only after that it jumps to the next word start. "...next" always jumps to the next word start.

For example, Windows 7 Notepad performs "...next" on pressing Ctrl+Right, while Sublime Text 3 performs "...end" on pressing Ctrl+Right. To configure Ctrl+Right (and Shift+Ctrl+Right) behaviour, re-assign this hotkey from one command to another - press F9 in the Command Palette dialog.

"Go to word next" vs "Go to word next, simple"? "...simple" command performs simplified jump, it treats all alpha-numerical characters and symbols (#$%^&@ etc) as one group, so it makes single jump over "test@#some!" string. "Go to word next" treats alpha-numericals and symbols as different char groups, and stops at the beginning of each group.

Plugin CudaExt provides such related commands:

* Cuda-Ext: Jump: Left into CamelCase/snake_case
* Cuda-Ext: Jump: Right into CamelCase/snake_case

==Sorting and finding duplicate lines==
CudaText has two sorting methods.

Method 1: Python plugin "Sort", which supports Undo for its commands. It works not fast and takes lot of memory on sorting. It cannot sort huge files, because it reads all file contents from Pascal buffer to Python buffers.

Commands in menu "Plugins / Sort":

* Sort ascending
* Sort descending
* Sort ascending, ignore case
* Sort descending, ignore case
* Sort dialog... (shows all sorting options in dialog)
* Reverse lines
* Shuffle lines
* Remove duplicate lines
* Remove duplicate lines, but keep blanks
* Remove duplicate lines + origins
* Remove adjacent duplicate lines (ie nearest repeated lines)
* Extract duplicate lines (put duplicate lines to a new document)
* Extract duplicate lines, ignore case
* Extract unique lines
* Remove blank lines
* Remove adjacent blank lines
* Ini file: sort sections and keys
* Ini file: sort sections, but not keys
* Sort e-mail list by domain (lines should be valid email addresses to sort them by domain)

The advantage of "Sort" plugin is that is has additional commands (for duplicate lines, for ini files, for e-mails).

Plugin has config file, you can edit it via menu item "Options / Settings-plugins / Sort". In section [sort] you can change option "allow_all" to 0 or 1 to disable/enable sorting of entire document, if nothing is selected. If selection exists (single selection), plugin handles selected lines.

Method 2: Pascal-based sorting commands, which are named like "(without undo) Sort...". They clear current Undo (ie user cannot undo sorting operation), but they are optimized for speed and memory. Commands don't read document contents into additional buffers, they sort document in-place (changing pointers only). So they work with all files which CudaText can load.

Commands in Command Palette:

* (without undo) sort ascending
* (without undo) sort ascending, ignore case
* (without undo) sort descending
* (without undo) sort descending, ignore case
* (without undo) delete all blank lines
* (without undo) delete adjacent blank lines
* (without undo) delete all duplicate lines
* (without undo) delete adjacent duplicate lines
* (without undo) reverse lines
* (without undo) shuffle lines

==Markers==

"Markers" are text positions which are shown with red (color in default theme) triangles below them.
CudaText gives such commands in the Command Palette:

* "markers: drop marker at caret": Adds a marker on current caret position.
* "markers: go to last marker (don't delete)": Moves caret to the last placed marker without deleting it.
* "markers: collect last marker (delete)": Moves caret to the last placed marker and deletes it.
* "markers: remove all": Removes all markers in the current document.
* "markers: swap caret and last marker": Moves caret to the last placed marker, deletes this marker, and adds marker on the previous caret position. Command is to jump to the last marker, second command call jumps back, 3rd command call jumps back, etc.
* "markers: select to last marker": Makes text selection from caret position to the position of last placed marker.
* "markers: delete to last marker": Deletes text from caret position to the position of last placed marker.

Markers are utilized by the Snippets plugin.

[[File:cudatext-markers-html.png]]
 
Snippets plugin finds tab-stops in the inserting snippet text, and places markers for them.  
After markers are placed by Snippets plugin, Tab-key works in special way - it runs command "collect last marker", ie it jumps to the next marker ("next" by the order of tab-stop: 1, 2, 3... tab-stop 0 is the last). When user collects all markers by Tab-key, this special mode deactivates and Tab-key works as usual again. Command "markers: remove all" also deactivates that mode.

==Dialog "Save tabs"==

Dialog "Save tabs?" shows on CudaText closing, if at least one document is modified and not saved to disk.
Dialog lists all modified file-tabs (usually one file per one file-tab, but it's allowed to have 2 files in a single file-tab). Checkmarks (all checked by default) are used to check/uncheck file-tabs which will be saved on pressing "Save" button. For untitled documents to be saved, program will show "Save as" prompts.
Button "Don't save" closes dialog and program, loosing modifications.
Button "Cancel" closes the dialog, but not the program.

CudaText has the option "ui_reopen_session". When it is true, dialog "Save tabs?" shows additional button: "Don't save / Keep in session", which doesn't save disk files, but stores modified documents to active "session" file. Program will read it on start.

Also CudaText gives the command "dialog: save tabs" in the Command Palette. It shows the same dialog, the difference is that buttons do not close the program.

==Hex display of special chars==

Editor shows some characters in a "hex form", like "x2000" for character U+2000. For codes below 0xFF, hex form is shorter, like "x01". If single-byte encoding is used (e.g. cp437), then only codes below 0xFF will be shown. Hex form is painted with different font color.

[[File:cudatext-hex-chars.png]]

Special characters are:

* U+0000...U+001F, except Tab-char U+0009
* U+2000...U+200F: white spaces + specials
* U+2028...U+202F: white spaces + specials
* U+2066...U+2069
* U+0085
* U+061C
* U+FEFF

==Tabs features==

Control of UI tabs is named ATTabs, and has many features:

* Pseudo-tab "+" at the end. Option "ui_tab_show_plus".
* Scrolling arrows on the left, to scroll tabs left/right when there are lot of them and they don't fit by width. Thin scrolling indicator auto-appears on the top (default color is red).
* Drop-down arrow on the right side, to show menu of all tabs in the current group.
* Tabs can be placed on all 4 sides. Option "ui_tab_position".

[[File:cudatext-tabs-left_.png]]

* Layout of arrows is customizable. Option "ui_tab_button_layout". Button "+" is available, to replace "+" pseudo-tab, this button is always visible (pseudo-tab can be scrolled away). Button "x" is available, to close current tab.

[[File:cudatext-tabs-layout.png]]

* Tabs can be multi-line (height of all tabs is limited by 2/3 of window height). Option "ui_tab_multiline".

[[File:cudatext-tabs-multiline.png]]

* Tabs can have fixed or variable width. Option "ui_tab_variable_width". Minimal/maximal width of fixed tabs is customizable.
* Tabs can be shaped/bordered, or can be flat. Option "ui_tab_flat". Flat tabs are painted with additional colored underline for the active document.

[[File:cudatext-tabs-flat.png]]

* Tabs can be dragged by mouse: inside original group or to another groups (use "=" top menu item). And can be moved to specified group index using tab context menu items "Move tab to group n".
* Program can be used without tabs at all. Options "ui_tab_show" and "ui_tab_disabled".

* Tabs can be colored, by calling tab's context menu, and "Set tab color..." menu item. Internally, it calls plugin cuda_palette to choose the color, then color is applied. Plugin dialog has several modes (even simplest mode named "60 colors" is enough). By default, only thin line at the edge of tabs is colored, but you can colorize the entire tab using CudaText option "ui_tab_fullcolor". Coloring is saved to session (tab color is usual property of editor).

[[File:cudatext-tab-colors.png]]

==Show pictures in the text==
CudaText gives the plugin API to show pictures between the text lines.
These spaces between lines are called "gaps".
Plugin "Insert Pics" exists to show picture files in gaps,
it saves pictures in the "helper files" (using Base64 encoding) 
near the original text file. It looks like this:

[[File:cudatext-insert-pics.png]]

* You can use any lexer for files with pictures.
* You can add the unlimited number of pictures. But only one picture per "gap".
* You can add/delete pictures later, using plugin's commands in menu "Plugins / Insert Pics".
* When you delete the "helper file" (located in the same folder), all pictures will be lost for plugin.

==Activating internet links==
CudaText allows to activate internet links (URLs) and e-mails (e-mail can be with the 'mailto:' and without it).
This feature needs that links are automatically underlined in the editor.
After the double-click on an underlined link, editor shows small button over the link 
(button with caption "Open link" or "Send e-mail"), and clicking on this temporary button activates the link.

[[File:cudatext-click-link.png]]

This works with the default values of 2 options:

* "links_regex": it must include RegEx, which detects and underlines links
* "mouse_click_links": it gives choices:
** don't activate links by clicks
** activate by single click
** activate by double click

==HTML color codes underlining==
CudaText can colorize HTML color codes, which have these forms:

* #abc
* #abc0
* #aabbcc
* #aabbcc00
* rgb(100, 200, 100)
* rgba(100, 200, 100, 0.5)
* hsl(0, 100%, 50%)
* hsla(0, 100%, 50%, 0.5)

Two options configure this feature:
* "underline_color_files": Specifies which file extensions are supported by the feature.
* "underline_color_size": Specifies the size of colored block in the editor area. It can be simple underline below the color code, or a background highlighting. Background highlighting can be in 2 variants: for entire text, for the fragment inside brackets.

Screenshot shows all 3 variants in different CudaText windows:

[[File:cudatext-color-underline.png]]

=Add-ons=

==Python API==
See [[CudaText API|Wiki page about Python API]].

==Major plugins Wiki==
See [[CudaText plugins|Wiki page about major plugins]].

==Entire plugins list==
See the [https://github.com/halfbrained/cudatext_plugins_list GitHub repository]
with the readme and links about almost all published plugins.
You can make Pull-Request there, if needed.

==Kinds of add-ons==

* "plugins". Extensions with Python code. They add events and/or commands. Commands can be called then via "Plugins" top menu, but only if plugin's install.inf file doesn't hide menu items in "Plugins". In any case, all commands can be called via Command Palette dialog.

* "lexers". Syntax highlighting files. For ex, Arduino lexer adds item "Arduino" to the lexer menu. Some addons can add 2 or more lexers, for ex "HTML nnnnnn" addons often add 2 lexers: one is visible in the lexer menu, another one is hidden (it supports embedded blocks).

* "linters". Sub-plugins 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.

* "formatters". Sub-plugins for CudaFormatter plugin. Each supports one or several lexers and can reformat source code for these lexers. Examples: Python ReIndent, JS Sort Imports, AStyle Format.

* "tree helpers": Plugins which show Code Tree structure for some lexer (useful if language is complex, and lexer cannot handle all language complexity).

* "snippets". Collections of text fragments, for Snippets plugin. Install Snippets plugin first. Each addon supports some lexer(s). See details in the [[CudaText_plugins#Snippets]].

* "translations". 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". UI/syntax themes for the "Options / Color themes" menu. UI themes change colors of CudaText interface. Syntax themes change colors of words in syntax highlighted files.

* "sidebar themes": Icon sets for the sidebar (vertical row of buttons on the left side).

* "toolbar themes": Icon sets for the main toolbar (horizontal row of buttons on the top).

* "toolbar x icons": Icon sets for plugin "Config Toolbar", for user-added buttons.

* "file type icons": Icon sets for the "Project Manager" file list. Most popular lexers have icons here.

* "code tree icons": Icon sets for the Code Tree (icons are visible in the Code Tree with some lexers, e.g. C#).

=Tech topics=

==Program perfomance==

===Startup time===

CudaText starts quite fast: about 0.3 sec with about 30 plugins (all preinstalled + some popular plugins), on Linux, on CPU x64 Intel Core i3 3Hz.

If no additional plugins are installed, or Python engine is disabled (ie not configured on Unix, or Python DLL files are deleted on Windows), then it starts even faster.
If configuration/history are clean, it starts faster.
If bottom panel is hidden on start, via option "ui_bottom_on_start":2, it starts faster.

===Perfomance of loading huge files===

It's interesting how fast Linux editors open huge log files.
Test file has about 300M size, 4M ASCII lines, it's created by Python script:
<syntaxhighlight lang="python">
f = open("a.log", "w")
for n in range(4*1000*1000):
    k = 120-n%100
    f.write(str(n+1)+' '+chr(k%26+ord('a'))*k+'\n')
</syntaxhighlight>

PC is HP Pavilion g6, CPU AMD A10 x64, 4 cores, RAM 8G, Ubuntu 18.04. Each time is average of 2-3 tries in the same session.

* CudaText 1.98: 9 sec.
* Sublime Text 3.2: 11.5 sec.
* Geany 1.32: 6.5 sec., jump to end: additional 4-5 sec.
* Kate 17.12.3: 7 sec.
* gedit 3.28.1: 1 min 10 sec.
* Vim 8.0, NeoVim 0.2.2: 3 sec.
* Emacs GUI 25.2.2: 2 sec., after showing confirmation for big file
* Bluefish 2.2.10: 24 sec.

===Perfomance on huge lines===

It's interesting how some Linux editors handle huge lines. Tested several editors on Ubuntu 19.10 on Intel i3 CPU. With XML file with a single line of length 4M. XML file contains line like <id name="nnnnnnnnnnnnnnn"> with the huge "name" value of 4M.

Python script to generate test file:

<syntaxhighlight lang="python">
#!/usr/bin/python3
f = open("a.xml", "w")
f.write('<id name="')
for n in range(1, 4096):
    f.write("n" * 1024)
f.write('">\n')
</syntaxhighlight>

*    CudaText 1.96. Opens file: 1.5sec. Caret moves at the end of line: very fast (<0.1sec). Editing of this line: adding each char is about 0.5sec.

*    Sublime Text 3.2. Opens file: 2sec. Caret moves at the end of line: each Left/Right arrow is 0.5sec delay. Editing of this line: not fast.

*    Geany 1.35. Opens file: about 10sec, then for next 5-10sec I cannot place caret by mouse, then it works. Caret moves at line begin: fast, caret moves at line end: slow (delay 0.5sec after each Left/Right key). Editing at the end: adding each char is about 6sec.

*    Kate 19.04. Gives colored panel "The file ... was opened and contained lines longer than ... The lines were wrapped and document is set to read-only mode...". Caret moves at the end of wrapped doc: fast. Editing is disabled.

*    gedit 3.34. Hanged on opening file (from command line and from editor), waited it for 20sec.

*    Vim 8.0. Opens file: 2-3sec. In word-wrapped mode. Caret moves at the end of line: each Left/Right command (Vim hotkeys) is 2sec delay. Editing of this line: adding each char is about 3sec.

*    Emacs 26.3 GUI. Opens file: 1sec. In word-wrapped mode. With the statusbar error "Internal error in rng-validate-mode triggered at buffer position 10. Stack overflow in regexp matcher". Pressing Ctrl+End to move to end: editor hanged with "wait" cursor.

*    Bluefish 2.2.10. On opening file, gives the warning about too long lines, on choosing "don't split lines" it hanged, waited for 30sec.

===Perfomance of built-in sorting===

Test on ~100M text file with short ASCII lines.
Test on Ubuntu 19.10 on Intel i3 CPU.

CudaText 1.97:
* sort time: 18sec
* sort time with ignoring case: 19sec
* memory used after file loading: ~1.0G
* peak memory used on sorting: the same (inplace sorting in the same list)

Sublime Text 3.2:
* sort time: 14sec
* sort time with ignoring case: 16sec
* memory used after file loading: ~1.3G
* peak memory used on sorting: ~3.3G

==Encoding detection==

Encoding detection works by this pseudo-code:

<pre>
  // Corresponding source code is in repository ATSynEdit, file atstrings_load.inc,
  // procedure DoDetectStreamEncoding and procedure TATStrings.DoLoadFromStream

  if file_size > 50M then
    return(UTF8)
  
  if file_has_signature(UTF8) then
    return(UTF8)

  if file_has_signature(UTF32_LE) then
    return(UTF32_LE)

  if file_has_signature(UTF32_BE) then
    return(UTF32_BE)

  if file_has_signature(UTF16_LE) then
    return(UTF16_LE)

  if file_has_signature(UTF16_BE) then
    return(UTF16_BE)

  if option "def_encoding_utf8":true then
    enc = UTF8
  else
    enc = ANSI // OS depentant
   
  detect = file_detect_utf8_content
  // it can get 3 values: 
  //     Unknown (only ASCII chars present)
  //     Yes (correct UTF8, non-ASCII, chars present)
  //     No (broken UTF8 chars present)
  if detect == Yes then
    return(UTF8)
  if detect == No then
    enc = ANSI

  if file_detect_by_python_standard(detect) then
    return(detect)

  if file_detect_utf16_content(detect) then
    return(detect)
  
  return(enc)
</pre>

UTF-8 content detection works by first 8K of file.
UTF-16 content detection works by first 5K of file.
If encoding was detected as UTF8, the file loader checks the content again (the entire file size now) for UTF8 chars correctness, and if it finds "not correct UTF8 chars", encoding will be changed to ANSI.

ANSI maps to one of real codepages, it depends on current Windows locale. On non-Windows OS, ANSI maps to cp1252.

What is "detect by python standard"? It is detection [https://docs.python.org/3/reference/lexical_analysis.html#encoding-declarations by this standard]. Encoding name is searched by RegEx in the first 1-2 lines of file, if they are comment lines. Comments of these kinds are supported: // # ; --. For simplicity, comment chars are skipped, ignoring current lexer, so it works for all files and all lexers.

==How to open files in a new tab instead of a new window==

Option "ui_one_instance" controls it, so change it to 'true' (without quotes, in "user.json").
This option is here for several years already, but people are asking this question again and again (forum, GitHub, Linux forums).
Seems the term "instance" is not known very good, people cannot find this option easily.

==How to compile CudaText==

Install FPC and Lazarus:

* [https://github.com/newpascal/fpcupdeluxe/releases download FpcUpDeluxe]. On Windows, you must unlock .exe file in the Windows Explorer dialog. 
* in FpcUpDeluxe, choose FPC 3.0.4 or 3.2.0, install it first.
* in FpcUpDeluxe, choose Lazarus 2.0 or "trunk", install it next.

Modern way for app sources.

There is [https://github.com/Alexey-T/CudaText_up Linux script CudaText_up] - it downloads sources to ~/cudatext_up, then calls Lazarus to compile them. You can use it with FPC cross-compilers, installed from FpcUpDeluxe, script will compile CudaText for any of available platforms. Without cross-compilers, script makes CudaText only for the current platform. It puts result to ~/cudatext_up/bin.

Old way for app sources.

* download GitHub repos:
** https://github.com/bgrabitmap/bgrabitmap (install first)
** https://github.com/Alexey-T/Python-for-Lazarus
** https://github.com/Alexey-T/ATFlatControls
** https://github.com/Alexey-T/EncConv
** https://github.com/Alexey-T/ATSynEdit (install after ATFlatControls and EncConv)
** https://github.com/Alexey-T/EControl (install after ATSynEdit)
** https://github.com/Alexey-T/ATSynEdit_Ex (install after EControl)
** https://github.com/Alexey-T/ATSynEdit_Cmp
** https://github.com/Alexey-T/ATBinHex-Lazarus
** https://github.com/Alexey-T/Emmet-Pascal
** https://github.com/Alexey-T/CudaText (no package here, only project)

* install .lpk packages into Lazarus (find all .lpk files, open them in IDE, install from Packages dialog)
* in the Lazarus component palette, you should see:
** "AT Controls" tab: TATButton, TATButtonsToolbar, TATListbox, TATScroll, TATSynEdit, TATLabelLink, TATGauge
** "Python" tab: several items
* in Lazarus, open "cudatext.lpi" project, compile it

==How to install plugins from GitHub==

First, you need to know GitHub repository (repo) URL of plugin. For example, https://github.com/kvichans/cuda_find_in_files . If you have plugin already, then you can see this URL in the plugin's install.inf (line "homepage=").

Next, call CudaText menu item "Plugins / Addons Manager / Install from GitHub". Enter URL in the suggested dialog. Addons Manager will install latest version from GitHub. Addons Manager supports all branch names ("master", "main" and others), it will show menu of branch names if there are several branches in the repo. The repo must have correct file "install.inf" in the root, otherwise Addons Manager may not detect the plugin in the repo.

After you entered the URL, Addons Manager shows messagebox:

 GitHub repository can be cloned (using "git clone") or can be downloaded as zip file.  If you clone, Addon Manager's Update dialog will update add-on using "git pull", which is recommended.
 Buttons: Cancel / Download as zip / Clone repo.

Better to choose "Clone repo" here, this will allow to update plugin directly from GitHub. Choosing the "Download as zip" is ok, but you cannot update plugin from GitHub, you can update plugin only from the released versions from SF.net.

==How to simply install many add-ons==

* In the dialog "File / Open file", you can multi-select files in list - with Ctrl+click (on Windows) or Shift+arrows.
* Use command "Plugins / Addons Manager / Download all", which saves all addons zip files to some folder. When done, install many addons from this folder using "File / Open file" multi-selection.
* There is [https://sourceforge.net/projects/cudatext/files/addons_all/ this page] with zipped collection of all addons, but it is updated not often.

==How to make translation==

Translation template file is in the folder "data/lang".
The template file cannot be activated from "Options / Translations".
How to prepare the translation zip package:

* make the file "nn_NN.ini" (UTF-8 with BOM)
* use standard locale names in filename, e.g. ru_RU pt_PT ja_JP (this is needed for plugins which use Python translation API)
* write your contacts in the 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 "&" char as is, duplicate it as "&&".
* note: Linux Ubuntu font is about 1.3 times wider, than on Windows

* make the file "install.inf" with such text:

<syntaxhighlight lang="ini">
[info]
title=LangName translation (by AuthorName)
type=cudatext-data
subdir=lang
</syntaxhighlight>

* make the zip file "translation.nn_NN.zip", it must contain files nn_NN.ini, install.inf
* test this zip file: open it in CudaText via "File / Open", and check it's installed
* publish this zip file, at CudaText forum or at GitHub issues https://github.com/Alexey-T/CudaText/issues
* if package is OK, it will be at SourceForge downloads, and in Addon Manager

==How to make translation of Plugins menu==
CudaText supports translation of Plugins menu items. For example, you have plugin with module cuda_nnn, which has "install.inf" with such menu items:

<syntaxhighlight lang="ini">
[item1]
...
caption=MyPlugin\ItemOne
...
[item2]
...
caption=MyPlugin\SubMenu\ItemTwo
...
</syntaxhighlight>

Then you need to create files like "ru_RU.ini" in the folder "data/langmenu/cuda_nnn". Create folder "langmenu" inside "data" if it's absent. Files must be in UTF-8 no BOM encoding. They must have section "menu". All items in the ini-file are optional.

<syntaxhighlight lang="ini">
[menu]
MyPlugin=local name
ItemOne=local name of item
ItemTwo=local name of item
SubMenu=local name of menu
</syntaxhighlight>

To distribute those translation(s), make zip file like "langmenu.MyPlugin.zip", which must have "install.inf" and folder "cuda_nnn" (you can put more folders, for several plugins, if you want so). Install.inf contents:

<syntaxhighlight lang="ini">
[info]
title=Translation of menu items of MyPlugin
type=cudatext-data
subdir=langmenu
</syntaxhighlight>

Submit that zip file to CudaText GutHub page, or post it to the forum.

==Color themes==
There are two kinds of themes:

* 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 least on JavaScript/HTML/CSS/C/Pascal/Ini/Markdown lexers. On what files to test:
** You can use sample codes in the Lexer Properties dialog.
** You can use sample files from https://github.com/Alexey-T/lexer_tests/tree/master/test_CudaText_color_themes
* New theme files are saved in the subfolder "data/themes"

Don't configure custom lexer styles in the Lexer Properties dialog, if option "ui_lexer_themes" is on (usually it's on), because syntax-theme will override all your colors from that dialog. You can configure colors there, if option is off.

===How to create theme package===

* Make such file "install.inf":

<syntaxhighlight lang="ini">
[info]
title=MyName UI theme (by AuthorName)
type=cudatext-data
subdir=themes
homepage=https://github.com/nnnn/pppp
</syntaxhighlight>

* 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 no lexer active
* "statusbar alt" - shown on 2nd statusbar, run in console: <syntaxhighlight lang="python">msg_status_alt('dd', 8)</syntaxhighlight>
* "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: <syntaxhighlight lang="python">ed.set_prop(PROP_MARKED_RANGE, '5,10')</syntaxhighlight>

* "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

===Meaning of syntax-theme elements===

* Id: Normal id (identifier) or text.
* Id1: Special id, used e.g. for class names (when it is mixed-case id) or const names (when it is upper-case id).
* Id2: Special id, used e.g. for syntax constants (true, false, null...) and standard functions (sin, abs, max...).
* Id3: Special id, used e.g. for measurement units (mm, Kb, px...) and preprocessor directives.
* Id4: Special id, rarely used, e.g. Python uses it for function names after "def".
* IdKeyword: Special id, used for syntax keywords.
* IdVar: Variables, e.g. $name in PHP and Bash.
* IdBad: Incorrect/misslepped id.
* String: String literals.
* String2: String literals, used e.g. for RegEx constants.
* String3: String literals, one more kind, rarely used.
* Symbol: Non-word symbols, ie brackets/punctuation/etc.
* Symbol2: Non-word symbols, used when syntax needs another style for e.g. assignment/math operators.
* SymbolBad: Incorrect non-word symbols.
* Comment: Comments.
* Comment2: Comments, used when syntax needs another style of comments, e.g. shebang in Bash.
* CommentDoc: Documentation comments, ie comments which are parsed by special tools.
* Number: Numbers (decimal, hex, octal, floating...).
* Label: GoTo operator labels, or another special id.
* Color: Color constants, like #RRGGBB in HTML/CSS.
* IncludeBG#, SectionBG#: Styles which have background color set, and foreground color unset (none). Used to highlight function blocks, sub-lexer blocks, parts of a file, etc.
* BracketBG: Style with background+foreground colors. Used to highlight paired brackets, begin/end keywords, repeat/until keywords (when "dynamic highlighting" option is on) etc.
* CurBlockBG: Style with background color set, foreground color unset. Used to highlight block under caret, when "dynamic highlighting" option is on.
* SeparLine: Color of horizontal 1-pixel separator lines. Was used before in Pascal, for lines above functions.
* TagBound: HTML tags: angled brackets.
* TagId: HTML tags: tag names.
* TagIdBad: HTML tags: incorrect tag names.
* TagProp: HTML tags: properties/attributes of tags, before "=" char.
* TagPropBad: HTML tags: incorrect props/attrs of tags.
* TagInclude: Tags used for inclusion of sub-lexer blocks. Used e.g. in PHP, <? ?>.
* LightBG#: Styles with bright background color, and normal foreground. Used e.g. in Diff to highlight deleted (LightBG1) / changed (LightBG2) / added (LightBG3) text blocks.
* Pale#: Styles with pale (barely visible) foreground color. Rarely used.
* TextBold: Style with bold font.
* TextItalic: Style with italic font.
* TextBoldItalic: Style with bold+italic font.
* TextCross: Style with crossed/strikeout font.

==How to copy word under caret to clipboard==

A1: Install "Macros" plugin. In its dialog start recording a macro, and call these commands using "Command Palette":

* command "selection: select words at carets"
* command "clipboard: copy"
* command "selection: cancel selection"

Then assign a hotkey to this macro (in the "Command Palette", find your new macro and press F9).

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

It's good to use these commands with hotkeys Alt+Left and Alt+Right (assign it in the "Command Palette").

==Unix specific topics==

===How to reinstall missed files===

Sometimes it's needed to reinstall missed files, e.g. when you have deleted some lexers from "Lexer library" dialog.
Simple re-run of .deb installer works, but it will not reinstall deleted data-files. Why? App has copy of its data-files in ~/.config/cudatext (see the topic about location of data+settings dirs). Binary (not deb installer!) makes this copy - only when binary version is not equal to the version stored to settings/packages.ini, "app" section. After you delete that "app" section, and run the binary (not deb installer), binary will refresh files from /usr/share/... to ~/.config/cudatext/...

===Difference between gtk2/qt5/etc versions===

Versions for gtk2/qt5/etc are compiled for different widget-sets, all functions are the same.

* Different widget-sets make different look of native UI controls (e.g. buttons - but only native buttons, note that Find/Replace dialog has not native buttons), native scrollbars, native File-Open/Save dialogs.
* Different widget-sets need different value of "ui_buffered*" option. So one value of "ui_buffered__linux" is OK for gtk2, while may be worse for qt5.

So far, different widget-sets are supported for Linux only.

===Linux keyboard input is 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.

===How to use middle-click paste on Linux===

* Set option "mouse_mid_click_paste" to true (in user.json).
* Consider to install plugin "Auto-Copy to Clipboard", which emulates Linux editors behaviour: copying to clipboard by simple text selection (no need to use hotkey Ctrl+C).
** This plugin has options to copy selection to a) usual clipboard, b) GTK primary selection (CudaText GTK builds only)

=== Linux installation ===
To support .deb package installation, program performs copying of its files, from .deb installation folder to the settings folder. Ie, when binary "cudatext" (it can be in any folder, e.g. in /usr/bin) starts, it checks, if "data/lexlib" exists near the binary, and if not, it copies folders "py", "data", "settings_default" from .deb installation folder to "~/.config/cudatext" (default location of settings, it can be changed by command line option). Program does this not always, it reads the "settings/packages.ini", and checks there [app] "ver" value. If value not equals to the binary's hardcoded version, program does that copying. So copying occurs once, after .deb package was upgraded.

It's not needed in most cases, but on Linux you can "install" the program, so that "cudatext" will be runnable from Terminal. The "installation" is:

* unpack CudaText archive (.xz) to some temp folder
* copy file "cudatext" to /usr/bin
* copy folders "py", "data", "settings_default" to "~/.config/cudatext"
* delete that temp folder

When you run "cudatext" (from /usr/bin), settings folder "~/.config/cudatext/settings" will be created automatically.

=== Arch Linux packages ===

The GTK2 and Qt5 binaries can also be installed via the AUR if you are on an Arch Linux based system:

* https://aur.archlinux.org/packages/cudatext-gtk2-bin/
* https://aur.archlinux.org/packages/cudatext-qt5-bin/

=== Linux Qt5 build ===
For CudaText Qt5 version, library libQt5Pas is required.

* For Ubuntu:

 $ sudo apt install libqt5pas-dev

* For Fedora:

 $ sudo yum install qt5pas

===App cannot run on FreeBSD===

If you run app in Terminal, you'll see an error about missing .so file. Reason of this error: FreeBSD version was compiled on Linux with different .so files. To fix error, run command in Terminal:

 $ sudo ln -s /usr/local/lib/libiconv.so.2 /usr/local/lib/libiconv.so.3

==How to select extra symbols by double-click==

Some languages consider special symbols as word-chars. For example, in PHP, "$" symbol is part of a variable name, so double-click should select "$" together with other word-chars. Follow these steps to add extra symbols (e.g. "$") to word-chars.

* Open new file-tab, activate your lexer (click the lexer-cell in the statusbar)
* Call menu item "Plugins / Options Editor"
* In the Options Editor dialog:
** Select item of option "nonword_chars", read the description about this option in the bottom
** Your lexer name must be pre-selected in the combobox on the dialog bottom
** Check the checkmark "For: lexer", so that your option will go to the lexer-specific config
** Enter new value of the option "nonword_chars" now. Copy/paste the value from the "Default" field, and remove some special symbols from that value.
** Press Enter-key in the input field. Value must appear in the list of options in the "Lexer" column.
* Close Options Editor, restart the program

What does this procedure do? It creates (or modifies) file "[CudaText]/settings/lexer LexerName.json" to be like this:

<syntaxhighlight lang="JSON">
{
  "nonword_chars": "-+*=/\\()[]{}<>\"'.,:;~?!@#%^&|`"
}
</syntaxhighlight>

==How to upgrade but keep all the settings==

* Q: CudaText for Windows. How can I upgrade but keep all the settings the way I have configured them - including themes, icon sets, etc (basic settings I could just copy the settings file over - but I'm not sure what to do for the icons and the rest...)

* A: Copy all files from the zip package, overwriting old files. All user settings are located in "settings" (which is absent in the zip package) and "data" (in different files). If you did not modify CudaText preinstalled files, you will not loose any settings.

==How to customize top menu and context menu==

Plugin "Configure Menu" (in Addon Manager) allows to change top menu and context menu. Plugin can create file (settings/menu.json) with default menu configuration, which you edit to customize all menus. File has items like:

 ,{"cap":"&Save", "cmd":"cmd_FileSave"}

How to add here built-in commands? See identifiers of CudaText commands in the file "py/cudatext_cmd.py", they have prefixes cCommand_ (low level commands) and cmd_ (high level commands). For example, cmd_FileSave is the command to save current file.

How to add here plugin commands? For example, you have plugin "Comments", it is in the folder "py/cuda_comments". See plugin's file install.inf, and there find needed Python functions names. Then write  item like this:

 ,{"cap":"Toggle line comment", "cmd":"module=cuda_comments;cmd=cmt_toggle_line_body;"}

Here "cuda_comments" is folder name, and "cmt_toggle_line_body" is Python function from install.inf.

==How to help the author to reproduce a bug==
Bugs are often cannot be reproduced on author's PC because of different "user config", "lexer-specific configs", plugins configs.
To help the author, make the ZIP file with CudaText folder, add your test file(s) there too, and send this ZIP to e-mail support(@)uvviewsoft.com .

What CudaText folder to pack?
* On Windows: the folder where you copied the program. Exclude files EXE DLL PYD ZIP from ZIP.
* On macOS: ~/Library/Application Support/CudaText.
* On Linux, other Unixes: ~/.config/cudatext, or $XDG_CONFIG_HOME/cudatext if this OS variable is set.

Make the bug reproducable on your CudaText folder on your test file(s). Put your test file(s) in ZIP too. If needed to reproduce the bug, create the [[#Sessions|session]] using Session Manager plugin (bug may be visible only with some session). Put session file in ZIP too (usually it's already in the "settings" subfolder).

==Behaviour of column selection==

CudaText gives two modes of column selection, which have differences when you select over wrapped lines, or lines with full-width characters. This is controlled by the option "carets_primitive_column_sel".

* Value "true": "pritimive mode" which behaves much like Sublime Text. In this mode editor places multi-selections over visual rectangle of characters. In this mode, one line can have 6 chars selected, and another line can have 8 chars selected. This depends on visual positions of chars in those lines.

* Value "false": in this mode, all affected lines have the same number of selected chars. But when full-width chars (e.g. CJK) are present in text, selection may look weird. Here is an example picture where starting lines are ASCII and ending lines have full-width chars.

[[File:cudatext-column-sel-cjk.png]]

It is not a bug. In this example, user selected column block from column 7 (at line 1) until column 20 (at line 6), so column block takes columns 7...20 from all lines. On first ASCII lines, columns 7...20 take different visual area, than columns on last lines. When you copy/paste that block to another program, block may look differently. But that block contains equal number of chars on each line.

Even more weird look happens when user selects column block over word-wrapped lines.

[[File:cudatext-column-sel-weird.png]]

Here is the program's logic in all these cases (with full-width characters and with word-wrapped lines). Program calculates (line1, column1) text position of column block left-top edge. Then program calculates (line2, column2) text position of column block right-bottom edge. Then program selects characters in range column1...column2 in all those affected lines line1...line2. And this program logic produces so weird look in word-wrapped mode.

==How to replace from/to text containing line-breaks==
There are several ways to perfrom it:

1. The simplest way: set multi-line mode in the Find/Replace dialog, using "+" button. Input fields will become tall and multi-line. To enter line-breaks there, press Ctrl+Enter.

2. Use plugin CudaExt:
* Select fragment in editor (can contain line-breaks), "what to replace" .
* Copy to clipboard the fragment (can contain line-breaks), which will be "replacement".
* Call command in CudaExt plugin: "Replace all occurrences of selected string with clipbrd".

3. Search for selected editor text (can contain line-breaks) using command "find current selection, next".

4. Copy fragment (can contain line-breaks) which you need to find, to clipboard. Call command in CudaExt plugin: "Find clipbrd: next".

==How to create macros and call them via toolbar==

Q: I've used Boxer Editor for over a decade. Its strength is you can create macros that can be assigned to buttons that you can place onto the toolbar. I don’t know of any other text editors that can do that. ?

This can be done in CudaText like this:

* Install plugin "Macros". Restart CudaText.
* Use new menu "Macros" in the top menu, to record some macro(s). This will create command(s) "plugin: Macros: ..." in the Command Palette.
* Install plugin "Config Toolbar".
* Call config dialog via "Plugins / Config Toolbar / Configure buttons". In that dialog, add a button. In the button properties, choose your recorded macro command ("Choose command" button). This will add toolbar button for your macro. Customize this button as you wish (any icon, caption, tooltip).

=Troubleshooting the Windows shell extension for CudaText=

There may be rare cases where CudaText's menu item shows up in Windows Explorer context menu but the entry's icon is missing and an error message states that the provided file name was not found.

==File sets information==

If you download a 32 bit version of CudaText, you will notice that there are two sets of files belonging to the shell extension.

Set 1 consists of these files:

* CudaText_shell32.dll
* install_shell32.cmd
* uninstall_shell32.cmd

Set 2 consists of these files:

* CudaText_shell64.dll
* install_shell64.cmd
* uninstall_shell64.cmd

Since 32 bit versions of CudaText can be run on both 32 bit and 64 bit versions of Windows, two sets of files are needed. Use set 1 if you run CudaText on a 32 bit version and set 2 if you run it on a 64 bit version of Windows.

The download package of CudaText 64 bit contains only set 2 since this version can only be run on a 64 bit version of Windows.

'''Please note:''' It is ''not'' possible to install the 32 bit version of the shell extension on 64 bit Windows or vice versa.

==Common information==

The context menu item works for all types of files, folders, disk drives, desktop links to these items, the desktop background and the background of an Explorer window showing a folder's content. Other kinds of right-clicked items don't show the context menu item.

The context menu entry's icon is extracted from the file "cudatext.exe", the absence of the icon indicates that "cudatext.exe" wasn't found by the shell extension. That's also the reason for the error message mentioned above.

==Fixing installation error==

'''Please note:''' In the following only the 64 bit version of the shell extension running on 64 bit Windows is dealt with. If you want to install the 32 bit shell extension on 32 bit Windows you have to select the appropriate file names.

In case a suitable item has been right-clicked and the icon is missing from the context menu item, it is possible to install the shell extension manually. To do that please follow the steps below.

At first ensure that all the files

* cudatext.exe
* CudaText_shell64.dll
* install_shell64.cmd
* uninstall_shell64.cmd

are stored in the same folder.

Start a Windows console with administrative permissions. If you don't know how to do that search the internet to learn it.

Use the "CD" command to navigate to the folder where the above files are stored (it should be your CudaText folder). You should end up with a command prompt that looks for example like this:

 C:\cudatext>

Type the following command into your console window and hit Enter:

 regsvr32 /u "<Path-to-CudaText-folder>\cudatext_shell64.dll"

This uninstalls the failing shell extension. You should see a confirmation message that indicates a successful deregistration of the DLL.

Close all programs and log off or restart Windows. Login in again and ensure that the CudaText context menu item has disappeared.

Start a Windows console with administrative permissions again and use the "CD" command to navigate to your CudaText folder (the folder where the above files are stored).

Type the following command into your console window and hit Enter:

 regsvr32 "<Path-to-CudaText-folder>\cudatext_shell64.dll"

You should see a confirmation message that indicates a successful registration of the DLL. Check the Explorer context menu to see if there is a CudaText menu item that has an icon. Right click for example a *.txt file and select "Open with CudaText" from the context menu.


=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, source code repository URL (usually on GitHub)
* "api" field, optional, minimal required API version (3 numbers dot-separated)
* "os" field, optional, comma-separated list of supported platforms, described below

===Install.inf supported "os" values===

Value of "os" field is comma-separated list of platforms (no spaces around commas).
Each platform is supported OS name, with optional trailing "-" and CPU family name.

OS names are:

* win
* linux
* macos
* freebsd
* openbsd
* netbsd
* dragonfly
* solaris
* haiku

CPU families are:
* i386
* x86_64
* arm
* aarch64
* sparc
* ppc
* ppc64
* mips

So for example Windows x86 platform values are "win" and "win-i386", Linux AMD64 platform values are "linux" and "linux-x86_64".

===Install.inf for plugins===

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

<syntaxhighlight lang="ini">
[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
</syntaxhighlight>

Section names: "item" followed by any string (e.g. "item1"). Fields in sections:

* "section": possible values are "commands", "events".
* "caption": caption of menu item in Plugins menu. "\" separates menu levels. "&" makes accelerator hotkey. "-" as final level name, makes separator menu item.
* "method": Python method name in Command class.
* "lexers": comma-separated lexer names, means that command can be run only when such lexer(s) active.
* "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.
* "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".

Only for "section=events":

* "events": comma-separated list of events to handle in plugin, e.g. "events=on_change,on_caret".
* "keys": supported only for several events:
** for "on_key": comma-separated list of int key codes to handle in event, e.g. "keys=9" means that event is only called for key code 9 (Tab char).
** for "on_open" / "on_open_pre": comma-separated list of lower-case file extensions, without leading dot, to handle in event.

====Install.inf sidebar buttons====

CudaText can show plugin's sidebar buttons even without running the plugin in "on_start" event.
Plugin should add sections "sidebar*" ("*" means any substring), with the keys:

* "hint": Tooltip of button, must be the same as used by plugin to create its button.
* "icon": Filename of PNG icon. If path is missed, CudaText uses file from its "data" folder. To specify filename in plugin folder, write value as "{dir}/subdir/filename.png" - with macro {dir}, with forward slashes.
* "method": Python method name to show plugin panel. This command should create side panel for this button.

Plugin should add sections "bottombar*" ("*" means any substring) to perform the same, but for the bottom part of sidebar, where buttons "Console" and "Output" are placed.

====Install.inf 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:

<syntaxhighlight lang="ini">
[info]
$var=Name1,Name2,Name3
</syntaxhighlight>

In [itemN] sections set lexers like this:

<syntaxhighlight lang="ini">
[itemN]
lexers=$var
</syntaxhighlight>

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:

<syntaxhighlight lang="ini">
[info]
$var=regex:.*SQL.*
</syntaxhighlight>

===Install.inf for 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".

<syntaxhighlight lang="ini">
[info]
title=NiceDarkTheme
desc=Nice Dark theme (by AuthorName)
type=cudatext-data
subdir=themes
</syntaxhighlight>

===Install.inf for 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.

<syntaxhighlight lang="ini">
[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
</syntaxhighlight>

===Install.inf for lite lexers===

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

<syntaxhighlight lang="ini">
[info]
title=MyLexer
type=lexer-lite
subdir=-
</syntaxhighlight>

==Format of .cuda-lexops files==

Files keep lexer styles, which user changed in the "Lexer Properties" dialog. JSON format.

Root keys:
* "files": str: space-separated list of file masks for lexer. Each mask can be "nnn" for extension .nnn, or "/mmm" for full filename mmm.
* "style_NN" for each lexer style name "NN", which user have changed. Subkeys are:
** "font_color": str: color of font, in Pascal format.
** "font_style": str: several chars: "i" for italic, "b" for bold, "s" for strikeout.
** "back": str: color of background, in Pascal format.
** "brd_c_l", "brd_c_r", "brd_c_t", "brd_c_b": str: color of border (left, right, top, bottom), in Pascal format.
** "brd_t_l", "brd_t_r", "brd_t_t", "brd_t_b": int: type of border (left, right, top, bottom). Values 0..9: None, Solid, Dash, Dot, DashDot, DashDotDot, Solid2, Solid3, WavyLine, Double.

Color in Pascal format: hex number (6..8 digits) with "$" prefix, or constants. See possible constants (with hex values) in Lazarus file Graphics.pp, where string 'clBlack' is defined. https://github.com/graemeg/lazarus/blob/upstream/lcl/graphics.pp

==More==

=CudaText vs Sublime Text, different answers to questions=

==How to call external programs/compilers?==

ST3: Use feature of editor called "build systems".

CudaText: Use plugin "External Tools", which adds "Tools" item to the top menu, with dialog to add/configure programs and URLs.

==How to change settings for one OS only?==

ST3: You need to use platform-specific config files. E.g. for macOS, platform-specific config is "Preferences (OSX).sublime-settings".

CudaText: You need to use the config user.json, but write there options with OS specific suffixes. E.g. Windows option is "font_name", and macOS option is "font_name__mac". Possible suffixes are listed in default.json: __linux, __mac, __freebsd etc. Only limited count of options support OS suffixes, this is marked in the default config (default.json).

==How to change settings for one syntax only?==

ST3: To edit syntax-specific config, call "Preferences / Settings - Syntax Specific".

CudaText: To edit lexer-specific config, see [[#Configs]]. 

==How to add commands to top/context menu?==

ST3: You need to create *.sublime-menu files: https://www.sublimetext.com/docs/3/menus.html#available_menus

CudaText: You need to install plugin "Configure Menu". In its dialog, create "menu.json" file which has default items of top menu and context menu. Then edit that file.

==How to find/replace text in many files?==

ST3: Use built-in command "Find in files".

CudaText: Use plugin FindInFiles. It has 2 major versions: v3 is frozen, and new v4 is evolving.

==How to find file in a project?==

ST3: Use "Goto Anything" (Ctrl+P on Windows/Linux, Command+P on macOS).

CudaText:

* To find file by name, use command "Plugins / Project Manager / Go to file...". After file is focused in project, press Enter to open it.
* To find file by contents, use plugin FindInFiles (v3) which allows to search in project files. Quote from its help:
<pre>
Set special value "<Project Folders>" (in short <p>) for field "In folder" to search in project files.
</pre>

==How to show vertical lines on some columns?==

ST3: Use option

 "rulers": [40, 80, 120],

CudaText: Use option

 "margin_string": "40 80 120",

==How to highlight pair brackets?==

ST3: Use plugin, e.g. https://packagecontrol.io/packages/BracketHighlighter

CudaText: Use several "bracket_" options, see in the "Options Editor" plugin.

==How to highlight pair HTML tags?==

ST3: Use plugin, e.g. https://packagecontrol.io/packages/BracketHighlighter

CudaText: Use options for "dynamic highlighting", "lexer_dynamic_" in "Options Editor" plugin.

==How to add custom syntax support?==

ST3: You need to create syntax file, https://www.sublimetext.com/docs/3/syntax.html

CudaText: You need to create lexer, see [[#Lexers]].

==How to customize hotkeys?==

ST3: You need to edit keybinding files like "Default (Windows).sublime-keymap".

CudaText: In the Command Palette dialog, focus needed command item, press F9 - additional dialog will appear to set the hotkey. Method 2: install plugin "Configure Hotkeys" which gives alternative dialog.

==How to use Emmet?==

ST3: Install plugin "Emmet". Emmet here is written in JavaScript.

CudaText: Use pre-installed plugin "Emmet". Emmet here is written in Pascal with minor differences (e.g. "lorem" works differently).

==How to show 2/3/4 files at once?==

ST3: Use "View / Layout" menu.

CudaText: Use "=" item in the top menu.

==How to split window for single file?==

ST3:

* menu "File / New View into File"
* menu "View / Layout / Columns: 2 (or Rows: 2)"
* drag the tab into another group

CudaText: menu "View / Split tab / Toggle split".

==How to detect syntax by first line of file?==

ST3: It's configured in syntax file: https://superuser.com/questions/752025/sublime-text-3-detect-syntax-based-on-file-header

CudaText: Use "file types config", see [[#File_types_config]].

==How to assign syntax to undetected file extension?==

ST3: Open your file, click statusbar item for syntax, use item "Open all with current extension as...".

CudaText: Use "file types config", see [[#File_types_config]].

==How to select several occurrences of a word?==

ST3: Use command "Selection / Expand selection to word".

CudaText: Use command "Selection / Add next occurrence of selected word".

==How to select all occurrences of a word?==

ST3: In the Find dialog, enter a word, check "whole words", press "Find All".

CudaText:

* In the Find dialog, enter a word, check "whole words", press "Select all".
* Plugin "Highlights Occurrences" gives command "Select all occurrences".

==How to record macros?==

ST3: Use menu items in the "Tools" menu.

CudaText: Install plugin "Macros", which adds item "Macros" to the top menu.

==How to use "Go to symbol"?==

ST3: Use menu item "Go to symbol".

CudaText: It doesn't have "Go to anything" but it has "Go to symbol" for a lexer, if lexer finds such symbols for Code Tree. Install plugin "CudaExt", which gives menu "Plugins / Cuda-Ext / Code Tree" with several menu items. One item is "Symbols list" which shows Code Tree items in the menu dialog.

==How to switch between C++ (for example) header/implementation files?==

ST3: Use command "Switch header/implementation".

CudaText: Use plugin "Switch Header" (it's configurable for all lexers).

==How to jump to next/previous modified lines?==

ST3: Use commands "Next modification", "Previous modification".

CudaText: Use plugin "CudaExt" which gives commands: "Jump: to next/previous changed lines", "Jump: to next/previous working lines", "Jump: to next/previous saved lines". See [[#Line_states]].

==How to detect indentation characters in a file?==

ST3: Menu item "View / Indentation / Guess settings from buffer".

CudaText: Plugin "Detect Indent" which does the same.

==How to change indentation characters in a file?==

ST3: Click statusbar cell "Tab size..."/"Spaces...", it has menu items "Convert indentation to spaces", "Convert indentation to tabs".

CudaText: The same as for ST3.

==How to install plugins without package manager?==

ST3: Open terminal, go to Packages folder, run "git clone" in that folder, or copy plugin there.

CudaText: Open terminal, go to "py" subfolder, run "git clone" in that folder, or copy "cuda_" plugin folder there.

==How to make vertical/column selection?==

ST3: See the official documentation page "Column Selection".

CudaText:

* Mouse shortcuts: [[#Mouse shortcuts]].
* Keyboard commands: "column select: up / down / left / right / ....".
* Click the statusbar cell "-", it will toggle to "||", and usual mouse selection will perform column selection. 

==How to swap line up/down==

ST3: Commands "Edit / Line / Swap Line Up/Down".

CudaText: Commands "Edit / Line operations / Move line(s) up/down".

==How to show menu of tabs, project files, symbols==

ST3: "Goto anything" (Ctrl+P) for all stuff.

CudaText:

* List of opened tabs: command "ui: switch tab, dialog".
* List of files in the current project: "plugin: Project Manager: Go to file".
* List of "symbols" in the current document: "plugin: Cuda-Ext: Code Tree: Symbols list" (shows the same symbols as code-tree can show).

==How to use 'atomic saving'==
'Atomic' file saving is saving to a temporary file, then renaming that file to the destination.
'Atomic' saving is not implemented in CudaText, because users of Sublime Text 3 consider it as harmful feature.

* It drops NTFS extended file attributes, on Windows (and Unixes too?)
* It drops NTFS file streams, on Windows
* Problems with files located on Network drives, on Windows
* Problems with symlinks
* It needs additional options like "on which drives to use atomic saving"

[[Category: CudaText]]
[[Category: Applications written in Free Pascal]]
[[Category: Applications created with Lazarus]]
[[Category: Tools]]
