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