body_builder component, providing an html interface to libdar::user_interaction More...

#include <html_web_user_interaction.hpp>

Inheritance diagram for html_web_user_interaction:

[legend]

Collaboration diagram for html_web_user_interaction:

[legend]

Public Member Functions
	html_web_user_interaction (unsigned int x_warn_size=25)

	html_web_user_interaction (const html_web_user_interaction &ref)=delete

	html_web_user_interaction (html_web_user_interaction &&ref) noexcept=delete

html_web_user_interaction &	operator= (const html_web_user_interaction &ref)=delete

html_web_user_interaction &	operator= (html_web_user_interaction &&ref) noexcept=delete

void	set_warning_list_size (unsigned int size)
	change the number of last warnings to display

virtual void	on_event (const std::string &event_name) override
	inherited from actor More...

void	auto_hide (bool mode, bool unless_interrupted)
	when the control thread has finished, this html_web_user_interaction object becomes invisible More...

void	clear ()
	clear counters, logs and reset html interface and make the component become visible if it was not already More...

std::shared_ptr< web_user_interaction >	get_user_interaction ()
	libdar strcture provided for user interaction

html_statistics &	get_statistics ()
	libdar structure provided for user information

void	hide_statistics ()
	hide statistics fields in the web interface More...

void	run_and_control_thread (libthreadar::thread *arg)
	provide a libdar thread to be managed by this html_web_component (stop actions) More...

void	join_controlled_thread ()
	let the calling thread suspended until the controlled thread ends (the one passed to run_and_control_thread()) More...

bool	is_libdar_running () const
	whether a libdar thread is running under "this" management

bool	has_libdar_been_aborted () const
	whether libdar thread has been aborted (to be checked by the caller upon libdar_has_finished event)

Public Member Functions inherited from body_builder
	body_builder ()
	constructor

	body_builder (const body_builder &ref)
	copy constructor More...

	body_builder (body_builder &&ref) noexcept=delete
	move constructor More...

body_builder &	operator= (const body_builder &ref)
	assignment operator drops all existing children More...

body_builder &	operator= (body_builder &&ref) noexcept=delete
	move operator More...

virtual	~body_builder ()
	the (virtual) destructor

void	set_prefix (const chemin &prefix)

void	adopt (body_builder *obj)

bool	is_adopted () const
	whether the object has currently a parent (= is adopted)

void	foresake (body_builder *obj)

void	set_visible (bool mode)
	ask for the object to become visible in HTML page or temporarily hidden More...

bool	get_visible () const
	returns the current visible status of the object More...

bool	get_visible_recursively () const
	return the effective visible status of an object taking into account all of ancestors that adopted it

void	add_css_class (const std::string &name)
	set this object with a additional css_class (assuming it is defined in a css_library available for this object)

void	add_css_class (const css_class_group &cg)
	set this object with an additional set of css_classes (assuming they are all defined in a css_library available for this object)

bool	has_css_class (const std::string &name) const
	check the presence of the given class name

void	remove_css_class (const std::string &name)
	remove the provided css_class name from the list of css_class names this object has been assigned to

void	remove_css_class (const css_class_group &cg)
	remove the provided css_class_group from the list

void	clear_css_classes ()
	clear the whole list of css_class names

const std::set< std::string > &	get_css_classes_as_a_set () const
	provide the list of css_class names that this object has been set with

css_class_group	get_css_class_group () const
	provide the list of css_class names as a css_class_group

std::string	get_css_classes (const std::string &extra="") const
	return the class_name as inlined css, suitable to be added in a html marker More...

void	define_css_class_in_library (const css_class &csscl)

void	define_css_class_in_library (const std::string &name, const css &cssdef)

bool	is_css_class_defined_in_library (const std::string &name) const
	check whether a css_class of given name already exists in a reachable css_library

std::string	get_body_part (const chemin &path, const request &req)

void	ignore_body_changed_from_my_children (bool mode)
	ignore my_body_part_has_changed() invoked from adopted children and myself More...

bool	get_ignore_body_changed_from_my_children () const
	get the current status of ignore_body_changed_from_my_children()

