23. Glossary

<install_path>

The path to the directory where Sublime Text was installed.

action

In the Sublime Text package/plug-in context, and action is a Command that gets executed to do something within Sublime Text.

Buffer

sublime.Buffer class represents the data of a loaded file and additional metadata associated with 1 or more Views. In documentation, sometimes the term Buffer and a View are used interchangeably, though they are far from being the same.

Build System

Sublime Text comes with a beautiful and flexible subsystem to launch external programs. Because it is surrounded by information about the file you are currently editing, this framework is very convenient to use it to “do something” with the file you are editing – typically:

  • running it,

  • testing it, or

  • translating it into something else.

The whole concept of “building” is indeed the concept of translating something (considered source) into something else, whether it is a program or set of documentation, or whatever it is.

Because this subsystem is normally used to compile (or otherwise translate) the files of the current source-code project, this subsystem is referred to as the “Build System”.

See Build Systems for details.

Command

A sublime.Command object represents an action to be executed and can be referenced in many types of resource files. It may accept JSON-serializable arguments and can be defined in user plugins. See Commands for more details.

Command Palette

A pop-up for quick access to various Commands provided by Sublime Text’s core or a package. The Command Palette can be opened via ctrl+shift+p or via Tools > Command Palette....

Completion

Sublime Text Completions are yet another way to save typing and time by finishing words or inserting boilerplate text.

Console

Ctrl+` (Ctrl+backtick) (or View > Show Console) opens the console Overlay Panel at the bottom of the Sublime Text window, with 2 child panels: an output panel and below that, an input panel that allows you to send input directly into the Python interpreter that is executing plug-ins.

Context

A Context is an optional element of a Key Binding, that uses the key “context” in the Key Binding dictionary object. When present, it provides a possibly-complex condition under which that key combination can be applied.

See Key Binding Definitions for full details.

Context Menu

A Context Menu is a pop-up menu that opens as a result of right-clicking any of several objects in the Sublime Text GUI. (Some keyboards also have the ability to open Context Menus.)

The objects in Sublime Text that can host a Context Menu are (Context Menu names are in parentheses):

  • Sheets

    • Views (Context)

    • Images (Image Context)

    • Tabs (Tab Context)

  • Side Bar

    • OPEN FILES list (Tab Sidebar Context)

    • FOLDERS

      • Mount Points (Side Bar Mount Point)

      • Folders and Files, possible multiple items selected (Side Bar)

  • Status Bar

    • Encoding Status (Encoding)

    • Line Ending Status (Line Endings)

    • Indentation Status (Indentation)

    • Current Syntax Status (Syntax)

  • Overlay Panels

    • Console (Console Input Widget)

    • Find-in-Files Panel (Find in Files)

    • Other input panels (Widget Context)

The Context Menu content can be found (and customized) in Package Resource files in various Packages named

<context_menu_name>.sublime-menu

The default version of these are in the Default Package, and customizations of these can be found in various other Packages.

See Menus for more details.

Core Package

A shipped package that provides core functionality for Sublime Text.

cursor
caret

The insertion point, where keystrokes will change the file, a.k.a. “cursor”. “caret” is the preferred term.

data directory
<data_path>

Core concept and storage for all of Sublime Text’s customized resources. Refer to Data Directory for details.

Edit

A View’s sublime.Edit object is a collection of changes on the View’s Buffer performed through that View. Users cannot create Edit objects. Sublime handles this for us. But we must receive them as arguments in TextCommand.run() methods and pass them to View methods as arguments when those methods change the Buffer.

Editing Panel

The Editing Panel occupies the whole area to the right of the Side Bar (when the Side Bar is visible) and is where the Sublime Text user spends most of his time.

The Editing Panel contains 1 or more Focus Group Panels.

The Editing Panel can be made to display more than one Focus Group by invoking alternate Layouts.

To see examples of different Layouts, hold down the [alt+shift] keys and hit the following numbers in this sequence: 2, 3, 8, 9, and finally 1 to return to the original Layout. Each of those “areas” is called a Focus Group.

See Layouts for more details.

EOL

end of line

Event Listeners

sublime_plugin.EventListener class and sublime_plugin.ViewEventListener class call user-specified callbacks when an event happens. The former is “global” (application wide) and the latter is targeted at one specific View object.

executable directory
<executable_path>

The directory in which Sublime Text executable was installed. If you used a Windows Installer, it is likely C:\Program Files\Sublime |nbsp| Text\.

file base name
file stem

The part of the file name before the extension.

My_Language.sublime-build
^^^^^^^^^^^
     |
     +-- file stem (or base name)
file type

In the context of Sublime Text, a file type refers to the type of file as determined by the applicable .sublime-syntax syntax definition. However, this is an ambiguous term and in some instances it could also be used with the broader meaning it has in technical texts.

Focus Group
Focus Group Panel

A Focus Group Panel is a single sub-panel of the Editing Panel that contains 1 or more Sheets. While a Focus Group can host any number of Sheets, it can only display one Sheet at a time.

See Focus Group Panel for more details.

GUI

Graphical User Interface

Gutter

The area on either side of the text-editing area where line numbers, symbols, and colored markings can be drawn to convey certain meaning about the lines of text they are next to.

input handlers

sublime_plugin.TextInputHandler class and sublime_plugin.CommandInputHandler class are used to get information from the user, from within the Command Palette. For example, the command “Rename File” uses an object instantiated from the former, and the command “View Package File” uses an object instantiated from the latter. The pop-up previews in these objects use miniHTML.

input panel

An input area (a sublime.View object) allowing the user to free-form type.

installed Package

A user package inside the Installed Packages folder in the .sublime-package archive (.zip) format.

Key Binding

A Key Binding is a dictionary object that supplies Sublime Text with a possibly-conditional keyboard trigger that it should use to execute a command (with optional arguments) specified in the Key Binding’s definition. Key Binding dictionary objects are found in .sublime-keymap files.

See Key Bindings for more details.

Layout

A Layout controls how the Editing Panel divides its area among 1 or more Focus Groups. Sublime Text’s default Layout simply shows 1 Focus Group. That means the contents of only 1 file (Sheet) can be displayed at any given time. To display 2 or more Sheets simultaneously (e.g. side by side or one above the other), you need to invoke a Layout that hosts more than one Focus Group at a time.

To see some examples, hold down the [alt+shift] keys and then type these numbers(in this sequence): 2, 3, 8, 9, and then 1 again to return to the normal Layout.

Sublime Text’s Layout engine is extremely flexible. See Layouts for more information about how to control it to your liking.

Main Menu

Sublime Text’s Main Menu is the row of click-able words just under each Window’s Title Bar. See Menus for more details.

miniHTML

A subset of HTML and CSS that provides layout for things like pop-up windows that show information in a nice, readable format.

Minimap

A small, condensed version of your text file displayed along the right margin, providing a high-level view of the entire file. It helps users navigate large files more easily by allowing them to scroll quickly through the content.

Mount Point

A Mount Point is a top-level object in the Side Bar’s Folder List. It represents the top-level directory of a Directory Tree, which represents the computer’s file system below that directory, possibly filtered by the contents of the .sublime-project file.

Overlay
Overlay Panel

“Overlay” is short for “Overlay Panel”, which is an input/output Widget that is Sublime Text’s version of a GUI dialog box. Overlay Panels use Widgets to interact with the user. Example Widgets:

  • Buttons,

  • TextBoxes (instances of the sublime.View class)

  • miniHTML pop-up windows (Widgets for presenting information more complex than a single line of text). Hit [alt+shift+ctrl+p] to see an example.

Overlay Panel Examples:

  • At Bottom of Window

    • Find Overlay

    • Find-in-Files Overlay

    • Replace Overlay

    • Console Overlay

  • At Top of Window

    • Command Palette Overlay

    • Goto Anything Overlay

    • Overlays used by Packages to get user input

    • Custom user-created Overlays

  • Where Cursor Is

    • Current Scope Overlay ([alt+shift+ctrl+p] is an example of a miniHTML Widget)

Override Package

A special package that can override individual resource files of an installed Package or shipped Package.

See Overriding Whole Files from a Zipped Package for more details.

Package

A Package is a collection of files grouped together and given a name, that are focused on augmenting Sublime Text is some fashion. The files are called Package Resource files.

Package URL syntax always uses forward slashes as directory separators.

Key:

<ep>/Packages/:

Shipped packages (loaded first, do not touch)

<dp>/Installed Packages/:

ZIP files with extensions renamed to .sublime-package

<dp>/Packages/<pkg_name>/:

Unpacked package directories (also where Packages are developed)

<dp>/Packages/User/:

User overrides, loaded last, can apply to anything. Packages can be developed here as well in experimental stages. Can later be moved into %A%/Packages/<pkg_name>/ later.

Package Resource

A Package Resource is simply a Resource File that is part of a Package and therefore in a Package directory.

See Packages for more details.

PackageDev

A package that:

  • Eases the creation of snippets, syntax definitions, etc. for Sublime Text.

  • Brings with it:

    • enhanced syntax highlighting to Package Resource files

    • auto-completion in resource files

    • eases creation of package resources

panel

The term “panel” (lower case) refers to an independent area of a Window. This is a term used with almost any software application that interacts with the user using a GUI. The various panels involved with most Windows applications are (in typical top-to-bottom order):

  • Title Bar Panel

  • Main Menu Panel

  • Client Area Panel (this is where the user spends most of his time)

  • Status Bar Panel (some applications don’t have Status Bars)

The Client Area Panel is often subdivided into sub-panels of its own, depending on the application. As you can see, these form a tree structure within the application.

The “leaf” objects in this tree are normally referred to as “Controls” or “Widgets”, while “panels” are considered to be “containers” for other panels or Widgets.

Phantoms

sublime.Phantom class provides miniHTML “balloon messages” on things while editing, containing information for the user that is not part of the buffer being edited.

Plugin

Plugins are augmentations to Sublime Text implemented in Python. See Plugins for details.

Point

sublime_types.Point is an alias for an Integer. A Point indicates a location within a buffer. Specifically, it is an offset (in characters) from the start of a buffer, regardless of the current file’s encoding.

To keep things simple, when Sublime Text loads a file, no matter what platform it is on, it normalizes the line endings to just a single ASCII line-feed (LF, 0x0A) character between each line, so you don’t have to worry about how many characters are involved with line separation on any given platform. In other words, if Point a points to the last character on a line, Point a + 2 will always point to the first character on the next line.

Process

This term is used in the sense of a Process being a running program under an Operating System (OS). Sublime Text is designed internally so that one process handles all Sublime Text Windows open. As an intentional side effect, this also allows all windows and code(including code you wrote to customize Sublime Text) can share the same resources. For example, you could write code that could iterate through all open Sublime Text windows and do something with them, as a service to the user.

Project

A Project in Sublime Text is merely a collection of 0 or more top-level folders to be displayed in the Side Bar to make it easier for the user to open files and navigate within that directory structure. When a Project is stored on disk, it “remembers” that collection for the user. It’s file name is meant to convey the meaning of the scope of the work that was being performed with that particular file structure. Project files always have .sublime-project and can be, but do not need to be within any of the top-level folders contained in the Project.

When a project is saved to disk, a Workspace with the same name is saved alongside it.

See Projects for more details.

Quick Panel

An object used to get an item from a list of choices from a user (i.e. a filter-able drop-down list). The Command Palette [ctrl+shift+p] is such an object.

reaction

In the Sublime Text package/plug-in context, and reaction is a response to an event by an event handler.

Regex
Regular Expression

A Regular Expression is a pattern describing a certain amount of text. The name comes from the mathematical theory on which they are based. The term is often abbreviated as “regex”.

Regular Expressions provide a powerful way to both:

  • find text as well as

  • determining if certain text strings match certain patterns.

As such, Regexes are ubiquitous throughout the computer industry and many implementations have been implemented over the years. For example, Regular Expressions are instrumental and part of the core concepts in Compiler front-ends (the part that reads what the programmer wrote and translates it into an intermediate representations such as an Abstract Syntax Tree).

Because they are so well-established and well-understood by most programmers, programmers’ text editors almost always implement Regexes in their find and find-and-replace operations.

Sublime Text is no exception to this, although Sublime Text notably implements two distinct implementations of Regexes:

Note that Oniguruma Regex Library is NOT an extension of the Boost Perl Regex library; it is a separate Regex library that supports various character encodings and is used in different programming languages and applications. While both libraries provide Regex functionality, they are distinct projects with different features and implementations.

Region

A sublime.Region object represents a contiguous “area” within a Buffer. A Region object contains 2 Point values a and b indicating the beginning and ending of the Region. In true Python style, the 2nd Point contains the Buffer character offset of the character just after the last character in the Region.

A Region can represent:

  • a single selection Region (where the ordering of a and b are important), or

  • simply an area of the text buffer, where ordering is generally ignored.

If b == a, the Region is empty. If b < a, then the caret is shown on the left side of the Region. This has an impact on changing the selection Region with up- and down-arrow keys.

Resource File

A Package Resource file is any special file the Sublime Text uses. Examples:

- .sublime-settings      Modifies default settings     \
- .sublime-keymap        Implements key actions         >-- Behaviour and user input
- .sublime-macro         Stores replay-able key seq.   /
- .sublime-build         Launches external programs
- .sublime-snippet       Custom static text snippets
- .sublime-completions   Autocomplete entries
- .sublime-color-scheme  \
- .tmTheme                \
- .sublime-theme           >- Visual appearance.
- .hidden-color-scheme    /
- .hidden-tmTheme        /
- .sublime-commands      Adds cmds to Command Palette  \___ Operations and Menu
- .sublime-menu          Defines and modifies menus    /    items to trigger them
- .sublime-syntax        \
- .tmLanguage             \__ Add syntax highlighting support.
- .hidden-tmLanguage      /
- .tmPreferences         /
- .sublime-mousemap      Map commands to mouse-button clicks.
- .py                    Plugins add new :term:`Commands` and event handlers.
- *.*                    Any other files needed.  Examples:

    - documentation
    - configuration files
    - external scripts
    - tools
    - libraries
Scope

Scope is the “characteristics of the caret’s location in a text file”.

Syntax definitions make Sublime Text aware of the Scope for any given position in a file. They do so by generating scope names to provide metadata about language tokens. This metadata is updated on-the-fly every time the caret moves in any kind of document, but it is especially applicable in source code where the metadata reveals the nature of the area that the caret is currently sitting in (e.g. keyword, keyword category, number, symbol, comment, etc.).

See Scope, Selectors and Context for more details.

Selection

The term “selection” (lower case) in this documentation simply refers to a text selection in a View. However, when it is capitalized as “Section” (capitalized), is the name of a class: sublime.Selection. Each View has exactly one Selection object, which is the LIST of selection Regions within a View. In normal editing, there is only one Region in this list, and it is normally empty: the caret. However, Sublime Text supports any number of these in a View at any given time for special types of editing. Once that special editing action is complete, you can hit [Esc] to go back to having one caret again (selection).

Selector

A Selector is a string that is evaluated against the current Scope, and triggers a True or False result based on that evaluation. Its use is to determine whether a particular ‘thing’ is applicable based on the nature of the current caret location, i.e. its Scope.

If you’re familiar with CSS, Sublime Text Selectors behave like selectors in a CSS file: they are a very efficient method of determining whether something “applies” or not.

See Scope, Selectors and Context for more details.

Settings

The Sublime Text application has exactly one sublime.Settings object. That object is a representation of the current settings, and can be converted to a Python dictionary for viewing and use, though that dictionary is only a copy, so modifying it does not change the settings. There is, however, a way this can be done for individual Views. Settings are stored in, and loaded from Sublime-relaxed-JSON format files with the extension .sublime-settings. See Settings for more information.

Sheet

sublime.Sheet class displays and manages contents shown within a tab. There are three types of Sheets in Sublime Text 4:

  • text sheet (contains a View enabling user to view/edit a Buffer)

  • image sheet (displays an image from a variety of image formats)

  • HTML sheet (displays “mini HTML”)

shipped Package

A Package that is provided by Sublime Text on every installation. Shipped Packages can be “visible” as files in <app_dir>/Packages/ or built into Sublime Text, in which case they are not visible.

Side Bar

In Sublime Text, the Side Bar in a possibly-hidden panel on the left side that helps the user with opening and navigating among open files.

Snippet

In Sublime Text, a Snippet is a “smart template”, whose content is defined in a simplified XML file, at most one Snippet per file, with a .sublime-snippet extension. Snippets can optionally have any number of “fields” each with optional default and/or placeholder text in them. See Snippets for details.

Status Bar

The Status Bar is the bar at the bottom of any Window that shows a variety of helpful information about the states of various parts of that window. See Status Bar for more details.

Sublime-relaxed-JSON format

Normal JSON except:

  • EOL comments are allowed with //, and

  • a trailing comma after last list item is allowed (like in Python)

Target

The term “target” has special meaning in the Sublime Text Build System. It means the external program that is to be launched – not its output.

In special cases, a Sublime Text Command can be the Target, in which case it executes fully within Sublime Text, not as an external process.

Terminus

A package that brings a real terminal to Sublime Text, with access to the Sublime Text Python API. It:

  • adds a terminal directly to Sublime Text,

  • works on Windows, Linux and MacOS,

  • can be used in Sublime-build files to execute builds.

TextCommand

A TextCommand is a class that inherits from sublime.TextCommand. It is the only type of command where:

  • you can edit or do things with the buffer, and

  • you get an Edit object as an argument, enabling you to make calls on View methods that require an Edit object as an argument.

User Package

A Package installed or managed by the user. User Packages live in <data_path>/Packages/User/. See Data Directory for more details.

View

sublime.View class is the graphical display and editing interface of a Buffer. Multiple Views can show (and allow editing on) the same buffer.

In a Command’s run() method, self.view is automatically populated with a reference to the View the command is attached to.

In the Console input panel, view is automatically attached to the View that most recently had keyboard focus. Thus view.run_command('command_name') for example runs that command (which may be supplied by a Plugin).

The input Widgets in the “Find/Replace” dialogs are also View objects, as well as the console input and display panels, and the input area of the Command Palette.

Widget

An object within a GUI that interacts with the user and is normally limited to one type of input or output. Examples: text display, clicks, free-form typing, selecting an item from a list. They are the “leaf” objects in the tree structure that makes up the GUI. Examples:

  • Labels (display text)

  • Buttons

  • TextBoxes

  • Drop-Down Lists

  • Menu Items

Widgets can contain other Widgets, so they are not always “strictly” leaf objects in the tree.

Most Widgets (except Labels) accept various kinds of user input (e.g. keyboard, mouse, etc.).

Window

sublime.Window class managing the container for the Sublime Text UI (opened document tabs, side bar, etc.), with minimize, maximize and close buttons on the right side of title bar. Each window always has exactly 1 project open at any given time. There can be any number of Windows open at the same time, though all of them are always controlled by at most a single Process.

Workspace

Projects in Sublime Text are made up of at least two files: the .sublime-project file, which contains the project definition, and the .sublime-workspace file, which contains user specific data, such as the open files, the modifications to each, and various application states such as what files were open, cursor positions, tab ordering, etc.. It is possible to have more than one .sublime-workspace file per project, and either the workspace or the project file can be opened (Project > Open Project...) to return to your “last session” with that project, or to a particular session by opening the workspace file. You might want to have more than one workspace file if you regularly edit 2 or more different groups of files in that project and the tasks are logically separate, or that use different Window layouts, etc..

See Projects for more details