# Customizing jEdit

## The Buffer Options Dialog Box

Utilities>Buffer Options displays a dialog box for changing editor settings on a per-buffer basis. Changes made in this dialog box are not retained after the buffer is closed.

The following settings can be changed here:

- The line separator (see )

- The character encoding (see )

- If the file should be GZipped on disk (see )

- Whether to show a dialog or auto-reload when this buffer's file is changed on disk.

- The edit mode (see )

- The fold mode (see )

- The automatic indentation scheme (see )

- The wrap mode and margin (see )

- The tab width (see )

- The indent width

- If soft tabs should be used (see )

## Buffer-Local Properties

Buffer-local properties provide an alternate way to change editor settings on a per-buffer basis. While changes made in the Buffer Options dialog box are lost after the buffer is closed, buffer-local properties take effect each time the file is opened, because they are embedded in the file itself.

When jEdit loads a file, it checks the first and last 10 lines for colon-enclosed name/value pairs. For example, placing the following in a buffer changes the indent width to 4 characters, enables soft tabs, and activates the Perl edit mode:

    :indentSize=4:noTabs=true:mode=perl:

Adding buffer-local properties to a buffer takes effect after the the buffer is saved and loaded again.

The following table describes each buffer-local property in detail.

Property name | Description
--- | ---
`collapseFolds` | Folds with a level of this or higher will be collapsed when the buffer is opened. If set to zero, all folds will be expanded initially. See .
`deepIndent` | When set to true, multiple-line expressions delimited by parentheses are aligned like so:
    retVal.x = (int)(horizontalOffset
        + Chunk.offsetToX(info.chunks,
                          offset));
With this setting disabled, the text would look like so:
    retVal.x = (int)(horizontalOffset
        + Chunk.offsetToX(info.chunks,
        offset));
`folding` | The fold mode; one of none, indent, explicit, or the name of a plugin folding mode. See .
`indentSize` | The width, in characters, of one indent. Must be an integer greater than 0. See .
`maxLineLen` | The maximum line length and wrap column position. Inserting text beyond this column will automatically insert a line break at the appropriate position. See .
`mode` | The default edit mode for the buffer. See .
`noTabs` | If set to true, soft tabs (multiple space characters) will be used instead of real tabs. See .
`noWordSep` | A list of non-alphanumeric characters that are not to be treated as word separators. Global default is _.
`tabSize` | The tab width. Must be an integer greater than 0. See .
`wordBreakChars` | Characters, in addition to spaces and tabs, at which lines may be split when the word wrap mode is set to hard. See .
`wrap` | The word wrap mode; one of none, soft, or hard. See .
`autoIndent` | The automatic indentation scheme; one of none, full, or simple. See .

You may see `:encoding=XXX:` in a file as it is a buffer-local property and specifying the character encoding for the file. But it is not really a buffer-local property, and behaves differently. It is detected by `buffer-local-property` detector only if the detector is selected in encoding options. Thus, it works only at loading, and it must appear near the top of the file. See .

## The Global Options Dialog Box

Utilities>Options displays the options dialog. It has 2 tabs, the first is Global Options. This tab contains several options panes, each containing a set of related options. Use the list on the left splitter to switch between panes. Only panes created by jEdit are described here; Plugin Options panes are created and documented by the plugins themselves.

### The General Pane

The General pane contains various settings, such as the number of recent files to remember, when to check for changed files, if the recent file list should be sorted, what current locale to use, if caret positions or markers in buffers should be saved, if previously open files or split configurations should be restored on startup, and so on.

If Open Buffers Are Changed On Disk...

If Do Nothing is selected, then modifications from jEdit will silently clobber changes made from other processes during saves. Don't use this option unless you know what you are doing! Also, changing this option here only affects newly opened buffers, not the ones that are currently open. You can also change this setting for individual buffers from Buffer Options.

Check for changed buffers upon...

This option allows you choose additional times that jEdit checks for changed files on disk. For slow or remote file systems, removing unnecessary file status checks might improve performance. Regardless of the choice here, files are still checked before save, unless Do Nothing is also selected for the previous option.

### The Abbreviations Pane

The Abbreviations option pane can be used to enable or disable automatic abbreviation expansion, and to edit currently defined abbreviations.

The combo box labelled Abbrev set selects the abbreviation set to edit. The first entry, global, contains abbreviations available in all edit modes. The subsequent entries correspond to each mode's local set of abbreviations.

To change an abbreviation or its expansion, either double-click the appropriate table entry, or click a table entry and then click the Edit button. This will display a dialog box for modifying the abbreviation.

