= About =

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

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

Features for HTML/CSS coding: 

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

Screenshot:

[[File:cudatext.png]]

= Download =

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

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

= Configs =

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

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

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

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

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

= Help topics =
== Command line parameters ==

Usage:

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

Supported keys:

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

Notes:

* Filenames can be with ":line" or ":line:column" suffix to place caret.
* Folders cannot be loaded yet.
* Projects (.cuda-proj files) can be loaded, if Project Manager plugin installed.
* Sessions (.cuda-session files) can be loaded, if Session Manager installed.

== Mouse shortcuts ==

Multi-carets:

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

Select:

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

Clicks:

* double-click - select clicked word (see option word_chars).
* triple-click - select entire line (limited by end-of-lines).
    
* middle-button click (with option mouse_mid_click_scroll) - start "Browser Scroll" mode: circle mark appears and mouse moving around this mark auto-scrolls text in 4 directions; speed of scrolling depends on distance of cursor from circle mark (any click to turn off).

* middle-button click (with option mouse_mid_click_paste) - paste from clipboard. This is like in Linux. Additionally it's good to install plugin "Auto-Copy to Clipboard".

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

== Multi-carets ==

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

Animation:

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

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

=== Why Comments-plugin dont comment blocks in lexer? ===

Plugin "Comments" can comment

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

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

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

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

=== How to setup styles of hidden sublexer? ===

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

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

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

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

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

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

== File-types config ==

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

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

This allows to open files with extension "mht" with custom lexer, and file with name "myconfig.conf" with another custom lexer.
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 (.lcf), so setting will be reset on reinstalling lexer.
* It can specify file extension, or name+extension, but cannot set complex file mask with "*".

==Encodings==

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

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

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

Encoding names for command-line:

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

==Line ends==

Main types of line-ends are supported: 

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

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

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

* unprinted_show
* unprinted_ends
* unprinted_end_details

==Groups of tabs==

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

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

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

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

==Auto-completion==

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

Example for PHP lexer:

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

== Syntax tree ==

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

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

==How to restore lexers styles/colors after reinstalling app?==

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

[[File:cudatext_restore_styles.png]]

==Snippets==

To use snippets you need:

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

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

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

Menu of Snippets plugin:

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

By default CudaText includes 120+ snippets for HTML tags. They work in lexers HTML, HTML_ (alternate html lexer in Addon Manager). Just type tag name w/o bracket, press Tab, and snippet 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

==Find/Replace dialog==

Dialog has hotkeys:

* Alt+Enter: Find first
* Enter: Find next/ Replace next (depends of focused input)
* Shift+Enter: Find previous
* Alt+Z: Replace, and find next
* Ctrl+Alt+Z: Replace, and don't find next
* Alt+A: Replace all
* Ctrl+Enter: Add newline in multi-line input
* 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

==Comments==

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

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

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

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

Comment chars are saved:

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

== Char map ==

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

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

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

[[File:cudatext-charmap.png]]

== Tab-switcher using history ==

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

CudaText can do this with Ctrl+Tab, but without dialog. To do it, install CudaExt addon. It has [https://github.com/kvichans/cuda_ext/blob/master/readme/setup-tab-switcher.txt file in readme dir], which shows what to do.

==Minimap, Micromap==

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

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

Colored marks on micromap:

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

== Paste with middle-button-click ==

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

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

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

==Full-screen==

There are two menu items in the View menu:

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

Notes:

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

==more==

= Tech topics=
==How to compile program==

* install FPC (FreePascal) 3.x (will be used by Lazarus)
* install SVN (program "svn" needed to install Lazarus trunk and/or FPC)
* install Lazarus IDE release, then install Lazarus "trunk" (1.6.4 is not Ok, you need at last 1.7). See this info: [[Getting_Lazarus]].
* download ATnnnnnn packages, EControl package, from https://github.com/Alexey-T/
* download CudaText source too
* 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, TLinkLabel, TGauge
** in System tab: TUniqueInstance
* in IDE, open "cudatext.lpi" like usual Lazarus project, compile it

Install order

* first install package ATSynEdit
* next install package EControl
* package ATSynEdit has one file, which depends on EControl. It is atsynedit_adapter_econtrol.pas. It is here to not make new package for 1 file. When you compile CudaText, FPC shows error about this file, you need to add dir "atsynedit" to project's search dirs.
* package ATSynEdit has files, which depend on ATListbox package. atsynedit_form_*.pas. They are here to not make new package. You added dir to "atsynedit" to project's dirs, so files will be found.
* then install other packages

== Python API ==

See [[CudaText API]].

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

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

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

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

* For Ubuntu: run

  sudo apt-get install libqt4pas-dev

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

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

==Why on Linux, chars are duplicated==

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

 echo $GTK_IM_MODULE

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

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

* "subdir" field (required), for plugins it should begin with prefix "cuda_"
* "homepage" field, URL on Github
* "api" field, specify if plugin cannot work on old API versions


=== Plugins ===

Example of 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.160
  
  [item1]
  section=commands
  caption=MyPlugin\Cmd one
  method=run
  lexers=CSS,HTML
  hotkey=Alt+F
  
  [item2]
  section=commands
  caption=MyPlugin\-
  method=nnnn
  
  [item3]
  section=commands
  caption=MyPlugin\Cmd other
  method=run_more
  menu=0

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

* Line "menu=0" means that item is not visible in Plugins menu.
* Line "lexers=" means that command can be run only when such lexer(s) active.
* Line "hotkey=" allowed. 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.

==== 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 inf for data-files, to be copied into subdir of "data" dir (name of subdir can be any, for example "themes"):

  [info]
  title=Name
  desc=My files
  type=cudatext-data
  subdir=mydir

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

==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 extension ".synw-snippet". Encoding is UTF8 no BOM. They can be placed in any subdir of "data/snippets" dir, file names and dir names have no meaning, but it's good to name subdirs like AuthorName.SyntaxName, so users can easily find newly installed snippets.

'''File format'''

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

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

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

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

==More==


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