Zed Development: Glossary
These are some terms and structures frequently used throughout the zed codebase.
This is a best effort list and a work in progress.
Naming conventions
These are generally true for the whole codebase. Note that Name can be anything
here. An example would be AnyElement
and LspStore
.
AnyName
: A type erased version of name. ThinkBox<dyn NameTrait>
.NameStore
: A wrapper type which abstracts over whether operations are running locally or on a remote.
GPUI
State menagement
App
: A singleton which holds the full application state including all the entities. Crucially:App
is notSend
, which means thatApp
only exists on the thread that created it (which is the main/UI thread, usually). Thus, if you see a&mut App
, know that you're on UI thread.Context
: A wrapper around theApp
struct with specialized behavior for a specificEntity
. Think of it as(&mut App, Entity<V>)
. The specialized behavior is surfaced in the API surface ofContext
. E.g.,App::spawn
takes anAsyncFnOnce(AsyncApp) -> Ret
, whereasContext::spawn
takes anAsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret
.AsyncApp
: An owned version ofApp
for use in async contexts. This type is still notSend
(soAsyncApp
= you're on the main thread) and any use of it may be fallible (to account for the fact that theApp
might've been terminated by the time this closure runs). The convenience ofAsyncApp
lies in the fact that you usually interface withApp
via&mut App
, which would be inconvenient to use with async closures;AsyncApp
is owned, so you can use it in async closures with no sweat.AppContext
A trait which abstracts overApp
,AsyncApp
&Context
and their Test versions.Task
: A future running or scheduled to run on the background or foreground executor. In contradiction to regular Futures Tasks do not need.await
to start running. You do need to await them to get the result of the task.Executor
: Used to spawn tasks that run either on the foreground or background thread. Try to run the tasks on the background thread.BackgroundExecutor
: A threadpool runningTask
s.ForegroundExecutor
: The main thread runningTask
s.
Entity
: A strong, well-typed reference to a struct which is managed by gpui. Effectively a pointer/map key into theApp::EntityMap
.WeakEntity
: A runtime checked reference to anEntity
which may no longer exist. Similar tostd::rc::Weak
.Global
: A singleton type which has only one value, that is stored in theApp
.Event
: A datatype which can be send by anEntity
to subscribersAction
: An event that represents a user's keyboard input that can be handled by listeners Example:file finder: toggle
Observing
: reacting entities notifying they've changedSubscription
: An event handler that is used to react to the changes of state in the application.- Emitted event handling
- Observing
{new,release,on notify}
of an entity
UI
View
: AnEntity
which can produce anElement
through its implementation ofRender
.Element
: A type that can be laid out and painted to the screen.element expression
: An expression that builds an element tree, example:
#![allow(unused)] fn main() { h_flex() .id(text[i]) .relative() .when(selected, |this| { this.child( div() .h_4() .absolute() etc etc }
Component
: A builder which can be rendered turning it into anElement
.Dispatch tree
: TODOFocus
: The place where keystrokes are handled firstFocus tree
: Path from the place thats the current focus to the UI Root. ExampleTODO
Zed UI
-
Window
: A struct in zed representing a zed window in your desktop environment (see image below). There can be multiple if you have multiple zed instances open. Mostly passed around for rendering. -
Modal
: A UI element that floats on top of the rest of the UI -
Picker
: A struct representing a list of items in floating on top of the UI (Modal). You can select an item and confirm. What happens on select or confirm is determined by the picker's delegate. (The 'Model' in the image below is a picker.) -
PickerDelegate
: A trait used to specialize behavior for aPicker
. ThePicker
stores thePickerDelegate
in the field delegate. -
Center
: The middle of the zed window, the center is split into multiplePane
s. In the codebase this is a field on theWorkspace
struct. (see image below). -
Pane
: An area in theCenter
where we can place items, such as an editor, multi-buffer or terminal (see image below). -
Panel
: AnEntity
implementing thePanel
trait. These can be placed in aDock
. In the image below we see the:ProjectPanel
in the left dock, theDebugPanel
in the bottom dock, andAgentPanel
in the right dock. NoteEditor
does not implementPanel
and hence is not aPanel
. -
Dock
: A UI element similar to aPane
which can be opened and hidden. There can be up to 3 docks open at a time, left right and below the center. A dock contains one or morePanel
s notPane
s. (see image). -
Project
: One or moreWorktree
s -
Worktree
: Represents either local or remote files. -
Multibuffer: A list of Editors, a multi-buffer allows editing multiple files simultaneously. A multi-buffer opens when an operation in Zed returns multiple locations, examples: search or go to definition. See project search in the image below.
Editor
Editor
: The text editor, nearly everything in zed is anEditor
, even single line inputs. Each pane in the image above contains one or moreEditor
instances.Workspace
: The root of the windowEntry
: A file, dir, pending dir or unloaded dir.Buffer
: The in-memory representation of a 'file' together with relevant data such as syntax trees, git status and diagnostics.pending selection
: You have mouse down and you're dragging but you have not yet released.
Collab
Collab session
: Multiple users working in a sharedProject
Upstream client
: The zed client which has shared their workspaceDownstream client
: The zed client joining a shared workspace
Debugger
DapStore
: Is an entity that manages debugger sessionsdebugger::Session
: Is an entity that manages the lifecycle of a debug session and communication with DAPSBreakpointStore
: Is an entity that manages breakpoints states in local and remote instances of ZedDebugSession
: Manages a debug session's UI and running stateRunningState
: Directily manages all the views of a debug sessionVariableList
: The variable and watch list view of a debug sessionConsole
: TODOTerminal
: TODOBreakpointList
: TODO