31. Glossary

<data_path>

The storage directory for all of Sublime Text’s customized resources. Refer to Data Directory for details.

<executable_path>

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

<install_path>

The path to the directory where Sublime Text was installed.

action

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

Buffer

The container for the edited content of a View, representing that content as a contiguous sequence of possibly-multi-byte characters. Line separators within the Buffer are always a single newline (’\n’, 0x0A) character, regardless of the file’s line-endings. For platforms that use different line separators for text stored in files, this translation occurs during loading and saving, but the line separators in Buffers are consistent across all platforms.

See Buffer for more information.

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.

caret
cursor

The insertion point, where keystrokes will change the file, a.k.a. “cursor”. “caret” is the preferred term when it means the “cursor” when no text is selected.

Channel

A “Channel” is a special term in the context of the Package Control Package and is the first link in the chain of infrastructure it uses to list, install and uninstall packages on individual workstations running Sublime Text. It is a JSON file that contains URLs to Repositories of Sublime Text Packages (not to be confused with Git repositories).

Think of it as a “communication path” through which the Package Control Package can acquire Packages.

See Distribution Data Tree for more details.

Client Area

The Client Area of a window is a Windows OS term and it means the portion of an application’s window below the Main Menu (if one is present) and above the Status Bar (if one is present). This is generally considered the “production area” of the application.

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
Console Panel

