Textadept Manual

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

Introduction

Textadept is a fast, minimalist, and ridiculously extensible text editor for Linux and Mac OSX. The C/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/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

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.

Compiling & Build-time Configuration

Note: A knowledge of Scintilla internals may be necessary!

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.

Similarly, lexer.lua.home and lexer.lua.script must match the location of textadept/ in src/textadept.c's set_default_editor_properties function.

You may now choose to edit default properties in src/textadept.c. Keep in mind however that they can be edited more easily in the Lua buffer_new and view_new event handlers. There is no real advantage to doing it in C. For reference, set_default_editor_properties is called when Textadept loads or when a view is split; set_default_buffer_properties is called when Textadept loads or creates a new buffer/file. You can also edit the default style/font in src/textadept.c's new_scintilla_buffer function. Remember that font names prefixed by a ! use Pango for rendering and colors are defined by red | green << 8 | blue << 16. Editing other default styles is discussed later.

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.

Using Textadept

Remember that 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 is only aimed to answer the most frequent questions. Most everything else is covered in the LuaDoc.

Also, a decent knowledge of Lua is assumed.

Key Commands

Textadept is very keyboard-driven. Learn or create your own key commands in core/ext/key_commands.lua. The keys, buffer, view, and textadept LuaDoc pages will be useful.

To enable standard key commands, edit /init.lua by changing

--require 'ext/key_commands_std'
require 'ext/key_commands'

to be

require 'ext/key_commands_std'
--require 'ext/key_commands'

Menus

Textadept does not have a menu built in, but you can create and add one. This is done through the textadept.gtkmenu function. The menu can then be shown by assigning 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 you have to assign some actions to menus. This is done through the 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.

To enable a standard menu, edit /init.lua by changing

--require 'ext/menu.lua'

to be

require 'ext/menu'

Colors, Fonts, etc.

Scintilla's default styles (32-39) can be changed in lexers/lexer.lua's DefaultTypesAndStyles function. Standard colors are in the colors table, and standard styles are located below the style function. Most lexers use these same colors and styles, so instead of having to change each individual lexer style, most styles can be changed in the same place.

Changing the style of the project manager is different. Consult the LuaDoc for how to do this.

Lexers

Consult the in-depth documentation on lexers in in the LuaDoc.

Modules

Modules are basically Lua packages of functionality. They can be generic or language-specific. See the LuaDoc for modules for more information.

File Types

File types can be recognized and associated with lexers through the core/ext/mime_types.lua file. By default Textadept identifies most file types for the lexers it has. To add a new file type, follow this series of steps:

  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 lexers/lexers_doc.txt 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.

Project Manager/Side Pane

The side pane can function as pretty much any treeview-based data structure, not just a project manager. See the layout and take a look at the existing browsers in core/ext/pm/*_browser.lua.

Find/Replace

See LuaDoc

Events

List of built-in events.

Lua Command Entry

Pressing Control+C will bring up the Lua command entry. It uses Textadept's Lua state, so be careful. It is useful for debugging, inspecting, and entering buffer or view commands (if you forget key shortcuts). Use textadept.print instead of print. The former prints to a clean buffer, and the latter prints to standard out. Tab-completion is available. You can press Tab and a list of available candidates is dislayed. Use the arrow keys to make a selection and press Enter.

Valid XHTML 1.0!