| blob | ddac90456101ae4d2a9fba7cec9c6bfd0aab38e3 |
1 *gui_mac.txt* For Vim version 7.1. Last change: 2007 Sep 18
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 The MacVim Graphical User Interface *macvim* *gui-macvim*
9 1. MacVim differences |macvim-differences|
10 2. Starting MacVim |gui-macvim-start|
11 3. Special colors |macvim-colors|
12 4. Menus |macvim-menus|
13 5. Dialogs |macvim-dialogs|
14 6. System services |macvim-services|
15 7. Known bugs/missing features |macvim-todo|
16 8. Hints |macvim-hints|
18 Other relevant documentation:
19 |gui.txt| For generic items of the GUI.
20 |os_mac.txt| For Mac specific items.
22 {Vi does not have a GUI}
24 ==============================================================================
25 1. MacVim differences *macvim-differences*
27 One of the goals of MacVim is to make Vim behave like a proper Mac OS X
28 application. For this reason MacVim behaves slightly different from other GUI
29 ports of Vim. Most of the modifications are provided in the system gvimrc
30 file; you can quickly open this file and look at it yourself by typing: >
31 :tabe $VIM/gvimrc
32 Note that this file will be overwritten each time you update MacVim, so it is
33 better to keep your own modifications inside "~/.gvimrc".
35 *macvim-windows*
36 There is some confusion regarding the term "window" in MacVim since it means
37 one thing to Vim and another to MacVim. A "window" in Vim is what opens up
38 when you type ":sp", whereas a "window" in MacVim is the GUI window which
39 contains the text view, scrollbars, toolbar and tabline. To avoid confusion,
40 the former is referred to as a Vim-window, whereas the latter is simply called
41 a window.
43 *macvim-shift-movement*
44 Text editors on Mac OS X lets the user hold down shift+movement key to extend
45 the selection. Also, pressing a printable key whilst selecting replaces the
46 current selection with that character. MacVim can emulate this kind of
47 behaviour (by providing key bindings and by setting 'keymodel' and
48 'selectmode' to non-default values) although it is not enabled by default. To
49 make MacVim behave more like TextEdit and less like Vim, add the following
50 lines to your "~/.vimrc" (not .gvimrc) file: >
51 if has("gui_macvim")
52 let macvim_hig_shift_movement = 1
53 endif
54 <
55 *macvim-encoding*
56 It is not possible to modify 'termencoding' in MacVim; this option is forcibly
57 set to "utf-8".
59 *macvim-drag-n-drop*
60 Dragging files and dropping them on a window opens those files in tabs in that
61 window, unless Vim is in command-line mode. In command-line mode the names of
62 the files are added to the command line. Holding down modifier keys whilst
63 dragging is not supported.
65 *macvim-default-menu*
66 The default menu in MacVim has been changed to conform better with the Apple
67 Human Interface Guidelines (HIG). At the moment this breaks the localized
68 menus, so only English menus are supported.
70 Note: The menus are a work in progress. If you know something about the HIG
71 and want to contribute to MacVim you could do so by making the menus better.
73 ==============================================================================
74 2. Starting MacVim *gui-macvim-start*
76 The easiest way to start MacVim is by double-clicking its icon in the Finder,
77 but most users will probably prefer to use the Terminal. First some Finder
78 related ways of starting MacVim are described, then Terminal is discussed.
79 Note that you can put MacVim anywhere on your hard drive, but in this help
80 file it is assumed that you have put it inside your /Applications folder.
82 MacVim automatically registers itself as an editor of several standard file
83 formats. This enables you to double-click a file to open it with MacVim (if
84 it is not associated with another program), or to right-click a file to bring
85 up the "Open with" menu. You can also drag and drop files onto the Dock icon
86 to open them in tabs in a new window, or you can drop them in an already open
87 window to open the files in tabs in that specific window. Finally, you can
88 use Mac OS X System Services to open files in MacVim, see |macvim-services|.
90 There are essentially two ways to start MacVim from Terminal: either call the
91 Vim binary with the -g switch >
92 /Applications/MacVim.app/Contents/MacOS/Vim -g file ...
93 or use the "open" command (which is of limited use since it cannot be used to
94 pass parameters to Vim) >
95 open -a MacVim file ...
97 In order to save you from having to type the entire path every time you start
98 MacVim, add the following alias to "~/.profile": >
99 alias gvim='/Applications/MacVim.app/Contents/MacOS/Vim -g'
101 Once in terminal Vim it is possible to start MacVim by using the following
102 command:
103 :gui [++opt] [+cmd] [-f|-b] [files...]
104 Note: Forking ("-b") currently does not work.
106 ==============================================================================
107 3. Special colors *macvim-colors*
109 The colors in MacVim are defined in two dictionaries inside the "Resources"
110 folder of the application bundle (MacVim.app/Contents/Resources). It is
111 possible to add more colors by modifying these files. Color names are case
112 insensitive when accessed from Vim, but in the dictionary they must be
113 lowercase.
115 *SystemColors.plist*
116 There are only a few system colors that can be accessed from Vim. These
117 colors are defined in the dictionary "SystemColors.plist". This dictionary
118 stores (key, value) pairs where the key is the name of the color and the
119 value is an NSColor selector name.
121 The most useful system colors are: >
122 MacSelectedTextBackgroundColor
123 MacSecondarySelectedColor
124 The former is the "Highlight Color" which can be changed in the "Appearance"
125 section of the System Preferences. The latter is the selection color used by
126 a Cocoa application when it is not in focus.
128 *Colors.plist*
129 Apart from the system colors, it is also possible to use the colors listed in
130 the dictionary "Colors.plist". The key in this dictionary is the name of the
131 color and the value is an RGB value on the form #rrggbb stored as an integer.
133 ==============================================================================
134 4. Menus *macvim-menus*
136 *:menukeyequiv*
137 MacVim has a special way of binding keys to menu items that differs from other
138 Vim GUI ports. A menu binding is called a "key equivalent" in Mac OS X
139 terminology, this is displayed on the right side of a menu item. The
140 ":menukeyequiv" command is used to set the key equivalent of a menu item.
141 This command takes two parameters, the first names the menu item to bind to,
142 the second gives the key combination. For example: >
143 :menukeyequiv File.New\ Tab <D-t>
144 This sets the key equivalent of the "New Tab" menu item under the "File" menu
145 to Cmd+t.
147 Note that key equivalents:
148 * should always contain the Cmd modifier flag (<D-...>)
149 * take precedence over normal mappings made with ":map"
150 * can only be modified during startup (e.g. in .gvimrc)
152 It is possible to reset a key equivalent by calling :menukeyequiv with a menu
153 name but no key. This is so that the default key equivalents can be reset in
154 "~/.gvimrc". For example, if you would like to free up <D-s> (which is the
155 key equivalent of "File.Save") then add the following line to "~/.gvimrc": >
156 menukeyequiv File.Save
157 Now you can use :map to bind <D-s> to whatever you like.
159 It is not necessary to reset a key equivalent if all you want to do is to
160 change the key equivalent of a menu item. For example, say you want to use
161 <D-M-Right> as the key equivalent for "Next Tab", then add the following line
162 to "~/.gvimrc": >
163 menukeyequiv Window.Next\ Tab <D-M-Right>
164 <
165 *:action*
166 It is typical for menu items in Cocoa applications to bind to Objective-C
167 selectors. To support this, MacVim introduces the ":action" command. This
168 command takes the name of an action message as its only parameter. (An action
169 message is an Objective-C message with "void" return type and a single
170 parameter of type "id".) For example, the "New Window" menu item on the
171 "File" menu is created in the following manner: >
172 :an 10.290 File.New\ Window :action newWindow:<CR>
174 Note 1: A menu item which is bound to ":action" will automatically be bound to
175 that action in all modes (as if ":an" was used). It is not possible to bind
176 to ":action" in one mode only.
177 Note 2: The action is "nil-targeted", which means it is passed down the first
178 responder chain.
180 *Actions.plist*
181 Some action messages would not be suitable to call from within Vim, so there
182 is a dictionary called "Actions.plist" (in the Resources folder of the
183 application bundle) which contains all actions that may be called. The key in
184 this dictionary is the name of the action message (case sensitive), the value
185 is not used.
187 ==============================================================================
188 5. Dialogs *macvim-dialogs*
190 Dialogs can be controlled with the keyboard in two ways. By default each
191 button in a dialog is bound to a key. The button that is highlighted by blue
192 is bound to Enter, and any button with the title "Cancel" is bound to Escape.
193 Other buttons are usually bound to the first letter in the title of the
194 button. There is no visual feedback to indicate which letter a button is
195 bound to, so sometimes some experimentation might be required in order to
196 figure out which key to press.
198 The second way of controlling dialogs with the keyboard is to enable "Full
199 keyboard access" in the "Keyboard & Mouse" pane of the System Preferences (you
200 can also toggle this on or off by pressing Ctrl-F7). Once keyboard access is
201 enabled it is possible to move between buttons with Tab and pressing Space to
202 select the current button. The current button is indicated with a blue
203 outline.
205 ==============================================================================
206 6. System services *macvim-services*
208 MacVim supports a few system services. These can be accessed from the MacVim
209 submenu in the Services menu. For services to work, MacVim.app should be
210 located in the /Applications folder. (You might have to logout and then login
211 again before Mac OS X detects the MacVim services.)
213 These are the currently supported services:
214 * New Tab Containing Selection: Opens a new tab in the topmost window and
215 pastes the currently selected text in that tab. A new window will be
216 opened if necessary.
217 * Open Selected File in Tab: If the selected text represents a file
218 name, then the corresponding file is opened in a new tab in the topmost
219 window.
220 * Open Selected File in Window: Same as the above, but always open in a new
221 window.
223 ==============================================================================
224 7. Known bugs/missing features *macvim-todo*
226 Here are some of the bigger bugs in MacVim. Of course there are others, but
227 these are ones that are know and/or which were judged major.
229 - Localized menus are not supported. Choosing anything but "English" in the
230 "International" pane of "System Prefences" may break the menus (and
231 toolbar).
232 - Composing characters are not supported, they will mess up the display
233 - Only "utf-8" is supported for 'enc'
234 - Sometimes multibyte characters look "too wide", i.e. they overlap the
235 following character. It might help to change 'ambiwidth'.
236 - Printing
237 - No find/replace dialog
239 If you find new bugs then add a new issue at http://code.google.com/p/macvim/
240 or post your findings to the vim_mac mailing list. If you are missing feature
241 X in MacVim then voice your opinion on the vim_mac mailing list; it might be
242 simple to implement, but unless somebody asks for a particular feature then
243 there is little incentive to add it.
245 ==============================================================================
246 8. Hints *macvim-hints*
248 In this section some general (not necessarily MacVim specific) hints are
249 given.
251 Scenario: You try opening a bunch of files in tabs but not all files get
252 opened in their own tab.
253 Solution: To get around this, set 'tabpagemax' to something big in your
254 .gvimrc file (e.g. ":set tabpagemax=100").
256 Scenario: You want to open a file in a tab in an already opened window, but
257 typing "gvim filename" in Terminal opens it up in a separate window.
258 Solution: Use the |--remote-tab| switch. If you have several windows open you
259 might have to specify which window you want the file to open in by using the
260 |--servername| switch. The title of a window usually ends in something like
261 "VIM" or "VIM3" --- this is the server name of that window. So to open a file
262 named "foobar.txt" in a window whose title ends in "VIM3" you would type (the
263 order of the arguments matters): >
264 gvim --servername VIM3 --remote-tab foobar.txt
265 For more information, consult the |client-server| manual page.
267 Scenario: You like to be able to select text by holding down shift and
268 pressing the arrow keys and find the Vim way of selecting text strange.
269 Solution: See |macvim-shift-movement|.
271 Scenario: You dislike the default font (Monaco) and/or want a font with bold
272 and italic variants.
273 Solution: The font "Courier New" is a fixed width font that ships with Mac OS
274 X which has both bold and italic variants; however, it is not particularly
275 well suited for programming. A better alternative is to use the font
276 "Bitstream Vera Sans Mono" which can be downloaded for free, and it also has
277 both oblique and bold variants. After having downloaded and installed the
278 Bitstream Vera font, you can make it the default font by adding the following
279 line to "~/.gvimrc": >
280 set guifont=Bitstream\ Vera\ Sans\ Mono:h13
281 The suffix ":h13" specifies the point size of the font should be "13" (see
282 'guifont' for more information on how to set the font).
284 Scenario: You can't find the information on MacVim you thought should be in
285 this manual page.
286 Solution: Post your question on the vim_mac mailing list and wait for an
287 answer.
289 vim:tw=78:sw=4:ts=8:ft=help:norl: