vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

netbeans.txt (38092B)


      1 *netbeans.txt*	For Vim version 9.2.  Last change: 2026 Apr 09
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Gordon Prieur et al.
      5 
      6 
      7 					*netbeans* *NetBeans* *netbeans-support*
      8 
      9 Vim NetBeans Protocol: a socket interface for Vim integration into an IDE.
     10 
     11 1.  Introduction				|netbeans-intro|
     12 2.  Integration features			|netbeans-integration|
     13 3.  Configuring Vim for NetBeans		|netbeans-configure|
     14 4.  Error Messages				|netbeans-messages|
     15 5.  Running Vim in NetBeans mode		|netbeans-run|
     16 6.  NetBeans protocol				|netbeans-protocol|
     17 7.  NetBeans commands				|netbeans-commands|
     18 8.  Known problems				|netbeans-problems|
     19 9.  Debugging NetBeans protocol			|netbeans-debugging|
     20 10. NetBeans External Editor
     21     10.1. Downloading NetBeans			|netbeans-download|
     22     10.2. NetBeans Key Bindings			|netbeans-keybindings|
     23     10.3. Preparing NetBeans for Vim		|netbeans-preparation|
     24     10.4. Obtaining the External Editor Module	|obtaining-exted|
     25     10.5. Setting up NetBeans to run with Vim	|netbeans-setup|
     26 
     27 {only available when compiled with the |+netbeans_intg| feature}
     28 
     29 ==============================================================================
     30 1. Introduction						*netbeans-intro*
     31 
     32 The NetBeans interface was initially developed to integrate Vim into the
     33 NetBeans Java IDE, using the external editor plugin.  This NetBeans plugin no
     34 longer exists for recent versions of NetBeans but the protocol was developed
     35 in such a way that any IDE can use it to integrate Vim.
     36 
     37 The NetBeans protocol of Vim is a text based communication protocol, over a
     38 classical TCP socket.  There is no dependency on Java or NetBeans.  Any
     39 language or environment providing a socket interface can control Vim using
     40 this protocol.  There are existing implementations in C, C++, Python and Java.
     41 The name NetBeans is kept today for historical reasons.
     42 
     43 Active project using the NetBeans protocol of Vim:
     44 - Eclim, (dead link) eclim.org/
     45 
     46 VimIntegration, description of various projects doing Vim Integration:
     47 	(dead link) www.freehackers.org/VimIntegration
     48 
     49 Projects using the NetBeans protocol of Vim are or were:
     50 - Agide, an IDE for the AAP project, written in Python (now replaced by
     51   |:Termdebug|): http://www.a-a-p.org (link now dead)
     52 - Clewn, a gdb integration into Vim, written in C:
     53 	http://clewn.sourceforge.net/
     54 - Pyclewn, a gdb integration into Vim, written in Python:
     55 	http://pyclewn.sourceforge.net/
     56 - VimWrapper, library to easy Vim integration into IDE:
     57 	(dead link) freehackers.org/VimWrapper
     58 Outdated projects (links don't work):
     59 - VimPlugin, integration of Vim inside Eclipse:
     60 	http://vimplugin.sourceforge.net/wiki/pmwiki.php
     61 - PIDA, IDE written in Python integrating Vim:
     62 	http://pida.co.uk/
     63 
     64 Check the specific project pages to see how to use Vim with these projects.
     65 
     66 An alternative is to use a channel, see |channel|.
     67 
     68 In the rest of this help page, we will use the term "Vim Controller" to
     69 describe the program controlling Vim through the NetBeans socket interface.
     70 
     71 
     72 About the NetBeans IDE ~
     73 
     74 NetBeans is an open source Integrated Development Environment developed
     75 jointly by Sun Microsystems, Inc. and the netbeans.org developer community.
     76 Initially just a Java IDE, NetBeans has had C, C++, and Fortran support added
     77 in recent releases.
     78 
     79 For more information visit the main NetBeans web site http://www.netbeans.org.
     80 The External Editor is now, unfortunately, declared obsolete.  See (link seems
     81 dead): externaleditor.netbeans.org.
     82 
     83 Sun Microsystems, Inc. also ships NetBeans under the name Sun ONE Studio.
     84 Visit http://www.sun.com for more information regarding the Sun ONE Studio
     85 product line.
     86 
     87 Current releases of NetBeans provide full support for Java and limited support
     88 for C, C++, and Fortran.  Current releases of Sun ONE Studio provide full
     89 support for Java, C, C++, and Fortran.
     90 
     91 ==============================================================================
     92 2. Integration features					*netbeans-integration*
     93 
     94 The NetBeans socket interface of Vim allows to get information from Vim or to
     95 ask Vim to perform specific actions:
     96 - get information about buffer: buffer name, cursor position, buffer content,
     97   etc.
     98 - be notified when buffers are open or closed
     99 - be notified of how the buffer content is modified
    100 - load and save files
    101 - modify the buffer content
    102 - installing special key bindings
    103 - raise the window, control the window geometry
    104 
    105 For sending key strokes to Vim or for evaluating functions in Vim, you must
    106 use the |clientserver| interface.
    107 
    108 
    109 ==============================================================================
    110 3. Configuring Vim for NetBeans			*netbeans-configure*
    111 
    112 For more help about installing Vim, please read |usr_90.txt| in the Vim User
    113 Manual.
    114 
    115 
    116 On Unix:
    117 --------
    118 
    119 When running configure without arguments the NetBeans interface should be
    120 included.  That is, if the configure check to find out if your system supports
    121 the required features succeeds.
    122 
    123 In case you do not want the NetBeans interface you can disable it by
    124 uncommenting a line with "--disable-netbeans" in the Makefile.
    125 
    126 Currently the NetBeans interface is supported by Vim running in a terminal and
    127 by gvim when it is run with one of the following GUIs: GTK, GNOME, Windows
    128 and Motif.
    129 
    130 							*netbeans-xpm*
    131 If Motif support is required the user must supply XPM libraries.
    132 The XPM library is required to show images within Vim with Motif.
    133 Without it the toolbar and signs will be disabled.
    134 
    135 The XPM library is provided by Arnaud Le Hors of the French National Institute
    136 for Research in Computer Science and Control.  It can be downloaded from
    137 https://ftp.nluug.nl/ftp/windowing/X/contrib/libraries/.  The current release,
    138 as of this writing, is xpm-3.4k-solaris.tgz, which is a gzip'ed tar file.  If
    139 you create the directory /usr/local/xpm and untar the file there you can use
    140 the uncommented lines in the Makefile without changing them.  If you use
    141 another xpm directory you will need to change the XPM_DIR in src/Makefile.
    142 
    143 
    144 On MS-Windows:
    145 --------------
    146 
    147 The Win32 support is now in beta stage.
    148 
    149 To use XPM signs on Win32 (e.g. when using with NetBeans) you can compile
    150 XPM by yourself or use precompiled libraries from (link seems dead):
    151 iamphet.nm.ru/misc/ (for MS Visual C++) or
    152 http://gnuwin32.sourceforge.net (for MinGW).
    153 
    154 Enable debugging:
    155 -----------------
    156 
    157 To enable debugging of Vim and of the NetBeans protocol, the "NBDEBUG" macro
    158 needs to be defined.  Search in the Makefile of the platform you are using for
    159 "NBDEBUG" to see what line needs to be uncommented.  This effectively adds
    160 "-DNBDEBUG" to the compile command.  Also see |netbeans-debugging|
    161 
    162 ==============================================================================
    163 4. Error Messages					*netbeans-messages*
    164 
    165 These error messages are specific to NetBeans socket protocol:
    166 
    167 							*E463*
    168 Region is guarded, cannot modify
    169 		The Vim Controller has defined guarded areas in the text,
    170 		which you cannot change.  Also sets the current buffer, if
    171 		necessary.
    172 
    173 							*E532*
    174 The defineAnnoType highlighting color name is too long
    175 		The maximum length of the "fg" or "bg" color argument in the
    176 		defineAnnoType command is 32 characters.
    177 		New in version 2.5.
    178 
    179 							*E656*
    180 Writes of unmodified buffers forbidden
    181 		Writes of unmodified buffers that were opened from the
    182 		Vim Controller are not possible.
    183 
    184 							*E657*
    185 Partial writes disallowed
    186 		Partial writes for buffers that were opened from the
    187 		Vim Controller are not allowed.
    188 
    189 							*E658*
    190 Connection lost for this buffer
    191 		The Vim Controller has become confused about the state of
    192 		this file.  Rather than risk data corruption, it has severed
    193 		the connection for this file.  Vim will take over
    194 		responsibility for saving changes to this file and the
    195 		Vim Controller will no longer know of these changes.
    196 
    197 							*E744*
    198 Read-only file
    199 		Vim normally allows changes to a read-only file and only
    200 		enforces the read-only rule if you try to write the file.
    201 		However, NetBeans does not let you make changes to a file
    202 		which is read-only and becomes confused if Vim does this.
    203 		So Vim does not allow modifications to files when run
    204 		in NetBeans mode.
    205 
    206 ==============================================================================
    207 5. Running Vim in NetBeans mode				*netbeans-run*
    208 
    209 There are two different ways to run Vim in NetBeans mode:
    210 
    211 	+ an IDE may start Vim with the |-nb| command line argument
    212 	+ NetBeans can be started from within Vim with the |:nbstart| command
    213 
    214 Vim uses a 3 second timeout on trying to make the connection.
    215 
    216 							*netbeans-parameters*
    217 Three forms can be used to setup the NetBeans connection parameters.
    218 When started from the command line, the |-nb| command line argument may be:
    219 
    220 	-nb={fname}				from a file
    221 	-nb:{hostname}:{addr}:{password}	directly
    222 	-nb					from a file or environment
    223 
    224 When started from within Vim, the |:nbstart| optional argument may be:
    225 
    226 	={fname}				from a file
    227 	:{hostname}:{addr}:{password}	        directly
    228 	<MISSING ARGUMENT>			from a file or environment
    229 
    230 							*E660* *E668*
    231 When NetBeans is started from the command line, for security reasons, the best
    232 method is to write the information in a file readable only by the user.  The
    233 name of the file can be passed with the "-nb={fname}" argument or, when "-nb"
    234 is used without a parameter, the environment variable "__NETBEANS_CONINFO".
    235 The file must contain these three lines, in any order:
    236 
    237 	host={hostname}
    238 	port={addr}
    239 	auth={password}
    240 
    241 Other lines are ignored.  The Vim Controller is responsible for deleting the
    242 file afterwards.
    243 
    244 {hostname} is the name of the machine where Vim Controller is running.  When
    245 omitted the environment variable "__NETBEANS_HOST" is used or the default
    246 "localhost".
    247 
    248 {addr} is the port number for the NetBeans interface.  When omitted the
    249 environment variable "__NETBEANS_SOCKET" is used or the default 3219.
    250 
    251 {password} is the password for connecting to NetBeans.  When omitted the
    252 environment variable "__NETBEANS_VIM_PASSWORD" is used or "changeme".
    253 
    254 Vim will initiate a socket connection (client side) to the specified host and
    255 port upon startup.  The password will be sent with the AUTH event when the
    256 connection has been established.
    257 
    258 
    259 ==============================================================================
    260 6. NetBeans protocol					*netbeans-protocol*
    261 
    262 The communication between the Vim Controller and Vim uses plain text
    263 messages.  This protocol was first designed to work with the external editor
    264 module of NetBeans.  Later it was extended to work with Agide (A-A-P GUI IDE,
    265 formerly http://www.a-a-p.org, link now dead) and then with other IDE.
    266 The extensions are marked with "version 2.1".
    267 
    268 Version 2.2 of the protocol has several minor changes which should only affect
    269 NetBeans users (ie, not Agide users).  However, a bug was fixed which could
    270 cause confusion.  The netbeans_saved() function sent a "save" protocol
    271 command.  In protocol version 2.1 and earlier this was incorrectly interpreted
    272 as a notification that a write had taken place.  In reality, it told NetBeans
    273 to save the file so multiple writes were being done.  This caused various
    274 problems and has been fixed in 2.2.  To decrease the likelihood of this
    275 confusion happening again, netbeans_saved() has been renamed to
    276 netbeans_save_buffer().
    277 
    278 We are now at version 2.5.  For the differences between 2.4 and 2.5 search for
    279 "2.5" below.
    280 
    281 The messages are currently sent over a socket.  Since the messages are in
    282 plain UTF-8 text this protocol could also be used with any other communication
    283 mechanism.
    284 
    285 Netbeans messages are processed when Vim is idle, waiting for user input.
    286 When Vim is run in non-interactive mode, for example when running an automated
    287 test case that sources a Vim script, the idle loop may not be called often
    288 enough.  In that case, insert |:sleep| commands in the Vim script.  The |:sleep|
    289 command does invoke Netbeans messages processing.
    290 
    291 6.1 Kinds of messages		|nb-messages|
    292 6.2 Terms			|nb-terms|
    293 6.3 Commands			|nb-commands|
    294 6.4 Functions and Replies	|nb-functions|
    295 6.5 Events			|nb-events|
    296 6.6 Special messages		|nb-special|
    297 6.7 Protocol errors		|nb-protocol_errors|
    298 
    299 
    300 6.1 Kinds of messages					*nb-messages*
    301 
    302 There are four kinds of messages:
    303 
    304 kind		direction	comment ~
    305 Command		IDE -> editor	no reply necessary
    306 Function	IDE -> editor	editor must send back a reply
    307 Reply		editor -> IDE	only in response to a Function
    308 Event		editor -> IDE	no reply necessary
    309 
    310 The messages are sent as a single line with a terminating newline character.
    311 Arguments are separated by a single space.  The first item of the message
    312 depends on the kind of message:
    313 
    314 kind		first item		example ~
    315 Command		bufID:name!seqno	11:showBalloon!123 "text"
    316 Function	bufID:name/seqno	11:getLength/123
    317 Reply		seqno			123 5000
    318 Event		bufID:name=seqno	11:keyCommand=123 "S-F2"
    319 
    320 
    321 
    322 6.2 Terms						*nb-terms*
    323 
    324 bufID		Buffer number.  A message may be either for a specific buffer
    325 		or generic.  Generic messages use a bufID of zero.  NOTE: this
    326 		buffer ID is assigned by the IDE, it is not Vim's buffer
    327 		number.  The bufID must be a sequentially rising number,
    328 		starting at one.  When the 'switchbuf' option is set to
    329 		"usetab" and the "bufID" buffer is not found in the current
    330 		tab page, the netbeans commands and functions that set this
    331 		buffer as the current buffer will jump to the first open
    332 		window that contains this buffer in other tab pages instead of
    333 		replacing the buffer in the current window.
    334 
    335 seqno		The IDE uses a sequence number for Commands and Functions.  A
    336 		Reply must use the sequence number of the Function that it is
    337 		associated with.  A zero sequence number can be used for
    338 		Events (the seqno of the last received Command or Function can
    339 		also be used).
    340 
    341 string		Argument in double quotes.  Text is in UTF-8 encoding.  This
    342 		means ASCII is passed as-is.  Special characters are
    343 		represented with a backslash:
    344 			\"	double quote
    345 			\n	newline
    346 			\r	carriage-return
    347 			\t	tab (optional, also works literally)
    348 			\\	backslash
    349 		NUL bytes are not allowed!
    350 
    351 boolean		Argument with two possible values:
    352 			T	true
    353 			F	false
    354 
    355 number		Argument with a decimal number.
    356 
    357 color		Argument with either a decimal number, "none" (without the
    358 		quotes) or the name of a color (without the quotes) defined
    359 		both in the color list in |highlight-ctermfg| and in the color
    360 		list in |gui-colors|.
    361 		New in version 2.5.
    362 
    363 offset		A number argument that indicates a byte position in a buffer.
    364 		The first byte has offset zero.  Line breaks are counted for
    365 		how they appear in the file (CR/LF counts for two bytes).
    366 		Note that a multibyte character is counted for the number of
    367 		bytes it takes.
    368 
    369 lnum/col	Argument with a line number and column number position.  The
    370 		line number starts with one, the column is the byte position,
    371 		starting with zero.  Note that a multibyte character counts
    372 		for several columns.
    373 
    374 pathname	String argument: file name with full path.
    375 
    376 
    377 6.3 Commands						*nb-commands*
    378 
    379 actionMenuItem	Not implemented.
    380 
    381 actionSensitivity
    382 		Not implemented.
    383 
    384 addAnno serNum typeNum off len
    385 		Place an annotation in this buffer.
    386 		Arguments:
    387 		   serNum	number	serial number of this placed
    388 					annotation, used to be able to remove
    389 					it
    390 		   typeNum	number	sequence number of the annotation
    391 					defined with defineAnnoType for this
    392 					buffer
    393 		   off		number	offset where annotation is to be
    394 					placed
    395 		   len		number	not used
    396 		In version 2.1 "lnum/col" can be used instead of "off".
    397 
    398 balloonResult text
    399 		Not implemented.
    400 
    401 close		Close the buffer.  This leaves us without current buffer, very
    402 		dangerous to use!
    403 
    404 create		Creates a buffer without a name.  Replaces the current buffer
    405 		(it's hidden when it was changed).
    406 		The Vim Controller should use this as the first command for a
    407 		file that is being opened.  The sequence of commands could be:
    408 			create
    409 			setCaretListener	(ignored)
    410 			setModified		(no effect)
    411 			setContentType		(ignored)
    412 			startDocumentListen
    413 			setTitle
    414 			setFullName
    415 
    416 defineAnnoType typeNum typeName tooltip glyphFile fg bg
    417 		Define a type of annotation for this buffer.
    418 		Arguments:
    419 		   typeNum	number	sequence number (not really used)
    420 		   typeName	string	name that identifies this annotation
    421 		   tooltip	string	not used
    422 		   glyphFile	string	name of icon file
    423 		   fg		color	foreground color for line highlighting
    424 		   bg		color	background color for line highlighting
    425 		Vim will define a sign for the annotation.
    426 		When color is a number, this is the "#rrggbb" Red, Green and
    427 		Blue values of the color (see |gui-colors|) and the
    428 		highlighting is only defined for gVim.
    429 		When color is a name, this color is defined both for Vim
    430 		running in a color terminal and for gVim.
    431 		When both "fg" and "bg" are "none" no line highlighting is
    432 		used (new in version 2.1).
    433 		When "glyphFile" is empty, no text sign is used (new in
    434 		version 2.1).
    435 		When "glyphFile" is one or two characters long, a text sign is
    436 		defined (new in version 2.1).
    437 		Note: the annotations will be defined in sequence, and the
    438 		sequence number is later used with addAnno.
    439 
    440 editFile pathname
    441 		Set the name for the buffer and edit the file "pathname", a
    442 		string argument.
    443 		Normal way for the IDE to tell the editor to edit a file.
    444 
    445 		You must set a bufId different of 0 with this command to
    446 		assign a bufId to the buffer.  It will trigger an event
    447 		fileOpened with a bufId of 0 but the buffer has been assigned.
    448 
    449 		If the IDE is going to pass the file text to the editor use
    450 		these commands instead:
    451 			setFullName
    452 			insert
    453 			initDone
    454 		New in version 2.1.
    455 
    456 enableBalloonEval
    457 		Not implemented.
    458 
    459 endAtomic	End an atomic operation.  The changes between "startAtomic"
    460 		and "endAtomic" can be undone as one operation.  But it's not
    461 		implemented yet.  Redraw when necessary.
    462 
    463 guard off len
    464 		Mark an area in the buffer as guarded.  This means it cannot
    465 		be edited.  "off" and "len" are numbers and specify the text
    466 		to be guarded.
    467 
    468 initDone	Mark the buffer as ready for use.  Implicitly makes the buffer
    469 		the current buffer.  Fires the BufReadPost autocommand event.
    470 
    471 insertDone starteol readonly
    472 		Sent by Vim Controller to tell Vim an initial file insert is
    473 		done.  This triggers a read message being printed.  If
    474 		"starteol" is "F" then the last line doesn't have a EOL.  If
    475 		"readonly" is "T" then the file is marked as readonly.  Prior
    476 		to version 2.3, no read messages were displayed after opening
    477 		a file.  New in version 2.3.
    478 
    479 moveAnnoToFront serNum
    480 		Not implemented.
    481 
    482 netbeansBuffer isNetbeansBuffer
    483 		If "isNetbeansBuffer" is "T" then this buffer is "owned" by
    484 		NetBeans.
    485 		New in version 2.2.
    486 
    487 putBufferNumber pathname
    488 		Associate a buffer number with the Vim buffer by the name
    489 		"pathname", a string argument.  To be used when the editor
    490 		reported editing another file to the IDE and the IDE needs to
    491 		tell the editor what buffer number it will use for this file.
    492 		Also marks the buffer as initialized.
    493 		New in version 2.1.
    494 
    495 raise		Bring the editor to the foreground.
    496 		Only when Vim is run with a GUI.
    497 		New in version 2.1.
    498 
    499 removeAnno serNum
    500 		Remove a previously placed annotation for this buffer.
    501 		"serNum" is the same number used in addAnno.
    502 
    503 save		Save the buffer when it was modified.  The other side of the
    504 		interface is expected to write the buffer and invoke
    505 		"setModified" to reset the "changed" flag of the buffer.
    506 		The writing is skipped when one of these conditions is true:
    507 		- 'write' is not set
    508 		- the buffer is read-only
    509 		- the buffer does not have a file name
    510 		- 'buftype' disallows writing
    511 		New in version 2.2.
    512 
    513 saveDone
    514 		Sent by Vim Controller to tell Vim a save is done.  This
    515 		triggers a save message being printed.  Prior to version 2.3,
    516 		no save messages were displayed after a save.
    517 		New in version 2.3.
    518 
    519 setAsUser	Not implemented.
    520 
    521 setBufferNumber pathname
    522 		Associate a buffer number with Vim buffer by the name
    523 		"pathname".  To be used when the editor reported editing
    524 		another file to the IDE and the IDE needs to tell the editor
    525 		what buffer number it will use for this file.
    526 		Has the side effect of making the buffer the current buffer.
    527 		See "putBufferNumber" for a more useful command.
    528 
    529 setContentType
    530 		Not implemented.
    531 
    532 setDot off	Make the buffer the current buffer and set the cursor at the
    533 		specified position.  If the buffer is open in another window
    534 		than make that window the current window.
    535 		If there are folds they are opened to make the cursor line
    536 		visible.
    537 		In version 2.1 "lnum/col" can be used instead of "off".
    538 
    539 setExitDelay seconds
    540 		Set the delay for exiting to "seconds", a number.
    541 		This delay is used to give the IDE a chance to handle things
    542 		before really exiting.  The default delay is two seconds.
    543 		New in version 2.1.
    544 		Obsolete in version 2.3.
    545 
    546 setFullName pathname
    547 		Set the file name to be used for a buffer to "pathname", a
    548 		string argument.
    549 		Used when the IDE wants to edit a file under control of the
    550 		IDE.  This makes the buffer the current buffer, but does not
    551 		read the file.  "insert" commands will be used next to set the
    552 		contents.
    553 
    554 setLocAndSize	Not implemented.
    555 
    556 setMark		Not implemented.
    557 
    558 setModified modified
    559 		When the boolean argument "modified" is "T" mark the buffer as
    560 		modified, when it is "F" mark it as unmodified.
    561 
    562 setModtime time
    563 		Update a buffers modification time after the file has been
    564 		saved directly by the Vim Controller.
    565 		New in version 2.3.
    566 
    567 setReadOnly readonly
    568 		When the boolean argument "readonly" is "T" for True, mark the
    569 		buffer as readonly, when it is "F" for False, mark it as not
    570 		readonly.  Implemented in version 2.3.
    571 
    572 setStyle	Not implemented.
    573 
    574 setTitle name
    575 		Set the title for the buffer to "name", a string argument.
    576 		The title is only used for the Vim Controller functions, not
    577 		by Vim.
    578 
    579 setVisible visible
    580 		When the boolean argument "visible" is "T", goto the buffer.
    581 		The "F" argument does nothing.
    582 
    583 showBalloon text
    584 		Show a balloon (popup window) at the mouse pointer position,
    585 		containing "text", a string argument.  The balloon should
    586 		disappear when the mouse is moved more than a few pixels.
    587 		Only when Vim is run with a GUI.
    588 		New in version 2.1.
    589 
    590 specialKeys
    591 		Map a set of keys (mostly function keys) to be passed back
    592 		to the Vim Controller for processing.  This lets regular IDE
    593 		hotkeys be used from Vim.
    594 		Implemented in version 2.3.
    595 
    596 startAtomic	Begin an atomic operation.  The screen will not be updated
    597 		until "endAtomic" is given.
    598 
    599 startCaretListen
    600 		Not implemented.
    601 
    602 startDocumentListen
    603 		Mark the buffer to report changes to the IDE with the
    604 		"insert" and "remove" events.  The default is to report
    605 		changes.
    606 
    607 stopCaretListen
    608 		Not implemented.
    609 
    610 stopDocumentListen
    611 		Mark the buffer to stop reporting changes to the IDE.
    612 		Opposite of startDocumentListen.
    613 		NOTE: if "netbeansBuffer" was used to mark this buffer as a
    614 		NetBeans buffer, then the buffer is deleted in Vim.  This is
    615 		for compatibility with Sun Studio 10.
    616 
    617 unguard off len
    618 		Opposite of "guard", remove guarding for a text area.
    619 		Also sets the current buffer, if necessary.
    620 
    621 version		Not implemented.
    622 
    623 
    624 6.4 Functions and Replies				*nb-functions*
    625 
    626 getDot		Not implemented.
    627 
    628 getCursor	Return the current buffer and cursor position.
    629 		The reply is:
    630 			seqno bufID lnum col off
    631 		seqno = sequence number of the function
    632 		bufID = buffer ID of the current buffer (if this is unknown -1
    633 			is used)
    634 		lnum  = line number of the cursor (first line is one)
    635 		col   = column number of the cursor (in bytes, zero based)
    636 		off   = offset of the cursor in the buffer (in bytes)
    637 		New in version 2.1.
    638 
    639 getLength	Return the length of the buffer in bytes.
    640 		Reply example for a buffer with 5000 bytes:
    641 			123 5000
    642 		TODO: explain use of partial line.
    643 
    644 getMark		Not implemented.
    645 
    646 getAnno serNum
    647 		Return the line number of the annotation in the buffer.
    648 		Argument:
    649 			serNum		serial number of this placed
    650 					annotation
    651 		The reply is:
    652 			123 lnum	line number of the annotation
    653 			123 0		invalid annotation serial number
    654 		New in version 2.4.
    655 
    656 getModified	When a buffer is specified: Return zero if the buffer does not
    657 		have changes, one if it does have changes.
    658 		When no buffer is specified (buffer number zero): Return the
    659 		number of buffers with changes.  When the result is zero it's
    660 		safe to tell Vim to exit.
    661 		New in version 2.1.
    662 
    663 getText		Return the contents of the buffer as a string.
    664 		Reply example for a buffer with two lines
    665 			123 "first line\nsecond line\n"
    666 		NOTE: docs indicate an offset and length argument, but this is
    667 		not implemented.
    668 
    669 insert off text
    670 		Insert "text" before position "off".  "text" is a string
    671 		argument, "off" a number.
    672 		"text" should have a "\n" (newline) at the end of each line.
    673 		Or "\r\n" when 'fileformat' is "dos".  When using "insert" in
    674 		an empty buffer Vim will set 'fileformat' accordingly.
    675 		When "off" points to the start of a line the text is inserted
    676 		above this line.  Thus when "off" is zero lines are inserted
    677 		before the first line.
    678 		When "off" points after the start of a line, possibly on the
    679 		NUL at the end of a line, the first line of text is appended
    680 		to this line.  Further lines come below it.
    681 		Possible replies:
    682 			123		no problem
    683 			123 !message	failed
    684 		Note that the message in the reply is not quoted.
    685 		Also sets the current buffer, if necessary.
    686 		Does not move the cursor to the changed text.
    687 		Resets undo information.
    688 
    689 remove off length
    690 		Delete "length" bytes of text at position "off".  Both
    691 		arguments are numbers.
    692 		Possible replies:
    693 			123		no problem
    694 			123 !message	failed
    695 		Note that the message in the reply is not quoted.
    696 		Also sets the current buffer, if necessary.
    697 
    698 saveAndExit	Perform the equivalent of closing Vim: ":confirm qall".
    699 		If there are no changed files or the user does not cancel the
    700 		operation Vim exits and no result is sent back.  The IDE can
    701 		consider closing the connection as a successful result.
    702 		If the user cancels the operation the number of modified
    703 		buffers that remains is returned and Vim does not exit.
    704 		New in version 2.1.
    705 
    706 
    707 6.5 Events						*nb-events*
    708 
    709 balloonEval off len type
    710 		The mouse pointer rests on text for a short while.  When "len"
    711 		is zero, there is no selection and the pointer is at position
    712 		"off".  When "len" is non-zero the text from position "off" to
    713 		"off" + "len" is selected.
    714 		Only sent after "enableBalloonEval" was used for this buffer.
    715 		"type" is not yet defined.
    716 		Not implemented yet.
    717 
    718 balloonText text
    719 		Used when 'ballooneval' is set and the mouse pointer rests on
    720 		some text for a moment.  "text" is a string, the text under
    721 		the mouse pointer.
    722 		Only when Vim is run with a GUI.
    723 		New in version 2.1.
    724 
    725 buttonRelease button lnum col
    726 		Report which button was pressed and the location of the cursor
    727 		at the time of the release.  Only for buffers that are owned
    728 		by the Vim Controller.  This event is not sent if the button
    729 		was released while the mouse was in the status line or in a
    730 		separator line.  If col is less than 1 the button release was
    731 		in the sign area.
    732 		New in version 2.2.
    733 
    734 disconnect
    735 		Tell the Vim Controller that Vim is exiting and not to try and
    736 		read or write more commands.
    737 		New in version 2.3.
    738 
    739 fileClosed	Not implemented.
    740 
    741 fileModified	Not implemented.
    742 
    743 fileOpened pathname open modified
    744 		A file was opened by the user.
    745 		Arguments:
    746 		   pathname	string	  name of the file
    747 		   open		boolean   always "T"
    748 		   modified	boolean   always "F"
    749 
    750 geometry cols rows x y
    751 		Report the size and position of the editor window.
    752 		Arguments:
    753 		   cols		number	  number of text columns
    754 		   rows		number	  number of text rows
    755 		   x		number	  pixel position on screen
    756 		   y		number	  pixel position on screen
    757 		Only works for Motif.
    758 
    759 insert off text
    760 		Text "text" has been inserted in Vim at position "off".
    761 		Only fired when enabled, see "startDocumentListen".
    762 
    763 invokeAction	Not implemented.
    764 
    765 keyCommand keyName
    766 		Reports a special key being pressed with name "keyName", which
    767 		is a string.
    768 		Supported key names:
    769 			F1		function key 1
    770 			F2		function key 2
    771 			...
    772 			F12		function key 12
    773 
    774 			' '		space (without the quotes)
    775 			!		exclamation mark
    776 			...		any other ASCII printable character
    777 			~		tilde
    778 
    779 			X		any unrecognized key
    780 
    781 		The key may be prepended by "C", "S" and/or "M" for Control,
    782 		Shift and Meta (Alt) modifiers.  If there is a modifier a dash
    783 		is used to separate it from the key name.  For example:
    784 		"C-F2".
    785 		ASCII characters are new in version 2.1.
    786 
    787 keyAtPos keyName lnum/col
    788 		Like "keyCommand" and also report the line number and column
    789 		of the cursor.
    790 		New in version 2.1.
    791 
    792 killed		A file was deleted or wiped out by the user and the buffer
    793 		annotations have been removed.  The bufID number for this
    794 		buffer has become invalid.  Only for files that have been
    795 		assigned a bufID number by the IDE.
    796 
    797 newDotAndMark off off
    798 		Reports the position of the cursor being at "off" bytes into
    799 		the buffer.  Only sent just before a "keyCommand" event.
    800 
    801 quit		Not implemented.
    802 
    803 remove off len
    804 		Text was deleted in Vim at position "off" with byte length
    805 		"len".
    806 		Only fired when enabled, see "startDocumentListen".
    807 
    808 revert		Not implemented.
    809 
    810 save		The buffer has been saved and is now unmodified.
    811 		Only fired when enabled, see "startDocumentListen".
    812 
    813 startupDone	The editor has finished its startup work and is ready for
    814 		editing files.
    815 		New in version 2.1.
    816 
    817 unmodified	The buffer is now unmodified.
    818 		Only fired when enabled, see "startDocumentListen".
    819 
    820 version vers	Report the version of the interface implementation.  Vim
    821 		reports "2.4" (including the quotes).
    822 
    823 
    824 6.6 Special messages					*nb-special*
    825 
    826 These messages do not follow the style of the messages above.  They are
    827 terminated by a newline character.
    828 
    829 ACCEPT		Not used.
    830 
    831 AUTH password	editor -> IDE: First message that the editor sends to the IDE.
    832 		Must contain the password for the socket server, as specified
    833 		with the |-nb| argument.  No quotes are used!
    834 
    835 DISCONNECT	IDE -> editor: break the connection.  The editor will exit.
    836 		The IDE must only send this message when there are no unsaved
    837 		changes!
    838 
    839 DETACH		IDE -> editor: break the connection without exiting the
    840 		editor.  Used when the IDE exits without bringing down the
    841 		editor as well.
    842 		New in version 2.1.
    843 
    844 REJECT		Not used.
    845 
    846 
    847 6.7 Protocol errors					*nb-protocol_errors*
    848 
    849 These errors occur when a message violates the protocol:
    850 *E627* *E628* *E629* *E632* *E633* *E634* *E635* *E636*
    851 *E637* *E638* *E639* *E640* *E641* *E642* *E643* *E644* *E645* *E646*
    852 *E647* *E648* *E649* *E650* *E651* *E652*
    853 
    854 
    855 ==============================================================================
    856 7. NetBeans commands					*netbeans-commands*
    857 
    858 							*:nbstart* *E511* *E838*
    859 :nbs[tart] {connection}	Start a new Netbeans session with {connection} as the
    860 			socket connection parameters.  The format of
    861 			{connection} is described in |netbeans-parameters|.
    862 			At any time, one may check if the netbeans socket is
    863 			connected by running the command:
    864 			':echo has("netbeans_enabled")'
    865 
    866 							*:nbclose*
    867 :nbc[lose]		Close the current NetBeans session.  Remove all placed
    868 			signs.
    869 
    870 							*:nbkey*
    871 :nb[key] {key}		Pass the {key} to the Vim Controller for processing.
    872 			When a hot-key has been installed with the specialKeys
    873 			command, this command can be used to generate a hotkey
    874 			message to the Vim Controller.
    875 			This command can also be used to pass any text to the
    876 			Vim  Controller.  It is used by Pyclewn, for example,
    877 			to build the complete set of gdb commands as Vim user
    878 			commands.
    879 			The events newDotAndMark, keyCommand and keyAtPos are
    880 			generated (in this order).
    881 
    882 
    883 ==============================================================================
    884 8. Known problems					*netbeans-problems*
    885 
    886 NUL bytes are not possible.  For editor -> IDE they will appear as NL
    887 characters.  For IDE -> editor they cannot be inserted.
    888 
    889 A NetBeans session may be initiated with Vim running in a terminal, and
    890 continued later in a GUI environment after running the |:gui| command.  In this
    891 case, the highlighting defined for the NetBeans annotations may be cleared
    892 when the ":gui" command sources .gvimrc and this file loads a colorscheme
    893 that runs the command ":highlight clear".
    894 New in version 2.5.
    895 
    896 
    897 ==============================================================================
    898 9. Debugging NetBeans protocol				*netbeans-debugging*
    899 
    900 To debug the Vim protocol, you must first compile Vim with debugging support
    901 and NetBeans debugging support.  See |netbeans-configure| for instructions
    902 about Vim compiling and how to enable debug support.
    903 
    904 When running Vim, set the following environment variables:
    905 
    906     export SPRO_GVIM_DEBUG=netbeans.log
    907     export SPRO_GVIM_DLEVEL=0xffffffff
    908 
    909 Vim will then log all the incoming and outgoing messages of the NetBeans
    910 protocol to the file netbeans.log .
    911 
    912 The content of netbeans.log after a session looks like this:
    913 Tue May 20 17:19:27 2008
    914 EVT: 0:startupDone=0
    915 CMD 1: (1) create
    916 CMD 2: (1) setTitle "testfile1.txt"
    917 CMD 3: (1) setFullName "testfile1.txt"
    918 EVT(suppressed): 1:remove=3 0 -1
    919 EVT: 1:fileOpened=0 "d:\\work\\vimWrapper\\vimWrapper2\\pyvimwrapper\\tests\\testfile1.txt" T F
    920 CMD 4: (1) initDone
    921 FUN 5: (0) getCursor
    922 REP 5: 1 1 0 0
    923 CMD 6: (2) create
    924 CMD 7: (2) setTitle "testfile2.txt"
    925 CMD 8: (2) setFullName "testfile2.txt"
    926 EVT(suppressed): 2:remove=8 0 -1
    927 EVT: 2:fileOpened=0 "d:\\work\\vimWrapper\\vimWrapper2\\pyvimwrapper\\tests\\testfile2.txt" T F
    928 CMD 9: (2) initDone
    929 
    930 
    931 ==============================================================================
    932 10. NetBeans External Editor
    933 
    934 NOTE: This information is obsolete!  Only relevant if you are using an old
    935 version of NetBeans.
    936 
    937 
    938 10.1. Downloading NetBeans			*netbeans-download*
    939 
    940 The NetBeans IDE is available for download from netbeans.org.  You can
    941 download a released version, download sources, or use CVS to download the
    942 current source tree.  If you choose to download sources, follow directions
    943 from netbeans.org on building NetBeans.
    944 
    945 Depending on the version of NetBeans you download, you may need to do further
    946 work to get the required External Editor module.  This is the module which
    947 lets NetBeans work with gvim (or xemacs :-).  See (dead link)
    948 externaleditor.netbeans.org
    949 for details on downloading this module if your NetBeans release does not have
    950 it.
    951 
    952 For C, C++, and Fortran support you will also need the cpp module.  See
    953 cpp.netbeans.org (link seems dead) for information regarding this
    954 module.
    955 
    956 You can also download Sun ONE Studio from Sun Microsystems, Inc for a 30 day
    957 free trial.  See http://www.sun.com for further details.
    958 
    959 
    960 10.2. NetBeans Key Bindings			*netbeans-keybindings*
    961 
    962 Vim understands a number of key bindings that execute NetBeans commands.
    963 These are typically all the Function key combinations.  To execute a NetBeans
    964 command, the user must press the Pause key followed by a NetBeans key binding.
    965 For example, in order to compile a Java file, the NetBeans key binding is
    966 "F9".  So, while in vim, press "Pause F9" to compile a java file.  To toggle a
    967 breakpoint at the current line, press "Pause Shift F8".
    968 
    969 The Pause key is Function key 21.  If you don't have a working Pause key and
    970 want to use F8 instead, use: >
    971 
    972 	:map <F8> <F21>
    973 
    974 The External Editor module dynamically reads the NetBeans key bindings so vim
    975 should always have the latest key bindings, even when NetBeans changes them.
    976 
    977 
    978 10.3. Preparing NetBeans for Vim		*netbeans-preparation*
    979 
    980 In order for NetBeans to work with vim, the NetBeans External Editor module
    981 must be loaded and enabled.  If you have a Sun ONE Studio Enterprise Edition
    982 then this module should be loaded and enabled.  If you have a NetBeans release
    983 you may need to find another way of obtaining this open source module.
    984 
    985 You can check if you have this module by opening the Tools->Options dialog
    986 and drilling down to the "Modules" list (IDE Configuration->System->Modules).
    987 If your Modules list has an entry for "External Editor" you must make sure
    988 it is enabled (the "Enabled" property should have the value "True").  If your
    989 Modules list has no External Editor see the next section on |obtaining-exted|.
    990 
    991 
    992 10.4. Obtaining the External Editor Module	*obtaining-exted*
    993 
    994 There are 2 ways of obtaining the External Editor module.  The easiest way
    995 is to use the NetBeans Update Center to download and install the module.
    996 Unfortunately, some versions do not have this module in their update
    997 center.  If you cannot download via the update center you will need to
    998 download sources and build the module.  I will try and get the module
    999 available from the NetBeans Update Center so building will be unnecessary.
   1000 Also check (dead link) externaleditor.netbeans.org
   1001 for other availability options.
   1002 
   1003 To download the External Editor sources via CVS and build your own module,
   1004 see (dead link) externaleditor.netbeans.org and http://www.netbeans.org.
   1005 Unfortunately, this is not a trivial procedure.
   1006 
   1007 
   1008 10.5. Setting up NetBeans to run with Vim	*netbeans-setup*
   1009 
   1010 Assuming you have loaded and enabled the NetBeans External Editor module
   1011 as described in |netbeans-preparation| all you need to do is verify that
   1012 the gvim command line is properly configured for your environment.
   1013 
   1014 Open the Tools->Options dialog and open the Editing category.  Select the
   1015 External Editor.  The right hand pane should contain a Properties tab and
   1016 an Expert tab.  In the Properties tab make sure the "Editor Type" is set
   1017 to "Vim".  In the Expert tab make sure the "Vim Command" is correct.
   1018 
   1019 You should be careful if you change the "Vim Command".  There are command
   1020 line options there which must be there for the connection to be properly
   1021 set up.  You can change the command name but that's about it.  If your gvim
   1022 can be found by your $PATH then the Vim Command can start with "gvim".  If
   1023 you don't want gvim searched from your $PATH then hard code in the full
   1024 Unix path name.  At this point you should get a gvim for any source file
   1025 you open in NetBeans.
   1026 
   1027 If some files come up in gvim and others (with different file suffixes) come
   1028 up in the default NetBeans editor you should verify the MIME type in the
   1029 Expert tab MIME Type property.  NetBeans is MIME oriented and the External
   1030 Editor will only open MIME types specified in this property.
   1031 
   1032 
   1033  vim:tw=78:ts=8:noet:ft=help:norl: