| Edita |
A free open source programmers editor / text-based IDE for the Euphoria programming language.
This is the first draft of this reference manual. Some items are missing. If you see the word DEV it indicates something I intend to amend shortly.
Edita is designed to be easy, and where possible intuitive and natural to use. It does however contain some advanced features that are not immediately obvious. This document contains a detailed and occasionally quite technical description of all the features of Edita. It is not necessary to read and digest all or indeed even any of this to begin using Edita. This document is meant to be referred to when needed, rather than read like a book.
The windows installers for the "full" and "plus" packages are both a single windows executable which defaults to installing in C:\Program Files\Edita and requires only two clicks on the Next buttons to do so.
Later versions of the software can be installed directly over the previous version and in fact doing so is recommended. As usual making a backup first is advised, and it is probably not wise to reinstall while still actually running the program ;-)).
The installation process does not create any shortcuts, program groups, or registry entries. There is no uninstall process other than deleting the Edita folder manually. If needed, shortcuts can be created in the usual manner by dragging the edita.exe file from Windows Explorer onto the start button or the windows desktop (and obviously they should be manually deleted should you later choose to uninstall Edita).
Once installed, Edita can be run by clicking on C:\Program Files\Edita\edita.exe, or from source by "exw edita.exw".
Other distribution options (eg the source) may require separate installation of Euphoria and the use of a suitable archive extractor such as WinZip, unless installing on Windows XP which has the needed archive handling built-in.
The New option from the File menu defaults the directory from the current active file tab whereas the New option on the menu raised when right clicking on a file tab defaults the directory from that file. (This directory only becomes relevant when later attempting to save the file.)
The Open option from the File menu defaults (ie starts the open dialogue window in) the directory from the current active file tab whereas the Open option on the menu raised when right clicking on a file tab defaults the directory from that file.
If the "Permanent Fold Margin" is not set (see Display Options), then when the first bookmark (or fold) is created, all text is moved right one column to make way for the indicator. Likewise, when the last bookmark (or fold) is removed (and said option is not checked), this margin is removed and all text moves left one column.
A bookmark can be removed by pressing Ctrl F2 again, when the cursor is on the
bookmarked line.
Ctrl Shift F2 removes all bookmarks.
F2 jumps to the next bookmark, if any, while Shift F2 jumps to the previous. Neither F2 nor Shift F2 "wrap" round the start/end of file. If there is demand, an option to enable such wrapping will be added.
The true indicator of a bookmark is the yellow colour rather than an asterisk, as we shall see when Code Folding is discussed below.
Note that Undo/Redo (Ctrl Z and Ctrl Y) have no effect on bookmark settings, apart from the obvious fact that if the line of code a bookmark applies to is removed, then so too is the bookmark.
Bookmarks are saved between sessions, unless the file is externally modified (in which case the message "error loading fold record" may be displayed).
Upper. CONVERTS TO UPPER CASE.
Lower. converts to lower case.
Capitalise. Capitalises Each Word.
Sentence. Converts to sentence case. Does not understand things like proper
nouns and acronyms, some touch-up is usually required.
Cut append deletes the selected text and adds it to the end of the windows clipboard. Keyboard equivalent: Ctrl Shift X
Cut prepend deletes the selected text and adds it to the start of the windows clipboard. Keyboard equivalent: Alt Shift X
Copy places the selected text on the windows clipboard, replacing the previous contents of the clipboard, if any. Keyboard equivalent: Ctrl C
Copy append adds the selected text to the end of the windows clipboard. Keyboard equivalent: Ctrl Shift C
Copy prepend adds the selected text to the start of the windows clipboard. Keyboard equivalent: Alt Shift C
Paste inserts the contents of the windows clipboard at the current cursor position. Keyboard equivalent: Ctrl V
Jumps forward around a control structure (eg if -> elsif -> else -> end if -> if...)
If the cursor is on or immediately to the right of a bracket then the cursor moves to the corresponding open/close bracket, if one can be found. (If the cursor is between two bracket characters, the match for the one on the right is found.) Otherwise, the cursor moves to the open/closing/next control flow statement corresponding to the one under the cursor, or at the start of the line, if there is one. Control flow statements are: [global|end] procedure, function, type, [end] if, for, while, elsif, and else.
In the case of if/elsif/else/endif, Ctrl ']' (and Ctrl Shift ']') move forwards to the end if, and then back to the if, Ctrl '[' (and Ctrl Shift '[') move back. In other cases, Ctrl '[' and Ctrl ']' effectively behave the same.
If the Shift key is down, then block selection occurs. This makes it easy to block an entire routine or control structure: place the cursor at the start of line where the routine or control structure starts and press Ctrl Shift '['. It may be necessary to press Shift Home or Shift End to include leading spaces or trailing comments, before cutting or copying the text.
Note that when matching brackets, the trailing bracket is consistently not part of any blocked text, whereas the opening bracket may or may not be. Additional keystrokes such as Shift left- or right-arrow, or even Escape (to cancel the selection), Ctrl Shift '[' (to re-block starting from the other end) and then Shift left/right, may be required. All text between two brackets can be selected by starting with the cursor just to the right of the opening bracket, unless there is a bracket immediately after it (in which case the text is blocked to the closing bracket for the one on the right). Pressing Ctrl Shift '[' usually makes it much easier to see the text between matching brackets, even if you have no intention of copying or cutting the text.
Lastly, note that this block matching assumes the source compiles cleanly; it will happily match up an end for statement with a while or if statement if an end while or end if is missing, however it will issue a warning if the "jumpto" and the initial position are a mismatch. It should be possible to use this feature on incomplete code, hence if there is a bracket or control structure mismatch before the [valid] code actually being edited, it should not interfere.
If no suitable matching start/end can be found, then nothing happens.
If the "Permanent Fold Margin" is not set (see Display Options), then when the first fold (or bookmark) is created, all text is moved right one column to make way for the indicator. Likewise, when the last fold (or bookmark) is removed (and said option is not checked), this margin is removed and all text moves left one column.
Folds can be removed by moving the cursor onto them and pressing Ctrl + or by clicking on the '>' in the fold margin. Folds can also be created by clicking on the fold margin (if it is visible) next to a routine, if, for, or while block.
Undo/Redo (Ctrl Z and Ctrl Y) have no effect on (recent) code folds, with the exception that if lines within a fold are altered, the fold is removed.
aside: When folding a block of selected text, if the caret is technically on (say) the line following an 'end function' but in column 1, so no characters are selected, the block is 'trimmed' to exclude the trailing (blank) line, and similarly a blank line at the start of the block which is technically part of the selection, but does not stand out as such, is also trimmed, and is not deemed part of the block to be folded. This makes it more intuitive to use and reduces (but does not completely eliminate) the chance of folded blocks appearing as "> ".
If there is no current selection (or it does not span multiple lines after being trimmed), then Ctrl [ matching is used to determine what, if anything, should be folded. For example (line numbers added for clarity):
6 7 global procedure saveX(integer X) 8 if X > lastX then 9 LastXmove=+1 10 elsif X < lastX then 11 lastXmove=-1 12 end if 13 lastX=X 14 end procedure 15If the cursor is on line 7, and Ctrl - is keyed, then Ctrl [ matches with the 'end procedure' on line 14 (but see gotcha below), giving:
6 7 >global procedure saveX(integer X) 15The fold can be removed by pressing Ctrl + or clicking on the '>'
If line 7 is already (or is later) bookmarked, as well as folded, then a yellow > is shown in column 1. Thus the true indicator of a fold is the > character, rather than the blue colour, ie the opposite of the true indicator of a bookmark (which is the yellow colour rather than an asterisk). (If there is demand, an option to specify some other colour than blue for folds will be added.)
If the cursor is on say the 'v' of saveX, then Ctrl [ does not match anything, in which case Ctrl [ matching is re-attempted from column 1 of the current line. If the cursor is on either '(' or ')', then Ctrl [ matches the other, on the same line, (such bracket matching will be more useful, for example, when editing C code) and again a second attempt at matching occurs from column 1. However, there is a 'gotcha' as mentioned above; suppose you have:
7 global function create(integer objType, -- eg Window, TabItem, etc
8 object label, -- eg "Main Window"
9 object hBitmap,-- from loadBitmap, loadIcon, or 0
10 atom pID, -- parent-id, or 0
11 atom x, -- x coord (relative to parent-id)
12 atom y, -- y coord (relative to parent-id)
13 atom nWidth, -- width in pixels
14 atom nHeight, -- height in pixels
15 object style) -- 0, WS_xxx, or {WS_xxx,WS_EX_xxx}
16 -- some code
...
73 end function
74
Then pressing Ctrl - when the cursor is on the '(' of line 7, [or the ')' on
line 15,] folds that particular block:
7 >global function create(integer objType, -- eg Window, TabItem, etc 16 -- some code ... 73 end function 74In particular, if you have just searched for 'create', then that word will be block selected, effectively leaving the cursor on the '('. It is of course a simple matter to press Ctrl - to remove the fold, and then press Home, and Ctrl - again, (or press Home initially) to fold away the entire routine:
7 >global function create(integer objType, -- eg Window, TabItem, etc 74Hence this is not considered a problem as such, just slightly unexpected behaviour in certain circumstances.
Going back to the first example, if the cursor is on the 'end if' on line 12, then lines 8 to 12 are folded (if it was on the if only the first branch would be folded):
6 7 global procedure saveX(integer X) 8 > if X > lastX then 13 lastX=X 14 end procedure 15Folds may also be nested, so after folding the if block as above, the procedure can also be folded. When the procedure is unfolded, the if block remains folded. However it is not possible for more than one fold to either begin or end on the same line, nor are overlapping folds permitted. Should this be detected, the existing fold is automatically expanded before creating the new fold.
In the example above, the search for 'end procedure' scans through the if fold, if you see what I mean - internally it scans every line, before, in, and after any fold in its search. If the first/matching 'end procedure' was inside an existing fold, then that fold would be removed automatically before the routine fold occured.
Note that code folds (assuming there is no multi-line block selection at the time) do not occur in much the same conditions that Ctrl [ does not find a match. Also, folds created on if, elsif, and else statements fold just that branch, whereas folds created on end if statements fold the entire construct.
Largely because of the ability to hide away any set of lines (comments, variable definitions, etc), Edita does not, unlike some other folding editors, attempt to display initial '-' indicators for available folds. (Not least of all because for an N line source, there are about (N^2)/2 possible folds, eg ~600 million for win32lib.ew)
Folds are saved between sessions, unless the file is externally modified (in which case the message "error loading fold record" may be displayed).
A bookmark entry may become a both bookmark and fold entry by the obvious method of setting bit #02 and filling in the end value; that in turn can be made into a fold-only entry by clearing bit #01 from the type (etc).
Unused entries (ie with type of #00) are removed from the list.
A copy of this (combined bookmarks and folds) list is saved in edita.edb, table folds, along with copies of the start/end line texts. When the file is next opened, these saved lines are compared against the text just loaded (ignoring space/tab differences) to make sure the file has not been altered externally. Additional tests are performed to guard against corruption ("error loading fold record", "error saving fold record").
The complication this introduces (to 0.2.1) is that all line adjustments must be performed by a complex routine which scans up/down the set of folds. This is almost completely embodied within the new routine adjustLine(). Other relevant routines are getScreenLine and ensureVisible, and paintLine and paintLines have been changed to use absolute line numbers (rather than offsets from TopLine <= 0.2.1)
There are also a large number of places where non-intuitive changes were needed, for example in VK_LEFT processing:
CursorX = ExpLength(filetext[currfile][CursorY])became
CursorX = ExpLength(filetext[currfile][adjustLine(CursorY,-1)+1])Explanation: CursorY is 0-based, so the original line set CursorX to the end of the previous line (with the stress being on the word previous there). In the new code I had to adjustLine (to move from the line just past the end of a fold to the start of the fold) before adding 1 to the 0-based result to index properly.
It strikes me that this array could also hold wordwrap entries, which are the logical opposite of folds in that there are additional lines shown which do not actually exist, as opposed to existing lines which are not actually shown. I have not thought too deeply about this one, but it is clear that what you want are entries along the lines of 'The last time I looked at line 387, it took me 6 physical lines to display it.' That also matches the general rule of thumb that any change to line 387 might need all 6 lines to be redisplayed (and carry on to the end of screen should the 6 change).
Alt + and Alt - are implemented entirely in setFolds() in edita.exw.
The shroud option has recently changed significantly:
The clear (2.4) and debug (2.5) option should normally be checked (and are by default), since doing so makes bug reports far easier to follow. Theoretically it might be slightly easier to recreate a viable source from a bound application with this option set but I would not consider that a significant risk (apart from 2.4 shroud which as mentioned is human-readable). However you should check that any ex.err file produced does not contain any sensitive information in an overly blatent form such as "password = blahblahblah". If that is the case, either replace the password variable with something less obvious, which is effectively what will happen when clear/debug is not set, or (better) discard or encrypt any sensitive information asap, for example leaving the ex.err with "password = {247998365,-16,202048,12}", which your program can still use but anyone else reading the ex.err file cannot.
The list option is of relatively limited practical use. It creates a file named deleted.txt which you can examine and judge for yourself.
I do not and have never used either the quiet or console options. You can find more information about these in %EUDIR%/doc/bind.doc.
It is possible to edit, or copy the command text to the clipboard for later pasting into a batch file.
This program also demonstrates how to write a built-in interface to an external command-line program. If you want to invoke eg WATCOM from Edita, please examine the source file eabind.ew.
Files ending in "htm", "html", and "bat" are executed using the "open" command of ShellExecute (in shell32.dll).
If you experience any problems please try the Parameterised Run option (see below)
Edita monitors any programs it has launched, testing for failure and opening the ex.err file if it has changed and the option to do so is set.
Edita also invokes SetForegroundWindow when it detects a program it launched has terminated, if it is the last program lauched by Edita which is still running. Focus will not automatically return to Edita when one or more programs launched from it are still running. This is deliberate; the include file eama.ew allows an application to close any existing instance of itself (provided it is a windows app), which can be quite helpful, for instance to close a database which is normally opened exclusively by the application you are running/testing. In such cases, focus should remain with the second application: Edita should not, after detecting the termination of the first, automatically steal focus from the instance still running/just launched. In most cases it does tend to get focus, just noting that there are some cases it deliberately does not.
Pressing Ctrl F5 opens a simple dialogue allowing the command line to be edited.
Previously run commands may be selected from the drop-down list.
Checking the "Capture Console Output" option forces the use of exwc to run the program (and hence a DOS box is always displayed). If possible, the application should invoke flush(1) after each puts, print, or printf, to cause the message to appear immediately, otherwise messages (including those before a getc) may be buffered until the application terminates, so the program may appear to have 'died' when in fact it is waiting for input.
The use of eamsg() (defined in eama.ew) instead of "Capture Console Output" is recommended for GUI programs.
Shift F5 uses the details last entered on this screen (even when a different file is open).
Line 1 of an ex.err can almost always be successfully analysed, as can call stack entries (those beginning "... called from"), some Warning messages, and lines in the "Traced lines leading up to the failure:" section.
It is also possible to jump to the appropriate line from an ex.err file by double clicking on a suitable line (ie one containg a filename and line number).
The 'source' file is shown in the window title. The directory and filename of the file to compare against default to the same, however a comparison is not valid until at least one of them is changed. Previous directories that files have been compared against (this editing session) can be selected from a drop down list. Files in the directory shown can be selected via the browse button. Note that clicking on a file tab, behind the compare window (moving it if necessary), automatically sets the directory/filename to compare against. This is particularly useful when a recovering a backup.
The option to ignore whitespace should be left checked, to avoid false differences being reported between spaces and tabs.
The Overwrite option causes the comparison results to be written over the current filetab, which is obviously slightly dangerous, but any mishap can almost always be quite easily recovered. In fairness, this option is much more relevant to Directory Compare (see below). If not checked, the output is placed in a new "[untitled]" file tab.
The Rename option is a little out-of-date, see Directory Compare below for further discussion.
Once a different directory/file has been selected, the default switches from the Browse button to the Compare button. Pressing the latter produces a text file which lists all unchanged files as normal, deleted lines prefixed with a '<', and inserted lines with a '>'. Each difference can be found in turn by pressing F4.
Technical note: The core of file compare is truly excellent (all credit due to Wu, Manber and Myers) however gathering the needed "stack of change points" is possibly subject to significant improvement. In eaplan9.e, if the variable stack were to be removed, the program would be nothing less than amazingly, astoundingly, and astonishingly fast, (not that you can really check that if it does not return a verifiable result,) as opposed to the 'normally bearable' performance now. In truth, it works, and it works pretty darn well, even if I have to say so myself, but I do want to point out that particular source (less than 100 lines if you exclude comments) to as many eyes as possible, for any sensible suggestions.
The first point to note here is the window title (quite obviously this is the same program as used for individual file compare, and quite obviously that is so for good reason). It starts with the word 'Directory' and shows a directory, not a file. The second point to note is that the Filename is now a progress indicator, not an input field.
The third thing is to discuss the rationale behind this. I distribute the full source of Edita. You make some changes. Now, do I want:
If you finish something, I want to be able to test it without running into problems caused by the incomplete mods I am working on (in which case I am unlikely to apply it immediately, but I can reply straight away that "it looks good"), and without running into any incompatibilities I have introduced in the meantime. Applying changes is nowhere near as easy as applying a unix-style diff, but this utility is designed to make it reasonably straightforward.
What this program does is take two directories and compares filename-for-filename in each. After comparing two files, it Renames the second directory by decrementing the extension, eg fred.exw becomes fred.dxw. As it stands, directory compare simply does not work unless Rename is checked, but I will admit that this is not exactly an ideal solution. I do plan to remove the Rename checkbox, and save a list of files already compared, at least in memory if not also on disk, but almost certainly not this year, and probably not even in 2006.
If two files prove to be identical, they are easily skipped, otherwise the Overwrite option comes into its own. The assumption is made that before applying a set of changes from a second party, it is reasonable to assume some kind of backup has been created. It is fair to say that Directory Compare does not really deliver on its promise unless the Overwrite option is checked.
Assuming this, the programmer is expected to step through the changes made to each altered file using F4, and manually select the changes needed by hand. It is in fact a design decision that changes must be "approved" in this manner.
After accepting the changes to each file, Directory Compare should be run again, to find the next file which has been changed, until it reports that all files have been processed.
In summary, Directory Compare works well for small or frequent updates from a limited number of developers, with one person strictly in charge. However it has to be admitted it is not intended for huge developments with hundreds of concurrent developers. I have succesfully used this feature on numerous occasions with Edita and previously MEditor, applying sometimes quite involved modifications in a relatively short time (eg 20 mins), yet retaining a high confidence factor.
The search string defaults to the currently selected text, if any, providing it the selection does not span multiple lines.
An option to search based on the current project data may be added in a future release. Also an option to skip the backup directory. [DEV]
Comments, whitespace (but not line breaks), and ubiquitous lines (eg "end if") are skipped. Works on any text source and is reasonably fast, eg win32lib should complete in under a minute.
Example output:
>9093 9148 12471 13056 14310 + hWnd = getHandle( id )
9094 curStyle = w32Func( xGetWindowLong, { hWnd, GWL_STYLE })
>9095 9105 styleMask = xor_bits( #FFFFFFFF, style )
9096 | style = and_bits( styleMask ,curStyle )
9097 9107 9159 9168 if style != curStyle then
9098 9160 VOID = w32Func( xSetWindowLong,{ hWnd, GWL_STYLE, style })
Line 9093 matches more than 5 other lines so has a '+' in column 6.
The quick jump feature displays a list of Euphoria routines, or sections in other files. Selecting an entry jumps to the appropriate line. The drop-down list on the toolbar performs a similar function, less the All/Global/Section and Filter capability.
If the file extension is one of e, eu, ew, ex, exu, exw, or exwc, then the "All" radio is checked on entry, else the "Sections" radio is checked.
If applying the existing filter on entry results in an empty list, then the filter is cleared. This is likely to happen when switching between sources.
"All" lists procedures, functions, and types, whether they are local or global. The routine type keyword must be on the same line as the routine name.
"Global", fairly obviously, lists only those that are global. The global qualifier must be on the same line as the routine type and name. For example:
global procedure myproc()Will not be listed under either All or Global; although the Euphoria interpreter will ignore the linebreaks, Quick Jump will not.
"Sections" lists any line which is underlined with either dashes (--) or equal signs (==). If you want html sections to be listed, put "<!---->" or longer on the next line, starting in column 1. The actual test is whether characters 3 to 5 (with tabs being counted as one character) are either "---" or "===", and the previous line is not blank and does not start with "--", and does not contain "end function" or "end procedure". Note that "Sections" is not really intended for use on program source files, and although there is no rule against it, just don't expect it to be very useful on files like win32lib.ew.
If you want to create sections in a Euphoria source, the recommended pattern is:
-------------------------- -- Some comment --------------------------instead of:
-------------------------- -- Some other comment --------------------------Only "Some comment" appears, "Some other comment" does not.
To get rid of a section (eg "classBGColor[ MleText ] = w32NoColor -- COLOR_WINDOW" is underlined in win32lib & therefore shows up as a section), insert a blank line.
Ex.err files are handled specially, using the simple test that the third character is one of '.', '\'. or ':', and terminating when the line "Traced lines leading up to the failure:" is found. I would normally expect the "All" and "Global" radios on an ex.err file to give a blank window.
The recovery tab can be shown by selecting Tools/Recovery, or by displaying the File Panel (Ctrl L) and selecting the Recovery tab.
Alphabetic entries are shown for each directory, within that an alphabetic list of backed-up files, and within that a list of backups of that file, most recent first. The treeview is automatically expanded with focus on the most recent backup of the currently open file. If a file (say test.exw) was saved as above five times on December 17th 2005, at around 2:58pm, then the backup list would be:
5C171462.exw 5C171461.exw 5C171460.exw 5C171459.exw 5C171458.exwThe latest file is always listed first, even over a decade change. The 5 denotes 2005, the C denotes 12 (December), etc. Note that minutes may be artifically increased to ensure uniqueness. Selecting the first entry opens the file edita/backups/5C171462.exw, next to the current filetab.
To restore a backup in its entirety, right click on the edit area after opening the file and select Yes on the restore prompt which appears.
A new backup of the file (in the state that needed to be recovered from) will be made when a file restored in the above manner is subsequently saved.
A backup may also be opened solely for examination, to copy or restore only a selected portion, or for use with say file compare.
It is a simple matter to compare a restored file with the 'live' one: select Tools/Compare, then click on the 'other' file tab in the background (doing so updates the file compare window's directory and filename fields) and press the Compare button. Note: When used in that fashion, Overwrite and Rename should not be checked. The differences (if any) and all other lines are saved in a new [untitled] tab; press F4 to jump to the next inserted/deleted line. In general, a line beginning with '>' indicates an inserted line and '<' a deleted line, though it obviously depends heavily which way round they were compared, and/or it depends on whether you are thinking in terms of restoring the backup, or asking what has been done to the file since that backup was made.
It is of course generally unwise to open a backup file and start editing it; the backup directory is regularly purged and when that happens any work would be lost, plus it would be difficult to test any changes made to a backup file with these encoded names. Edita does not specifically guard against such behaviour, with the sole exception of the edit area menu being replaced by a restore prompt, no other warnings appear.
The Recovery tree also shows details for original files which no longer exist (as you would probably expect).
Auutomatic backups can be disabled in Edit Options, and can be automatically purged a set number of days after creation.
The program (vedb.exw) can also be run stand-alone. In this case, the first, second, and last phases are omitted.
For comparison purposes, here, on a slow machine checking a database covering 450-odd files over 50+ directories with about 1850 global routines, and if not finding anything much to be fixed, a full background scan takes approximately two minutes, the verification process completes in around ten seconds, apart from shutting down and restarting Edita, which may take longer than actually running the program. Removing details of a test copy of the Edita sources, that had been physically deleted prior to running the program, took about 90 seconds.
This option can be removed, as can all other menu entries, by changing the appropriate line in ealng_XX.txt to:
"Crash (?9/0)" = ""
There is however no mechanism as yet for preserving such changes when a new version of the software is installed.
Note that the extended text entries _F1HELP and _VEDB are skipped.
The function keys F6, F7, F8, and F9 are reserved for playing back previously recorded keystrokes. These keys should be thought of as "registers"; saving, loading, defaulting, copying/swapping and editing the settings for these keys is covered in the next section, Macro management. For the remainder of this section, all references to F8 imply the same for F6, F7, & F9.
The undo function (Ctrl Z) can be used if a macro does something undesired to the source file, though for a long macro you may need to key it several times.
Ctrl F8 begins recording a macro for the F8 key, discarding any previous keys.
If Ctrl F8 is pressed again, macro recording stops. Attempting to record a
second/different key while still recording the first gives an error message.
If F8 is pressed while recording, further recording stops, and the macro is
replayed immediately.
One macro can invoke another, but to avoid infinite
recursion, the function key invoked must be numerically lower than the one
currently being recorded. See also the Swap command in the next section.
If Shift F8 is pressed, any recording in progress stops, and the macro
management screen is shown (see next section).
Creating macros is definately a bit of an art form and requires some practice, but can make otherwise tedious jobs much quicker. Possibly the real trick is to take very special care over where the cursor ends up. One thing I should point out now is that if you are not well acquainted will all the keystrokes normally used to select text, jump to the next word, and so on, then the rest of this section will probably not make a great deal of sense to you. Most useful macros end with F3 (find next, if you needed to be told that I suggest you skip this section) or similar cursor movement.
First, a very simple example:
something, eg fred, something, eg fred, something, eg fred, something, eg fred, something, eg fred, something, eg fred, something, eg fred,(if you weren't quite so literal and got several lines of fred, that's OK too.)
For the next example, we have several nested if statements and we want to make it a bit clearer what each end if means, by converting:
if a=1 then if b=1 then end if end ifto:
if a=1 then if b=1 then end if -- b=1 end if -- a=1I suppose the first thing is to realise that this can be done in a purely mechanical fashion, by repeating the same set of keystrokes over and over.
The next task is to decide what would be a good thing to search for, and/or where would a good place to start and end each iteration. "then" is a good target in this case, much better than "if" which could make things confusing. (A target of "end if^p" is also a possibility and would allow a macro to be recorded which only applies to uncommented if statements, but I shall leave that as an exercise for the reader to figure out.)
We start by block selecting "then" (forwards, the way it would be blocked if we had just searched for it, rather than starting with the cursor to the right of the 'n' and blocking backwards to the 't').
Start recording by pressing Ctrl F8.
There is a handy little trick to starting a macro which really comes into
its own when it is replayed at a later date.
Press Ctrl F, Escape to "log" the search target ("then") against the macro.
Now press Ctrl Left (or the keys needed to get to the start or just before the search target) followed
by F3.
What this does is ensure the macro always starts on the desired
search key, without this, it is all to easy to load a macro and run it
without realising the cursor is in column 1.
Move the cursor to the end of the condition by pressing Ctrl Left, Left.
Block select to the start of the condition by pressing Shift Home, and Ctrl Shift Right twice, then press Ctrl C to copy it ("a=1").
Move back to the opening 'if' (any of Left, Ctrl Left, or Home will do), press Ctrl [ to locate the corresponding "end if", type " -- ", and then Ctrl V to paste ("a=1").
Now get back to the opening 'if' by pressing Home followed by Ctrl ], and move past the "then" we just processed by pressing End, or Downarrow.
Finally, key F3 to find the next "then" (which is still the default search target) and stop recording by pressing Ctrl F8.
You can now process subsequent (and nested) if statements in the same manner just by pressing F8. Note that this macro will not work properly on if statements whose condition spans multiple lines (not sure if that is possible, left as an excercise for the reader), plus it will find "then" inside comments, though you can press F8 on those it will work on and F3 to skip those it will not, which is a very common idiom when playing back macros.
I should probably note that Ctrl [ and Ctrl ] only work when editing files with the extensions specified in Euphoria.syn. I have also been quite speicific in the use of those keys to avoid any elsif/else lines.
As a final example, I often need to convert text such as:
dopts = create(Window, xl("Display Options"), 0,Main, 272,149,405,355,0)
showpth = create(CheckBox,xl("Show full path in title bar"),0,dopts, 15, 15,200,20,0)
toolbar = create(CheckBox,xl("Tool Bar"), 0,dopts, 15, 40,200,20,0)
tabbar = create(CheckBox,xl("Tab Bar"), 0,dopts, 15, 65,200,20,0)
mltabs = create(CheckBox,xl("Multiline Tabs"), 0,dopts, 30, 90,200,20,0)
sdtb = create(CheckBox,xl("Single Dir Tab Bar"), 0,dopts, 30,115,200,20,0)
hsb = create(CheckBox,xl("Horizontal Scroll Bar"), 0,dopts, 15,140,200,20,0)
vsb = create(CheckBox,xl("Vertical Scroll Bar"), 0,dopts, 15,165,200,20,0)
psb = create(CheckBox,xl("Permanent Scroll Bars"), 0,dopts, 15,190,200,20,0)
sbar = create(CheckBox,xl("Status Bar"), 0,dopts, 15,215,200,20,0)
pfm = create(CheckBox,xl("Permanent Fold Margin"), 0,dopts, 15,240,200,20,0)
to:
"Display Options" = "Display Options" "Show full path in title bar" = "Show full path in title bar" "Tool Bar" = "Tool Bar" "Tab Bar" = "Tab Bar" "Multiline Tabs" = "Multiline Tabs" "Single Dir Tab Bar" = "Single Dir Tab Bar" "Horizontal Scroll Bar" = "Horizontal Scroll Bar" "Vertical Scroll Bar" = "Vertical Scroll Bar" "Permanent Scroll Bars" = "Permanent Scroll Bars" "Status Bar" = "Status Bar" "Permanent Fold Margin" = "Permanent Fold Margin"(it happens to be something I often need to do to maintain ealng_en.txt)
The full text of a macro that will do just that is given in the next section.
Actions which are not [currently] supported in macros include:
Some of the options on the Find window may not work:
This window is displayed when Shift F8 (or F6, F7 or F9) is keyed. When a macro is recorded in F6..F9, it only exists in memory and is discarded at the end of the edit session; this window is the only way that permanent copies of macros can be made.
The current values of F6, F7, F8, and F9 are displayed, each with a check box against it. These boxes can be toggled by pressing the corresponding function key. Below this is a list of previously saved macros, and at the bottom are buttons labelled Load, Overwrite, Delete, Swap, and OK.
If one, and only one, of the checkboxes is ticked, and an entry in the listview is selected the Load and Overwrite buttons are enabled, though as shown above the Overwrite button is not enabled if the selected function key is empty. These buttons copy macro details from the permanent (listview) area to the "registers" F6..F9 (Load) and vice versa (Overwrite).
If exactly two of the checkboxes are ticked, the Swap button is enabled: The simplest way to prevent mutual recursion in macros (otherwise they would loop forever, or until they ran out of memory) is to prevent low number keys from calling higher numbered keys (or themselves):
---Can call--- Key F6 F7 F8 F9 F6 no no no no F7 yes no no no F8 yes yes no no F9 yes yes yes noThe Swap button allows keys to be reordered, ideally /before/ recording a macro which uses another. Nested macros are not used very often, one case might be that you already have a working macro, but also want to insert the current date and time above any line which is modified. You might therefore load the working macro into F6 (or swap it out of F9), and record in F7: {Home, Return, Uparrow, "-- PL 12/11/05", F3, F6}.
Note that infinite recursion is guarded against when the macro is run, rather than tested for here, and no attempt is made to update calls to a macro that moves keys; if you recorded an F6 it will playback an F6.
The Delete key is only enabled if an entry in the listview is selected, and none of the top four checkboxes are ticked. Deleted macros are lost forever; if you have any important macros, it may be wise to copy the text from the edit screen (described below) into a text file.
The registers F6..F9 can be edited by clicking on the text area to the right of the checkboxes. This is allowed even if the macro is empty, to allow, for example, a macro posted on a message board to be pasted into the editor. The listview items can be edited by double clicking on them.
The edit window (which can be resized) contains two multi-line edit text areas. The top box contains the name/description of the macro. As a general idea, this should be set to something like "cict - copy if condition text to end if statement. Does not work for multi-line conditionals. Must be loaded to F7 and blah to F6". Any text can be used, up to the standard edit box limit of 32K characters.
If the top box is left as, or set to, "F6" thru "F9", then on exit that key ("register") is updated, and any modifications are only kept in memory/ will be discarded at the end of the edit session. Any other value is added to/replaces (without warning) the corresponding entry in the list view and is saved to disk.
If the value in this top edit box begins with "F6", and is followed by some additional text (even if it is only ' '), then it is a possible default for the F6 key when Edita is next started. In practice, when more than one entry beginning with "F6" exists, the last (alphabetically) is used as the default. Similarly for names/descriptions beginning "F7" through "F9".
Note that if you edit the top box, eg to correct a spelling mistake, a new database entry will be created and you should manually delete the old one.
You can switch between the two edit boxes using Ctrl Tab.
Editing macro entries is a bit of a hit-and-miss affair; very little
assistance is given, and there is very little checking (as yet) that an
edited macro will not cause a crash.
"{MR_CHAR,{" (or "{1,{") indicates a graphic character,
"{MR_VIRT,{" (or "{2,{") a virtual (function) key, and
"{MR_FIND,{" (or "{3,{") a search target.
Keys are held internally using a much more purely numeric format, using the
standard windows keycodes, eg Uparrow is 38, F1 is 112. This is also true for
the macros table in edita.edb. Some keys always appear as numbers, eg Ctrl C
is shown as 3.
MR_CHAR and MR_VIRT are followed by {keycode, control, shift}, MR_FIND (which sets the default, a subsequent F3 is usually present to actually perform the search) is followed by the search target and some settings from the Find window. Multiple MR_CHAR entries are packed for ease of reading into a single string, but are stored as individual characters internally.
Usually the only things practical to edit are text strings, or, as mentioned, paste a complete macro. It is not the intention to make macros easy to edit, it is usually far easier to re-record them from scratch. Some blatent errors such as a missing closing bracket are caught, and an option is given to retry (ie resume editing) or cancel (ie discard the edit field contents).
Note that nested macro calls are just saved as normal function keys.
As promised, here is the text of the macro I use to maintain ealng_en.txt:
{{MR_FIND,{{"xl(",0,0,1,0}}}, {MR_VIRT,{VK_LEFT,1,0}}, {MR_VIRT,{VK_F3,0,0}},
{MR_VIRT,{VK_ESCAPE,0,0}}, {MR_VIRT,{VK_HOME,0,1}}, {MR_VIRT,{VK_DELETE,0,0}},
{MR_VIRT,{VK_RIGHT,0,1}}, {MR_VIRT,{VK_F3,1,1}}, {MR_VIRT,{VK_ESCAPE,0,0}},
{MR_VIRT,{VK_END,0,1}}, {MR_VIRT,{VK_DELETE,0,0}}, {MR_VIRT,{VK_HOME,0,1}},
{MR_CHAR,{3,1,0}}, {MR_VIRT,{VK_END,0,0}}, {MR_CHAR," = "},
{MR_CHAR,{22,1,0}}, {MR_FIND,{{"xl(",0,0,1,0}}},{MR_VIRT,{VK_F3,0,0}}}
Line 1 sets the search target, Ctrl Left, F3 (aka the 'handy little trick').If you want to test it, just copy and paste it into Macro management, and copy and paste the sample text given in the last section to try it out on.
Just in case, here is the complete text of the other macro I described above:
{{MR_FIND,{{"then",0,0,1,0}}}, {MR_VIRT,{VK_LEFT,1,0}}, {MR_VIRT,{VK_F3,0,0}},
{MR_VIRT,{VK_LEFT,1,0}}, {MR_VIRT,{VK_LEFT,0,0}}, {MR_VIRT,{VK_HOME,0,1}},
{MR_VIRT,{VK_RIGHT,1,1}}, {MR_VIRT,{VK_RIGHT,1,1}}, {MR_CHAR,{3,1,0}},
{MR_VIRT,{219,1,0}}, {MR_CHAR," -- "}, {MR_CHAR,{22,1,0}},
{MR_VIRT,{221,1,0}}, {MR_VIRT,{VK_END,0,0}}, {MR_VIRT,{VK_F3,0,0}}}
There are no plans to further enhance this feature, but you should feel free to modify eamacro.ew and/or eamncode.e yourself, if you so wish.
If at any point you are not sure whether macro recording is still active, press Alt Home (move to line 1 of screen) - the Note: Macro recording stopped message will appear if recording was still in progress.
Alternatively Shift F6..9 will stop any recording and open the management screen.
This option allows you to edit the colours for the selected syntax. All files ending with ".syn" in the syn subdirectory and loaded at startup, and each .syn file must specify at least one file extension. The syntax colouring is automatically selected by the file extension of the file currently being edited.
A column of radio buttons is displayed, with small colour swatches to the left displaying the current settings. The descriptions of some of the radio buttons are taken from the appropriate syn file. Below these are check boxes for bold and italic, and to the right is an edit box and a column of standard colours. At the bottom of the screen are three buttons labelled Custom, OK, and Cancel.
One of the radio buttons on the left must be selected before the bold, italic, edit box, standard colours, or Custom button are enabled. The radio buttons may be selected by clicking on either the sample patch or the radio button immediately to its right. Once this is done, the user may:
It is possible to have both the font and colour dialogs open simultaneously, which you might want to do because the bold and italic availability (as shown on the color screen) is dependent on the font selected.
The number of nested bracket colours required is specified in the appropriate syn, between 1 and 7 (or omit the Braces line for no bracket colouring).
The remaining radio buttons correspond to sections in the syn file. There is no theoretical limit to the number of sections that can be defined, however it can be difficult to select distinct colours if there are too many sections, and the colour dialogue is probably limited to around 18 colours, as any more and the window may not fit on the screen (depending on your screen settings).
Pressing the OK button closes the window and saves the settings to file. Pressing the Cancel button restores the settings to the state they were in when the dialog was opened, and closes the window.
Press OK to accept the colour changes (and rewrite the clr file) or cancel to close the dialog and return to the colour settings on entry.
It is wise to close and reopen the editor to ensure all changes have been properly saved before continuing. In some cases this may also free a small number of system resources.
The first four entries (SYSTEM_FIXED_FONT, ANSI_FIXED_FONT, OEM_FIXED_FONT, and DEVICE_DEFAULT_FONT) are "stock" fonts. You may not change the size of these fonts, however their equivalent will usually exist lower in the list, where it may be possible to change the size. For example, on my machine the following are equivalent:
SYSTEM_FIXED_FONT FixedSys 11 pt, ANSI_FIXED_FONT Courier 10 pt, OEM_FIXED_POINT Lucida Console 8 pt Bold[*], DEVICE_DEFAULT_FONT Courier New 12 pt.The main reason these fonts are listed at all is their guaranteed availability which makes them suitable for defaults when the editor is installed: a Russian version, say, of welcome.txt is unlikely to be readable in Courier New no matter what language you speak, but is far more likely to be readable if shown in whatever SYSTEM_FIXED_FONT is aliased to on a Russian machine.
There is little gain in using these builtin fonts over selecting any of the other fonts (it might save an insignificant few K of memory, or less). One downside to using stock fonts is that urls are not underlined.
Clicking on or cursoring to a face will update the text appearance in the main editor. Apart from the four entries listed above, the Size listbox will change to show the available sizes, with the closest available match to the last selected fontsize selected. Again, clicking on or cursoring to a different size updates the text in the main editor window.
True type fonts are shown with a default set of 16 popular sizes, however as these are scalable, many other sizes can be specified.
The size edit box is enabled for true type fonts only. If a new size is entered, it is automatically inserted in the list of available fonts, and applied immediately to the main editor display. The size is not recognised if it is not one of "1".."9", "10".."99", "1.1".."9.9", or "10.1".."99.9". Neither a trailing ".0" nor a leading "0" are accepted. As soon as a valid point size is entered, an appropriate entry is added to the list of font sizes and the editor text updated. When entering eg "35", a font of size 3 may be created and then a font of size 35. The unneeded font size 3 will not be recreated when the editor is exited and reloaded.
Alt-F sets the focus to the Face ListBox, and Alt_S sets the focus to the Size ListBox (rather than the EditBox above), which allows cursor up and down to be used to change the selection. In the case of Alt-S, this gives more consistent behaviour between True-Type and non-True-Type fonts for which the editbox is disabled.
Fractional point sizes are rounded to the nearest available size (as in fact are integral ones, since the concept of point size predates computers by several hundred years, and 1/72th of an inch is not exactly metric). Many sizes will appear identical, for example on this machine Courier New 9.1 to 9.6 are equivalent, as are 9.7 to 10.2. In general, it is only worth trying fractional sizes ending with ".5".
It is possible to have both the font and colour dialogs open simultaneously.
Press OK to close the font box and keep the selected font or cancel to return to the font which was in force when the font dialog was opened.
It is wise to close and reopen the editor to ensure all changes have been properly saved before continuing. In some cases this may also free a small number of system resources.
[*] This dialog does not permit selection of bold. Text attributes (ie bold and italics) may instead be associated with individual syntax elements via the Colour option.
The following options are self explanatory, and apply immediately so if in doubt just try checking and unchecking them:
crashpath = "D:\edita\"rather than the much more cryptic
crashpath = {68'D',58':',92'\',101'e',100'd',105'i',116't',97'a',92'\'}
The ex.err file itself is not modified, so if you need to see the other
view, simply toggle this setting and reload ex.err (by right clicking on
the file tab). Note that ex.err is created by the RDS Euphoria interpreter.
The numbering scheme allows up to 10,000 backups per day, per file extension, (reducing to 7640 per day if started just before midnight), and guarantees that backup names will not be duplicated over any 10-year period.
Automatic backups can be disabled by changing "Create backups automatically" in Edit Options. The number of days to retain backups can also be set there.
Unchecked, the backup directory will usually fill at a rate of say 25MB per week. (Though with this rather large html file, at some 230K, and being saved up to 20 times an hour, I am generating something nearer 130MB/week. [ OK, doing the maths suggests an average of 15 saves/hr, if I work a 40hr week :-P ])
Specifying a non-zero value for the number of days to retain backups causes the backups to be scanned once at the start of each editing session. Only the actual dates, not the times, are examined, so for example when set for 2 days and it is 11:35pm on the 21st, a file dated at 12:05am on the 19th will be left alone, despite it being about 2.98 days old.
The editor remains fully responsive while this scan occurs.
The number of days to retain backups is currently limited to 90 days. At this setting, the backup directory is likely to contain between 300MB and 1.6GB of data, and contain maybe as many as 8000 files, which will obviously impact on performance. Also, the 'year wrap' logic (see checkBackups() in eaedb.e) is nice and simple, but would fail to delete say December 2005 files sometime in January 2007, if the retention period was over 365 days. You can of course set the value to zero and manage this directory manually.
Also note that the file dates in the backups directory correspond to the date and time of the file about to be overwritten, not the date and time that the backup was physically created, for which the file name is a better indicator. Put another way, the automatic purge works from the file name, not the file date.
The [optional] File Panel on the left is currently showing the project tree, ie
all files included in the current project.
The right hand border can be dragged to resize the file panel.
At the bottom of the screen is the [optional] message area, here showing the
output of a console application.
The left border, top edge, or top left corner can be dragged to resize the
message area.
The main window shows one bookmark and two folded routines.
The source eama.ew includes routines for an application to send text directly to the message area directly, and is recommended for all GUI applications since it does not require that a console window appears.
This window appears if F1 is pressed when the cursor is over the word "length". In this case you can look at the official RDS Euphoria manual (providing it is installed in %EUDIR%/doc) by pressing Reference Manual, or press Keyboard Help for a quick reference listing all the shortcut keys supported, of which there are about 115. The Keyboard Help window also appears if the editor does not recognise the word under the cursor.
The above text (for the builtins, which otherwise do not have an "official" routine definition available) is stored in lang/ealng_en.exh. This, along with other standard includes and all [Euphoria] files in the current project are regularly (automatically) scanned, and help entries added for any global routine definitions found. If the word under the cursor is found other than in ealng_en.exh, and it is not a global definition in a standard include file, such as sort on line 6 of sort.e, the Reference Manual button is replaced with an Examine Code button which opens the source at the routine definition.
If you define a new global routine, Edita automatically creates a new help text entry for it shortly after the file is saved. The help window also shows details of routines defined locally in the file currently being edited.
If Edita does not recognise the surrounding function (which it always looks for first), it scans the current file looking for definitions/use of the word under the cursor. Note that this does not (yet) lookup global variables and constants. To recap, if you are on the word "True" on a line such as "if flag = True then", you will probably see something like "constant True = (1=1)" along with several other uses of it. However if the current line is "setVisible(XX,True)", then the help text for setVisible will always be shown. If in this case you really do want to lookup True, the easiest way is to block select it and press Ctrl F3, or perhaps to copy and paste it onto a new blank line before pressing F1.
If nothing else can be found (eg the cursor is on a blank line), then the keyboard help is shown.
| New | Cut | Undo | Run | Fonts | Background | |
| Open | Print preview | Copy | Redo | Show Formatting | Colours | Help |
| Save | Paste | Find | Autocomplete | |||
| Save All | Find Next | |||||
| Close | Find Prior |
Toolbar entries can be removed, if desired, by amending lang/ealng_XX.txt.