Documentation for the UI customisation
This commit is contained in:
Ben Jackson
parent
80afb153b9
commit
3726766694
4 changed files with 180 additions and 1 deletions
158
README.md
158
README.md
|
|
@ -65,11 +65,15 @@ For a tutorial and usage overview, take a look at the
|
|||
* [Other servers](#other-servers)
|
||||
* [Customisation](#customisation)
|
||||
* [Changing the default signs](#changing-the-default-signs)
|
||||
* [Changing the default window sizes](#changing-the-default-window-sizes)
|
||||
* [Changing the terminal size](#changing-the-terminal-size)
|
||||
* [Advanced UI customisation](#advanced-ui-customisation)
|
||||
* [Example](#example)
|
||||
* [FAQ](#faq)
|
||||
* [Motivation](#motivation)
|
||||
* [License](#license)
|
||||
|
||||
<!-- Added by: ben, at: Sun 12 Jul 2020 16:46:02 BST -->
|
||||
<!-- Added by: ben, at: Sat 18 Jul 2020 12:58:35 BST -->
|
||||
|
||||
<!--te-->
|
||||
|
||||
|
|
@ -673,6 +677,8 @@ You can configure your choices in the `.vimspector.json`. See
|
|||
|
||||
|
||||
|
||||
Scopes and variables are represented by the buffer `vimspector.Variables`.
|
||||
|
||||
## Watches
|
||||
|
||||
The watches window is a prompt buffer, where that's available. Enter insert mode
|
||||
|
|
@ -687,6 +693,8 @@ to add a new watch expression.
|
|||
|
||||
|
||||
|
||||
The watches are represented by the buffer `vimspector.StackTrace`.
|
||||
|
||||
## Stack Traces
|
||||
|
||||
* In the threads window, use `<CR>` to expand/collapse.
|
||||
|
|
@ -694,6 +702,8 @@ to add a new watch expression.
|
|||
|
||||
|
||||
|
||||
The stack trace is represented by the buffer `vimspector.StackTrace`.
|
||||
|
||||
## Program Output
|
||||
|
||||
* In the outputs window use the WinBar to select the output channel.
|
||||
|
|
@ -704,6 +714,10 @@ to add a new watch expression.
|
|||
|
||||
|
||||
|
||||
If the output window is closed, a new one can be opened with
|
||||
`:VimspectorShowOutput <category>` (use tab-completion - `wildmenu` to see the
|
||||
options).
|
||||
|
||||
### Console
|
||||
|
||||
The console window is a prompt buffer, where that's available, and can be used
|
||||
|
|
@ -718,6 +732,9 @@ adapters.
|
|||
|
||||
NOTE: See also [Watches](#watches) above.
|
||||
|
||||
If the output window is closed, a new one can be opened with
|
||||
`:VimspectorShowOutput Console`.
|
||||
|
||||
## Closing debugger
|
||||
|
||||
To close the debugger, use:
|
||||
|
|
@ -1298,6 +1315,145 @@ sign define vimspectorBPDisabled text=🔵 texthl=Normal
|
|||
sign define vimspectorPC text=🔶 texthl=SpellBad
|
||||
```
|
||||
|
||||
## Changing the default window sizes
|
||||
|
||||
> ***Please Note***: This cusomiation API is ***unstable***, meaning that it may
|
||||
change at any time. I will endeavour to reduce the impact of this and annouce
|
||||
changes in Gitter.
|
||||
|
||||
The following options control the default sizes of the UI windows (all of them
|
||||
are numbers)
|
||||
|
||||
- `g:vimspector_sidebar_width` (default: 50 columns):
|
||||
The width in columns of the left utility windows (variables, watches, stack
|
||||
trace)
|
||||
- `g:vimspector_bottombar_height` (default 10 lines):
|
||||
The height in rows of the output window below the code window.
|
||||
|
||||
Example:
|
||||
|
||||
```viml
|
||||
let g:vimspector_sidebar_width = 75
|
||||
let g:vimspector_bottombar_height = 15
|
||||
```
|
||||
|
||||
## Changing the terminal size
|
||||
|
||||
The terminal is typically created as a vertical split to the righ of the code
|
||||
window, and that window is re-used for subsequent terminal buffers.
|
||||
The following control the sizing of the terminal window used
|
||||
for debuggee input/output when using Vim's built-in terminal.
|
||||
|
||||
- `g:vimspector_code_minwidth` (default: 82 columns):
|
||||
Minimum number of columns to try and maintain for the code window when
|
||||
splitting to create the terminal window.
|
||||
- `g:vimspector_terminal_maxwidth` (default: 80 columns):
|
||||
Maximum number of columns to use for the terminal.
|
||||
- `g:vimspector_terminal_minwidth` (default: 10 columns):
|
||||
Minimum number of columns to use when it is not possible to fit
|
||||
`g:vimspector_terminal_maxwidth` columns for the terminal.
|
||||
|
||||
That's a lot of options, but essentially we try to make sure that there are at
|
||||
least `g:vimspector_code_minwidth` columns for the main code window and that the
|
||||
terminal is no wider than `g:vimspector_terminal_maxwidth` columns.
|
||||
`g:vimspector_terminal_minwidth` is there to ensure that there's a reasonable
|
||||
number of columns for the terminal even when there isn't enough horizontal space
|
||||
to satisfy the other contraints.
|
||||
|
||||
Example:
|
||||
|
||||
```viml
|
||||
let g:vimspector_code_minwidth = 90
|
||||
let g:vimspector_terminal_maxwidth = 75
|
||||
let g:vimspector_terminal_minwidth = 20
|
||||
```
|
||||
|
||||
## Advanced UI customisation
|
||||
|
||||
> ***Please Note***: This cusomiation API is ***unstable***, meaning that it may
|
||||
change at any time. I will endeavour to reduce the impact of this and annouce
|
||||
changes in Gitter.
|
||||
|
||||
The above customisation of window sizes is limited intentionally to keep things
|
||||
simple. Vimspector also provides a way for you to customise the UI without
|
||||
restrictions, by running a `User` autocommand just after creating the UI or
|
||||
opening the terminal. This requires you to write some vimscript, but allows you
|
||||
to do things like:
|
||||
|
||||
* Hide a particular window or windows
|
||||
* Move a particular window or windows
|
||||
* Resize windows
|
||||
* Have multiple windows for a particular buffer (say, you want 2 watch windows)
|
||||
* etc.
|
||||
|
||||
You can essentially do anything you could do manually by writing a little
|
||||
vimscript code.
|
||||
|
||||
The `User` autocommand is raised with `pattern` set with the following values:
|
||||
|
||||
* `VimspectorUICreated`: Just after setting up the UI for a debug session
|
||||
* `VimspectorTerminalOpened`: Just after opening the terminal window for program
|
||||
input/output.
|
||||
|
||||
The following global variable is set up for you to get access to the UI
|
||||
elements: `g:vimspector_session_windows`. This is a `dict` with the following
|
||||
keys:
|
||||
|
||||
* `g:vimspector_session_windows.tagpage`: The tab page for the session
|
||||
* `g:vimspector_session_windows.variables`: Window ID of the variables window,
|
||||
containing the `vimspector.Variables` buffer.
|
||||
* `g:vimspector_session_windows.watches`: Window ID of the watches window,
|
||||
containng the `vimspector.Watches` buffer.
|
||||
* `g:vimspector_session_windows.stack_trace`: Window ID of the stack trade
|
||||
window containing the `vimspector.StackTrace` buffer.
|
||||
* `g:vimspector_session_windows.code`: Window ID of the code window.
|
||||
* `g:vimspector_session_windows.output`: Window ID of the output window.
|
||||
|
||||
In addition, the following key is added when triggering the
|
||||
`VimspectorTerminalOpened` event:
|
||||
|
||||
* `g:vimspector_session_windows.terminal`: Window ID of the terminal window
|
||||
|
||||
## Example
|
||||
|
||||
There is some example code in `support/custom_ui_vimrc` showing how you can use
|
||||
the window IDs to modify various aspects of the UI using some basic vim
|
||||
commands, primarily `win_gotoid` funciton and the `wincmd` ex command.
|
||||
|
||||
To try this out `vim -Nu support/custom_ui_vimrc <some file>`.
|
||||
|
||||
Here's a rather smaller example. A simple way to use this is to drop it into a
|
||||
file named `my_vimspector_ui.vim` in `~/.vim/plugin` (or paste into your
|
||||
`vimrc`):
|
||||
|
||||
```viml
|
||||
" Set the basic sizes
|
||||
let g:vimspector_sidebar_width = 80
|
||||
let g:vimspector_code_minwidth = 85
|
||||
let g:vimspector_terminal_minwidth = 75
|
||||
|
||||
function! s:CustomiseUI()
|
||||
" Customise the basic UI...
|
||||
|
||||
" Close the output window
|
||||
call win_gotoid( g:vimspector_session_windows.output )
|
||||
q
|
||||
endfunction
|
||||
|
||||
function s:SetUpTerminal()
|
||||
" Customise the terminal window size/position
|
||||
" For some reasons terminal buffers in Neovim have line numbers
|
||||
call win_gotoid( g:vimspector_session_windows.terminal )
|
||||
set norelativenumber nonumber
|
||||
endfunction
|
||||
|
||||
augroup MyVimspectorUICustomistaion
|
||||
autocmd!
|
||||
autocmd User VimspectorUICreated call s:CustomiseUI()
|
||||
autocmd User VimspectorTerminalOpened call s:SetUpTerminal()
|
||||
augroup END
|
||||
```
|
||||
|
||||
# FAQ
|
||||
|
||||
1. Q: Does it work? A: Yeah. It's a bit unpolished.
|
||||
|
|
|
|||
|
|
@ -453,6 +453,11 @@ class DebugSession( object ):
|
|||
self._stackTraceView.ExpandFrameOrThread()
|
||||
|
||||
def ShowOutput( self, category ):
|
||||
if not self._outputView.WindowIsValid():
|
||||
with utils.LetCurrentTabpage( self._uiTab ):
|
||||
vim.command( f'botright { settings.Int( "bottombar_height", 10 ) }new' )
|
||||
self._outputView.UseWindow( vim.current.window )
|
||||
|
||||
self._outputView.ShowOutput( category )
|
||||
|
||||
def GetOutputBuffers( self ):
|
||||
|
|
|
|||
|
|
@ -102,6 +102,17 @@ class OutputView( object ):
|
|||
# FIXME: nunmenu the WinBar ?
|
||||
self._buffers = {}
|
||||
|
||||
def WindowIsValid( self ):
|
||||
return self._window.valid
|
||||
|
||||
def UseWindow( self, win ):
|
||||
assert not self._window.valid
|
||||
self._window = win
|
||||
# TODO: Sorting of the WinBar ?
|
||||
for category, _ in self._buffers.items():
|
||||
self._RenderWinBar( category )
|
||||
|
||||
|
||||
def _ShowOutput( self, category ):
|
||||
if not self._window.valid:
|
||||
return
|
||||
|
|
|
|||
|
|
@ -214,6 +214,13 @@ def AnyWindowForBuffer( buf ):
|
|||
yield
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def LetCurrentTabpage( tabpage ):
|
||||
with RestoreCurrentWindow():
|
||||
vim.current.tabpage = tabpage
|
||||
yield
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def LetCurrentWindow( window ):
|
||||
with RestoreCurrentWindow():
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue