xtd::forms::background_worker Class Reference

Inheritance diagram for xtd::forms::background_worker:

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, string::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(string::format("{}{}", std::any_cast<string>(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(string::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.

Public Events
event< background_worker, do_work_event_handler >	do_work
	Occurs when run_worker_async() is called.
event< background_worker, progress_changed_event_handler >	progress_changed
	Occurs when report_progress(int32) is called.
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.

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

Public Properties
bool	cancellation_pending () const noexcept
	Gets a value indicating whether the application has requested cancellation of a background operation.
bool	is_busy () const noexcept
	Gets a value indicating whether the background_worker is running an asynchronous operation.
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.
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.
bool	worker_supports_cancellation () const noexcept
	Gets a value indicating whether the background_worker supports asynchronous cancellation.
void	worker_supports_cancellation (bool value)
	Gets a value indicating whether the background_worker supports asynchronous cancellation.

Public Methods
void	cancel_async ()
	Requests cancellation of a pending background operation.
virtual void	on_do_work (do_work_event_args &e)
	Raises the background_worker::do_work event.
virtual void	on_progress_changed (const progress_changed_event_args &e)
	Raises the background_worker::progress_changed event.
virtual void	on_run_worker_completed (const run_worker_completed_event_args &e)
	Raises the background_worker::run_worker_completed event.
void	run_worker_async ()
	Starts execution of a background operation.
template<typename argument_t >
void	run_worker_async (argument_t argument)
	Starts execution of a background operation.
void	report_progress (int32 percent_progress)
	Raises the ProgressChanged event.
void	report_progress (int32 percent_progress, std::any user_state)
	Raises the ProgressChanged event.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<typename object_a_t , typename object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.
Protected Member Functions inherited from xtd::forms::component
	component ()
	Initialises a new instance of the component class.
virtual bool	can_raise_events () const noexcept
	Gets a value indicating whether the component can raise an event.
bool	design_mode () const noexcept
	Gets a value that indicates whether the component is currently in design mode.

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

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.

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.

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.

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.

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;

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.

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