Tabs over screens: a tab bar over a WorkspaceModel, one screen instance per tab, mounted into the tab's page through DocumentScreenHost::mountInto, with the screen's head row above it or, when the placement is External, mounted by the host instead. More...

#include <workspace.hpp>

Public Member Functions
	Workspace (reactive::Runtime &runtime, IViewBackend &backend, DocumentScreenHost &host, WorkspaceOptions options={}, ContainerWidget *parent=nullptr, HeadPlacement headPlacement=HeadPlacement::InPage)
	The shell, its tab bar appended to `parent`.
	~Workspace ()
	Unmounts every screen without asking, newest first, then the pages.
	Workspace (Workspace const &)=delete
Workspace &	operator= (Workspace const &)=delete
	Workspace (Workspace &&)=delete
Workspace &	operator= (Workspace &&)=delete
TabsWidget &	root () noexcept
	The tab bar: the shell's root widget, which the host places.
WorkspaceModel &	model () noexcept
	The tab logic the bar shows, for an application that reads or drives it by tab id.
std::expected< std::size_t, MountError >	open (std::string_view screenId, ParamMap const &params)
	Opens a screen, or focuses the tab that already shows it (WorkspaceModel::open).
std::size_t	start (WorkspaceStart const &how)
	Opens the start screens (WorkspaceModel::start).
void	flushRecord ()
	Writes the record now, cancelling a pending debounced write: what sign-out does before the session is cleared.
std::vector< std::string >	record () const
	The record as it would be written now: the routes of the open tabs, in order.
void	activate (std::size_t index)
	Shows a tab and makes it the most recently used.
void	next ()
	Shows the next tab in most-recently-used order (Ctrl+Tab). Repeated calls walk the order as it was at the first of them; any other activation starts a new walk.
void	previous ()
	Shows the previous tab in most-recently-used order (Ctrl+Shift+Tab).
void	close (std::size_t index, std::function< void(bool)> done)
	Closes a tab through its screen's close protocol.
void	closeOthers (std::size_t index, std::function< void(bool)> done)
	Closes every tab but one, one at a time, stopping at the first veto.
void	closeAll (std::function< void(bool)> done)
	Closes every tab, one at a time, stopping at the first veto.
void	closeSaved (std::function< void(bool)> done)
	Closes every tab without unsaved changes, one at a time, stopping at the first veto.
std::optional< std::size_t >	active () const
	The active tab's index.
ScreenHandle *	handleOf (std::size_t index) const noexcept
	The screen handle of a tab: what a client remounts for development reload and inspects.
ScreenHandle *	activeHandle () const
	The active tab's screen handle.
Node	headRowForActive () const
	The active tab's head row, the same reactive content headRow builds for the body-embedded rendering, for a host that mounts it elsewhere (a shell's own top bar, say). Never null: an invisible, empty row stands in for "no active tab" rather than a null Node, since a caller mounting this may not expect to handle one.
void	forceCloseAll ()
	Closes every tab without asking, newest first: what signing out does, since no close guard may keep a screen of the principal who is leaving.
std::vector< WorkspaceTab >	tabs () const
	The open tabs, in order.

Detailed Description

Tabs over screens: a tab bar over a WorkspaceModel, one screen instance per tab, mounted into the tab's page through DocumentScreenHost::mountInto, with the screen's head row above it or, when the placement is External, mounted by the host instead.

The model holds the tab logic: tabs keep the order they were opened in, opening a screen whose identity an open tab already has focuses that tab, a singleton screen has one tab, and closing runs each screen's close protocol (spec 6 §3), one tab at a time, a walk over several tabs stopping at the first veto. The bar shows the model's tabs and takes Ctrl+Tab, Ctrl+Shift+Tab and Ctrl+W, which documents may not declare. Neither copyable nor movable; owned by the owner thread of its runtime.

Definition at line 63 of file workspace.hpp.

Constructor & Destructor Documentation

◆ Workspace()

morph::ui::Workspace::Workspace	(	reactive::Runtime &	runtime,
		IViewBackend &	backend,
		DocumentScreenHost &	host,
		WorkspaceOptions	options = {},
		ContainerWidget *	parent = nullptr,
		HeadPlacement	headPlacement = HeadPlacement::InPage )

inline

The shell, its tab bar appended to parent.

Parameters

runtime	The runtime the screens' reactive nodes belong to. Borrowed.
backend	The backend the bar and the pages are made with. Borrowed.
host	What mounts the screens. Borrowed; it outlives the shell.
options	The screens' catalog facts.
parent	The container the shell is appended to; null makes it a backend root.
headPlacement	Where the active screen's head row is drawn. External leaves the host to mount headRowForActive() itself, so a shell with its own top bar shows the head once.

Definition at line 73 of file workspace.hpp.

◆ ~Workspace()

morph::ui::Workspace::~Workspace ( )

inline

Unmounts every screen without asking, newest first, then the pages.

Definition at line 116 of file workspace.hpp.

Member Function Documentation

◆ root()

TabsWidget & morph::ui::Workspace::root ( )

inlinenodiscardnoexcept

The tab bar: the shell's root widget, which the host places.

Returns: It.

Definition at line 125 of file workspace.hpp.

◆ model()

WorkspaceModel & morph::ui::Workspace::model ( )

inlinenodiscardnoexcept

The tab logic the bar shows, for an application that reads or drives it by tab id.

Returns: It, valid as long as the shell.

