= About =

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

* Syntax highlighting for 200+ languages ([http://sourceforge.net/p/synwrite/wiki/Lexers%20list/ full lexers list])
* Code folding
* Code tree (treeview with functions/classes/etc in the code)
* Multi-carets, multi-selections
* Search/replace with reg.ex.
* Supports many encodings
* Simple auto-completion (fixed list) for some lexers
* Extendable via Python plugins
* Command palette (Sublime style)
* Configs in JSON
* Made on [[ATSynEdit]] engine

Features for HTML/CSS coding:

* Smart auto-completion for HTML, CSS.
* HTML tags completion with Tab-key.
* HTML color codes underline.
* HTML tooltips on mouse-over.
* Viewer for pictures (jpeg, png, gif, bmp, ico).

Screenshot on Windows:

[[File:cudatext.png]]

Screenshot on macOS Sierra:

[[File:CudaText macOS Sierra.png]]

= Download =

* Homepage: http://uvviewsoft.com/
* SourceForge downloads: http://cudatext.sf.net
* GitHub repository: https://github.com/Alexey-T/CudaText

It has builds for Windows, Linux, Linux ARM (for Raspberry Pi 3), macOS, FreeBSD.

= Configs =

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

'''Lexer-specific config''': settings which are read when some lexer activates. E.g. if you open Pascal file, config for Pascal is read after user config (file "lexer Pascal.json"). You should not write "ui_" options to lexer-specific configs (it may give weird effects on changing lexer), and some other global options.

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

== 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
* -v, --version - Show application version
* -n - Ignore option "ui_one_instance", and force new app window
* -z=[text|binary|hex|unicode] - Open in viewer, with given mode
* -r - Open all files from command line in read-only mode
* -e=value - Open all files from command line in given encoding
* -el - Show possible encoding names
* -nh - Ignore saved file history (caret, selection, scroll pos)
* -w=left,top,width,height - Set position/size of app window, 4 numbers specified, any can be missed to keep previous value

Notes:

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

===macOS===

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

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

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

== Mouse shortcuts ==

Multi-carets:

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

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.

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.
* Ctrl+ drag-drop selected block - copy this block, instead of moving it.

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

===Clipboard commands with selections===

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

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

== Lexers ==

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

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

[[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 at sf.net ===

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

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

=== Lexers editing ===

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

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

Screenshot of SynWrite dialog:

[[File:synwrite-lexer-editor.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 2nd isn't visible in the Lexers menu, so it's called hidden). Users, which have option "ui_lexer_themes" off, want to configure styles of all lexers. How to access hidden ones?

* Open "Lexer library" dialog (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 make lexer hidden/visible, by using "Hide/Show" button in the "Lexer library" dialog.

===I have made new lexer - how to distribute it?===

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

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

===Lite lexers===

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

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

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

* SynWrite handles \S regex (non space chars) ok, while CudaText not
* SynWrite lexers need constructs like \x0D\x0A, or \z (EOL), while CudaText is ok with simple \n (CudaText text never has CR char)
* For CudaText avoid "system colors" in lexer styles (e.g. "window background", "window text", "hint background"), because OSes have different system colors
* SynWrite lexer settings are not used 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"

==Add-on types==

* "plugins". These are addons with Python code. They add python events and/or python commands. Commands can be called then via "Plugins" top menu, but only if plugin's install.inf file doesn't hide menuitems in "Plugins". For example, install.inf in CudaExt hides all menuitems in "Plugins". In all cases, all commands can be called via Commands (F1) dialog.

* "lexers". These are syntax hiliting support. For ex, Arduino lexer adds menuitem "Arduino" to the lexer menu. Some addons can add 2 lexers (or more), for ex "HTML nnnnnn" addons often add 2 lexers: one is visible in the lexer menu, another one is hidden (it supports embedded blocks hiliting).

* "linters". These are Python modules for CudaLint plugin. Each supports some lexer (or several similar lexers). To use them, install CudaLint plugin, open your work file, and call CudaLint commands: it calls appropriate linter and shows colored bookmarks on error/warning lines.

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

* "translations". These are CudaText UI translations. For ex, JP translation changes all menuitems + dialogs to JP language. Dialogs of plugins are not affected (but authors can support translation in their plugins).

* "themes". These are UI/syntax themes for the "Options - Color themes" menu. UI themes change colors of CudaText interface. Syntax themes change colors of words in syntax hilited files.

* "sidebar themes": These are icon sets for the sidebar (vertical bar on the left side).

* "toolbar themes": These are icon sets for the main toolbar (horizontal row of buttons).

* "toolbar x icons": These are icon-sets for plugin Config Toolbar, for new user-added buttons.

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

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

==Location of settings/data files==

When CudaText runs in portable mode (executable file is located near folder "data"), then portable folders are used. Otherwise:

In CudaText version 1.66 or older:
* Windows: %AppData%\CudaText
* Linux, macOS, FreeBSD: ~/.cudatext

In CudaText version 1.67 or newer:
* Windows: %AppData%\CudaText
* Linux, FreeBSD: ~/.config/cudatext, or $XDG_CONFIG_HOME/cudatext if variable set
* macOS: ~/Library/Application Support/CudaText

==Encodings==

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

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

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

Encoding names for command-line:

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

==Line ends==

Main types of line-ends are supported:

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

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

Mixed line-ends (LF with CR LF) in one file are supported. To see mixed line-ends, use app option "unprinted_content".

==Groups of tabs==

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

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

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

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

==Auto-completion==

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

Example for PHP lexer:

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

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

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

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

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

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

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

== 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_con.png]]

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

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

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

== Search in Commands dialog ==

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

* "fop" matches "<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 has normal search. Normal means that filter leaves only those listbox items, which contain all words from the filter (in any order).

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

[[File:cudatext cmd dlg.png]]

==Regular expressions==

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

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

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

===Change case on replaces===

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

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

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

Modifiers affect only element after them, element is:

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

==Snippets==

To use snippets you need:

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

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

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

Menu of Snippets plugin:

[[File:cudatext_snippets_menu.png‎]]

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

===Snippets for HTML tags===

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

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

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

==Output/Validate panels==

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

These panels have hotkeys:

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

==Dialogs Find/Replace==

Dialog has hotkeys:

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

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

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

==Dialog "Go to"==

Dialog allows to enter text in formats:

* 10: jump to given line number (to line start)
* 10:10: jump to given line and column numbers
* 10%: jump to percents of total line count
* d1000: jump to absolute decimal offset
* xFF00: jump to absolute hex offset

More allowed formats can be added by plugins.

==Comments==

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

* '''Line comments''': from some position to line-end. E.g. in C lexer: "//text here", in Python lexer: "# text here".
* '''Comments for range''' ('''Stream comments'''): from offset to another offset. E.g. in C lexer: "/* text here */".
* '''Comments for full lines''': from newline to another newline. Rarely used, e.g. used in PowerShell.

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

Comment chars are editable in SynWrite editor, in dialog "Lexer properties" (after you install the same lexer to SynWrite). In dialog tab "Commenting" you'll see input fields.

Command "Toggle stream comment" in plugin adds/removes comments of last 2 types: for range, for full lines (plugin chooses needed kind).

Comment chars are saved:

* Line comments: in lexer file data/lexlib/nnn.lcf.
* Range comments: in files data/lexlib/nnn.cuda-lexmap.

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

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

CudaText can do this via plugin CudaExt. It gives command "Choose tab to switch to" which shows dialog. You need to assign hotkey Ctrl+Tab to this command (hotkey will be removed from CudaText command).

==Minimap, Micromap==

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

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

Colored marks on micromap:

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

== Paste with middle-button-click ==

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

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

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

==Full-screen==

There are two menu items in the View menu:

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

Notes:

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

==Python integration==
===Python on Windows===
On Windows, Python engine (currently version 3.5) is preinstalled. Option "pylib" has default value like this: "python35.dll".

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

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

 "pylib": "python33.dll",

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

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

Terminal command:

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

* If not found, install Python 3.x, go to search-step
* Set "pylib__linux" in the "user.json" config, to one of the found filenames. Write option to the "user.json" or course - it is called by menu item "Options / Settings-user".

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

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

==Line states==

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

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

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

==Project Manager==

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

Plugin has context menu on its panel, with items:

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

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

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

===Preview tab===
To see preview tab, call "File - Open folder" and choose a folder with text files. Folder will open in the side panel "Project". Make single click on files in this panel, they will open in "preview tab". Single preview tab is shared by all clicked files in "Project". It has italic caption. When you begin to edit file in this preview tab, tab becomes "normal".

==CudaLint plugin==
CudaLint allows to check syntax of source code files. It was initially ported from SublimeLinter 2.x plugin for Sublime Text. It requires sub-plugins, "linters", for each lexer. When a linter works, it adds output lines to the "Validate" panel of CudaText, and puts yellow/red bookmarks on warning/error lines.

Linters are Python modules, in the "py" folder, with names "cuda_lint_"+something.

To support more lexers, it's a good idea to port linter from SublimeLinter. To port a linter, most you need is:

* Fix "imports" to use "cuda_lint" module, instead of SublimeLinter modules. cuda_lint gives almost the same classes which SublimeLinter gives. Except Node.js linter class - it's not supported yet. Usual Linter and PythonLinter classes are supported.
* Change syntax name (for Sublime Text) to CudaText lexer name, names are often different. If no such lexer for CudaText exists yet, ask for it.
* Remove in linter usage of Sublime Text API to read settings (often used in linters). You can add usage of settings via CudaText API ini_read, or via json module.
* If linter was using Node.js, take some code to run Node, from cuda_lint_csslint linter.

===Linters per project===
How to configure linters per project? In your project (Project Manager plugin), right-click root node of project treeview, call menu item "Project file / Project properties...". In this dialog, in the "Variablies" field, enter variable(s) like this:

 linter_css=csslint

Variable prefix "linter_" required, after goes lower-case lexer name (CSS). Value of variable must be name of linter's folder (in "py" folder) without "cuda_lint_". So if linter's folder is py/cuda_lint_aaa, specify value "aaa".

In this example, CudaLint plugin allows, for mentioned lexer CSS, only linter "csslint", even if another CSS linter (e.g. "csstree") is installed and found first.

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

==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 with variable line length
* binary: text with fixed line length (line breaks ignored)
* hex viewer (with fixed width)
* unicode (UTF-16) text with variable line length
* combined unicode+hex (with fixed width)

CudaText suggests to use viewer for files of too big size (bigger than option ui_max_size_open). And for files with binary contents. You cannot change viewer mode from UI, but can do it from plugin API.

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. Viewer allows to change encoding via statusbar click, but only in non-Unicode modes.

==External Tools plugin==

Several examples of external tools configs. Call dialog of External Tools plugin (menu Tools -- Config...). Add a new tool. Set dialog properties as shown below. This must add menu item, for new tool, under Tools menu.

===Tool to compile by GCC===

You can test how this tool works on any Linux, because GCC is preinstalled. Test the tool on C++ example, which is created from CudaText by menu "File -- New from template -- C++".

Properties:

* Name: C - compile
* File name: gcc
* Shell command: unchecked
* Parameters: "{FileNameOnly}" -o "{FileNameNoExt}"
* Initial folder: {FileDir}
* Lexers: C,C++
* Capture output: Output panel
* Encoding: utf_8

Optionally, configure "Pattern", so double click in the Output panel will put caret to the source code. Example of GCC error line in the Output panel, it will be handled by double click: "new.cpp:10:3: error: 'zz' was not declared in this scope".

* Pattern: (?P<file>[^:]+):(?P<line>\d+):(?P<col>\d+): .+

===Tool to run C program===

Tool is for Linux, so "File name" don't have an extension. For Windows, change "File name" field to "{FileNameNoExt}.exe".

* Name: C - run
* File name: "./{FileNameNoExt}"
* Shell command: checked
* Parameters: (empty)
* Initial folder: {FileDir}
* Lexers: C,C++
* Capture output: Output panel
* Encoding: utf_8
* Pattern: (empty)

===Tool to compile+run C program===

In the External Tools dialog, press Join button, to join 2 tools created in above steps. Properties of joined tool:

* Name: C - make+run
* Series: C - compile; C - run
* Lexers: C,C++


===Tool to run Python scripts===

Tool uses Python 3 installation on Linux. For Windows, change "File name" field to the full path to "python.exe" file. Also on Windows you may need to toggle checkbox "Shell command".

* Name: Python3
* File name: python3
* Shell command: unchecked
* Parameters: "{FileNameOnly}"
* Initial folder: {FileDir}
* Lexers: Python
* Capture output: Output panel
* Encoding: utf_8
* Pattern: \s*File "(?P<file>.+)", line (?P<line>\d+)

===URL for Google search===

This is URL, not tool. In the External Tools dialog, press URL button, then press Add to add a new URL.

* Name: Google find
* URL:
<syntaxhighlight lang="ini">
http://google.com/search?q={SelectedText|q}
</syntaxhighlight>

==more==

=Tech topics=
== Python API ==

Separate big page about Python API is [[CudaText API]].

==How to compile program==

There is Linux script CudaText_up https://github.com/Alexey-T/CudaText_up - it downloads all CudaText sources (several packages) into ~/cudatext_up, then calls Lazarus (better to use Lazarus "trunk" or at last 1.8.4) to compile them. You can use it with FPC cross-compilers, ie with FpcUpDeluxe, it will compile app for all platforms (which you specify in command line). Without cross-compilers, script makes CudaText only for the current platform. It puts result to ~/cudatext_up/bin.

And here is the old way:

* install FPC and Lazarus:
** download FpcUpDeluxe. Must unlock exe-file on Windows then. https://github.com/newpascal/fpcupdeluxe/releases
** in FpcUpDeluxe, choose FPC 3.0.2 (3.0.4) and Lazarus "trunk", install them both.
* download Github repos:
** https://github.com/Alexey-T/Python-for-Lazarus (install first)
** https://github.com/Alexey-T/ATFlatControls (install next)
** https://github.com/Alexey-T/ATSynEdit (install next)
** https://github.com/Alexey-T/EControl (install after ATSynEdit)
** https://github.com/Alexey-T/ATSynEdit_Ex (install after EControl)
** https://github.com/Alexey-T/UniqueInstance (install next)
** https://github.com/Alexey-T/CudaText (no package here, only project)

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

==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 "master" branch.

==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.
* To download without SourceForge lags, use this page: http://totalcmd.net/plugring/CudaText_addons.html , but page is updated not often.

==How to make translation==

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

* make file "nn_NN.ini" (utf-8 with bom)
* use standard locale names in filename, e.g. ru_RU pt_PT ja_JP (needed for plugins which uses Python translation API)
* write your contacts in first commented lines. Comments must begin with ";" at line start. Also you can add other comments.
* to set accelerator-chars for menus/dialogs, use "&" char (e.g. "Open &file"). If needed "&" as is, write "&&".
* note: Linux Ubuntu font is 1.3x times wider (than WinXP)

* make "install.inf" with such text:

 [info]
 title=LangName translation (by AuthorName)
 type=cudatext-data
 subdir=lang

* make zip file "translation.nn_NN.zip" with files nn_NN.ini, install.inf
* test this zip: open it in CudaText, and check it's installed
* publish zip at CudaText forum or https://github.com/Alexey-T/CudaText/issues
* if package ok, it will be at SF.net downloads, and in Addon Manager

==Color themes==
Two kinds of themes exist:

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

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

* Call dialog: "Options/ Settings - more/ Settings - theme - nnnnn"
* For UI themes: customize colors in dialog
* For syntax themes: customize lexer-styles in dialog
* For syntax themes: test theme at last on JS/HTML/CSS/C/Pascal/Ini/Markdown/Go lexers.
** 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 subdir "data/themes"

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

===How to make theme package===

* Make such file "install.inf":

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

* Make zip file "theme.MyName.zip" with files "MyTheme.cuda-theme-nnnnn" and "install.inf"
* Test zip file: open zip file in CudaText, confirm installation
* Publish file at forum or https://github.com/Alexey-T/CudaText/issues

===How to see all UI theme items===

* "editor, font" - color of font when no lexer is active. Click statusbar field with lexer-name, call "none".
* "editor, disabled state, font/bg" - editor shown with this bg-color when Replace dialog runs action, with option "confirm on replace" (during confirm message editor is disabled), if none lexer active
* "statusbar alt" - shown on 2nd statusbar, run in console: <syntaxhighlight>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>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

==How to use on Windows XP==

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

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

* *.dll
* *.zip
* folder DLLs

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

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

  "pylib": "python34.dll",

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

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

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

A2: Plugin CudaExt has commands:

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

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

==What SynWrite features not implemented==

* Sync-Editing, ie auto editing of name (identifier) in all places of selected block (sync range), w/o clicking each place of name
* Panel "Clips" from right side (CudaText has snippets w/o panel)
* Panel "Clipboard" from right side, which monitors copying to clipboard

==Unix specific topics==

===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 ===
On Linux you can install program, not using installers, in such way:

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

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

=== Linux Qt build ===
For CudaText Qt version, library libQt4Pas needed.

* For Ubuntu: run

  sudo apt-get install libqt4pas-dev

* For all: [[Qt_Interface#Quick_start_guide_for_Linux]]. You need to download binary from libQt4Pas homepage.

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

==More==

=Formats of files=
==Format of auto-completion acp file==

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

 Type Id |Hint
 Type Id (Param1; Param2; ...) |Hint
 Type Id (Param1; Param2; ...): ResultType |Hint

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

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

 #chars .-#

==Format of install.inf files==

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

* "title" field (required)
* "desc" field, long text for install prompt dialog
* "type" field (required) must be one of:
** cudatext-plugin: to install plugin to subdir of "py" dir
** cudatext-data: to copy any files into subdir of "data" dir
** lexer: to install lexers (zip must be made by SynWrite's ExLexer addon)
** lexer-lite: to install lite lexer

* "subdir" field (required)
** for plugins it should begin with prefix "cuda_"
** for lexers it should be "-"
* "homepage" field, 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 OS: win, win32, win64, linux, linux32, linux64, macos, freebsd, freebsd32, freebsd64
* "req" field, optional, comma-separated list of Python modules, which are required in the "py" folder, e.g. "cuda_lint,cuda_tree"
* "reqlexer" field, optional, comma-separated list of lexers, which are required, e.g. "HTML,CSS"

=== Plugins ===

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

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

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

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

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

Section names: from "item1" to "item400", any numbers can be skipped. Fields in "item" 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": only for plugin which handles "on_key": comma-separated list of int key codes to handle in "on_key", e.g. "keys=9" means that "on_key" is only called for key code 9 (tab char).

Plugin can show sidebar button(s), without running plugin code. For this, add sections "sidebar1" to "sidebar3", with keys:

* "hint": hint of button, must be the same as used by plugin to create button in runtime.
* "icon": filename of PNG icon. If path missed, used file from CudaText. To use path in plugin dir, write value as "{dir}/subdir/filename.png" - with macro, with / slashes.
* "method": Python method name to show plugin side panel. This command must create side panel for this sidebar button.

==== Lexer lists ====

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

 [info]
 $var=Name1,Name2,Name3

In [itemN] sections set lexers like this:

 [itemN]
 lexers=$var

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

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

===Data-files===

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

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

===Lexers===

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

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

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

===Lite lexers===

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

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

==Format of snippet files==

===Contents===

To specify markers:

* ${NN}
* ${NN:default text}

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

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

The following macros are allowed in snippets text:

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

===File names===

Snippets are stored in separate files with extensions:

* .cuda-snippet
* .synw-snippet (same format as .cuda-snippet)
* .cuda-snips (compact format)

Encoding is UTF-8, no BOM. Files can be placed in any subdir of "data/snippets" dir, file names and dir names have no meaning, but it's good to name subdirs like AuthorName.SyntaxName, so users can easily find newly installed snippets.

===Format of .cuda-snippet===

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

* "name": snippet full name, shown in dialog.
* "id": snippet short alias for Tab-key (latin letters, digits, "_.$"), line is optional.
* "lex": lexers list, comma-separated, for which snippet is active, line is optional, empty means snippet always active.

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

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

===Format of .cuda-snips===

File contains one or several lines, one snippet per line. Empty lines, lines starting with "#" or space, are ignored. Format of lines:

* id text
* /N=name text
* id /N=name text
* id /L=lexers text
* id /L=lexers /N=name text
* id /L="lexers" /N="name" text

Here "id" is short alias for Tab-key, "name" (if not set, it's the same as "id") is full name for dialog, "lexers" is comma-separated lexer list, "text" is snippet contents. Contents can have escaped special chars: "\n", "\r", "\t" (tab-char), "\\" (backslash).

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

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