xtd::forms::timer Class Reference

Inheritance diagram for xtd::forms::timer:

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/xtd>
 
namespace timer_example {
  class form1 : public form {
  public:
    form1() {
      label1.parent(self_);
      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(self_);
      button1.text("Start");
      button1.location({10, 90});
      button1.click += delegate_(object & sender, const event_args & e) {
        timer1.enabled(!timer1.enabled());
        button1.text(timer1.enabled() ? "Stop" : "Start");
      };
      
      timer1.interval(100_ms);
      timer1.tick += delegate_(object & sender, const event_args & e) {
        label1.text(string::format("{:F1}", ++counter / 10.0));
      };
      
      text("Timer example");
      client_size({230, 130});
    }
    
  private:
    forms::timer timer1;
    label label1;
    button button1;
    int counter = 0;
  };
}
 
auto main() -> int {
  application::run(timer_example::form1 {});
}

Public Events
xtd::event< timer, xtd::event_handler >	tick
	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 auto	enabled () const noexcept -> bool
	Gets whether the timer is running.
virtual auto	enabled (bool value) -> timer &
	Sets whether the timer is running.
virtual auto	interval () const noexcept -> xtd::time_span
	Gets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
virtual auto	interval (const xtd::time_span &value) -> timer &
	Sets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
virtual auto	interval_milliseconds () const noexcept -> xtd::int32
	Gets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.
virtual auto	interval_milliseconds (xtd::int32 value) -> timer &
	Sets the time, in milliseconds, before the tick event is raised relative to the last occurrence of the tick event.

Public Methods
auto	start () -> void
	Stops the timer.
auto	stop () -> void
	Starts the timer.

Public Static Methods
static auto	create () -> timer
	A factory to create an xtd::forms::timer.
static auto	create (const xtd::time_span &interval) -> timer
	A factory to create an xtd::forms::timer with specified interval.
static auto	create (const xtd::time_span &interval, bool enable) -> timer
	A factory to create an xtd::forms::timer with specified interval, and enable values.
static auto	create (xtd::int32 interval_milliseconds) -> timer
	A factory to create an xtd::forms::timer with specified interval.
static auto	create (xtd::int32 interval_milliseconds, bool enable) -> timer
	A factory to create an xtd::forms::timer with specified interval, and enable values.

Prootected methods
virtual auto	on_tick (const xtd::event_args &e) -> void
	Raises the xtd::forms::timer::tick event.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual auto	equals (const object &obj) const noexcept -> bool
	Determines whether the specified object is equal to the current object.
virtual auto	get_hash_code () const noexcept -> xtd::usize
	Serves as a hash function for a particular type.
virtual auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	to_string () const -> xtd::string
	Returns a xtd::string that represents the current object.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are the same instance.
	component ()
	Initialises a new instance of the component class.
virtual auto	can_raise_events () const noexcept -> bool
	Gets a value indicating whether the component can raise an event.
auto	design_mode () const noexcept -> bool
	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 auto xtd::forms::timer::enabled ( ) const -> bool

nodiscardvirtualnoexcept

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.

enabled() [2/2]

virtual auto xtd::forms::timer::enabled ( bool value ) -> timer &

virtual

Sets whether the timer is running.

Parameters

value

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.

interval() [1/2]

virtual auto xtd::forms::timer::interval ( ) const -> xtd::time_span

nodiscardvirtualnoexcept

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.

interval() [2/2]

virtual auto xtd::forms::timer::interval ( const xtd::time_span & value ) -> timer &

virtual

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

Parameters

value

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.

interval_milliseconds() [1/2]

virtual auto xtd::forms::timer::interval_milliseconds ( ) const -> xtd::int32

nodiscardvirtualnoexcept

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 auto xtd::forms::timer::interval_milliseconds ( xtd::int32 value ) -> timer &

virtual

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

Parameters

value

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.

start()

auto xtd::forms::timer::start

(

)

-> void

Stops the timer.

Remarks

You can also stop the timer by setting the enabled property to false.

stop()

auto xtd::forms::timer::stop

(

)

-> void

Starts the timer.

Remarks

You can also start the timer by setting the enabled property to true.

create() [1/5]

auto xtd::forms::timer::create ( ) -> timer

staticnodiscard

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

Returns

New xtd::forms::timer created.

create() [2/5]

auto xtd::forms::timer::create ( const xtd::time_span & interval ) -> timer

staticnodiscard

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

Parameters

interval

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.

Returns

New xtd::forms::timer created.

create() [3/5]

auto xtd::forms::timer::create ( const xtd::time_span & interval, bool enable ) -> timer

staticnodiscard

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

Parameters

interval	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.
enabled	true if the timer is currently enabled; otherwise, false. The default is false.

Returns

New xtd::forms::timer created.

create() [4/5]

auto xtd::forms::timer::create ( xtd::int32 interval_milliseconds ) -> timer

staticnodiscard

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

Parameters

interval_milliseconds

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.

Returns

New xtd::forms::timer created.

create() [5/5]

auto xtd::forms::timer::create ( xtd::int32 interval_milliseconds, bool enable ) -> timer

staticnodiscard

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

Parameters

interval_milliseconds	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.
enabled	true if the timer is currently enabled; otherwise, false. The default is false.

Returns

New xtd::forms::timer created.

on_tick()

virtual auto xtd::forms::timer::on_tick ( const xtd::event_args & e ) -> void

protectedvirtual

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

Parameters

e	An event_args that contains the event data. This is always xtd::event_args::empty.

Member Data Documentation

tick

xtd::event<timer, xtd::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.

---

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

• xtd.forms/include/xtd/forms/timer.hpp