| blob | d98e4a3d199797190d18d3aea30ebb38aa0f122d |
1 *gui_mac.txt* For Vim version 7.1. Last change: 2008 Feb 05
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. Known bugs/missing features |macvim-todo|
19 10. Hints |macvim-hints|
21 Other relevant documentation:
22 |gui.txt| For generic items of the GUI.
23 |os_mac.txt| For Mac specific items.
25 {Vi does not have a GUI}
27 ==============================================================================
28 0. Important! *macvim-important*
30 MacVim is still under development...this is not the finished product! If you
31 have problems with MacVim then make it known either by adding an issue report
32 on the MacVim project page >
33 http://code.google.com/p/macvim
34 or by posting to the vim_mac mailing list *vim_mac* >
35 http://groups.google.com/group/vim_mac
37 Remember to keep checking the project page for new snapshots. (If you
38 downloaded this copy from somewhere else, you might want to go there now to
39 make sure that you have got the latest version.)
41 ==============================================================================
42 1. MacVim differences *macvim-differences*
44 One of the goals of MacVim is to make Vim behave like a proper Mac OS X
45 application. For this reason MacVim behaves slightly different from other GUI
46 ports of Vim. Most of the modifications are provided in the system gvimrc
47 file; you can quickly open this file and look at it yourself by typing: >
48 :tabe $VIM/gvimrc
49 Note that this file will be overwritten each time you update MacVim, so it is
50 better to keep your own modifications inside "~/.gvimrc".
52 *macvim-windows*
53 There is some confusion regarding the term "window" in MacVim since it means
54 one thing to Vim and another to MacVim. A "window" in Vim is what opens up
55 when you type ":sp", whereas a "window" in MacVim is the GUI window which
56 contains the text view, scrollbars, toolbar and tabline. To avoid confusion,
57 the former is referred to as a Vim-window, whereas the latter is simply called
58 a window.
60 *macvim-encoding*
61 It is not possible to modify 'termencoding' in MacVim; this option is forcibly
62 set to "utf-8". The option 'encoding' also defaults to "utf-8" (as opposed to
63 "latin1" in the other GUI ports).
65 Note: UTF-8 can represent all characters defined in Unicode, which includes
66 all characters in all other standard encodings, so it should be perfectly safe
67 to edit files in any encoding while 'encoding' is set to "utf-8". Of course,
68 you may need to set 'fileencodings' to auto-detect the encoding of the files
69 you edit, or force the detection with |++enc| on the command line.
71 However, if you are editing files that use multiple encodings (container
72 formats like MIME or Unix mbox files) or no standard encoding (binary data,
73 see also |edit-binary|), you may want to prevent MacVim from re-encoding the
74 file at all. In this situation, you will need to set both 'encoding' and
75 'fileencodings' to a simple single-byte encoding such as Latin1 so that when
76 the file is read into memory, the original bytes are left untouched.
78 *macvim-movement*
79 Some Mac OS X standard key mappings involving Cmd or Option and an arrow key
80 are set up by default in "$VIM/gvimrc". You can quickly disable all of these
81 by adding the following lines to your "~/.vimrc" (not .gvimrc) file: >
82 if has("gui_macvim")
83 let macvim_skip_cmd_opt_movement = 1
84 endif
85 Note: These are the only key mappings that MacVim makes (not counting menu key
86 equivalents which are not set up with :map).
88 *macvim-shift-movement*
89 Text editors on Mac OS X lets the user hold down shift+movement key to extend
90 the selection. Also, pressing a printable key whilst selecting replaces the
91 current selection with that character. MacVim can emulate this kind of
92 behaviour (by providing key bindings and by setting 'keymodel' and
93 'selectmode' to non-default values) although it is not enabled by default. To
94 make MacVim behave more like TextEdit and less like Vim, add the following
95 lines to your "~/.vimrc" (not .gvimrc) file: >
96 if has("gui_macvim")
97 let macvim_hig_shift_movement = 1
98 endif
99 <
100 *macvim-drag-n-drop*
101 Dragging files and dropping them on a window opens those files in tabs in that
102 window, unless Vim is in command-line mode. In command-line mode the names of
103 the files are added to the command line. Holding down modifier keys whilst
104 dragging is not supported.
106 If a file is dropped on the Dock icon, it is always opened in a new tab
107 regardless of the mode Vim is currently in. The same holds if you
108 double-click on a file in the Finder.
110 *macvim-default-menu*
111 The default menu in MacVim has been changed to conform better with the Apple
112 Human Interface Guidelines (HIG). At the moment this breaks the localized
113 menus, so only English menus are supported.
115 Note: The menus are a work in progress. If you know something about the HIG
116 and want to contribute to MacVim you could do so by making the menus better.
118 *macvim-window-title*
119 The default window title does not include the argument list because it looks
120 really bad once you start using tabs. For example, dropping two files, then
121 dropping two more, and switching back to the first tab would cause weird
122 strings like "((3) of 2)" to appear in the window title.
124 *macvim-options*
125 These are the non-standard options that MacVim supports:
126 'fullscreen' 'toolbariconsize' 'transparency'
128 *macvim-find*
129 Whenever you search for something in Vim (e.g. using "/") the search query is
130 copied to the OS X "Find Pasteboard". The idea is that if you search for
131 something and switch to another application, then you can hit <D-g> (or <D-G>)
132 to repeat the search in the new app. The same feature works if you search in
133 some app, switch to MacVim and hit <D-g>.
135 Note that the command |n| is not the same as <D-g>. The former will repeat
136 the last search made in Vim, whereas the latter searches for the string on the
137 OS X Find Pasteboard using the action findNext: (see |:macaction|).
139 The <D-g> key equivalent is a great way to bring a search from one window to
140 another in MacVim. Simply search for something in one window (using "/") then
141 switch to another (e.g. with <D-`>) and hit <D-g> and the search will be
142 repeated in the new window.
144 ==============================================================================
145 2. Starting MacVim *macvim-start*
147 The easiest way to start MacVim is by double-clicking its icon in the Finder,
148 but most users will probably prefer to use the Terminal. First some Finder
149 related ways of starting MacVim are described, then Terminal is discussed.
150 Note that you can put MacVim anywhere on your hard drive, but in this help
151 file it is assumed that you have put it inside your /Applications folder.
153 MacVim automatically registers itself as an editor of several standard file
154 formats. This enables you to double-click a file to open it with MacVim (if
155 it is not associated with another program), or to right-click a file to bring
156 up the "Open with" menu. You can also drag and drop files onto the Dock icon
157 to open them in tabs in a new window, or you can drop them in an already open
158 window to open the files in tabs in that specific window. Finally, you can
159 use Mac OS X System Services to open files in MacVim, see |macvim-services|.
161 There are essentially two ways to start MacVim from Terminal: either call the
162 Vim binary with the -g switch >
163 /Applications/MacVim.app/Contents/MacOS/Vim -g file ...
164 or use the "open" command (which is of limited use since it cannot be used to
165 pass parameters to Vim) >
166 open -a MacVim file ...
167 <
168 *mvim*
169 To save yourself from having to type the entire path to the Vim binary each
170 time you start MacVim, you could create an alias such as >
171 alias gvim='/Applications/MacVim.app/Contents/MacOS/Vim -g'
172 and add that to "~/.profile". A more flexible way to start MacVim is to use
173 the shell script "mvim" which comes bundled with MacVim. Put this script in a
174 folder in your path and then simply type "mvim" to start MacVim. This script
175 will try to find MacVim.app in various typical folders such as >
176 ~/Applications ~/Applications/vim
177 /Applications /Applications/vim
178 /Applications/Utilities /Applications/Utilities/vim
179 If you would rather put MacVim.app in some other directory then that is also
180 possible, simply set the environment variable VIM_APP_DIR to whatever folder
181 you have placed MacVim.app in.
183 Note: Starting MacVim by creating a symlink to >
184 .../MacVim.app/Contents/MacOS/Vim
185 with 'ln -s' does not work.
187 Once in terminal Vim it is possible to start MacVim by using the following
188 command:
189 :gui [++opt] [+cmd] [-f|-b] [files...]
190 Note: Forking ("-b") currently does not work.
192 *odbeditor* *external-editor*
193 MacVim can act as an 'external editor' for Mac OS X applications that support
194 the ODB Editor Protocol (or the 'external editor' protocol). Each application
195 has different ways of configuring this option, check the application's
196 documentation. Once configured properly MacVim can be used to open files in
197 such an application.
199 A technical note: MacVim handles file open, modified and closed events. In
200 the open event the FTok and Burl parameters are parsed (the latter is ignored
201 at the moment though). In the modified and closed events the Tokn parameter
202 is sent back to the server application.
204 ==============================================================================
205 3. Preferences *macvim-prefs* *macvim-preferences*
207 Some settings are global to the MacVim application and would not make sense as
208 Vim options. These settings are stored in a user default database and can be
209 accessed via the "MacVim/Preferences..." menu item.
211 Not all entries in the user defaults database are exposed via the preference
212 panel, usually because they should not be changed by the user under normal
213 circumstances. These options can still be changed with the "defaults" command
214 by opening Terminal and typing >
215 defaults write org.vim.MacVim KEY VALUE
216 Check the man page on "defaults" for more information on this command as well
217 as general information regarding Mac OS X user defaults.
219 Here is a list of relevant dictionary entries:
221 KEY VALUE ~
222 MMCellWidthMultiplier width of a normal glyph in em units [float]
223 MMNoFontSubstitution disable automatic font substitution [bool]
224 MMTabMaxWidth maximum width of a tab [int]
225 MMTabMinWidth minimum width of a tab [int]
226 MMTabOptimumWidth default width of a tab [int]
227 MMTextInsetBottom text area offset in pixels [int]
228 MMTextInsetLeft text area offset in pixels [int]
229 MMTextInsetRight text area offset in pixels [int]
230 MMTextInsetTop text area offset in pixels [int]
231 MMTexturedWindow use brushed metal window (Tiger only) [bool]
232 MMTranslateCtrlClick interpret ctrl-click as right-click [bool]
233 MMZoomBoth zoom button maximizes both directions [bool]
235 As an example, if you have more than one mouse button and would wish to free
236 up Ctrl-click so you can bind it to something else, then the appropriate
237 command is: >
238 defaults write org.vim.MacVim MMTranslateCtrlClick 0
240 If you wish to restore all user defaults to their starting values, open
241 Terminal and type: >
242 defaults delete org.vim.MacVim
244 ==============================================================================
245 4. Special colors *macvim-colors*
247 The colors in MacVim are defined in two dictionaries inside the "Resources"
248 folder of the application bundle (MacVim.app/Contents/Resources). It is
249 possible to add more colors by modifying these files. Color names are case
250 insensitive when accessed from Vim, but in the dictionary they must be
251 lowercase.
253 *SystemColors.plist*
254 There are only a few system colors that can be accessed from Vim. These
255 colors are defined in the dictionary "SystemColors.plist". This dictionary
256 stores (key, value) pairs where the key is the name of the color and the
257 value is an NSColor selector name.
259 The most useful system colors are: >
260 MacSelectedTextBackgroundColor
261 MacSecondarySelectedColor
262 The former is the "Highlight Color" which can be changed in the "Appearance"
263 section of the System Preferences. The latter is the selection color used by
264 a Cocoa application when it is not in focus.
266 *Colors.plist*
267 Apart from the system colors, it is also possible to use the standard X11
268 color names (see http://en.wikipedia.org/wiki/X11_color_names) which usually
269 come in a file called "rgb.txt". MacVim does not have such a file, instead it
270 keeps these colors in a dictionary called "Colors.plist". The key in this
271 dictionary is the name of the color and the value is an RGB value on the form
272 #rrggbb stored as an integer.
274 *macvim-colorscheme*
275 MacVim ships with a custom color scheme that is used instead of the default
276 Vim color scheme. The color scheme can be changed with >
277 :colorscheme macvim
278 If you prefer a dark background color, then type >
279 :set bg=dark
280 after having loaded the "macvim" color scheme.
282 The color scheme uses the the system "Highlight Color", which can be changed in
283 the "Appearance" pane of the System Preferences. It also changes the
284 highlight color when a window becomes inactive.
286 If you have any comments regarding this colors cheme (is it better or worse
287 than the default?) then post them to |vim_mac|.
289 ==============================================================================
290 5. Menus *macvim-menus*
292 *:macm* *:macmenukey*
293 MacVim has a special way of binding keys to menu items that differs from other
294 Vim GUI ports. A menu binding is called a "key equivalent" in Mac OS X
295 terminology, this is displayed on the right side of a menu item. The
296 ":macmenukey" command is used to set the key equivalent of a menu item. This
297 command takes two parameters, the first names the menu item to bind to, the
298 second gives the key combination. For example: >
299 :macmenukey File.New\ Tab <D-t>
300 This sets the key equivalent of the "New Tab" menu item under the "File" menu
301 to Cmd+t.
303 Note that key equivalents:
304 * must contain the Cmd modifier flag (<D-...>)
305 * take precedence over normal mappings made with ":map"
306 * can only be modified during startup (e.g. in .gvimrc)
308 It is possible to reset a key equivalent by calling :macmenukey with a menu
309 name but no key. This is so that the default key equivalents can be reset in
310 "~/.gvimrc". For example, if you would like to free up <D-s> (which is the
311 key equivalent of "File.Save") then add the following line to "~/.gvimrc": >
312 macmenukey File.Save
313 Now you can use :map to bind <D-s> to whatever you like.
315 It is not necessary to reset a key equivalent if all you want to do is to
316 change the key equivalent of a menu item. For example, say you want to use
317 <D-M-Right> as the key equivalent for "Next Tab", then add the following line
318 to "~/.gvimrc": >
319 macmenukey Window.Next\ Tab <D-M-Right>
320 <
321 *:maca* *:macaction*
322 It is typical for menu items in Cocoa applications to bind to Objective-C
323 selectors. To support this, MacVim introduces the ":macaction" command. This
324 command takes the name of an action message as its only parameter. (An action
325 message is an Objective-C message with "void" return type and a single
326 parameter of type "id".) For example, the "New Window" menu item on the
327 "File" menu is created in the following manner: >
328 :an 10.290 File.New\ Window :macaction newWindow:<CR>
330 Note 1: A menu item which is bound to ":macaction" will automatically be bound
331 to that action in all modes (as if ":an" was used). It is not possible to
332 bind to ":macaction" in one mode only.
333 Note 2: The action is "nil-targeted", which means it is passed down the first
334 responder chain.
336 *Actions.plist*
337 Some action messages would not be suitable to call from within Vim, so there
338 is a dictionary called "Actions.plist" (in the Resources folder of the
339 application bundle) which contains all actions that may be called. The key in
340 this dictionary is the name of the action message (case sensitive), the value
341 is not used.
343 Here is a random assortment of actions from Actions.plist which might be
344 useful.
346 Action Description ~
347 findNext: Search forward using the "Find Pasteboard"
348 findPrevious: Search backward using the "Find Pasteboard"
349 fontSizeDown: Decrease font size
350 fontSizeUp: Increase font size
351 newWindow: Open a new (empty) window
352 orderFrontCharacterPalette: Show the the "Special Characters" dialog
353 orderFrontFontPanel: Show the Font panel
354 orderFrontPreferencePanel: Show the Preferences panel
355 performZoom: Zoom window (same as clicking the green blob)
356 selectNextWindow: Select next window (similar to <D-`>)
357 selectPreviousWindow: Select previous window (similar to <S-D-`>)
359 As an example, to map <C-z> to performZoom: you could do something like this: >
360 :map <silent> <C-z> :macaction performZoom:<CR>
361 A better way to map to performZoom: would be to set the key equivalent of the
362 menu item "Window.Zoom" to the above action. This can be done by adding the
363 following line to "~/.gvimrc": >
364 macmenukey Window.Zoom <D-C-z>
365 (Note that key equivalents must contain the 'D' flag.)
367 ==============================================================================
368 6. Toolbar *macvim-toolbar*
370 The toolbar in MacVim works just like in the other GUIs (see |gui-toolbar|),
371 with the addition of two separator items (see |menu-separator|). You can use
372 them as follows: >
373 :an ToolBar.-space1- <Nop>
374 :an ToolBar.-flexspace2- <Nop>
375 The first example creates an empty space on the toolbar, the second creates an
376 empty space which will shink or expand so that the items to the right of it
377 are right-aligned. A space (flexspace) will be created for any toolbar item
378 whose name begins with "-space" ("-flexspace") and ends with "-"
380 Toolbar icons should be tiff, png or icns, of dimension 32x32 or 24x24 pixels.
381 The larger size is used when 'tbis' is "medium" or "large", otherwise the
382 smaller size is used (which is the default). If the icon file only contains
383 one dimension then Mac OS X will scale the icon to the appropriate dimension
384 if necessary. To avoid this, use a file format which supports multiple
385 resolutions (such as icns) and provide both 32x32 and 24x24 versions of the
386 icon.
388 Note: Only a subset of the builtin toolbar items presently have icons. If no
389 icon can be found a warning triangle is displayed instead.
391 ==============================================================================
392 7. Dialogs *macvim-dialogs*
394 Dialogs can be controlled with the keyboard in two ways. By default each
395 button in a dialog is bound to a key. The button that is highlighted by blue
396 is bound to Enter, and any button with the title "Cancel" is bound to Escape.
397 Other buttons are usually bound to the first letter in the title of the
398 button. There is no visual feedback to indicate which letter a button is
399 bound to, so sometimes some experimentation might be required in order to
400 figure out which key to press.
402 The second way of controlling dialogs with the keyboard is to enable "Full
403 keyboard access" in the "Keyboard & Mouse" pane of the System Preferences (you
404 can also toggle this on or off by pressing Ctrl-F7). Once keyboard access is
405 enabled it is possible to move between buttons with Tab and pressing Space to
406 select the current button. The current button is indicated with a blue
407 outline.
409 ==============================================================================
410 8. System services *macvim-services*
412 MacVim supports a few system services. These can be accessed from the MacVim
413 submenu in the Services menu. For services to work, MacVim.app should be
414 located in the /Applications folder. (You might have to logout and then login
415 again before Mac OS X detects the MacVim services.)
417 These are the currently supported services:
418 * New Tab Containing Selection: Opens a new tab in the topmost window and
419 pastes the currently selected text in that tab. A new window will be
420 opened if necessary.
421 * Open Selected File in Tab: If the selected text represents a file
422 name, then the corresponding file is opened in a new tab in the topmost
423 window.
424 * Open Selected File in Window: Same as the above, but always open in a new
425 window.
427 ==============================================================================
428 9. Known bugs/missing features *macvim-todo*
430 Here are some of the bigger bugs in MacVim. Of course there are others, but
431 these are ones that are know and/or which were judged major.
433 - Localized menus are not supported. Choosing anything but "English" in the
434 "International" pane of "System Prefences" may break the menus (and
435 toolbar).
436 - Some Unicode characters are not handled well (e.g. nonspacing marks)
437 - Sometimes multibyte characters look "too wide", i.e. they overlap the
438 following character. It might help to change 'ambiwidth', or override the
439 automatic font substitution by setting 'guifontwide' manually.
440 - Printing
441 - No find/replace dialog
443 If you find new bugs then add a new issue at http://code.google.com/p/macvim/
444 or post your findings to the |vim_mac| mailing list. If you are missing
445 feature X in MacVim then voice your opinion on the |vim_mac| mailing list; it
446 might be simple to implement, but unless somebody asks for a particular
447 feature then there is little incentive to add it.
449 ==============================================================================
450 10. Hints *macvim-hints*
452 In this section some general (not necessarily MacVim specific) hints are
453 given.
455 Scenario: ~
456 You try opening a bunch of files in tabs but not all files get
457 opened in their own tab.
458 Solution: ~
459 To get around this, set 'tabpagemax' to something big in your
460 .gvimrc file (e.g. ":set tabpagemax=100").
462 Scenario: ~
463 You want to open a file in a tab in an already opened window, but typing
464 "mvim filename" in Terminal opens it up in a separate window.
465 Solution: ~
466 Use the |--remote-tab| switch. If you have several windows open you
467 might have to specify which window you want the file to open in by using the
468 |--servername| switch. The title of a window usually ends in something like
469 "VIM" or "VIM3" --- this is the server name of that window. So to open a file
470 named "foobar.txt" in a window whose title ends in "VIM3" you would type (the
471 order of the arguments matters): >
472 mvim --servername VIM3 --remote-tab foobar.txt
473 For more information, consult the |client-server| manual page.
475 Scenario: ~
476 You like to be able to select text by holding down shift and
477 pressing the arrow keys and find the Vim way of selecting text strange.
478 Solution: ~
479 See |macvim-shift-movement|.
481 Scenario: ~
482 You do not want MacVim to set up any key mappings.
483 Solution: ~
484 See |macvim-movement|.
486 Scenario: ~
487 Enabling localized menus breaks the toolbar and the menus as well.
488 Solution: ~
489 This is a know problem, see |macvim-todo|.
491 Scenario: ~
492 You dislike the default font (DejaVu Sans Mono).
493 Solution: ~
494 The standard fixed width font on other Mac OS X applications is
495 Monaco. If you prefer this font then add the following line to your
496 "~/.gvimrc" (note that Monaco does not come in italic and bold variants): >
497 set guifont=Monaco:h10
498 The suffix ":h10" specifies the point size of the font should be "10" (see
499 'guifont' for more information on how to set the font).
501 Scenario: ~
502 When you click the (green) zoom button you want the window to maximize
503 horizontally as well as vertically.
504 Solution: ~
505 Hold down Cmd and click the zoom button.
507 Scenario: ~
508 Typing feels sluggish when the cursor is just before a right bracket (i.e. ')',
509 '}', or ']').
510 Solution: ~
511 Disable the "matchparen" plugin (see |matchparen|) by typing :NoMatchParen.
512 If that helps, then you can permanently disable "matchparen" by adding the
513 following line to your "~/.vimrc": >
514 let loaded_matchparen=1
515 <
517 Scenario: ~
518 You can't find the information on MacVim you thought should be in
519 this manual page.
520 Solution: ~
521 Post your question on the |vim_mac| mailing list and wait for an
522 answer.
524 vim:tw=78:sw=4:ts=8:ft=help:norl: