doc/gui_macvim.txt

   1 *gui_macvim.txt* For Vim version 7.1.  Last change: 2007 Sep 13
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 The MacVim Graphical User Interface                     *macvim* *gui-macvim*
   8
   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. System services              |macvim-services|
  14 6. Known bugs/missing features  |macvim-todo|
  15 7. Hints                        |macvim-hints|
  16
  17 Other relevant documentation:
  18 |gui.txt|       For generic items of the GUI.
  19 |os_mac.txt|    For Mac specific items.
  20
  21 {Vi does not have a GUI}
  22
  23 ==============================================================================
  24 1. MacVim differences                                   *macvim-differences*
  25
  26 One of the goals of MacVim is to make Vim behave like a proper Mac OS X
  27 application.  For this reason MacVim behaves slightly different from other GUI
  28 ports.  Most of the modifications are provided in the system gvimrc file; you
  29 can quickly open this file and look at it yourself by typing: >
  30         :tabe $VIM/gvimrc
  31 Note that this file will be overwritten each time you update MacVim, so it is
  32 better (where possible) to keep your own modifications inside "~/.gvimrc".
  33
  34                                                         *macvim-windows*
  35 There is some confusion regarding the term "window" in MacVim since it means
  36 one thing to Vim and another to MacVim.  A "window" in Vim is what opens up
  37 when you type ":sp", whereas a "window" in MacVim is the GUI window which
  38 contains the text view, scrollbars, toolbar and tabline.  To avoid confusion,
  39 the former is referred to as a Vim-window, whereas the latter is simply called
  40 a window.
  41
  42                                                         *macvim-shift-movement*
  43 Text editors on Mac OS X lets the user hold down shift+movement key to extend
  44 the selection.  Also, pressing a printable key whilst selecting replaces the
  45 current selection with that character.  MacVim tries to emulate this behaviour
  46 by providing several key bindings and by setting 'keymodel' and 'selectmode'
  47 to non-default values.  To disable this behaviour, add the following line to
  48 your "~/.vimrc" (not .gvimrc) file: >
  49         if has("gui_macvim")
  50           let macvim_skip_hig_shift_movement = 1
  51         endif
  52 <
  53                                                         *macvim-encoding*
  54 It is not possible to modify 'termencoding' in MacVim; this option is forcibly
  55 set to "utf-8".
  56
  57                                                         *macvim-drag-n-drop*
  58 Dragging files and dropping them on a window opens those files in tabs in that
  59 window.  This happens even when Vim is in command-line mode.  Holding down
  60 modifier keys whilst dragging is not supported.
  61
  62                                                         *macvim-default-menu*
  63 The default menu in MacVim has been changed to conform better with the Apple
  64 Human Interface Guidelines (HIG).
  65
  66 Note: The menus are a work in progress.  If you know something about the HIG
  67 and want to contribute to MacVim you could do so by making the menus better.
  68
  69 ==============================================================================
  70 2. Starting MacVim                                      *gui-macvim-start*
  71
  72 MacVim can be started from Terminal or by double clicking its icon in the
  73 Finder.  If you use the Dock then you might want to drag the MacVim icon to
  74 the Dock so that you have easy access to it.  MacVim automatically registers
  75 itself as an editor of several standard file formats.  This enables you to
  76 double-click a file to open it with MacVim (if it is not associated with
  77 another program), or to right-click a file to bring up the "Open with" menu.
  78 You can also drag and drop files onto the Dock icon to open them in tabs in a
  79 new window, or you can drop them in an already open window to open the files
  80 in tabs in that specific window.  Finally, you can use Mac OS X System
  81 Services to open files in MacVim, see |macvim-services|.
  82
  83 There are essentially two ways to start MacVim from Terminal: either call the
  84 Vim binary with the -g switch >
  85         MacVim.app/Contents/MacOS/Vim -g file ...
  86 or use the "open" command (which is of limited use since it cannot be used to
  87 pass parameters to Vim) >
  88         open -a MacVim file ...
  89
  90 In order to save you from having to type the entire path every time you start
  91 MacVim, add the following alias to "~/.profile": >
  92         alias gvim='/Applications/MacVim.app/Contents/MacOS/Vim -g'
  93 (This assumes that you have put MacVim.app in /Applications.)
  94
  95 Once in terminal Vim it is possible to start MacVim by using the following
  96 command:
  97         :gui [++opt] [+cmd] [-f|-b] [files...]
  98 Note: Forking ("-b") currently does not work.
  99
 100 ==============================================================================
 101 3. Special colors                                       *macvim-colors*
 102
 103 The colors in MacVim are defined in two dictionaries inside the "Resources"
 104 folder of the application bundle (MacVim.app/Contents/Resources).  It is
 105 possible to add more colors by modifying these files.  Color names are case
 106 insensitive when accessed from Vim, but in the dictionary they must be
 107 lowercase.
 108
 109                                                         *SystemColors.plist*
 110 There are only a few system colors that can be accessed from Vim.  These
 111 colors are defined in the dictionary "SystemColors.plist".  This dictionary
 112 stores (key, value) pairs where the key is the name of the color  and the
 113 value is an NSColor selector name.
 114
 115 The most useful system colors are: >
 116         MacSelectedTextBackgroundColor
 117         MacSecondarySelectedColor
 118 The former is the "Highlight Color" which can be changed in the "Appearance"
 119 section of the System Preferences.  The latter is the selection color used
 120 when an application is not in focus.
 121
 122                                                         *Colors.plist*
 123 Apart from the system colors, it is also possible to use the colors listed in
 124 the dictionary "Colors.plist". The key in this dictionary is the name of the
 125 color  and the value is an RGB value on the for #rrggbb stored as an integer.
 126
 127 ==============================================================================
 128 4. Menus                                                *macvim-menus*
 129
 130 MacVim has a special way of binding keys to menu items that differs from other
 131 Vim GUI ports.  A menu binding is called a "key equivalent" in Mac OS X
 132 terminology.  The ":menukeyequiv" command is used to set the key equivalent of
 133 a menu item.  This command takes two parameters, the first names the menu item
 134 to bind to, the second gives the key combination.  For example: >
 135         :menukeyequiv File.New\ Tab <D-t>
 136 This sets the key equivalent of the "New Tab" menu item under the "File" menu
 137 to Cmd+t.
 138
 139 Note 1: A key equivalent should always contain the Cmd key modifier flag!
 140 Note 2: Key equivalents take precedence over normal mappings made with ":map".
 141
 142 It is typical for menu items in Cocoa applications to bind to Objective-C
 143 selectors.  To support this, MacVim introduces the ":action" command.  This
 144 command takes the name of an action message as its only parameter.  (An action
 145 message is an Objective-C message with "void" return type and a single
 146 parameter of type "id".)  For example, the "New Window" menu item on the
 147 "File" menu is created in the following manner: >
 148         :an 10.290 File.New\ Window :action newVimWindow:<CR>
 149
 150 Note 1: A menu item which is bound to ":action" will automatically be bound to
 151 that action in all modes (as if ":an" was used).  It is not possible to bind
 152 to ":action" in one mode only.
 153 Note 2: The action is "nil-targeted", which means it is passed down the first
 154 responder chain.
 155
 156                                                         *Actions.plist*
 157 Some action messages would not be suitable to call from within Vim, so there
 158 is a dictionary called "Actions.plist" (in the Resources folder of the
 159 application bundle) which contains all actions that may be called.  The key in
 160 this dictionary is the name of the action message (case sensitive), the value
 161 is not used.
 162
 163 ==============================================================================
 164 5. System services                                      *macvim-services*
 165
 166 MacVim supports a few system services.  These can be accessed from the MacVim
 167 submenu in the Services menu.  For services to work, MacVim.app should be
 168 located in the /Applications folder.  (You might have to logout and then login
 169 again before Mac OS X detects the MacVim services.)
 170
 171 These are the currently supported services:
 172 * New Tab Containing Selection: Opens a new tab in the topmost window and
 173   pastes the currently selected text in that tab.  A new window will be
 174   opened if necessary.
 175 * Open Selected File in Tab (Window): If the selected text represents a file
 176   name, then the corresponding file is opened in a new tab in the topmost
 177   window (in a new window).
 178
 179 ==============================================================================
 180 6. Known bugs/missing features                          *macvim-todo*
 181
 182 Here are some of the bigger bugs in MacVim.  Of course there are others, but
 183 these are ones that are know and/or which were judged major.
 184
 185 - Composing characters are not supported, they will mess up the display
 186 - Only "utf-8" is supported for 'enc'
 187 - Sometimes multibyte characters look "too wide", i.e. they overlap the
 188   following character.  It might help to change 'ambiwidth'.
 189 - Printing
 190 - No find/replace dialog
 191
 192 If you find new bugs then add a new issue at http://code.google.com/p/macvim/
 193 or post your findings to the vim_mac mailing list.  If you are missing feature
 194 X in MacVim then voice your opinion on the vim_mac mailing list; it might be
 195 simple to implement, but unless somebody ask for a particular feature then
 196 there is little incentive to add it.
 197
 198 ==============================================================================
 199 7. Hints                                                *macvim-hints*
 200
 201 In this section some general (not necessarily MacVim specific) hints are
 202 given.
 203
 204 Scenario: You try opening a bunch of files in tabs but not all files get
 205 opened in their own tab.
 206 Solution: To get around this, set 'tabpagemax' to something big in your
 207 .gvimrc file (e.g. ":set tabpagemax=100").
 208
 209 Scenario: You want to open a file in a tab in an already opened window, but
 210 typing "gvim filename" in Terminal opens it up in a separate window.
 211 Solution: Use the |--remote-tab| switch.  If you have several windows open you
 212 might have to specify which window you want the file to open in by using the
 213 |--servername| switch.  The title of a window usually ends in something like
 214 "VIM" or "VIM3" --- this is the server name of that window.  So to open a file
 215 named "foobar.txt" in a window which ends in "VIM3" you would type: >
 216         gvim --servername VIM3 --remote-tab foobar.txt
 217 For more information, consult the |client-server| manual page.
 218
 219 Scenario: You can't find the information on MacVim you thought should be in
 220 this manual page.
 221 Solution: Post your question on the vim_mac mailing list and wait for an
 222 answer.
 223
 224  vim:tw=78:sw=4:ts=8:ft=help:norl: