Mercurial > vim
annotate runtime/doc/terminal.txt @ 12031:9897241c08b5 v8.0.0896
patch 8.0.0896: cannot close a terminal window when the job ends
commit https://github.com/vim/vim/commit/dd693ce28b158ff573129ee30fe5b886544a03c2
Author: Bram Moolenaar <Bram@vim.org>
Date: Thu Aug 10 23:15:19 2017 +0200
patch 8.0.0896: cannot close a terminal window when the job ends
Problem: Cannot automaticlaly close a terminal window when the job ends.
Solution: Add the ++close argument to :term. Add the term_finish option to
term_start(). (Yasuhiro Matsumoto, closes #1950) Also add
++open.
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Thu, 10 Aug 2017 23:30:05 +0200 |
parents | 12833414cc02 |
children | 407a475c67fd |
rev | line source |
---|---|
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
1 *terminal.txt* For Vim version 8.0. Last change: 2017 Aug 10 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
2 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
3 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
4 VIM REFERENCE MANUAL by Bram Moolenaar |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
5 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
6 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
7 Terminal window support *terminal* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
8 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
9 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
10 WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
11 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
12 The terminal feature is optional, use this to check if your Vim has it: > |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
13 echo has('terminal') |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
14 If the result is "1" you have it. |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
15 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
16 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
17 1. Basic use |terminal-use| |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
18 2. Remote testing |terminal-testing| |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
19 3. Debugging |terminal-debug| |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
20 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
21 {Vi does not have any of these commands} |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
22 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
23 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
24 1. Basic use *terminal-use* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
25 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
26 This feature is for running a terminal emulator in a Vim window. A job can be |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
27 started connected to the terminal emulator. For example, to run a shell: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
28 :term bash |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
29 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
30 Or to run a debugger: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
31 :term gdb vim |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
32 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
33 The job runs asynchronously from Vim, the window will be updated to show |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
34 output from the job, also while editing in any other window. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
35 |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
36 |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
37 Typing ~ |
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
38 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
39 When the keyboard focus is in the terminal window, typed keys will be sent to |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
40 the job. This uses a pty when possible. You can click outside of the |
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
41 terminal window to move keyboard focus elsewhere. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
42 |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
43 CTRL-W can be used to navigate between windows and other CTRL-W commands, e.g.: |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
44 CTRL-W CTRL-W move focus to the next window |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
45 CTRL-W : enter an Ex command |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
46 See |CTRL-W| for more commands. |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
47 |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
48 Special in the terminal window: *CTRL-W_.* *CTRL-W_N* |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
49 CTRL-W . send a CTRL-W to the job in the terminal |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
50 CTRL-W N go to Terminal-Normal mode, see |Terminal-mode| |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
51 CTRL-\ CTRL-N go to Terminal-Normal mode, see |Terminal-mode| |
11914 | 52 CTRL-W " {reg} paste register {reg} *CTRL-W_quote* |
53 Also works with the = register to insert the result of | |
54 evaluating an expression. | |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
55 |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
56 See option 'termkey' for specifying another key instead of CTRL-W that |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
57 will work like CTRL-W. However, typing 'termkey' twice sends 'termkey' to |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
58 the job. For example: |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
59 'termkey' CTRL-W move focus to the next window |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
60 'termkey' : enter an Ex command |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
61 'termkey' 'termkey' send 'termkey' to the job in the terminal |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
62 'termkey' . send a CTRL-W to the job in the terminal |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
63 'termkey' N go to terminal Normal mode, see below |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
64 'termkey' CTRL-N same as CTRL-W N |
11965
a932d3da41c8
patch 8.0.0863: a remote command does not work in the terminal window
Christian Brabandt <cb@256bit.org>
parents:
11914
diff
changeset
|
65 *t_CTRL-\_CTRL-N* |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
66 The special key combination CTRL-\ CTRL-N can be used to switch to Normal |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
67 mode, just like this works in any other mode. |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
68 |
11814
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
69 |
d3d0db111d17
patch 8.0.0787: cannot send CTRL-W command to terminal job
Christian Brabandt <cb@256bit.org>
parents:
11774
diff
changeset
|
70 Size ~ |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
71 |
11659
49c12c93abf3
Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents:
11621
diff
changeset
|
72 See option 'termsize' for controlling the size of the terminal window. |
49c12c93abf3
Updated runtime files and translations.
Christian Brabandt <cb@256bit.org>
parents:
11621
diff
changeset
|
73 (TODO: scrolling when the terminal is larger than the window) |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
74 |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
75 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
76 Syntax ~ |
11774
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
77 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
78 :[range]ter[minal] [options] [command] *:ter* *:terminal* |
11774
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
79 Open a new terminal window. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
80 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
81 If [command] is provided run it as a job and connect |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
82 the input and output to the terminal. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
83 If [command] is not given the 'shell' option is used. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
84 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
85 A new buffer will be created, using [command] or |
11914 | 86 'shell' as the name, prefixed with a "!". If a buffer |
87 by this name already exists a number is added in | |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
88 parentheses. E.g. if "gdb" exists the second terminal |
11914 | 89 buffer will use "!gdb (1)". |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
90 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
91 If [range] is given it is used for the terminal size. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
92 One number specifies the number of rows. Unless the |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
93 "vertical" modifier is used, then it is the number of |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
94 columns. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
95 |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
96 Two comma separated numbers are used as "rows,cols". |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
97 E.g. `:24,80gdb` opens a terminal with 24 rows and 80 |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
98 columns. However, if the terminal window spans the |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
99 Vim window with, there is no vertical split, the Vim |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
100 window width is used. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
101 *term++close* *term++open* |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
102 Supported [options] are: |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
103 ++close The terminal window will close |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
104 automatically when the job terminates. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
105 ++open When the job terminates and no window |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
106 show it, a window will be opened. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
107 Note that this can be interruptive. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
108 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
109 When the buffer associated with the terminal is wiped out the job is killed, |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
110 similar to calling `job_stop(job, "kill")` |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
111 |
11967
12833414cc02
patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents:
11965
diff
changeset
|
112 By default the 'bufhidden' option of the buffer will be set to "hide". |
11914 | 113 So long as the job is running: If the window is closed the buffer becomes |
114 hidden. The command will not be stopped. The `:buffer` command can be used | |
115 to turn the current window into a terminal window. If there are unsaved | |
116 changes this fails, use ! to force, as usual. | |
11967
12833414cc02
patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents:
11965
diff
changeset
|
117 *E947* |
12833414cc02
patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents:
11965
diff
changeset
|
118 So long as the job is running, the buffer is considered modified and Vim |
12833414cc02
patch 8.0.0864: cannot specify the name of a terminal
Christian Brabandt <cb@256bit.org>
parents:
11965
diff
changeset
|
119 cannot be quit easily, see |abandon|. |
11914 | 120 |
121 When the job has finished and no changes were made to the buffer: closing the | |
122 window will wipe out the buffer. | |
123 | |
124 Before changes can be made to a terminal buffer, the 'modifiable' option must | |
125 be set. This is only possible when the job has finished. At the first change | |
126 the buffer will become a normal buffer and the highlighting is removed. | |
127 You may want to change the buffer name with |:file| to be able to write, since | |
128 the buffer name will still be set to the command. | |
129 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
130 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
131 Resizing ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
132 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
133 The size of the terminal can be in one of three modes: |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
134 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
135 1. The 'termsize' option is empty: The terminal size follows the window size. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
136 The minimal size is 2 screen lines with 10 cells. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
137 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
138 2. The 'termsize' option is "rows*cols", where "rows" is the minimal number of |
11774
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
139 screen rows and "cols" is the minimal number of cells. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
140 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
141 3. The 'termsize' option is "rowsXcols" (where the x is upper or lower case). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
142 The terminal size is fixed to the specified number of screen lines and |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
143 cells. If the window is bigger there will be unused empty space. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
144 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
145 If the window is smaller than the terminal size, only part of the terminal can |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
146 be seen (the lower-left part). |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
147 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
148 The |term_getsize()| function can be used to get the current size of the |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
149 terminal. |term_setsize()| can be used only when in the first or second mode, |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
150 not when 'termsize' is "rowsXcols". |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
151 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
152 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
153 Terminal-Job and Terminal-Normal mode ~ |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
154 *Terminal-mode* |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
155 When the job is running the contents of the terminal is under control of the |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
156 job. That includes the cursor position. Typed keys are sent to the job. |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
157 The terminal contents can change at any time. This is called Terminal-Job |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
158 mode. |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
159 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
160 Use CTRL-W N (or 'termkey' N) to switch to Terminal-Normal mode. Now the |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
161 contents of the terminal window is under control of Vim, the job output is |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
162 suspended. CTRL-\ CTRL-N does the same. |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
163 *E946* |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
164 In Terminal-Normal mode you can move the cursor around with the usual Vim |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
165 commands, Visually mark text, yank text, etc. But you cannot change the |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
166 contents of the buffer. The commands that would start insert mode, such as |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
167 'i' and 'a', return to Terminal-Job mode. The window will be updated to show |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
168 the contents of the terminal. |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
169 |
12031
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
170 In Terminal-Normal mode the statusline and window title show "(Terminal)". If |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
171 the job ends while in Terminal-Normal mode this changes to |
9897241c08b5
patch 8.0.0896: cannot close a terminal window when the job ends
Christian Brabandt <cb@256bit.org>
parents:
11967
diff
changeset
|
172 "(Terminal-finished)". |
11866
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
173 |
be40c8a9240d
patch 8.0.0813: cannot use a terminal window while the job is running
Christian Brabandt <cb@256bit.org>
parents:
11814
diff
changeset
|
174 |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
175 Unix ~ |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
176 |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
177 On Unix a pty is used to make it possible to run all kinds of commands. You |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
178 can even run Vim in the terminal! That's used for debugging, see below. |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
179 |
11914 | 180 Environment variables are used to pass information to the running job: |
181 TERM name of the terminal, 'term' | |
182 ROWS number of rows in the terminal initially | |
183 LINES same as ROWS | |
184 COLUMNS number of columns in the terminal initially | |
185 COLORS number of colors, 't_Co' (256*256*256 in the GUI) | |
186 VIM_SERVERNAME v:servername | |
187 | |
188 The |client-server| feature can be used to communicate with the Vim instance | |
189 where the job was started. This only works when v:servername is not empty. | |
190 If needed you can set it with: > | |
191 call remote_startserver('vim-server') | |
192 | |
193 In the job you can then do something like: > | |
194 vim --servername $VIM_SERVERNAME --remote +123 some_file.c | |
195 This will open the file "some_file.c" and put the cursor on line 123. | |
196 | |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
197 |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
198 MS-Windows ~ |
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
199 |
11774
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
200 On MS-Windows winpty is used to make it possible to run all kind of commands. |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
201 Obviously, they must be commands that run in a terminal, not open their own |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
202 window. |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
203 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
204 You need the following two files from winpty: |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
205 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
206 winpty.dll |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
207 winpty-agent.exe |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
208 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
209 You can download them from the following page: |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
210 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
211 https://github.com/rprichard/winpty |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
212 |
edf1a2a247fa
patch 8.0.0769: build problems with terminal on MS-Windows
Christian Brabandt <cb@256bit.org>
parents:
11763
diff
changeset
|
213 Just put the files somewhere in your PATH. |
11763
21f3930dfe6e
Documentation updates.
Christian Brabandt <cb@256bit.org>
parents:
11659
diff
changeset
|
214 |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
215 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
216 2. Remote testing *terminal-testing* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
217 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
218 Most Vim tests execute a script inside Vim. For some tests this does not |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
219 work, running the test interferes with the code being tested. To avoid this |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
220 Vim is executed in a terminal window. The test sends keystrokes to it and |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
221 inspects the resulting screen state. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
222 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
223 Functions ~ |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
224 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
225 term_sendkeys() send keystrokes to a terminal |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
226 term_wait() wait for screen to be updated |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
227 term_scrape() inspect terminal screen |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
228 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
229 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
230 ============================================================================== |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
231 3. Debugging *terminal-debug* |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
232 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
233 The Terminal debugging plugin can be used to debug a program with gdb and view |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
234 the source code in a Vim window. For example: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
235 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
236 :TermDebug vim |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
237 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
238 This opens three windows: |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
239 - A terminal window in which "gdb vim" is executed. Here you can directly |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
240 interact with gdb. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
241 - A terminal window for the executed program. When "run" is used in gdb the |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
242 program I/O will happen in this window, so that it does not interfere with |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
243 controlling gdb. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
244 - A normal Vim window used to show the source code. When gdb jumps to a |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
245 source file location this window will display the code, if possible. Values |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
246 of variables can be inspected, breakpoints set and cleared, etc. |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
247 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
248 This uses two terminal windows. To open the gdb window: > |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
249 :term gdb [arguments] |
11914 | 250 To open the terminal to run the tested program |term_start()| is used. |
11621
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
251 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
252 TODO |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
253 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
254 |
b8299e742f41
patch 8.0.0693: no terminal emulator support
Christian Brabandt <cb@256bit.org>
parents:
diff
changeset
|
255 vim:tw=78:ts=8:ft=help:norl: |