| blob | 64442388d404b84c8172399bcce817e8f011bd10 |
1 *gui_mac.txt* For Vim version 7.2. Last change: 2009 Sep 23
4 VIM REFERENCE MANUAL by Bjorn Winckler
7 The MacVim Graphical User Interface *macvim* *gui-macvim*
9 0. Important! |macvim-important|
10 1. MacVim differences |macvim-differences|
11 2. Starting MacVim |macvim-start|
12 3. Preferences |macvim-preferences|
13 4. Special colors |macvim-colors|
14 5. Menus |macvim-menus|
15 6. Toolbar |macvim-toolbar|
16 7. Dialogs |macvim-dialogs|
17 8. System services |macvim-services|
18 9. mvim:// URL handler |macvim-url-handler|
19 10. Keyboard shortcuts |macvim-shortcuts|
20 11. International |macvim-international|
21 12. Known bugs/missing features |macvim-todo|
22 13. Hints |macvim-hints|
24 Other relevant documentation:
25 |gui.txt| For generic items of the GUI.
27 {Vi does not have a GUI}
29 ==============================================================================
30 0. Important! *macvim-important*
32 MacVim is still under development...this is not the finished product! If you
33 have problems with MacVim then make it known either by adding an issue report
34 on the MacVim project page >
35 http://code.google.com/p/macvim
36 or by posting to the vim_mac mailing list *vim_mac* >
37 http://groups.google.com/group/vim_mac
39 Remember to keep checking the project page for new snapshots or use the
40 automatic updating feature which can be enabled in the preferences pane. (If
41 you downloaded this copy from somewhere else, you might want to go there now
42 to make sure that you have got the latest version.)
44 ==============================================================================
45 1. MacVim differences *macvim-differences*
47 One of the goals of MacVim is to make Vim behave like a proper Mac OS X
48 application. For this reason MacVim behaves slightly different from other GUI
49 ports of Vim. Most of the modifications are provided in the system gvimrc
50 file; you can quickly open this file and look at it yourself by typing: >
51 :tabe $VIM/gvimrc
52 Note that this file will be overwritten each time you update MacVim, so it is
53 better to keep your own modifications inside "~/.gvimrc".
55 *macvim-windows*
56 There is some confusion regarding the term "window" in MacVim since it means
57 one thing to Vim and another to MacVim. A "window" in Vim is what opens up
58 when you type ":sp", whereas a "window" in MacVim is the GUI window which
59 contains the text view, scrollbars, toolbar and tabline. To avoid confusion,
60 the former is referred to as a Vim-window, whereas the latter is simply called
61 a window.
63 *macvim-encoding*
64 It is not possible to modify 'termencoding' in MacVim; this option is forcibly
65 set to "utf-8". The option 'encoding' also defaults to "utf-8" (as opposed to
66 "latin1" in the other GUI ports).
68 Note: UTF-8 can represent all characters defined in Unicode, which includes
69 all characters in all other standard encodings, so it should be perfectly safe
70 to edit files in any encoding while 'encoding' is set to "utf-8". Of course,
71 you may need to set 'fileencodings' to auto-detect the encoding of the files
72 you edit, or force the detection with |++enc| on the command line.
74 However, if you are editing files that use multiple encodings (container
75 formats like MIME or Unix mbox files) or no standard encoding (binary data,
76 see also |edit-binary|), you may want to prevent MacVim from re-encoding the
77 file at all. In this situation, you will need to set both 'encoding' and
78 'fileencodings' to a simple single-byte encoding such as Latin1 so that when
79 the file is read into memory, the original bytes are left untouched.
81 *macvim-shift-movement*
82 Text editors on Mac OS X lets the user hold down shift+movement key to extend
83 the selection. Also, pressing a printable key whilst selecting replaces the
84 current selection with that character. MacVim can emulate this kind of
85 behaviour (by providing key bindings and by setting 'keymodel' and
86 'selectmode' to non-default values) although it is not enabled by default. To
87 make MacVim behave more like TextEdit and less like Vim, add the following
88 lines to your "~/.vimrc" (not .gvimrc) file: >
89 if has("gui_macvim")
90 let macvim_hig_shift_movement = 1
91 endif
92 <
93 *macvim-drag-n-drop*
94 Dragging files and dropping them on a window opens those files in tabs in that
95 window, unless Vim is in command-line mode. In command-line mode the names of
96 the files are added to the command line. Holding down modifier keys whilst
97 dragging is not supported.
99 If a file is dropped on the Dock icon, it is always opened in a new tab
100 regardless of the mode Vim is currently in. The same holds if you
101 double-click on a file in the Finder.
103 The "Open files from applications" preference in the General preference pane
104 gives more options on how dropped files should open, in case tabs are not
105 desired.
107 *macvim-default-menu*
108 The default menu in MacVim has been changed to conform better with the Apple
109 Human Interface Guidelines (HIG). At the moment this breaks the localized
110 menus, so only English menus are supported.
112 Note: The menus are a work in progress. If you know something about the HIG
113 and want to contribute to MacVim you could do so by making the menus better.
115 *macvim-window-title*
116 The default window title does not include the argument list because it looks
117 really bad once you start using tabs. For example, dropping two files, then
118 dropping two more, and switching back to the first tab would cause weird
119 strings like "((3) of 2)" to appear in the window title.
121 *macvim-tablabel*
122 Tab labels only show the tail of the file name to make the tabs more readable
123 when editing files in deeply nested folders. Add the line "set guitablabel="
124 to your .gvimrc file to revert back to the default Vim tab label.
126 *macvim-options*
127 These are the non-standard options that MacVim supports:
128 'antialias' 'fullscreen' 'fuoptions'
129 'macmeta' 'toolbariconsize' 'transparency'
131 *macvim-commands*
132 These are the non-standard commands that MacVim supports:
133 |:macaction| |:macmenu|
135 *macvim-find*
136 Whenever you search for something in Vim (e.g. using "/") the search query is
137 copied to the OS X "Find Pasteboard". The idea is that if you search for
138 something and switch to another application, then you can hit <D-g> (or <D-G>)
139 to repeat the search in the new app. The same feature works if you search in
140 some app, switch to MacVim and hit <D-g>.
142 Note that the command |n| is not the same as <D-g>. The former will repeat
143 the last search made in Vim, whereas the latter searches for the string on the
144 OS X Find Pasteboard using the action findNext: (see |:macaction|).
146 The <D-g> key equivalent is a great way to bring a search from one window to
147 another in MacVim. Simply search for something in one window (using "/") then
148 switch to another (e.g. with <D-`>) and hit <D-g> and the search will be
149 repeated in the new window.
151 *macvim-backspace* *macvim-delete*
152 The 'backspace' option is set in the system vimrc to make the delete key
153 behave in a more familiar way to new users. If you dislike this non-default
154 behaviour, then add the line "set backspace&" to your "~/.vimrc" file.
156 ==============================================================================
157 2. Starting MacVim *macvim-start*
159 The easiest way to start MacVim is by double-clicking its icon in the Finder,
160 but most users will probably prefer to use the Terminal. First some Finder
161 related ways of starting MacVim are described, then Terminal is discussed.
162 Note that you can put MacVim anywhere on your hard drive, but in this help
163 file it is assumed that you have put it inside your /Applications folder.
165 MacVim automatically registers itself as an editor of several standard file
166 formats. This enables you to double-click a file to open it with MacVim (if
167 it is not associated with another program), or to right-click a file to bring
168 up the "Open with" menu. You can also drag and drop files onto the Dock icon
169 to open them in tabs in a new window, or you can drop them in an already open
170 window to open the files in tabs in that specific window (it is possible to
171 have files open in e.g. splits by changing the "Open files from applications"
172 option in the General preference pane). Finally, you can use Mac OS X System
173 Services to open files in MacVim, see |macvim-services|.
175 There are essentially two ways to start MacVim from Terminal: either call the
176 Vim binary with the -g switch >
177 /Applications/MacVim.app/Contents/MacOS/Vim -g file ...
178 or use the "open" command (this method can not be used to pass parameters to
179 Vim) >
180 open -a MacVim file ...
181 The advantage of using the latter method is that the settings relating to file
182 opening in the preferences panel are respected, and files open instantly if
183 |Quickstart| is enabled.
185 To save yourself from having to type the entire path to the Vim binary each
186 time you start MacVim, you could create an alias such as >
187 alias gvim='/Applications/MacVim.app/Contents/MacOS/Vim -g'
188 and add that to "~/.profile".
190 *mvim*
191 A more flexible way to start MacVim is to use the shell script "mvim" which
192 comes bundled with MacVim. Put this script in a folder in your path and then
193 simply type "mvim" to start MacVim. This script will try to find MacVim.app
194 in various typical folders such as >
195 ~/Applications ~/Applications/vim
196 /Applications /Applications/vim
197 /Applications/Utilities /Applications/Utilities/vim
198 If you would rather put MacVim.app in some other directory then that is also
199 possible, simply set the environment variable VIM_APP_DIR to whatever folder
200 you have placed MacVim.app in.
202 The "mvim" script can be symlinked to in order to start up MacVim in different
203 modes as follows (assuming you placed "mvim" in "/usr/local/bin"): >
204 * Diff: ln -s /usr/local/bin/mvim mvimdiff
205 * Read-only: ln -s /usr/local/bin/mvim mview
206 * Ex: ln -s /usr/local/bin/mvim mex
207 * Restricted: ln -s /usr/local/bin/mvim rmvim
208 If the symlink destination starts with "m" (or "g"), Vim will start in GUI
209 mode. Removing the initial "m" from the above destination names makes Vim
210 start without the GUI. (In the last case, the destination name can be
211 "rmvim", "rgvim" or "rvim".)
213 Note: Starting MacVim by creating a symlink to >
214 .../MacVim.app/Contents/MacOS/Vim
215 with 'ln -s' does not work.
217 Once in terminal Vim it is possible to start MacVim by using the following
218 command:
219 :gui [++opt] [+cmd] [-f|-b] [files...]
220 Note: Forking ("-b") currently does not work.
222 *Quickstart*
223 Quickstart ensures that new windows open instantaneously e.g. when <D-n> is
224 pressed. This feature can be enabled from the Advanced preferences pane (it
225 is disabled by default). Note that this setting does not affect the speed
226 with which windows open when using the |mvim| command.
228 The main reason why this feature is not enabled by default is because on OS X
229 10.4 changes to runtime files (e.g. those in "~/.vim") are not detected. For
230 example, if you install a new plugin and then press <D-n> to open a new
231 window, then that first window will not notice the plugin (but any consecutive
232 windows after the first one will). On OS X 10.5 and later all modifications
233 to runtime files in "~/.vim" are detected, so unless you keep runtime files in
234 another folder there should be no problems.
236 *odbeditor* *external-editor*
237 MacVim can act as an 'external editor' for Mac OS X applications that support
238 the ODB Editor Protocol (or the 'external editor' protocol). Each application
239 has different ways of configuring this option, check the application's
240 documentation. Once configured properly MacVim can be used to open files in
241 such an application.
243 A technical note: MacVim handles file open, modified and closed events. In
244 the open event the FTok and Burl parameters are parsed (the latter is ignored
245 at the moment though). In the modified and closed events the Tokn parameter
246 is sent back to the server application.
248 ==============================================================================
249 3. Preferences *macvim-prefs* *macvim-preferences*
251 Some settings are global to the MacVim application and would not make sense as
252 Vim options. These settings are stored in a user default database and can be
253 accessed via the "MacVim.Preferences..." menu item.
255 *macvim-user-defaults*
256 Not all entries in the user defaults database are exposed via the preference
257 panel, usually because they should not be changed by the user under normal
258 circumstances. These options can still be changed with the "defaults" command
259 by opening Terminal and typing >
260 defaults write org.vim.MacVim KEY VALUE
261 Check the man page on "defaults" for more information on this command as well
262 as general information regarding Mac OS X user defaults.
264 Here is a list of relevant dictionary entries:
266 KEY VALUE ~
267 MMCellWidthMultiplier width of a normal glyph in em units [float]
268 MMDialogsTrackPwd open/save dialogs track the Vim pwd [bool]
269 MMLoadDefaultFont load font (disable for faster startup) [bool]
270 MMLoginShellArgument login shell parameter [string]
271 MMLoginShellCommand which shell to use to launch Vim [string]
272 MMNoFontSubstitution disable automatic font substitution [bool]
273 MMShowAddTabButton enable "add tab" button on tabline [bool]
274 MMTabMaxWidth maximum width of a tab [int]
275 MMTabMinWidth minimum width of a tab [int]
276 MMTabOptimumWidth default width of a tab [int]
277 MMTextInsetBottom text area offset in pixels [int]
278 MMTextInsetLeft text area offset in pixels [int]
279 MMTextInsetRight text area offset in pixels [int]
280 MMTextInsetTop text area offset in pixels [int]
281 MMTexturedWindow use brushed metal window (Tiger only) [bool]
282 MMTranslateCtrlClick interpret ctrl-click as right-click [bool]
283 MMVerticalSplit files open in vertical splits [bool]
284 MMZoomBoth zoom button maximizes both directions [bool]
286 As an example, if you have more than one mouse button and would wish to free
287 up Ctrl-click so you can bind it to something else, then the appropriate
288 command is: >
289 defaults write org.vim.MacVim MMTranslateCtrlClick 0
291 If you wish to restore all user defaults to their starting values, open
292 Terminal and type: >
293 defaults delete org.vim.MacVim
294 <
295 *macvim-login-shell*
296 Applications opened from the Finder do not automatically source the user's
297 environment variables (which are typically set in .profile or .bashrc). This
298 presents a problem when using |:!| to execute commands in the shell since e.g.
299 $PATH might not be set properly. To work around this problem MacVim starts
300 new Vim processes via a login shell so that all environment variables are set.
302 By default MacVim uses the $SHELL environment variable to determine which
303 shell to use (if $SHELL is not set "/bin/bash" is used). It is possible to
304 override this choice by setting the user default MMLoginShellCommand to the
305 shell that should be used (e.g. "/bin/tcsh"). MacVim tries to make the shell
306 a login shell by prepending argv[0] with a dash. If you use an exotic shell
307 and need to pass it a parameter to make it a login shell then you can set the
308 user default MMLoginShellArgument (e.g. to "-l"). Finally, if the "bash"
309 shell is used, then "-l" is automatically added as an argument. To override
310 this behaviour set MMLoginShellArgument to "--".
312 ==============================================================================
313 4. Special colors *macvim-colors*
315 The colors in MacVim are defined in two dictionaries inside the "Resources"
316 folder of the application bundle (MacVim.app/Contents/Resources). It is
317 possible to add more colors by modifying these files. Color names are case
318 insensitive when accessed from Vim, but in the dictionary they must be
319 lowercase.
321 *SystemColors.plist*
322 There are only a few system colors that can be accessed from Vim. These
323 colors are defined in the dictionary "SystemColors.plist". This dictionary
324 stores (key, value) pairs where the key is the name of the color and the
325 value is an NSColor selector name.
327 The most useful system colors are: >
328 MacSelectedTextBackgroundColor
329 MacSecondarySelectedColor
330 The former is the "Highlight Color" which can be changed in the "Appearance"
331 section of the System Preferences. The latter is the selection color used by
332 a Cocoa application when it is not in focus.
334 *Colors.plist*
335 Apart from the system colors, it is also possible to use the standard X11
336 color names (see http://en.wikipedia.org/wiki/X11_color_names) which usually
337 come in a file called "rgb.txt". MacVim does not have such a file, instead it
338 keeps these colors in a dictionary called "Colors.plist". The key in this
339 dictionary is the name of the color and the value is an RGB value on the form
340 #rrggbb stored as an integer.
342 *macvim-colorscheme*
343 MacVim ships with a custom color scheme that is used instead of the default
344 Vim color scheme. The color scheme can be changed with >
345 :colorscheme macvim
346 If you prefer a dark background color, then type >
347 :set bg=dark
348 after having loaded the "macvim" color scheme.
350 The color scheme uses the the system "Highlight Color", which can be changed in
351 the "Appearance" pane of the System Preferences. It also changes the
352 highlight color when a window becomes inactive.
354 If you have any comments regarding this color scheme (is it better or worse
355 than the default?) then post them to |vim_mac|.
357 ==============================================================================
358 5. Menus *macvim-menus*
360 Menus in Mac OS X behave slightly different from other platforms. For that
361 reason two new commands have been added to Vim. To understand what these
362 commands do you must first understand how menus work on OS X.
364 Each entry in a menu is called a "menu item". With each menu item is
365 associated: a title, a key equivalent and an action message. When a menu is
366 displayed the title is shown on the left and the key equivalent (if any) is
367 shown on the right. Key equivalents enable you to access a menu item using
368 the keyboard instead of having to use the mouse. When a menu item is clicked
369 it will send it's associated action message. Actions can be used to instruct
370 MacVim to paste some text (paste:), open a new window (newWindow:), etc.
371 Certain actions are standard throughout OS X which is why MacVim must be able
372 to set these for each menu item. (E.g. the menu item "Edit.Paste" must be
373 bound to the action "paste:" otherwise pasting won't work in dialogs since
374 that is the action that instructs them to paste something.)
376 Menus are configured using the |:macmenu| command and the |:macaction| command
377 can be used to send action messages.
379 *:maca* *:macaction*
380 :maca[ction] {action:} Send the message "action:" to the first responder.
381 The list of allowed actions can be seen by typing
382 :maca <C-d>
383 An attempt to send an action not listed here will
384 result in an error. This list is specified in a
385 property list file called |Actions.plist|.
387 *:macm* *:macmenu*
388 :macm[enu] {menu} {key}={arg} ...
389 Set Mac specific properties for {menu}. The
390 properties that can be set are:
391 action the action this menu sends
392 alt "yes" if alternate of previous menu
393 key the key equivalent of this menu
394 This command must be used in a startup file, for
395 example in "~/.gvimrc". It has no effect otherwise.
397 For convenience, a menu with "action=name:" which is
398 bound to <Nop> will act as if bound to
399 ":maca name:<CR>". Thus, if "Menu.Item" is given by
400 :an Menu.Item <Nop>
401 :macm Menu.Item action=name:
402 then ":emenu Menu.Item" is equivalent to
403 ":maca name:".
405 The key equivalent is specified with the <D-..>
406 syntax. This is case-sensitive, so <D-a> means Cmd-a
407 whereas <D-A> means Cmd-Shift-a.
408 Note that key equivalents must contain the Cmd
409 modifier flag (<D-..>), and they take precedence over
410 normal mappings.
411 Use the syntax "key=<nop>" to clear the key equivalent
412 of a menu. This can be used to free up a key
413 combination that is set in the system gvimrc so that
414 it may be mapped to using ":map".
416 Recognised values of "alt" are "0", "no", "1", and
417 "yes". The default is "no". An alternate menu must
418 have the same key equivalent as the previous menu,
419 except the modifier flags must differ. The alternate
420 menu is by default hidden and only shows up when the
421 modifier is held down.
423 Here are some examples on how to use these commands:
425 1. Create a menu item with title "New Window" under the "File" menu, with key
426 equivalent Cmd-n, which opens a new window when selected: >
427 :an 10.290 File.New\ Window <Nop>
428 :macm File.New\ Window action=newWindow: key=<D-n>
429 2. Change the key equivalent to cycle through tabs to Cmd-Left/Right: >
430 :macm Window.Previous\ Tab key=<D-Left>
431 :macm Window.Next\ Tab key=<D-Right>
432 3. Create a mapping in normal mode which closes the current tab/window: >
433 :map <C-w> :maca performClose:<CR>
434 4. Free up Cmd-t and remap it to open a file browser in a split view: >
435 macm File.New\ Tab key=<nop>
436 nmap <D-t> :sp .<CR>
437 Note: These two lines must be added to .gvimrc else the first line will fail.
438 The second line is case sensitive, so <D-T> (Cmd-Shift-t) is not the same as
439 <D-t> (Cmd-t)!
441 The standard Vim menus are modified in "$VIM/gvimrc". Take a look at that
442 file for more examples on how to set up menus. Note: When no window is open a
443 minimal default menu is used. The default menu is set up in MainMenu.nib
444 which resides in "Resources/English.lproj/" folder inside the app bundle.
446 *Actions.plist*
447 Some action messages would not be suitable to call from within Vim, so there
448 is a dictionary called "Actions.plist" (in the Resources folder of the
449 application bundle) which contains all actions that may be called. The key in
450 this dictionary is the name of the action message (case sensitive), the value
451 is not used.
453 Hint: The |:macaction| command supports command-line completion so you can
454 enter ":maca<Space><C-d>" to see a list of all available actions.
456 Here is a random assortment of actions from Actions.plist which might be
457 useful.
459 Action Description ~
460 fileOpen: Show "File Open" dialog
461 findNext: Search forward using the "Find Pasteboard"
462 findPrevious: Search backward using the "Find Pasteboard"
463 fontSizeDown: Decrease font size
464 fontSizeUp: Increase font size
465 hide: Hide MacVim
466 miniaturizeAll: Minimize all windows to the dock
467 newWindow: Open a new (empty) window
468 orderFrontCharacterPalette: Show the the "Special Characters" dialog
469 orderFrontFontPanel: Show the Font panel
470 orderFrontPreferencePanel: Show the Preferences panel
471 performMiniaturize: Minimize window to the dock
472 performZoom: Zoom window (same as clicking the green blob)
473 terminate: Quit MacVim
474 zoomAll: Zoom all windows
475 _cycleWindows: Select next window (similar to <D-`>)
476 _cycleWindowsBackwards: Select previous window (similar to <D-S-`>)
478 ==============================================================================
479 6. Toolbar *macvim-toolbar*
481 The toolbar in MacVim works just like in the other GUIs (see |gui-toolbar|),
482 with the addition of two separator items (see |menu-separator|). You can use
483 them as follows: >
484 :an ToolBar.-space1- <Nop>
485 :an ToolBar.-flexspace2- <Nop>
486 The first example creates an empty space on the toolbar, the second creates an
487 empty space which will shink or expand so that the items to the right of it
488 are right-aligned. A space (flexspace) will be created for any toolbar item
489 whose name begins with "-space" ("-flexspace") and ends with "-"
491 Toolbar icons should be tiff, png or icns, of dimension 32x32 or 24x24 pixels.
492 The larger size is used when 'tbis' is "medium" or "large", otherwise the
493 smaller size is used (which is the default). If the icon file only contains
494 one dimension then Mac OS X will scale the icon to the appropriate dimension
495 if necessary. To avoid this, use a file format which supports multiple
496 resolutions (such as icns) and provide both 32x32 and 24x24 versions of the
497 icon.
499 Note: Only a subset of the builtin toolbar items presently have icons. If no
500 icon can be found a warning triangle is displayed instead.
502 ==============================================================================
503 7. Dialogs *macvim-dialogs*
505 Dialogs can be controlled with the keyboard in two ways. By default each
506 button in a dialog is bound to a key. The button that is highlighted by blue
507 is bound to Enter, any button with the title "Cancel" is bound to Escape, and
508 any button with the title "Don't Save" is bound to <D-d>. Other buttons are
509 usually bound to the first letter in the title of the button. There is no
510 visual feedback to indicate which letter a button is bound to, so sometimes
511 some experimentation might be required in order to figure out which key to
512 press.
514 The second way of controlling dialogs with the keyboard is to enable "Full
515 keyboard access" in the "Keyboard" pane of the System Preferences (you can
516 also toggle this on or off by pressing Ctrl-F7). Once keyboard access is
517 enabled it is possible to move between buttons with Tab and pressing Space to
518 select the current button. The current button is indicated with a blue
519 outline.
521 ==============================================================================
522 8. System services *macvim-services*
524 MacVim supports a few system services. These can be accessed from the MacVim
525 submenu in the Services menu. For services to work, MacVim.app should be
526 located in the /Applications folder. (You might have to logout and then login
527 again before Mac OS X detects the MacVim services.)
529 These are the currently supported services:
530 * New Document Containing Selection: Open a new window and paste the
531 currently selected text.
532 * New Document Here: Open a new window and set the current directory
533 to that of the selected text. This is intended to be used from a
534 Finder window to open an empty document in the currently selected
535 folder.
536 * Open Selected File: If the selected text represents a file name,
537 then the corresponding file is opened in a new window.
539 If new files are set to open in the current window (in the General preference
540 pane) then the above services will also reuse the topmost window, instead of
541 opening a new window.
543 ==============================================================================
544 9. mvim:// URL handler *mvim://* *macvim-url-handler*
546 MacVim supports a custom URL handler for "mvim://" URLs. The handler is
547 supposed to be compatible to TextMate's URL scheme as documented at
548 http://blog.macromates.com/2007/the-textmate-url-scheme/.
550 Currently, this means that the format is >
551 mvim://open?<arguments>
552 where "arguments" can be:
553 * url — the actual file to open (i.e. a file://... URL), if you leave
554 out this argument, the frontmost document is implied
555 * line — line number to go to (one based)
556 * column — column number to go to (one based)
558 For example, the link >
559 mvim://open?url=file:///etc/profile&line=20
560 will open the file /etc/profile on line 20 when clicked in a web browser.
562 Note that url has to be a file:// url pointing to an existing local file.
564 ==============================================================================
565 10. Keyboard shortcuts *macvim-shortcuts*
567 Most keyboard shortcuts in MacVim are bound to menu items and can be
568 discovered by looking through the menus (see |macvim-menus| on how to create
569 your own menu shortcuts). The remaining shortcuts are listed here:
571 *Cmd-.* *<D-.>*
572 Cmd-. Interrupt Vim. Unlike Ctrl-C which is sent as normal
573 keyboard input (and hence has to be received and then
574 interpreted) this sends a SIGINT signal to the Vim
575 process. Use this shortcut if the Vim process appears
576 to have locked up and is not responding to key presses.
577 This Cmd-key combination cannot be unmapped.
579 *Cmd-`* *<D-`>*
580 Cmd-` Cycle to the next window. On an American keyboard the
581 `-key is located under the Esc-key. On European
582 keyboards this key is often adjacent to the left
583 Shift-key and it may be not even be marked with "`".
584 This Cmd-key combination can only be unmapped via the
585 "Keyboard" System Preferences.
587 *Cmd-Left* *<D-Left>*
588 Cmd-Left Move cursor to the beginning of the line
589 (see |cmd-movement|).
591 *Cmd-Right* *<D-Right>*
592 Cmd-Right Move cursor to the end of the line (see |cmd-movement|).
594 *Cmd-Up* *<D-Up>*
595 Cmd-Up Move cursor to the first line (see |cmd-movement|).
597 *Cmd-Down* *<D-Down>*
598 Cmd-Down Move cursor to the last line (see |cmd-movement|).
600 *Alt-Left* *<M-Left>*
601 Alt-Left Move cursor to the beginning of the previous word
602 (see |alt-movement|).
604 *Alt-Right* *<M-Right>*
605 Alt-Right Move cursor to the beginning of the next word
606 (see |alt-movement|).
608 *Alt-Up* *<M-Up>*
609 Alt-Up Move cursor one paragraph forward (see |alt-movement|).
611 *Alt-Down* *<M-Down>*
612 Alt-Down Move cursor to the previous paragraph
613 (see |alt-movement|).
615 *cmd-movement* *alt-movement*
616 The above mappings involving Cmd/Alt + arrow key are enabled by default in the
617 system gvimrc file "$VIM/gvimrc". You can quickly disable all of these by
618 adding the following lines to your "~/.vimrc" (not .gvimrc) file: >
619 if has("gui_macvim")
620 let macvim_skip_cmd_opt_movement = 1
621 endif
622 Note: These are the only key mappings that MacVim makes (not counting menu key
623 equivalents which are not set up with :map).
625 See |macvim-shift-movement| if you want Shift to select text when used in
626 conjunction with the above Cmd/Alt movement shortcuts.
628 ==============================================================================
629 11. International *macvim-international*
631 When editing non-English text it may be convenient to keep separate keyboard
632 layouts for normal and insert mode. This is supported via the 'imd' option on
633 Mac OS X 10.5 or later (on 10.4 the 'imd' option support is not as useful as
634 it only switches between Roman and non-Roman input sources and it has been
635 known not to work very reliably).
637 For example: When 'noimd' is enabled (i.e. IM is enabled) the input source is
638 saved when toggling between normal and insert mode, so you can use a US layout
639 in normal mode then switch to insert mode and choose a Swedish layout. When
640 you go back to normal mode the US layout will be selected and when you enter
641 insert mode the Swedish layout is selected. This also works when searching
642 for text etc. see 'imc', 'imi', 'ims'.
644 Note that the layout used in normal mode is the layout used when 'noimd' is
645 set (i.e when IM is enabled). If you find that MacVim switches to the
646 wrong layout when going back to normal mode, then select the layout you want
647 to use in normal mode and type ":set imd" followed by ":set noimd".
649 ==============================================================================
650 12. Known bugs/missing features *macvim-todo*
652 This list is by no means exhaustive, it only enumerates some of the more
653 prominent bugs/missing features.
655 - Localized menus are not supported. Choosing anything but "English" in the
656 "International" pane of "System Prefences" may break the menus (and
657 toolbar).
658 - Some Unicode characters are not handled well (e.g. nonspacing marks)
659 - Sometimes multibyte characters look "too wide", i.e. they overlap the
660 following character. It might help to change 'ambiwidth', or override the
661 automatic font substitution by setting 'guifontwide' manually.
662 - Printing. As a temporary solution <D-p> creates a PostScript file which is
663 then opened in Preview where it may be printed.
664 - The toolbar looks ugly and is not very useful.
666 If you find new bugs then add a new issue at http://code.google.com/p/macvim/
667 or post your findings to the |vim_mac| mailing list. If you are missing
668 feature X in MacVim then voice your opinion on the |vim_mac| mailing list; it
669 might be simple to implement, but unless somebody asks for a particular
670 feature then there is little incentive to add it.
672 ==============================================================================
673 13. Hints *macvim-hints*
675 In this section some general (not necessarily MacVim specific) hints are
676 given.
678 Scenario: ~
679 You try opening a bunch of files in tabs but not all files get opened in their
680 own tab.
681 Solution: ~
682 To get around this, set 'tabpagemax' to something big in your .gvimrc file
683 (e.g. ":set tabpagemax=100").
685 Scenario: ~
686 You want to open a file in a tab in an already opened window, but typing "mvim
687 filename" in Terminal opens it up in a separate window.
688 Solution: ~
689 Use the |--remote-tab| switch. If you have several windows open you might
690 have to specify which window you want the file to open in by using the
691 |--servername| switch. The title of a window usually ends in something like
692 "VIM" or "VIM3" --- this is the server name of that window. So to open a file
693 named "foobar.txt" in a window whose title ends in "VIM3" you would type (the
694 order of the arguments matters): >
695 mvim --servername VIM3 --remote-tab foobar.txt
696 For more information, consult the |client-server| manual page.
698 Scenario: ~
699 You like to be able to select text by holding down shift and pressing the
700 arrow keys and find the Vim way of selecting text strange.
701 Solution: ~
702 See |macvim-shift-movement|.
704 Scenario: ~
705 You do not want MacVim to set up any key mappings.
706 Solution: ~
707 See |cmd-movement|.
709 Scenario: ~
710 Enabling localized menus breaks the toolbar and the menus as well.
711 Solution: ~
712 This is a known problem, see |macvim-todo|.
714 Scenario: ~
715 You dislike the default font (DejaVu Sans Mono).
716 Solution: ~
717 The standard fixed width font on Mac OS X is Menlo (it used to be Monaco prior
718 to OS X 10.6). If you prefer this font then add the following line to your
719 "~/.gvimrc": >
720 set guifont=Menlo:h11
721 The suffix ":h11" specifies the point size of the font should be "11" (see
722 'guifont' for more information on how to set the font).
724 Scenario: ~
725 When you click the (green) zoom button you want the window to maximize
726 horizontally as well as vertically.
727 Solution: ~
728 Hold down Cmd and click the zoom button. If you prefer this to be the default
729 action, then set the user default MMZoomBoth (see |macvim-prefs|).
731 Scenario: ~
732 Typing feels sluggish when the cursor is just before a right bracket (i.e.
733 ')', '}', or ']').
734 Solution: ~
735 Disable the "matchparen" plugin (see |matchparen|) by typing :NoMatchParen.
736 If that helps, then you can permanently disable "matchparen" by adding the
737 following line to your "~/.vimrc": >
738 let loaded_matchparen=1
739 <
740 Scenario: ~
741 You want to use MacVim as an editor for some external application.
742 Solution: ~
743 If the external application lets you set a program to execute then something
744 like "mvim -f" might be all you need (the "-f" switch ensures that the "mvim"
745 script returns only after you close the editor window, otherwise "mvim"
746 returns immediately). If the external program honors the EDITOR environment
747 variable (e.g Git does this) then you may get away by adding the following
748 line to your "~/.profile": >
749 export EDITOR='mvim -f'
750 If you have not installed the "mvim" script in your path you can provide the
751 path to the Vim binary instead. Thus, if "MacVim.app" resides in the
752 Applications folder then you would use the following line: >
753 export EDITOR='/Applications/MacVim.app/Contents/MacOS/Vim -g -f'
755 Scenario: ~
756 You have set MacVim to open from an external program and when you finish
757 editing (by closing the MacVim window) you want the external program to regain
758 focus.
759 Solution: ~
760 Use the VimLeave autocommand to hide MacVim when the window closes: >
761 au VimLeave * maca hide:
762 Assuming your external program has a setting for which command to execute to
763 bring up an editor, you would set that option to something like: >
764 mvim -f -c "au VimLeave * maca hide:"
765 (See the above Scenario for an explanation of the "-f" switch.)
767 Scenario: ~
768 You would like to remap Caps Lock to Esc.
769 Solution: ~
770 The app "PCKeyboardHack" can be used to remap Caps Lock. It is available as a
771 free download from:
772 http://www.pqrs.org/tekezo/macosx/keyremap4macbook/extra.html
773 On some Apple keyboards the Caps Lock key doesn't immediately register and
774 this makes Caps Lock "drop" key presses. To work around this problem go into
775 the "Keyboard" System Preference and remap Caps Lock to Ctrl first (click the
776 "Modifier Keys..." button). This trick may also be necessary if the Caps Lock
777 light turns on/off despite having remapped to Esc.
779 Scenario: ~
780 You have problems creating custom mappings involving the Cmd key.
781 Solution: ~
782 To bind to a key involving Cmd you use the "<D-..>" syntax. Many Cmd-key
783 mappings are already used by the menus so if your mapping doesn't work then
784 the solution is usually to first unmap the menu binding (see |macvim-menus|,
785 in particular read the end of that section). Also see the section on
786 |macvim-shortcuts| for some Cmd-key combinations which are not used by the
787 menus but still need to be freed up before they can be used in custom bindings.
789 Scenario: ~
790 You can't find the information on MacVim you thought should be in this manual
791 page.
792 Solution: ~
793 Post your question on the |vim_mac| mailing list and wait for an answer.
795 vim:tw=78:sw=4:ts=8:ft=help:norl: