PageRenderTime 66ms CodeModel.GetById 51ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-5-pre1/doc/users-guide/basics.xml

#
XML | 526 lines | 410 code | 113 blank | 3 comment | 0 complexity | 3adcc9fd302e6cf53b9ada19a8c4dfe4 MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<chapter id="basics">
  3    <title>jEdit Basics</title>
  4    <!-- jEdit buffer-local properties: -->
  5    <!-- :indentSize=1:noTabs=true: -->
  6    <!-- :xml.root=users-guide.xml: -->
  7
  8    <section id="overview">
  9        <title>Interface Overview</title>
 10        
 11        <para>A <firstterm>View</firstterm> is the jEdit term for an editor main
 12        window. It is possible to have multiple views open at once, and each
 13        View can be split into multiple panes. jEdit remembers the state of open
 14        views between editing sessions.</para>
 15
 16        <para>An open file is referred to as a <firstterm>Buffer</firstterm>.
 17        Unlike some editors where each buffer gets its own View, jEdit
 18        completely separates the two concepts. A buffer might be visible in
 19        several views, or none at all.</para>
 20
 21        <para>A <firstterm>TextArea</firstterm> is an editor for a buffer.
 22        An <firstterm>EditPane</firstterm> contains a TextArea plus optional buffer switcher.
 23        A View contains one EditPane by default, and additional panes are created whenever
 24        the View is split.  </para>
 25
 26        <para>The drop-down buffer switcher list at the top of each EditPane shows
 27        a BufferSet, or a set of open buffers (see <xref linkend="buffersets" />). 
 28        Selecting a buffer on this list will make it visible in the TextArea. Different
 29        emblems are displayed next to buffer names in the list, depending the
 30        buffer's state; a red disk is shown for buffers with unsaved changes, a
 31        lock is shown for read-only buffers, and a spark is shown for new
 32        buffers which don't yet exist on disk.</para>
 33
 34        <para>With the new Tango icon theme, these symbols are slightly different,
 35        a red square is shown for buffers with unsaved changes, a lock is shown for
 36        read-only buffers, and a yellow square is shown for new buffers which don't
 37        yet exist on disk.</para>
 38
 39        <para>As with most other graphical applications, there is a tool bar at
 40        the top of the View which provides quick access to frequently-used
 41        commands. Also, clicking the TextArea with the right mouse button
 42        displays a popup menu which also facilitates quick access to various
 43        commands. Both the tool bar and the right-click menu can be completely
 44        customized to suit your tastes in the
 45        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
 46        Options</guimenuitem> dialog box; see <xref linkend="context-pane" />
 47        and <xref linkend="toolbar-pane" />.</para>
 48
 49        <para>Most of the View is taken up by the TextArea. If you've ever used
 50        a graphical user interface before, the TextArea will be instantly
 51        familiar. Text can be inserted simply by typing. More details on text
 52        insertion and deletion can be found in <xref
 53        linkend="entering-text" />.</para>
 54
 55        <para>The strip on the left of the TextArea is called a
 56        <firstterm>gutter</firstterm>. The gutter displays marker and register
 57        locations, as well as folding arrows; it will also display line numbers
 58        if the <guimenu>View</guimenu>&gt;<guimenuitem>Line
 59        Numbers</guimenuitem> (shortcut: <keycap>C+e C+t</keycap>) command is
 60        invoked. Note this menu toggle action has the side-effect of changing the
 61        persistent jEdit properties for the Gutter, which can also
 62        be set from the <guilabel>Gutter</guilabel> pane of the
 63        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
 64        Options</guimenuitem> dialog box.</para>
 65
 66        <para> The gutter is divided into two sections. Right-clicking on the left side
 67        gives you a context menu, while right-clicking on the right side (where line numbers might be)
 68        toggles a marker at that position.
 69        Text can be selected by left-clicking and dragging on right side of the gutter,
 70        over the range of lines you wish to select.
 71        </para>
 72
 73    </section>
 74
 75        <section id="views">
 76        <title>Multiple Views</title>
 77
 78        <para>As documented at the beginning of this chapter, multiple Views
 79        (main windows) can be open at once.</para>
 80
 81        <para><guimenu>View</guimenu>&gt;<guimenuitem>New View</guimenuitem>
 82        creates a new View, or main window.</para>
 83
 84        <para><guimenu>View</guimenu>&gt;<guimenuitem>New Plain
 85        View</guimenuitem> creates a new View but without any tool bars or
 86        dockable windows. This can be used to open a small window for taking notes
 87        and so on.</para>
 88
 89        <para><guimenu>View</guimenu>&gt;<guimenuitem>Close View</guimenuitem>
 90        closes the current View. If only one View is open, closing it will exit
 91        jEdit, unless background mode is on; see <xref linkend="starting" /> for
 92        information about starting jEdit in background mode.</para>
 93
 94        <para><guimenu>View</guimenu>&gt;<guimenuitem>Split
 95        Horizontally</guimenuitem> (shortcut: <keycap>C+2</keycap>) splits the
 96        View into two TextAreas, placed above each other.</para>
 97
 98        <para><guimenu>View</guimenu>&gt;<guimenuitem>Split
 99        Vertically</guimenuitem> (shortcut: <keycap>C+3</keycap>) splits the
