Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…


Cannot retrieve contributors at this time

file 453 lines (379 sloc) 20.732 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452
*gui_mac.txt* For Vim version 7.1. Last change: 2007 Nov 11


The MacVim Graphical User Interface *macvim* *gui-macvim*

0. Important! |macvim-important|
1. MacVim differences |macvim-differences|
2. Starting MacVim |macvim-start|
3. Special colors |macvim-colors|
4. Menus |macvim-menus|
5. Toolbar |macvim-toolbar|
6. Dialogs |macvim-dialogs|
7. System services |macvim-services|
8. Known bugs/missing features |macvim-todo|
9. Hints |macvim-hints|

Other relevant documentation:
|gui.txt| For generic items of the GUI.
|os_mac.txt| For Mac specific items.

{Vi does not have a GUI}

0. Important! *macvim-important*

MacVim is still under development...this is not the finished product! If you
have problems with MacVim then make it known either by adding an issue report
on the MacVim project page >
or by posting to the vim_mac mailing list *vim_mac* >

Remember to keep checking the project page for new snapshots. (If you
downloaded this copy from somewhere else, you might want to go there now to
make sure that you have got the latest version.)

1. MacVim differences *macvim-differences*

One of the goals of MacVim is to make Vim behave like a proper Mac OS X
application. For this reason MacVim behaves slightly different from other GUI
ports of Vim. Most of the modifications are provided in the system gvimrc
file; you can quickly open this file and look at it yourself by typing: >
:tabe $VIM/gvimrc
Note that this file will be overwritten each time you update MacVim, so it is
better to keep your own modifications inside "~/.gvimrc".

There is some confusion regarding the term "window" in MacVim since it means
one thing to Vim and another to MacVim. A "window" in Vim is what opens up
when you type ":sp", whereas a "window" in MacVim is the GUI window which
contains the text view, scrollbars, toolbar and tabline. To avoid confusion,
the former is referred to as a Vim-window, whereas the latter is simply called
a window.

It is not possible to modify 'termencoding' in MacVim; this option is forcibly
set to "utf-8". The option 'encoding' also defaults to "utf-8" (as opposed to
"latin1" in the other GUI ports).

Note: UTF-8 can represent all characters defined in Unicode, which includes
all characters in all other standard encodings, so it should be perfectly safe
to edit files in any encoding while 'encoding' is set to "utf-8". Of course,
you may need to set 'fileencodings' to auto-detect the encoding of the files
you edit, or force the detection with |++enc| on the command line.

However, if you are editing files that use multiple encodings (container
formats like MIME or Unix mbox files) or no standard encoding (binary data,
see also |edit-binary|), you may want to prevent MacVim from re-encoding the
file at all. In this situation, you will need to set both 'encoding' and
'fileencodings' to a simple single-byte encoding such as Latin1 so that when
the file is read into memory, the original bytes are left untouched.

Some Mac OS X standard key mappings involving Cmd or Option and an arrow key
are set up by default in "$VIM/gvimrc". You can quickly disable all of these
by adding the following lines to your "~/.vimrc" (not .gvimrc) file: >
if has("gui_macvim")
let macvim_skip_cmd_opt_movement = 1
Note: These are the only key mappings that MacVim makes (not counting menu key
equivalents which are not set up with :map).

Text editors on Mac OS X lets the user hold down shift+movement key to extend
the selection. Also, pressing a printable key whilst selecting replaces the
current selection with that character. MacVim can emulate this kind of
behaviour (by providing key bindings and by setting 'keymodel' and
'selectmode' to non-default values) although it is not enabled by default. To
make MacVim behave more like TextEdit and less like Vim, add the following
lines to your "~/.vimrc" (not .gvimrc) file: >
if has("gui_macvim")
let macvim_hig_shift_movement = 1
Dragging files and dropping them on a window opens those files in tabs in that
window, unless Vim is in command-line mode. In command-line mode the names of
the files are added to the command line. Holding down modifier keys whilst
dragging is not supported.

If a file is dropped on the Dock icon, it is always opened in a new tab
regardless of the mode Vim is currently in. The same holds if you
double-click on a file in the Finder.

The default menu in MacVim has been changed to conform better with the Apple
Human Interface Guidelines (HIG). At the moment this breaks the localized
menus, so only English menus are supported.

Note: The menus are a work in progress. If you know something about the HIG
and want to contribute to MacVim you could do so by making the menus better.

The default window title does not include the argument list because it looks
really bad once you start using tabs. For example, dropping two files, then
dropping two more, and switching back to the first tab would cause weird
strings like "((3) of 2)" to appear in the window title.

These are the non-standard options that MacVim supports:
'fullscreen' 'toolbariconsize' 'transparency'

2. Starting MacVim *macvim-start*

The easiest way to start MacVim is by double-clicking its icon in the Finder,
but most users will probably prefer to use the Terminal. First some Finder
related ways of starting MacVim are described, then Terminal is discussed.
Note that you can put MacVim anywhere on your hard drive, but in this help
file it is assumed that you have put it inside your /Applications folder.

MacVim automatically registers itself as an editor of several standard file
formats. This enables you to double-click a file to open it with MacVim (if
it is not associated with another program), or to right-click a file to bring
up the "Open with" menu. You can also drag and drop files onto the Dock icon
to open them in tabs in a new window, or you can drop them in an already open
window to open the files in tabs in that specific window. Finally, you can
use Mac OS X System Services to open files in MacVim, see |macvim-services|.

There are essentially two ways to start MacVim from Terminal: either call the
Vim binary with the -g switch >
/Applications/ -g file ...
or use the "open" command (which is of limited use since it cannot be used to
pass parameters to Vim) >
open -a MacVim file ...
To save yourself from having to type the entire path to the Vim binary each
time you start MacVim, you could create an alias such as >
alias gvim='/Applications/ -g'
and add that to "~/.profile". A more flexible way to start MacVim is to use
the shell script "mvim" which comes bundled with MacVim. Put this script in a
folder in your path and then simply type "mvim" to start MacVim. This script
will try to find in various typical folders such as >
~/Applications ~/Applications/vim
/Applications /Applications/vim
/Applications/Utilities /Applications/Utilities/vim
If you would rather put in some other directory then that is also
possible, simply set the environment variable VIM_APP_DIR to whatever folder
you have placed in.

Note: Starting MacVim by creating a symlink to >
with 'ln -s' does not work.

Once in terminal Vim it is possible to start MacVim by using the following
:gui [++opt] [+cmd] [-f|-b] [files...]
Note: Forking ("-b") currently does not work.

*odbeditor* *external-editor*
MacVim can act as an 'external editor' for Mac OS X applications that support
the ODB Editor Protocol (or the 'external editor' protocol). Each application
has different ways of configuring this option, check the applications
documentation. Once configured properly MacVim can be used to open files in
such an application.

A technical note: MacVim handles file open, modified and closed events. In
the open event the FTok and Burl parameters are parsed (the latter is ignored
at the moment though). In the modified and closed events the Tokn parameter
is sent back to the server application.

3. Special colors *macvim-colors*

The colors in MacVim are defined in two dictionaries inside the "Resources"
folder of the application bundle ( It is
possible to add more colors by modifying these files. Color names are case
insensitive when accessed from Vim, but in the dictionary they must be

There are only a few system colors that can be accessed from Vim. These
colors are defined in the dictionary "SystemColors.plist". This dictionary
stores (key, value) pairs where the key is the name of the color and the
value is an NSColor selector name.

The most useful system colors are: >
The former is the "Highlight Color" which can be changed in the "Appearance"
section of the System Preferences. The latter is the selection color used by
a Cocoa application when it is not in focus.

Apart from the system colors, it is also possible to use the standard X11
color names (see which usually
come in a file called "rgb.txt". MacVim does not have such a file, instead it
keeps these colors in a dictionary called "Colors.plist". The key in this
dictionary is the name of the color and the value is an RGB value on the form
#rrggbb stored as an integer.

MacVim ships with a custom colorscheme that can be used as an alternative to
the default Vim colorscheme. You can try it out by typing: >
:colorscheme macvim
The colorscheme uses the the system "Highlight Color", which can be changed in
the "Appearance" pane of the System Preferences. It also changes the
highlight color when a window becomes inactive.

If you have any comments regarding this colorscheme (is it better or worse
than the default?) then post them to |vim_mac|.

4. Menus *macvim-menus*

*:macm* *:macmenukey*
MacVim has a special way of binding keys to menu items that differs from other
Vim GUI ports. A menu binding is called a "key equivalent" in Mac OS X
terminology, this is displayed on the right side of a menu item. The
":macmenukey" command is used to set the key equivalent of a menu item. This
command takes two parameters, the first names the menu item to bind to, the
second gives the key combination. For example: >
:macmenukey File.New\ Tab <D-t>
This sets the key equivalent of the "New Tab" menu item under the "File" menu
to Cmd+t.

Note that key equivalents:
* must contain the Cmd modifier flag (<D-...>)
* take precedence over normal mappings made with ":map"
* can only be modified during startup (e.g. in .gvimrc)

It is possible to reset a key equivalent by calling :macmenukey with a menu
name but no key. This is so that the default key equivalents can be reset in
"~/.gvimrc". For example, if you would like to free up <D-s> (which is the
key equivalent of "File.Save") then add the following line to "~/.gvimrc": >
macmenukey File.Save
Now you can use :map to bind <D-s> to whatever you like.

It is not necessary to reset a key equivalent if all you want to do is to
change the key equivalent of a menu item. For example, say you want to use
<D-M-Right> as the key equivalent for "Next Tab", then add the following line
to "~/.gvimrc": >
macmenukey Window.Next\ Tab <D-M-Right>
*:maca* *:macaction*
It is typical for menu items in Cocoa applications to bind to Objective-C
selectors. To support this, MacVim introduces the ":macaction" command. This
command takes the name of an action message as its only parameter. (An action
message is an Objective-C message with "void" return type and a single
parameter of type "id".) For example, the "New Window" menu item on the
"File" menu is created in the following manner: >
:an 10.290 File.New\ Window :macaction newWindow:<CR>

Note 1: A menu item which is bound to ":macaction" will automatically be bound
to that action in all modes (as if ":an" was used). It is not possible to
bind to ":macaction" in one mode only.
Note 2: The action is "nil-targeted", which means it is passed down the first
responder chain.

Some action messages would not be suitable to call from within Vim, so there
is a dictionary called "Actions.plist" (in the Resources folder of the
application bundle) which contains all actions that may be called. The key in
this dictionary is the name of the action message (case sensitive), the value
is not used.

Here is a random assortment of actions from Actions.plist which might be

Action Description ~
fontSizeDown: Decrease font size
fontSizeUp: Increase font size
newWindow: Open a new (empty) window
orderFrontCharacterPalette: Show the the "Special Characters" dialog
orderFrontFontPanel: Show the Font panel
performZoom: Zoom window (same as clicking the green blob)
selectNextWindow: Select next window (similar to <D-`>)
selectPreviousWindow: Select previous window (similar to <S-D-`>)

As an example, to map <C-z> to performZoom: you could do something like this: >
:map <silent> <C-z> :macaction performZoom:<CR>
A better way to map to performZoom: would be to set the key equivalent of the
menu item "Window.Zoom" to the above action. This can be done by adding the
following line to "~/.gvimrc": >
macmenukey Window.Zoom <D-C-z>
(Note that key equivalents must contain the 'D' flag.)

5. Toolbar *macvim-toolbar*

The toolbar in MacVim works just like in the other GUIs (see |gui-toolbar|),
with the addition of two separator items (see |menu-separator|). You can use
them as follows: >
:an ToolBar.-space1- <Nop>
:an ToolBar.-flexspace2- <Nop>
The first example creates an empty space on the toolbar, the second creates an
empty space which will shink or expand so that the items to the right of it
are right-aligned. A space (flexspace) will be created for any toolbar item
whose name begins with "-space" ("-flexspace") and ends with "-"

Note: Only a subset of the builtin toolbar items presently have icons. If no
icon can be found a warning triangle is displayed instead.

6. Dialogs *macvim-dialogs*

Dialogs can be controlled with the keyboard in two ways. By default each
button in a dialog is bound to a key. The button that is highlighted by blue
is bound to Enter, and any button with the title "Cancel" is bound to Escape.
Other buttons are usually bound to the first letter in the title of the
button. There is no visual feedback to indicate which letter a button is
bound to, so sometimes some experimentation might be required in order to
figure out which key to press.

The second way of controlling dialogs with the keyboard is to enable "Full
keyboard access" in the "Keyboard & Mouse" pane of the System Preferences (you
can also toggle this on or off by pressing Ctrl-F7). Once keyboard access is
enabled it is possible to move between buttons with Tab and pressing Space to
select the current button. The current button is indicated with a blue

7. System services *macvim-services*

MacVim supports a few system services. These can be accessed from the MacVim
submenu in the Services menu. For services to work, should be
located in the /Applications folder. (You might have to logout and then login
again before Mac OS X detects the MacVim services.)

These are the currently supported services:
* New Tab Containing Selection: Opens a new tab in the topmost window and
  pastes the currently selected text in that tab. A new window will be
  opened if necessary.
* Open Selected File in Tab: If the selected text represents a file
  name, then the corresponding file is opened in a new tab in the topmost
* Open Selected File in Window: Same as the above, but always open in a new

8. Known bugs/missing features *macvim-todo*

Here are some of the bigger bugs in MacVim. Of course there are others, but
these are ones that are know and/or which were judged major.

- Localized menus are not supported. Choosing anything but "English" in the
  "International" pane of "System Prefences" may break the menus (and
- Some Unicode characters are not handled well (e.g. nonspacing marks)
- Sometimes multibyte characters look "too wide", i.e. they overlap the
  following character. It might help to change 'ambiwidth', or override the
  automatic font substitution by setting 'guifontwide' manually.
- Printing
- No find/replace dialog

If you find new bugs then add a new issue at
or post your findings to the |vim_mac| mailing list. If you are missing
feature X in MacVim then voice your opinion on the |vim_mac| mailing list; it
might be simple to implement, but unless somebody asks for a particular
feature then there is little incentive to add it.

9. Hints *macvim-hints*

In this section some general (not necessarily MacVim specific) hints are

Scenario: ~
You try opening a bunch of files in tabs but not all files get
opened in their own tab.
Solution: ~
To get around this, set 'tabpagemax' to something big in your
.gvimrc file (e.g. ":set tabpagemax=100").

Scenario: ~
You want to open a file in a tab in an already opened window, but typing
"mvim filename" in Terminal opens it up in a separate window.
Solution: ~
Use the |--remote-tab| switch. If you have several windows open you
might have to specify which window you want the file to open in by using the
|--servername| switch. The title of a window usually ends in something like
"VIM" or "VIM3" --- this is the server name of that window. So to open a file
named "foobar.txt" in a window whose title ends in "VIM3" you would type (the
order of the arguments matters): >
mvim --servername VIM3 --remote-tab foobar.txt
For more information, consult the |client-server| manual page.

Scenario: ~
You like to be able to select text by holding down shift and
pressing the arrow keys and find the Vim way of selecting text strange.
Solution: ~
See |macvim-shift-movement|.

Scenario: ~
You do not want MacVim to set up any key mappings.
Solution: ~
See |macvim-movement|.

Scenario: ~
Enabling localized menus breaks the toolbar and the menus as well.
Solution: ~
This is a know problem, see |macvim-todo|.

Scenario: ~
You dislike the default font (DejaVu Sans Mono).
Solution: ~
The standard fixed width font on other Mac OS X applications is
Monaco. If you prefer this font then add the following line to your
"~/.gvimrc" (note that Monaco does not come in italic and bold variants): >
set guifont=Monaco:h10
The suffix ":h10" specifies the point size of the font should be "10" (see
'guifont' for more information on how to set the font).

Scenario: ~
When you click the (green) zoom button you want the window to maximize
horizontally as well as vertically.
Solution: ~
Hold down Cmd and click the zoom button.

Scenario: ~
Typing feels sluggish when the cursor is just before a right bracket (i.e. ')',
'}', or ']').
Solution: ~
Disable the "matchparen" plugin (see |matchparen|) by typing :NoMatchParen.
If that helps, then you can permanently disable "matchparen" by adding the
following line to your "~/.vimrc": >
let loaded_matchparen=1

Scenario: ~
You can't find the information on MacVim you thought should be in
this manual page.
Solution: ~
Post your question on the |vim_mac| mailing list and wait for an

Something went wrong with that request. Please try again.