xtd 0.2.0
xtd::forms::background_worker Class Reference

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(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;
};
}
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_handlerdo_work
 Occurs when run_worker_async() is called. More...
 
event< background_worker, progress_changed_event_handlerprogress_changed
 Occurs when report_progress(int32) is called. More...
 
event< background_worker, run_worker_completed_event_handlerrun_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
eAn 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
eAn 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
eAn 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_progressThe 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_progressThe percentage, from 0 to 100, of the background operation that is complete.
user_stateA 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_exceptionxtd::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
argumentA parameter for use by the background operation to be executed in the xtd::forms::background_worker::do_work event handler.
Exceptions
xtd::invalid_operaton_exceptionxtd::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
valuetrue 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
valuetrue 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: