xtd 0.2.0
Loading...
Searching...
No Matches
xtd::timers::timer Class Reference
Inheritance diagram for xtd::timers::timer:
xtd::object

Definition

Generates an event after a set interval, with an option to generate recurring events.

Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
Generates an event after a set interval, with an option to generate recurring events.
Definition timer.h:50
#define core_export_
Define shared library export.
Definition core_export.h:13
Inheritance
xtd::objectxtd::timers::timer
Header
#include <xtd/threading/timer>
Namespace
xtd::threading
Library
xtd.core
Remarks
The xtd::timers::timer component is a server-based timer that raises an xtd::timers::timer::elapsed event in your application after the number of milliseconds in the xtd::timers::timer::interval property has elapsed. You can configure the xtd::timers::timer object to raise the event just once or repeatedly using the xtd::timers::timer::auto_reset property. Typically, a xtd::timers::timer object is declared at the class level so that it stays in scope as long as it is needed. You can then handle its xtd::timers::timer::elapsed event to provide regular processing. For example, suppose you have a critical server that must be kept running 24 hours a day, 7 days a week. You could create a service that uses a xtd::timers::timer object to periodically check the server and ensure that the system is up and running. If the system is not responding, the service could attempt to restart the server or notify an administrator.
The server-based xtd::timers::timer class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised xtd::timers::timer::elapsed event, resulting in more accuracy than Windows timers in raising the event on time.
The xtd::timers::timer component raises the xtd::timers::timer::elapsed event, based on the value (in milliseconds) of the xtd::timers::timer::interval property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a xtd::timers::timer to start the batch processing every 30 minutes.
Warning
The xtd::timers::timer class has the same resolution as the system clock. This means that the xtd::timers::timer::elapsed event will fire at an interval defined by the resolution of the system clock if the xtd::timers::timer::interval property is less than the resolution of the system clock. For more information, see the xtd::timers::timer::interval property.
Note
The system clock that is used is the same clock used by GetTickCount, which is not affected by changes made with timeBeginPeriod and timeEndPeriod.
Remarks
When xtd::timers::timer::auto_reset is set to false, a xtd::timers::timer object raises the xtd::timers::timer::elapsed event only once, after the first xtd::timers::timer::iInterval has elapsed. To keep raising the xtd::timers::timer::elapsed event regularly at the interval defined by the xtd::timers::timer::interval, set xtd::timers::timer::auto_reset to true, which is the default value.
If the xtd::timers::timer::synchronizing_object property is equal to std::nullopt, the xtd::timers::timer::elapsed event is raised on a xtd::threading::thread_pool thread. If processing of the xtd::timers::timer::elapsed event lasts longer than xtd::timers::timer::interval, the event might be raised again on another xtd::threading::thread_pool thread. In this situation, the event handler should be reentrant.
Note
The event-handling method might run on one thread at the same time that another thread calls the xtd::timers::timer::stop method or sets the xtd::timers::timer::enabled property to false. This might result in the xtd::timers::timer::elapsed event being raised after the timer is stopped. The example code for the xtd::timers::timerstop method shows one way to avoid this race condition.
Remarks
Even if xtd::timers::timer::synchronizing_object is not equal to std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the xtd::timers::timer::enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events.
If you use the xtd::timers::timer class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the xtd::timers::timer to the xtd::timers::timer::synchronizing_object property, so that the event is marshaled to the user interface thread.
For a list of default property values for an instance of xtd::timers::timer, see the xtd::timers::timer::timer constructor.
Note
xtd includes several timer classes, each of which offers different functionality:
  • xtd::timers::timer, which fires an event and executes the code in one or more event sinks at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime.
  • xtd::threading::timer, which executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the xtd::timers::timer class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime.
  • xtd::forms::timer, a Windows Forms component that fires an event and executes the code in one or more event sinks at regular intervals. The component has no user interface and is designed for use in a single-threaded environment; it executes on the UI thread.
Examples
The following example instantiates a xtd::timers::timer object that fires its xtd::timers::timer::elapsed event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the xtd::timers::elapsed_event_args::signal_time property each time it is raised.
#include <xtd/timers/timer>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::timers;
namespace timer_example {
class program {
public:
static void main() {
set_timer();
console::write_line("\nPress the Enter key to exit the application...\n");
console::write_line("The application started at {:t}.{:d3}", date_time::now(), date_time::now().millisecond());
console::read_line();
a_timer.stop();
a_timer.close();
console::write_line("Terminating the application...");
}
static void set_timer() {
// Hook up the elapsed event for the timer.
a_timer.elapsed += on_timed_event;
a_timer.auto_reset(true);
a_timer.enabled(true);
}
static void on_timed_event(object& source, const elapsed_event_args& e) {
console::write_line("The elapsed event was raised at {:t}.{:d3}",
e.signal_time(), e.signal_time().millisecond());
}
private:
// Create a timer with a two second interval.
inline static timer a_timer {2'000};
};
}
startup_(timer_example::program::main);
// This example produces output similar to the following:
//
// Press the Enter key to exit the application...
//
// The application started at 22:12:37.523
// The elapsed event was raised at 22:12:39.531
// The elapsed event was raised at 22:12:41.537
// The elapsed event was raised at 22:12:43.543
// The elapsed event was raised at 22:12:45.548
// The elapsed event was raised at 22:12:47.553
// The elapsed event was raised at 22:12:49.557
// The elapsed event was raised at 22:12:51.560
// The elapsed event was raised at 22:12:53.565
// The elapsed event was raised at 22:12:55.570
//
// Terminating the application...
Provides data for the xtd::timers::timer::elapsed event.
Definition elapsed_event_args.h:18
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
@ e
The E key.
Provides the xtd::timers::timer component, which allows you to raise an event on a specified interval...
Definition elapsed_event_args.h:11
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
Examples
timers_timer.cpp, and timers_timer_synchronizing_object.cpp.

Public Events

event< timer, elapsed_event_handlerelapsed
 Occurs when the interval elapses.
 

Public Constructors

 timer ()
 Initializes a new instance of the xtd::timers::timer class, and sets all the properties to their initial values.
 
 timer (double interval)
 Initializes a new instance of the xtd::timers::timer class, and sets the xtd::timers::timer::interval property to the specified number of milliseconds.
 
 timer (const xtd::time_span &interval)
 Initializes a new instance of the xtd::timers::timer class, setting the xtd::timers::timer::interval property to the specified period.
 

Public Properties

bool auto_reset () const noexcept
 Gets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).
 
timerauto_reset (bool value)
 Sets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).
 
bool enabled () const noexcept
 Gets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.
 
timerenabled (bool value)
 Sets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.
 
double interval () const noexcept
 Gets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.
 
timerinterval (double value)
 Sets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.
 
std::optional< std::reference_wrapper< isynchronize_invoke > > synchronizing_object () const noexcept
 Gets the object used to marshal event-handler calls that are issued when an interval has elapsed.
 
timersynchronizing_object (isynchronize_invoke &value)
 Sets the object used to marshal event-handler calls that are issued when an interval has elapsed.
 
timersynchronizing_object (std::nullptr_t value)
 Resets the object used to marshal event-handler calls that are issued when an interval has elapsed.
 

Public Methods

void close ()
 Releases the resources used by the xtd::timers::timer.
 
void start ()
 Starts raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to true.
 
void stop ()
 Stops raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to false.
 

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.
 

Constructor & Destructor Documentation

◆ timer() [1/3]

xtd::timers::timer::timer ( )

Initializes a new instance of the xtd::timers::timer class, and sets all the properties to their initial values.

Remarks
The following table shows initial property values for an instance of xtd::timers::timer.
Property Initial alue
xtd::timers::timer::auto_reset true
xtd::timers::timer::enabled false
xtd::timers::timer::nterval 100 milliseconds
xtd::timers::timer::synchronizing_object std::nullopt

◆ timer() [2/3]

xtd::timers::timer::timer ( double  interval)
explicit

Initializes a new instance of the xtd::timers::timer class, and sets the xtd::timers::timer::interval property to the specified number of milliseconds.

Parameters
intervalThe time, in milliseconds, between events. The value must be greater than zero and less than or equal to int32_object::max_value.
Exceptions
d::argument_exceptionThe value of the interval parameter is less than or equal to zero, or greater than int32_object::max_value.
Remarks
This constructor sets the xtd::timers::timer::interval property of the new timer instance, but does not enable the timer.

◆ timer() [3/3]

xtd::timers::timer::timer ( const xtd::time_span interval)
explicit

Initializes a new instance of the xtd::timers::timer class, setting the xtd::timers::timer::interval property to the specified period.

Parameters
intervalThe time between events. The value in milliseconds must be greater than zero and less than or equal to int32_object::max_value.

Member Function Documentation

◆ auto_reset() [1/2]

bool xtd::timers::timer::auto_reset ( ) const
noexcept

Gets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).

Returns
true if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event each time the interval elapses; false if it should raise the xtd::timers::timer::elapsed event only once, after the first time the interval elapses. The default is true.
Remarks
If the xtd::timers::timer is already enabled when the xtd::timers::timer::start method is called, the interval is reset. If xtd::timers::timer::auto_reset is false, the xtd::timers::timer::start method must be called in order to start the count again.
Resetting the interval affects when the xtd::timers::timer::elapsed event is raised. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when the count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after the xtd::timers::timer::enabled property was set to true.

◆ auto_reset() [2/2]

timer & xtd::timers::timer::auto_reset ( bool  value)

Sets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).

Parameters
valuetrue if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event each time the interval elapses; false if it should raise the xtd::timers::timer::elapsed event only once, after the first time the interval elapses. The default is true.
Remarks
If the xtd::timers::timer is already enabled when the xtd::timers::timer::start method is called, the interval is reset. If xtd::timers::timer::auto_reset is false, the xtd::timers::timer::start method must be called in order to start the count again.
Resetting the interval affects when the xtd::timers::timer::elapsed event is raised. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when the count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after the xtd::timers::timer::enabled property was set to true.

◆ enabled() [1/2]

bool xtd::timers::timer::enabled ( ) const
noexcept

Gets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.

Returns
true if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event; otherwise, false. The default is false.
Exceptions
xtd::object_closed_exceptionThis property cannot be set because the timer has been closed.
xtd::argument_exceptionThe xtd::timers::timer::interval property was set to a value greater than xtd::int32_object::max_value before the timer was enabled.
Remarks
Setting xtd::timers::timer::enabled to true is the same as calling xtd::timers::timer::start, while setting xtd::timers::timer::enabled to false is the same as calling xtd::timers::timer::stop.
Note
The signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a xtd::threading::thread_pool thread. This might result in the xtd::timers::timer::elapsed event being raised after the xtd::timers::timer::enabled property is set to false. The code example for the xtd::timers::timer::stop method shows one way to work around this race condition.
Remarks
If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses.
If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after Enabled was set to true.

◆ enabled() [2/2]

timer & xtd::timers::timer::enabled ( bool  value)

Sets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.

Parameters
valuetrue if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event; otherwise, false. The default is false.
Exceptions
xtd::object_closed_exceptionThis property cannot be set because the timer has been closed.
xtd::argument_exceptionThe xtd::timers::timer::interval property was set to a value greater than xtd::int32_object::max_value before the timer was enabled.
Remarks
Setting xtd::timers::timer::enabled to true is the same as calling xtd::timers::timer::start, while setting xtd::timers::timer::enabled to false is the same as calling xtd::timers::timer::stop.
Note
The signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a xtd::threading::thread_pool thread. This might result in the xtd::timers::timer::elapsed event being raised after the xtd::timers::timer::enabled property is set to false. The code example for the xtd::timers::timer::stop method shows one way to work around this race condition.
Remarks
If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses.
If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after Enabled was set to true.

◆ interval() [1/2]

double xtd::timers::timer::interval ( ) const
noexcept

Gets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.

Returns
The time, in milliseconds, between xtd::timers::timer::elapsed events. The value must be greater than zero, and less than or equal to xtd::int32_object::max_value. The default is 100 milliseconds.
Exceptions
xtd::argument_exceptionThe interval is less than or equal to zero.
-or
The interval is greater than xtd::int32_object::max_value.
Remarks
You use the xtd::timers::timer::interval property to determine the frequency at which the xtd::timers::timer::elapsed event is fired. Because the xtd::timers::timer class depends on the system clock, it has the same resolution as the system clock. This means that the xtd::timers::timer::elapsed event will fire at an interval defined by the resolution of the system clock if the xtd::timers::timer::interval property is less than the resolution of the system clock. The following example sets the xtd::timers::timer::interval property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds.
Note
The system clock that is used is the same clock used by GetTickCount, which is not affected by changes made with timeBeginPeriod and timeEndPeriod.
Remarks
If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after xtd::timers::timer::enabled was set to true.
If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses. xtd::timers::timer::enabled is then set to false.
Note
If xtd::timers::timer::enabled and xtd::timers::timer::auto_reset are both set to false, and the timer has previously been enabled, setting the xtd::timers::timer::interval property causes the xtd::timers::timer::elapsed event to be raised once, as if the xtd::timers::timer::enabled property had been set to true. To set the interval without raising the event, you can temporarily set the xtd::timers::timer::enabled property to true, set the xtd::timers::timer::interval property to the desired time interval, and then immediately set the xtd::timers::timer::enabled property back to false.

◆ interval() [2/2]

timer & xtd::timers::timer::interval ( double  value)

Sets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.

Parameters
valueThe time, in milliseconds, between xtd::timers::timer::elapsed events. The value must be greater than zero, and less than or equal to xtd::int32_object::max_value. The default is 100 milliseconds.
Exceptions
xtd::argument_exceptionThe interval is less than or equal to zero.
-or
The interval is greater than xtd::int32_object::max_value.
Remarks
You use the xtd::timers::timer::interval property to determine the frequency at which the xtd::timers::timer::elapsed event is fired. Because the xtd::timers::timer class depends on the system clock, it has the same resolution as the system clock. This means that the xtd::timers::timer::elapsed event will fire at an interval defined by the resolution of the system clock if the xtd::timers::timer::interval property is less than the resolution of the system clock. The following example sets the xtd::timers::timer::interval property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds.
Note
The system clock that is used is the same clock used by GetTickCount, which is not affected by changes made with timeBeginPeriod and timeEndPeriod.
Remarks
If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after xtd::timers::timer::enabled was set to true.
If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses. xtd::timers::timer::enabled is then set to false.
Note
If xtd::timers::timer::enabled and xtd::timers::timer::auto_reset are both set to false, and the timer has previously been enabled, setting the xtd::timers::timer::interval property causes the xtd::timers::timer::elapsed event to be raised once, as if the xtd::timers::timer::enabled property had been set to true. To set the interval without raising the event, you can temporarily set the xtd::timers::timer::enabled property to true, set the xtd::timers::timer::interval property to the desired time interval, and then immediately set the xtd::timers::timer::enabled property back to false.

◆ synchronizing_object() [1/3]

std::optional< std::reference_wrapper< isynchronize_invoke > > xtd::timers::timer::synchronizing_object ( ) const
noexcept