Ctrl+` (Ctrl+backtick) (or View ‣ Show Console) opens the Console Panel at the bottom of the Sublime Text window, with 2 child Views: an output View acting as read-only display area (where you can see debugging and logging output), and input View acting as a “textbox” (in Windows UI terms) allowing you to send input directly into the Python interpreter that is executing Plugins, allowing you to directly make calls to the Sublime Text API if/when needed.

See Console Panel for more details.

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)

  • 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.

Control

In the context of a GUI, a control is an input/output object on the screen that interacts with the user. “Control” is a term that stems from the Windows operating system. The preferred cross-platform term is Widget. See Widget for more details and examples.

Core Package

A shipped Package that provides core functionality for Sublime Text.

data directory

See <data_path>

Default Key Map

The .sublime-keymap files in the Default Package that applies to the current platform. See Key Map

DIP

DIP stands for device- or density-independent pixels, a unit of length based on a “reference screen” with 160 DPI. Thus, 1 DIP = 1/160 inch = 0.00625 inch.

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 Area

The Editing Area 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 Area contains 1 or more View Groups.

The Editing Area can be made to display more than one View 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 View Group.

See Layouts for more details.

EOL
BOL

Both EOL and BOL are abbreviations for “end of line” and “beginning of line” respectively, and are terms commonly used in a programming context.

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

See <executable_path>

file base name
file stem
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

“Focus” as a noun is short for “keyboard focus”, i.e. where keystrokes will be received when they occur.

Used as a verb, it means “move keyboard focus to”, and is usually followed by the direct object which is what part of the UI receives focus.

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.

hook

An OS “hook” is a mechanism that allows an application to intercept and respond to events such as messages, mouse actions, and keystrokes. It is a point in the system message-handling mechanism where an application can install a subroutine to monitor the message traffic in the system and process certain types of messages before they reach the target window procedure.

A hook subroutine can report back (typically via return value) that it “handled” the event, so that it is not passed “downstream” to other applications.

The sequence such subroutines are called is important, and the OS itself is always first in that sequence, thus enabling it to monopolize (if designed) certain keypresses that are not intended for applications to handle. Examples of such keypresses for Windows:

  • Alt-Space (normally opens a control menu in upper-left corner of window)

  • Alt-Tab (normally opens an application selection popup that allows users to change keyboard focus to a different application without using the mouse)

  • Alt-KeypadN (‘N’ => [0-9]) when NumLock mode is active (reserved by the OS for generating non-ASCII characters through the keyboard)

See Windows Hooks for more details about how this functions on Windows.

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.

JSONC format

JSONC (JSON with Comments) is normal JSON except:

  • EOL comments are allowed with //, and

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

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.

Keymap
Key Map

A *.sublime-keymap file. The Default Package contains these files:

  • Default (Windows).sublime-keymap

  • Default (Linux).sublime-keymap

  • Default (OSX).sublime-keymap

keypress

A keypress is a single keystroke with possible Ctrl, Alt, Shift and ⊞ (⌘ on OSX) modifier keys connected with it.

Each keypress has a “main” key, which is the name for that key. Note that only unshifted key names can be used with modifier keys in Key Bindings.

See Main Key Names to see the list of valid main key names.

keypress sequence

A keypress sequence is a specific sequence of single keypresses which are bound to a single Command. Example: Ctrl-K, Ctrl-U is bound to the Sublime Text Command upper_case.

Layout

Layout has 2 distinct meanings in Sublime Text:

  1. Window Layout, and

  2. View Layout.

Macro

A macro is a series of recorded editing operations that can be saved and played back any number of times.

See Macros for more details.

Main Menu

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

miniHTML

A subset of HTML and CSS that provides layout for things like Popup overlays that show information in a nice, readable format. Phantom

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.

Multi-select

A View Group is said to have “multi-select” when multiple Views are selected in the same View Group into side-by-side editing mode.

Namespace Package

A Namespace Package is a special type of Python package not represented by a parent/__init__.py file, but may itself contain sub-packages. Namespace packages are a mechanism for splitting a single Python package across multiple directories on disk. It does this via the Python package’s __path__ list. Once populated, subsequent import operations that use that package’s name (__package__ as found in sys.modules), use that __path__ list to find its sub-packages.

See Namespace Packages and PEP 420 for more details.

OS

Operating System

Overlay

An Overlay is Sublime Text’s implementation of a GUI Dialog Box. It is called an Overlay because it is anchored to, and temporarily overlays part of the current View Group, usually at the top of the current View Group. Overlays are used to gather user input and/or perform certain types of actions that sometimes require more than a single key-stroke to complete.

See Overlay for more details.

Compare Panel.

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 Sublime Text’s primary mechanism for acquiring and adding features and capabilities to Sublime Text that are not shipped with Sublime Text out of the box. You can acquire Packages from the Sublime Text New Package Control Hub, from 3rd parties, or you can create them yourself if you are so inclined.

A Package is a collection of files grouped together and given a name, that are focused on augmenting Sublime Text in 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 <dp>/Packages/pkg_name/ later.

See also

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
Panel

Lower-case “panel” (lower case) is a generalized GUI term that refers to an independent area of a Window. Panels are made to sit alongside each other, not overlaying other parts of the window. The various panels involved with most Windows applications are (in typical top-to-bottom order):

  • Title Bar

  • Main Menu

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

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

The Client Area 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.

Because Sublime Text has its own official “thing” called a Panel (which is indeed a panel in this sense), in this documentation, the use of the term “panel” in this sense is minimized so as to avoid confusion. Instead we use “bare terms” without the word “panel”, such as “Title Bar” and “Editing Area” instead of “Title Bar Panel” and “Editing Panel”

Capitalized “Panel” in the Sublime Text context refers to Sublime Text’s implementation of a GUI Tool Palette (a dialog box that stays open and can be interacted with in order to assist in some way with the production activity in the main window). Panels are found at the lower part of the Window and provide a semi-permanent location for sets of Widgets used in continued editing operations.

Example: the Find Panel continues to highlight whatever text is entered there, as long as the Find Panel is open. This continue highlighting can be very useful in different circumstances while you are editing.

See Panel for more details.

Compare Overlay.

Phantom

sublime.Phantom class provides miniHTML “balloon messages” on things while editing, containing information or clickable links or icons for the user that is not part of the buffer being edited, but it does displace text. They can be:

  • in-line (between characters in a View’s row), or

  • between rows.

Between-row Phantoms are used in Build Systems to display error messages. (See exec.py in the shipped Default Package for an example of how they are used. exec.py contains the ExecCommand WindowCommand and the utilities that go with it, which is the default method of launching an external program used by Build Systems.)

The PackageDev Package uses Phantoms when you edit Any type of Settings. For example: Preferences ‣ Settings opens a side-by-side layout with Settings files. On the left Settings file (read-only) it places a “pencil” icon between the setting name and its value. This “pencil” icon is an inline Phantom. Clicking on it copies the setting to the right (editable) file which can be saved to override that setting.

See Phantoms for more details.

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.

Popup

An Overlay that contains miniHTML to convey information to the user, and overlays part of a View’s editing area.

See Popups for more details.

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

“Quick Panel” is Sublime Text’s implementation of a widget that behaves like a dropdown list. It is a Widget 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 and Goto Anything Ctrl-P are such objects. It has an input area at the top which allows you to type information which helps it filter down the list of items to be selected from (via a Fuzzy Match algorithm).

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, thus enabling those two values to be used in slice operations if/when the buffer is represented as a Python string.

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 a < b, then the caret is shown on the right side of the Region. If b < a, then the caret is shown on the left side of the Region. This has an impact on how the selected text area is changed when Shift-Up and Shift-Down arrow keys are used within the text being edited.

Repository

A “Repository” is a special term in the context of the Package Control Package and is a link in the chain of infrastructure it uses to distribute Packages to Sublime Text users across the world. It is not a Git repository (as the name might suggest), but is a JSON file which contains (directly and indirectly) JSON objects that describe individual Sublime Text Packages—enough information to allow the Package Control Package and its infrastructure to provide the services it provides, including listing, installing and uninstalling packages on user workstations with a maximum of convenience and a minimum of human effort.

See Distribution Data Tree for more details.

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 especially applicable in source code where it reveals the nature of any given location in the file (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. Furthermore, each such Region may or may not be empty: if a Region has text selected, this can be detected by that Region’s a and b attributes containing different indices into the buffer. Once that special editing action (with multiple carets/selections) is complete, when the user hits the Esc key, the View goes back to having one caret (selection) again.

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

Settings control Sublime Text’s behavior, or that of one of its Packages.

See Settings for more details.

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”)

See Sheet for more details.

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. See Side Bar for more details.

side-by-side editing

Side-by-side editing occurs when a View Group has multiple tabs (Views) selected making them editable in a side-by-side “mini layout” within that View Group.

See Side-by-Side Editing for more details.

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.

Syntax

Sublime Text uses Syntax definition files (either .sublime-syntax or .tmLanguage files) for syntax highlighting. The format for these files is covered by the following references:

Tab

In the Sublime Text context, a Tab is a part of a Sheet that carries the name of the View contained therein. If you open a new Window via any method other than mouse-dragging and existing Tab, the sheet and view that shows is considered “transient”, and has no Tab. As soon as you start typing in that View, Sublime Text gives the view a name, the name appears in the Tab, and the View (and its containing Sheet) are no longer “transient”. View names can also appear in italics when the View is “semi-transient”—when you have merely single-clicked on a file in the Side Bar, but have not officially opened it or started editing it yet.

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_plugin.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.

transient

In English, “transient” means “lasting only a short time”. In the Sublime Text context, this term is applied to Sheets when they are are temporary.

When you close all the views in a Window, Sublime Text opens a transient sheet with no tab. The reason it has no tab is because it is not associated with a file name yet. In this state it is considered “transient” and its sheet.is_transient() method will return True, and its sheet.is_semi_transient() method will return False.

When you single-click on files in the Side Bar, note that they are displayed in a Sheet with a Tab with their filename displayed in italics. If you click on another file, the same tab is used, and the new filename is displayed in its place, replacing the original. In this state, the filename does not appear in the OPEN FILES list in the Side Bar. This state is “semi-transient”, and it’s sheet.is_transient() method will return False, and its sheet.is_semi_transient() method will return True.

When a Sheet is in the “semi-transient” state, if you

  • File ‣ Open File... from the menu,

  • double-click the filename in the Side Bar,

  • double-click the Tab (when it is already showing in “transient” mode), or

  • start editing it,

it will promote it to being “open”, and its sheet.is_semi_transient() method will thereafter return False.

UI

User Interface

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 thus allow editing on) the same buffer. A View can be in read-only mode.

In a TextCommand’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 are the input and display areas of the Console panels, and the input area of the Command Palette. See sublime.View::element() function docstring for a list of the different places in the Sublime Text UI that Views play a role.

View Group
Group
Pane

A View Group (sometimes referred to as just a “group”) is a single sub-pane of the Editing Area that contains 0 or more Sheets. While a View Group can host any number of Sheets, it only displays one Sheet at a time. In the Sublime Text API, it appears that View Groups were once referred to as “panes” (perhaps since they resemble “window panes”) based on the presence of these commands:

  • new_pane (means open new View Group with current View, bound to Ctrl-k, Ctrl-Up in default key bindings),

  • new_pane (means open new View Group without current View, bound to Ctrl-k, Ctrl-Shift-Up in default key bindings),

  • close_pane (means close View Group if there is more than 1, without closing the current View, bound to Ctrl-k, Ctrl-Down).

See View Group for more details.

View Layout

The term “Layout” is used in this context because the Viewport API has several methods containing the term “layout”, so you need to know what it means, because it is unique to Sublime Text.

A View’s “Layout” is the entire rectangular area of existing text in a View’s Buffer, rendered in the current font and font size, whether it is visible or not.

The Layout’s dimensions are exactly the DPI width and height of the text itself, after being rendered with the current font in the current font size.

If the amount of text in a View is smaller in width and height than the Viewport, then the Layout’s dimensions are smaller than the Viewport, since it is only the DIP width and height of the text itself. If the View’s vertical scroll bar is scrolled all the way to the top, then this means that all the text in the Layout will be visible in the Viewport.

As the text grows in length and width, so do the Layout’s dimensions. When the width of the text (and thus the Layout’s width) grows wider than the width of the Viewport, a horizontal scroll bar appears at the bottom of the View. (Incidentally, the appearance of the horizontal scrollbar causes causing the Viewport’s height to shorten by the height of the scrollbar, typically 15 DIP.) No matter how large the text is vertically or horizontally, the dimensions of the Layout are the dimensions of the rendered text itself, and these can be larger or smaller than the dimensions of the Viewport. When they are larger in either direction, the Viewport is a “window” into the Layout.

Compare Viewport.

View Layout Coordinates

(x,y) coordinates in DIP units of a point in the rendered text of a View’s Buffer. These are used to translate a “position in the Layout” to a particular point in the text in the View’s Buffer, or vice versa. Piont (0,0) is the upper-left-most corner of the first character in the Buffer, and positive Y proceeds downward.

Viewport

Like the CSS Viewport (which is the visible area of a web page), a Sublime Text View has a Viewport, which is the visible area of text in the View’s Buffer. It exists between the left and right gutters and above any scrollbar at the bottom of the View. When a horizontal scrollbar appears at the bottom of the View, the Viewport shortens by that dimension (typically 15 DIP).

See Viewport for more details.

Compare View Layout.

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 (Sublime Text’s implementation is called a View)

  • Drop-Down Lists (Sublime Text’s implementation is called a Quick Panel)

  • Menu Items

  • Checkboxes

  • Radio Buttons

  • Tabs

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 OS Process.

Window Coordinates

(x,y) coordinates in DIP units of a point in the window’s Client Area. These are used to translate a “position in the window” (e.g. from a mouse cursor) to a particular point in the text in the View’s Buffer, or vice versa. Point (0,0) is the upper-left-most corner of the window’s “Client Area” (about 4 DIP below and about 7 DIP to the left of the “F” in the “File” menu). Positive Y proceeds downward. This term is specific to Sublime Text.

Window Layout

In the context of window.set_layout() and window.run_command("set_layout", ...) Command, a Window Layout controls how the Editing Area divides its area among 1 or more View Groups. Sublime Text’s default Layout simply shows 1 View 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 View 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.

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