344 lines
11 KiB
Markdown
344 lines
11 KiB
Markdown
# Always have a nice view for vim split windows
|
|
|
|
------------- - -----------------------------------------------
|
|
Plugin : GoldenView.vim
|
|
Author : Zhao Cai
|
|
EMail : caizhaoff@gmail.com
|
|
Homepage : http://zhaocai.github.io/GoldenView.Vim/
|
|
Vim.org : http://www.vim.org/scripts/script.php?script_id=4529
|
|
Version : 1.3.6
|
|
Date Created : Tue 18 Sep 2012 05:23:13 PM EDT
|
|
Last Modified : Mon 22 Apr 2013 05:55:22 PM EDT
|
|
------------- - -----------------------------------------------
|
|
|
|
|
|
|
|
The initial motive for [GoldenView][GoldenView] comes from the frustration of using other vim plugins to auto-resize split windows. The idea is deadly simple and very useful: **resize the focused window to a proper size.** However, in practice, many hiccups makes **auto-resizing** not a smooth experience. Below are a list of issues [GoldenView][GoldenView] attempts to solve:
|
|
|
|
First and the most important one, auto-resizing should play nicely with existing plugins like `tagbar`, `vimfiler`, `unite`, `VOoM`, `quickfix`, `undotree`, `gundo`, etc. These windows should manage there own window size.
|
|
|
|
Second, auto-resizing should take care of **the other windows** too. Resizing the focused window may cause the other windows become too small. When you have 4+ split windows, auto-resizing may just make a mess out of it.
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
[GoldenView][GoldenView] has preliminarily solved the issues described above. It also provides other features. Bascally, it does two things:
|
|
|
|
### 1. AutoResizing
|
|
First of all, it automatically resize the focused split window to a "golden" view based on [golden ratio][golden-ratio-wikipedia] and `textwidth`.
|
|
|
|
|
|
### 2. Tiled Windows Management
|
|
|
|
Second, it maps a single key (`<C-L>` by default) to nicely split windows to tiled windows.
|
|
|
|
```
|
|
----+----------------+------------+---+
|
|
| | | | |
|
|
| F | | S1 | T |
|
|
| I | +------------| A |
|
|
| L | | S2 | G |
|
|
| E | MAIN PANE +------------+ B |
|
|
| R | | S3 | A |
|
|
| | | | R |
|
|
| | | | |
|
|
+---+----------------+------------+---+
|
|
```
|
|
|
|
To get this view, just hit `<C-L>` 4 times. or, if you have a large monitor, you may get tiled windows below.
|
|
|
|
|
|
```
|
|
----+---------------+--------------+------------+---+
|
|
| | | | | |
|
|
| F | | | S1 | T |
|
|
| I | | +------------| A |
|
|
| L | | M2 | S2 | G |
|
|
| E | MAIN PANE | +------------+ B |
|
|
| R | | | S3 | A |
|
|
| | | | | B |
|
|
| | | | | |
|
|
+---+---------------+--------------+------------+---+
|
|
```
|
|
|
|
|
|
To quickly switch between those windows, a few keys are mapped to
|
|
|
|
- Focus to the main window
|
|
- Switch with the `MAIN PANE`, the largest, smallest, etc.
|
|
- Jump to the next and previous window
|
|
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
Install [GoldenView][GoldenView] is the *same as installing other vim plugins*. If experienced with vim, you can skim the example below and move to [next section](#quick-start).
|
|
|
|
|
|
### **Option A** - With [Plugin Manager][vim-plugin-manager] ( **recommended** )
|
|
|
|
If you use plugin managers like *Pathogen*, *vundle*, *neobundle*, *vim-addon-manager*, etc., just unarchive the zip file or clone the [GoldenView][GoldenView] repo from `git://github.com/zhaocai/GoldenView.git` into your local plugin installation directory (most likely `~/.vim/bundle/`). Then add corresponding scripts in .vimrc for the bundle manager you are using.
|
|
|
|
**Example**:
|
|
|
|
- *neobundle*:
|
|
|
|
```vim
|
|
NeoBundle 'zhaocai/GoldenView.Vim' "Always have a nice view for vim split windows
|
|
```
|
|
|
|
- *vundle*:
|
|
|
|
```vim
|
|
Bundle 'zhaocai/GoldenView.Vim'
|
|
```
|
|
|
|
- *vim-addon-manager*:
|
|
|
|
```vim
|
|
call vam#ActivateAddons(['GoldenView.Vim'], {'auto_install' : 1})
|
|
```
|
|
|
|
|
|
### **Option B** - Without [Plugin Manager][vim-plugin-manager]
|
|
|
|
Unarchive the zip file into a directory that is under `runtimepath` of your vim, `~/.vim` for example.
|
|
|
|
|
|
## Quick Start
|
|
[GoldenView][GoldenView] should work out of the box without configuration. It should automatically start to resize focused window to [golden ratio][golden-ratio-wikipedia] based on `textwidth` and vim available size. You may start to play with it now.
|
|
|
|
To get you started, a few default keys are mapped as below:
|
|
|
|
```vim
|
|
" 1. split to tiled windows
|
|
nmap <silent> <C-L> <Plug>GoldenViewSplit
|
|
|
|
" 2. quickly switch current window with the main pane
|
|
" and toggle back
|
|
nmap <silent> <F8> <Plug>GoldenViewSwitchMain
|
|
nmap <silent> <S-F8> <Plug>GoldenViewSwitchToggle
|
|
|
|
" 3. jump to next and previous window
|
|
nmap <silent> <C-N> <Plug>GoldenViewNext
|
|
nmap <silent> <C-P> <Plug>GoldenViewPrevious
|
|
|
|
```
|
|
|
|
The meaning of those keys are self-explaining. A general workflow would be `<Plug>GoldenViewSplit` key to quickly and nicely split windows to the layout as below. Then you may open your files.
|
|
|
|
```
|
|
----+----------------+------------+---+
|
|
| | | | |
|
|
| F | | S1 | T |
|
|
| I | +------------| A |
|
|
| L | | S2 | G |
|
|
| E | MAIN PANE +------------+ B |
|
|
| R | | S3 | A |
|
|
| | | | R |
|
|
| | | | |
|
|
+---+----------------+------------+---+
|
|
|
|
```
|
|
|
|
To switch `S1` with `MAIN PANE`, in `S1` and hit `<Plug>GoldenViewSwitchMain`. To switch back, hit `<Plug>GoldenViewSwitchToggle` in either `MAIN PAIN` or `S1`
|
|
|
|
#### g:goldenview__enable_default_mapping
|
|
|
|
Every experienced vim user has a different set of key mappings. If you you are (most likely) unhappy about some of the mappings, map you own keys as below:
|
|
|
|
```vim
|
|
let g:goldenview__enable_default_mapping = 0
|
|
|
|
nmap <silent> <MY_KEY> <Plug>GoldenViewSplit
|
|
" ... and so on
|
|
|
|
```
|
|
|
|
#### g:goldenview__enable_at_startup
|
|
|
|
if you do not want to start auto-resizing automatically, you can put the following script in your vimrc.
|
|
|
|
```vim
|
|
let g:goldenview__enable_at_startup = 0
|
|
```
|
|
|
|
## More Commands and Mappings
|
|
|
|
### `:ToggleGoldenViewAutoResize`
|
|
### `:DisableGoldenViewAutoResize`
|
|
### `:EnableGoldenViewAutoResize`
|
|
|
|
These commands toggle, enable, and disable GoldenView auto-resizing.
|
|
|
|
|
|
### `:GoldenViewResize`
|
|
this command do manual resizing of focused window.
|
|
|
|
You can also map a key for this as below:
|
|
|
|
```vim
|
|
nmap <silent> <YOUR_KEY> <Plug>GoldenViewResize
|
|
|
|
```
|
|
|
|
### `:SwitchGoldenViewMain`
|
|
### `:SwitchGoldenViewLargest`
|
|
### `:SwitchGoldenViewSmallest`
|
|
|
|
these commands do as it named.
|
|
|
|
You can also add mappings as below. ( no default keys for these mappings)
|
|
```vim
|
|
nmap <silent> <YOUR_KEY> <Plug>GoldenViewSwitchWithLargest
|
|
nmap <silent> <YOUR_KEY> <Plug>GoldenViewSwitchWithSmallest
|
|
|
|
```
|
|
|
|
Other switch rules can be easily defined. If you have some ideas, please post to [github issue][GoldenViewIssue] for discussion.
|
|
|
|
|
|
## Rules
|
|
|
|
[GoldenView][] defines two rules:
|
|
|
|
### `g:goldenview__ignore_urule`
|
|
is to "ignore" - allow those special buffers to manage their own window size.
|
|
|
|
### `g:goldenview__restore_urule`
|
|
is to "restore" - restore window size of some of special buffers.
|
|
|
|
The `urule` (user rules) are like this, which will be normalize at runtime for faster processing.
|
|
|
|
```vim
|
|
\{
|
|
\ 'filetype' : [
|
|
\ '' ,
|
|
\ 'qf' , 'vimpager', 'undotree', 'tagbar',
|
|
\ 'nerdtree', 'vimshell', 'vimfiler', 'voom' ,
|
|
\ 'tabman' , 'unite' , 'quickrun', 'Decho' ,
|
|
\ ],
|
|
\ 'buftype' : [
|
|
\ 'nofile' ,
|
|
\ ],
|
|
\ 'bufname' : [
|
|
\ 'GoToFile' , 'diffpanel_\d\+' ,
|
|
\ '__Gundo_Preview__' , '__Gundo__' ,
|
|
\ '\[LustyExplorer-Buffers\]' , '\-MiniBufExplorer\-' ,
|
|
\ '_VOOM\d\+$' , '__Urannotate_\d\+__' ,
|
|
\ '__MRU_Files__' ,
|
|
\ ],
|
|
\},
|
|
|
|
```
|
|
|
|
## Profiles
|
|
[GoldenView][] defines two profile:
|
|
|
|
### `g:goldenview__active_profile`
|
|
defines the functions and preferences to auto resize windows.
|
|
|
|
### `g:goldenview__reset_profile`
|
|
|
|
defines reset preferences to restore everything to default.
|
|
|
|
|
|
`function GoldenView#ExtendProfile()` is provided to customize preferences.
|
|
|
|
For more details, please read the source code! :)
|
|
|
|
|
|
|
|
## Troubleshooting:
|
|
|
|
### Please do not resize me!
|
|
|
|
[GoldenView][] maintains rules for "common" cases. But vim offers a great variety of plugins which defines buffers for special purposes. If you find some special buffers which is supposed to not be auto-resized. Please check `g:goldenview__ignore_urule`. You may extend the `g:goldenview__active_profile` yourself or post the issue to [github issue][GoldenViewIssue] for adding it to builtin support.
|
|
|
|
|
|
|
|
### [minibufexpl.vim][] takes 5+ lines
|
|
|
|
Check my fork [minibufexpl.vim][] to see if it is working for you. I have send pull request to the origin repo.
|
|
|
|
|
|
### I cannot resize window height to < 7
|
|
|
|
This is features. As mentioned in the [Introduction](#always-have-a-nice-view-for-vim-split-windows) section, there is no normal cases to have a normal window too small. For special cases like [minibufexpl.vim][], it can be handled case by case.
|
|
|
|
|
|
However, if you really want to have small windows. It can be done by :
|
|
|
|
```vim
|
|
|
|
" Extend a new profile named 'small-height' from default profile.
|
|
"
|
|
" 1. Change "2" to your desire minimal height
|
|
" 2. Change "small-height" to the profile name you like
|
|
" ---------------------------------------------------------------
|
|
call GoldenView#ExtendProfile('small-height', {
|
|
\ 'other_window_winheight' : 2 ,
|
|
\ })
|
|
|
|
let g:goldenview__active_profile = 'small-height'
|
|
```
|
|
|
|
(refer to issue #5)
|
|
|
|
### I still have Issues:
|
|
|
|
If you have any issues, please post it to [github issue][GoldenViewIssue] for discussion.
|
|
|
|
Remember to run the following command and post the results.
|
|
```vim
|
|
echo GoldenView#Info()
|
|
```
|
|
|
|
|
|
## Contributors
|
|
|
|
|
|
|
|
|
|
## RELEASE HISTORY
|
|
|
|
Refer to [History.md]( https://github.com/zhaocai/GoldenView.Vim/blob/master/History.md )
|
|
|
|
|
|
|
|
|
|
## LICENSE:
|
|
|
|
Copyright (c) 2013 Zhao Cai \<caizhaoff@gmail.com\>
|
|
|
|
This program is free software: you can redistribute it and/or modify it under
|
|
the terms of the GNU General Public License as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option)
|
|
any later version.
|
|
|
|
This program is distributed in the hope that it will be useful, but WITHOUT
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License along with
|
|
this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
|
|
|
|
|
|
[dwm]: http://www.vim.org/scripts/script.php?script_id=4186
|
|
[golden-ratio-plugin]: http://www.vim.org/scripts/script.php?script_id=3690
|
|
[golden-ratio-wikipedia]: http://en.wikipedia.org/wiki/Golden_ratio
|
|
[zl]: https://github.com/zhaocai/zl.vim "zl.vim vim script library"
|
|
[GoldenView]: http://zhaocai.github.io/GoldenView.Vim/ "GoldenView Homepage"
|
|
[GoldenViewCode]: https://github.com/zhaocai/GoldenView.Vim "GoldenView Vim Plugin"
|
|
[vim-plugin-manager]: http://vim-scripts.org/vim/tools.html "Vim Plugin Manangers"
|
|
[GoldenViewIssue]: https://github.com/zhaocai/GoldenView.Vim/issues "GoldenView Issue Track"
|
|
[minibufexpl.vim]: https://github.com/zhaocai/minibufexpl.vim
|
|
|