Definition

Executes an operation on a separate thread.

Header: #include <xtd/forms/background_worker>

Namespace: xtd::forms

Library: xtd.forms

Remarks: The background_worker class allows you to run an operation on a separate, dedicated thread. Time-consuming operations like downloads and database transactions can cause your user interface (UI) to seem as though it has stopped responding while they are running. When you want a responsive UI and you are faced with long delays associated with such operations, the background_worker class provides a convenient solution.; To execute a time-consuming operation in the background, create a background_worker and listen for events that report the progress of your operation and signal when your operation is finished.; To set up for a background operation, add an event handler for the xtd::forms::background_worker::do_work event. Call your time-consuming operation in this event handler. To start the operation, call run_worker_async. To receive notifications of progress updates, handle the progress_changed event. To receive a notification when the operation is completed, handle the run_worker_completed event.

Note: You must be careful not to manipulate any user-interface objects in your xtd::forms::background_worker::do_work event handler. Instead, communicate to the user interface through the progress_changed and run_worker_completed events.

Remarks: If your background operation requires a parameter, call run_worker_async with your parameter. Inside the xtd::forms::background_worker::do_work event handler, you can extract the parameter from the do_work_event_args.argument property.

Examples: The following code example demonstrates the use of background_worker component.
#include <xtd/forms/application>
#include <xtd/forms/background_worker>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/label>
#include <xtd/forms/panel>
#include <xtd/forms/progress_bar>
#include <xtd/forms/text_box>
#include <xtd/threading/thread>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::threading;
namespace background_worker_example {
class form1 : public form {
public:
static void main() {
application::run(background_worker_example::form1 {});
}
form1() {
text("Background worker example");
auto_size_mode(forms::auto_size_mode::grow_and_shrink);
auto_size(true);
form_closed += [&] {
cancel_button.perform_click();
};

command_panel.parent(*this);
command_panel.size({300, 80});
command_panel.controls().push_back_range({run_button, cancel_button, status});

progress_panel.parent(*this);
progress_panel.top(80);
progress_panel.size({300, 155});
progress_panel.controls().push_back_range({progress, progress_text});
progress_panel.visible(false);

run_button.location({10, 10});
run_button.text("Run");
run_button.click += [&] {
progress_panel.visible(true);
cancel_button.enabled(true);
run_button.enabled(false);
worker.run_worker_async();
if (worker.is_busy())
status.text("Status : running");
};

cancel_button.location({215, 10});
cancel_button.text("Cancel");
cancel_button.enabled(false);
cancel_button.click += [&] {
cancel_button.enabled(false);
worker.cancel_async();
};

status.location({10, 50});
status.auto_size(true);
status.text("Status : not started");

progress.location({10, 10});
progress.width(280);

progress_text.location({10, 45});
progress_text.size({280, 100});
progress_text.multiline(true);
progress_text.read_only(true);
progress_text.word_wrap(false);

worker.worker_supports_cancellation(true);
worker.worker_reports_progress(true);
worker.do_work += [&] {
for (auto step = 1; step <= progress.maximum(); ++step) {
if (worker.cancellation_pending()) break; // stop work...
thread::sleep(100_ms); // simulate work...
worker.report_progress(step, ustring::format("step {} / {}", step, progress.maximum()));
}
};

worker.progress_changed += [&](object & sender, const progress_changed_event_args & e) {
progress.value(e.progress_percentage());
progress_text.append_text(ustring::format("{}{}", std::any_cast<ustring>(e.user_state()), environment::new_line()));
};

worker.run_worker_completed += [&](object & sender, const run_worker_completed_event_args & e) {
progress_panel.visible(false);
run_button.enabled(true);
cancel_button.enabled(false);
progress.value(0);
progress_text.text("");
status.text(ustring::format("Status : {}", e.cancel() ? "canceled" : "completed"));
};
}

private:
panel command_panel;
panel progress_panel;
button run_button;
button cancel_button;
label status;
progress_bar progress;
text_box progress_text;
background_worker worker;
};
}
startup_(background_worker_example::form1::main);

Examples:: background_worker.cpp.

Constructors
	background_worker () noexcept
	Initializes a new instance of the background_worker class. More...

Properties
bool	cancellation_pending () const noexcept
	Gets a value indicating whether the application has requested cancellation of a background operation. More...

bool	is_busy () const noexcept
	Gets a value indicating whether the background_worker is running an asynchronous operation. More...

bool	worker_reports_progress () const noexcept
	Gets a value indicating whether the background_worker can report progress updates.Gets or sets a value indicating whether the background_worker can report progress updates. More...

void	worker_reports_progress (bool value)
	Sets a value indicating whether the background_worker can report progress updates.Gets or sets a value indicating whether the background_worker can report progress updates. More...

bool	worker_supports_cancellation () const noexcept
	Gets a value indicating whether the background_worker supports asynchronous cancellation. More...

void	worker_supports_cancellation (bool value)
	Gets a value indicating whether the background_worker supports asynchronous cancellation. More...

Methods
void	cancel_async ()
	Requests cancellation of a pending background operation. More...

virtual void	on_do_work (do_work_event_args &e)
	Raises the background_worker::do_work event. More...

virtual void	on_progress_changed (const progress_changed_event_args &e)
	Raises the background_worker::progress_changed event. More...

virtual void	on_run_worker_completed (const run_worker_completed_event_args &e)
	Raises the background_worker::run_worker_completed event. More...

void	run_worker_async ()
	Starts execution of a background operation. More...

template<typename argument_t >
void	run_worker_async (argument_t argument)
	Starts execution of a background operation. More...

void	report_progress (int32 percent_progress)
	Raises the ProgressChanged event. More...

void	report_progress (int32 percent_progress, std::any user_state)
	Raises the ProgressChanged event. More...

Events
event< background_worker, do_work_event_handler >	do_work
	Occurs when run_worker_async() is called. More...

event< background_worker, progress_changed_event_handler >	progress_changed
	Occurs when report_progress(int32) is called. More...

event< background_worker, run_worker_completed_event_handler >	run_worker_completed
	Occurs when the background operation has completed, has been canceled, or has raised an exception. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...

bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...

virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...

virtual type_object	get_type () const noexcept
	Gets the type of the current instance. More...

template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object. More...

virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object. More...

Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...

static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Protected Member Functions inherited from xtd::forms::component
	component ()
	Initialises a new instance of the component class. More...

virtual bool	can_raise_events () const noexcept
	Gets a value indicating whether the component can raise an event. More...

bool	design_mode () const noexcept
	Gets a value that indicates whether the component is currently in design mode. More...

Constructor & Destructor Documentation

◆ background_worker()

xtd::forms::background_worker::background_worker ( )

noexcept

Initializes a new instance of the background_worker class.

Remarks: This constructor initializes a background_worker.

Member Function Documentation

◆ cancel_async()

void xtd::forms::background_worker::cancel_async ( )

Requests cancellation of a pending background operation.

Remarks: cancel_async submits a request to terminate the pending background operation and sets the cancellation_pending property to true.; When you call cancel_async, your worker method has an opportunity to stop its execution and exit. The worker code should periodically check thecancellation_pending property to see if it has been set to true.

◆ cancellation_pending()

bool xtd::forms::background_worker::cancellation_pending ( ) const

noexcept

Gets a value indicating whether the application has requested cancellation of a background operation.

Returns: true if the application has requested cancellation of a background operation; otherwise, false. The default is false.

◆ is_busy()

bool xtd::forms::background_worker::is_busy ( ) const

noexcept

Gets a value indicating whether the background_worker is running an asynchronous operation.

Returns: true, if the background_worker is running an asynchronous operation; otherwise, false.

◆ on_do_work()

virtual void xtd::forms::background_worker::on_do_work ( do_work_event_args & e )

virtual

Raises the background_worker::do_work event.

Parameters

e	An event_args that contains the event data.

◆ on_progress_changed()

virtual void xtd::forms::background_worker::on_progress_changed ( const progress_changed_event_args & e )

virtual

Raises the background_worker::progress_changed event.

Parameters

e	An event_args that contains the event data.

◆ on_run_worker_completed()

virtual void xtd::forms::background_worker::on_run_worker_completed ( const run_worker_completed_event_args & e )

virtual

Raises the background_worker::run_worker_completed event.

Parameters

e	An event_args that contains the event data.

◆ report_progress() [1/2]

void xtd::forms::background_worker::report_progress ( int32 percent_progress )

Raises the ProgressChanged event.

Parameters

percent_progress The percentage, from 0 to 100, of the background operation that is complete.

◆ report_progress() [2/2]

void xtd::forms::background_worker::report_progress	(	int32	percent_progress,
		std::any	user_state
	)

Raises the ProgressChanged event.

Parameters

percent_progress	The percentage, from 0 to 100, of the background operation that is complete.
user_state	A unique object indicating the user state. Returned as the user_state property of the progress_changed_even_args.

◆ run_worker_async() [1/2]

void xtd::forms::background_worker::run_worker_async ( )

Starts execution of a background operation.

Exceptions

xtd::invalid_operaton_exception xtd::background_worker::is_busy is true;

◆ run_worker_async() [2/2]

template<typename argument_t >

void xtd::forms::background_worker::run_worker_async ( argument_t argument )

inline

Starts execution of a background operation.

Parameters

argument A parameter for use by the background operation to be executed in the xtd::forms::background_worker::do_work event handler.

Exceptions

xtd::invalid_operaton_exception xtd::background_worker::is_busy is true;

◆ worker_reports_progress() [1/2]

bool xtd::forms::background_worker::worker_reports_progress ( ) const

noexcept

Gets a value indicating whether the background_worker can report progress updates.Gets or sets a value indicating whether the background_worker can report progress updates.

Returns: true if the background_worker supports progress updates; otherwise false. The default is false.

Remarks: Set the worker_reports_progress property to true if you want the background_worker to support progress updates. When this property is true, user code can call the report_progress method to raise the progress_changed event.

◆ worker_reports_progress() [2/2]

void xtd::forms::background_worker::worker_reports_progress ( bool value )

Sets a value indicating whether the background_worker can report progress updates.Gets or sets a value indicating whether the background_worker can report progress updates.

Parameters

value true if the background_worker supports progress updates; otherwise false. The default is false.

Remarks: Set the worker_reports_progress property to true if you want the background_worker to support progress updates. When this property is true, user code can call the report_progress method to raise the progress_changed event.

◆ worker_supports_cancellation() [1/2]

bool xtd::forms::background_worker::worker_supports_cancellation ( ) const

noexcept

Gets a value indicating whether the background_worker supports asynchronous cancellation.

Returns: true if the background_worker supports cancellation; otherwise false. The default is false.

Remarks: Set the worker_supports_cancellation property to true if you want the background_worker to support cancellation. When this property is true, you can call the cancel_async method to interrupt a background operation.

◆ worker_supports_cancellation() [2/2]

void xtd::forms::background_worker::worker_supports_cancellation ( bool value )

Gets a value indicating whether the background_worker supports asynchronous cancellation.

Parameters

value true if the background_worker supports cancellation; otherwise false. The default is false.

Remarks: Set the worker_supports_cancellation property to true if you want the background_worker to support cancellation. When this property is true, you can call the cancel_async method to interrupt a background operation.

Member Data Documentation

◆ do_work

event<background_worker, do_work_event_handler> xtd::forms::background_worker::do_work

Occurs when run_worker_async() is called.

Remarks: For more information about handling events, see Handling and Raising Events.

◆ progress_changed

event<background_worker, progress_changed_event_handler> xtd::forms::background_worker::progress_changed

Occurs when report_progress(int32) is called.

Remarks: For more information about handling events, see Handling and Raising Events.

◆ run_worker_completed

event<background_worker, run_worker_completed_event_handler> xtd::forms::background_worker::run_worker_completed

Occurs when the background operation has completed, has been canceled, or has raised an exception.

Remarks: For more information about handling events, see Handling and Raising Events.

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

xtd.forms/include/xtd/forms/background_worker.h

Definition

Constructors

Properties

Methods

Events

Additional Inherited Members

Constructor & Destructor Documentation

◆ background_worker()

Member Function Documentation

◆ cancel_async()

◆ cancellation_pending()

◆ is_busy()

◆ on_do_work()

◆ on_progress_changed()

◆ on_run_worker_completed()

◆ report_progress() [1/2]

◆ report_progress() [2/2]

◆ run_worker_async() [1/2]

◆ run_worker_async() [2/2]

◆ worker_reports_progress() [1/2]

◆ worker_reports_progress() [2/2]

◆ worker_supports_cancellation() [1/2]

◆ worker_supports_cancellation() [2/2]

Member Data Documentation

◆ do_work

◆ progress_changed

◆ run_worker_completed