The Add button displays a dialog box where you can define a new abbreviation. The Remove button removes the currently selected abbreviation from the list.

See for information about positional parameters in abbreviations.

Abbreviations creating and editing

### The Appearance Pane

The Appearance pane can be used to change the appearance of user interface controls such as buttons, labels and menus. It can also be used to change the icon set, or look and feel, enable/disable the splash screen or system tray, and other appearance tweaks. You can also set the number of items retained in history text fields, see .

### The Context Menu Pane

The Context Menu option pane edits the text area's right-click context menu. See .

### The Docking Pane

The Docking option pane shows a list of available dockables, and allows you to specify docking locations for each of them. Another way to specify docking locations is to use the popup menus associated with each dockable window.

It is possible to configure jEdit to automatically load and/or save Docking Layouts (similar to eclipse perspectives) based on the edit mode of your current buffer through the checkboxes in this pane. See .

jEdit also supports alternate docking frameworks. If the appropriate plugins are installed (Currently only MyDoggy is available), you can change docking frameworks from here.

### The Editing Pane

The Editing option pane contains settings such as the tab size, syntax highlighting and soft tabs on a global or mode-specific basis.

Changing options from this optionpane does not change XML mode definition files on disk; it merely writes values to the user properties file which override those set in mode files. To find out how to edit mode files directly, see . Some of these options can be further overridden on an individual file basis through the use of buffer-local properties.

The `File name glob` and `First line glob` text fields let you specify a glob pattern that paths and first lines of buffers will be matched against to determine the edit mode. See for information about glob patterns.

The `Extra Word Characters` allows you to set the `noLineSep` buffer property on a mode-wide basis, allowing you to define what is considered part of a word when double-clicking on it in the text area.

The `Deep Indent` option instructs jEdit to indent subsequent lines so that they line up with the open bracket on the previous line.

### The Encodings Pane

This option pane offers users of jEdit many flexible options for defining how Encodings are handled in jEdit. See for the basics.

The default line separator character (see ) can be set from here.

Use autodetection when possible is an option you can switch on or off.

The `List of Encoding Autodetector Names` can be used to control what encoding detections are used on each file when it is loaded. The order they appear in this list determines the order of detectors that are tried. There are some detectors which are available with jEdit core:

- `BOM`: detects Byte Order Mark.

- `XML-PI`: detects encoding declaration in XML Processing Instruction.

- `html`: detects charset description in HTML META element.

- `python`: detects various encoding declaration accepted in Python. This accepts encoding declarations for GNU Emacs or Bram Moolenaar's VIM.

- `buffer-local-property`: detects same syntax described at for property name "encoding". Note that unlike other buffer-local properties, this one will not work unless it is at the top of the file, and this appears in the list of encoding detectors.

Others can be defined in plugins as services and added to this space-separated list. See EncodingDetector for details on how to offer additional encoding autodetector.

The `List of Fallback Encodings` is used when a file fails to open in the default encoding, and the Encoding Autodetectors also fail. The list order here determines the order of encodings that are tried. Each is separated by a space. This is especially handy when doing directory searches through files of different encodings. We suggest using `UTF-8` as either your default or one of the fallback encodings.

While jEdit allows you to edit files in a variety of different encodings, the average user switches between only 2 or 3. In other parts of jEdit, where the list of encodings is displayed in a combobox (such as the buffer options) or a menu (such as File - Reload with Encoding submenu) it may be desirable to display only a subset of available encodings, those that are in common local use. The Encodings checkbox list allows the user to select the subset of supported encodings to display in other GUI components that list all of the encodings.

### The Gutter Pane

The Gutter option pane contains settings to customize the appearance of the gutter. You can customize values such as "minimal number of digits to reserve for line numbers", and "fold style". See .

### The Mouse Pane

The Mouse option pane contains settings for toggling drag and drop of text, as well as gutter mouse click behavior.

The only option that may not be self-explanatory is the Double-Click drag joins non-alphanumeric characters. This option means that double-click will select a region that includes the non-alphabetical characters, as defined for the current mode. The actual set of characters can be defined for an indiviual file via buffer-local properties (`noWordSep`) or on a mode-wide basis from the Editing option pane (`Extra Word Characters`).

### The Plugin Manager Pane

The Plugin Manager pane contains a chooser for the desired download mirror, as well as various settings such as the directory where plugins are to be installed. In addition, you can set the time in minutes that the pluginlist can be cached from jedit.org, helping to reduce the server load. See .

