runtime/doc/usr_31.txt

   1 *usr_31.txt*    For Vim version 7.1.  Last change: 2007 May 08
   2
   3                      VIM USER MANUAL - by Bram Moolenaar
   4
   5                               Exploiting the GUI
   6
   7
   8 Vim works well in a terminal, but the GUI has a few extra items.  A file
   9 browser can be used for commands that use a file.  A dialog to make a choice
  10 between alternatives.  Use keyboard shortcuts to access menu items quickly.
  11
  12 |31.1|  The file browser
  13 |31.2|  Confirmation
  14 |31.3|  Menu shortcuts
  15 |31.4|  Vim window position and size
  16 |31.5|  Various
  17
  18      Next chapter: |usr_32.txt|  The undo tree
  19  Previous chapter: |usr_30.txt|  Editing programs
  20 Table of contents: |usr_toc.txt|
  21
  22 ==============================================================================
  23 *31.1*  The file browser
  24
  25 When using the File/Open... menu you get a file browser.  This makes it easier
  26 to find the file you want to edit.  But what if you want to split a window to
  27 edit another file?  There is no menu entry for this.  You could first use
  28 Window/Split and then File/Open..., but that's more work.
  29    Since you are typing most commands in Vim, opening the file browser with a
  30 typed command is possible as well.  To make the split command use the file
  31 browser, prepend "browse": >
  32
  33         :browse split
  34
  35 Select a file and then the ":split" command will be executed with it.  If you
  36 cancel the file dialog nothing happens, the window isn't split.
  37    You can also specify a file name argument.  This is used to tell the file
  38 browser where to start.  Example: >
  39
  40         :browse split /etc
  41
  42 The file browser will pop up, starting in the directory "/etc".
  43
  44 The ":browse" command can be prepended to just about any command that opens a
  45 file.
  46    If no directory is specified, Vim will decide where to start the file
  47 browser.  By default it uses the same directory as the last time.  Thus when
  48 you used ":browse split" and selected a file in "/usr/local/share", the next
  49 time you use a ":browse" it will start in "/usr/local/share" again.
  50    This can be changed with the 'browsedir' option.  It can have one of three
  51 values:
  52
  53         last            Use the last directory browsed (default)
  54         buffer          Use the same directory as the current buffer
  55         current         use the current directory
  56
  57 For example, when you are in the directory "/usr", editing the file
  58 "/usr/local/share/readme", then the command: >
  59
  60         :set browsedir=buffer
  61         :browse edit
  62
  63 Will start the browser in "/usr/local/share".  Alternatively: >
  64
  65         :set browsedir=current
  66         :browse edit
  67
  68 Will start the browser in "/usr".
  69
  70         Note:
  71         To avoid using the mouse, most file browsers offer using key presses
  72         to navigate.  Since this is different for every system, it is not
  73         explained here.  Vim uses a standard browser when possible, your
  74         system documentation should contain an explanation on the keyboard
  75         shortcuts somewhere.
  76
  77 When you are not using the GUI version, you could use the file explorer window
  78 to select files like in a file browser.  However, this doesn't work for the
  79 ":browse" command.  See |netrw-browse|.
  80
  81 ==============================================================================
  82 *31.2*  Confirmation
  83
  84 Vim protects you from accidentally overwriting a file and other ways to lose
  85 changes.  If you do something that might be a bad thing to do, Vim produces an
  86 error message and suggests appending ! if you really want to do it.
  87    To avoid retyping the command with the !, you can make Vim give you a
  88 dialog.  You can then press "OK" or "Cancel" to tell Vim what you want.
  89    For example, you are editing a file and made changes to it.  You start
  90 editing another file with: >
  91
  92         :confirm edit foo.txt
  93
  94 Vim will pop up a dialog that looks something like this:
  95
  96         +-----------------------------------+
  97         |                                   |
  98         |   ?   Save changes to "bar.txt"?  |
  99         |                                   |
 100         |   YES   NO             CANCEL     |
 101         +-----------------------------------+
 102
 103 Now make your choice.  If you do want to save the changes, select "YES".  If
 104 you want to lose the changes for ever: "NO".  If you forgot what you were
 105 doing and want to check what really changed use "CANCEL".  You will be back in
 106 the same file, with the changes still there.
 107
 108 Just like ":browse", the ":confirm" command can be prepended to most commands
 109 that edit another file.  They can also be combined: >
 110
 111         :confirm browse edit
 112
 113 This will produce a dialog when the current buffer was changed.  Then it will
 114 pop up a file browser to select the file to edit.
 115
 116         Note:
 117         In the dialog you can use the keyboard to select the choice.
 118         Typically the <Tab> key and the cursor keys change the choice.
 119         Pressing <Enter> selects the choice.  This depends on the system
 120         though.
 121
 122 When you are not using the GUI, the ":confirm" command works as well.  Instead
 123 of popping up a dialog, Vim will print the message at the bottom of the Vim
 124 window and ask you to press a key to make a choice. >
 125
 126         :confirm edit main.c
 127 <       Save changes to "Untitled"? ~
 128         [Y]es, (N)o, (C)ancel:  ~
 129
 130 You can now press the single key for the choice.  You don't have to press
 131 <Enter>, unlike other typing on the command line.
 132
 133 ==============================================================================
 134 *31.3*  Menu shortcuts
 135
 136 The keyboard is used for all Vim commands.  The menus provide a simple way to
 137 select commands, without knowing what they are called.  But you have to move
 138 your hand from the keyboard and grab the mouse.
 139    Menus can often be selected with keys as well.  This depends on your
 140 system, but most often it works this way.  Use the <Alt> key in combination
 141 with the underlined letter of a menu.  For example, <A-w> (<Alt> and w) pops
 142 up the Window menu.
 143    In the Window menu, the "split" item has the p underlined.  To select it,
 144 let go of the <Alt> key and press p.
 145
 146 After the first selection of a menu with the <Alt> key, you can use the cursor
 147 keys to move through the menus.  <Right> selects a submenu and <left> closes
 148 it.  <Esc> also closes a menu.  <Enter> selects a menu item.
 149
 150 There is a conflict between using the <Alt> key to select menu items, and
 151 using <Alt> key combinations for mappings.  The 'winaltkeys' option tells Vim
 152 what it should do with the <Alt> key.
 153    The default value "menu" is the smart choice: If the key combination is a
 154 menu shortcut it can't be mapped.  All other keys are available for mapping.
 155    The value "no" doesn't use any <Alt> keys for the menus.  Thus you must use
 156 the mouse for the menus, and all <Alt> keys can be mapped.
 157    The value "yes" means that Vim will use any <Alt> keys for the menus.  Some
 158 <Alt> key combinations may also do other things than selecting a menu.
 159
 160 ==============================================================================
 161 *31.4*  Vim window position and size
 162
 163 To see the current Vim window position on the screen use: >
 164
 165         :winpos
 166
 167 This will only work in the GUI.  The output may look like this:
 168
 169         Window position: X 272, Y 103 ~
 170
 171 The position is given in screen pixels.  Now you can use the numbers to move
 172 Vim somewhere else.  For example, to move it to the left a hundred pixels: >
 173
 174         :winpos 172 103
 175 <
 176         Note:
 177         There may be a small offset between the reported position and where
 178         the window moves.  This is because of the border around the window.
 179         This is added by the window manager.
 180
 181 You can use this command in your startup script to position the window at a
 182 specific position.
 183
 184 The size of the Vim window is computed in characters.  Thus this depends on
 185 the size of the font being used.  You can see the current size with this
 186 command: >
 187
 188         :set lines columns
 189
 190 To change the size set the 'lines' and/or 'columns' options to a new value: >
 191
 192         :set lines=50
 193         :set columns=80
 194
 195 Obtaining the size works in a terminal just like in the GUI.  Setting the size
 196 is not possible in most terminals.
 197
 198 You can start the X-Windows version of gvim with an argument to specify the
 199 size and position of the window: >
 200
 201         gvim -geometry {width}x{height}+{x_offset}+{y_offset}
 202
 203 {width} and {height} are in characters, {x_offset} and {y_offset} are in
 204 pixels.  Example: >
 205
 206         gvim -geometry 80x25+100+300
 207
 208 ==============================================================================
 209 *31.5*  Various
 210
 211 You can use gvim to edit an e-mail message.  In your e-mail program you must
 212 select gvim to be the editor for messages.  When you try that, you will
 213 see that it doesn't work: The mail program thinks that editing is finished,
 214 while gvim is still running!
 215    What happens is that gvim disconnects from the shell it was started in.
 216 That is fine when you start gvim in a terminal, so that you can do other work
 217 in that terminal.  But when you really want to wait for gvim to finish, you
 218 must prevent it from disconnecting.  The "-f" argument does this: >
 219
 220         gvim -f file.txt
 221
 222 The "-f" stands for foreground.  Now Vim will block the shell it was started
 223 in until you finish editing and exit.
 224
 225
 226 DELAYED START OF THE GUI
 227
 228 On Unix it's possible to first start Vim in a terminal.  That's useful if you
 229 do various tasks in the same shell.  If you are editing a file and decide you
 230 want to use the GUI after all, you can start it with: >
 231
 232         :gui
 233
 234 Vim will open the GUI window and no longer use the terminal.  You can continue
 235 using the terminal for something else.  The "-f" argument is used here to run
 236 the GUI in the foreground.  You can also use ":gui -f".
 237
 238
 239 THE GVIM STARTUP FILE
 240
 241 When gvim starts, it reads the gvimrc file.  That's similar to the vimrc file
 242 used when starting Vim.  The gvimrc file can be used for settings and commands
 243 that are only to be used when the GUI is going to be started.  For example,
 244 you can set the 'lines' option to set a different window size: >
 245
 246         :set lines=55
 247
 248 You don't want to do this in a terminal, since it's size is fixed (except for
 249 an xterm that supports resizing).
 250    The gvimrc file is searched for in the same locations as the vimrc file.
 251 Normally its name is "~/.gvimrc" for Unix and "$VIM/_gvimrc" for MS-Windows.
 252 The $MYGVIMRC environment variable is set to it, thus you can use this command
 253 to edit the file, if you have one: >
 254
 255         :edit $MYGVIMRC
 256 <
 257    If for some reason you don't want to use the normal gvimrc file, you can
 258 specify another one with the "-U" argument: >
 259
 260         gvim -U thisrc ...
 261
 262 That allows starting gvim for different kinds of editing.  You could set
 263 another font size, for example.
 264    To completely skip reading a gvimrc file: >
 265
 266         gvim -U NONE ...
 267
 268 ==============================================================================
 269
 270 Next chapter: |usr_32.txt|  The undo tree
 271
 272 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: