Macro/Shell Extensions

## Action Routines

All of the editing capabilities of NEdit are represented as a special type of subroutine, called an action routine, which can be invoked from both macros and translation table entries (see "Key Binding" in the Customizing section of the Help menu).

### 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()

An action 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).

### Menu Action Routine Arguments

Arguments are text strings enclosed in quotes. Below are the menu action routines which take arguments. Optional arguments are enclosed in [].

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

        close( ["prompt" | "save" | "nosave"] )

        execute_command( shell-command )

        filter_selection( shell-command )

        find( search-string [, search-direction] [, search-type]
           [, search-wrap] )

        find_again( [search-direction] [, search-wrap] )

        find_definition( [tag-name] )

        find_dialog( [search-direction] [, search-type]
           [, keep-dialog] )

        find_selection( [search-direction] [, search-wrap]
           [, non-regex-search-type] )

        goto_line_number( [line-number] [, column-number] )

        goto_mark( mark-letter )

        include_file( filename )

        load_tags_file( filename )

        macro_menu_command( macro-menu-item-name )

        mark( mark-letter )

        open( filename )

        replace( search-string, replace-string,
           [, search-direction] [, search-type] [, search-wrap] )

        replace_again( [search-direction] [, search-wrap] )

        replace_all( search-string, replace-string [, search-type] )

        replace_dialog( [search-direction] [, search-type]
           [, keep-dialog] )

        replace_in_selection( search-string,
           replace-string [, search-type] )

        save_as( filename )

        shell_menu_command( shell-menu-item-name )

        unload_tags_file( filename )

        ----------- Some notes on argument types above -----------

        Arguments to new()
                       "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".

        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.

### Window Preferences Actions

    set_auto_indent( "off" | "on" | "smart" )

Set auto indent mode for the current window.

    set_em_tab_dist( em-tab-distance )

Set the emulated tab size. An em-tab-distance value of 0 or -1 translates to no emulated tabs. Em-tab-distance must be smaller than 1000.

    set_fonts( font-name, italic-font-name, bold-font-name, bold-italic-font-name )

Set all the fonts used for the current window.

    set_highlight_syntax( [0 | 1] )

Set syntax highlighting mode for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_incremental_backup( [0 | 1] )

Set incremental backup mode for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_incremental_search_line( [0 | 1] )

Show or hide the incremental search line for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_language_mode( language-mode )

Set the language mode for the current window. If the language mode is "" or unrecognized, it will be set to Plain.

    set_locked( [0 | 1] )

This only affects the locked status of a file, not it's read-only status. Permissions are NOT changed. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_make_backup_copy( [0 | 1] )

Set whether backup copies are made during saves for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_overtype_mode( [0 | 1] )

Set overtype mode for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_show_line_numbers( [0 | 1] )

Show or hide line numbers for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_show_matching( "off" | "delimiter" | "range" )

Set show matching (...) mode for the current window.

    set_match_syntax_based( [0 | 1] )

Set whether matching should be syntax based for the current window.

    set_statistics_line( [0 | 1] )

Show or hide the statistics line for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_tab_dist( tab-distance )

Set the size of hardware tab spacing. Tab-distance must must be a value greater than 0 and no greater than 20.

    set_use_tabs( [0 | 1] )

Set whether tabs are used for the current window. A value of 0 turns it off and a value of 1 turns it on. If no parameters are supplied the option is toggled.

    set_wrap_margin( wrap-width )

Set the wrap width for text wrapping of the current window. A value of 0 means to wrap at window width.

    set_wrap_text( "none" | "auto" | "continuous" )

Set wrap text mode for the current window.

### Keyboard-Only Actions

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.

    backward_character( ["nobell"] )

Moves the cursor one character to the left.

    backward_paragraph(["nobell"] )

Moves the cursor to the beginning of the paragraph, or if the cursor is already at the beginning of a paragraph, moves the cursor to the beginning of the previous paragraph. Paragraphs are defined as regions of text delimited by one or more blank lines.

    backward_word( ["nobell"] )

Moves the cursor to the beginning of a word, or, if the cursor is already at the beginning of a word, moves the cursor to the beginning of the previous word. Word delimiters are user-settable, and defined by the X resource wordDelimiters.

    beginning_of_file( ["scrollbar"] )

Moves the cursor to the beginning of the file.

    beginning_of_line( ["absolute"] )

Moves the cursor to the beginning of the line. If "absolute" is given, always moves to the absolute beginning of line, regardless of the text wrapping mode.

    beginning_of_selection()

Moves the cursor to the beginning of the selection without disturbing the selection.

    copy_clipboard()

Copies the current selection to the clipboard.

    copy_primary()

Copies the primary selection to the cursor.

    copy_to()

If a secondary selection exists, copies the secondary selection to the cursor. If no secondary selection exists, copies the primary selection to the pointer location.

    copy_to_or_end_drag()

Completes either a secondary selection operation, or a primary drag. If the user is dragging the mouse to adjust a secondary selection, the selection is copied and either inserted at the cursor location, or, if pending-delete is on and a primary selection exists in the window, replaces the primary selection. If the user is dragging a block of text (primary selection), completes the drag operation and leaves the text at it's current location.

    cut_clipboard()

Deletes the text in the primary selection and places it in the clipboard.

    cut_primary()

Copies the primary selection to the cursor and deletes it at its original location.

    delete_selection()

Deletes the contents of the primary selection.

    delete_next_character( ["nobell"] )

If a primary selection exists, deletes its contents. Otherwise, deletes the character following the cursor.

    delete_previous_character( ["nobell"] )

If a primary selection exists, deletes its contents. Otherwise, deletes the character before the cursor.

    delete_next_word( ["nobell"] )

If a primary selection exists, deletes its contents. Otherwise, deletes the word following the cursor.

    delete_previous_word( ["nobell"] )

If a primary selection exists, deletes its contents. Otherwise, deletes the word before the cursor.

    delete_to_start_of_line( ["nobell", "wrap"] )

If a primary selection exists, deletes its contents. Otherwise, deletes the characters between the cursor and the start of the line. If "wrap" is given, deletes to the previous wrap point or beginning of line, whichever is closest.

    delete_to_end_of_line( ["nobell", "absolute"] )

If a primary selection exists, deletes its contents. Otherwise, deletes the characters between the cursor and the end of the line. If "absolute" is given, always deletes to the absolute end of line, regardless of the text wrapping mode.

    deselect_all()

De-selects the primary selection.

    end_of_file( ["scrollbar"] )

Moves the cursor to the end of the file.

    end_of_line( ["absolute"] )

Moves the cursor to the end of the line. If "absolute" is given, always moves to the absolute end of line, regardless of the text wrapping mode.

    end_of_selection()

Moves the cursor to the end of the selection without disturbing the selection.

    exchange( ["nobell"] )

Exchange the primary and secondary selections.

    extend_adjust()

Attached mouse-movement events to begin a selection between the cursor and the mouse, or extend the primary selection to the mouse position.

    extend_end()

Completes a primary drag-selection operation.

    extend_start()

Begins a selection between the cursor and the mouse. A drag-selection operation can be started with either extend_start or grab_focus.

    focus_pane( [relative-pane] | [positive-index] | [negative-index] )

Move the focus to the requested pane. Arguments can be specified in the form of a relative-pane ("first", "last", "next", "previous"), a positive-index (numbers greater than 0, 1 is the same as "first") or a negative-index (numbers less than 0, -1 is the same as "last").

    forward_character()

Moves the cursor one character to the right.

    forward_paragraph( ["nobell"] )

Moves the cursor to the beginning of the next paragraph. Paragraphs are defined as regions of text delimited by one or more blank lines.

    forward_word( ["tail"] ["nobell"] )

Moves the cursor to the beginning of the next word. Word delimiters are user-settable, and defined by the X resource wordDelimiters. If the "tail" argument is supplied the cursor will be moved to the end of the current word or the end of the next word, if the cursor is between words.

    grab_focus()

Moves the cursor to the mouse pointer location, and prepares for a possible drag-selection operation (bound to extend_adjust), or multi-click operation (a further grab_focus action). If a second invocation of grab focus follows immediately, it selects a whole word, or a third, a whole line.

    insert_string( "string" )

If pending delete is on and the cursor is inside the selection, replaces the selection with "string". Otherwise, inserts "string" at the cursor location.

    key_select( "direction" [,"nobell"] )

Moves the cursor one character in "direction" ("left", "right", "up", or "down") and extends the selection. Same as forward/backward-character("extend"), or process-up/down("extend"), for compatibility with previous versions.

    move-destination()

