

                                                   A . d . i . e

                                         The ADvanced Interactive Editor




Introduction.

Adie is an extremely fast and convenient programming text editor and file viewer written using the FOX Toolkit, and supports UTF8 unicode text rendering.

Flexible syntax coloring is available for multiple programming languages and may include user-written extensions.  Each syntactical element may be given its own, user-defined color, or other character attributes.

Project browsing is made easy by displaying a File- and Directory-browser side by side with the text buffer so files may be visited by means of a single click.  Files may also be opened simply by highlighting a file name, compiler warning message, or #include directive and hitting a single button; Adie will search for the file in the same directory as an already loaded file, or in a number of predefined directories (like for example include directories).

Unlimited undo and redo capability will allow changes to be unwound painlessly, making accidental deletes easy to recover.

Bookmarks may be set to quickly hop around in the text; a special "insertion point" bookmark is automatically set whenever text is modified, allowing the user to alway jump back to the last modified line.

General Features.

  - User-extensible syntax coloring for multiple programming languages.
  - Block selection and manipulation.
  - Highlighting of current line.
  - Optional line number display.
  - Preferences are configurable with convenient dialogs.
  - Ability to edit huge text sizes.
  - Wheel mouse scroll support, with vernier (fine) scrolling support.
  - Right-mouse pixel-proportional scrolling.
  - Help window (this text) which can stay up during editing.
  - Parse vim, emacs, and adie modelines to set programming language.
  - Edit multiple files in multi-window mode.
  - Automatically configure hardtabs when loading files recognized as Makefiles.
  - Searching files matching a wildcard pattern for a regular expression.
  - Built-in calculator for expressions.
  - Optionally persist bookmarks when closing file.
  - Optionally persist scroll-position when closing file.

File Access Features.

  - File Dialog supporting bookmarked directories.
  - Drag and drop file into editor to switch to file.
  - File- and directory-browser allows single-click file loading.
  - Visit recently edited files from recent files menu.
  - Parse filename and line number to open file at given line (and column) from command line.
  - Jump to file and line number of highlighted compiler warnings or errors.
  - Open new window or switch current window to another file.
  - Open highlighted #include-files by searching common include directories (configurable).
  - Detect external programs changing or removing file being edited outside of the editor.
  - Insert text from another file into the text editor.
  - Extract text from the text editor to another file.
  - Save As, and Save-To to save text to another filename.
  - Reload file from disk to revert to on-disk version.
  - Customize wild-card patterns for limiting files shown in File Dialog or File Browser.
  - Search files wildcard pattern for text matching regular expression, and open with a click.

Editing Features.

  - Drag select, word select, or whole lines selection.
  - Block selection, cut-and paste text blocks, insert or overstrike text blocks.
  - Cut and paste to clipboard support.
  - X11 primary selection support using middle-mouse paste.
  - Unlimited undo/redo capability with alternate history mode.
  - Drag-and-drop support for text move or copy.
  - Highlight matching braces or parentheses.
  - Set bookmarks to remember points of interest in the file.
  - Search and Replace dialog for simple, or regular expression search, with previous search history.
  - Quick incremental search bar supporting search-as-you type.
  - Highlight numerical expression and calculate its result.
  - Filter selected text through shell-commands.
  - Simple auto-indent feature.
  - Indent or unindent selected lines of text.
  - Search for highlighted text.
  - Set a fixed word wrap column, or perform fluent word wrap mode.
  - Strip trailing spaces, strip carriage-returns for DOS files.
  - Add carriage-returns when saving to DOS files.
  - Mouse wheel scrolling.
  - Right-mouse drag to scroll proportionally.
  - Right-mouse context menu with handy options.

Syntax Coloring Features.

  - Describe syntax of programming language using collection of nested regular expressions.
  - Custom coloring for each syntax rule.
  - Switch collection of coloring rules based on file-extension, or based on mode line.
  - Selected files may be custom colorized based on entire file name.
  - Explicitly set syntax from pulldown menu.
  - Syntax description also configures some switches (e.g. enable tab support for Makefiles).
  - Group syntaxes of similar programming languages to give them similar colors.


Starting a New Document.

To start a new document, invoke the 'File' / 'New' menu, or press the 'New' button on the toolbar.  A new window will be opened, with a filename like 'untitled' or 'untitled1', etc. in the current directory.  The editor will remember the document hasn't been given a filename yet, and will prompt for a filename when being saved.

A second method to start a new document is the 'New File' menu, or 'New File' button on the toolbar.  This will immediately prompt the user for a filename using the File Dialog. However, the file will not be created on disk until its saved.  The advantage of this method is that the file extension will be known, and thus the correct syntax can be chosen for highlighting the newly added text. Of course since the filename is known, there will be no need for a prompt later to enter it.


Opening and Saving Files the Old Fashioned Way.

To open a file, you can invoke the 'File' / 'Open' menu, or press on the 'Open' button on the toolbar.  This will bring up the standard File Dialog, which allows you to select a file.
To save a file, you can either invoke the 'File' / 'Save', 'Save As', or 'Save To' menu option.  'Save' will save the text to the same filename as it was loaded from.  'Save As' will prompt the user to enter a new filename, then save the file to the new name.  This will leave the document under the new name in the text buffer, and a subsequent 'Save' will save the document to the new filename.
When you invoke 'Save To', you will be prompted for a new filename, similar to 'Save As', except that the document will not change to the new filename.  A subsequent 'Save' will still save the document to its prior name.


The File Dialog.

When working with the File Dialog, you can quickly navigate to the desired file by typing the first few letters of a filename and then pressing Enter (Return).
If you don't know what you're looking for, you can navigate among the files using the arrow-keys.  Use Backspace key to move to a higher directory folder.  Use Control-H to move to your home directory, or Control-W to move back to the current working directory.
If any bookmarks have been set, you can quickly jump to previously bookmarked directory folders.
Of course, you can also directly type the path of the file into the 'File Name' text entry box.
To limit visual overload, use 'File Filter' to select a wild-card pattern to limit the displayed files to those matching the pattern.
Once the proper file name has been selected, press Return to select it.  Alternatively, when selecting files with the mouse, you can simply double-click the file and immediately return.
The File Dialog is designed to facilitate the experienced user, and allows selection of a file without ever using the mouse.  Because your hands are already on the keyboard.

To bring up the File Dialog via keyboard, use Control-O (open existing file), Shift-Control-N (new file with name), Shift-Control-S (save as), or Shift-Control-T (save to).


Opening Files Using the File and Directory Browser.

An alternative method to open files is the File and Directory Browser. You can display the File and Directory Browser by invoking the 'File Browser' option under the 'View' menu.  To open a file using the File and Directory Browser, simply click on the file. If there are many files, you may want to limit the number of files displayed by specifying a file wild-card pattern in the 'Filter' combo box.
The patterns can be any file wildcard expression such as '*.cpp'.  By default, the File and Directory Browser shows all files, i.e. the pattern is '*'.
Additional patterns can be added to the list using the 'Preferences' Dialog.


Opening Recently Visited Files.

The recent file section of the 'File' menu shows files which have been recently visited.  You can quickly get back to a file you've been editing simply by selecting one of these recent files.
If you select a file which is already open, the window currently editing that file will be brought to the top.


Opening Files by Drag and Drop.

Using a file browser such as PathFinder or other Konqueror or other XDND compatible file browsers, you can simply drop a file into the text pane and have the editor open this file.  If the current file being edited has been changed, you will be prompted to save it first before switching to the dropped file.


Opening a Selected Filename.

Selecting any filename, possibly in another application, and invoking the 'File' / 'Open Selected' menu, or the 'Open Selected' toolbar button causes the editor to open the selected file.  If more than the filename alone is selected, the additional text may be subject to various interpretations.  When the selected string is of the form:

   #include "filename.h"

or:

   #include <filename.h>

The editor will parse the filename from the string and open it in the same directory as the currently loaded file, and if not found there, look into a sequence of (possibly relative) search paths. [You can specify the list of search paths to search by entering a list of absolute or relative pathnames into the 'Preferences' dialog, under the 'Miscellaneous' sub panel]. When the selected filename is of the form:

   filename.cpp(177)

or:

   filename.cpp:177:9

or:
   filename.cpp:177


The editor will not only load the filename, but also jump to the given line number (and column number, if available).  In the case column number is available, it will also place the cursor on the 9-column of line 177.  If this file has already been loaded, the editor will simply jump to the given line number in the already open file, and bring the window to the front.
This option is very useful when fixing compiler errors.  Various other popular compiler error or warning formats are supported besides GCC.
If a file is of the form:

  "C:\\Users\\Annual Sales Figures.txt"

Which represents an escaped pathname [possibly, because there are spaces in the filename], the editor will un-escape the selected pathname, and try to open it.  On Linux and other unix-like systems, it will assume bash-escape rules; on Windows, as this example here is, it will follow Windows command-line escape rules.


Editing Text.

When a new document is first created, the editor will initially be placed into 'Insert Mode,' i.e. any characters you type will be inserted at the current cursor location.  Hitting the 'INS' key, the editor will be placed in overstrike-mode.  In overstrike mode, characters you type will replace the ones already there [unless you are at the end of a line].

Tabs Or Spaces?

When you hit the 'Tab' key, a special tab-character will be inserted ('Tab Mode'), unless the editor is in ('EMT', or 'Emulated Tabs Mode'). The tab character is typically set to 8 columns, but this may be changed if desired.  If you very, very rarely need to insert a tab-character, but mostly want to use 'EMT' mode, you can insert a hard-tab via Control-Tab key.


Navigating Through The Text.

The usual methods apply: Arrow keys, Delete, Backspace, Page-Up, Page Down, Home, End, etc.  A few keys have interesting modifiers. Holding the 'Shift' key while pressing navigation keys causes the range of characters to be selected.  Holding the 'Alt' key similarly causes a 'Block-Select' to be performed.  With some navigation keys, holding 'Control' will cause words, not characters, to become selected.  For the 'Control-Up' and 'Control-Down' the text buffer will scroll while keeping cursor on the same line.


Mouse Operations.

The left mouse button is used to place the cursor at some location in the text.  If you hold the left mouse button while dragging the mouse, a range of text is selected, starting from the initial location where the left-button was first pressed (the anchor point), to the location where the mouse is moved next.  Releasing the left button will cause the region of text to remain selected.

Often, you will want to select whole words, or lines.  This is also performed with the left mouse button: to select whole words, double-click and hold the left mouse button, then drag while holding it down. The selection now will try to encompass whole words.  Simply double-clicking will select the whole word at the location where the click takes place.

To select lines, triple-click and hold the left mouse button. As you drag while holding the left button, whole lines will be selected if the pointer moves from line to line.  Simply triple-clicking will select the entire line containg the location where the click takes place.

Block-selection is performed by holding the Control key while pressing the left mouse button. When the block-selection is zero columns wide, there is no selected text, but a multi-line insert position.
A paste operation where multi-line insert position is in effect will insert lines of text in the middle of the selected columns.
For block-selections to work, the editor must NOT be in line wrap mode, and the font used to display text must be fixed pitch or "cell" based font.  Block selections will not work with proportional fonts or line-wrapping.

Clicking right mouse button normally brings up the context popup menu.  Pressing the right mouse button and then dragging will move the text proportionally to the mouse movement.  This is very convenient for sideways scrolling or fine-positioning the text around where the action is.

The middle mouse button (or wheel-button) is used to paste text selected anywhere on the screen (on Linux); however, pressing and holding the middle mouse button on a selected text will drag the selection to a new location, and drop it where the middle button is released [except if the middle button is release while the insertion cursor is inside the selection being dragged.

The mouse wheel usually scrolls the text up and down.  The amount of scrolling can be configured, but it defaults to 10 lines.  Pressing Control while rolling the mouse wheel causes the scrolling to advance by one page of text at a time (the seven league boots, if you will).  Use it to roll through large text files quickly.


Scrolling Text.

Use the scrollbars to scroll text. You can press the scrollbar thumb with the left mouse button, then move it.  Doing so while holding Control or Shift key will set the scrollbar into "fine" scrolling mode, moving the text very delibrately and proportionally to the mouse movement.  Using the middle mouse button anywhere in the scrollbar will cause the scroll position to jump to the new location.  Holding the middle mouse button subsequently will scroll as normal.  You can use this technique if you know approximately where in the text you want to go.

When dragging a selection, or performing a drag- and drop-operation, the text buffer will also scroll automatically when the cursor gets near the edge of the window.


The Clipboard.

After selecting some text, you can cut (Control-X) or copy (Control-C) this text to the clipboard. A subsequent paste operation will then insert the contents of the clipboard at the current cursor location.
If some text has been selected in another application, then you can paste this text by placing the cursor at the right spot in your text and invoking the Paste command (or type Control-V).

If a block-selection is in effect, the lines of text on the clipboard will replace the selected block of text; columns of text before and after the selection will remain intact, but columns past the last selected column may move left of right, depending on whether the new text is wider or smaller than the original block.
If the new text comprises more lines of text than the original selected block, new blank lines will be appended and the spill-over will be inserted at the selected column.


The Primary Selection.

When text is selected anywhere (possibly in another application), the editor can paste this text into the current edit-buffer by means of the middle mouse button [or by pressing the wheel-button if you have a wheel mouse].


Text Drag and Drop.

After selecting some text, you can drag this text to another location by pressing the middle mouse button; because Adie is fully drag and drop enabled, you can not only drag a selection from one place to another inside the edit-buffer, but also between different editor applications, or even from Adie to another drag and drop enabled application or vice-versa.
Within the same text window, the drag defaults to a text-movement.  You can change this to a text copy by holding down the Control key while you're dragging.
Between one text window and another, the drag defaults to a copy operation you can change this to a text movement by holding down the Shift key while dragging.


Undo and Redo.

The editor supports unlimited (well, the limit is large...) undo and redo capability.  Each time you insert, remove, or replace some text, the editor remembers what you did.
If you make a mistake, you can undo the last edit, and the one before that, and so on. Having invoked undo many times, it is sometimes desirable to invoke the redo command, i.e. to perform the original editing operation again.  Thus, you can move backward or forward in time.

The "Merge Undos" option consolidates contiguous single-character insertions or deletions into larger undo commands.  When the "Merge Undos" mode is on, an undo or redo will undo inserts or deletes on a word-by-word basis.  It tries to be smart about which character classes are "mergeable," so that for example editing source code, we're not backing over operators and other punctuation that may have special meanings in programming languages (we're still experimenting with this feature so the precise behaviour will be fine-tuned a bit in the future.

A new addition to the undo system is the "Alternate History" mode.  If, after undoing several commands, you decide edit the buffer in a different way, all commands that you have undone would normally be deleted, and you would no longer be able to go forward with redo from that point.
However, when "Alternate History" mode on, Adie will remember "the path not taken" and allow you to undo back to the original text, prior to the change.

Needless to say, this may vastly expand the amount of memory used by the undo system; however, to prevent things getting out of hand the undo list is periodically trimmed to keep it manageable.

When you load a file, or save a file after editing it, the undo system will remember the state of the text buffer as "clean" or "marked".  Making further changes, you will be able to quickly go back to this clean state using the "Revert" command.  Unlike reload, no disk I/O is performed when this happens: we're simply exucuting undo or redo commands to go back to the marked state.

Of course, if a huge amount of text was modified, and the undo list had to be trimmed, you will potentially not be able to reach the marked state anymore if it wanders into the trimmed range.  However, the default limits are set pretty large for editing regular source files; if you ever run into these limits, they can be changed in the preferences panel.


Evaluating Numerical Expressions.

Often, when writing technical software, you want to pre-calculate some numbers.  Adie makes this easy by allowing you to simply type a formula, highlighting it, and then invoking the Edit / Expression menu, or hitting the Expression button on the toolbar.

For instance:

  circumference=PI*2*10;

Selecting the part PI*2*10 and executing the Expression button will replace the text with:

  circumference=62.8318530717959;

The expression calculator knows the usual operators:

  ? :	alternate expression
  <, <=, >, >=	comparisons
  ==, !=	equalities
  <<, >>	bit-shifts
  &, |, ^	bit-wise operations
  +, -	addition and subtraction
  *, /, %	multiply, divide, modulo
  **	power
  -, ~	unary minus, bitwise not
  ( )	parenthesized subexpressions

The expression calculator knows common math functions: abs(), acos(), acosh(), asin(), asinh(), atan(), atan2(), atanh(), cbrt(), ceil(), cos(), cosh(), cub(), erf(), erfc(), exp(), exp2(), exp10(), floor(), inverf(), inverfc(), isfin(), isinf(), isnan(), log(), log2(), log10(), max(), min(), near(), pow(), round(), sin(), sinh(), sqr(), sqrt(), tan(), tanh(), trunc(), wrap(), wrap4().

And a few mathematical constants: PI, E, DTOR (degree to radians), RTOD (radians to degrees).


Modeline Support.

Modelines are hints embedded in a comment that suggest certain editor settings.  For instance, in a document with no file-extension, a modeline can be used to suggest which syntax coloring language mode to select.
If modelines are enabled, Adie tries to detect the presence of a modeline somewhere in the first 30 lines, or in the last 10 lines of a document.

Modelines can automatically enable or disable some features in the editor, such as syntax coloring language mode, tan stop settings, text wrapping mode, tab emulation or hard-tab mode, and auto-indent modes.

Vim modelines are of the form:

	"[text]{white}{vi:|vim:|ex:}[white]{options1}"

In Vim modelines, programming language, wrap mode, wrap columns, auto-indent, tab-columns, and soft- or hard-tab modes may be configured.  These take precedence over the defaults and values in the syntax file if present.

Emacs modelines are of the form:

	"-*- key1: value1; key2: value2; -*-"

In Emacs modelines, programming language, tab stops, wrap mode, soft- or hard-tab modes, and auto-indent may be configured. Example:

	-*- mode: C++; tab-width: 8; -*-

Finally, in Adie modelines, which are of the form:

	"adie: key1=value1 key2=value2 key3=value3 :"

Language mode, tab stops, wrap columns, wrap mode, soft- or hard-tab mode, and auto-indent may be configured.  The variables are simple two-letter names.  The variable "la" configures the programming language to be used for syntax coloring; the variable "ts" sets the tab-stop value. The variable "ww" controls wrap column, and "wr" enables word-wrapping if set to 1.  The variable "et" controls hard-tabs 0 or soft-tabs 1, and the variable "ai" enables auto-indent if set to 1.
For example, the adie mode line:

	adie: la=C++ ts=8 ww=80 wr=1 et=1 ai=1:

This would set the syntax coloring to C++-mode, 8-column tabs, wrap lines at 80 columns, expand tabs to spaces, and turn auto-indent on.

These settings may also be set in the syntax file; however, the modeline, if enabled, will override the value in the syntax file or the default setting from the dialog, if present.


Searching Files.

The Search Files dialog can be used to search files for a particular search string or regular expression pattern.  You typically don't want to search all types of files, but only text files or source files.
Thus, just like the File Dialog, you can apply a wildcard filter to limit the files to be examined.  Moreover, you can select which directory folder to search.  For a larger project, you optionally can also search subdirectories of that directory folder.
Once the search parameters have been set, click Search to start the search.  Depending on the number of files to be searched, this may sometimes take some time, so periodically, the editor check to see if the Pause button has been pressed.  After pausing the search, you can either resume, or stop.
As the files are being searched, file locations and context of successful searches (hits) are recorded.
You can click on these to open the file and jump to the location of the hit.

Multiple searches may be performed, and the string to be searched does not have to be the same each time a search is started.  Pressing Delete button will however delete all the results and present you with a clean slate.


Search and Replace.

Adie uses the standard Search Dialog for searching strings. The search dialog offers forward and backward searches (relative to the current cursor location), and three search modes:

Exact. In the Exact mode, a search looks for a verbatim occurrence of the search string in the text.

Ignore Case. In the Ignore Case mode, a search looks for a verbatim occurrence also, but while disregarding the uppercase/lowercase distinctions.

Expression. In the Expression mode, the the search performs a full regular expression match.  The regular expression syntax being used is very similar to PERL and is as follows:


  Special Constructs:

  ( ... )	Grouping sub pattern
  (?i ... )	Match sub pattern case insensitive
  (?I ... )	Match sub pattern case sensitive
  (?n ... )	Match sub pattern with newlines
  (?N ... )	Match sub pattern with no newlines
  (?: ... )	Non-capturing parentheses
  (?= ... )	Zero width positive lookahead
  (?! ... )	Zero width negative lookahead
  (?<= X )	Zero width positive (arbitrary) lookbehind
  (?<! X )	Zero width negative (arbitrary) lookbehind
  (?> X )	Atomic grouping (possessive match)


  Greedy quantifiers:

  *	Match 0 or more [greedy]
  +	Match 1 or more [greedy]
  ?	Match 0 or 1 [greedy]
  {}	Match 0 or more [greedy]
  {n}	Match n times [greedy]
  {,m}	Match no more than m times [greedy]
  {n,}	Match n or more [greedy]
  {n,m}	Match at least n but no more than m times [greedy]


  Lazy quantifiers:

  *?	Match 0 or more [lazy]
  +?	Match 1 or more [lazy]
  ??	Match 0 or 1 [lazy]
  {}?	Match 0 or more times [lazy]
  {n}?	Match n times [lazy]
  {,m}?	Match no more than m times [lazy]
  {n,}?	Match n or more [lazy]
  {n,m}?	Match at least n but no more than m times [lazy]


  Possessive quantifiers:

  *+	Match 0 or more [possessive]
  ++	Match 1 or more [possessive]
  ?+	Match 0 or 1 [possessive]
  {}+	Match 0 or more times [possessive]
  {n}+	Match n times [possessive]
  {,m}+	Match no more than m times [possessive]
  {n,}+	Match n or more [possessive]
  {n,m}+	Match at least n but no more than m times [possessive]


  Boundaries:

  ^	Match begin of line
  $	Match end of line
  \<	Begin of word
  \>	End of word
  \b	Word boundary
  \B	Word interior
  \A	Match only beginning of string
  \Z	Match only and end of string


  Character classes:

  [abc]	Match 'a', 'b', or 'c'
  [^abc]	Match any but 'a', 'b', or 'c'
  [a-zA-Z]	Match upper- or lower-case a through z
  []]	Matches ']'
  [-]	Matches '-'


  Predefined character classes:

  .	Match any character
  |	Alternation
  []	Character class
  \d	Digit [0-9]
  \D	Non-digit
  \s	Space
  \S	Non-space
  \w	Word character [a-zA-Z_0-9]
  \W	Non-word character
  \l	Letter [a-zA-Z]
  \L	Non-letter
  \h	Hex digit [0-9a-fA-F]
  \H	Non-hex digit
  \u	Single uppercase character
  \U	Single lowercase character
  \p	Punctuation (not including '_')
  \P	Non punctuation


  Back References:

  \1	Reference to 1st capturing group
  \2	Reference to 2nd capturing group
  ..
  \9	Reference to 9th capturing group


  Characters:

  x	Any character
  \\	Backslash character '\'
  \cX	Control character (X is '@', 'A'...'Z', '[', '\', ']', '^', '_', or '?' for DEL)
  \xFF	Hexadecimal number (should be exactly two hex-digits)
  \033	Octal (not to exceed 255 in value)
  \a	Alarm, bell
  \b	Only in character classes: a Backspace character code. Otherwise, word-boundary
  \e	Escape character
  \t	Tab
  \f	Form feed
  \n	Newline
  \r	Return
  \v	Vertical tab
  \X	Just X (unless X is one of [dDsSwWlLhHuUpP\0123456789xcaetfnrv])


Greedy match (the default) tries to match as many characters as possible, but backs off one at a time until a match is found.  Lazy match tries to match as few characters as possible, but advances one at a time until a match is found.  The possessive match behaves much like the greedy match, but does not back off; if the rest of the pattern does not succeed, the match fails.
Possessive match can often be a major guard against unnecessary recursion by calling it quits early, in cases where backing off has no possibility of success.


Keyboard Bindings.

The following table lists the keyboard bindings.

Key:	Action:
====	=======

  Up	Move cursor up.
  Shift+Up	Move cursor up and extend selection.
  Ctl+Up	Scroll text downward, keeping current line.
  Down	Move cursor down.
  Shift+Down	Move cursor down and extend selection.
  Ctl+Down	Scroll text upward, keeping current line.
  Left	Move cursor left.
  Shift+Left	Move cursor left and extend selection.
  Ctl+Left	Move cursor left by one word.
  Ctl+Shift+Left	Move cursor left by one word and extend selection.
  Right	Move cursor right.
  Shift+Right	Move cursor right and extend selection.
  Ctl+Right	Move cursor right by one word.
  Ctl+Shift+Right	Move cursor right by one word and extend selection.
  Home	Move cursor to begin of line.
  Shift+Home	Move cursor to begin of line and extend selection.
  Ctl+Home	Move cursor to top of text.
  Ctl+Shift+Home	Move cursor to to top of text and extend selection.
  End	Move cursor to end of line.
  Ctl+End	Move cursor to bottom of text.
  Shift+End	Move cursor to end of line and extend selection.
  Ctl+Shift+End	Move cursor to bottom of text and extend selection.
  Page Up	Move cursor up one page.
  Shift+Page Up	Move cursor up one page and extend selection.
  Page Down	Move cursor down one page.
  Shift+Page Down	Move cursor down one page and extend selection.
  Insert	Toggle between insert mode and overstrike mode.
  Shift+Insert	Paste text from clipboard.
  Ctl+Insert	Copy selected text to clipboard.
  Delete	Delete character after cursor, or text selection.
  Ctl+Delete	Delete word after cursor.
  Shift+Delete	Delete to end of line.
  BackSpace	Delete character before cursor, or text selection.
  Ctl+BackSpace	Delete word before cursor.
  Shift+BackSpace	Delete to begin of line.
  Return	Insert end of line, add indent if auto-indent is on.
  Shift+Return	Insert end of line, and indent even if auto-indent is off.
  Ctl+Return	Insert end of line only.
  Tab	Insert (emulated) tab.
  Ctl-Tab	Insert hard tab.
  Ctl+Shift+<	Move current line up.
  Ctl+Shift+>	Move current line down.
  Ctl-D	Copy current line.
  Ctl+A	Select all text.
  Ctl+X	Cut selected text to clipboard.
  Ctl+C	Copy selected text to clipboard.
  Ctl+K	Delete line.
  Ctl+V	Paste text from clipboard.


Changing Font.

You can change font by invoking the Font Selection Dialog from the Font menu. The Font Dialog displays four list boxes showing the font Family, Weight, Style, and Size of each font.
You can narrow down the number of fonts displayed by selecting a specific character set, setwidth, pitch, and whether or not scalable fonts are to be listed only.
The All Fonts checkbutton causes all fonts to be listed. Use this feature if you need to select old-style X11 bitmap fonts.
The Preview window shows a sample of text in the selected font.


Changing Preferences.

Since there is no accounting for tastes, Adie can be extensively configured by means of the Preferences dialog. The Preferences dialog is comprised of a number of subpanes which allow you to change colors, editor modes, file patterns, and word delimiters.


Changing Colors.

The colors subpane allows you to change the colors used in the File/Directory browser, and the Text Window.
You can simply drag colors from one color well to another, or you can double-click on a color well and bring up the Color Dialog.
The Color Dialog offers a number of ways to create a new color, either by selecting one of the pre-defined color wells, by mixing a custom color in RGB, HSV, or CMYK color space, or by selecting a named color from a list.


Changing Editor Settings.

The editor subpane is used to change various modes of the editor:

Word Wrapping.  This enables word wrapping mode for the Text Window; when word wrapping is turned on, text flowed to stay within the wrap margins.

Fixed Wrap Margin.  When this feature is enabled, the text is flowed to stay within a fixed wrap column; when disabled, the Text Window is in continuous wrapping mode, and the text is flowed to fit the size of the Text Window.  This option has no effect if the Word Wrapping option is off.

Wrap Margin.  This specifies the column at which paragraphs are to be wrapped; the wrap margin only has effect if the fixed wrap margin option is selected.

Tab Columns.  This specifies the tab spacing, in terms of spaces.

Strip Carriage Returns.  When this option is selected, MS-Windows/MS-DOS text files with lines ending in CRLF are transformed into LF only files upon read; this is mostly of interest when loading DOS files on a UNIX system; when Adie runs under MS-Windows, files are normally automatically translated back and forth.

Strip Trailing Spaces.  When selected, Adie will remove all white-space after the last printable character when reading a file.

Auto Indent.  This causes spaces or tabs to be inserted to match the previous line; this option is meant for programmers.

Brace Match Time.  When entering a brace, parenthesis, or bracket, the cursor temporarily jumps to the matching brace and pauses there for a bit before hopping back to the insert position.  If the brace match time is set to 0, then this feature is disabled.

Insert Tab Characters.  When this option is selected, hard tab characters are inserted when entering the tab key.  If the option is not selected then entering the tab key will insert the corresponding number of spaces into the text buffer.

Mouse Wheel Lines.  This is the number of lines scrolled when the mouse wheel is rotated by one notch.  When holding the control key while using the wheel, the text scrolls by one page at a time; when holding the alt key, it scrolls one pixel at a time.

Save View of File.  When this option is selected, the current view or scroll position is saved so that a subsequent visit to this file can immediately jump back to the same view.
Disabling this option will cause all remembered views to be forgotten.

Save Bookmarks.  When selected, all currently set bookmarks will be saved for this file; a subsequent visit to this file will restore the bookmarks.
Disabling this option will cause all remembered bookmarks to be forgotten.


Changing File Patterns.

This subpane allows you to enter a list of file patterns, one pattern on each line. These patterns are used in the File/Directory browser and the File Dialog.  They are especially useful in the File/Directory browser as it allows you to cause the File/Directory browser to only show those file types you want to see (e.g. only source files).
Each line of a pattern has the format:

   patternname (patternlist)

Where patternname is the name of the pattern (e.g. "C Source") and the patternlist is a comma separated list of patterns (for example "*.h,*.c").
The patternname is optional.
Some examples from my own setup of Adie (you can paste these from this help window if you want) are shown below:

  All Files (*)
  All Source (*.cpp,*.cxx,*.cc,*.C,*.c,*.hpp,*.hxx,*.hh,*.H,*.h,*.y,*.l)
  C++ Source Files (*.cpp,*.cxx,*.cc,*.c,*.C)
  C++ Header Files (*.h,*.hpp,*.hxx,*.hh,*.H)
  C Source Files (*.c)
  C Header Files (*.h)
  Python Files (*.py)
  Perl Files (*.pl)
  Ruby Files (*.rb)
  Lex (*.l)
  Yacc (*.y)
  Object (*.o)
  X Pixmap (*.xpm)
  X Bitmap (*.xbm)

Some details on the allowable wild-card patterns:

  ?	Matches single character.
  *	Matches zero or more characters.
  [abc]	Matches a single character, which must be a, b, or c.
  [^abc]	Matches a single character, which must be anything other than a, b, or c.
  [!abc]	Ditto.
  [a-zA-Z]	Matches single character, which must be one of a-z or A-Z.
  [^a-zA-Z]	Matches single character, which must be anything other than a-z or A-Z.
  [!a-zA-Z]	Ditto.
  pat1|pat2	Matches either pat1 or pat2.
  pat1,pat2	Ditto.
  (pat1|pat2)	Matches either pat1 or pat2; patterns may be nested.
  (pat1,pat2)	Ditto.


Changing Delimiters.

Different programming language have different notions about identifiers.  Adie accomodates for this by allowing you to specify which characters (besides white space, of course) are used to delimit identifiers or tokens in the programming language. The default set of delimiters is "!"#$%&'()*+,-./:;<=>?@[\]^`{|}~".


Syntax Coloring Text.

Syntax highlighting colorizes source code based on recognizing certain patterns in the source files being edited.  For example, in C++ the keywords 'class' and 'while' may be given a different color from normal text. When syntax highlighting is enabled, the Adie editor will evaluate the color of each piece of text as you type it.  Thus, you'll have immediate feedback as misspellings of keywords will be instantly obvious.
Coloring the syntactical elements is only performed if syntax coloring is turned on, and a particular language syntax has been selected for the file.
Colors may be assigned by the user using the 'Preferences' dialog, using the 'Styles' subpanel.  Each particular syntactical element may be given a different foreground color and background color.  Separate colors are available for when a syntactial element is highlighted, selected, or is the currently active cursor line.
Apart from coloring, it is also possible to emphasize a syntactical element with underlines, strikeouts, or bold-face.  These effects may be selected by checking the underline, strikeout, or bold-face checkbuttons in the 'Styles' subpanel next to the style element.
Colors that are set to fully transparent (alpha = 0), will revert to the default text foreground and background colors.  Most users will probably prefer not to set the background colors but only foreground colors, making it easier to keep background colors consistent among the different syntactical elements.

