ActionRoutines

From Niki

Problems I see with the documentation of Action Routines are:

• an unclear structure, Actions Representing Menu Commands, then Menu Action Routine Arguments, now --Some notes on argument types above-- followed by Window Preferences Actions plugged into the middle of somewhere and finally Keyboard-Only Actions. Adding to this is that the actions for copy, cut and paste, while clearly represented in the Edit menu, are listed under the Keyboard-Only Actions.
• The introduction says all actions can be called from both macros and translation table entries. This is true, but unfortunately there are some actions (grab_focus() is only one of them) that make only sense when bound to a key or even a mouse event. Calling them in macros doesn't give the possibly expected result.
• Why are pure mouse actions like secondary_start() listed under the heading Keyboard-Only Actions?

Btw, what does Keyboard-Only Actions really mean, considering that these are not actions that can only be bound to key(board) events. And Actions Representing Menu Commands are also bound to shortcuts, aren't they. So what's the difference between uppercase() bound to Ctrl+6 but listed under Actions Repr... and copy_clipboard() represented in the Edit menu as Copy Ctrl+C but listed under Keyboard-Only...?

ActionRoutineDoc

Suggested new structure for this section:

---

Action Routines

All of the editing capabilities of NEdit are represented as a special type of subroutine, called an Action Routine (AR), which can be invoked from both macros and translation table entries (see "Key Binding" in the Customizing section of the Help menu).
Arguments to ARs are text strings enclosed in quotes. Optional arguments are enclosed in [].
In addition to the arguments listed in the call descriptions below, any routine involving cursor movement can take the argument "extend", meaning, adjust the primary selection to the new cursor position. Routines which take the "extend" argument as well as mouse dragging operations for both primary and secondary selections can take the optional keyword "rect", meaning, make the selection rectangular. Any routine that accepts the "scrollbar" argument will move the display but not the cursor or selection. Routines that accept the "nobell" argument will fail silently without beeping, when that argument is supplied.

Some ARs correspond directly to a menu command. An AR representing a menu command is usually named the same as its corresponding menu item except that all punctuation is removed, all letters are changed to lower case, and spaces are replaced with underscores. To present a dialog to ask the user for input, use the actions with the `_dialog` suffix. Actions without the `_dialog` suffix take the information from the routine's arguments (see below).

Some notes on argument types used below:
    filename       Path names are relative to the directory from
                   which NEdit was started. Shell interpreted
                   wildcards and `~' are not expanded.

    keep-dialog    Either "keep" or "nokeep".

    mark-letter    The mark command limits users to single
                   letters. Inside of macros, numeric marks are
                   allowed, which won't interfere with marks set
                   by the user.

    macro-menu-item-name
                   Name of the command exactly as specified in
                   the Macro Menu dialogs.

    non-regex-search-type
                   Either "literal", "case", "word", or
                   "caseWord".

    search-direction
                   Either "forward" or "backward".

    search-type    Either "literal", "case", "word",
                   "caseWord", "regex", or "regexNoCase".

    search-wrap    Either "wrap" or "nowrap".

    shell-menu-item-name
                   Name of the command exactly as specified in
                   the Shell Menu dialogs.

Actions Representing Menu Commands

    File Menu                 Search Menu
    -----------------------   -------------------------
    new()                     find()
    open()                    find_dialog()
    open_dialog()             find_again()
    open_selected()           find_selection()
    close()                   replace()
    save()                    replace_dialog()
    save_as()                 replace_all()
    save_as_dialog()          replace_in_selection()
    revert_to_saved()         replace_again()
    include_file()            goto_line_number()
    include_file_dialog()     goto_line_number_dialog()
    load_macro_file()         goto_selected()
    load_macro_file_dialog()  mark()
    load_tags_file()          mark_dialog()
    load_tags_file_dialog()   goto_mark()
    unload_tags_file()        goto_mark_dialog()
    load_tips_file()          goto_matching()
    load_tips_file_dialog()   select_to_matching()
    unload_tips_file()        find_definition()
    print()                   show_tip()
    print_selection()
    exit()                    Shell Menu
                              -------------------------
    Edit Menu                 filter_selection_dialog()
    -----------------------   filter_selection()
    undo()                    execute_command()
    redo()                    execute_command_dialog()
    delete()                  execute_command_line()
    select_all()              shell_menu_command()
    shift_left()
    shift_left_by_tab()       Macro Menu
    shift_right()             -------------------------
    shift_right_by_tab()      macro_menu_command()
    uppercase()               repeat_macro()
    lowercase()               repeat_dialog()
    fill_paragraph()
    control_code_dialog()     Windows Menu
                              -------------------------
                              split_pane()
                              close_pane()
                              detach_document()
                              move_document_dialog()


Following is a list of all Action Routines in alphabetical order:

backward_character( ["nobell"] )

Moves the cursor one character to the left.

new( ["tab" | "window" | "prefs" | "opposite"] )

                   "tab":      Open a new tab
                   "window":   Open a new window
                   "prefs":    Follow the user's tab/window
                               preference
                   "opposite": Opposite of user's tab/window
                               preference
                   Default behaviour is "prefs".