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_mode(forms::auto_size_mode::grow_and_shrink);
      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;
    background_worker worker;
  };
}
 
int main() {
  application::run(examples::form1());
}

Inherits xtd::forms::component.

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

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.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.
Protected Member Functions inherited from xtd::forms::component
	component ()=default
	Initialises a new instance of the component class.
virtual bool	can_raise_events () const
	Gets a value indicating whether the component can raise an event.
bool	design_mode () const
	Gets a value that indicates whether the component is currently in design mode.

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

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 )

inlinevirtual

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 )

inlinevirtual

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_t

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

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

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

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

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.

---

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

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