Gets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Returns
The xtd::isynchronize_invoke representing the object used to marshal the event-handler calls that are issued when an interval has elapsed. The default is std::nullopt.
Remarks
When xtd::timers::timer::synchronizing_object is std::nullopt, the method that handles the xtd::timers::timer::elapsed event is called on a thread from the system-thread pool. For more information on system-thread pools, see xtd::threading::thread_pool.
When the xtd::timers::timer::elapsed event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting xtd::timers::timer::synchronizing_object to a Windows Forms component, which causes the method that handles the xtd::timers::timer::elapsed event to be called on the same thread that the component was created on.
Note
Even if the xtd::timers::timer::synchronizing_object property is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the Enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events.
Examples
The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the xtd::timers::timer::interval property is set to one minute (60,000 milliseconds), and the xtd::timers::timer::synchronizing_object property is set to the xtd::forms::form object.
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/forms/save_file_dialog>
#include <xtd/forms/text_box>
#include <xtd/io/stream_writer>
#include <xtd/timers/timer>
#include <xtd/date_time>
#include <xtd/startup>
#include <memory>
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::io;
using namespace xtd::timers;
namespace timer_example {
class form1 : public form {
public:
static void main() {
application::run(form1 {});
}
form1() {
initialize_component();
text("Quick Text Editor");
button1.text("Save");
text_box1.multiline(true);
// Configure the SaveFile dialog
save_file_dialog1.filter("txt files (*.txt)|*.txt|All files (*.*)|*.*");
save_file_dialog1.restore_directory(true);
// Define the event handler
timer.elapsed += {*this, &form1::prompt_for_save};
// Synchronize the timer with the text box
timer.synchronizing_object(*this);
// Start the timer
timer.auto_reset(true);
}
private:
void initialize_component() {
form_closing += {*this, &form1::form1_form_closing};
controls().push_back_range({text_box1, button1});
button1.dock(dock_style::bottom);
button1.click += {*this, &form1::button1_click};
text_box1.dock(dock_style::fill);
text_box1.text_changed += {*this, &form1::text_box1__text_changed};
}
void prompt_for_save(object& source, const elapsed_event_args& e) {
if (has_changed && !dialog_is_open) {
elapsed_minutes++;
dialog_is_open = true;
if (message_box::show(string::format("{0} minutes have elapsed since the text was saved. Save it now? ",
elapsed_minutes), "Save Text",
message_box_buttons::yes_no_cancel, message_box_icon::question) == dialog_result::yes)
button1_click(*this, event_args::empty);
}
dialog_is_open = false;
}
void button1_click(object& sender, const event_args& e) {
if (string::is_empty(save_file_dialog1.file_name())) {
if (save_file_dialog1.show_dialog() == dialog_result::ok)
sw = new_ptr<stream_writer>(save_file_dialog1.file_name(), false);
}
txt = text_box1.text();
has_changed = false;
}
void form1_form_closing(object& sender, form_closing_event_args& e) {
timer.close();
if (sw != null) {
sw->write(txt);
sw->close();
}
}
void text_box1__text_changed(object& sender, const event_args& e) {
has_changed = true;
}
save_file_dialog save_file_dialog1;
text_box text_box1;
bool dialog_is_open = false;
int elapsed_minutes = 0;
bool has_changed = false;
string txt;
// Create a timer with a 1-minute interval
timers::timer timer {60'000};
};
}
startup_(timer_example::form1::main);
Represents the base class for classes that contain event data, and provides a value to use for events...
Definition event_args.h:18
Represents a Windows button control.
Definition button.h:49
Provides data for the form_closing event.
Definition form_closing_event_args.h:22
Represents a window or dialog box that makes up an application's user interface.
Definition form.h:54
Prompts the user to select a location for saving a file. This class cannot be inherited.
Definition save_file_dialog.h:30
Represents a standard Windows text box.
Definition text_box.h:31
Implements a timer that raises an event at user-defined intervals. This timer is optimized for use in...
Definition timer.h:38
void stop()
Starts the timer.
void start()
Stops the timer.
xtd::sptr< type_t > ptr
The xtd::ptr object is a shared pointer.
Definition ptr.h:27
@ button1
The first button on the message box is the default button.
The xtd::forms namespace contains classes for creating Windows-based applications that take full adva...
Definition xtd_about_box.h:12
The xtd::io namespace contains types that allow reading and writing to files and data streams,...
Definition binary_reader.h:16

◆ synchronizing_object() [2/3]

timer & xtd::timers::timer::synchronizing_object ( isynchronize_invoke value)

Sets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Parameters
valueThe xtd::isynchronize_invoke representing the object used to marshal the event-handler calls that are issued when an interval has elapsed. The default is std::nullopt.
Remarks
When xtd::timers::timer::synchronizing_object is std::nullopt, the method that handles the xtd::timers::timer::elapsed event is called on a thread from the system-thread pool. For more information on system-thread pools, see xtd::threading::thread_pool.
When the xtd::timers::timer::elapsed event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting xtd::timers::timer::synchronizing_object to a Windows Forms component, which causes the method that handles the xtd::timers::timer::elapsed event to be called on the same thread that the component was created on.
Note
Even if the xtd::timers::timer::synchronizing_object property is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the Enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events. The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the xtd::timers::timer::interval property is set to one minute (60,000 milliseconds), and the xtd::timers::timer::synchronizing_object property is set to the xtd::forms::form object.
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/forms/save_file_dialog>
#include <xtd/forms/text_box>
#include <xtd/io/stream_writer>
#include <xtd/timers/timer>
#include <xtd/date_time>
#include <xtd/startup>
#include <memory>
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::io;
using namespace xtd::timers;
namespace timer_example {
class form1 : public form {
public:
static void main() {
application::run(form1 {});
}
form1() {
initialize_component();
text("Quick Text Editor");
button1.text("Save");
text_box1.multiline(true);
// Configure the SaveFile dialog
save_file_dialog1.filter("txt files (*.txt)|*.txt|All files (*.*)|*.*");
save_file_dialog1.restore_directory(true);
// Define the event handler
timer.elapsed += {*this, &form1::prompt_for_save};
// Synchronize the timer with the text box
timer.synchronizing_object(*this);
// Start the timer
timer.auto_reset(true);
}
private:
void initialize_component() {
form_closing += {*this, &form1::form1_form_closing};
controls().push_back_range({text_box1, button1});
button1.dock(dock_style::bottom);
button1.click += {*this, &form1::button1_click};
text_box1.dock(dock_style::fill);
text_box1.text_changed += {*this, &form1::text_box1__text_changed};
}
void prompt_for_save(object& source, const elapsed_event_args& e) {
if (has_changed && !dialog_is_open) {
elapsed_minutes++;
dialog_is_open = true;
if (message_box::show(string::format("{0} minutes have elapsed since the text was saved. Save it now? ",
elapsed_minutes), "Save Text",
message_box_buttons::yes_no_cancel, message_box_icon::question) == dialog_result::yes)
button1_click(*this, event_args::empty);
}
dialog_is_open = false;
}
void button1_click(object& sender, const event_args& e) {
if (string::is_empty(save_file_dialog1.file_name())) {
if (save_file_dialog1.show_dialog() == dialog_result::ok)
sw = new_ptr<stream_writer>(save_file_dialog1.file_name(), false);
}
txt = text_box1.text();
has_changed = false;
}
void form1_form_closing(object& sender, form_closing_event_args& e) {
timer.close();
if (sw != null) {
sw->write(txt);
sw->close();
}
}
void text_box1__text_changed(object& sender, const event_args& e) {
has_changed = true;
}
save_file_dialog save_file_dialog1;
text_box text_box1;
bool dialog_is_open = false;
int elapsed_minutes = 0;
bool has_changed = false;
string txt;
// Create a timer with a 1-minute interval
timers::timer timer {60'000};
};
}
startup_(timer_example::form1::main);

◆ synchronizing_object() [3/3]

timer & xtd::timers::timer::synchronizing_object ( std::nullptr_t  value)

Resets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Parameters
valuenullptr.
Remarks
When xtd::timers::timer::synchronizing_object is std::nullopt, the method that handles the xtd::timers::timer::elapsed event is called on a thread from the system-thread pool. For more information on system-thread pools, see xtd::threading::thread_pool.
When the xtd::timers::timer::elapsed event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting xtd::timers::timer::synchronizing_object to a Windows Forms component, which causes the method that handles the xtd::timers::timer::elapsed event to be called on the same thread that the component was created on.
Note
Even if the xtd::timers::timer::synchronizing_object property is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the Enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events. The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the xtd::timers::timer::interval property is set to one minute (60,000 milliseconds), and the xtd::timers::timer::synchronizing_object property is set to the xtd::forms::form object.
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/forms/save_file_dialog>
#include <xtd/forms/text_box>
#include <xtd/io/stream_writer>
#include <xtd/timers/timer>
#include <xtd/date_time>
#include <xtd/startup>
#include <memory>
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::io;
using namespace xtd::timers;
namespace timer_example {
class form1 : public form {
public:
static void main() {
application::run(form1 {});
}
form1() {
initialize_component();
text("Quick Text Editor");
button1.text("Save");
text_box1.multiline(true);
// Configure the SaveFile dialog
save_file_dialog1.filter("txt files (*.txt)|*.txt|All files (*.*)|*.*");
save_file_dialog1.restore_directory(true);
// Define the event handler
timer.elapsed += {*this, &form1::prompt_for_save};
// Synchronize the timer with the text box
timer.synchronizing_object(*this);
// Start the timer
timer.auto_reset(true);
}
private:
void initialize_component() {
form_closing += {*this, &form1::form1_form_closing};
controls().push_back_range({text_box1, button1});
button1.dock(dock_style::bottom);
button1.click += {*this, &form1::button1_click};
text_box1.dock(dock_style::fill);
text_box1.text_changed += {*this, &form1::text_box1__text_changed};
}
void prompt_for_save(object& source, const elapsed_event_args& e) {
if (has_changed && !dialog_is_open) {
elapsed_minutes++;
dialog_is_open = true;
if (message_box::show(string::format("{0} minutes have elapsed since the text was saved. Save it now? ",
elapsed_minutes), "Save Text",
message_box_buttons::yes_no_cancel, message_box_icon::question) == dialog_result::yes)
button1_click(*this, event_args::empty);
}
dialog_is_open = false;
}
void button1_click(object& sender, const event_args& e) {
if (string::is_empty(save_file_dialog1.file_name())) {
if (save_file_dialog1.show_dialog() == dialog_result::ok)
sw = new_ptr<stream_writer>(save_file_dialog1.file_name(), false);
}
txt = text_box1.text();
has_changed = false;
}
void form1_form_closing(object& sender, form_closing_event_args& e) {
timer.close();
if (sw != null) {
sw->write(txt);
sw->close();
}
}
void text_box1__text_changed(object& sender, const event_args& e) {
has_changed = true;
}
save_file_dialog save_file_dialog1;
text_box text_box1;
bool dialog_is_open = false;
int elapsed_minutes = 0;
bool has_changed = false;
string txt;
// Create a timer with a 1-minute interval
timers::timer timer {60'000};
};
}
startup_(timer_example::form1::main);

◆ close()

void xtd::timers::timer::close ( )

Releases the resources used by the xtd::timers::timer.

◆ start()

void xtd::timers::timer::start ( )

Starts raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to true.

Remarks
If xtd::timers::timer::start is called and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses. If xtd::timers::timer::start is called and xtd::timers::timer::auto_reset is true, the xtd::timers::timer raises the xtd::timers::timer::elapsed event the first time the interval elapses and continues to raise the event on the specified interval.
Note
If xtd::timers::timer::auto_reset is false, the xtd::timers::timer::start method must be called in order to start the count again.

◆ stop()

void xtd::timers::timer::stop ( )

Stops raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to false.

Remarks
You can also stop timing by setting xtd::timers::timer::enabled to false.
Note
The signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a xtd::threading::thread_pool thread, so the event-handling method might run on one thread at the same time that a call to the xtd::timers::timer::stop method runs on another thread. This might result in the xtd::timers::timer::elapsed event being raised after the xtd::timers::timer::stop method is called. The second code example in the Examples section shows one way to work around this race condition.

Member Data Documentation

◆ elapsed

event<timer, elapsed_event_handler> xtd::timers::timer::elapsed

Occurs when the interval elapses.

Remarks
The xtd::timers::timer::elapsed event is raised if the xtd::timers::timer::enabled property is true and the time interval (in milliseconds) defined by the xtd::timers::timer::interval property elapses. If the xtd::timers::timer::auto_reset property is true, the event is raised repeatedly at an interval defined by the xtd::timers::timer::interval property; otherwise, the event is raised only once, the first time the xtd::timers::timer::interval value elapses.
If xtd::timers::timer::interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set xtd::timers::timer::enabled to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after xtd::timers::timer::enabled was set to true.
If the xtd::timers::timer::synchronizing_object property is std::nullopt,the xtd::timers::timer::elapsed event is raised on a xtd::threading::thread_pool thread. If the processing of the xtd::timers::timer::elapsed event lasts longer than xtd::timers::timer::interval, the event might be raised again on another xtd::threading::thread_pool thread. In this situation, the event handler should be reentrant.
Note
The event-handling method might run on one thread at the same time that another thread calls the xtd::timers::timer::stop method or sets the xtd::timers::timer::enabled property to false. This might result in the xtd::timers::timer::elapsed event being raised after the timer is stopped. The example code for the Stop method shows one way to avoid this race condition.
Remarks
Even if xtd::timers::timer::synchronizing_object is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the xtd::timers::timer:enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events.

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