README

   1 Compiling:
   2
   3 - To build the project:
   4     + patch vim7 src with MacVim patch
   5     + make vim7 src with --enable-gui=macvim
   6     + build MacVim.xcodeproj
   7 - To install:
   8     + copy MacVim.app to /Applications (or anywhere you want it)
   9     + in ~/.profile add this line:
  10       alias gvim='/Applications/MacVim.app/Contents/MacOS/Vim -g'
  11 - To run:
  12     + Double click MacVim icon
  13     + with the above alias you can type 'gvim' in terminal to open MacVim
  14       (if the -g switch is left out, then Vim is started in terminal mode)
  15     + in terminal mode of Vim, type :gui and MacVim will start
  16 - Technical notes:
  17     + to build a universal binary, the compiler AND linker needs the flags
  18       '-isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch ppc -arch i386'; also,
  19       make needs argument --with-mac-arch=both
  20     + vim runtime files are copied to
  21       'MacVim.app/Contents/Resources/vim/runtime/'
  22
  23 Weirdness:
  24
  25 - [obsolete] When the text system (Cocoa) comes across multi byte characters it
  26   automatically chooses a font for those characters;  this font may not be the
  27   same height as the one set on the text storage and hence the program must
  28   account for the fact that lines may have differing heights.
  29   We get around this problem by resizing the window to fit the text storage
  30   after the layout manager has performed layout.  As a side-effect the user
  31   sees how the window resizes when certain multi byte characters are being
  32   displayed.
  33 - [obsolete] Remember to set 'inputReceived = YES' in MMBackend
  34   handlePortMessage:, otherwise Vim will not inform MMVimController of
  35   changes it makes (e.g. in response to a key down event).
  36 - The way delegate messages from the tab bar are handled are based on lots of
  37   assumptions on how the code works.  See comments in tabView:... delegate
  38   messages in MMWindowController.
  39 - [obsolete] The insertion point is automatically moved to wherever changes are
  40   made in the text storage.  To set the position manually (via
  41   setSelectedRange:), first call endEditing on the text storage.
  42 - Delegate messages from the tab view need to be able to differentiate whether
  43   the message was sent due to the user clicking a tab with the mouse, or if the
  44   vim task initiated the change.  To facilitate this, flags must be set
  45   whenever the vim task does something that results in these delegate messages
  46   being sent.  See comments in the tabView:...Item: messages in
  47   MMWindowController.
  48 - In Vim the first tab has index 1, in the gui the first tab has index 0.  This
  49   is compensated for in MMBackend.m.
  50 - The PSMTabBarControl does not reorder the NSTabView when a user drags tabs
  51   around, so we must rely on [PSMTabBarControl representedItems] to get the
  52   correct order of tabs (the order which the user can 'see').  WARNING! This
  53   means that the code cannot rely on calls like
  54   [NSTabView selectTabViewItemAtIndex:] etc. since the NSTabView has the
  55   'wrong' order.
  56 - The MMVimController is added to the NSEventTrackingRunLoopMode, otherwise
  57   updates from Vim would not reach the MMVimController while the user
  58   resizes the window using the mouse.
  59 - It seems that (oneway void) DO messages can arrive when another such message
  60   is being processed.  For this reason, no input is sent to Vim whilst in
  61   processCommandQueue:.  Instead, messages are queued and sent when
  62   processCommandQueue: has finished.  Otherwise the invariant that all Vim
  63   messages must appear in the same order they were issued will be violated.
  64 - Text storage dimensions are not ever directly modified, instead a message is
  65   sent to Vim asking it to change the "shell size".  Otherwise, a message
  66   asking Vim to change the shell size might get lost and Vim and MacVim will
  67   have inconsistent states.
  68 - gui_mch_browse() and gui_mch_dialog() are blocking calls, but you can't put
  69   up dialogs in Cocoa which block until the user dismisses them (it uses
  70   callbacks).  This complicates the browsing somewhat.
  71 - When binding menus to :action note that that action will be used for all
  72   modes.  The reason for this is that MacVim needs to be able to execute such
  73   menu items even when no windows are open (e.g. newVimWindow:) and the default
  74   menu action relies on Vim to deal with it.
  75 - The 'help' key is treated as a special key by Cocoa; when the user presses
  76   this key the mouse cursor changes to a question mark and the application is
  77   put into 'context help mode'.  The key down event is never sent down the
  78   responder chain.  To get around this problem we are forced to subclass
  79   NSApplication and look for the 'help' key in sendEvent: (see MMApplication).
  80
  81
  82 Design decisions:
  83
  84 - Output is queued and sent to the MMVimController only when
  85   [MMBackend flushQueue] is called in order to minimize the amount of
  86   messages sent back and forth between the task and gui.  Also, this makes sure
  87   that commands reach MacVim in the same order they were issued by Vim.
  88 - Drawing commands are stored in a buffer (drawData) and put on the output
  89   queue whenever [MMBackend flush] is called.  This buffer might no
  90   longer be needed now that there is a general output queue.  However, the
  91   existing code works, so why change it?
  92 - [obsolete] The gui listens for tasks on a named port whose name is derived
  93   from CFBundleIdentifier (which is defined inside Info.plist of the app
  94   bundle).  In order to run two different copies of MacVim at the same time,
  95   they need to have differing bundle identifiers; otherwise one copy will not
  96   be able to create the named listening port and all tasks will connect to the
  97   first copy.
  98 - The gui creates a named NSConnection which vends the MMAppController object.
  99 - All tabs share one text view and its associated text storage.  There used to
 100   be one text view per tab, but this only complicated the code since Vim has no
 101   concept of different views (as in NSView).
 102 - Vim holds the actual state.  MacVim should never change Vim related states
 103   directly, instead it must ask Vim to change the state and wait for Vim to
 104   reply with an actual state change command.
 105 - If MacVim wants to change the state of Vim it must go through
 106   processInput:data:, this is an asynchronous call.
 107 - MacVim can query state information synchronously by adding a suitable message
 108   to MMBackendProtocol, however this must not change the state of Vim!
 109 - If MacVim or Vim dies, the NSConnection is invalidated and connectionDidDie:
 110   is invoked.
 111
 112
 113 Keyboard stuff:
 114
 115 - input ends up in one of the following methods
 116     (1)  insertText:
 117     (2)  doCommandBySelector:
 118     (3)  performKeyEquivalent:
 119
 120 - (1) handles: printable keys (a, Space, 1, ...) and <M-key> (also <M-C-key>).
 121   if Ctrl+Option is held [NSEvents characters] will translate the input to
 122   control characters; note that if the translation fails, then Shift and Option
 123   modifiers are NOT includeded in [NSEvent characters], but they are included
 124   in [NSEvent charactersIgnoringModifiers].  e.g. given <M-C-S-1>, characters
 125   returns 1, charactersIgnoringModifiers returns <M-S-1>.
 126 - (2) handles: Ctrl+key, enter, backspace, escape.
 127   same note on translation of Ctrl+key as above holds true.
 128 - (3) handles: Cmd+key, arrow keys, function keys, help key
 129 - <M-Space> and <Space> are two different characters (the former is 0xa0)
 130
 131
 132 Bugs:
 133
 134 - Using NSString initWithBytesNoCopy:::: causes crash when trying to set window
 135   title.
 136 - NSTabViewItem setInitialFirstResponder: seems to have no effect, so we
 137   manually set the first responder when the tab item selection changes.
 138 - PSMTabBarControl never removes itself as an observer, which can cause all
 139   sort of weird problems (crashes etc.), so this is taken care of at cleanup.
 140 - PSMTabBarControl retains its delegate, so the delegate is forcibly set to nil
 141   at cleanup, else there will be a memory leak.
 142
 143
 144 Features (!supp indicates that a feature is not supported):
 145
 146 - Multiple top-level windows: each window runs its own vim process (they are
 147   completely independent)
 148 - Tabs: uses PSMTabBarControl to show tabs, can reorder tabs by dragging them,
 149   has overflow menu, new tab button on tabline
 150 - Menubar: accelerators !supp, actext hint displayed as tool tip
 151   instead of on menu, each window has its own menu, set key equivalents with
 152   :menukeyequiv command
 153 - Toolbar: toolbariconsize supported (tiny&small equiv to 24x24 px,
 154   medium&large equiv to 32x32 px), toolbar supports 'icons' and 'text' options
 155   (but not 'tooltip' which is always on), each window has its own toolbar,
 156   custom toolbar items
 157 - Cocoa input protocols: input managers, character palette input etc.
 158   supported, marked text !supp, cocoa key bindings (DefaultKeyBinding.dict)
 159   are disabled
 160 - Mouse: resize (vim) windows, selection, different mouse cursors,
 161   autoscrolling whilst selecting (horizontal autoscroll !supp)
 162 - Drag and Drop: drag files onto dock icon to open in tabs, drag text and files
 163   onto text view
 164 - Zoom: Command-click to zoom to fill window, otherwise only zoom height,
 165   hold down Option to zoom all windows
 166 - Resize: live resize (although terribly slow), :set lines will not make window
 167   higher than can fit the screen (no such restrictions on width at the moment)
 168 - Pasteboard: star-register works with the mac os x pasteboard
 169 - Open/Save dialog: use with :browse
 170 - Gui dialogs
 171 - Fonts: bold/italic/underline traits supported, font changes with ':set gfn',
 172   or use font panel
 173 - File type associations: add more associations by editing Info.plist
 174 - Start GUI from terminal, type :gui
 175 - Scroll bars
 176 - Wide characters: but composed characters !supp
 177 - Printing: !supp
 178 - Find/Replace dialog: !supp
 179 - External editor protocol: !supp
 180 - Services menu: some simple minded provider entries
 181 - Encodings: !supp (enc, tenc always set to utf-8)
 182 - Autosave window position
 183 - Smart cascading of new windows