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

Definition

Implements a timer that raises an event at user-defined intervals. This timer is optimized for use in Windows Forms applications and must be used in a window.

Header
#include <xtd/forms/timer>
Namespace
xtd::forms
Library
xtd.forms
Remarks
A timer is used to raise an event at user-defined intervals. This Windows timer is designed for a single-threaded environment where UI threads are used to perform processing. It requires that the user code have a UI message pump available and always operate from the same thread.
When you use this timer, use the tick event to perform a polling operation or to display a splash screen for a specified period of time. Whenever the enabled property is set to true and the interval property is greater than zero, the tick event is raised at intervals based on the interval property setting.
This class provides methods to set the interval, and to start and stop the timer.
The Windows Forms Timer component is single-threaded, and is limited to an accuracy of 55 milliseconds.
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 code example demonstrates the use of timer component.
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/label>
using namespace xtd;
using namespace xtd::drawing;
using namespace xtd::forms;
namespace timer_example {
class form1 : public form {
public:
form1() {
label1.parent(*this);
label1.text("0.0");
label1.font(drawing::font("Arial", 48, font_style::italic));
label1.location({10, 10});
label1.auto_size(true);
label1.fore_color(color::dodger_blue);
button1.parent(*this);
button1.text("Start");
button1.location({10, 90});
button1.click += [&](object & sender, const event_args & e) {
timer1.enabled(!timer1.enabled());
button1.text(timer1.enabled() ? "Stop" : "Start");
};
timer1.interval(100_ms);
timer1.tick += [&](object & sender, const event_args & e) {
label1.text(string::format("{:F1}", ++counter / 10.0));
};
text("Timer example");
client_size({230, 130});
}
private:
timer timer1;
label label1;
int counter = 0;
};
}
auto main() -> int {
application::run(timer_example::form1 {});
}
Defines a particular format for text, including font face, size, and style attributes....
Definition font.h:45
Represents the base class for classes that contain event data, and provides a value to use for events...
Definition event_args.h:18
static void run()
Begins running a standard application message loop on the current thread, without a form.
Represents a Windows button control.
Definition button.h:49
virtual const xtd::string & text() const noexcept
Gets the text associated with this control.
Represents a window or dialog box that makes up an application's user interface.
Definition form.h:54
control & parent(const control &value) override
Sets the parent container of the control.
Represents a standard Windows label.
Definition label.h:38
Implements a timer that raises an event at user-defined intervals. This timer is optimized for use in...
Definition timer.h:38
@ e
The E key.
@ button1
The first button on the message box is the default button.
@ text
The xtd::forms::status_bar_panel displays text in the standard font.
The xtd::drawing namespace provides access to GDI+ basic graphics functionality. More advanced functi...
Definition brush.h:18
The xtd::forms namespace contains classes for creating Windows-based applications that take full adva...
Definition xtd_about_box.h:12
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
Examples
clock.cpp, dot_matrix_display.cpp, draw_point.cpp, forms_timer.cpp, fourteen_segment_display.cpp, lcd_label2.cpp, lcd_label_with_dot_matrix.cpp, lcd_label_with_fourteen_segment.cpp, lcd_label_with_nine_segment.cpp, lcd_label_with_seven_segment.cpp, lcd_label_with_sixteen_segment.cpp, nine_segment_display.cpp, progress_bar.cpp, screenshot.cpp, seven_segment_display.cpp, sixteen_segment_display.cpp, status_bar.cpp, stopwatch_form.cpp, timers_timer_synchronizing_object.cpp, tool_bar.cpp, and wiggly.cpp.

Public Events

event< timer, event_handlertick
 Occurs when the specified timer interval has elapsed and the timer is enabled.
 

Public Constructors

 timer ()
 Initializes a new instance of the timer class.
 

Public Properties

virtual bool enabled () const noexcept
 Gets whether the timer is running.
 
virtual timerenabled (bool enabled)
 Sets whether the timer is running.
 
virtual time_span interval () const noexcept
 Gets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
 
timerinterval (const time_span &interval)
 Sets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
 
virtual int32 interval_milliseconds () const noexcept
 Gets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
 
virtual timerinterval_milliseconds (int32 interval)
 Sets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
 

Public Methods

void start ()
 Stops the timer.
 
void stop ()
 Starts the timer.
 

Public Static Methods

static timer create ()
 A factory to create an xtd::forms::timer.
 
static timer create (const time_span &interval)
 A factory to create an xtd::forms::timer with specified interval.
 
static timer create (const time_span &interval, bool enable)
 A factory to create an xtd::forms::timer with specified interval, and enable values.
 
static timer create (int interval_milliseconds)
 A factory to create an xtd::forms::timer with specified interval.
 
static timer create (int interval_milliseconds, bool enable)
 A factory to create an xtd::forms::timer with specified interval, and enable values.
 

Prootected methods

virtual void on_tick (const event_args &e)
 Raises the xtd::forms::timer::tick 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

◆ timer()

xtd::forms::timer::timer ( )

Initializes a new instance of the timer class.

Remarks
When a new timer is created, it is disabled; that is, enabled is set to false. To enable the timer, call the start method or set enabled to true.
If the timer is disabled and the timer is out of scope, the timer will be destroyed.

Member Function Documentation

◆ enabled() [1/2]

virtual bool xtd::forms::timer::enabled ( ) const
virtualnoexcept

Gets whether the timer is running.

Returns
true if the timer is currently enabled; otherwise, false. The default is false.
Remarks
Calling the start method is the same as setting enabled to true. Likewise, calling the stop method is the same as setting enabled to false.
Examples
lcd_label2.cpp, lcd_label_with_dot_matrix.cpp, lcd_label_with_fourteen_segment.cpp, lcd_label_with_nine_segment.cpp, lcd_label_with_seven_segment.cpp, lcd_label_with_sixteen_segment.cpp, and wiggly.cpp.

◆ enabled() [2/2]

virtual timer & xtd::forms::timer::enabled ( bool  enabled)
virtual

Sets whether the timer is running.

Parameters
enabledtrue if the timer is currently enabled; otherwise, false. The default is false.
Remarks
Calling the start method is the same as setting enabled to true. Likewise, calling the stop method is the same as setting enabled to false.

◆ interval() [1/2]

virtual time_span xtd::forms::timer::interval ( ) const
virtualnoexcept

Gets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.

Returns
An xtd::time_span specifying the interval before the tick event is raised relative to the last occurrence of the tick event. The value must be greater than zero.
Examples
clock.cpp, lcd_label2.cpp, lcd_label_with_dot_matrix.cpp, lcd_label_with_fourteen_segment.cpp, lcd_label_with_nine_segment.cpp, lcd_label_with_seven_segment.cpp, lcd_label_with_sixteen_segment.cpp, and wiggly.cpp.

◆ interval() [2/2]

timer & xtd::forms::timer::interval ( const time_span interval)

Sets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.

Parameters
intervalAn xtd::time_span specifying the interval before the tick event is raised relative to the last occurrence of the tick event. The value must be greater than zero.

◆ interval_milliseconds() [1/2]

virtual int32 xtd::forms::timer::interval_milliseconds ( ) const
virtualnoexcept

Gets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.

Returns
An int32 specifying the number of milliseconds before the tick event is raised relative to the last occurrence of the tick event. The value cannot be less than one.
Remarks
To get the number of seconds in the interval, divide this number by 1,000.

◆ interval_milliseconds() [2/2]

virtual timer & xtd::forms::timer::interval_milliseconds ( int32  interval)
virtual

Sets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.

Parameters
intervalAn int32 specifying the number of milliseconds before the tick event is raised relative to the last occurrence of the tick event. The value cannot be less than one.
Remarks
To get the number of seconds in the interval, divide this number by 1,000.

◆ start()

void xtd::forms::timer::start ( )

Stops the timer.

Remarks
You can also stop the timer by setting the enabled property to false.
Examples
timers_timer_synchronizing_object.cpp.

◆ stop()

void xtd::forms::timer::stop ( )

Starts the timer.

Remarks
You can also start the timer by setting the enabled property to true.
Examples
timers_timer_synchronizing_object.cpp.

◆ create() [1/5]

static timer xtd::forms::timer::create ( )
static

A factory to create an xtd::forms::timer.

Returns
New xtd::forms::timer created.

◆ create() [2/5]

static timer xtd::forms::timer::create ( const time_span interval)
static

A factory to create an xtd::forms::timer with specified interval.

Parameters
intervalAn xtd::time_span specifying the interval before the tick event is raised relative to the last occurrence of the tick event. The value must be greater than zero.
Returns
New xtd::forms::timer created.

◆ create() [3/5]

static timer xtd::forms::timer::create ( const time_span interval,
bool  enable 
)
static

A factory to create an xtd::forms::timer with specified interval, and enable values.

Parameters
intervalAn xtd::time_span specifying the interval before the tick event is raised relative to the last occurrence of the tick event. The value must be greater than zero.
enabledtrue if the timer is currently enabled; otherwise, false. The default is false.
Returns
New xtd::forms::timer created.

◆ create() [4/5]

static timer xtd::forms::timer::create ( int  interval_milliseconds)
static

A factory to create an xtd::forms::timer with specified interval.

Parameters
interval_millisecondsAn int32 specifying the number of milliseconds before the tick event is raised relative to the last occurrence of the tick event. The value cannot be less than one.
Returns
New xtd::forms::timer created.

◆ create() [5/5]

static timer xtd::forms::timer::create ( int  interval_milliseconds,
bool  enable 
)
static

A factory to create an xtd::forms::timer with specified interval, and enable values.

Parameters
interval_millisecondsAn int32 specifying the number of milliseconds before the tick event is raised relative to the last occurrence of the tick event. The value cannot be less than one.
enabledtrue if the timer is currently enabled; otherwise, false. The default is false.
Returns
New xtd::forms::timer created.

◆ on_tick()

virtual void xtd::forms::timer::on_tick ( const event_args e)
protectedvirtual

Raises the xtd::forms::timer::tick event.

Parameters
eAn event_args that contains the event data. This is always xtd::event_args::empty.

Member Data Documentation

◆ tick

event<timer, event_handler> xtd::forms::timer::tick

Occurs when the specified timer interval has elapsed and the timer is enabled.

Remarks
Calling the Assert method on the xtd::diagnostics::debug class from within the tick event may not behave as expected, as displaying the assertion dialog box may cause Windows to raise the tick event repeatedly. We recommend that you refrain from testing assertions within this event, and use the write, write_if, write_line, or write_line_if methods instead.
For more information about handling events, see Handling and Raising Events.
Examples
lcd_label2.cpp, lcd_label_with_dot_matrix.cpp, lcd_label_with_fourteen_segment.cpp, lcd_label_with_nine_segment.cpp, lcd_label_with_seven_segment.cpp, lcd_label_with_sixteen_segment.cpp, and wiggly.cpp.

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