runtime/doc/netbeans.txt

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