<!-- jEdit buffer-local properties: -->
<!-- :indentSize=1:noTabs=true: -->
<!-- :xml.root=users-guide.xml: -->

<chapter id="basics"><title>jEdit Basics</title>
 <sect1 id="overview"><title>Interface Overview</title>
  <para>
   A <firstterm>view</firstterm> is the jEdit term for an editor window.
   It is possible to have multiple views open at once, and each view can
   be split into multiple panes. jEdit remembers the state of open views between editing sessions.
  </para>
  <para>
   An open file is referred to as a <firstterm>buffer</firstterm>.
   Unlike some editors where each buffer gets its own view, jEdit completely separates the two concepts. A buffer might be visible in several views, or none at all.
  </para>
  <para>
   The drop-down list at the top of the view shows all open buffers; selecting one will make it visible in the view's text area. Different emblems are displayed next to buffer names in the list,
   depending the buffer's state;
   a red disk is shown for buffers with unsaved changes,
   a lock is shown for read-only buffers,
   and a spark is shown for new buffers which don't yet exist on disk.
  </para>
  <para>
   As with most other graphical applications, there is a tool bar at the top of the view which provides quick access to frequently-used commands. Also, clicking the text area with the right mouse button displays a popup menu which also facilitates quick access to various commands.
   Both the tool bar and the right-click menu can be completely customized to suit your tastes in the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box; see <xref linkend="context-pane" />
   and <xref linkend="toolbar-pane"/>.
  </para>
  <para>
   Most of the view is taken up by the text area. If you've ever used a graphical user interface before, the text area will be instantly familiar. Text can be inserted simply by typing. More details on text insertion and deletion can be found in <xref linkend="entering-text"/>.
  </para>
  <para>
   The strip on the left of the text area is called a <firstterm>gutter</firstterm>.
   The gutter displays marker and register locations, as well as folding arrows; it will also display
   line numbers if the 
   <guimenu>View</guimenu>&gt;<guimenuitem>Line Numbers</guimenuitem> (shortcut: <keycap>C+e C+t</keycap>) command is invoked. Note this command only takes effect until the view is closed. To have line numbers visible all the time, enable the appropriate setting in the <guilabel>Gutter</guilabel> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box.
  </para>
 </sect1>

 <sect1 id="buffers"><title>Switching Buffers</title>
  <para>
   In addition to using the drop-down list at the top of the view, as documented in the previous section, the current buffer can also be switched using menu item commands and their keyboard shortcuts.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Go to Previous Buffer</guimenuitem>
   (keyboard shortcut: <keycap>C+PAGE_UP</keycap>) switches to the previous buffer in the list.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Go to Next Buffer</guimenuitem>
   (keyboard shortcut: <keycap>C+PAGE_DOWN</keycap>) switches to the next buffer in the list.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Go to Recent Buffer</guimenuitem>
   (keyboard shortcut: <keycap>C+BACK_QUOTE</keycap>)
   flips between the two most recently edited buffers.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Show Buffer Switcher</guimenuitem>
   (keyboard shortcut: <keycap>A+BACK_QUOTE</keycap>)
   has the same effect as clicking on the buffer switcher combo box.
  </para>
  <para>
   If you prefer an alternative graphical paradigm for switching buffers, take a look at one of these plugins:
  </para>
  <itemizedlist>
   <listitem><para><application>BufferList</application></para></listitem>
   <listitem><para><application>BufferSelector</application></para></listitem>
   <listitem><para><application>BufferTabs</application></para></listitem>
  </itemizedlist>
  <para>
   If you decide to use one of these plugins, you can hide the popup menu buffer switcher in the <guilabel>View</guilabel> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box.
  </para>
  <para>
   A number of plugins that implement fast keyboard-based buffer switching are available as well:
  </para>
  <itemizedlist>
   <listitem><para><application>FastOpen</application></para></listitem>
   <listitem><para><application>OpenIt</application></para></listitem>
   <listitem><para><application>SwitchBuffer</application></para></listitem>
  </itemizedlist>
 </sect1>
 <sect1 id="views"><title>Multiple Views</title>
  <para>
   As documented at the beginning of this chapter, multiple views can be opened at once, and views can be split into multiple panes.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>New View</guimenuitem> creates a new view.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>New Plain View</guimenuitem> creates
   a new view but without any tool bars or docked windows. This can be used to
   open a small window for taking notes and so on.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Close View</guimenuitem> closes the
   current view. If only one view is open, closing it will exit jEdit,
   unless background mode is on; see <xref linkend="starting" /> for information
   about starting jEdit in background mode.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Split
   Horizontally</guimenuitem>
   (shortcut: <keycap>C+2</keycap>)
   splits the view into two text areas, placed above each other.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Split
   Vertically</guimenuitem>
   (shortcut: <keycap>C+3</keycap>)
   splits the view into two text areas, placed next to each other.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Unsplit Current</guimenuitem>
   (shortcut: <keycap>C+0</keycap>)
   removes the split containing the current text area only.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Unsplit All</guimenuitem>
   (shortcut: <keycap>C+1</keycap>)
   removes all splits from the view.
  </para>
  <para>
   When a view is split, editing commands operate on the text area that
   has keyboard focus. To give a text area keyboard focus, click in it
   with the mouse, or use the following commands.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Go to
   Previous Text Area</guimenuitem>
   (shortcut: <keycap>A+PAGE_UP</keycap>)
   shifts keyboard focus to the previous text area.
  </para>
  <para>
   <guimenu>View</guimenu>&gt;<guimenuitem>Go to
   Next Text Area</guimenuitem>
   (shortcut: <keycap>A+PAGE_DOWN</keycap>)
   shifts keyboard focus to the next text area.
  </para>
 </sect1>
  <sect1 id="docking"><title>Window Docking</title>
   <para>
    Various jEdit and plugin
    windows can be docked into the view for convenience. Dockable windows
    have a popup button in their top-left corner. Clicking this button displays a menu with commands for docking the window in one of four sides of the view.
   </para>
   <para>
    On each side of the text area where there are docked windows, a strip of buttons is shown. There is a button for activating each docked window, as well as a close box and a popup menu button, which when clicked shows a menu for moving or undocking the currently selected window. The popup menu also contains a command for opening a new floating instance of the current window.
   </para>
   <para>
    The commands in the <guimenu>View</guimenu>&gt;<guisubmenu>Docking</guisubmenu>
    menu move keyboard focus between docking areas.
   </para>
   <para>
    Dockable windows can also be configured in the <guilabel>Docking</guilabel> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box.
   </para>
   <sidebar><title>For power users</title>
    <para>
     Each dockable has three commands associated with it; one is part of the
     menu bar and opens the dockable. The other two commands are:
    </para>
    <itemizedlist>
     <listitem><para><guimenuitem>Window Name
     (Toggle)</guimenuitem> - opens the dockable window if it is hidden, and
     hide it if its already open.</para></listitem>
     <listitem><para><guimenuitem>Window Name
     (New Floating Instance)</guimenuitem> - opens a new instance of the
     dockable in a floating window, regardless of the docking
     configuration. For example, this can be used to view two
     different directories side-by-side in two file system browser windows.</para>
     <para>
     A new floating instance can also be opened from the dockable window's popup menu.
     </para>
    </listitem>
    </itemizedlist>
    <para>
     These commands cannot be invoked from the menu bar. However, they can be
     added to the tool bar or context menu, and given keyboard shortcuts;
     see <xref linkend="global-opts" />.
    </para>
   </sidebar>
  </sect1>
  <sect1 id="status-bar"><title>The Status Bar</title>
   <para>
    The <firstterm>status bar</firstterm> at the bottom of the view consists
    of the following components, from left to right:
   </para>
   <itemizedlist>
    <listitem><para>The line number containing the caret</para></listitem>
    <listitem><para>The column position of the caret, with the leftmost column
    being 1.</para>
    <para>
     If the line contains tabs, the <firstterm>file</firstterm> position (where a hard
     tab is counted as one column) is shown first, followed by the
     <firstterm>screen</firstterm> position (where each tab counts for the number of
     columns until the next tab stop).
    </para>
    <para>
     Double-clicking on the caret location indicator displays the
     <guimenu>Edit</guimenu>&gt;<guimenuitem>Go to Line</guimenuitem> dialog
     box; see <xref linkend="lines" />.
    </para></listitem>
    <listitem><para>A message area where various prompts and status messages
    are shown.</para></listitem>
    <listitem><para>The current buffer's edit mode, fold mode,
    and character encoding. Double-clicking one of these
    displays the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
    Options</guimenuitem> dialog box. For more information about these settings,
    see:</para>
    <itemizedlist>
     <listitem><para><xref linkend="buffer-opts" /></para></listitem>
     <listitem><para><xref linkend="modes" /></para></listitem>
     <listitem><para><xref linkend="folding" /></para></listitem>
     <listitem><para><xref linkend="encodings" /></para></listitem>
    </itemizedlist>
    </listitem>
    <listitem><para>A set of
    flags which indicate various editor features and settings. Clicking each
    flag will toggle the feature in question; hovering the mouse over a flag
    will show a tool tip with an explanation:</para>
    <itemizedlist>
    <listitem><para>Word wrap - see <xref linkend="word-wrap" />.</para></listitem>
    <listitem><para>Multiple selection - see <xref linkend="multi-select" />.</para></listitem>
    <listitem><para>Rectangular selection - see <xref linkend="rect-select" />.</para></listitem>
    <listitem><para>Overwrite mode - see <xref linkend="entering-text" />.</para></listitem>
    <listitem><para>Line separator - see <xref linkend="line-separators" />.</para></listitem>
    </itemizedlist>
    </listitem>
    <listitem><para>A Java heap memory usage indicator, that shows used and
    total heap memory, in megabytes. Double-clicking this indicator opens the
    <guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>Memory Status</guimenuitem>
    dialog box.</para></listitem>
   </itemizedlist>
   <para>
    The visibility of each of the above items can be controlled in the
    <guibutton>Status Bar</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box; see <xref linkend="status-bar-pane"/>.
   </para>
 </sect1>
 <sect1 id="action-bar"><title>The Action Bar</title>
  <para>
   The action bar allows almost any editor feature to be accessed from the keyboard.
  </para>
  <para>
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Action Bar</guimenuitem> (shortcut: <keycap>C+ENTER</keycap>) displays the action bar at the bottom of the view and gives it keyboard focus. The action bar remembers previously entered strings; see <xref linkend="history" /> for details.
  </para>
  <para>
   To use the action bar, input a command and press <keycap>Enter</keycap>.
   The following commands are supported:
  </para>
   <bridgehead renderas="sect3">Action invocations</bridgehead>
   <para>
    Each menu item and tool bar button is bound to an <firstterm>action</firstterm>. To find out the name of an action, invoke the menu item or click the tool bar button, and look in the action bar's history.
   </para>
   <para>
    If a substring or an action name is entered, pressing <keycap>Tab</keycap> shows a popup listing matching actions. An action can be selected using the
    <keycap>Up</keycap> and <keycap>Down</keycap> arrow keys, or by entering more characters of its name.
   </para>
   <para>
    Pressing <keycap>Enter</keycap> with an incomplete substring invokes the action that would be first in the completion popup's list.
   </para>
   <para>
    For example, entering <userinput>l-o</userinput> will match <userinput>global-options</userinput>, which has the same effect as invoking <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>.
   </para>
   <bridgehead renderas="sect3">Buffer-local properties</bridgehead>
   <para>
    Entering <userinput>buffer.property=value</userinput> sets the value of the buffer-local property named <userinput>property</userinput> to <userinput>value</userinput>.
    Buffer-local properties are documented in <xref linkend="buffer-local"/>.
   </para>
   <para>
    For example, entering <userinput>buffer.tabSize=4</userinput> changes the current buffer's tab size to 4.
   </para>
   <para>
    See <xref linkend="buffer-local"/> for information about buffer-local properties.
   </para>
   <bridgehead renderas="sect3">Global properties</bridgehead>
   <para>
    Entering <userinput>property=value</userinput> sets the value of the global property named <userinput>property</userinput> to <userinput>value</userinput>.
    This feature is primarily intended to help plugin developers, since the properties jEdit uses to store its settings are not currently documented.
   </para>
   <bridgehead renderas="sect3">Command repetition</bridgehead>
   <para>
   To repeat a command multiple times, enter a number in the action bar, then invoke the command. For example,
   <quote><keycap>C+ENTER</keycap> <keycap>1</keycap> <keycap>4</keycap>
   <keycap>C+d</keycap></quote> will delete
   14 lines; <quote><keycap>C+ENTER</keycap> <keycap>9</keycap>
   <keycap>#</keycap></quote>
   will insert <quote>#########</quote> in the buffer.
  </para>
  <para>
   If you specify a repeat count greater than 20, a confirmation dialog box will
   be displayed, asking if you really want to perform the action. This prevents
   you from hanging jEdit by executing a command too many times.
  </para>
 </sect1>
</chapter>