cadabra::DocumentThread Class Reference

Description

A base class with all the logic to manipulate a Cadabra notebook document.

Relies on the various objects derived from ActionBase in order to get actual work done. All methods here will always run on the GUI thread.

In order to implement a GUI, derive from both DocumentThread and GUIBase and then implement the virtual functions of the latter (those implement basic insertion/removal of notebook cells; the logic to figure out which ones and to implement the undo/redo stack is all in the GUI-agnostic DocumentThread).

#include <DocumentThread.hh>

Inheritance diagram for cadabra::DocumentThread:

Classes
class	Prefs

Public Member Functions
	DocumentThread (GUIBase *)
	DocumentThread (const DocumentThread &)=delete
	It is not possible to copy-construct a DocumentThread as it holds on to resources which are not easily copied (such as GUI elements).
virtual void	set_compute_thread (ComputeThread *)
	Let the notebook know about the ComputeThread so that it can send cells for evaluation.
void	build_visual_representation ()
	Ensure that the gui has an up-to-date representation of the dtree.
void	queue_action (std::shared_ptr< ActionBase >)
	All changes to the document should be made by submitting ActionBase derived objects to the 'queue_action' function, so that an undo stack can be kept.
void	run_all_cells ()
	Run all cells in the document.
void	run_cell (DTree::iterator, bool shift_pressed)
	Run a single cell in the document.
void	run_cells_referencing_variable (std::string variable, double value)
	Run all cells containing references to a given variable.
void	new_document ()
	Setup an empty new document with a single Python input cell.
virtual void	load_from_string (const std::string &)
	Load a new notebook from a JSON string.
virtual void	on_interactive_output (const nlohmann::json &msg)
virtual void	set_progress (const std::string &msg, int cur_step, int total_steps)
void	undo ()
	One undo step.
void	redo ()
	One redo step.
std::pair< DTree::iterator, size_t >	find_string (DTree::iterator start_it, size_t start_pos, const std::string &f, bool case_ins) const
	Find string, return match, or a (doc.end(), std::string::npos).
void	set_user_details (const std::string &name, const std::string &email, const std::string &affiliation)
	Set user details which will be sent to the Cadabra log server.

Public Attributes
friend	ActionBase
	All actions are considered pieces of code which are part of DocumentThread, so they should be able to access its private variables.
friend	ActionAddCell
friend	ActionPositionCursor
friend	ActionRemoveCell
friend	ActionSplitCell
friend	ActionSetRunStatus
friend	ActionInsertText
friend	ActionCompleteText
friend	ActionEraseText
Prefs	prefs
std::thread::id	main_thread_id
	For debugging purposes we store the main thread idea here (the main Cadabra class sets it).

Protected Types
enum class	help_t { algorithm , property , latex , none }
	Help system. More...
typedef std::stack< std::shared_ptr< ActionBase > >	ActionStack

Protected Member Functions
void	process_action_queue ()
	Process the action queue.
virtual bool	on_unhandled_error (const std::exception &err)
bool	help_type_and_topic (const std::string &before, const std::string &after, help_t &help_type, std::string &help_topic) const

Protected Attributes
GUIBase *	gui
ComputeThread *	compute
DTree	doc
	The actual document tree.
DTree::iterator	current_cell
	Iterator to the currently active cell in the notebook, or doc.end() if nothing active.
bool	follow_mode
	If follow_mode is true, the follow_cell can be set, and this will make the canvas view follow the indicated cell.
DTree::iterator	follow_cell
DTree::iterator	follow_last_cell
std::mutex	stack_mutex
	The action undo/redo/todo stacks and logic to execute them.
ActionStack	undo_stack
ActionStack	redo_stack
std::queue< std::shared_ptr< ActionBase > >	pending_actions
bool	disable_stacks

Member Typedef Documentation

ActionStack

typedef std::stack<std::shared_ptr<ActionBase> > cadabra::DocumentThread::ActionStack

protected

Member Enumeration Documentation

help_t

enum class cadabra::DocumentThread::help_t

strongprotected

Help system.

Enumerator
algorithm
property
latex
none

Constructor & Destructor Documentation

DocumentThread() [1/2]

DocumentThread::DocumentThread

(

GUIBase *

g

)

DocumentThread() [2/2]

cadabra::DocumentThread::DocumentThread ( const DocumentThread &  )

delete

It is not possible to copy-construct a DocumentThread as it holds on to resources which are not easily copied (such as GUI elements).

Member Function Documentation

build_visual_representation()

void DocumentThread::build_visual_representation

(

)

Ensure that the gui has an up-to-date representation of the dtree.

Traverses the entire tree so is expensive to run and should only be used when loading new documents or creating a new canvas view.

find_string()

std::pair< DTree::iterator, size_t > DocumentThread::find_string	(	DTree::iterator	start_it,
		size_t	start_pos,
		const std::string &	f,
		bool	case_ins
	)		const

Find string, return match, or a (doc.end(), std::string::npos).

help_type_and_topic()

bool DocumentThread::help_type_and_topic ( const std::string &  before, const std::string &  after, help_t &  help_type, std::string &  help_topic  ) const

protected

load_from_string()

void DocumentThread::load_from_string ( const std::string &  json )