void	set_no_CR (bool no_cr=true)
	ask for the implementation not to add a new line after this control More...

void	assign_anchor (bool mode)
	assign an anchor to this object (the object's inherited_get_body_part() will be wrapped into an HTML anchor: ) More...

std::string	get_assigned_anchor () const
	return the anchor value that has been assiged to this object (without the leading #) More...

virtual void	bind_to_anchor (const std::string &val)
	ask inherited components to use this anchor in case they redirect to an new URL or generate new URLs within their body part. More...

Public Member Functions inherited from actor
	actor (const actor &ref)=default

	actor (actor &&ref) noexcept(false)=default

actor &	operator= (const actor &ref)=default

actor &	operator= (actor &&ref) noexcept(false)

virtual void	on_event (const std::string &event_name)=0
	implementation in inherited class of the action triggered by the event given in argument More...

Public Member Functions inherited from reference
	reference ()
	usual constructor

	reference (const reference &ref)
	copy constructor More...

	reference (reference &&ref) noexcept(false)
	move constructor (only operational for objects without peering) More...

reference &	operator= (const reference &ref)
	assignment operator (only operational for objects without peering) More...

reference &	operator= (reference &&ref) noexcept(false)
	move assigment operator More...

virtual	~reference ()
	destructor

void	peer_with (reference *obj)
	method used to create a relation between two objects More...

void	break_peer_with (reference *obj)
	break the peering with the object given as argument

bool	is_peer (reference *obj) const
	whether a peering exists with that object

bool	is_empty () const
	whether the current object has peering

unsigned int	size () const
	the number of peers

Public Member Functions inherited from events
	events (const events &ref)
	copy constructor More...

	events (events &&ref) noexcept(false)=default

events &	operator= (const events &ref)=default

events &	operator= (events &&ref) noexcept(false)

void	record_actor_on_event (actor *ptr, const std::string &name)
	record an actor for an given event

Static Public Attributes
static const std::string	display_started = "html_web_user_interaction_displaystarted"
	when the object has been set visible

static const std::string	can_refresh = "html_web_user_interaction_canrefresh"
	last changes makes the object html refreshable

static const std::string	dont_refresh = "html_web_user_interaction_dontrefresh"
	last changes forbid html refresh

static const std::string	libdar_has_finished = "html_web_user_interaction_libdarfinished"
	inform the caller that libdar has finished and user asked to close the "window" (or autohide was set)

Protected Member Functions
virtual std::string	inherited_get_body_part (const chemin &path, const request &req) override
	inherited from body_builder, called by the webdar thread More...

virtual void	new_css_library_available () override

virtual void	my_visibility_has_changed () override
	available for inherited class to be informed when their visibility changes More...

Protected Member Functions inherited from body_builder
virtual std::string	inherited_get_body_part (const chemin &path, const request &req)=0
	implementation of get_body_part() method for inherited classes More...

void	my_body_part_has_changed ()
	let a class record a change in what inherited_get_body_part() would return if it was called again with the same request More...

virtual void	my_visibility_has_changed ()
	available for inherited class to be informed when their visibility changes More...

bool	has_my_body_part_changed () const
	obtain the body_part changed status More...

chemin	get_path () const
	return the path of 'this' according to its descent in the body_builder tree of adopted children

std::string	get_recorded_name () const

void	store_css_library ()
	this creates a css_library accessible from adopted objects to hold html class definitions More...

bool	has_local_css_library () const
	return true if this object has a css_library locally stored (not from a adopter object)

std::unique_ptr< css_library > &	lookup_css_library () const
	lookup toward registered parent body_builder object for the closest stored css_library More...

std::string	get_body_part_from_target_child (const chemin &path, const request &req)

std::string	get_body_part_from_all_children (const chemin &path, const request &req)

virtual void	path_has_changed ()
	For inherited classes, called when the path has changed,. More...

virtual void	has_adopted (body_builder *obj)
	Be informed that a new child has been adopted. More...

virtual void	will_foresake (body_builder *obj)
	Be informed that a child is about to be foresaken. More...

virtual void	has_been_adopted_by (body_builder *obj)
	Be informed that we have been adopted by obj, our new parent.

virtual void	will_be_foresaken_by (body_builder *obj)
	Be informed that we are about to be foresaken by obj, our soon former parent.

virtual void	css_classes_have_changed ()
	Be informed about css class modification. More...

virtual void	new_css_library_available ()

unsigned int	size () const
	access to adopted childs

body_builder *	operator[] (unsigned int i)
	access to adopted childs

body_builder *	get_parent () const
	return the parent object or nullptr if no object has adopted this object

template<class T >
void	closest_ancestor_of_type (T *&ancestor)
	access to the closest ancestor (parent) matching (dynamic_cast) the provided type More...

void	orphan_all_children ()
	orphan all adopted children

bool	get_no_CR () const
	true if it has been requested no to add Carriage Return after the HTML object

Protected Member Functions inherited from reference
virtual void	broken_peering_from (reference *obj)
	to be informed when a peer has broke the peering with me More...

void	reset_read_peers () const
	reset the peers reading

bool	read_next_peer (reference *&peer) const

Protected Member Functions inherited from events
virtual void	broken_peering_from (reference *obj) override
	inherited from class reference More...

void	register_name (const std::string &name)
	add a new event for actors to register against

void	unregister_name (const std::string &name)
	remove an event and remove all actors that registed on it

void	rename_name (const std::string &old_name, const std::string &new_name)
	rename an event and keep all existing peering to this new event More...

void	act (const std::string &name)
	trigger a given event

Detailed Description

body_builder component, providing an html interface to libdar::user_interaction

adoption tree (= how the component show on the browser)

+-h_global----------------------------------+
|                                           |
|                                           |
|+-h_logs----------------------------------+|
|| h_warnings (libdar messages/warnings    ||
|+-----------------------------------------+|
|+-h_form----------------------------------+|
||+-h_inter-------------------------------+||
||| h_inter_text (question from libdar)   |||
||| h_pause (radio button yes/no)         |||
||+---------------------------------------+||
||+---------------------------------------+||
||| h_get_string(string asked from libdar)|||
||+---------------------------------------+||
|+-----------------------------------------+|
|                                           |
|+-----------------------------------------+|
|| stats (libdar::statistics)              ||
|+-----------------------------------------+|
|                                           |
| +-------+  +-------+             +-------+|
| | ask   |  | force |             |finish ||
| | close |  | close |             |       ||
| +-------+  +-------+             +-------+|
+-------------------------------------------+

usage: once created, this component can be adopted from another body_builder

The caller should use get_user_interaction() to provide a user interaction to a libthreadar::thread object for it can interact with the user thanks to this html_web_user_interaction but the caller should not run() the thread directly. Instead, the caller should invoke the run_and_control_thread() method passing the thread object to run as argument.

the caller (code) can still access the thread object as usually except for the join() method which should not be called directly. While the thread is running, the (web) user can also interact with the thread, using the button that shows at the bottom of the component. Once the thread has finished, the component can automatically hide from the UI (auto_hide(true)) or stay visible until the user press the "finish" html_button. the caller (code) can register to the libdar_has_finished event to be notified when the thread has ended as detected by this html_web_user_interaction (for that its get_body_part() must be regularly invoked). This can be done by mean of page refresh, though, this is not always good to use, in particular when the user (web UI side) has to fill some html fields. For that reasons two additional events

can_refresh
dont_refresh are available and can be registered from the caller to avoid freshing the HTML page when it conflicts with the expected HTML behavior.

Last, the caller (code) can call the join_controlled_thread(). This call is a substitute for the libthreadar::thread::join() which one must not be called directly. It will suspend the caller until the controlled thread has completed. Of course, this call can be run upon libdar_has_finished event reception, in which case join_controlled_thread() will return immediately. But at the difference of join() it will not rethrow exceptions, as this will be done by the html_web_user_interaction itself while asked to get_body_par() / inherited_get_body_part().
Note
to communicate with a libdar thread, this class relies on a web_user_interaction objects that manages exclusive access (using mutex) to data structures provided and requested by libdar.

Member Function Documentation

◆ auto_hide()

void html_web_user_interaction::auto_hide	(	bool	mode,
		bool	unless_interrupted
	)

inline

when the control thread has finished, this html_web_user_interaction object becomes invisible

by default the object stays visible and user has to click on the "close" button to go forward

Parameters

[in]	mode	if set to true, no "close" button shows once the thread has complete
[in]	unless_interrupted	if set to true and the thread has ended due to user request the autohide feature is disabled and a "close" button shows.

◆ clear()

void html_web_user_interaction::clear ( )

clear counters, logs and reset html interface and make the component become visible if it was not already

Note: this implies hide_statistics, but counters labels stay untouched.

Warning: this call should not be run when a thread has been given to run_and_control_thread() until the libdar_has_finished event occured.

◆ hide_statistics()

void html_web_user_interaction::hide_statistics ( )

inline

hide statistics fields in the web interface

Note: get_statistics() unhides the field and it is hidden again, when calling clear()

◆ inherited_get_body_part()

string html_web_user_interaction::inherited_get_body_part	(	const chemin &	path,
		const request &	req
	)

overrideprotectedvirtual

inherited from body_builder, called by the webdar thread

Implements body_builder.

◆ join_controlled_thread()

void html_web_user_interaction::join_controlled_thread ( )

let the calling thread suspended until the controlled thread ends (the one passed to run_and_control_thread())

unlike the join() call of libthreadar::thread that should always be called after run(), this method here, is only necessary if a parent thread needs to wait for a thread controlled by "this". This call does not propagate exception from the child thread, this is done from the get_body_part() of the html_web_user_interaction object.

Note: , join_controlled_thread() must not be called by the same thread that updates "this" component, by mean of [inherited_]get_body_part(), because this call could be suspended and the monitored thread status could not be updated, leading the join_controlled_thread() to never exit from suspension.

◆ my_visibility_has_changed()

void html_web_user_interaction::my_visibility_has_changed ( )

overrideprotectedvirtual

available for inherited class to be informed when their visibility changes

Reimplemented from body_builder.

◆ new_css_library_available()

void html_web_user_interaction::new_css_library_available ( )

overrideprotectedvirtual

this is a trigger, ran when a css_library becomes available in a parent or "this"

Note: this may also be triggered upon adoption by a object having acces to a css_library

Reimplemented from body_builder.

◆ on_event()

void html_web_user_interaction::on_event ( const std::string & event_name )

overridevirtual

inherited from actor

Implements actor.

◆ run_and_control_thread()

void html_web_user_interaction::run_and_control_thread ( libthreadar::thread * arg )

provide a libdar thread to be managed by this html_web_component (stop actions)

Parameters

[in] arg is the thread to be managed, it must have been setup but not run() by the caller this method will run() the thread, monitor its liveness then join() it when it has completed.

The caller can either register to the event libdar_has_finished to be informed when the thread will have completed or directly call join_controlled_thread() in which case it will be suspending for the thread to terminate.

In case the controlled thread is interrupted by an exception, this exception is propagated to the controlling thread while the body_builder::get_body_part() / inherited_get_body_part() method is invoked.

During the life of the thread, this body_builder component displays buttons to stop the provided thread, as well as the output of the get_user_interaction() returned component (which is a libdar::user_interaction object).

Note: the run_and_control_thread() method cannot be invoked while a thread is already managed by this object.; , this is the duty of the caller to give to the thread as libdar::user_interaction the web_user_interaction object returned by the get_user_interaction() method, for libdar to also interact with the user (display message, ask questions), using this html_web_user_interaction.; , the provided thread object is not memory-managed/allocated by this object, it must exist during the whole life of the object until it ends or is aborted

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

html_web_user_interaction.hpp
html_web_user_interaction.cpp

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Function Documentation

◆ auto_hide()

◆ clear()

◆ hide_statistics()

◆ inherited_get_body_part()

◆ join_controlled_thread()

◆ my_visibility_has_changed()

◆ new_css_library_available()

◆ on_event()

◆ run_and_control_thread()