Struct Session 

pub struct Session {

    pub clipboard: Option<Clipboard>,
    pub prefs: Prefs,
    pub mode: Mode,
    pub journal: Vec<(String, Value)>,
    pub ui_requests: Vec<UiRequest>,
    pub format_painter: Option<(Arc<Workbook>, usize, RangeRef, bool)>,
    pub last_find: Option<Value>,
    pub hide_ruler: bool,
    pub recording: Option<usize>,
    pub recorder: Option<Recorder>,
    pub macro_approvals: HashSet<(u64, String)>,
    pub macro_debug: Option<Debugger>,
    pub macro_recording: Option<RecordingStart>,
    pub draw_tool: String,
    pub draw_color: String,
    pub draw_width: f32,
    pub comments_pane: bool,
    pub show_all_notes: bool,
    pub link_policy: LinkPolicy,
    pub text_width: Option<TextWidth>,
    /* private fields */
}

Fields

clipboard: Option<Clipboard>

prefs: Prefs

mode: Mode

journal: Vec<(String, Value)>

Commands run so far, without their passwords (cmd::journal_params).

ui_requests: Vec<UiRequest>

format_painter: Option<(Arc<Workbook>, usize, RangeRef, bool)>

Format painter source style (sticky when double-clicked).

last_find: Option<Value>

Find state (last search).

hide_ruler: bool

View › Show › Ruler is off (rulers in Page Layout view; an application option).

recording: Option<usize>

Journal position where Automate › Record Actions started.

recorder: Option<Recorder>

The recording buffer while a recorder runs (Session::start_recording): top-level commands with the place they ran in, kept apart from the journal.

macro_approvals: HashSet<(u64, String)>

Macros the person allowed to run in this session: (document uid, the macro’s content as canonical JSON, from macros::fingerprint).

macro_debug: Option<Debugger>

The macro being debugged, between debugger actions.

macro_recording: Option<RecordingStart>

Where the macro recorder started (beside recorder, its buffer).

draw_tool: String

Draw tab tool: “” (select), “pen” or “eraser”; pen colour and width.

draw_color: String

draw_width: f32

comments_pane: bool

Review › Show Comments: the Comments pane is open.

show_all_notes: bool

Review › Notes › Show All Notes: every note is displayed. An application display setting (like Excel’s comment indicator option), so it’s not saved in the file.

link_policy: LinkPolicy

Whether link.open may open web and e-mail addresses without the user’s confirmation (#2181). Host code sets it; no command does.

text_width: Option<TextWidth>

Measures cell text for AutoFit Column Width. Without it (CLI, MCP) AutoFit uses cmd::format::approx_text_width.

Implementations

impl Session

pub fn open_confirmed_link(&mut self, target: &str) -> Result<Json>

Opens a link the user has just confirmed in the host’s “Open Hyperlink” prompt: an allowed address goes to the host (UiRequest::OpenUrl), a reference selects, anything else is refused (classify). Not a command: only host code that showed the user this exact address may call it.

impl Session

pub fn windows(&self) -> &[WindowState]

The open windows, in the order they were opened.

pub fn active_window(&self) -> Option<u64>

The active window’s id (None with no workbook open).

pub fn window(&self, id: u64) -> Option<&WindowState>

pub fn window_title(&self, id: u64) -> Option<String>

The window title: the workbook’s name when it has one window, “Name:1”, “Name:2”… in opening order when it has several.

pub fn doc_window(&self, doc: u64) -> Option<u64>

The most recently active window of a workbook, preferring one that isn’t hidden.

pub fn target_window(&self, t: Target) -> Result<u64>

Resolves a Target to a window id.

pub fn activate_window(&mut self, id: u64)

Makes a window active, swapping its view into its workbook. Unknown ids are ignored.

pub fn show_window(&mut self, id: u64)

Makes a window the one commands act on while the interface draws it, without counting as an activation: the most recently active window of each workbook stays the same.

pub fn new_window(&mut self) -> Result<u64>

View › New Window: another window on the active window’s workbook, showing what it shows.

pub fn close_window(&mut self, id: u64)

Closes one window. The workbook stays open while it has another window; closing its last window closes the workbook (unsaved changes are the caller’s to ask about).

pub fn hide_window(&mut self, id: u64)

View › Hide on a window; the most recent visible window comes forward.

pub fn unhide_window(&mut self, id: u64)

View › Unhide: shows a hidden window and activates it.

pub fn last_hidden_window(&self) -> Option<u64>

The most recently hidden window.

pub fn window_list(&self) -> Json

The windows as scripts and the Switch Windows lists see them: [{window, doc, index, title, dirty, active, hidden}], index being the workbook’s position in Session::documents.

pub fn with_target<T>( &mut self, t: Target, f: impl FnOnce(&mut Session) -> T, ) -> Result<T>

Runs f with the target window active, then brings back the window that was active, so a script acting on another window doesn’t change what the user is looking at. When f itself switched windows (window.activate, file.new, a close), its choice stands.

pub fn enter_target(&mut self, t: Target) -> Result<Option<TargetGuard>>

The first half of Session::with_target, for callers whose closure can’t borrow the session alone (the UI runs commands through its app): activates the target window and returns what Session::leave_target needs to bring the previous one back.

pub fn leave_target(&mut self, guard: Option<TargetGuard>)

pub fn execute_in(&mut self, t: Target, id: &str, params: Json) -> Result<Json>

Session::execute on a target window.

pub fn execute_headless_in( &mut self, t: Target, id: &str, params: Json, ) -> Result<Json>

Session::execute_headless on a target window.

impl Session

pub fn new() -> Session

pub fn documents(&self) -> &[DocState]

pub fn active_index(&self) -> usize

pub fn set_active(&mut self, i: usize)

Makes the workbook at i active, in its most recently active window (unless the active window already shows it).

pub fn active(&self) -> Option<&DocState>

pub fn document_index(&self, uid: u64) -> Option<usize>

Where the open workbook with this DocState::uid is in Session::documents.

pub fn active_mut(&mut self) -> Option<&mut DocState>

pub fn doc(&self) -> Result<&DocState>

pub fn doc_mut(&mut self) -> Result<&mut DocState>

pub fn locked_cell_message(&self, sheet: usize, at: CellRef) -> Option<String>

The warning an edit of at on sheet gets from sheet protection, or None when the edit is allowed. Front ends ask before opening an editor, so typing into a locked cell never leaves a draft that can’t be entered (and so blocks saving).

pub fn add_document(&mut self, d: DocState) -> usize

Opens a workbook in a new window, which becomes the active one.

pub fn close_document(&mut self, i: usize)

Closes a workbook and its windows; the most recently active remaining window comes forward.

pub fn new_workbook(&mut self) -> usize

A new blank workbook titled BookN.

pub fn commands(&self) -> Vec<CommandInfo>

pub fn execute(&mut self, id: &str, params: Json) -> Result<Json>

Runs a command by id. Undoable commands record a history step when the workbook changed, unless an undo group is open on the document (the group then makes the step). Panics inside commands are caught and reported; the workbook is restored.

pub fn grouped<R>( &mut self, label: &str, f: impl FnOnce(&mut Session) -> Result<R>, ) -> Result<R>

Runs f as one undo step labelled label on the active document: whatever commands f runs, one Undo brings back the workbook as it was before. If f fails, every change it made is rolled back and its error is returned. Groups nest; the outermost one makes the step.

pub fn group_begin(&mut self, label: &str) -> Result<GroupToken>

Opens an undo group on the active document that can span several calls (for example a debugger that runs one step per call). Until Session::group_end or Session::group_rollback, undoable commands on that document add no undo steps of their own, and Undo and Redo are unavailable there.

pub fn group_end(&mut self, token: GroupToken) -> Result<bool>

Ends an undo group. If the workbook changed, the group becomes one undo step, unless it is nested in another open group on the same document, which then owns the step. Groups opened inside it and still open end with it. Returns whether the workbook changed.

pub fn abort_groups(&mut self, doc: u64) -> bool

Stops the running action on the document with uid doc: every undo group open on it is rolled back as Session::group_rollback does, putting back the workbook, selection, undo and redo history as they were when the outermost one began. Their tokens are then spent (ending or rolling one back reports that it has already ended). Returns whether a group was open. automate.stopAction runs it on the active document.

pub fn group_rollback(&mut self, token: GroupToken) -> Result<()>

Ends an undo group by putting back the workbook, selection, undo and redo history as they were when it began.

pub fn start_recording(&mut self)

Starts recording top-level commands into an empty buffer, replacing any recording in progress. Queries, failed commands and commands run by other commands are not recorded.

pub fn stop_recording(&mut self) -> Option<Recorder>

Stops recording and returns what was recorded (None when nothing was recording).

pub fn is_recording(&self) -> bool

Whether the recording buffer is collecting commands.

pub fn depth(&self) -> u32

How many commands are running: 0 between top-level commands, 1 inside one, 2 inside a command run by a command, and so on.

pub fn group_is_open(&self, token: &GroupToken) -> bool

Whether the token’s undo group is still open (nothing has ended or rolled it back).

pub fn in_group(&self, doc: u64) -> bool

Whether an undo group is open on the document with this uid.

pub fn run(&mut self, id: &str, params: Json) -> Result<Json, String>

pub fn take_ui_requests(&mut self) -> Vec<UiRequest>

pub fn execute_headless(&mut self, id: &str, params: Json) -> Result<Json>

Runs a command for a caller with no UI (MCP, CLI): queued UI requests are dropped, and a command that only queued a file dialog because it got no file (file.open, file.saveAs, file.save on a workbook with no file yet, data.getData) is an error instead of a silent success.

Trait Implementations

impl Default for Session

fn default() -> Session

Returns the “default value” for a type.