Moves the cursor to the pointer location without disturbing the selection. (This is an unusual way of working. We left it in for compatibility with previous versions, but if you actually use this capability, please send us some mail, otherwise it is likely to disappear in the future.

    move_to()

If a secondary selection exists, deletes the contents of the secondary selection and inserts it at the cursor, or if pending-delete is on and there is a primary selection, replaces the primary selection. If no secondary selection exists, moves the primary selection to the pointer location, deleting it from its original position.

    move_to_or_end_drag()

Completes either a secondary selection operation, or a primary drag. If the user is dragging the mouse to adjust a secondary selection, the selection is deleted and either inserted at the cursor location, or, if pending-delete is on and a primary selection exists in the window, replaces the primary selection. If the user is dragging a block of text (primary selection), completes the drag operation and deletes the text from it's current location.

    newline()

Inserts a newline character. If Auto Indent is on, lines up the indentation of the cursor with the current line.

    newline_and_indent()

Inserts a newline character and lines up the indentation of the cursor with the current line, regardless of the setting of Auto Indent.

    newline_no_indent()

Inserts a newline character, without automatic indentation, regardless of the setting of Auto Indent.

    next_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )

Moves the cursor and scroll forward one page. The parameter "stutter" moves the cursor to the bottom of the display, unless it is already there, otherwise it will page down. The parameter "column" will maintain the preferred column while moving the cursor.

    page_left( ["scrollbar"] ["nobell"] )

Move the cursor and scroll left one page.

    page_right( ["scrollbar"] ["nobell"] )

Move the cursor and scroll right one page.

    paste_clipboard()

Insert the contents of the clipboard at the cursor, or if pending delete is on, replace the primary selection with the contents of the clipboard.

    previous_page( ["stutter"] ["column"] ["scrollbar"] ["nobell"] )

Moves the cursor and scroll backward one page. The parameter "stutter" moves the cursor to the top of the display, unless it is already there, otherwise it will page up. The parameter "column" will maintain the preferred column while moving the cursor.

    process_bdrag()

Same as secondary_or_drag_start for compatibility with previous versions.

    process_cancel()

Cancels the current extend_adjust, secondary_adjust, or secondary_or_drag_adjust in progress.

    process_down( ["nobell", "absolute"] )

Moves the cursor down one line. If "absolute" is given, always moves to the next line in the text buffer, regardless of wrapping.

    process_return()

Same as newline for compatibility with previous versions.

    process_shift_down( ["nobell", "absolute"] )

Same as process_down("extend") for compatibility with previous versions.

    process_shift_up( ["nobell", "absolute"] )

Same as process_up("extend") for compatibility with previous versions.

    process_tab()

If tab emulation is turned on, inserts an emulated tab, otherwise inserts a tab character.

    process_up( ["nobell", "absolute"] )

Moves the cursor up one line. If "absolute" is given, always moves to the previous line in the text buffer, regardless of wrapping.

    raise_window([relative-window] | [positive-index] | [negative-index])

Raise the current focused window to the front if no argument is supplied. Arguments can be specified in the form of a relative-window ("first", "last", "next", "previous"), a positive-index (numbers greater than 0, 1 is the same as "last") or a negative-index (numbers less than 0, -1 is the same as "first").

    scroll_down( nUnits, ["lines" | "pages"] )

Scroll the display down (towards the end of the file) by a given number of units, units being lines or pages. Default units are lines.

    scroll_left( nPixels )

Scroll the display left by nPixels.

    scroll_right( nPixels )

Scroll the display right by nPixels.

    scroll_up( nUnits, ["lines" | "pages"] )

Scroll the display up (towards the beginning of the file) by a given number of units, units being lines or pages. Default units are lines.

    scroll_to_line( lineNum )

Scroll to position line number lineNum at the top of the pane. The first line of a file is line 1.

    secondary_adjust()

Attached mouse-movement events to extend the secondary selection to the mouse position.

    secondary_or_drag_adjust()

Attached mouse-movement events to extend the secondary selection, or reposition the primary text being dragged. Takes two optional arguments, "copy", and "overlay". "copy" leaves a copy of the dragged text at the site at which the drag began. "overlay" does the drag in overlay mode, meaning the dragged text is laid on top of the existing text, obscuring and ultimately deleting it when the drag is complete.

    secondary_or_drag_start()

To be attached to a mouse down event. Begins drag selecting a secondary selection, or dragging the contents of the primary selection, depending on whether the mouse is pressed inside of an existing primary selection.

    secondary_start()

To be attached to a mouse down event. Begin drag selecting a secondary selection.

    select_all()

Select the entire file.

    self_insert()

To be attached to a key-press event, inserts the character equivalent of the key pressed.