This is Info file axe.info, produced by Makeinfo-1.55 from the input file axe.texi.  File: axe.info, Node: Actions, Next: SampBinds, Prev: SampRsrcs, Up: Customise Actions specific to aXe ======================= The main editing subwindow of a top-level aXe window is derived from an Athena Text Widget. Hence all of the default bindings of keys to Text Widget action routines apply. The Text Widget is fully described in 'Athena Widget Set - C Language InterFace' of the 'MIT X Window System Manual Set', but for your convenience an extract from the section describing the default key bindings can be viewed on-line (*Note The default key bindings: Bindings.). aXe extends the functionality of the Text Widget by providing additional action routines, but it does not set up any default key bindings for them, i.e. the new features are only available through the menu and button interfaces, or the minibuffer. If you wish to set up your own bindings then you need to know the names of the new action routines. They are goto-line search-caret forward-search-selection backward-search-selection include-file include-selection paste delete-word delete-line cut undo where centre-line set-preferences new-window close-window close-all iconify-all deiconify-all new-buffer clear-buffer close-buffer save-and-close save-all save-file save-as load-file reload-file size match-parens find-match re-search forward-line backward-line delete-selection-or-previous-character insert-or-expand-tab keymap set-mark highlight-region kill-region copy-region yank-region It should be obvious which menu entries/buttons those in the first eight groups correspond to. include-file inserts a file using the file selector, as distinct from insert-file, the Text Widget action bound to Meta-i that brings up the Text Widget's own insertFile dialogue box. new-window and new-buffer may be given the optional argument `load', causing the file selector to be popped up for the new window or buffer immediately it is created. Without an argument save-and-close saves and closes all buffers. With the argument `window' it saves and closes the current window; with the argument `buffer' it saves and closes the current buffer. The remaining actions are not available via the menus or buttons and hence must be bound to keystrokes or typed into the minibuffer (*Note How to use the minibuffer: Minibuffer.). size reports the size of the editing buffer in the information bar. match-parens, if bound to `)', `}' or `]', causes the matching closing bracket to be highlit for a period of time determined by the value of the *blinkPeriod* resource (*Note AxeiiText widget resources: AxeiiTextRsrcs.). find-match causes a search to be made for the character matching the `(', `)', `{', `}', `[' or `]' immediately to the right of the caret, and if successful, highlighting the text between the two characters, inclusive. re-search is like the standard search action except that regular expression searching is performed. It must be supplied with a direction argument of 'forward' or 'backward'. search and re-search share the same popup. The main observable difference when regular expression searching is in effect is that its title is 'RE search' rather than 'search'. There are also minor differences in the messages The forward/backward-line actions are similar to the Text Widgets's next/previous-line actions except that they maintain position within the line if at all possible, i.e. the cursor does not gravitate towards the left margin as ever shorter lines are encountered. The delete-selection-or-previous-character action does what its name suggests. insert-or-expand-tab is bound to the Tab key by default, and operates in conjunction with the *expandTabs* resource (*Note AxeiiText widget resources: AxeiiTextRsrcs.). If that resource is False then tabs are inserted, otherwise an appropriate number of spaces to take the insertion point up to the next tab stop is inserted. The keymap action enables an alternative set of bindings to be switched in. keymap takes a name as argument, which, together with the suffix Keymap, defines the name of a translations resource. A name of None restores the original translations, e.g. *ed.translations:#override \n F1:keymap(foo) \n ... *ed.fooKeymap.translations:F1:keymap(None) \n ... The final set of actions allows selections to be manipulated via the keyboard. set-mark sets an invisible marker. It is initially at the beginning of the buffer. highlight-region highlights the region between the marker and the caret. kill-region deletes the region between the mark and the caret, and stores it in cut buffer 2. copy-region copies the region between the mark and the caret to cut buffer 2. yank-region inserts the contents of cut buffer 2 at the current insertion point.  File: axe.info, Node: SampBinds, Next: Minibuffer, Prev: Actions, Up: Customise Examples of binding actions to keystrokes ========================================= Binding actions to keystrokes involves setting the translations resource of the Text Widget (instance name ed). Here is an example of how this might be done in a resources file. Axe*ed.translations: #override \n\ Down: forward-line() \n\ Up: backward-line() \n\ Delete: delete-selection-or-previous-character() Some of the features in aXe are implemented through setting ed's translations resource in the class resource file, but at Release 4 of X if you provide a value for the same resource it will completely override the application's. A mechanism, which aXe uses, has become available at Release 5 to overcome this difficulty. So if your aXe is an R5 one then you can skip the remainder of this section. If at R4 you don't want to lose any of the application's bindings then you will have to repeat in your value those you wish to keep. The features affected are the matching of parentheses and the reporting of the current line number on a button release. This is how they are implemented in the class resource file Axe*ed.translations: #override \n\ ): match-parens() \n\ ]: match-parens() \n\ : extend-end(PRIMARY, CUT_BUFFER0) where() \n\ : where() \n\ : extend-end(PRIMARY, CUT_BUFFER0) where() and the following is an example of how a user supplied value might look Axe*ed.translations: #override \n\ ): match-parens() \n\ ]: match-parens() \n\ Down: forward-line() \n\ Up: backward-line() \n\ Delete: delete-selection-or-previous-character() Meta=: where() The matching of parentheses has been kept but the reporting of the current line number has been implemented another way, viz. by binding to Meta-=. The Btn?Up actions are not repeated because what is left after removing the where() action is the default behaviour that is defined by the Text Widget.  File: axe.info, Node: Minibuffer, Next: Minimenu, Prev: SampBinds, Up: Customise How to use the minibuffer ========================= Commands corresponding to the two *Search:Text* operations plus *Search:Line*, *Insert:File*, *File:SaveAs* and *File:Load* can be entered directly into the minibuffer. The command names are styled after those of the Unix editor ed and are /regular-expression ?regular-expression [0-9][0-9]* r filename w filename e filename In addition pipe and shell commands have been introduced. Their names are `|' and `!' respectively. Execution of pipe has the effect of replacing the selected text, if any, in the editing buffer by the result of filtering by the command specified in the remainder of the minibuffer. If no text is selected then the output of running the command specified as the pipe argument is inserted at the current insertion point. Execution of shell has the effect of passing the whole buffer or the selected text to the shell command specified as argument and displaying the output, if any, of that command in a new aXe window, unless a `>' occurs in the command, in which case it is assumed that the user wishes to handle the output themself. The command names must occur in column 1 of the minibuffer, and whitespace preceding the argument of `r', `w', `e', `|' and `!' commands is mandatory. The minibuffer also recognises actions as commands. Thus it is not necessary restart aXe with new key bindings to experiment with untried features or to execute infrequently used actions - simply type them into the minibuffer, e.g. new-window() [or simply new-window] or new-window(load). New action routines have been defined so that the minibuffer can be enabled from the editing buffer. When they are used the normal editing buffer translations are suspended and replaced by a minimal set of editing bindings that take effect in the minibuffer, i.e it is not necessary to move the mouse into the minibuffer to execute commands in it. If they are found to be inadequate the mouse can always be moved into the minibuffer to gain access to full range of Text Widget key bindings. The names of the action routines are mini-search mini-insert mini-saveas mini-load mini-pipe mini-shell mini-stuff mini-search may be given an argument of `forward' or `backward'; the default is forward. When the command is mini-insert, mini-saveas or mini-load the minibuffer is initialised with the directory already associated with the editing buffer. mini-pipe, mini-shell and mini-stuff may be given arguments with which to initialise the minibuffer, so frequently used filters and other minibuffer commands can be set up via user defined key bindings. If the last mini-pipe, mini-shell or mini-stuff argument ends with `\n' then the command will be executed right away. Four other action routines have been defined. They are mini-clear mini-select mini-commit mini-abort mini-clear enables and flushes the minibuffer. There is no command corresponding to *Search:Line* so mini-clear could be bound to a key for the purpose as it would provide an empty minibuffer awaiting the entry of a line number. mini-select enables the minibuffer without altering it, so the previous command can then be repeated by simply hitting the Return key. mini-commit executes the command in the minibuffer. mini-abort is defined so that a minibuffer command can be aborted while the accelerators are in effect. The default minibuffer translations and accelerators (the bindings that get installed as the editing buffer translations when the minibuffer is enabled via the above action routines) have Return bound to mini-commit and mini-abort bound to both Escape and `Ctrl-g'. In all cases except mini-search, hitting the Return key causes reinstatement of the editing buffer translations after execution of the minibuffer command. The reason for this is so that repeated searches can be made simply by continuing to hit the Return key. Thus it is necessary to explicitly abort search operations. Note that the caret is only displayed in the minibuffer when it is active, either because the mouse pointer has been moved into it or because it has been enabled by execution of one of the mini- action routines, and further that the caret in the editing buffer is disabled in the latter case, although it won't always be easy to spot that that has happened. Here are some typical bindings that might be used MetaG: mini-clear() CtrlS: mini-search() CtrlR: mini-search(backward) CtrlX,B: mini-select() CtrlX,O: mini-select() CtrlX,CtrlF: mini-load() CtrlX,CtrlI: mini-insert() CtrlX,CtrlW: mini-saveas() CtrlX,CtrlX: mini-pipe("sed 's/^/> /'\n") Print: mini-shell(lpr -Pprinter\n) The second last example will cause each line of the selected text to be prefixed by `> ', i.e. it might be used to annotate a section of a mail message or news article being replied to. It is best to quote the whole argument to mini-pipe because of the way it would otherwise be split on spaces and commas. aXe does try to piece the line together again but can't know whether a split was as a result of a space or a comma; it always assumes that it was a space. The last example causes the selected text or the whole of the text in the editing buffer to be queued for printing by printer `printer'. The minibuffer menu provides a few ready-made examples that are likely to be commonly used. * Menu: * Minimenu:: The minibuffer menu  File: axe.info, Node: Minimenu, Next: Macro, Prev: Minibuffer, Up: Minibuffer The minibuffer menu ------------------- The minibuffer menu provides easy access to a few selected external commands that it is hoped will be commonly required, e.g. printing, spelling checking, formatting and mailing. The mini-shell commands that implement them are: mini-shell(lpr) mini-shell(spell) mini-shell(nroff) mini-shell(mail) Those commands only place the commands `! lpr', `! spell' etc. into the minibuffer (with its accelerators enabled) so it is possible to add options to them before proceeding. For convenience, the menu also provides exec and abort entries; the first is simply equivalent to hitting Return, and causes the command in the minibuffer to be executed, while the second removes the accelerators so that keystrokes in the editing buffer will revert to being directed to that buffer instead of to the minibuffer. A further three entries are identical to the first three except that the commands are entered and executed in one operation. They are identifiable by having in the entry label, which is meant to convey that the command contains the Return to cause it to be executed. It does not make sense to replicate `mail' in this way since a recipient will always have to be added to the minibuffer command before execution. Although probably useful as it stands, the minbuffer menu is merely a demonstration of what can be done. It is totally customisable by the user by defining the *miniMenu* resource. Its value is a whitespace separated list of items. If a `:' occurs in an item then the left hand part will be taken as the corresponding menu entry label and the right hand part as the minibuffer action, otherwise the whole item will be used for both purposes. If the action part begins with `mini-' then it is left untouched, otherwise it is taken to be an argument to mini-shell. Furthermore, an item of `|' is interpreted to mean that a dividing line should be added to the menu at that position. An item of `+' means that the default menu should be substituted at that point, i.e. the user can either replace or add to the default menu. So *miniMenu:who | + would add an item called who, that would execute the who command, to the top of the default menu, and separated from it by a dividing line, whereas *miniMenu:who would generate a menu consisting of a single `who' entry. The resource value defining the default menu is: print:lpr spell nroff mail | \ exec:mini-commit abort:mini-abort | \ print:lpr\n spell:spell\n nroff:nroff\n Labels and actions can be quoted using either the single or the double quote characters, e.g "laser printer":'lpr -Plaser' or 'laser printer':"lpr -Plaser" The " and ' characters themselves can only be included by using the other quote character to do the quoting, e.g. "jim's printer" You can provide help to be displayed in the information bar when the mouse enters your menu items by setting each's help resource. The name of the widget is the same as the item's label, e.g. *laser printer.help:Send to laser printer  File: axe.info, Node: Macro, Next: Undo, Prev: Minimenu, Up: Customise Defining and using a keyboard macro =================================== A single global keyboard macro can be defined. The following new action routines have been defined in this connection: start-macro end-macro exec-macro repeat-macro start-macro and end-macro should be self-explanatory. exec-macro executes the macro once. repeat-macro optionally takes an argument specifying a repeat count. This is most likely to be of use when the action is executed as a minibuffer command. Otherwise a repeat count is taken from the minibuffer and the macro is executed that many times. This is most likely to be of use when repeat-macro() is used from a key binding. If the conversion fails or the minibuffer has been suppressed then the repeat count defaults to 1. Here are some bindings that might be used: CtrlX,(: start-macro() CtrlX,): end-macro() CtrlX,E: exec-macro() CtrlX,R: repeat-macro() A macro is defined by executing start-macro and stepping through the sequence of actions that will constitute one invocation, followed by end-macro. The macro is effective in all buffers, not just the one in which it is defined, and gets replaced if start-macro is executed again. With these bindings the effect of the mini-pipe example above could equally well be accomplished, after moving the insertion point to the beginning of the first line to be annotated, by defining a macro with the following sequence of keystrokes C-x ( > C-a C-n C-x ) and by executing `C-x e' for each subsequent line to be annotated, or by entering the number of remaining lines to be annotated in the minibuffer and executing `C-x r'.  File: axe.info, Node: Undo, Next: Server, Prev: Macro, Up: Customise How the undo mechanism works ============================ The availability of undo is controlled by the resource *undo*, which is True by default. By default you are able to undo only the most recent operation that changed the file. If you wish to retain a greater history then set the *undoLevel* resource (*Note AxeiiText widget resources: AxeiiTextRsrcs.) to the level you require. The default is 1. A value of 0 means keeping unlimited information, but that could run away with large amounts of memory if editing over an extended period. The new action undo performs a single undo. Inserted characters, apart from control codes, which are dealt with individually, are handed back in units of uninterrupted runs of at most a line. A run is interrupted by any operation other than the insertion of a character, even if it doesn't change the file, e.g. moving the caret. If you want to undo single characters then delete them in the normal way. Deleted characters can be undone individually. The implementation allows undos of undos. Once *undoLevel* consecutive undos have been performed the next (consecutive) undo will cause the most recent undo to be undone, the next the undo before that, and so on ad infinitum until some action other than undo breaks the sequence. Note that if you have a number of undos to perform it is quicker to type undo in the minibuffer and repeatedly re-execute it by hitting the Return key than by selecting *Undo* from the *Misc* menu each time. You should be aware that currently multiple changes arising from performing a single action, e.g. by doing a `replace All' or executing a keyboard macro, require multiple undos to get back to the position prior to the action being invoked, and may be impossible if *undoLevel* is not great enough. If you find that for some reason the undo information has got out of step then the easiest way to get back in sync is to save and reload the file. Loading or reloading a file causes all the current undo information to be thrown away and the mechanism to be reinitialised.  File: axe.info, Node: Server, Next: Popups, Prev: Undo, Up: Customise aXe as a server of windows ========================== There are two main differences when aXe is acting as a server: an additional window is created and aXe does not terminate when the number of windows reduces to zero. The function of the extra window is to provide a way of getting an editing window when there are no others to use as a launch pad, and to provide a way of shutting down the application. The default server window allows empty windows to be created and provides access to the help system. Alternatively, a FileNominator (*Note The file selector: Nominator.) can be used as the server window by setting the top level *fileServer* resource (*Note Application resources: AppRsrcs,). Additionally, editing windows can be obtained from a server by cooperating clients on the same host. Two such clients are provided: coaxe and faxe. Coaxe waits until it gets notification that its aXe window has been closed, whereas faxe terminates as soon as it has successfully contacted its server. Faxe can take several filename arguments, but coaxe is restricted to one. By default multiple files passed to faxe are assigned a window each. A group of files can be assigned to buffers of the same window by preceding the list by any leading substring of the keyword -buffer. The keyword may occur more than once on the command line. Coaxe and faxe start up aXe in non-server mode if a server is not already running, and coaxe is notified when the invocation terminates, i.e. when the last window is closed. A display can support servers for many hosts, but only one server per host is catered for. If a second server is started for some host when one is already running then the second will take over the role of server to the client programs, and the first will be uncontactable by them. Shutting down aXe from the server window is equivalent to doing a *Window:Close All*, i.e. a check is made for unsaved changes if any editing windows exist. A third client program, poleaxe, is also provided for shutting down the server, but checks are not carried out when it is used. It is not a serious client; it only came into being because of the pun afforded by its name.  File: axe.info, Node: Popups, Next: Nominator, Prev: Server, Up: Top aXe's secondary popup windows ***************************** From time to time as aXe is running windows other than the main editing windows and the initial server window, if running in server mode, that is, are popped up for the input and output of information. Each type is briefly described in one of the menu items that now follow. * Menu: * Nominator:: The file selector * NumPad:: The numeric keypad * ControlCode:: The control code selector * Confirmer:: The confirmer * Preferences:: The preferences setter * Help:: The help system  File: axe.info, Node: Nominator, Next: NumPad, Prev: Popups, Up: Popups The file selector ================= The FileNominator popup is popped up whenever a menu operation that requires a file name is selected, or an equivalent action routine has been activated through a key binding set up by the user. The FileNominator is both a directory browser and a file selector. It consists of a scrollable list of the contents of the directory associated with the buffer from which it was popped up, or the directory last visited by the user in earlier usage, a filter section, which allows the user to filter the list of files displayed according to normal shell pattern matching rules, a 1-line text area in which the filename to be returned is assembled, and three buttons. The filter pattern that is initially applied may be something other than the default `*'. A different value is specified by setting the value of the resource *filter*, for example to `*[ch]'. A file may be nominated by choosing from the list using mouse button 1 (causing the name to be entered into the filename input area), or by typing into the input area, or by doing both. All keyboard input is directed there when the list widget has the input focus. The content of the input is assumed to be relative to the directory currently displayed if not an absolute pathname. The selection is always taken from the nomination in the input area, and happens when the select button is clicked (mouse button 1) or the Return key is pressed. If no modification is to be made then a choice from the List can be selected by double clicking mouse button 1 or by single clicking mouse button 2. Further, an immediate selection of some other directory in the path of the displayed directory can be made by selecting from the `path' button menu. A `~' as the first character in the input area is understood to mean the user's home directory. If a nomination begins with a `$' then the first component will be treated as a possible reference to an environment variable, with the expansion being made if a variable of that name exists. In addition the user may define a list of potential nominations - either files or directories - to be added to the `path' button menu. Since selecting an entry from the menu is equivalent to entering the entry in the input area and selecting it in the normal way, i.e it is subject to the checks that would be applied if the user had typed the value as a nomination, then `~' and `$' may feature in the user-added entries. The user adds entries by providing a value for the *pathList* resource of the FileNominator. It is a colon separated list of pathnames that are converted into menu entries and added to the path button menu. When the selection is a directory the contents of the directory are filtered according to the pattern in the filter input area, so that a reduced subset of interest may be displayed. A new filter can be run on the current directory by hitting Return in the filter input area or by selecting Apply from the menu belonging to the filter menu button. The menu has two other entries: `Apply to directories', which controls whether directories should always be displayed or whether they should also be subject to filtering, and `Apply to "." files', which controls whether names beginning with a `.' should be displayed or not. The last two entries are toggles, whose selection cause toggling of the setting and rescanning of the directory with the toggled value effective. The "." files entry takes precedence over the one for directories e.g. if the pattern is `*c' and there is a file called .filec, then it won't be shown unless there is a tick mark against the `Apply to "." files' entry.  File: axe.info, Node: NumPad, Next: ControlCode, Prev: Nominator, Up: Popups The numeric keypad ================== The NumericPad popup is popped up whenever the *Line* entry of the *Search* menu is selected, or the goto-line action invoked by other means. This popup is an instance of a general purpose widget for entering numeric data, and contains features that are probably inappropriate for aXe, like the ability to change the base to octal or hexadecimal. A number can be entered into the 1-line text area by clicking the digit buttons or from the keyboard whilst the popup has the input focus. A number is submitted to the application by clicking the enter button or by hitting either the Return or the Enter key. The cancel button is for dismissing the popup without entering a number.  File: axe.info, Node: ControlCode, Next: Confirmer, Prev: NumPad, Up: Popups The control code selector ========================= The ControlCodeSelector popup is popped up whenever the *Control Codes* entry of the *Insert* menu is selected, or the insert-control action is invoked by other means. Selecting an item in the table of control codes that is displayed causes the item to become highlighted and its ASCII code to be displayed in a label at the lower left of the popup. The widget that is at the heart of this popup has a resource, *base*, which controls how the numeric value of the code is displayed. aXe displays the value to the base 8, i.e. in octal. The currently selected control code is entered into the current buffer of the window from which the popup was popped up by clicking the enter button with mouse button 1. Several consecutive control codes can be entered as the popup is only popped down when the cancel button is clicked. A code from the table can be entered directly into the current buffer by clicking the item with mouse button 2.  File: axe.info, Node: Confirmer, Next: Preferences, Prev: ControlCode, Up: Popups The confirmer ============= The Confirmer popup is popped up whenever the user is about to perform a potentially destructive act, like clearing a buffer that has unsaved changes. Apart from a superfluous bitmap, it contains a message describing the reason why the user is being asked to confirm proceeding with the requested operation, and three buttons. The rightmost button - cancel - is for dismissing the popup by abandoning the requested operation. The remaining two buttons provide alternative courses of action. If the middle button is greyed out then it means that there is only one possible action to take. The symbols at the right hand end of the button labels signify keyboard accelerators for selecting those buttons. `^A' is shorthand for hitting key A in conjunction with the Control key. Thus, if the popup is popped up as a result of a keyboard event then in all probability the user will be able to make a choice without having to resort to the mouse since the popup is centred around the mouse pointer and a popular way of working is for the widget having the input focus to be determined by the location of the mouse.  File: axe.info, Node: Preferences, Next: Help, Prev: Confirmer, Up: Popups The preferences setter ====================== The Preferences popup allows a selected number of user preferences (resources) to be changed at runtime. You should note that under `Wrap Mode' selection of `Auto Fill' automatically forces on `No Wrap', and selection of `Line' or `Word' automatically forces off `Auto Fill'. These are the combinations that it has been found work best. Any typing within the popup is directed to the `Tab Every' entry field as this is the only one which requires keyboard input. Although there is apparently provision for having the settings apply to just one buffer, all the buffers in one window, or to all buffers, only the first is possible. The buttons corresponding to the last two cases are insensitive to button presses, which is indicated by their being greyed out.  File: axe.info, Node: Help, Next: Language, Prev: Preferences, Up: Popups The help system =============== You have obviously already discovered the help system. If you require more information about how to use it then jump to the *Note Axinfo::, node. If a window fails to appear in response to requesting help then it is almost certain that the executable, axinfo, was not found on your shell command search path. If a small window appears containing a message that the application defaults file could not be found then axinfo has either not been installed properly or you have incorrectly overridden the default search path for application defaults files, for example by setting the environment variable XFILESEARCHPATH, Once axinfo has been started up it is independent of aXe, i.e. terminating the one does not terminate the other. On the other hand, if an axinfo is already running, as a result of having been started independently or remaining from an earlier invocation of aXe, when help is requested then aXe communicates with that axinfo rather than fire up a new one.  File: axe.info, Node: Language, Next: Builtins, Prev: Help, Up: Top aXe's extension language ************************ aXe's extension language is Tcl. As Tcl is a separate package with its own documentation, which should be available locally, it is not described here. The language extension is an option at build time. If the *Help* menu does not contain an *Extension* entry then the option has not been configured into the version of aXe you are running. In order to integrate Tcl into aXe a new action routine, execute, has been introduced. It takes a Tcl command as argument. Thus Tcl commands can be bound to keystrokes, e.g. *ed.translations:#override \n\ Ctrlx,r:execute(prefix) where `prefix' might be the following procedure: proc prefix {{text {> }}} { with-selection action insert-string $text } with-selection is a general purpose procedure that applies another procedure to each line of the selection in turn. The applied procedure and its arguments are passed as arguments to with-selection. In the example above the applied procedure is `action' and its arguments are `insert-string' and `$text'. with-selection is implemented as follows: proc with-selection {func {args {}}} { set selection [get-selection] set start [lindex $selection 0] set end [lindex $selection 1] set lines [lindex $selection 2] if {$start == $end} {return} set-position $start for {set line 0} {$line < $lines} {incr line} { action beginning-of-line eval $func $args action next-line } action beginning-of-line set-selection $start [get-position] } By default prefix prepends `> ' to each line in the selection, but by supplying an argument a different prefix can be employed, e.g. prefix "! " prefix " " prefix and with-selection make use of a number of builtin commands (*Note Builtin extension language commands: Builtins.) that have been defined. * Menu: * Builtins:: Built in extension language commands * Utilities:: Other extension language commands * UseLang:: Using the extension language  File: axe.info, Node: Builtins, Next: Utilities, Prev: Language, Up: Language Builtin extension language commands =================================== `action arg1 arg2 ...' enables action routines to be executed from within Tcl commands. Action routine arguments are separated by spaces, not enclosed in parentheses, e.g. search forward, not search(forward). `eval-buffer' evaluates the current buffer on the assumption that it contains a Tcl script. In other words new commands can be entered and immediately tried out. `get-selection' returns a list consisting of the starting and finishing positions of the selection, the number of lines spanned by it, and the selection itself. `get-position' returns the value of the insertion point. `set-position point' sets the insertion point to the value of its argument. `set-selection start finish' sets the selection to be the text spanned by the positions passed as arguments. `set-value resource value' `set-source-value resource value' `set-sink-value resource value' set the resource named in the first argument to the value in the second for the text widget or its source or sink objects.  File: axe.info, Node: Utilities, Next: UseLang, Prev: Builtins, Up: Language Other extension language commands ================================= A small collection of commands built using the builtins (*Note Builtin extension language commands: Builtins.) and action routines should have been loaded when aXe was started up. It consists of the following commands. `with-selection proc args' applies a procedure and its arguments to each line of the selection in turn. Example: with-selection action insert-string "> " `prefix string' prepends an optional string to each line of the selection. The default string is `> '. `strip n' removes a number of characters equal to the value of its argument from the beginning of each line in the selection. If no argument is given the default is 1. `join-lines n separator' joins together the next n lines as given by the first argument (default 1) to the current line, and inserts the text given by the second argument (default " ") at the join. `format-all' formats the entire buffer by applying the action form-paragraph to successive paragraphs. On completion the caret is restored to the character position it was originally at, but of course that is likely to be correspond to a different place in the text. `upper' `lower' convert the selection to upper and lower case respectively.  File: axe.info, Node: UseLang, Next: Changes, Prev: Utilities, Up: Language Using the extension language ============================ User-defined commands that are to be loaded at startup should be stored in the file axe.tcl in the user's home directory. Commands can also be loaded dynamically at runtime from a file by executing `source pathname' in the minibuffer. If the file does not exist then the command will fail, and that failure will be reported identically to other errors, i.e. the keyboard bell will be rung and an appropriate message displayed in an alert popup. The easiest way to execute Tcl commands is to type them into the minibuffer. Thus the example given at the beginning (*Note aXe's extension language: Language.) could equally well be executed by typing `prefix' in the minibuffer, whereas making a selection and typing prefix " " will cause each line in the selection to be indented by 4 spaces. Using the minibuffer is especially convenient if you want to create and try out new commands from within aXe. If the current buffer contains a Tcl script defining some new procedures then these can be loaded into aXe by typing `eval-buffer' in the minibuffer. The new procedures may be tried out by issuing commands in the minibuffer to invoke them. Changes to the script can be made and the process repeated as often as necessary as defining a procedure replaces the existing definition, if any. The extension language makes it possible for things to be done in aXe that either I couldn't envisage users wanting to do or wouldn't want to implement as fixed features. Here are just a couple of examples that might set you thinking of the possibilities. `Example 1' The following procedure demonstrates how the extension language might be used to set up modes. proc a-mode {} { set-value tabEvery 4 set-value wrap word } Execution of the procedure will affect the current buffer of the window in which it is executed. There are three ways in which it could be executed: 1. by typing `a-mode' in the minibuffer. 2. by setting up a minibuffer menu entry and selecting it. The entry might be set up using the following resource specification: *miniMenu:+ 'A mode':mini-stuff(a-mode\n) 3. by setting up a translation, such as the following: *ed.translations: #override \n\ Metam:execute(a-mode) and typing `Meta-m' in the editing buffer to which it is to be applied. `Example 2' This example shows how a procedure defining a C++ template header file might be set up. proc class {class {baseclass {}}} { action insert-string "#ifndef ${class}_h\n" action insert-string "#define ${class}_h\n\n" action insert-string "class $class" if {$baseclass != {}} { action insert-string " : public $baseclass" } action insert-string "\n\{\npublic:\n" action insert-string " $class\(\);\n ~$class\(\);\n\n" action insert-string "protected:\n\n" action insert-string "private:\n\};\n\n#endif\n" } When invoked with two arguments, the name of the new class and the name of the base class, then the following is generated at the insertion point of the current buffer, assuming arguments of Foo and Bar: #ifndef Foo_h #define Foo_h class Foo : public Bar { public: Foo(); ~Foo(); protected: private: }; #endif If the second argument is not given then the `class' line becomes class Foo  File: axe.info, Node: Changes, Next: Change 1, Prev: UseLang, Up: Top Changes since the previous release ================================== If this is the first time you have seen axinfo (aXe information system) then the minimum you need to know to begin to use it is that clicking on highlighted words using mouse button 1 will take you to other parts of the help. *Note Axinfo:: describes the system in more detail. * Menu: * Change 1:: Changes to the help system * Change 2:: Deleting the selection on text entry * Change 3:: Changes to the extension language * Change 4:: Setting of the WM_COMMAND property  File: axe.info, Node: Change 1, Next: Change 2, Prev: Changes, Up: Changes Changes to the help system ========================== aXe's help information is now displayed using a separate application (this program) that is either run standalone or invoked, if it is not already running, when an entry is selected from the *Help* menu. *Note Axinfo:: describes the system in detail. The underlying documentation system that is used permits both on-line help and printed output to be generated from the same input file. Hence the help information is now available as a User Guide. It should have been provided as a PostScript file when your site acquired the aXe distribution. Check availability with your system administrator.  File: axe.info, Node: Change 2, Next: Change 3, Prev: Change 1, Up: Changes Deleting the selection on text entry ==================================== A new AxeiiText widget resource `deleteOnInsert' has been introduced. It controls whether the entry of the first character via the keyboard (i.e. via the insert-char action) following the setting of the selection should delete the selection. The default value is `False'.  File: axe.info, Node: Change 3, Next: Change 4, Prev: Change 2, Up: Changes Changes to the extension language ================================= The supplied commands that manipulate the selection reselect the modified text so that it can be further operated on. Some new commands have been provided and others have been renamed. join and format have been renamed as join-lines and format-all because they masked Tcl procedures of the same names. getSelection, getPos, setPos and loopSel have been renamed as get-selection, get-position, set-position and with-selection. In addition get-selection provides the selection as an extra element of the returned list. The new commands are:- set-selection start finish which sets the selection. eval-buffer which evaluates the current buffer as a Tcl script, i.e. you can compose, add and try out new commands from within aXe. set-value resource value set-source-value resource value set-sink-value resource value which set the value of the named resource for the editing buffer Text widget, or its source or sink object. upper lower which convert the selection to upper or lower case respectively.  File: axe.info, Node: Change 4, Prev: Change 3, Up: Changes Setting of the WM_COMMAND property ================================== When running in server mode aXe now sets the WM_COMMAND property on the server window. This means that an entry for aXe will now show up in the output of xlsclients, and that aXe will be visible to startup generator applications. The WM_COMMAND property is not set if aXe is not running in server mode - there is no window that can be guaranteed to survive the term of the invocation.