If the option Disable Obsolete Plugins is checked, then plugins that were released on Plugin Manager will be checked against the plugins you have installed, for those with a maximum jEdit version that is lower than the one you are running. Plugins are marked with a maximum jEdit version when they are found to be broken or somehow incompatible with a given jEdit release. Until an update is made available for such a plugin on Plugin Manager, these plugins are automatically unloaded and marked unsupported. This should improve the stability of jEdit.

If you re-enable a plugin that was disabled this way, it will remain loaded until the next time the plugin list is checked - whenever the user selects the Update or Install tab from Plugin Manager. If you un-check this option, then plugins will not be automatically disabled in this way.

### The Printing Pane

The Printing option pane contains settings to control the appearance of printed output. Workarounds that might be needed for your Java version to print correctly can also be enabled here. See .

### The Proxy Servers Pane

The Proxy Servers option pane lets you specify HTTP and SOCKS proxy servers to use when jEdit makes network connections, for example when downloading plugins.

### The Saving and Backup Pane

The Saving and Backup option pane contains settings for the autosave and backup features. See and .

### The Shortcuts Pane

The Shortcuts option pane associates keyboard shortcuts with commands. Each command can have up to two shortcuts associated with it, and each shortcut can be a single or multiple key sequence.

jEdit 5 introduces a new feature known as "keymaps". Each keymap is a named set of keyboard shortcut mappings. Default keymaps are found in jEdit's `keymaps` folder, and user customized keymaps are are stored in the user settings' `keymaps` folder.

The top combobox allows you to Choose a Keymap, or a set of shortcuts. The "imported" keymap is automatically created and selected when jEdit needs to initially create a "keymaps" user settings folder. At this point, jEdit imports the existing shortcuts and places them into "imported". This makes it easy to bring in shortcuts from properties files that were customized with jEdit 4.5 or earlier.

If a keymap of the same name exists in the defaults and the user settings directory, the user version is the one that is used in favor of the default. To take an existing keymap and customize it, select it, click duplicate and you will be asked for the name of the new keymap. A copy of that keymap will be saved in the user settings `keymaps` directory. At this point, this keymap will be selected and will determine where new shortcut properties are stored. To remove all customizations and restore a default keymap, click reset.

The combo box below the keymap selector selects the command set to edit. Command sets exist for the set of all built-in commands, the commands of each plugin, and the set of macros.

To change a shortcut, click the appropriate table entry and press the keys you want associated with that command in the resulting dialog box. The dialog box will warn you if the shortcut is already assigned. The properties will be saved in the currently selected keymap.

### The Status Bar Pane

The Status Bar, its API, and its corresponding option pane contains settings to customize which widgets are in the status bar, their order, and what separators exist between them. Also, you can disable it completely, for regular and/or plain views. See .

From the `Options` tab, you can customize information about the caret display in the lower left corner.

Selecting the `Widgets` tab of this option pane shows you what widgets on the right, and their order. You can add or remove widgets and separators/labels here.

### The Syntax Highlighting Pane

The Syntax Highlighting pane can be used to customize the fonts and colors for syntax highlighting. See .

### The Text Area Pane

The Text Area pane contains settings to customize the appearance of the text area.

You can configure the Text Font, antialias settings, colors, cursor style, highlight matching, and word-completion settings from here.

Fractional Font Metrics is an old option that helps with certain versions of Java, but usually not in combination with subpixel antialiasing.

Additional Fonts with font substitution if checked, shows a list of Preferred fonts, as well as the following option. Fonts added to this list will determine the order jEdit searches for glyphs that may be missing from your chosen Text Font.

If the Font Substitution: Search all system fonts option is checked, all of the installed fonts are searched for glyphs, after the preferred list is searched. If this option is checked, no fonts need to be added to preferred fonts list. You probably don't want to un-check either of these options unless you want to test a system with limited fonts.

### The Tool Bar Pane

The Tool Bar option pane lets you edit the tool bar, or disable it completely. See .

### The View Pane

The View option pane lets you change various settings related to the editor main window appearance, including the arrangement of dockable windows, whether the search bar and buffer switcher are visible, and whether menu, toolbar, and statusbar are visible in full-screen mode. See .

You can choose the default bufferset scope here, as well as whether/how you want buffersets to be sorted in buffer switchers. See for more details.

If Abbreviate paths with environment variables when possible is checked, you will notice that jEdit displays abbreviated versions of file paths when it can, using `$VARIABLE/name.ext` or `%VARIABLE%\name.ext` syntax, depending on your platform. Abbreviating is used in the File System Browser, as well as in the window title, and in plugins, to save horizontal space. Reverse-expansions also work as you would expect them to, with both syntaxes recognized on both platforms.

### The File System Browser Panes

The File System Browser group contains two option panes, General and Colors. The former contains various file system browser settings. The latter configures glob patterns used for coloring the file list. See for more information.

## The jEdit Settings Directory

jEdit stores settings, keymaps, macros, and plugins as files inside the settings directory. In most cases, editing these files by hand is not necessary, since graphical tools and editor commands can do the job. However, being familiar with the structure of the settings directory still comes in handy in certain situations, for example when you want to copy jEdit settings between computers.

The location of the settings directory is system-specific

On Linux, it is `~/.jedit`. On Windows, you will find it in `%APPDATA%\jEdit`. On the Mac, it is `~/Library/jEdit`.

. It is printed to the activity log (Utilities>Troubleshooting>Activity Log). For example:

    [message] jEdit: Settings directory is /home/slava/.jedit

Another way to find the location of your settings directory is to use the "Utilities" menu, then the "Settings Directory" menu item. The first item in the pullout menu is the location of your settings directory.

Specifying the `-settings` switch on the command line instructs jEdit to store settings in a directory other than the default. For example, the following command will instruct jEdit to store all settings in the `jedit` subdirectory of the `C:` drive:

    C:\jedit> jedit -settings=C:\jedit

The `-nosettings` switch will force jEdit to not look for or create a settings directory; default settings will be used instead.

jEdit creates the following files and directories inside the settings directory; plugins may add more:

- `abbrevs` - a plain text file which stores all defined abbreviations. See .

- `activity.log` - a plain text file which contains the full activity log. See .

- `history` - a plain text file which stores history lists, used by history text fields and the Edit>Paste Previous command. See and .

- `jars` - this directory contains plugins. See .

- `jars-cache` - this directory contains plugin cache files which decrease the time to start jEdit. They are automatically updated when plugins are installed or updated.

- `keymaps` - this directory contains collections of named keyboard shortcuts which can be defined from the Shortcuts Option Pane (see ).

- `killring.xml` - stores recently deleted text. See .

- `macros` - this directory contains macros. See .

- `modes` - this directory contains custom edit modes. See .

- `perspective.xml` - an XML file that stores the list of open buffers and views used to maintain editor state between sessions.

- `PluginManager.download` - this directory is usually empty. It only contains files while the plugin manager is downloading a plugin. For information about the plugin manager, see .

- `pluginMgr-Cached.xml.gz` - this contains a cached copy of the last XML plugin list downloaded from plugin central. If you delete this file, a new one will be created next time you try to install a plugin via Plugin Manager.

- `printspec` - a binary file that stores printing settings.

- `properties` - a plain text file that stores the majority of jEdit's and its plugins settings. For more information see .

- `recent.xml` - an XML file which stores the list of recently opened files. jEdit remembers the caret position and character encoding of each recent file, and automatically restores those values when one of the files is opened.

- `registers.xml` - an XML file that stores register contents. See for more information about registers.

- `server` - a plain text file that only exists while jEdit is running. The edit server's port number and authorization key is stored here. See .

- `settings-backup` - this directory contains numbered backups of all automatically-written settings files.

- `startup` - This directory contains startup scripts in beanshell or other plugin-supported scripting languages. They are run at the time jEdit starts, after the `startup` scripts in the jEdit install directory have been run. See

### The jEdit properties file

The jEdit `properties` file uses the Java properties syntax to store key/value pairs. All of the values are stored as strings, but are interpreted as other types (such as integer or boolean) by plugins at runtime.

Do not edit this file while jEdit is running. If you do, it is possible that your changes (either your edits, or jEdit settings changes) may get lost.

### Site Properties

You may also put properties files in the `properties` directory under the jEdit home directory (NOT the jedit settings directory). You can locate the jEdit home directory by going to the Utilities menu directory, then the jEdit Home Directory menu item, and the first item in the pullout menu will be the location of the jEdit home directory. This is intended for site-wide settings. This lets you keep custom user properties separate from the jEdit site-wide properties, so they are easier to find, edit, and move between machines. Note that your custom properties files must have ".props" as the file name extension.

Prior to jEdit 5.0, this was also where site-wide keyboard shortcuts were placed, but now you can define custom sets of shortcuts as keymap files. These files can be cloned and edited from the Shortcuts Option Pane, or edited by hand. To place them in a system-wide location, copy them into the `keymaps` folder under the jedit home directory.

Site properties files are read in alphabetically by file name. This means that if you have a property with the same name in more than one file, the value for that property will be the value found in the last file that was read.

You can edit these files inside jEdit - changes made to these files will not be re-read until the next time jEdit is started.