Language Matching.

The set of patterns to be recognized in a piece of text are determined by the programming language syntax currently in effect for the text window.  The editor has several ways to determine which language is to be used for colorizing the text:

The first method is to look at the file's file-extension.  For example, a file extension '.py' will select the Python programming language. Each language syntax definition has a wildcard pattern which is matched against incoming filename, to determine if that langauge should be used for colorizing the file.

The second method is to look at a file's contents.  For example, when the string '#!/bin/bash' is spotted at the top of a file, the 'Shell' language is automatically selected.  This is a very useful method since shell scripts very often don't have a particular file extension.

The third method is to scan the top or bottom of the file for a so-called 'modeline'.  Adie currently supports vi, emacs, and its own modeline syntax.  The modeline is typically embedded in a comment-section at the top or at the end of the source text, and may contain other specifications like tab settings and other hints for editing.

The final method is for the user to simply enforce the programming language syntax, by selecting the proper language syntax from the menu. Adie will write this association to the registry, so when the same file will get loaded in the future, the same language will be automatically selected. If this method is used, the entire filename is used as the key to determine the language syntax, and this will be remembered in the registry setting from them on.
You can remove this association by explicitly selecting the "Plain" language mode while editing the file.


Writing Custom Syntax Files.

The syntax highlighting patterns in Adie are fully extensible, simply by writing you own language specification, or modifying one of the existing language specifications in the 'Adie.stx' file delivered with the software.
In order to get started on writing custom syntax patterns, it will be necessary to develop a basic understanding of how the syntax highlighting in Adie actually works.
Consider the following simple language definition (this is actually the language definition of the language specification file itself!):

  # Adie editor syntax-file syntax coloring
  language "Adie Syntax"
    filesmatch "*.stx"
    contextlines 1
    rule "Comment"
      openpattern     "#"
      closepattern    "$"
      style           "darkgreen"
    end
    rule "Keyword"
      pattern         "\<(language|filesmatch|contentsmatch|delimiters|contextlines|contextchars|rule|group|end|pattern|openpattern|closepattern|stoppattern|style|autoindent|wrapwidth|tabwidth|wordwrap|expandtabs)\>"
      style           "red"
    end
    rule "String"
      openpattern     "\""
      closepattern    "\""
      stoppattern     "$"
      style           "blue"
      rule "Escape"
        pattern       "\\\""
        style         "red"
      end
    end
  end

The first line of this language specification is a comment line.  Comment lines start with '#' and extend to the end of the line.  You can place comments anywhere on a line, but all text after the '#' becomes part of the comment up to the end of the line. The section between 'language' and 'end' is the actual language specification.  Each language specification must have a unique name, to distinguish it from other language specifications.  A language specification contains a number of language-specific parameters, followed by a number of syntax rules.

The first 'filesmatch' statement specifies the wildcard expressions that the filename should be matched against to identify this language as the one to be used for syntax coloring this file.  In this case, any file ending in '.stx' will use this language syntax.

The statement 'contextlines' specifies how many lines to go backward and forward relative to a change in the text, in order to pick up an incremental recoloring of the text after a modification.  The larger this number is, the more time it takes to recolor. If developing a completely new language specification, its suggested to leave this set as 1 and increase it until there are no more errors recolorizing large documents.

The syntax rules specify what patterns are matched and how to highlight/color them. As can be seen from the language specification above, syntax rules may contain other subrules.  This works as you expect: the nested rules colorize fragments of text found within the outer rules.
Each rule must have a name.  Rule names are used to assign colors, and so its OK to have different rules be given the same name, if they're to have the same color.

There are five types of rules:

 1. Simple rule. Simple rules match only a single regular expression 'pattern'.
 2. Bracket rule. Bracket rules match an 'openpattern' and 'closepattern'.
 3. Safe bracket rule. A bracket rule with an additional 'stoppattern'.
 4. Span rule. Match subrules inside a single over-arching pattern.
 5. Default rule. A rule that matches all text and has no patterns.