100        View into two TextAreas, placed next to each other.</para>
101
102        <para><guimenu>View</guimenu>&gt;<guimenuitem>Unsplit
103        Current</guimenuitem> (shortcut: <keycap>C+0</keycap>) removes the split
104        containing the current TextArea only.</para>
105
106        <para><guimenu>View</guimenu>&gt;<guimenuitem>Unsplit All</guimenuitem>
107        (shortcut: <keycap>C+1</keycap>) removes all splits from the View.</para>
108
109        <para>When a View is split, editing commands operate on the TextArea
110        that has keyboard focus. To give a TextArea keyboard focus, click in it
111        with the mouse, or use the following commands.</para>
112
113        <para><guimenu>View</guimenu>&gt;<guimenuitem>Go to Previous Text
114        Area</guimenuitem> (shortcut: <keycap>A+PAGE_UP</keycap>) shifts
115        keyboard focus to the previous TextArea.</para>
116
117        <para><guimenu>View</guimenu>&gt;<guimenuitem>Go to Next Text
118        Area</guimenuitem> (shortcut: <keycap>A+PAGE_DOWN</keycap>) shifts
119        keyboard focus to the next TextArea.</para>
120
121        <para><guimenu>Macros</guimenu>&gt;<guimenu>Interface</guimenu>&gt;
122        <guimenu>Splitpane Grow</guimenu> grows the size of the currently focused
123        TextArea. </para>
124
125    </section>
126
127    <section id="buffers">
128        <title>Switching Buffers</title>
129
130        <para>Each EditPane has an optional drop-down BufferSwitcher at the top.
131        The BufferSwitcher shows the current buffer and can also be used to
132        switch the current buffer, using menu item commands and their keyboard shortcuts.</para>
133
134        <para><guimenu>View</guimenu>&gt;<guimenuitem>Go to Previous
135        Buffer</guimenuitem> (keyboard shortcut: <keycap>C+PAGE_UP</keycap>)
136        switches to the previous buffer in the list.</para>
137
138        <para><guimenu>View</guimenu>&gt;<guimenuitem>Go to Next
139        Buffer</guimenuitem> (keyboard shortcut: <keycap>C+PAGE_DOWN</keycap>)
140        switches to the next buffer in the list.</para>
141
142        <para><guimenu>View</guimenu>&gt;<guimenuitem>Go to Recent
143        Buffer</guimenuitem> (keyboard shortcut: <keycap>C+BACK_QUOTE</keycap>)
144        flips between the two most recently edited buffers.</para>
145
146        <para><guimenu>View</guimenu>&gt;<guimenuitem>Show Buffer
147        Switcher</guimenuitem> (keyboard shortcut:
148        <keycap>A+BACK_QUOTE</keycap>) has the same effect as clicking on the
149        buffer switcher combo box.</para>
150
151        <para>If you prefer an alternative graphical paradigm for switching
152        buffers, take a look at one of these plugins:</para>
153
154        <itemizedlist>
155            <listitem>
156                <para><application>BufferList</application></para>
157            </listitem>
158
159            <listitem>
160                <para><application>BufferSelector</application></para>
161            </listitem>
162
163            <listitem>
164                <para><application>BufferTabs</application></para>
165            </listitem>
166        </itemizedlist>
167
168        <para>If you decide to use one of these plugins, you can hide the popup
169        menu buffer switcher in the <guilabel>View</guilabel> pane of the
170        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
171        Options</guimenuitem> dialog box.</para>
172
173        <para>A number of plugins that implement fast keyboard-based buffer
174        switching are available as well:</para>
175
176        <itemizedlist>
177            <listitem>
178                <para><application>FastOpen</application></para>
179            </listitem>
180
181            <listitem>
182                <para><application>OpenIt</application></para>
183            </listitem>
184
185            <listitem>
186                <para><application>SwitchBuffer</application></para>
187            </listitem>
188        </itemizedlist>
189    </section>
190
191    <section id="buffersets">
192        <title>Buffer Sets</title>
193
194        <para> The buffer sets feature helps keep the buffer lists local and manageable when using
195        jEdit in a multiple-View and multiple-EditPane environment. </para>
196
197        <para> As mentioned in the previous section, each EditPane can show a Buffer Switcher, which
198        displays the contents of a BufferSet. In jEdit 4.2, all EditPane buffer switchers
199        showed the same BufferSet: a global list of all buffers that were opened from any EditPane in any View.
200        When using many Views and EditPanes, this resulted in large lists of buffers, and made
201        the next/previous buffer actions useless with many Views, EditPanes and Buffers.
202        </para>
203
204        <para> In jEdit 4.3, it is possible to have more narrow scopes for the BufferSets
205        of an EditPane. This makes the 'next-buffer' and 'previous-buffer' actions switch
206        between buffers that are local to the view or pane. </para>
207
208        <para>
209        The three BufferSet scopes are: </para>
210
211        <orderedlist>
212            <listitem><para> <emphasis role="bold">Global</emphasis>: Includes all buffers open from any EditPane. </para></listitem>
213            <listitem><para> <emphasis role="bold">View</emphasis>: EditPanes in the same
214            View share the same BufferSet. Opening a buffer in one View will not affect the
215            other views. </para></listitem>
216            <listitem><para><emphasis role="bold">EditPane</emphasis>: Each EditPane can have its
217            own independent BufferSet.
218            </para></listitem>
219        </orderedlist>
220
221        <para> Bufferset scope can be set from <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> &gt; <guimenuitem>View</guimenuitem> &gt;
222        <guilabel>BufferSet scope:</guilabel>.
223        </para>
224
225        <para> <guimenu>File</guimenu> &gt; <guimenuitem>Close</guimenuitem> removes 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>
226
227        <para> The <guimenu> File </guimenu> &gt; <guimenuitem>Close (global)</guimenuitem> action closes the buffer in all EditPanes, as the jEdit 4.2 <guimenu> File </guimenu> &gt; <guimenuitem>Close</guimenuitem> action did before. </para>
228
229        <para> When <guimenuitem>Exclusive Buffersets</guimenuitem> are enabled, any time a buffer is opened from one EditPane, it should be automatically closed in other EditPanes which use a disjoint (non-intersecting) BufferSet. </para>
230
231        <para> <guimenuitem>Close Others</guimenuitem> will clear the BufferSet of the
232        current EditPane by performing a <guimenuitem>Close</guimenuitem> on all items except those buffers which are displayed in another active EditPane. </para>
233
234        <bridgehead> Switching Bufferset Scopes </bridgehead>
235
236        <para> The statusbar shows you which BufferSet scope is active
237        (look for the letter "G", "E" or "V"). Double-clicking on that
238        will allow you to change the scope without going into global options.
239
240        The BufferSet Scope can also be changed from
241        <guimenu>View</guimenu>&gt;<guimenu>Buffer Sets</guimenu>  &gt;
242        <guimenu>(Global|View|EditPane) Buffer Set</guimenu>.
243        Changes to the bufferset scope affects all editpanes immediately.
244        </para>
245
246    </section>
247
248    <section id="docking">
249        <title>Window Docking Layouts</title>
250
251        <para> A docking layout is similar to an Eclipse "Perspective" in that it describes a set of dockable windows that are visible to the user at any given time, hiding the rest. </para>
252
253        <para>Various jEdit and plugin windows can be docked into the View for
254        convenience. Dockable windows have a popup button in their top-left
255        corner. Clicking this button displays a menu with commands for docking
256        the window in one of four sides of the View.</para>
257
258        <para>On each side of the TextArea where there are docked windows, a
259        strip of buttons is shown. There is a button for activating each docked
260        window, as well as a close box and a popup menu button, which when
261        clicked shows a menu for moving or undocking the currently selected
262        window. The popup menu also contains a command for opening a new
263        floating instance of the current window.</para>
264
265        <para>The commands in the
266        <guimenu>View</guimenu>&gt;<guisubmenu>Docking</guisubmenu> menu move keyboard focus between docking areas.</para>
267
268
269        <para>
270        After you have customized the layout of your dockables and wish to save it for export/import, use the actions <guimenu>View</guimenu> - <guimenu>Docking</guimenu> - <guimenuitem>Save/Load Docking Layout</guimenuitem>. </para>
271        <para> It is possible to configure a Dockable layout for just one or a handful of edit modes. This makes it possible to save or load your dockable layout with the same keyboard shortcut (or automatically) based on the edit mode of your current buffer.
272        </para>
273
274        <para>
275        It is also possible to save/load a layout for a particular edit mode. The loading and saving can be done automatically, as configured in the global options docking pane when the mode of the buffer changes, or manually in response to invoking <guimenu>View</guimenu> - <guimenu>Docking</guimenu> - <guimenuitem>Save/Load Docking Layout for current mode.</guimenuitem>
276        </para>
277
278        <para>Dockable windows can be further configured in the
279        <guilabel>Docking</guilabel> pane of the
280        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
281        Options</guimenuitem> dialog box. See <xref linkend="docking-pane"/> for details.
282        </para>
283
284
285        <sidebar>
286            <title>For keyboard/power users</title>
287
288            <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>
289
290            <itemizedlist>
291                <listitem>
292                    <para><guimenuitem>Window Name (Toggle)</guimenuitem> -
293                    opens the dockable window if it is hidden, and hide it if
294                    its already open.</para>
295                </listitem>
296
297                <listitem>
298                    <para><guimenuitem>Window Name (New Floating
299                    Instance)</guimenuitem> - opens a new instance of the
300                    dockable in a floating window, regardless of the docking
301                    configuration. For example, this can be used to view two
302                    different directories side-by-side in two file system
303                    browser windows.</para>
304
305                    <para>A new floating instance can also be opened from the
306                    dockable window's popup menu.</para>
307                </listitem>
308            </itemizedlist>
309
310            <para>These commands cannot be invoked from the menu bar. However,
311            they can be added to the tool bar or context menu, and given
312            keyboard shortcuts; see <xref linkend="global-opts" />.</para>
313        </sidebar>
314    </section>
315
316    <section id="status-bar">
317        <title>The Status Bar</title>
318
319        <para>The <firstterm>status bar</firstterm> at the bottom of the View
320        consists of the following components, from left to right:</para>
321
322        <itemizedlist>
323            <listitem>
324                <para>Caret position information:</para>
325                <itemizedlist>
326                    <listitem>
327                      <para>The offset of the caret from the beginning of the file</para>
328                    </listitem>
329
330                    <listitem>
331                      <para>The line number containing the caret</para>
332                    </listitem>
333
334                    <listitem>
335                        <para>The column position of the caret, with the leftmost column
336                        being 1.</para>
337
338                        <para>If the line contains tabs, the <firstterm>file</firstterm>
339                        position (where a hard tab is counted as one column) is shown
340                        first, followed by the <firstterm>screen</firstterm> position
341                        (where each tab counts for the number of columns until the next
342                        tab stop).</para>
343                    </listitem>
344
345                    <listitem>
346                        <para>The percent offset of the caret from the start of the file.
347                        This is based on the line number of the caret and the total number
348                        of lines in the file, so this is the same as the relative position
349                        of the right scroll bar in the main text area.</para>
350                    </listitem>
351
352                </itemizedlist>
353                <para>
354                    All of the above information is configurable in the Global Options
355                    for the status bar.
356                </para>
357                <para>Double-clicking on the caret location indicator displays
358                the <guimenu>Edit</guimenu>&gt;<guimenuitem>Go to
359                Line</guimenuitem> dialog box; see <xref
360                linkend="lines" />.
361                </para>
362            </listitem>
363
364            <listitem>
365                <para>A message area where various prompts and status messages
366                are shown.</para>
367            </listitem>
368
369            <listitem>
370                <para>The current buffer's edit mode, fold mode, and character
371                encoding. Double-clicking one of these displays the
372                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
373                Options</guimenuitem> dialog box. For more information about
374                these settings, see:</para>
375
376                <itemizedlist>
377                    <listitem>
378                        <para><xref linkend="buffer-opts" /></para>
379                    </listitem>
380
381                    <listitem>
382                        <para><xref linkend="modes" /></para>
383                    </listitem>
384
385                    <listitem>
386                        <para><xref linkend="folding" /></para>
387                    </listitem>
388
389                    <listitem>
390                        <para><xref linkend="encodings" /></para>
391                    </listitem>
392                </itemizedlist>
393            </listitem>
394
395            <listitem>
396                <para>A set of flags which indicate various editor features and
397                settings. Clicking each flag will toggle the feature in
398                question; hovering the mouse over a flag will show a tool tip
399                with an explanation:</para>
400
401                <itemizedlist>
402                    <listitem>
403                        <para>Word wrap - see <xref
404                        linkend="word-wrap" />.</para>
405                    </listitem>
406
407                    <listitem>
408                        <para>Multiple selection - see <xref
409                        linkend="multi-select" />.</para>
410                    </listitem>
411
412                    <listitem>
413                        <para>Rectangular selection - see <xref
414                        linkend="rect-select" />.</para>
415                    </listitem>
416
417                    <listitem>
418                        <para>Overwrite mode - see <xref
419                        linkend="entering-text" />.</para>
420                    </listitem>
421
422                    <listitem>
423                        <para>Line separator - see <xref
424                        linkend="line-separators" />.</para>
425                    </listitem>
426
427                    <listitem>
428                        <para>Buffer Set Scope - see <xref
429                        linkend="buffersets" />.</para>
430                    </listitem>
431
432                </itemizedlist>
433            </listitem>
434
435            <listitem>
436                <para>A Java heap memory usage indicator, that shows used and
437                total heap memory, in megabytes. Double-clicking this indicator
438                opens the
439                <guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>Memory
440                Status</guimenuitem> dialog box.</para>
441            </listitem>
442        </itemizedlist>
443
444        <para>The visibility of each of the above items can be controlled in the
445        <guibutton>Status Bar</guibutton> pane of the
446        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
447        Options</guimenuitem> dialog box; see <xref
448        linkend="status-bar-pane" />.</para>
449    </section>
450
451    <section id="action-bar">
452        <title>The Action Bar</title>
453
454        <para>The action bar allows almost any editor feature to be accessed
455        from the keyboard.</para>
456
457        <para><guimenu>Utilities</guimenu>&gt;<guimenuitem>Action
458        Bar</guimenuitem> (shortcut: <keycap>C+ENTER</keycap>) displays the
459        action bar at the bottom of the View and gives it keyboard focus. The
460        action bar remembers previously entered strings; see <xref
461        linkend="history" /> for details.</para>
462
463        <para>To use the action bar, input a command and press
464        <keycap>Enter</keycap>. The following commands are supported:</para>
465
466        <bridgehead>Action invocations</bridgehead>
467
468        <para>Each menu item and tool bar button is bound to an
469        <firstterm>action</firstterm>. To find out the name of an action, invoke
470        the menu item or click the tool bar button, and look in the action bar's
471        history.</para>
472
473        <para>If a substring or an action name is entered, pressing
474        <keycap>Tab</keycap> shows a popup listing matching actions. An action
475        can be selected using the <keycap>Up</keycap> and <keycap>Down</keycap>
476        arrow keys, or by entering more characters of its name.</para>
477
478        <para>Pressing <keycap>Enter</keycap> with an incomplete substring
479        invokes the action that would be first in the completion popup's
480        list.</para>
481
482        <para>For example, entering <userinput>l-o</userinput> will match
483        <userinput>global-options</userinput>, which has the same effect as
484        invoking <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
485        Options</guimenuitem>.</para>
486
487        <bridgehead>Buffer-local properties</bridgehead>
488
489        <para>Entering <userinput>buffer.property=value</userinput> sets the
490        value of the buffer-local property named <userinput>property</userinput>
491        to <userinput>value</userinput>. Buffer-local properties are documented
492        in <xref linkend="buffer-local" />.</para>
493
494        <para>For example, entering <userinput>buffer.tabSize=4</userinput>
495        changes the current buffer's tab size to 4.</para>
496
497        <para>See <xref linkend="buffer-local" /> for information about
498        buffer-local properties.</para>
499
500        <bridgehead>Global properties</bridgehead>
501
502        <para>Entering <userinput>property=value</userinput> sets the value of
503        the global property named <userinput>property</userinput> to
504        <userinput>value</userinput>. This feature is primarily intended to help
505        plugin developers, since the properties jEdit uses to store its settings
506        are not currently documented.</para>
507
508        <bridgehead>Command repetition</bridgehead>
509
510        <para>To repeat a command multiple times, enter a number in the action
511        bar, then press the key-combination that invokes the command.
512        For example,
513        <quote><keycap>C+ENTER</keycap> <keycap>1</keycap> <keycap>4</keycap>
514        <keycap>C+d</keycap></quote> will delete 14 lines;
515        <quote><keycap>C+ENTER</keycap> <keycap>9</keycap>
516        <keycap>#</keycap></quote> will insert <quote>#########</quote> in the
517        buffer.
518        Note: The space characters in these examples should not be typed;
519        they are only here to visually separate the keys to be typed.</para>
520
521        <para>If you specify a repeat count greater than 20, a confirmation
522        dialog box will be displayed, asking if you really want to perform the
523        action. This prevents you from hanging jEdit by executing a command too
524        many times.</para>
525    </section>
526</chapter>