PageRenderTime 259ms CodeModel.GetById 237ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 1ms

/jEdit/tags/jedit-4-1-pre5/doc/users-guide/api-guide.xml

#
XML | 2353 lines | 2081 code | 264 blank | 8 comment | 0 complexity | 1c4327a1562dcbbc47f96f141e5a7b52 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1<!-- jEdit 3.2 Macro Guide, (C) 2001 John Gellene                -->
   2<!-- Thu Jun 21 23:49:14 EDT 2001 @200 /Internet Time/           -->
   3<!--                                                             -->
   4<!-- jEdit buffer-local properties:                              -->
   5<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2:           -->
   6<!--                                                             -->
   7<!-- This file contains the jEdit API Quick Reference            -->
   8
   9
  10<chapter id="api-guide"><title>General jEdit Classes</title>
  11
  12<sect1 id="class-jedit"><title>Class jEdit</title>
  13
  14<para>
  15    This is the main class of the application. All the methods in this
  16    class are static methods, so
  17    they are called with the following syntax, from both macros and
  18    plugins:
  19</para>
  20<programlisting>jEdit.<replaceable>method</replaceable>(<replaceable>parameters</replaceable>)
  21</programlisting>
  22
  23<para>
  24    Here are a few key methods:
  25</para>
  26
  27<itemizedlist>
  28
  29<listitem>
  30<funcsynopsis>
  31 <funcprototype>
  32  <funcdef>public static Buffer <function>openFile</function></funcdef>
  33  <paramdef>View <parameter>view</parameter></paramdef>
  34  <paramdef>String <parameter>path</parameter></paramdef>
  35 </funcprototype>
  36</funcsynopsis>
  37<para>
  38    Opens the file named <varname>path</varname> in the given
  39    <classname>View</classname>. To open a file in the current view, use the
  40    predefined variable <varname>view</varname> for the first parameter.
  41</para>
  42</listitem>
  43
  44<listitem>
  45<funcsynopsis>
  46 <funcprototype>
  47  <funcdef>public static Buffer <function>newFile</function></funcdef>
  48  <paramdef>View <parameter>view</parameter></paramdef>
  49 </funcprototype>
  50</funcsynopsis>
  51<para>
  52    This creates a new buffer captioned
  53    <guimenu>Untitled-&lt;n&gt;</guimenu>in the given
  54    <classname>View</classname>.
  55</para>
  56</listitem>
  57
  58<listitem>
  59<funcsynopsis>
  60 <funcprototype>
  61  <funcdef>public static boolean <function>closeBuffer</function></funcdef>
  62  <paramdef>View  <parameter>view</parameter></paramdef>
  63  <paramdef>Buffer  <parameter>buffer</parameter></paramdef>
  64 </funcprototype>
  65</funcsynopsis>
  66<para>
  67    Closes the buffer named <varname>buffer</varname> in the view named
  68    <varname>view</varname>. The user will be prompted to save the buffer
  69    before closing if there are unsaved changes.
  70</para>
  71</listitem>
  72
  73<listitem>
  74<funcsynopsis>
  75 <funcprototype>
  76  <funcdef>public static void <function>saveAllBuffers</function></funcdef>
  77  <paramdef>View <parameter>view</parameter></paramdef>
  78  <paramdef>boolean <parameter>confirm</parameter></paramdef>
  79 </funcprototype>
  80</funcsynopsis>
  81<para>
  82    This saves all open buffers with unsaved changes in the given
  83    <classname>View</classname>. The parameter <parameter>confirm</parameter>
  84    determines whether jEdit initially asks for confirmation of the save
  85    operation.
  86</para>
  87</listitem>
  88
  89<listitem>
  90<funcsynopsis>
  91 <funcprototype>
  92  <funcdef>public static boolean <function>closeAllBuffers</function></funcdef>
  93  <paramdef>View <parameter>view</parameter></paramdef>
  94 </funcprototype>
  95</funcsynopsis>
  96<para>
  97    Closes all buffers in the given <classname>View</classname>. A dialog
  98    window will be displayed for any buffers with unsaved changes to
  99    obtain user instructions.
 100</para>
 101</listitem>
 102
 103<listitem>
 104<funcsynopsis>
 105 <funcprototype>
 106  <funcdef>public static void <function>exit</function></funcdef>
 107  <paramdef>View <parameter>view</parameter></paramdef>
 108  <paramdef>boolean <parameter>reallyExit</parameter></paramdef>
 109 </funcprototype>
 110</funcsynopsis>
 111<para>
 112    This method causes jEdit to exit. If <parameter>reallyExit</parameter> is
 113    false and jEdit is running in background mode, the application will simply
 114    close all  buffers and views and remain in background mode.
 115</para>
 116</listitem>
 117
 118
 119<listitem>
 120<funcsynopsis>
 121 <funcprototype>
 122  <funcdef>public static String <function>getProperty</function></funcdef>
 123  <paramdef>String <parameter>name</parameter></paramdef>
 124 </funcprototype>
 125</funcsynopsis>
 126<para>
 127    Returns the value of the property named by <varname>name</varname>, or
 128    <constant>null</constant> if the property is undefined.
 129</para>
 130</listitem>
 131
 132<listitem>
 133<funcsynopsis>
 134 <funcprototype>
 135  <funcdef>public static void <function>setProperty</function></funcdef>
 136  <paramdef>String <parameter>name</parameter></paramdef>
 137  <paramdef>String <parameter>property</parameter></paramdef>
 138 </funcprototype>
 139</funcsynopsis>
 140<para>
 141    Sets the property named by <varname>name</varname> with the value
 142    <varname>property</varname>. An existing property is overwritten.
 143</para>
 144</listitem>
 145
 146<listitem>
 147<funcsynopsis>
 148 <funcprototype>
 149  <funcdef>public static boolean <function>getBooleanProperty</function></funcdef>
 150  <paramdef>String <parameter>name</parameter></paramdef>
 151 </funcprototype>
 152</funcsynopsis>
 153<para>
 154    Returns a <classname>boolean</classname> value of <constant>true</constant> or
 155    <constant>false</constant> for the property named by <varname>name</varname> by
 156    examining the contents of the property; returns
 157    <constant>false</constant> if the property cannot be found.
 158</para>
 159</listitem>
 160
 161<listitem>
 162<funcsynopsis>
 163 <funcprototype>
 164  <funcdef>public static void <function>setBooleanProperty</function></funcdef>
 165  <paramdef>String <parameter>name</parameter></paramdef>
 166  <paramdef>boolean <parameter>value</parameter></paramdef>
 167 </funcprototype>
 168</funcsynopsis>
 169<para>
 170    Sets the property named by <varname>name</varname> to
 171    <varname>value</varname>. The boolean value is stored internally as the
 172    string <quote>true</quote> or <quote>false</quote>.
 173</para>
 174</listitem>
 175
 176<listitem>
 177<funcsynopsis>
 178 <funcprototype>
 179  <funcdef>public static int <function>getIntegerProperty</function></funcdef>
 180  <paramdef>String <parameter>name</parameter></paramdef>
 181  <paramdef>int <parameter>defaultValue</parameter></paramdef>
 182 </funcprototype>
 183</funcsynopsis>
 184<para>
 185    Returns the integer value of the property named by
 186    <varname>name</varname>. If the property value is not a valid
 187    numeric string, returns <varname>defaultValue</varname> instead.
 188</para>
 189</listitem>
 190
 191<listitem>
 192<funcsynopsis>
 193 <funcprototype>
 194  <funcdef>public static void <function>setIntegerProperty</function></funcdef>
 195  <paramdef>String <parameter>name</parameter></paramdef>
 196  <paramdef>int <parameter>value</parameter></paramdef>
 197 </funcprototype>
 198</funcsynopsis>
 199<para>
 200    Sets the property named by <varname>name</varname> to
 201    <varname>value</varname>.
 202</para>
 203</listitem>
 204
 205<listitem>
 206<funcsynopsis>
 207 <funcprototype>
 208  <funcdef>public static Color <function>getColorProperty</function></funcdef>
 209  <paramdef>String <parameter>name</parameter></paramdef>
 210 </funcprototype>
 211</funcsynopsis>
 212<para>
 213    Returns the value of the specified property as a
 214    <classname>java.awt.Color</classname> instance, or <constant>null</constant>
 215    if the color value cannot be parsed.
 216</para>
 217</listitem>
 218
 219<listitem>
 220<funcsynopsis>
 221 <funcprototype>
 222  <funcdef>public static void <function>setColorProperty</function></funcdef>
 223  <paramdef>String <parameter>name</parameter></paramdef>
 224  <paramdef>Color <parameter>value</parameter></paramdef>
 225 </funcprototype>
 226</funcsynopsis>
 227<para>
 228    Sets the property named by <varname>name</varname> to
 229    the textual representation of the color instance named by
 230    <varname>value</varname>.
 231</para>
 232</listitem>
 233
 234<listitem>
 235<funcsynopsis>
 236 <funcprototype>
 237  <funcdef>public static Font <function>getFontProperty</function></funcdef>
 238  <paramdef>String <parameter>name</parameter></paramdef>
 239 </funcprototype>
 240</funcsynopsis>
 241<para>
 242    Returns the value of the specified property as a
 243    <classname>java.awt.Font</classname> instance, or <constant>null</constant>
 244    if the font specification cannot be parsed.
 245</para>
 246</listitem>
 247
 248<listitem>
 249<funcsynopsis>
 250 <funcprototype>
 251  <funcdef>public static void <function>setFontProperty</function></funcdef>
 252  <paramdef>String <parameter>name</parameter></paramdef>
 253  <paramdef>Font <parameter>value</parameter></paramdef>
 254 </funcprototype>
 255</funcsynopsis>
 256<para>
 257    Sets the property named by <varname>name</varname> to
 258    the textual representation of the font instance stored in
 259    <varname>value</varname>.
 260</para>
 261</listitem>
 262
 263<listitem>
 264<funcsynopsis>
 265 <funcprototype>
 266  <funcdef>public static void <function>setTemporaryProperty</function></funcdef>
 267  <paramdef>String <parameter>name</parameter></paramdef>
 268  <paramdef>String <parameter>property</parameter></paramdef>
 269 </funcprototype>
 270</funcsynopsis>
 271<para>
 272    This sets a property that will be stored during the current
 273    jEdit session only. This method is useful for storing a value
 274    obtained by one macro for use by another macro, because it does not
 275    clutter up the user properties file on disk.
 276</para>
 277</listitem>
 278
 279<listitem>
 280<funcsynopsis>
 281 <funcprototype>
 282  <funcdef>public static String <function>getJEditHome</function></funcdef>
 283  <void/>
 284 </funcprototype>
 285</funcsynopsis>
 286<para>
 287    Returns the path of the directory containing the jEdit executable file.
 288</para>
 289</listitem>
 290
 291<listitem>
 292<funcsynopsis>
 293 <funcprototype>
 294  <funcdef>public static String <function>getSettingsDirectory</function></funcdef>
 295  <void/>
 296 </funcprototype>
 297</funcsynopsis>
 298<para>
 299    Returns the path of the directory in which user-specific settings
 300    are stored. This will be <constant>null</constant> if jEdit was
 301    started with the
 302    <command>-nosettings</command> command-line switch; so do not
 303    blindly use this method without checking for a null return value
 304    first.
 305</para>
 306</listitem>
 307
 308</itemizedlist>
 309
 310
 311<para>The jEdit object also maintains a number of collections which
 312are useful in some situations. They include the following:</para>
 313
 314<itemizedlist>
 315
 316<listitem>
 317<funcsynopsis>
 318 <funcprototype>
 319  <funcdef>public static EditAction[] <function>getActions</function></funcdef>
 320  <void/>
 321 </funcprototype>
 322</funcsynopsis>
 323<para>
 324    Returns an array of <quote>actions</quote> or short routines maintained and used
 325    by the editor.
 326</para>
 327</listitem>
 328
 329<listitem>
 330<funcsynopsis>
 331 <funcprototype>
 332  <funcdef>public static EditAction <function>getAction</function></funcdef>
 333  <paramdef>String <parameter>action</parameter></paramdef>
 334 </funcprototype>
 335</funcsynopsis>
 336<para>
 337    Returns the action named <varname>action</varname>, or
 338    <constant>null</constant> if it does not exist.
 339</para>
 340</listitem>
 341
 342<listitem>
 343<funcsynopsis>
 344 <funcprototype>
 345  <funcdef>public static Properties <function>getProperties</function></funcdef>
 346  <void/>
 347 </funcprototype>
 348</funcsynopsis>
 349<para>
 350    Returns a Java <classname>Properties</classname> object (a class derived from
 351    <classname>Hashtable</classname>) holding all properties
 352    currently used by the program.  The constituent properties fall into three
 353    categories: application properties, <quote>site</quote> properties, and
 354    <quote>user</quote> properties.  Site properties take precedence over application
 355    properties with the same <quote>key</quote> or name, and user properties take
 356    precedence over both application and site properties.  User settings are
 357    written to a file named <filename>properties</filename> in the user settings
 358    directory upon program exit or whenever <function>jEdit.saveSettings()</function>
 359    is called.
 360</para>
 361</listitem>
 362
 363<listitem>
 364<funcsynopsis>
 365 <funcprototype>
 366  <funcdef>public static Buffer[] <function>getBuffers</function></funcdef>
 367  <void/>
 368 </funcprototype>
 369</funcsynopsis>
 370<para>
 371    Returns an array of open buffers.
 372</para>
 373</listitem>
 374
 375<listitem>
 376<funcsynopsis>
 377 <funcprototype>
 378  <funcdef>public static int <function>getBufferCount</function></funcdef>
 379  <void/>
 380 </funcprototype>
 381</funcsynopsis>
 382<para>
 383    Returns the number of open buffers.
 384</para>
 385</listitem>
 386
 387<listitem>
 388<funcsynopsis>
 389 <funcprototype>
 390  <funcdef>public static Buffer <function>getBuffer</function></funcdef>
 391  <paramdef>String <parameter>path</parameter></paramdef>
 392 </funcprototype>
 393</funcsynopsis>
 394<para>
 395    Returns the <classname>Buffer</classname> object containing the file named
 396    <varname>path</varname>. or <constant>null</constant> if the buffer does not exist.
 397</para>
 398</listitem>
 399
 400<listitem>
 401<funcsynopsis>
 402 <funcprototype>
 403  <funcdef>public static Mode[] <function>getModes</function></funcdef>
 404  <void/>
 405 </funcprototype>
 406</funcsynopsis>
 407<para>
 408    Returns an array containing all editing modes used by jEdit.
 409</para>
 410</listitem>
 411
 412<listitem>
 413<funcsynopsis>
 414 <funcprototype>
 415  <funcdef>public static Mode <function>getMode</function></funcdef>
 416  <paramdef>String <parameter>name</parameter></paramdef>
 417 </funcprototype>
 418</funcsynopsis>
 419<para>
 420    Returns the editing mode named by <varname>name</varname>, or
 421    <constant>null</constant> if such a mode does not exist.
 422</para>
 423</listitem>
 424
 425<listitem>
 426<funcsynopsis>
 427 <funcprototype>
 428  <funcdef>public static EditPlugin[] <function>getPlugins</function></funcdef>
 429  <void/>
 430 </funcprototype>
 431</funcsynopsis>
 432<para>
 433    Returns an array containing all loaded plugins.
 434</para>
 435</listitem>
 436
 437<listitem>
 438<funcsynopsis>
 439 <funcprototype>
 440  <funcdef>plugin static EditPlugin <function>getPlugin</function></funcdef>
 441  <paramdef>String <parameter>name</parameter></paramdef>
 442 </funcprototype>
 443</funcsynopsis>
 444<para>
 445    Returns the plugin named by <varname>name</varname>, or
 446    <constant>null</constant> if such a plugin does not exist.
 447</para>
 448</listitem>
 449
 450</itemizedlist>
 451</sect1>
 452
 453<sect1 id="class-view"><title>Class View</title>
 454
 455<para>
 456    This class represents the <quote>parent</quote> or top-level frame window
 457    in which the editing occurs. It contains the various visible
 458    components of the program, including the editing pane, menu bar,
 459    toolbar, and any docked windows.
 460</para>
 461
 462<para>
 463    Some useful methods from this class include the following:
 464</para>
 465
 466<itemizedlist>
 467
 468<listitem>
 469<funcsynopsis>
 470 <funcprototype>
 471  <funcdef>public void <function>splitHorizontally</function></funcdef>
 472  <void/>
 473 </funcprototype>
 474</funcsynopsis>
 475<para>
 476    Splits the view horizontally.
 477</para>
 478</listitem>
 479
 480<listitem>
 481<funcsynopsis>
 482 <funcprototype>
 483  <funcdef>public void <function>splitVertically</function></funcdef>
 484  <void/>
 485 </funcprototype>
 486</funcsynopsis>
 487<para>
 488    Splits the view vertically.
 489</para>
 490</listitem>
 491
 492<listitem>
 493<funcsynopsis>
 494 <funcprototype>
 495  <funcdef>public void <function>unsplit</function></funcdef>
 496  <void/>
 497 </funcprototype>
 498</funcsynopsis>
 499<para>
 500    Unsplits the view.
 501</para>
 502</listitem>
 503
 504<listitem>
 505<funcsynopsis>
 506 <funcprototype>
 507  <funcdef>public synchronized void <function>showWaitCursor</function></funcdef>
 508  <void/>
 509 </funcprototype>
 510</funcsynopsis>
 511<para>
 512    Shows a <quote>waiting</quote> cursor (typically, an hourglass).
 513</para>
 514</listitem>
 515
 516<listitem>
 517<funcsynopsis>
 518 <funcprototype>
 519  <funcdef>public synchronized void <function>hideWaitCursor</function></funcdef>
 520  <void/>
 521 </funcprototype>
 522</funcsynopsis>
 523<para>
 524    Removes the <quote>waiting</quote> cursor. This method and
 525    <function>showWaitCursor()</function> are implemented using a reference
 526    count of requests for wait cursors, so that nested calls work
 527    correctly; however, you should
 528    be careful to use these methods in tandem.
 529</para>
 530</listitem>
 531
 532<listitem>
 533<funcsynopsis>
 534 <funcprototype>
 535  <funcdef>public StatusBar <function>getStatus</function></funcdef>
 536  <void/>
 537 </funcprototype>
 538</funcsynopsis>
 539<para>
 540    Each <classname>View</classname> displays a
 541    <classname>StatusBar</classname> at its bottom edge. It shows the
 542    current cursor position, the editing mode of the current buffer and
 543    other information. The method <function>setMessage(String
 544    message)</function> can be called on the return value of
 545    <function>getStatus()</function> to display reminders or updates.
 546    The message remains until the method is called
 547    again. To display a temporary message in the status bar, call
 548    <function>setMessageAndClear(String message)</function>, which will
 549    erase the message automatically after ten seconds.
 550</para>
 551</listitem>
 552
 553<listitem>
 554<funcsynopsis>
 555 <funcprototype>
 556  <funcdef>public DockableWindowManager <function>getDockableWindowManager</function></funcdef>
 557  <void/>
 558 </funcprototype>
 559</funcsynopsis>
 560<para>
 561    The object returned by this method keeps track of all dockable
 562    windows. See <xref linkend="class-dockablewindowmanager" />.
 563</para>
 564</listitem>
 565
 566</itemizedlist>
 567
 568</sect1>
 569
 570<sect1 id="class-jedittextarea"><title>Class JEditTextArea</title>
 571
 572<para>
 573    This class is the visible component that displays the file
 574    being edited. It is derived from Java's
 575    <classname>JComponent</classname> class.
 576</para>
 577
 578<para>
 579    Methods in this class that deal with selecting text
 580    rely upon classes derived from jEdit's
 581    <classname>Selection</classname> class. The
 582    <quote>Selection API</quote> permits selection and concurrent manipulation
 583    of multiple, non-contiguous regions of text. After describing the
 584    selection classes, we will outline the selection methods
 585    of <classname>JEditTextArea</classname>, followed by a listing of
 586    other methods in this class that are useful in writing macros.
 587</para>
 588
 589<sect2 id="class-selection"><title>Class Selection</title>
 590  <para>
 591    This is an <glossterm>abstract class</glossterm> which holds data
 592    on a region of selected text. As an abstract class, it cannot be used
 593    directly, but instead serves as a parent class for specific types
 594    of selection structures.  The definition of
 595    <classname>Selection</classname> contains two child classes used by the
 596    Selection API:
 597  </para>
 598
 599  <itemizedlist>
 600    <listitem>
 601      <para>
 602        <classname>Selection.Range</classname> - representing an ordinary
 603        range of selected text
 604      </para>
 605    </listitem>
 606    <listitem>
 607      <para>
 608        <classname>Selection.Rect</classname> - representing a rectangular
 609        selection region
 610      </para>
 611    </listitem>
 612  </itemizedlist>
 613
 614  <para>
 615    A new instance of either type of <classname>Selection</classname>
 616    can be created by specifying its starting and ending caret positions:
 617  </para>
 618
 619  <informalexample><programlisting>selRange = new Selection.Range(start, end);
 620setRect = new Selection.Rect(start, end);</programlisting></informalexample>
 621
 622  <para>
 623    Both classes inherit or implement the following methods of the parent
 624    <classname>Selection</classname> class:
 625  </para>
 626
 627  <itemizedlist>
 628
 629    <listitem>
 630      <funcsynopsis>
 631        <funcprototype>
 632          <funcdef>public int <function>getStart</function></funcdef>
 633          <void/>
 634        </funcprototype>
 635      </funcsynopsis>
 636    </listitem>
 637
 638    <listitem>
 639      <funcsynopsis>
 640        <funcprototype>
 641          <funcdef>public int <function>getEnd</function></funcdef>
 642          <void/>
 643        </funcprototype>
 644      </funcsynopsis>
 645      <para>
 646        Retrieves the buffer position representing the start or end
 647        of the selection.
 648      </para>
 649    </listitem>
 650
 651    <listitem>
 652      <funcsynopsis>
 653        <funcprototype>
 654          <funcdef>public int <function>getStartLine</function></funcdef>
 655          <void/>
 656        </funcprototype>
 657      </funcsynopsis>
 658    </listitem>
 659
 660    <listitem>
 661      <funcsynopsis>
 662        <funcprototype>
 663          <funcdef>public int <function>getEndLine</function></funcdef>
 664          <void/>
 665        </funcprototype>
 666      </funcsynopsis>
 667      <para>
 668        Retrieves the zero-based index number representing the line
 669        on which the selection starts or ends.
 670      </para>
 671    </listitem>
 672
 673    <listitem>
 674      <funcsynopsis>
 675        <funcprototype>
 676          <funcdef>public int <function>getStart</function></funcdef>
 677          <paramdef>Buffer <parameter>buffer</parameter></paramdef>
 678          <paramdef>int <parameter>line</parameter></paramdef>
 679        </funcprototype>
 680      </funcsynopsis>
 681    </listitem>
 682
 683    <listitem>
 684      <funcsynopsis>
 685        <funcprototype>
 686          <funcdef>public int <function>getEnd</function></funcdef>
 687          <paramdef>Buffer <parameter>buffer</parameter></paramdef>
 688          <paramdef>int <parameter>line</parameter></paramdef>
 689        </funcprototype>
 690      </funcsynopsis>
 691      <para>
 692        These two methods return the position of the beginning or end of
 693        that portion of the selection falling on the line referenced by
 694        the <parameter>line</parameter> parameter.  The parameter
 695        <parameter>buffer</parameter> is required because a
 696        <classname>Selection</classname> object is a lightweight structure
 697        that does not contain a reference to the
 698        <classname>Buffer</classname> object to which it relates.
 699      </para>
 700      <para>
 701        These methods do not check whether the <parameter>line</parameter>
 702        parameter is within the range of lines actually covered by the
 703        selection. They would typically be used within a
 704        loop defined by the <function>getStartLine()</function> and
 705        <function>getEndLine()</function> methods to manipulate
 706        selection text on a line-by-line basis.  Using them without range
 707        checking could cause unintended behavior.
 708      </para>
 709    </listitem>
 710
 711  </itemizedlist>
 712
 713</sect2>
 714
 715<sect2 id="class-jedittextarea-selection"><title>Selection methods in
 716JEditTextArea</title>
 717<para>
 718  A <classname>JEditTextArea</classname> object maintains an
 719  <classname>Vector</classname> of current <classname>Selection</classname>
 720  objects. When a selection is added, the <classname>JEditTextArea</classname>
 721  attempts to merge the new selection with any existing selection whose range
 722  contains or overlaps with the new item.  When selections are added or
 723  removed using by these methods, the editing display is updated to show
 724  the change in selection status.
 725</para>
 726
 727<para>
 728  Here are the principal methods of <classname>JEditTextArea</classname>
 729  dealing with <classname>Selection</classname> objects:
 730</para>
 731
 732<sect3 id="class-jedittextarea-selection-add-remove">
 733<title>Adding and removing selections</title>
 734<itemizedlist>
 735
 736  <listitem>
 737    <funcsynopsis>
 738      <funcprototype>
 739        <funcdef>public void <function>setMultipleSelectionEnabled</function></funcdef>
 740        <paramdef>boolean <parameter>multi</parameter></paramdef>
 741      </funcprototype>
 742    </funcsynopsis>
 743    <para>
 744      Set multiple selection on or off according to the value of
 745      <parameter>multi</parameter>. This only affects the ability to
 746      make multiple selections in the user interface; macros and plugins
 747      can manipulate them regardless of the setting of this flag. In fact,
 748      in most cases, calling this method should not be necessary.
 749    </para>
 750  </listitem>
 751
 752  <listitem>
 753    <funcsynopsis>
 754      <funcprototype>
 755        <funcdef>public Selection[] <function>getSelection</function></funcdef>
 756        <void/>
 757      </funcprototype>
 758    </funcsynopsis>
 759    <para>
 760      Returns an array containing a copy of the current selections.
 761    </para>
 762  </listitem>
 763
 764  <listitem>
 765    <funcsynopsis>
 766      <funcprototype>
 767        <funcdef>public int <function>getSelectionCount</function></funcdef>
 768        <void/>
 769      </funcprototype>
 770    </funcsynopsis>
 771    <para>
 772      Returns the current number of selections.  This can be used to test
 773      for the existence of selections.
 774    </para>
 775  </listitem>
 776
 777  <listitem>
 778    <funcsynopsis>
 779      <funcprototype>
 780        <funcdef>public Selection <function>getSelectionAtOffset</function></funcdef>
 781        <paramdef>int <parameter>offset</parameter></paramdef>
 782      </funcprototype>
 783    </funcsynopsis>
 784    <para>
 785      Returns the <classname>Selection</classname> containing the specific offset,
 786      or <constant>null</constant> if there is no selection at that offset.
 787    </para>
 788  </listitem>
 789
 790  <listitem>
 791    <funcsynopsis>
 792      <funcprototype>
 793        <funcdef>public void <function>addToSelection</function></funcdef>
 794        <paramdef>Selection <parameter>selection</parameter></paramdef>
 795      </funcprototype>
 796    </funcsynopsis>
 797  </listitem>
 798
 799  <listitem>
 800    <funcsynopsis>
 801      <funcprototype>
 802        <funcdef>public void <function>addToSelection</function></funcdef>
 803        <paramdef>Selection[] <parameter>selection</parameter></paramdef>
 804      </funcprototype>
 805    </funcsynopsis>
 806    <para>
 807      Adds a single <classname>Selection</classname> or an array of
 808      <classname>Selection</classname> objects to the existing collection
 809      maintained by the <classname>JEditTextArea</classname>.  Nested or
 810      overlapping selections will be merged where possible.
 811    </para>
 812  </listitem>
 813
 814  <listitem>
 815    <funcsynopsis>
 816      <funcprototype>
 817        <funcdef>public void <function>extendSelection</function></funcdef>
 818        <paramdef>int <parameter>offset</parameter></paramdef>
 819        <paramdef>int <parameter>end</parameter></paramdef>
 820      </funcprototype>
 821    </funcsynopsis>
 822    <para>
 823      Extends the existing selection containing the position at
 824      <parameter>offset</parameter> to the position represented by
 825      <parameter>end</parameter>.  If there is no selection containing
 826      <parameter>offset</parameter> the method creates a new
 827      <classname>Selection.Range</classname> extending from
 828      <parameter>offset</parameter> to <parameter>end</parameter> and
 829      adds it to the current collection.
 830    </para>
 831  </listitem>
 832
 833  <listitem>
 834    <funcsynopsis>
 835      <funcprototype>
 836        <funcdef>public void <function>removeFromSelection</function></funcdef>
 837        <paramdef>Selection <parameter>sel</parameter></paramdef>
 838      </funcprototype>
 839    </funcsynopsis>
 840  </listitem>
 841
 842  <listitem>
 843    <funcsynopsis>
 844      <funcprototype>
 845        <funcdef>public void <function>removeFromSelection</function></funcdef>
 846        <paramdef>int <parameter>offset</parameter></paramdef>
 847      </funcprototype>
 848    </funcsynopsis>
 849    <para>
 850      These methods remove a selection from the current collection.  The
 851      second version removes any selection that contains the position at
 852      <parameter>offset</parameter>, and has no effect if no such
 853      selection exists.
 854    </para>
 855  </listitem>
 856</itemizedlist>
 857</sect3>
 858
 859<sect3 id="class-jedittextarea-selection-text">
 860<title>Getting and setting selected text</title>
 861<itemizedlist>
 862
 863  <listitem>
 864    <funcsynopsis>
 865      <funcprototype>
 866        <funcdef>public String <function>getSelectedText</function></funcdef>
 867        <paramdef>Selection  <parameter>s</parameter></paramdef>
 868      </funcprototype>
 869    </funcsynopsis>
 870  </listitem>
 871
 872  <listitem>
 873    <funcsynopsis>
 874      <funcprototype>
 875        <funcdef>public String <function>getSelectedText</function></funcdef>
 876        <paramdef>String <parameter>separator</parameter></paramdef>
 877      </funcprototype>
 878    </funcsynopsis>
 879  </listitem>
 880
 881  <listitem>
 882    <funcsynopsis>
 883      <funcprototype>
 884        <funcdef>public String <function>getSelectedText</function></funcdef>
 885        <void/>
 886      </funcprototype>
 887    </funcsynopsis>
 888    <para>
 889      These three methods return a <classname>String</classname> containing
 890      text corresponding to the current selections. The first version returns
 891      the text corresponding to a particular selection named as the parameter,
 892      allowing for iteration through the collection or focus on a specific
 893      selection (such as a selection containing the current caret position).
 894      The second version combines all selection text in a single
 895      <classname>String</classname>, separated by the
 896      <classname>String</classname> given as the
 897      <parameter>separator</parameter>. The final version operates like the
 898      second version, separating individual selections with newline characters.
 899    </para>
 900  </listitem>
 901
 902  <listitem>
 903    <funcsynopsis>
 904      <funcprototype>
 905        <funcdef>public void <function>setSelectedText</function></funcdef>
 906        <paramdef>Selection <parameter>s</parameter></paramdef>
 907        <paramdef>String <parameter>selectedText</parameter></paramdef>
 908      </funcprototype>
 909    </funcsynopsis>
 910  </listitem>
 911
 912  <listitem>
 913    <funcsynopsis>
 914      <funcprototype>
 915        <funcdef>public void <function>setSelectedText</function></funcdef>
 916        <paramdef>String <parameter>selectedText</parameter></paramdef>
 917      </funcprototype>
 918    </funcsynopsis>
 919    <para>
 920      The first version changes the text of the selection represented
 921      by <parameter>s</parameter> to
 922      <parameter>selectedText</parameter>. The second version sets the
 923      text of all active selections; if there are no selections, the
 924      text will be inserted at the current caret position.
 925    </para>
 926    <para>
 927      The second version of <function>setSelectedText()</function> is
 928      the method that will typically be used in macro scripts to insert
 929      text.
 930    </para>
 931  </listitem>
 932  <listitem>
 933    <funcsynopsis>
 934      <funcprototype>
 935        <funcdef>public int[] <function>getSelectedLines</function></funcdef>
 936        <void/>
 937      </funcprototype>
 938    </funcsynopsis>
 939    <para>
 940      Returns a sorted array of line numbers on which a selection or selections
 941      are present.
 942    </para>
 943    <para>
 944      This method is the most convenient way to iterate through selected lines
 945      in a buffer. The line numbers in the array returned by this method can
 946      be passed as a parameter to such methods as
 947      <function>Buffer.getLineText()</function> (see
 948      <xref linkend="class-buffer-editing"/>).
 949    </para>
 950  </listitem>
 951
 952</itemizedlist>
 953</sect3>
 954
 955<sect3 id="class-jedittextarea-selection-other">
 956<title>Other selection methods</title>
 957
 958<para>
 959  The following methods perform selection operations without using
 960  <classname>Selection</classname> objects as parameters or return
 961  values. These methods should only be used in macros.
 962</para>
 963
 964
 965<itemizedlist>
 966<listitem>
 967<funcsynopsis>
 968 <funcprototype>
 969  <funcdef>public void <function>selectBlock</function></funcdef>
 970  <void/>
 971 </funcprototype>
 972</funcsynopsis>
 973<para>
 974    Selects the code block surrounding the caret.
 975</para>
 976</listitem>
 977
 978<listitem>
 979<funcsynopsis>
 980 <funcprototype>
 981  <funcdef>public void <function>selectWord</function></funcdef>
 982  <void/>
 983 </funcprototype>
 984</funcsynopsis>
 985</listitem>
 986
 987<listitem>
 988<funcsynopsis>
 989 <funcprototype>
 990  <funcdef>public void <function>selectLine</function></funcdef>
 991  <void/>
 992 </funcprototype>
 993</funcsynopsis>
 994</listitem>
 995
 996<listitem>
 997<funcsynopsis>
 998 <funcprototype>
 999  <funcdef>public void <function>selectParagraph</function></funcdef>
1000  <void/>
1001 </funcprototype>
1002</funcsynopsis>
1003</listitem>
1004
1005<listitem>
1006<funcsynopsis>
1007 <funcprototype>
1008  <funcdef>public void <function>selectFold</function></funcdef>
1009  <void/>
1010 </funcprototype>
1011</funcsynopsis>
1012<para>
1013  Selects the <quote>fold</quote> (a portion of text sharing a given
1014  indentation level) that contains the line where the editing caret
1015  is positioned.
1016</para>
1017</listitem>
1018
1019<listitem>
1020<funcsynopsis>
1021 <funcprototype>
1022  <funcdef>public void <function>selectFoldAt</function></funcdef>
1023  <paramdef>int <parameter>line</parameter></paramdef>
1024 </funcprototype>
1025</funcsynopsis>
1026  <para>
1027    Selects the fold containing the line referenced by
1028    <parameter>line</parameter>.
1029  </para>
1030</listitem>
1031
1032<listitem>
1033<funcsynopsis>
1034 <funcprototype>
1035  <funcdef>public void <function>selectAll</function></funcdef>
1036  <void/>
1037 </funcprototype>
1038</funcsynopsis>
1039</listitem>
1040
1041<listitem>
1042<funcsynopsis>
1043 <funcprototype>
1044  <funcdef>public void <function>selectNone</function></funcdef>
1045  <void/>
1046 </funcprototype>
1047</funcsynopsis>
1048</listitem>
1049
1050<listitem>
1051<funcsynopsis>
1052 <funcprototype>
1053  <funcdef>public void <function>indentSelectedLines</function></funcdef>
1054  <void/>
1055 </funcprototype>
1056</funcsynopsis>
1057</listitem>
1058
1059</itemizedlist>
1060</sect3>
1061
1062
1063</sect2>
1064
1065<sect2 id="class-jedittextarea-caret">
1066<title>Editing caret methods</title>
1067<para>
1068    These methods are used to get, set and move the position of the
1069    editing caret:
1070</para>
1071
1072<itemizedlist>
1073<listitem>
1074<funcsynopsis>
1075 <funcprototype>
1076  <funcdef>public int <function>getCaretPosition</function></funcdef>
1077  <void/>
1078 </funcprototype>
1079</funcsynopsis>
1080<para>
1081    Returns a zero-based index of the caret position in the existing buffer.
1082</para>
1083</listitem>
1084
1085<listitem>
1086<funcsynopsis>
1087 <funcprototype>
1088  <funcdef>public void <function>setCaretPosition</function></funcdef>
1089  <paramdef>int <parameter>caret</parameter></paramdef>
1090 </funcprototype>
1091</funcsynopsis>
1092<para>
1093    Sets the caret position at <parameter>caret</parameter> and deactivates
1094    any selection of text.
1095</para>
1096</listitem>
1097
1098<listitem>
1099<funcsynopsis>
1100 <funcprototype>
1101  <funcdef>public void <function>moveCaretPosition</function></funcdef>
1102  <paramdef>int <parameter>caret</parameter></paramdef>
1103 </funcprototype>
1104</funcsynopsis>
1105<para>
1106    This moves the caret to the position represented by
1107    <parameter>caret</parameter> without affecting any selection of
1108    text.
1109</para>
1110</listitem>
1111
1112<listitem>
1113<funcsynopsis>
1114 <funcprototype>
1115  <funcdef>public int <function>getCaretLine</function></funcdef>
1116  <void/>
1117 </funcprototype>
1118</funcsynopsis>
1119<para>
1120    Returns the line on which the caret is positioned.
1121</para>
1122</listitem>
1123
1124
1125</itemizedlist>
1126
1127<para>
1128    Each of the following shortcut methods moves the caret.  If the
1129    <parameter>select</parameter> parameter is set to
1130    <constant>true</constant>, the intervening text will be selected
1131    as well.
1132</para>
1133
1134<itemizedlist>
1135
1136<listitem>
1137<funcsynopsis>
1138 <funcprototype>
1139  <funcdef>public void <function>goToStartOfLine</function></funcdef>
1140  <paramdef>boolean <parameter>select</parameter></paramdef>
1141 </funcprototype>
1142</funcsynopsis>
1143</listitem>
1144
1145<listitem>
1146<funcsynopsis>
1147 <funcprototype>
1148  <funcdef>public void <function>goToEndOfLine</function></funcdef>
1149  <paramdef>boolean <parameter>select</parameter></paramdef>
1150 </funcprototype>
1151</funcsynopsis>
1152</listitem>
1153
1154<listitem>
1155<funcsynopsis>
1156 <funcprototype>
1157  <funcdef>public void <function>goToStartOfWhiteSpace</function></funcdef>
1158  <paramdef>boolean <parameter>select</parameter></paramdef>
1159 </funcprototype>
1160</funcsynopsis>
1161</listitem>
1162
1163<listitem>
1164<funcsynopsis>
1165 <funcprototype>
1166  <funcdef>public void <function>goToEndOfWhiteSpace</function></funcdef>
1167  <paramdef>boolean <parameter>select</parameter></paramdef>
1168 </funcprototype>
1169</funcsynopsis>
1170</listitem>
1171
1172<listitem>
1173<funcsynopsis>
1174 <funcprototype>
1175  <funcdef>public void <function>goToFirstVisibleLine</function></funcdef>
1176  <paramdef>boolean <parameter>select</parameter></paramdef>
1177 </funcprototype>
1178</funcsynopsis>
1179</listitem>
1180
1181<listitem>
1182<funcsynopsis>
1183 <funcprototype>
1184  <funcdef>public void <function>goToLastVisibleLine</function></funcdef>
1185  <paramdef>boolean <parameter>select</parameter></paramdef>
1186 </funcprototype>
1187</funcsynopsis>
1188</listitem>
1189
1190<listitem>
1191<funcsynopsis>
1192 <funcprototype>
1193  <funcdef>public void <function>goToNextCharacter</function></funcdef>
1194  <paramdef>boolean <parameter>select</parameter></paramdef>
1195 </funcprototype>
1196</funcsynopsis>
1197</listitem>
1198
1199<listitem>
1200<funcsynopsis>
1201 <funcprototype>
1202  <funcdef>public void <function>goToPrevCharacter</function></funcdef>
1203  <paramdef>boolean <parameter>select</parameter></paramdef>
1204 </funcprototype>
1205</funcsynopsis>
1206</listitem>
1207
1208<listitem>
1209<funcsynopsis>
1210 <funcprototype>
1211  <funcdef>public void <function>goToNextWord</function></funcdef>
1212  <paramdef>boolean <parameter>select</parameter></paramdef>
1213 </funcprototype>
1214</funcsynopsis>
1215</listitem>
1216
1217<listitem>
1218<funcsynopsis>
1219 <funcprototype>
1220  <funcdef>public void <function>goToPrevWord</function></funcdef>
1221  <paramdef>boolean <parameter>select</parameter></paramdef>
1222 </funcprototype>
1223</funcsynopsis>
1224</listitem>
1225
1226<listitem>
1227<funcsynopsis>
1228 <funcprototype>
1229  <funcdef>public void <function>goToNextLine</function></funcdef>
1230  <paramdef>boolean <parameter>select</parameter></paramdef>
1231 </funcprototype>
1232</funcsynopsis>
1233</listitem>
1234
1235<listitem>
1236<funcsynopsis>
1237 <funcprototype>
1238  <funcdef>public void <function>goToPrevLine</function></funcdef>
1239  <paramdef>boolean <parameter>select</parameter></paramdef>
1240 </funcprototype>
1241</funcsynopsis>
1242</listitem>
1243
1244<listitem>
1245<funcsynopsis>
1246 <funcprototype>
1247  <funcdef>public void <function>goToNextParagraph</function></funcdef>
1248  <paramdef>boolean <parameter>select</parameter></paramdef>
1249 </funcprototype>
1250</funcsynopsis>
1251</listitem>
1252
1253<listitem>
1254<funcsynopsis>
1255 <funcprototype>
1256  <funcdef>public void <function>goToPrevParagraph</function></funcdef>
1257  <paramdef>boolean <parameter>select</parameter></paramdef>
1258 </funcprototype>
1259</funcsynopsis>
1260</listitem>
1261
1262<listitem>
1263<funcsynopsis>
1264 <funcprototype>
1265  <funcdef>public void <function>goToNextBracket</function></funcdef>
1266  <paramdef>boolean <parameter>select</parameter></paramdef>
1267 </funcprototype>
1268</funcsynopsis>
1269</listitem>
1270
1271<listitem>
1272<funcsynopsis>
1273 <funcprototype>
1274  <funcdef>public void <function>goToPrevBracket</function></funcdef>
1275  <paramdef>boolean <parameter>select</parameter></paramdef>
1276 </funcprototype>
1277</funcsynopsis>
1278</listitem>
1279
1280</itemizedlist>
1281
1282
1283</sect2>
1284
1285<!-- open sect3 -->
1286<sect2 id="class-jedittextarea-scrolling">
1287<title>Methods for scrolling the text area</title>
1288
1289<itemizedlist>
1290
1291<listitem>
1292  <funcsynopsis>
1293    <funcprototype>
1294      <funcdef>public void <function>scrollUpLine</function></funcdef>
1295      <void/>
1296    </funcprototype>
1297  </funcsynopsis>
1298</listitem>
1299
1300<listitem>
1301  <funcsynopsis>
1302    <funcprototype>
1303      <funcdef>public void <function>scrollUpPage</function></funcdef>
1304      <void/>
1305    </funcprototype>
1306  </funcsynopsis>
1307</listitem>
1308
1309<listitem>
1310  <funcsynopsis>
1311    <funcprototype>
1312      <funcdef>public void <function>scrollDownLine</function></funcdef>
1313      <void/>
1314    </funcprototype>
1315  </funcsynopsis>
1316</listitem>
1317
1318<listitem>
1319  <funcsynopsis>
1320    <funcprototype>
1321      <funcdef>public void <function>scrollUpPage</function></funcdef>
1322      <void/>
1323    </funcprototype>
1324  </funcsynopsis>
1325</listitem>
1326
1327<listitem>
1328<funcsynopsis>
1329 <funcprototype>
1330  <funcdef>public void <function>scrollTo</function></funcdef>
1331  <paramdef>int <parameter>location</parameter></paramdef>
1332  <paramdef>boolean <parameter>doElectricScroll</parameter></paramdef>
1333 </funcprototype>
1334</funcsynopsis>
1335</listitem>
1336
1337<listitem>
1338<funcsynopsis>
1339 <funcprototype>
1340  <funcdef>public void <function>scrollToCaret</function></funcdef>
1341  <paramdef>boolean <parameter>doElectricScroll</parameter></paramdef>
1342 </funcprototype>
1343</funcsynopsis>
1344<para>
1345    The first version scrolls the text area to ensure that the caret is
1346    visible; the second scrolls to ensure that an arbitrary offset
1347    (from the start of the buffer) is visible. The
1348    <parameter>doElectricScroll</parameter> parameter determines whether
1349    <quote>electric scrolling</quote> will occur. This leaves a minimum
1350    number of lines between the target line and the top and bottom of the
1351    editing pane.
1352</para>
1353</listitem>
1354
1355<listitem>
1356  <funcsynopsis>
1357    <funcprototype>
1358      <funcdef>public void <function>centerCaret</function></funcdef>
1359      <void/>
1360    </funcprototype>
1361  </funcsynopsis>
1362  <para>
1363    Scrolls the text area so that the line containing the edit caret is
1364    vertically centered.
1365  </para>
1366</listitem>
1367
1368<listitem>
1369 <funcsynopsis>
1370  <funcprototype>
1371    <funcdef>public void <function>setFirstLine</function></funcdef>
1372     <paramdef>int <parameter>firstLine</parameter></paramdef>
1373   </funcprototype>
1374 </funcsynopsis>
1375</listitem>
1376
1377<listitem>
1378  <funcsynopsis>
1379    <funcprototype>
1380      <funcdef>public int <function>getFirstLine</function></funcdef>
1381      <void/>
1382    </funcprototype>
1383  </funcsynopsis>
1384  <para>
1385    This pair of methods deals with the line number of the first line
1386    displayed at the top of the text area. Lines that are hidden by folds or
1387    narrowing are ignored when making this <quote>virtual</quote> line
1388    count, so the line number will not necessarily conform to the line
1389    numbers displayed in the text area's gutter. In addition, the virtual
1390    line index is zero-based, so <function>getFirstLine()</function> will
1391    always return zero for the first line of text.
1392  </para>
1393  <para>
1394    To convert a virtual line count to a physical count or vice versa,
1395    see <xref linkend="class-jedittextarea-virtual-lines" />.
1396  </para>
1397</listitem>
1398
1399</itemizedlist>
1400
1401</sect2>
1402
1403<sect2 id="class-jedittextarea-delete">
1404<title>Methods for deleting text</title>
1405
1406<itemizedlist>
1407
1408<listitem>
1409<funcsynopsis>
1410 <funcprototype>
1411  <funcdef>public void <function>backspace</function></funcdef>
1412  <void/>
1413 </funcprototype>
1414</funcsynopsis>
1415</listitem>
1416
1417<listitem>
1418<funcsynopsis>
1419 <funcprototype>
1420  <funcdef>public void <function>backspaceWord</function></funcdef>
1421  <void/>
1422 </funcprototype>
1423</funcsynopsis>
1424</listitem>
1425
1426<listitem>
1427<funcsynopsis>
1428 <funcprototype>
1429  <funcdef>public void <function>delete</function></funcdef>
1430  <void/>
1431 </funcprototype>
1432</funcsynopsis>
1433</listitem>
1434
1435<listitem>
1436<funcsynopsis>
1437 <funcprototype>
1438  <funcdef>public void <function>deleteWord</function></funcdef>
1439  <void/>
1440 </funcprototype>
1441</funcsynopsis>
1442</listitem>
1443
1444<listitem>
1445<funcsynopsis>
1446 <funcprototype>
1447  <funcdef>public void <function>deleteLine</function></funcdef>
1448  <void/>
1449 </funcprototype>
1450</funcsynopsis>
1451</listitem>
1452
1453<listitem>
1454<funcsynopsis>
1455 <funcprototype>
1456  <funcdef>public void <function>deleteParagraph</function></funcdef>
1457  <void/>
1458 </funcprototype>
1459</funcsynopsis>
1460</listitem>
1461
1462<listitem>
1463<funcsynopsis>
1464 <funcprototype>
1465  <funcdef>public void <function>deleteToStartOfLine</function></funcdef>
1466  <void/>
1467 </funcprototype>
1468</funcsynopsis>
1469</listitem>
1470
1471<listitem>
1472<funcsynopsis>
1473 <funcprototype>
1474  <funcdef>public void <function>deleteToEndOfLine</function></funcdef>
1475  <void/>
1476 </funcprototype>
1477</funcsynopsis>
1478</listitem>
1479
1480</itemizedlist>
1481</sect2>
1482
1483<sect2 id="class-jedittextarea-modify">
1484<title>Methods for modifying text</title>
1485
1486<itemizedlist>
1487
1488<listitem>
1489  <funcsynopsis>
1490    <funcprototype>
1491      <funcdef>public void <function>toLowerCase</function></funcdef>
1492      <void/>
1493    </funcprototype>
1494  </funcsynopsis>
1495</listitem>
1496
1497<listitem>
1498  <funcsynopsis>
1499    <funcprototype>
1500      <funcdef>public void <function>toUpperCase</function></funcdef>
1501      <void/>
1502    </funcprototype>
1503  </funcsynopsis>
1504  <para>
1505    These two methods operate on all selected text, including multiple
1506    selections.
1507  </para>
1508</listitem>
1509
1510<listitem>
1511  <funcsynopsis>
1512    <funcprototype>
1513      <funcdef>public void <function>joinLines</function></funcdef>
1514      <void/>
1515    </funcprototype>
1516  </funcsynopsis>
1517  <para>
1518    Joins the current line with the following line.
1519  </para>
1520</listitem>
1521
1522<listitem>
1523  <funcsynopsis>
1524    <funcprototype>
1525      <funcdef>public void <function>setOverwriteEnabled</function></funcdef>
1526      <paramdef>boolean <parameter>overwrite</parameter></paramdef>
1527    </funcprototype>
1528  </funcsynopsis>
1529</listitem>
1530
1531<listitem>
1532  <funcsynopsis>
1533    <funcprototype>
1534      <funcdef>public boolean <function>isOverwriteEnabled</function></funcdef>
1535      <void/>
1536    </funcprototype>
1537  </funcsynopsis>
1538  <para>
1539    Sets and gets whether added text will overwrite text at the editing
1540    caret or whether it will be inserted immediately to the right of the
1541    caret.
1542  </para>
1543</listitem>
1544
1545<listitem>
1546  <funcsynopsis>
1547    <funcprototype>
1548      <funcdef>public void <function>userInput</function></funcdef>
1549      <paramdef>char <parameter>ch</parameter></paramdef>
1550    </funcprototype>
1551  </funcsynopsis>
1552  <para>
1553     Inserts the character at the caret position as if it were typed at
1554     the keyboard (keyboard input is actually passed to this method).
1555     Unlike <function>setSelectedText()</function>, or
1556     <function>insert()</function> in the
1557     <classname>Buffer</classname> class, this method triggers
1558     any active text formatting features such as auto indent,
1559     abbreviation expansion and word wrap.
1560  </para>
1561</listitem>
1562
1563</itemizedlist>
1564
1565</sect2>
1566
1567<sect2 id="class-jedittextarea-commment">
1568<title>Methods for creating comments</title>
1569
1570<itemizedlist>
1571
1572<listitem>
1573<funcsynopsis>
1574 <funcprototype>
1575  <funcdef>public void <function>lineComment</function></funcdef>
1576  <void/>
1577 </funcprototype>
1578</funcsynopsis>
1579<para>
1580    This inserts the line comment string at the beginning of each selected line.
1581</para>
1582</listitem>
1583
1584<listitem>
1585<funcsynopsis>
1586 <funcprototype>
1587  <funcdef>public void <function>rangeComment</function></funcdef>
1588  <void/>
1589 </funcprototype>
1590</funcsynopsis>
1591<para>
1592    This surrounds each selected text chunk with
1593    the comment start and end strings.
1594</para>
1595</listitem>
1596
1597</itemizedlist>
1598</sect2>
1599
1600<sect2 id="class-jedittextarea-virtual-lines">
1601<title>Virtual and physical line indices</title>
1602
1603<para>
1604When jEdit's folding or narrowing features are used to hide
1605  portions of a buffer, the <quote>virtual</quote> line count visible
1606  in the text area is generally not equal to the <quote>physical</quote>
1607
1608line count of the buffer represented by the gutter's display.  The
1609  following pair of methods translate one enumeration to the other.
1610</para>
1611
1612
1613<itemizedlist>
1614
1615<listitem>
1616<funcsynopsis>
1617<funcprototype>
1618<funcdef>public int <function>virtualToPhysical</function></funcdef>
1619
1620<paramdef>int <parameter>lineNo</parameter></paramdef>
1621</funcprototype>
1622</funcsynopsis>
1623</listitem>
1624
1625<listitem>
1626<funcsynopsis>
1627<funcprototype>
1628
1629<funcdef>public int <function>physicalToVirtual</function></funcdef>
1630<paramdef>int <parameter>lineNo</parameter></paramdef>
1631</funcprototype>
1632</funcsynopsis>
1633</listitem>
1634
1635</itemizedlist>
1636
1637</sect2>
1638
1639</sect1>
1640
1641<sect1 id="class-buffer"><title>Class Buffer</title>
1642
1643<para>
1644    A <classname>Buffer</classname> represents the contents of an open text
1645    file as it is maintained in the computer's memory (as opposed to
1646    how it may be stored on a disk).
1647</para>
1648
1649<sect2 id="class-buffer-attrs"><title>File attribute methods</title>
1650
1651<itemizedlist>
1652
1653<listitem>
1654<funcsynopsis>
1655 <funcprototype>
1656  <funcdef>public String <function>getName</function></funcdef>
1657  <void/>
1658 </funcprototype>
1659</funcsynopsis>
1660</listitem>
1661
1662<listitem>
1663<funcsynopsis>
1664 <funcprototype>
1665  <funcdef>public String <function>getPath</function></funcdef>
1666  <void/>
1667 </funcprototype>
1668</funcsynopsis>
1669</listitem>
1670
1671<listitem>
1672<funcsynopsis>
1673 <funcprototype>
1674  <funcdef>public File <function>getFile</function></funcdef>
1675  <void/>
1676 </funcprototype>
1677</funcsynopsis>
1678<para>
1679 This method may return <constant>null</constant> if the file is stored on
1680 a remote file system (for example, if the <application>FTP</application>
1681 or <application>Archive</application> plugins are in use). This method
1682 should be avoided unless you really need to use the
1683 <classname>java.io.File</classname> APIs and you are sure the buffer in
1684 question is a local file.
1685</para>
1686</listitem>
1687
1688<listitem>
1689<funcsynopsis>
1690 <funcprototype>
1691  <funcdef>public boolean <function>isNewFile</function></funcdef>
1692  <void/>
1693 </funcprototype>
1694</funcsynopsis>
1695<para>
1696    Returns whether a buffer lacks a corresponding version on disk.
1697</para>
1698</listitem>
1699
1700<listitem>
1701<funcsynopsis>
1702 <funcprototype>
1703  <funcdef>public boolean <function>isDirty</function></funcdef>
1704  <void/>
1705 </funcprototype>
1706</funcsynopsis>
1707<para>
1708    Returns whether there have been unsaved changes to the buffer.
1709</para>
1710</listitem>
1711
1712<listitem>
1713<funcsynopsis>
1714 <funcprototype>
1715  <funcdef>public boolean <function>isReadOnly</function></funcdef>
1716  <void/>
1717 </funcprototype>
1718</funcsynopsis>
1719</listitem>
1720
1721<listitem>
1722<funcsynopsis>
1723 <funcprototype>
1724  <funcdef>public boolean <function>isUntitled</function></funcdef>
1725  <void/>
1726 </funcprototype>
1727</funcsynopsis>
1728</listitem>
1729
1730</itemizedlist>
1731
1732</sect2>
1733
1734<sect2 id="class-buffer-attr"><title>Editing attribute methods</title>
1735
1736<itemizedlist>
1737
1738<listitem>
1739<funcsynopsis>
1740 <funcprototype>
1741  <funcdef>public Mode <function>getMode</function></funcdef>
1742  <void/>
1743 </funcprototype>
1744</funcsynopsis>
1745</listitem>
1746
1747<listitem>
1748<funcsynopsis>
1749 <funcprototype>
1750  <funcdef>public void <function>setMode</function></funcdef>
1751  <paramdef>Mode <parameter>mode</parameter></paramdef>
1752 </funcprototype>
1753</funcsynopsis>
1754<para>
1755    Gets and sets the editing mode for the buffer.
1756</para>
1757</listitem>
1758
1759  <listitem>
1760    <funcsynopsis>
1761      <funcprototype>
1762        <funcdef>public int <function>getIndentSize</function></funcdef>
1763        <void/>
1764      </funcprototype>
1765    </funcsynopsis>
1766  </listitem>
1767
1768  <listitem>
1769    <funcsynopsis>
1770      <funcprototype>
1771        <funcdef>public int <function>getTabSize</function></funcdef>
1772        <void/>
1773      </funcprototype>
1774    </funcsynopsis>
1775    <para>
1776      These methods return the size of an initial indentation at the beginning
1777      of a line and the distance between tab stops, each measured in
1778      character columns. If these properties are not individually set for
1779      a specific buffer, they are inherited from the properties of the buffer's
1780      associated editing mode.
1781    </para>
1782  </listitem>
1783</itemizedlist>
1784
1785<para>
1786  The <classname>Buffer</classname> object maintains a table of
1787  properties that describe a broad range of attributes. The value of each
1788  property is stored using a
1789  <classname>String</classname> that names the particular property.
1790  Most of these properties are documented in <xref
1791  linkend="buffer-local" />.
1792</para>
1793
1794<itemizedlist>
1795
1796  <listitem>
1797    <funcsynopsis>
1798      <funcprototype>
1799        <funcdef>public Object <function>getProperty</function></funcdef>
1800        <paramdef>String <parameter>name</parameter></paramdef>
1801      </funcprototype>
1802    </funcsynopsis>
1803    <para>
1804      Using this method is generally discouraged, because it returns an
1805      <classname>Object</classname> which must be cast to another type
1806      in order to be useful, and this can cause problems if the object
1807      is of a different type than what your plugin or macro expects.
1808    </para>
1809    <para>
1810      jEdit 4.0 added a number of <quote>wrapper</quote> methods,
1811      documented below; you are strongly encouraged to use them
1812      instead.
1813    </para>
1814  </listitem>
1815
1816  <listitem>
1817    <funcsynopsis>
1818      <funcprototype>
1819        <funcdef>public void <function>setProperty</function></funcdef>
1820        <paramdef>String <parameter>name</parameter></paramdef>
1821        <paramdef>Object <parameter>value<

Large files files are truncated, but you can click here to view the full file