Except for the simple rule, the other rules may have subrules to colorize specific areas within the scope of that rule.  For example, inside the rule "String" above, which colors text blue, rule "Escape" matches escape sequences and colors them red. [An important detail is that the subrule patterns are matched before the closing rule of the outer rule, thus an escape like '\"' will prevent the outer rule from seeing the '"' as the end of the string.

Within each rule, the optional 'style' keyword can be used to specify an initial color to be used for the text highlighted by that rule.

The full list of keywords in the language specification is below:

language "name" ... end

The block between 'language' and 'end' describes one particular progamming language syntax.  Names must be unique.

filesmatch "wildcard"

This describes the wildcard pattern (see file patterns) used to matched against filenames or file extensions.  If there's a match, the language syntax will be used to higlight the file.

contentsmatch "regular-expression"

This sets the regular expression (see regular expressions) used to search the contents of the a small fragment of the file.  If the pattern is found, the language syntax fill be used to highlight the file.

delimiters "string"

Sets the delimiters and punctuation characters considered to be not part of a word in the language.  This affects next word, previous word cursor navigation commands.

contextlines <number>

Sets the number of lines to search around after a change in text to pick up incremental highlighting.  Set to 1 for many programming language but could be set based on largest syntactical element likely to be encountered.

contextchars <number>

Set the number of characters to search around after a change in text. Similar to 'contextlines' above.

autoindent yes | no

Set the auto indent feature for the language.  If set, the next new line after the current line will be indented at the same level as the current line by inserting spaces or tabs.  If no autoindent value is specified in the syntax description, the default value will be in effect.

wrapwidth <number>

Set the number of columns to wrap text at, if text is to be wrapped.  The special value 0 wraps the text at the window-edge.  If no value is specified, the default value will be in effect for this language.

tabwidth <number>

Set the number of columns a tab character indents with.  Typical value is 8.  If no value is specified, the default value will be in effect for this language.

wordwrap yes | no

Enables wrapping of long lines.  Lines will be broken at whitespace, if possible, to keep within the number of columns specified by 'wrapwidth' parameter, or the window edge if 'wrapwidth' was set to 0.  If no value is specified, the default value will be in effect for this language.

expandtabs yes | no

Enables tab expansion into spaces.  The number of spaces tabs expand into is set with 'tabwidth' parameter.  If no value is specified, the default value will be in effect for this language.

group "groupname"

Specifies this language is part of language group "groupname".  If specified, the language color scheme is consolidated on a per-group, rather than a per-language basis.  For example, group "C-Like" comprises various programming languages with similar syntactical elements.  Settings of a color scheme for one language will then be applied to all languages in the group.  For this to work, rule names must match; rule "Comment" in the Java language specification will have the same coloring as rule "Comment" in C or C++ language specification.  This can be a real time-saver as it allows you to set colors for many languages
in a consistent and succinct manner.

rule "name" ... end

Specifies a new language rule.  Within a rule, the following keywords may be used.

style "colorname"

This will give text colored by the rule a color, unless specified from the registry.  It is chiefly to ensure some highlighting is performed prior to customizing the color scheme.
Colors can be specified by name, for example "Aquamarine", or as a number hexadecimal digits, like #FF0000 (which yields a pure red).

pattern "regular-expression"

This sets the pattern this rule is to match against the text.  All text captured by the match will be colored by the colors associated with rule name. If quotes ('"') are to be matched, make sure to escape them as '\"'. Only quotes ('"') need to be escaped for the syntax parser itself.

openpattern "regular-expression"
closepattern "regular-expression"
stoppattern "regular-expression"

This sets regular expression patterns for bracket and safe-bracket rules. A bracket rule matches text against the regular expression specified by 'openpattern' and then colors all text subsequently until the place where the regular expression specified by 'closepattern' is found.  If 'stoppattern' is specified and encountered before the close pattern, the rule breaks out early.  This is handy for rules which may match huge quantities of text while the user hasn't finished typing, for example open-ended strings or multi-line comments.
Note that subrules, if any, are matched first before attempting close pattern or stop pattern.


Finding the Syntax File.

When Adie starts up, it normally looks in the directories listed in the PATH environment variable.  There are installations where this is not convenient.  Therefore, it is possible to set the search directories using the special 'syntaxpath' registry setting.
For testing purposes, you can also pass the filename of the syntax file directly on the command line using '-S' or '--syntax' flag.


Other Configuration Issues.

Because Adie is an editor written to use the FOX Toolkit, there are various other items, common to all FOX Toolkit programs, which may be configured either by hand or using some other control panel.
A few items of particular interest are list below:

  [SETTINGS]
  typingspeed=800
  clickspeed=400000000
  scrollspeed=80000000
  scrolldelay=600000000
  blinkspeed=500000000
  animspeed=20000000
  menupause=400000000
  tippause=800000000
  tiptime=2000000000
  dragdelta=6
  wheellines=10
  bordercolor=black
  basecolor=AntiqueWhite3
  hilitecolor=AntiqueWhite
  shadowcolor=AntiqueWhite4
  backcolor=AntiqueWhite1
  forecolor=black
  selforecolor=AntiqueWhite
  selbackcolor=#aea395
  tipforecolor=yellow
  tipbackcolor=black
  normalfont="[lucidatypewriter] 90 700 1 1 0 1"
  iconpath = /usr/share/icons:/home/jeroen/icons

These settings can be either placed in $HOME/.foxrc (and thus affect all FOX programs), or in $HOME/.foxrc/FoxTest/Adie (only applying to Adie).
File types may be bound to a command, mime-type, and icons using statements like the one below:

  [FILETYPES]
  cpp = "/usr/local/bin/adie %s &;C++ Source File;c_src.xpm;mini/c_src.xpm"
  /home/jeroen = ";Home Directory;home.xpm;mini/home.xpm;application/x-folder"
  defaultfilebinding = "/usr/local/bin/adie %s &;Document;document.xpm;mini/document.xpm"
  defaultexecbinding = ";Application;exec.xpm;mini/exec.xpm;application/x-executable-file"
  defaultdirbinding = ";Folder;folder.xpm;mini/folder.xpm;application/x-folder"

This example shows how the extension ".cpp" is bound to the program "adie" and is associated with two icons, a big icon "c_src.xpm" and a small icon "mini/c_src.xpm", which are to be found in the directories determined by 'iconpath", in this case, "/usr/share/icons" or "/home/jeroen/icons".

It also binds two icons "home.xpm" and "mini/home.xpm" to the home directory "/home/jeroen".

Finally, it assigns icons, commands, and mime-types to unbound documents, executables, and directories, overriding the built-in icons of the FOX Toolkit.
