diff options
Diffstat (limited to 'doc/06_AdeptEditing.md')
| -rw-r--r-- | doc/06_AdeptEditing.md | 329 |
1 files changed, 201 insertions, 128 deletions
diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md index b09487ec..8ae6ae6e 100644 --- a/doc/06_AdeptEditing.md +++ b/doc/06_AdeptEditing.md @@ -1,197 +1,270 @@ # Adept Editing -## Key Commands +## Basic Editing -Textadept is entirely keyboard-driven. See the comprehensive list of key -commands in the [appendix][]. Key commands can be modified in your -[key preferences][]. +Textadept has many basic editing features you are familiar with: basic text +entry, undo/redo, clipboard manipulation, deleting characters and words, +duplicating lines, joining lines, and transposing characters. These are +accessible from the top-level `Edit` menu and have associated key bindings. +Some of the basic editing features you may not be familiar with are discussed +below. -[appendix]: 14_Appendix.html#Key.Bindings -[key preferences]: 9_Preferences.html#Key.Commands - -## Character Autopairing +### Autopaired Characters Usually, quote (`'`, `"`) and brace (`(`, `[`, `{`) characters go together in pairs. By default, Textadept automatically inserts the complement character when -the first is typed. Similarly, the complement is deleted when you press -`Backspace` (`⌫`) over the first. See the [preferences][] page if you would like -to disable this. +the first is typed. Similarly, the complement is deleted when you press `Bksp` +(`⌫` on Mac OSX | `Bksp` in ncurses) over the first. See the [preferences][] +page if you would like to disable this. -[preferences]: 9_Preferences.html#Module.Settings +[preferences]: 08_Preferences.html#Generic -## Word Completion +### Word Completion Textadept provides buffer-based word completion. Start typing a word, press -`Ctrl+Return` (`^⎋` on Mac OSX | `M-Enter` in ncurses), and a list of suggested -completions based on words in the current document is provided. Continuing to -type changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the -selected word. +`Ctrl+Enter` (`^⎋` on Mac OSX | `M-Enter` in ncurses), and a list of suggested +completions based on words in the current buffer is provided. Continuing to type +changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the selected +word.  -## Adeptsense +### Virtual Space Mode -Textadept has the capability to autocomplete symbols for programming languages -and display API documentation. Lua is of course supported extremely well and -other languages have basic support with the help of [ctags][]. Symbol completion -is available by pressing `Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` in ncurses). -Documentation for symbols is available with `Ctrl+H` (`^H` | `M-H` or `M-S-H`). +Virtual space (freehand) mode is enabled and disabled with `Ctrl+Alt+Shift+V` +(`^⇧V` in Mac OSX | none in ncurses). When enabled, caret movement is not +restricted by line endings. - - - +### Overwrite Mode - +Overwrite mode is enabled and disabled with the `Insert` key. When enabled, +characters in the buffer will be overwritten instead of inserted as you type. +The caret also changes to an underline when in overwrite mode. -For more information on adding adeptsense support for another language, see -the [LuaDoc][]. +## Selections -[ctags]: http://ctags.sf.net -[LuaDoc]: api/_M.textadept.adeptsense.html +Textadept has many ways of creating and working with selections. Basic +selections are what you get when you do things like hold the `Shift` modifier +key (`⇧` on Mac OSX | `S-` in ncurses) while pressing the arrow keys, click and +drag the mouse over a range of text, or press `Ctrl+A` (`⌘A` | `M-A`) for +"Select All". More advanced selections like multiple and rectangular selections +are more complicated to create, but have powerful uses. -## Find and Replace +### Multiple Selection -`Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in ncurses) brings up the -Find/Replace dialog. In addition to offering the usual find and replace, -Textadept allows you to find with [Lua patterns][] and replace with Lua captures -and even Lua code! For example: replacing all `(%w+)` with -`%(string.upper('%1'))` capitalizes all words in the buffer. Lua captures (`%n`) -are only available from a Lua pattern search, but embedded Lua code enclosed in -`%()` is always allowed. +Clicking the mouse at a point in the buffer while holding the `Ctrl` modifier +key (`^` on Mac OSX | N/A in ncurses) places an additional caret at that point. +Clicking and dragging while holding the same modifier creates multiple +selections. When you start typing, the text is mirrored at each selection. -Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key commands -for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, `^⇧R` -respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in ncurses) only work -when the Find/Replace dialog is hidden. When it is visible in the GUI version, -use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and `Alt+A` (`⌘N`, `⌘P`, -`⌘R`, `⌘A` | N/A) for English locale. +This is currently unavailable in ncurses. -In the ncurses version, use `Tab` and `S-Tab` to toggle between the find next, -find previous, replace, and replace all buttons; `Up` and `Down` arrows switch -between the find and replace text fields; `^P` and `^N` cycles through history; -and `F1-F4` toggles find options. +### Rectangular Selection -[Lua patterns]: 14_Appendix.html#Lua.Patterns +Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S-` in ncurses) and pressing the arrow +keys enables rectangular selections to be made. Start typing to type on each +line. -### Find in Files + + + -`Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in ncurses) and -will prompt for a directory to search. The results are displayed in a new -buffer. Double-clicking a search result jumps to it in the file. You can also -use the `Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` on Mac OSX | none -in ncurses) key commands. Replace in Files is not supported. You will have to -`Find in Files` first, and then `Replace All` for each file a result is found -in. The `Match Case`, `Whole Word`, and `Lua pattern` flags still apply. +### Select to Matching Brace - +Putting the caret over a brace character (`(`, `)`, `[`, `]`, `{`, or `}`) and +pressing `Ctrl+Shift+M` (`^⇧M` on Mac OSX| `M-S-M` in ncurses) extends the +selection to the brace character's matching brace. -### Find Incremental +### Entity Selection -You can start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | -`M-^F` in ncurses). Incremental search searches the buffer as you type. Only the -`Match Case` option is recognized. Pressing `Esc` (`⎋` | `Esc`) stops it. +Textadept allows you to select many different entities from the caret. For +example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in ncurses) selects all characters in +a `""` sequence. Typing `Ctrl++` (`^+` | `M-+`) as a follow-up selects the +double-quotes too. See the `Edit -> Select In...` menu for available entities +and their key bindings. -### Replace in Selection +### Transforms -By default, `Replace All` replaces all text in the buffer. If you want to -replace all text in just a portion of the buffer, select a block of text and -then `Replace All`. +#### Enclose Entities -## Indentation +As a complement to selecting entities, you can enclose text as entities. The +`Edit -> Selection -> Enclose In...` menu contains all available entities and +their key bindings. -### Change Indent Level +If no text is selected, the word to the left of the caret is enclosed. + +#### Change Case + +Pressing `Ctrl+Alt+U` or `Ctrl+Alt+Shift+U` (`^U` or `^⇧U` on Mac OSX | `M-^U` +or `M-^L` in ncurses) converts selected text to upper-case letters or lower-case +letters respectively. + +#### Change Indent Level The amount of indentation for a selected set of lines is increased by pressing -`Tab` (`⇥` | `Tab`) and decreased by pressing `Shift+Tab` (`⇧⇥` | `S-Tab`). -Using these key sequences when no selection is present does not have the same -effect. +`Tab` (`⇥` on Mac OSX | `Tab` in ncurses) and decreased by pressing `Shift+Tab` +(`⇧⇥` | `S-Tab`). Whole lines do not have to be selected. As long as any part of +a line is selected, the entire line is eligible for indenting/dedenting. Using +these key sequences when no selection is present does not have the same effect. + +#### Move Lines + +Selected lines are moved with the `Ctrl+Shift+Up` and `Ctrl+Shift+Down` (`^⇧⇡` +and `^⇧⇣` on Mac OSX | `S-^Up` and `S-^Down` in ncurses) keys. Like with +changing indent level, as long as any part of a line is selected, the entire +line is eligible for moving. + +## Find & Replace -### Change Indent Size +`Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in ncurses) brings up the Find & +Replace pane. In addition to offering the usual find and replace with "Match +Case" and "Whole Word" options and find/replace history, Textadept allows you to +find with [Lua patterns][] and replace with Lua captures and even Lua code! For +example: replacing all `(%w+)` with `%(string.upper('%1'))` upper-cases all +words in the buffer. Lua captures (`%`_`n`_) are only available from a Lua +pattern search, but embedded Lua code enclosed in `%()` is always allowed. -The indent size is usually set by a [language-specific module][] or the -[theme][]. You can set it manually using the `Buffer -> Indentation` menu. -Textadept shows what it is using for indentation in the document statusbar. +Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key bindings +for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, `^⇧R` +respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in ncurses) only work +when the Find & Replace pane is hidden. When the pane is visible in the GUI +version, use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and `Alt+A` (`⌘N`, +`⌘P`, `⌘R`, `⌘A` | N/A) for English locale. - +In the ncurses version, `Tab` and `S-Tab` toggles between the find next, find +previous, replace, and replace all buttons; `Up` and `Down` arrows switch +between the find and replace text fields; `^P` and `^N` cycles through history; +and `F1-F4` toggles find options. -[language-specific module]: 7_Modules.html#Buffer.Properties -[theme]: 8_Themes.html#Buffer +[Lua patterns]: 14_Appendix.html#Lua.Patterns -### Using Tabs +### Replace in Selection -You can use tabs instead of the default spaces by pressing `Ctrl+Alt+Shift+T` -(`^⇧T` on Mac OSX | `M-T` or `M-S-T` in ncurses) or using the `Buffer -> Toggle -Use Tabs` menu. Textadept shows what it is using for indentation in the document -statusbar. +By default, `Replace All` replaces all text in the buffer. If you want to +replace all text in just a portion of the buffer, select a block of text and +then `Replace All`. -The default option is usually set by a [language-specific module][] or the -[theme][]. +### Find in Files -[language-specific module]: 7_Modules.html#Buffer.Properties -[theme]: 8_Themes.html#Buffer +`Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in ncurses) and +will prompt for a directory to search. The results are displayed in a new +buffer. Double-clicking a search result jumps to it in the file. You can also +use the `Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` on Mac OSX | none +in ncurses) key bindings. Replace in Files is not supported. You will have to +`Find in Files` first, and then `Replace All` for each file a result is found +in. The `Match Case`, `Whole Word`, and `Lua pattern` flags still apply. -### Converting Indentation +_Warning_: currently, there is no way to specify a file-type filter, so Find in +Files will scan **all** files, even binary ones, in **all** sub-directories. +Searches also block Textadept from receiving additional input, making the +interface temporarily unresponsive. Searching large directories or projects can +be very time consuming and frustrating, so using a specialized, external tool +such as [ack][] is recommended. -Use the `Edit -> Convert Indentation` menu to convert indentation. If the buffer -is using tabs, all spaces are converted to tabs. If the buffer is using spaces, -all tabs are converted to spaces. + -## Selecting Text +[ack]: http://betterthangrep.com/ -### Rectangular Selection +### Incremental Find -Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S` in ncurses) and pressing the arrow -keys enables rectangular selections to be made. Start typing to type on each -line. +You can start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | +`M-^F` in ncurses). Incremental search searches the buffer as you type. Only the +`Match Case` option is recognized. Pressing `Esc` (`⎋` | `Esc`) stops the +search. - - - +## Source Code Editing -### Multiple Selection +Textadept would not be a programmer's editor without some features for editing +source code. Textadept understands the syntax and structure of more than 80 +different programming languages and recognizes hundreds of file types. It uses +this knowledge to make viewing and editing code faster and easier. -Clicking the mouse at a point in the buffer while holding `Control` places an -additional caret at that point. Clicking and dragging while holding `Control` -creates multiple selections. Start typing to enter text at each selection. +### Lexers -This is currently unavailable in ncurses. +When you open a file, chances are that Textadept will identify the programming +language associated with that file and set a "lexer" to highlight syntactic +elements of the code. You can set or change the lexer manually by pressing +`Ctrl+Shift+L` (`⌘⇧L` on Mac OSX | `M-S-L` in ncurses) and selecting a lexer +from the list. You can customize how Textadept recognizes files in your +[file type preferences][]. -### Selecting Entities +Lexers can sometimes lose track of their context while you are editing and +highlight syntax incorrectly. Pressing `F5` triggers a full redraw. -Textadept allows you to select many different entities from the caret. For -example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in ncurses) selects all characters in -a `""` sequence. Typing `Ctrl++` (`^+` | `M-+`) as a follow-up selects the -double-quotes too. See the `Edit -> Select In...` menu for available entities -and their key commands. +[file type preferences]: 08_Preferences.html#File.Types -## Enclosing Text +### Code Folding -As a complement to selecting entities, you can enclose text as entities. The -`Edit -> Selection -> Enclose In...` menu contains all available entities and -their key commands. +Some lexers support code folding, where blocks of code can be temporarily +hidden, making viewing easier. Fold points are denoted by arrows in the margin +to the left of the code. Clicking on one toggles the folding for that block of +code. -If no text is selected, the word to the left of the caret is enclosed. + -## Word Highlight +### Word Highlight All occurrences of a given word are highlighted by putting the caret over the word and pressing `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX | N/A in ncurses). This -is useful to show occurrences of a variable name in source code. +is useful to show occurrences of a variable name, but is not limited to source +code. + + This is not supported in ncurses. - +### Adeptsense + +Textadept has the capability to autocomplete symbols for programming languages +and display API documentation. Symbol completion is available by pressing +`Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` in ncurses). Documentation for symbols +is available with `Ctrl+H` (`^H` | `M-H` or `M-S-H`). Note: In order for this +feature to work, the language you are working with must have an [Adeptsense][] +defined. Language-specific modules usually [define Adeptsenses][]. -## Editing Modes + + + -### Virtual Space + -Virtual space (freehand) mode is enabled and disabled with `Ctrl+Alt+Shift+V` -(`^⇧V` in Mac OSX | none in ncurses). When enabled, caret movement is not -restricted by line endings. +[Adeptsense]: api/_M.textadept.adeptsense.html +[define Adeptsenses]: api/_M.html#Adeptsense + +### Snippets + +Snippets are essentially pieces of text inserted into a document. However, +snippets are not limited to static text. They can be dynamic templates which +contain placeholders for further user input, can mirror or transform those user +inputs, and/or execute arbitrary code. Snippets are useful for rapidly +constructing blocks of code such as control structures, method calls, and +function declarations. Press `Ctrl+K` (`⌥⇥` on Mac OSX | `M-K` in ncurses) for a +list of available snippets. Snippets are composed of trigger word and snippet +text. Instead of manually selecting a snippet, you can type its trigger word +followed by the `Tab` (`⇥` | `Tab`) key. Subsequent presses of `Tab` (`⇥` | +`Tab`) cause the caret to enter placeholders in sequential order, `Shift+Tab` +(`⇧⇥` | `S-Tab`) goes back to the previous placeholder, and `Ctrl+Shift+K` +(`⌥⇧⇥` | `M-S-K`) cancels the current snippet. Snippets can be nested (inserted +from within another snippet) and are not limited to source code. +Language-specific modules usually [define snippets][], but you can create your +own custom snippets in your [snippet preferences][]. + + + + -### Overwrite +[define snippets]: api/_M.html#Snippets +[snippet preferences]: 08_Preferences.html#Snippets -Overwrite mode is enabled and disabled with the `Insert` key. When enabled, -characters in the buffer will be overwritten instead of inserted as you type. -The caret also changes to an underline when in overwrite mode. +### Toggle Comments + +Pressing `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in ncurses) comments or uncomments +the code on the selected lines. As long as any part of a line is selected, the +entire line will be commented or uncommented. Note: In order for this feature to +work, the language you are working with must have its comment prefix defined. +Language-specific modules usually [define prefixes][], but it can also be done +[manually][] in your [user-init file][]. + +[define prefixes]: api/_M.html#Block.Comment +[manually]: http://foicica.com/wiki/comment-supplemental +[user-init file]: 08_Preferences.html#User.Init |