xtd - Reference Guide  0.2.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Attributes | Public Member Functions | List of all members
xtd::forms::background_worker Class Reference

#include <background_worker.h>

Definition

Executes an operation on a separate thread.

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 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 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 do_work event handler, you can extract the parameter from the do_work_event_args.argument property.
Examples
The following code example demonstrate the use of background_worker component.
#include <chrono>
#include <thread>
#include <xtd/xtd>
using namespace std::literals;
using namespace xtd;
using namespace xtd::forms;
namespace examples {
class form1 : public form {
public:
form1() {
text("Background worker example");
auto_size(true);
controls().push_back_range({panel_command, progress});
form_closed += [&] {
if (worker.is_busy())
worker.cancel_async();
};
panel_command.parent(*this);
panel_command.size({300, 80});
panel_command.controls().push_back_range({button_run, button_cancel, status});
panel_progress.parent(*this);
panel_progress.top(80);
panel_progress.size({300, 155});
panel_progress.controls().push_back_range({progress, list_progress});
panel_progress.visible(false);
button_run.location({10, 10});
button_run.text("Run");
button_run.click += [&] {
panel_progress.visible(true);
button_cancel.enabled(true);
button_run.enabled(false);
worker.run_worker_async();
if (worker.is_busy())
status.text("Status : running");
};
button_cancel.location({215, 10});
button_cancel.text("Cancel");
button_cancel.enabled(false);
button_cancel.click += [&] {
button_cancel.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);
list_progress.location({10, 45});
list_progress.size({280, 100});
list_progress.multiline(true);
list_progress.read_only(true);
list_progress.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...
std::this_thread::sleep_for(100ms); // 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());
list_progress.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){
panel_progress.visible(false);
button_run.enabled(true);
button_cancel.enabled(false);
progress.value(0);
list_progress.text("");
status.text(ustring::format("Status : {}", e.cancel() ? "canceled" : "completed"));
};
}
private:
panel panel_command;
panel panel_progress;
button button_run;
button button_cancel;
label status;
progress_bar progress;
text_box list_progress;
};
}
int main() {
application::run(examples::form1());
}

Public Attributes

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_t) 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...
 

Public Member Functions

 background_worker ()
 Initializes a new instance of the background_worker class. More...
 
void cancel_async ()
 Requests cancellation of a pending background operation. More...
 
bool cancellation_pending () const
 Gets a value indicating whether the application has requested cancellation of a background operation. More...
 
bool is_busy () const
 Gets a value indicating whether the background_worker is running an asynchronous 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 report_progress (int32_t percent_progress)
 Raises the ProgressChanged event. More...
 
void report_progress (int32_t percent_progress, std::any user_state)
 Raises the ProgressChanged 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...
 
bool worker_reports_progress () const
 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
 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...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual 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...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Additional Inherited Members

- 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 ()=default
 Initialises a new instance of the component class. More...
 
virtual bool can_raise_events () const
 Gets a value indicating whether the component can raise an event. More...
 
bool design_mode () const
 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 ( )

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
inline

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
inline

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)
inlinevirtual

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)
inlinevirtual

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)
inlinevirtual

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_t  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_t  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.

◆ 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 do_work event handler.

◆ worker_reports_progress() [1/2]

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

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)
inline

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
inline

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)
inline

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.

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