Definition at line 129 of file workspace.hpp.

◆ open()

std::expected< std::size_t, MountError > morph::ui::Workspace::open	(	std::string_view	screenId,
		ParamMap const &	params )

inline

Opens a screen, or focuses the tab that already shows it (WorkspaceModel::open).

Parameters

screenId	The screen id.
params	Its params.

Returns: The tab's index, or why the screen could not be mounted; a refused mount opens nothing.

Definition at line 135 of file workspace.hpp.

◆ start()

std::size_t morph::ui::Workspace::start ( WorkspaceStart const & how )

inline

Opens the start screens (WorkspaceModel::start).

Parameters

how	The start screen, the fallback and the record.

Returns: The number of tabs opened.

Definition at line 146 of file workspace.hpp.

◆ flushRecord()

void morph::ui::Workspace::flushRecord ( )

inline

Writes the record now, cancelling a pending debounced write: what sign-out does before the session is cleared.

Definition at line 150 of file workspace.hpp.

◆ record()

std::vector< std::string > morph::ui::Workspace::record ( ) const

inlinenodiscard

The record as it would be written now: the routes of the open tabs, in order.

Returns: The routes.

Definition at line 154 of file workspace.hpp.

◆ activate()

void morph::ui::Workspace::activate ( std::size_t index )

inline

Shows a tab and makes it the most recently used.

Parameters

index The tab; past the last one does nothing.

Definition at line 158 of file workspace.hpp.

◆ next()

void morph::ui::Workspace::next ( )

inline

Shows the next tab in most-recently-used order (Ctrl+Tab). Repeated calls walk the order as it was at the first of them; any other activation starts a new walk.

Definition at line 166 of file workspace.hpp.

◆ previous()

void morph::ui::Workspace::previous ( )

inline

Shows the previous tab in most-recently-used order (Ctrl+Shift+Tab).

Definition at line 169 of file workspace.hpp.

◆ close()

void morph::ui::Workspace::close	(	std::size_t	index,
		std::function< void(bool)>	done )

inline

Closes a tab through its screen's close protocol.

Parameters

index	The tab.
done	Called once with whether it closed; may be empty.

Definition at line 174 of file workspace.hpp.

◆ closeOthers()

void morph::ui::Workspace::closeOthers	(	std::size_t	index,
		std::function< void(bool)>	done )

inline

Closes every tab but one, one at a time, stopping at the first veto.

Parameters

index	The tab kept; past the last one closes every tab.
done	Called once with whether every other tab closed; may be empty.

Definition at line 188 of file workspace.hpp.

◆ closeAll()

void morph::ui::Workspace::closeAll ( std::function< void(bool)> done )

inline

Closes every tab, one at a time, stopping at the first veto.

Parameters

done	Called once with whether every tab closed; may be empty.

Definition at line 199 of file workspace.hpp.

◆ closeSaved()

void morph::ui::Workspace::closeSaved ( std::function< void(bool)> done )

inline

Closes every tab without unsaved changes, one at a time, stopping at the first veto.

Parameters

done	Called once with whether each of them closed; may be empty.

Definition at line 203 of file workspace.hpp.

◆ active()

std::optional< std::size_t > morph::ui::Workspace::active ( ) const

inlinenodiscard

The active tab's index.

Returns: It, or std::nullopt while no tab is open.

Definition at line 207 of file workspace.hpp.

◆ handleOf()

ScreenHandle * morph::ui::Workspace::handleOf ( std::size_t index ) const

inlinenodiscardnoexcept

The screen handle of a tab: what a client remounts for development reload and inspects.

Parameters

index The tab's index.

Returns: Its handle, valid while the tab is open; null past the end.

Definition at line 218 of file workspace.hpp.

◆ activeHandle()

ScreenHandle * morph::ui::Workspace::activeHandle ( ) const

inlinenodiscard

The active tab's screen handle.

Returns: It, or null while no tab is open.

Definition at line 225 of file workspace.hpp.

◆ headRowForActive()

Node morph::ui::Workspace::headRowForActive ( ) const

inlinenodiscard

The active tab's head row, the same reactive content headRow builds for the body-embedded rendering, for a host that mounts it elsewhere (a shell's own top bar, say). Never null: an invisible, empty row stands in for "no active tab" rather than a null Node, since a caller mounting this may not expect to handle one.

Returns: The row, reactive to the active tab changing and to its head's own content changing.

Definition at line 235 of file workspace.hpp.

◆ forceCloseAll()

void morph::ui::Workspace::forceCloseAll ( )

inline

Closes every tab without asking, newest first: what signing out does, since no close guard may keep a screen of the principal who is leaving.

Definition at line 248 of file workspace.hpp.

◆ tabs()

std::vector< WorkspaceTab > morph::ui::Workspace::tabs ( ) const

inlinenodiscard

The open tabs, in order.

Returns: Each tab's screen, identity and caption.

Definition at line 252 of file workspace.hpp.

The documentation for this class was generated from the following file:

morph/ui/workspace.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Workspace()

◆ ~Workspace()

Member Function Documentation

◆ root()

◆ model()

◆ open()

◆ start()

◆ flushRecord()

◆ record()

◆ activate()

◆ next()

◆ previous()

◆ close()

◆ closeOthers()

◆ closeAll()

◆ closeSaved()

◆ active()

◆ handleOf()

◆ activeHandle()

◆ headRowForActive()

◆ forceCloseAll()

◆ tabs()