Textadept Manual

Written by Mitchell Foral. (mitchell{att}caladbolg.net)

Introduction

Textadept is a fast, minimalist, and ridiculously extensible text editor for Linux, Mac OSX, and Windows. The C++ core is just over 1600 lines of code (excluding comments and blank lines) and contains the bare framework for a text editor. More than half of the C++ base is the Lua extension, and nearly everything in Textadept is controlled by Lua, making the editor's extensibility almost limitless.

Why Another Text Editor? Why Lua?

Previously, I used SciTE for the longest time. It is small, fast, and extensible with Lua. You may know that I am the author of two SciTE-related projects: scite-tools and SciTE-st. scite-tools is a collection of Lua scripts that provide powerful editing capabilities such as snippets, dynamic key commands, and programming language modes. On the other hand, SciTE-st has a "fork" of Scintilla that uses dynamic Lua lexers instead of static C++ ones.

While SciTE is relatively small and fast, I think it is still a bit too big. My vision of a "perfect" editor is a small static core with the ability to add dynamic extensions to it on a per-user basis, much like Emacs and VIM in terms of their extensibility, though the applications themselves are far too big and bloated. A dynamic extension language would be required, but it has to be small and fast. Ruby and Python are far too large for the scope of this project. Having used Lua heavily in both of my projects, I fell in love with the language's speed and elegance, so it was a natural choice.

Main Features

Textadept is a mesh between SciTE-st and scite-tools with some extra UI features: split views, a side pane for open buffers, project management, symbol browsing, etc., integrated find replace, and a Lua command entry.

Overview of Changes to Scintilla (Scintilla-st)

  • Dynamic lexer that replaces Scintilla's standard ones.
  • AutoCSeparator is | (pipe), not ?.
  • Calltip colors match dark color scheme.
  • Added new messages:
    • SCI_GETLEXERLANGUAGE([unused], const char* languageName) Returns the name of the lexer currently loaded.
    • SCI_GETSTYLENAME([unused], const char* styleName) Returns the name of the style under the caret.
  • Removed some default key commands: Ctrl+L, Ctrl+Shift+L, Ctrl+T, Ctrl+Shift+T, Ctrl+D, Ctrl+U, Ctrl+Shift+U

Requirements

Note: Previous releases of Textadept had external dependencies like Lua and Zenity. These dependencies are no longer required since Lua is now built into Textadept and I ported Zenity to Lua-GTK mimicking CocoaDialog. Also, Textadept exports Lua symbols so the lpeg, bit, and gtk libraries work out of the box (additional Lua libraries should work too).

Install (Linux or Mac OSX)

After downloading and unpacking Textadept to any directory, you have two options: move it to /usr/share/textadept (may require root privilages) or move it to a different directory. If you choose the latter, you will need to recompile Textadept after making some changes discussed below. Then create a symlink from the textadept/textadept binary to /usr/bin/ or somewhere in your PATH.

Install (Windows)

Unpack Textadept into any directory and it's all set to go.

Compiling (Linux or Mac OSX)

If the textadept/ directory is not in /usr/share/textadept, you must edit src/textadept.h's textadept_home variable to reflect the path to textadept/. Remember that two \'s are necessary to make one \ character in a C/C++ literal string.

If you wish to change or add to the default key commands for non-Scintilla widgets that are built into the UI, search the various C source files for *_keypress functions. For key codes, refer to GDK's gdkkeysyms.h in your system's include directory (typically /usr/include).

There should be a scintilla.a file in src/scintilla-st/bin/. If there is not or you cannot use it for whatever reason, you will have to download scintilla-st from the Textadept website and replace the src/scintilla-st directory with it. More on this in a bit.

You are now ready to run make in the src/ directory which will compile Textadept. If you haven't already, create a symlink from the binary to /usr/bin/ or elsewhere in your PATH. You can now move on to the next section.

If you had to download or recompile scintilla-st, open its gtk/makefile and make sure its INCLUDEDIRS contains the path to Textadept's Lua header files (src/lua/). Add them if necessary like so: -Ipath/to/lua/headers. Then run make inside gtk/ before trying to compile Textadept.

Compiling (Windows)

Good luck. (TODO:)

Configuration and Usage

Initialization

Textadept first loads core/init.lua to initialize its core funtionality. Then init.lua is loaded for all extensions. The extensions are in core/ext/. You can disable an extension by commenting it out (put a -- before the require statement.) In addition to extensions, generic modules can be loaded on startup. By default the _m.textadept module is loaded. It contains useful editing tools like snippets, multiple line editing, bookmarks, macros, and more. Finally, command line arguments are processed (Linux, Mac OSX only).

Events

Textadept is very event-driven. Events occur when users create new buffers, close existing ones, modify saved ones, enter text, etc. Each event has a set of handlers. Handlers are simply Lua functions executed in the order they are added for a specific event. There is a list of default events.

Users are not limited to default events. Handlers can be added for custom event names and handled by calling textadept.events.handle('name' [, args]).

Two events users might like to be aware of are the view_new and buffer_new events. They are handled whenever a new view or buffer is created. The default handlers are located in core/events.lua and contain code that sets the default properties of views and buffers such as properties, margins, markers, tab and indent styles, etc. Each user might want to provide their own custom configuration. Modifying these handlers is not necessary however. Theme files can be used to set these properties.

Themes

Themes are located in themes/ as well as lexers/themes/. Typically a Textadept theme goes hand in hand with a lexer theme. Each Textadept theme is its own folder with two files: view.lua and buffer.lua. Each is loaded apropriately. Each lexer theme is a single Lua source file with color and style definitions used by most lexers. By default, a 'scite' theme is provided for users accustomed to SciTE's color theme.

To tell Textadept to use a theme, set the _THEME variable in core/init.lua to be a string containing the theme's name. If _THEME is unset, an empty string, or a given theme cannot be loaded for whatever reason, the default Textadept dark theme is used (error messages are printed to standard out).

Note: The main font is style 32.

The Project Manager theme is different from Textadept and lexer themes. You can read about creating one in textadept.pm's LuaDoc.

Menus

Textadept has a built-in menu (ext/menu.lua) that provides access to pretty much every feature Textadept has, but you can replace it with a user-created one. Create a menu using textadept.gtkmenu and assign it to the textadept.menubar field. Here is an example.

local gtkmenu = textadept.gtkmenu
textadept.menubar = {
  gtkmenu {
    title = 'File',
    'gtk-new', 'gtk-open', 'gtk-save', 'gtk-close', 'separator', 'gtk-quit'
  },
  gtkmenu {
    title = 'Edit',
    'gtk-undo', 'gtk-redo', 'separator', 'gtk-copy', 'gtk-paste'
  }
}

Of course, this menu is pretty useless because no actions have been assigned to a menu item when it is clicked on. Actions can be performed by a menu_clicked event handler.

local actions = {
  New = textadept.new_buffer,
  Open = textadept.io.open,
  Save = textadept.io.save
}

textadept.events.add_handler('menu_clicked',
  function(menu_item)
    local f = actions[menu_item]
    if type(f) == 'function' then f() end
  end)

Similarly, popup menus can be created and shown with textadept.popupmenu.

Key Commands

Power users typically do not want to use menus. Textadept was designed to be very keyboard-driven and thus has a dynamic key command manager in textadept.keys. The standard key commands are contained in core/ext/key_commands_std.lua. Most features have a key command, but the ones that do not are labeled as -- TODO:. In addition to dynamic key commands, static ones exist for various Textadept UI elements that cannot be changed without recompiling Textadept.

  • Lua Command Entry
    • Enter - Executes entry text as Lua code.
    • Escape - Hides completion buffer if it is open.
    • Tab - Display possible completions.
  • Textadept
    • Escape - Hides the find/replace frame if it is open.
  • Project Manager
    • Ctrl+Tab - Refocuses the Scintilla window.
    • Escape - Refocuses the Scintilla window.
  • Find/Replace Frame
    • Enter - Find next or previous.

The following LuaDoc pages could be useful for adding or editing key commands: buffer, view, and textadept.

Project Manager

The project manager's name is a bit deceptive. It is really just a side pane that can hold any treeview-based data structure, not just a list of files in a project. Different 'browser's can display different data. For example, Textadept has browsers for opened buffers, a filesystem, modules, and more. All available browsers can be seen in core/ext/pm/. Each browser is activated by a special prefix in the PM text entry. when writing a new browser, it must contain all the functions as described in textadept.pm.browser.

Lua Command Entry

Access to Textadept's Lua state is available through this command entry. Do take caution as improper use could crash Textadept and/or cause loss of data in extreme cases. This entry is useful for debugging, inspecting, and/or entering buffer or view commands. On a side note, instead of using print, use textadept.print because the former prints to standard out while the latter prints to a Textadept output buffer.

Tab completion is available! Pressing Tab will display a list of available completions. Use the arrow keys to make a selection and press Enter to insert it.

Additional Information

The LuaDoc is a valuable resource for all aspects of Textadept. Not only does it contain Textadept's Lua API, it also contains textual documentation for the more complicated parts of the editor. This manual was not intended to completely comprehensive.

Lexers

Everything you could ever want to know about lexers and how to write them can be found in lexer's LuaDoc.

Modules

Modules are basically Lua packages of functionality. Earlier, generic modules were mentioned. They are typically always available. Other modules are language-specific. They are available for specific programming languages like Lua or C++. _m has more information.

File Types

File types can be recognized and associated with lexers through textadept.mime_types in core/ext/mime_types.lua. Textadept can identify a good amount of file types, but if one is not recognized, here is what to do:

  1. Look in the languages table. Is the language for your file type supported? If not, add it. As indicated, each entry contains a language name and its associated lexer in lexers/. If a lexer is not available, you can write one. Consult lexer for excellent documentation.
  2. Look in the extensions table. Is your file extension supported? If not, add the extension and assign it a language defined in the languages table.
  3. If you added a new language, do you want extensionless files to be recognized by their shebang line? If so, add it to the shebangs table.
  4. If you added a new language, do you want extensionless files to be recognized by a pattern match on the file's first line? If so, add the pattern to the patterns table.

Valid XHTML 1.0!