virtual

Load a new notebook from a JSON string.

Should only be called from the GUI thread. Will cancel any pending operations on the existing notebook (if present) first.

Reimplemented in cadabra::NotebookWindow.

new_document()

void DocumentThread::new_document

(

)

Setup an empty new document with a single Python input cell.

on_interactive_output()

void DocumentThread::on_interactive_output ( const nlohmann::json &  msg )

virtual

Reimplemented in cadabra::NotebookWindow.

on_unhandled_error()

bool DocumentThread::on_unhandled_error ( const std::exception &  err )

protectedvirtual

Reimplemented in cadabra::NotebookWindow.

process_action_queue()

void DocumentThread::process_action_queue ( )

protected

Process the action queue.

It is allowed to call queue_action() above while this is running. So a running action can add more actions. Needs to be called on the GUI thread!

queue_action()

void DocumentThread::queue_action

(

std::shared_ptr< ActionBase >

ab

)

All changes to the document should be made by submitting ActionBase derived objects to the 'queue_action' function, so that an undo stack can be kept.

They are then processed by calling the 'process_action_queue' method (only available from this thread).

redo()

void DocumentThread::redo

(

)

One redo step.

run_all_cells()

void DocumentThread::run_all_cells

(

)

Run all cells in the document.

Only execute this on the main (GUI) thread!

run_cell()

void DocumentThread::run_cell	(	DTree::iterator	it,
		bool	shift_pressed
	)

Run a single cell in the document.

Only execute this on the main (GUI) thread!

run_cells_referencing_variable()

void DocumentThread::run_cells_referencing_variable	(	std::string	variable,
		double	value
	)

Run all cells containing references to a given variable.

This will eventually call compute->execute on the relevant cells, but is part of DocumentThread because this function takes care of scanning through the document to find out which cells to run.

set_compute_thread()

void DocumentThread::set_compute_thread ( ComputeThread *  cl )

virtual

Let the notebook know about the ComputeThread so that it can send cells for evaluation.

Notebook does NOT own this pointer.

Reimplemented in cadabra::NotebookWindow.

set_progress()

void DocumentThread::set_progress ( const std::string &  msg, int  cur_step, int  total_steps  )

virtual

Reimplemented in cadabra::NotebookWindow.

set_user_details()

void DocumentThread::set_user_details	(	const std::string &	name,
		const std::string &	email,
		const std::string &	affiliation
	)

Set user details which will be sent to the Cadabra log server.

undo()

void DocumentThread::undo

(

)

One undo step.

Member Data Documentation

ActionAddCell

friend cadabra::DocumentThread::ActionAddCell

ActionBase

friend cadabra::DocumentThread::ActionBase

All actions are considered pieces of code which are part of DocumentThread, so they should be able to access its private variables.

ActionCompleteText

friend cadabra::DocumentThread::ActionCompleteText

ActionEraseText

friend cadabra::DocumentThread::ActionEraseText

ActionInsertText

friend cadabra::DocumentThread::ActionInsertText

ActionPositionCursor

friend cadabra::DocumentThread::ActionPositionCursor

ActionRemoveCell

friend cadabra::DocumentThread::ActionRemoveCell

ActionSetRunStatus

friend cadabra::DocumentThread::ActionSetRunStatus

ActionSplitCell

friend cadabra::DocumentThread::ActionSplitCell

compute

ComputeThread* cadabra::DocumentThread::compute

protected

current_cell

DTree::iterator cadabra::DocumentThread::current_cell

protected

Iterator to the currently active cell in the notebook, or doc.end() if nothing active.

disable_stacks

bool cadabra::DocumentThread::disable_stacks

protected

doc

DTree cadabra::DocumentThread::doc

protected

The actual document tree.

This object is only modified on the GUI thread, either directly by code in DocumentThread, or by code in the various objects derived from ActionBase. In particular, ComputeThread cannot access this tree directly.

follow_cell

DTree::iterator cadabra::DocumentThread::follow_cell

protected

follow_last_cell

DTree::iterator cadabra::DocumentThread::follow_last_cell

protected

follow_mode

bool cadabra::DocumentThread::follow_mode

protected

If follow_mode is true, the follow_cell can be set, and this will make the canvas view follow the indicated cell.

gui

GUIBase* cadabra::DocumentThread::gui

protected

main_thread_id

std::thread::id cadabra::DocumentThread::main_thread_id

For debugging purposes we store the main thread idea here (the main Cadabra class sets it).

pending_actions

std::queue<std::shared_ptr<ActionBase> > cadabra::DocumentThread::pending_actions

protected

prefs

Prefs cadabra::DocumentThread::prefs

redo_stack

ActionStack cadabra::DocumentThread::redo_stack

protected

stack_mutex

std::mutex cadabra::DocumentThread::stack_mutex

protected

The action undo/redo/todo stacks and logic to execute them.

These stacks can be accessed from both the DocumentThread as well as the ComputeThread (the latter does it through the DocumentThread::queue_action method), so they need a mutex to access them.

undo_stack

ActionStack cadabra::DocumentThread::undo_stack

protected

---

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

• client_server/DocumentThread.hh
• client_server/DocumentThread.cc