<?xml version="1.0" encoding="UTF-8"?>
<chapter id="basics">
    <title>jEdit Basics</title>
    <!-- jEdit buffer-local properties: -->
    <!-- :indentSize=1:noTabs=true: -->
    <!-- :xml.root=users-guide.xml: -->

    <sect1 id="overview">
        <title>Interface Overview</title>

        <para>A <firstterm>View</firstterm> is the jEdit term for an editor main
        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>A <firstterm>TextArea</firstterm> is an editor for a buffer. 
        An <firstterm>EditPane</firstterm> contains a TextArea plus optional buffer switcher. 
        A View contains one EditPane by default, and additional panes are created whenever
        the View is split.  </para>
        
        <para>The drop-down buffer switcher list at the top of each EditPane shows
        a buffer set which by default includes all open buffers.
        Selecting a buffer on this list will make it visible in the TextArea. 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 TextArea 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 TextArea. If you've ever used
        a graphical user interface before, the TextArea 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 TextArea 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 menu toggle action has the side-effect of changing the
        persistent jEdit properties for the Gutter, which can also
        be set from the <guilabel>Gutter</guilabel> pane of the
        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
        Options</guimenuitem> dialog box.</para>
    </sect1>

        <sect1 id="views">
        <title>Multiple Views</title>

        <para>As documented at the beginning of this chapter, multiple Views
        (main windows) can be open at once.</para>

        <para><guimenu>View</guimenu>&gt;<guimenuitem>New View</guimenuitem>
        creates a new View, or main window.</para>

        <para><guimenu>View</guimenu>&gt;<guimenuitem>New Plain
        View</guimenuitem> creates a new View but without any tool bars or
        dockable 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 TextAreas, placed above each other.</para>

        <para><guimenu>View</guimenu>&gt;<guimenuitem>Split
        Vertically</guimenuitem> (shortcut: <keycap>C+3</keycap>) splits the
        View into two TextAreas, 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 TextArea 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 TextArea
        that has keyboard focus. To give a TextArea 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 TextArea.</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 TextArea.</para>
        
        <para><guimenu>Macros</guimenu>&gt;<guimenu>Interface</guimenu>&gt;
        <guimenu>Splitpane Grow</guimenu> grows the size of the currently focused
        TextArea. </para>
        
    </sect1>

    <sect1 id="buffers">
        <title>Switching Buffers</title>

        <para>Each EditPane has an optional drop-down BufferSwitcher at the top.
        The BufferSwitcher shows the current buffer and can also be used to 
        switch the current buffer, 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="buffersets">
        <title>Buffer Sets</title>

        <para> The buffer sets feature helps keep the buffer lists local and manageable when using
        jEdit in a multiple-View and multiple-EditPane environment. </para>
        
        <para> As mentioned in the previous section, each EditPane can show a Buffer Switcher, which
        displays the contents of a BufferSet. In jEdit 4.2, all EditPane buffer switchers
        showed the same BufferSet: a global list of all buffers that were opened from any EditPane in any View. 
        When using many Views and EditPanes, this resulted in large lists of buffers, and made
        the next/previous buffer actions useless with many views, EditPanes and buffers. 
        </para>
        
        <para> In jEdit 4.3, it is possible to have more narrow scopes for the BufferSets of an EditPane. This makes the 'next-buffer' and 'previous-buffer' actions switch between buffers that are local to the view or pane. </para>
        
        <para>
        The three BufferSet scopes are: </para>
        
        <orderedlist>
            <listitem><para> <emphasis role="bold">Global</emphasis>: Includes all buffers open from any EditPane. </para></listitem>
            <listitem><para> <emphasis role="bold">View</emphasis>: EditPanes in the same View share the same
            BufferSet. Opening a buffer in one View will not affect the non-global scope BufferSets in EditPanes of
            other Views. </para></listitem> 
            <listitem><para><emphasis role="bold">EditPane</emphasis>: Each EditPane can have its own independent
            BufferSet.
            </para></listitem>
        </orderedlist>
        
        <para> The default Buffer Set scope for newly created EditPanes is global by default, and can be
        changed from <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
        &gt; <guimenuitem>View</guimenuitem> &gt; <guilabel>BufferSet scope for new
        EditPanes</guilabel>. </para>

        <para> New BufferSets are initially empty, or populated with a copy of the 
        existing BufferSet. This behavior can be changed from 
        <guimenuitem>Global Options</guimenuitem> &gt; <guimenuitem>View</guimenuitem> &gt; 
        <guilabel>New BufferSets contain: copies of current BufferSet</guilabel>. </para>
        
        <para> <guimenu>File</guimenu> &gt; <guimenuitem>Close</guimenuitem> behavior has changed in 4.3pre15: now it will remove the current buffer from the EditPane's BufferSet only. If it
        was the last BufferSet to contain that buffer, the buffer is also closed. </para>
        <para> The <guimenu> File </guimenu> &gt; <guimenuitem>Close (global)</guimenuitem> action closes the buffer in all EditPanes, as the regular <guimenu> File </guimenu> &gt; <guimenuitem>Close</guimenuitem> action did before. </para>
        
        <para> <guimenuitem>Clear BufferSet except active</guimenuitem> will clear the BufferSet of the
        current EditPane by performing a <guimenuitem>Close</guimenuitem> on all items except those buffers which are displayed in another active EditPane. </para>       
        
        <bridgehead> Switching Bufferset Scopes at runtime (experimental) </bridgehead>
                
        <para> The statusbar shows you which BufferSet scope is active for the current EditPane 
        (look for the letter "G", "E" or "V"). Double-clicking on that
        will allow you to change the buffer set. Also, the scope for the current EditPane BufferSet can be changed from <guimenu>View</guimenu>&gt;<guimenu>Buffer Sets</guimenu> &gt;
        <guimenu>(Global|View|EditPane) Buffer Set</guimenu>. </para>

        <para> A new BufferSet can be created in a number of ways, such as when a new
        View is created (and the default BufferSet scope is not global) or when the
        View is split (and the default BufferSet scope is EditPane), or when the
        BufferSet scope is changed to EditPane via the statusbar or menu action. </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 TextArea 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>
                    
                    <listitem>
                        <para>Buffer Set Scope - see <xref
                        linkend="buffersets" />.</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 press the key-combination that invokes 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.
        Note: The space characters in these examples should not be typed;
        they are only here to visually separate the keys to be typed.</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>