iced_code_editor/lib.rs
1//! A high-performance code editor widget for Iced.
2//!
3//! This crate provides a canvas-based code editor with syntax highlighting,
4//! line numbers, and text selection capabilities for the Iced GUI framework.
5//!
6//! # Features
7//!
8//! - **Syntax highlighting** for multiple programming languages
9//! - **Line numbers** with styled gutter
10//! - **Text selection** via mouse drag and keyboard
11//! - **Clipboard operations** (copy, paste)
12//! - **Custom scrollbars** with themed styling
13//! - **Focus management** for multiple editors
14//! - **Dark & light themes** support with customizable colors
15//! - **Undo/Redo** with command history
16//! - **Command palette** (`Ctrl+Shift+P`), extensible with the host's own commands
17//! - **Optional Vim mode** with Normal, Insert, Visual, and Visual Line modes
18//!
19//! # Example
20//!
21//! ```no_run
22//! use iced::widget::container;
23//! use iced::{Element, Task};
24//! use iced_code_editor::{CodeEditor, Message as EditorMessage};
25//!
26//! struct MyApp {
27//! editor: CodeEditor,
28//! }
29//!
30//! #[derive(Debug, Clone)]
31//! enum Message {
32//! EditorEvent(EditorMessage),
33//! }
34//!
35//! impl Default for MyApp {
36//! fn default() -> Self {
37//! let code = r#"fn main() {
38//! println!("Hello, world!");
39//! }
40//! "#;
41//!
42//! Self { editor: CodeEditor::new(code, "rust") }
43//! }
44//! }
45//!
46//! impl MyApp {
47//! fn update(&mut self, message: Message) -> Task<Message> {
48//! match message {
49//! Message::EditorEvent(event) => {
50//! self.editor.update(&event).map(Message::EditorEvent)
51//! }
52//! }
53//! }
54//!
55//! fn view(&self) -> Element<'_, Message> {
56//! container(self.editor.view().map(Message::EditorEvent))
57//! .padding(20)
58//! .into()
59//! }
60//! }
61//!
62//! fn main() -> iced::Result {
63//! iced::run(MyApp::update, MyApp::view)
64//! }
65//! ```
66//!
67//! # Themes
68//!
69//! The editor supports all native Iced themes with automatic color adaptation:
70//!
71//! ```no_run
72//! use iced_code_editor::{CodeEditor, theme};
73//!
74//! // Create an editor (defaults to Tokyo Night Storm theme)
75//! let mut editor = CodeEditor::new("fn main() {}", "rs");
76//!
77//! // Switch to any Iced theme
78//! editor.set_theme(theme::from_iced_theme(&iced::Theme::Dracula));
79//! editor.set_theme(theme::from_iced_theme(&iced::Theme::CatppuccinMocha));
80//! editor.set_theme(theme::from_iced_theme(&iced::Theme::Nord));
81//! ```
82//!
83//! # Vim Mode
84//!
85//! Vim behavior is disabled by default and configured per editor instance:
86//!
87//! ```
88//! use iced_code_editor::{CodeEditor, VimMode};
89//!
90//! let mut editor =
91//! CodeEditor::new("fn main() {}", "rs").with_vim_enabled(true);
92//! assert!(editor.vim_enabled());
93//! assert_eq!(editor.vim_mode(), Some(VimMode::Normal));
94//!
95//! editor.set_vim_enabled(false);
96//! assert_eq!(editor.vim_mode(), None);
97//! ```
98//!
99//! A focused editor can toggle Vim behavior with `Ctrl+Alt+V`, or
100//! `Command+Alt+V` on macOS. Regular `Ctrl`/`Command+V` system paste is
101//! unchanged. Counts support both target lines (`5G`/`5gg` jump to logical
102//! line 5) and line operators (`5yy`, `5dd`, and `5cc` affect five lines).
103//! A fixed bottom status line shows the current mode, pending keys, and active
104//! `/pattern` or `:N` input. Submit with Enter, edit with Backspace, or cancel
105//! with Escape. `n` and `N` repeat the last search forward or backward.
106//!
107//! The Vim MVP provides Normal, Insert, Visual, and Visual Line modes; counts;
108//! `h/j/k/l`, word and line motions; `d/c/y`, `x`, `p/P`, and `u`/`Ctrl+R`;
109//! `/` search with `n`/`N`, `:N` line jumps; and a per-editor unnamed register.
110//! It is single-cursor and does not include general Ex commands, regex/search
111//! history, text objects, macros, named registers, marks, `.` repeat, or
112//! configurable mappings. Platform clipboard shortcuts continue to use the
113//! system clipboard instead of the Vim register.
114//!
115//! # Keyboard Shortcuts
116//!
117//! The editor supports a comprehensive set of keyboard shortcuts:
118//!
119//! ## Navigation
120//!
121//! | Shortcut | Action |
122//! |----------|--------|
123//! | **Arrow Keys** (Up, Down, Left, Right) | Move cursor |
124//! | **Shift + Arrows** | Move cursor with selection |
125//! | **Home** / **End** | Jump to start/end of line |
126//! | **Shift + Home** / **Shift + End** | Select to start/end of line |
127//! | **Ctrl + Home** / **Ctrl + End** | Jump to start/end of document |
128//! | **Page Up** / **Page Down** | Scroll one page up/down |
129//!
130//! ## Editing
131//!
132//! | Shortcut | Action |
133//! |----------|--------|
134//! | **Backspace** | Delete character before cursor (or delete selection if text is selected) |
135//! | **Delete** | Delete character after cursor (or delete selection if text is selected) |
136//! | **Shift + Delete** | Delete selected text (same as Delete when selection exists) |
137//! | **Enter** | Insert new line |
138//!
139//! ## Clipboard
140//!
141//! | Shortcut | Action |
142//! |----------|--------|
143//! | **Ctrl + C** or **Ctrl + Insert** | Copy selected text |
144//! | **Ctrl + V** or **Shift + Insert** | Paste from clipboard |
145//!
146//! # Supported Languages
147//!
148//! The editor supports syntax highlighting through the `syntect` crate:
149//! - Python (`"py"` or `"python"`)
150//! - Lua (`"lua"`)
151//! - Rust (`"rs"` or `"rust"`)
152//! - JavaScript (`"js"` or `"javascript"`)
153//! - And many more...
154//!
155//! For a complete list, refer to the `syntect` crate documentation.
156//!
157//! # Command History Management
158//!
159//! The [`CommandHistory`] type provides fine-grained control over undo/redo operations.
160//! While the editor handles history automatically, you can access it directly for
161//! advanced use cases:
162//!
163//! ## Monitoring History State
164//!
165//! ```no_run
166//! use iced_code_editor::CommandHistory;
167//!
168//! let history = CommandHistory::new(100);
169//!
170//! // Check how many operations are available
171//! println!("Undo operations: {}", history.undo_count());
172//! println!("Redo operations: {}", history.redo_count());
173//!
174//! // Check if operations are possible
175//! if history.can_undo() {
176//! println!("Can undo!");
177//! }
178//! ```
179//!
180//! ## Adjusting History Size
181//!
182//! You can dynamically adjust the maximum number of operations kept in history:
183//!
184//! ```no_run
185//! use iced_code_editor::CommandHistory;
186//!
187//! let history = CommandHistory::new(100);
188//!
189//! // Get current maximum
190//! assert_eq!(history.max_size(), 100);
191//!
192//! // Increase limit for memory-rich environments
193//! history.set_max_size(500);
194//!
195//! // Or decrease for constrained environments
196//! history.set_max_size(50);
197//! ```
198//!
199//! ## Clearing History
200//!
201//! You can reset the entire history when needed:
202//!
203//! ```no_run
204//! use iced_code_editor::CommandHistory;
205//!
206//! let history = CommandHistory::new(100);
207//!
208//! // Clear all undo/redo operations
209//! history.clear();
210//!
211//! assert_eq!(history.undo_count(), 0);
212//! assert_eq!(history.redo_count(), 0);
213//! ```
214//!
215//! ## Save Point Tracking
216//!
217//! Track whether the document has been modified since the last save:
218//!
219//! ```no_run
220//! use iced_code_editor::CommandHistory;
221//!
222//! let history = CommandHistory::new(100);
223//!
224//! // After loading or saving a file
225//! history.mark_saved();
226//!
227//! // Check if there are unsaved changes
228//! if history.is_modified() {
229//! println!("Document has unsaved changes!");
230//! }
231//! ```
232
233// Initialize rust-i18n for the entire crate
234rust_i18n::i18n!("locales", fallback = "en");
235
236mod buffer;
237mod canvas_editor;
238
239pub mod i18n;
240pub mod theme;
241
242/// Hidden re-exports for the `criterion` benchmark harness (`benches/`).
243///
244/// Compiled only with the `bench` feature; not part of the public API.
245#[doc(hidden)]
246#[cfg(feature = "bench")]
247pub use canvas_editor::bench_support;
248pub use canvas_editor::features::folding::FoldRegion;
249/// LSP integration types and traits for editor clients.
250pub use canvas_editor::lsp::{
251 LspClient, LspDocument, LspPosition, LspRange, LspTextChange,
252 compute_text_change,
253};
254pub use canvas_editor::{
255 ArrowDirection, CodeEditor, CommandHistory, ContextMenuEntry,
256 ContextMenuItem, IndentStyle, Message, VimMode,
257};
258pub use i18n::{Language, Translations};
259pub use theme::{Catalog, Style, StyleFn, from_iced_theme};
260
261#[cfg(all(feature = "lsp-process", not(target_arch = "wasm32")))]
262pub use canvas_editor::lsp::process::{
263 LSP_EVENT_QUEUE_CAPACITY, LspEvent, LspProcessClient,
264};
265
266#[cfg(all(feature = "lsp-process", not(target_arch = "wasm32")))]
267pub use canvas_editor::lsp::process::config::{
268 LspCommand, LspLanguage, LspServerConfig, ensure_rust_analyzer_config,
269 lsp_language_for_extension, lsp_language_for_path, lsp_server_config,
270 resolve_lsp_command,
271};
272
273#[cfg(all(feature = "lsp-process", not(target_arch = "wasm32")))]
274pub use canvas_editor::lsp::process::overlay::{
275 LspOverlayMessage, LspOverlayState, view_lsp_overlay,
276};