X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/timer.h diff --git a/interface/wx/timer.h b/interface/wx/timer.h index e46170d0fc..123c626fd6 100644 --- a/interface/wx/timer.h +++ b/interface/wx/timer.h @@ -3,33 +3,41 @@ // Purpose: interface of wxTimer // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +// generate notifications periodically until the timer is stopped (default) +#define wxTIMER_CONTINUOUS false + +// only send the notification once and then stop the timer +#define wxTIMER_ONE_SHOT true + +wxEventType wxEVT_TIMER; + + /** @class wxTimer - The wxTimer class allows you to execute code at specified intervals. Its - precision is platform-dependent, but in general will not be better than 1ms nor - worse than 1s. + The wxTimer class allows you to execute code at specified intervals. + Its precision is platform-dependent, but in general will not be better than + @c 1ms nor worse than @c 1s. There are three different ways to use this class: - You may derive a new class from wxTimer and override the - wxTimer::Notify member to perform the required action. - Or you may redirect the notifications to any - wxEvtHandler derived object by using the non-default - constructor or wxTimer::SetOwner. Then use the @c EVT_TIMER - macro to connect it to the event handler which will receive - wxTimerEvent notifications. - Or you may use a derived class and the @c EVT_TIMER - macro to connect it to an event handler defined in the derived class. - If the default constructor is used, the timer object will be its - own owner object, since it is derived from wxEvtHandler. - - In any case, you must start the timer with wxTimer::Start - after constructing it before it actually starts sending notifications. It can - be stopped later with wxTimer::Stop. + - You may derive a new class from wxTimer and override the + wxTimer::Notify member to perform the required action. + - You may redirect the notifications to any wxEvtHandler derived object by + using the non-default constructor or wxTimer::SetOwner. + Then use the @c EVT_TIMER macro to connect it to the event handler which + will receive wxTimerEvent notifications. + - You may use a derived class and the @c EVT_TIMER macro to connect it to + an event handler defined in the derived class. If the default constructor + is used, the timer object will be its own owner object, since it is + derived from wxEvtHandler. + + In any case, you must start the timer with wxTimer::Start() after constructing + it before it actually starts sending notifications. + It can be stopped later with wxTimer::Stop(). @note A timer can only be used from the main thread. @@ -41,19 +49,23 @@ class wxTimer : public wxEvtHandler { public: - //@{ /** - Creates a timer and associates it with @e owner. Please see - SetOwner() for the description of parameters. + Default constructor. + If you use it to construct the object and don't call SetOwner() later, + you must override Notify() method to process the notifications. */ wxTimer(); + + /** + Creates a timer and associates it with @a owner. + Please see SetOwner() for the description of parameters. + */ wxTimer(wxEvtHandler* owner, int id = -1); - //@} /** Destructor. Stops the timer if it is running. */ - ~wxTimer(); + virtual ~wxTimer(); /** Returns the ID of the events generated by this timer. @@ -67,14 +79,15 @@ public: /** Returns the current @e owner of the timer. + If non-@NULL this is the event handler which will receive the - @ref overview_wxtimerevent "timer events" when the timer is running. + timer events (see wxTimerEvent) when the timer is running. */ - wxEvtHandler GetOwner() const; + wxEvtHandler* GetOwner() const; /** - Returns @true if the timer is one shot, i.e. if it will stop after firing the - first notification automatically. + Returns @true if the timer is one shot, i.e.\ if it will stop after firing + the first notification automatically. */ bool IsOneShot() const; @@ -86,14 +99,20 @@ public: /** This member should be overridden by the user if the default constructor was used and SetOwner() wasn't called. + Perform whatever action which is to be taken periodically here. + + Notice that throwing exceptions from this method is currently not + supported, use event-based timer handling approach if an exception can + be thrown while handling timer notifications. */ - void Notify(); + virtual void Notify(); /** - Associates the timer with the given @a owner object. When the timer is - running, the owner will receive @ref overview_wxtimerevent "timer events" with - id equal to @a id specified here. + Associates the timer with the given @a owner object. + + When the timer is running, the owner will receive timer events (see wxTimerEvent) + with @a id equal to @a id specified here. */ void SetOwner(wxEvtHandler* owner, int id = -1); @@ -101,36 +120,56 @@ public: (Re)starts the timer. If @a milliseconds parameter is -1 (value by default), the previous value is used. Returns @false if the timer could not be started, @true otherwise (in MS Windows timers are a limited resource). - If @a oneShot is @false (the default), the Notify() - function will be called repeatedly until the timer is stopped. If @true, - it will be called only once and the timer will stop automatically. To make your - code more readable you may also use the following symbolic constants: - - wxTIMER_CONTINUOUS - Start a normal, continuously running, timer + If @a oneShot is @false (the default), the Notify() function will be called + repeatedly until the timer is stopped. + If @true, it will be called only once and the timer will stop automatically. - wxTIMER_ONE_SHOT - - Start a one shot timer + To make your code more readable you may also use the following symbolic constants: + - wxTIMER_CONTINUOUS: Start a normal, continuously running, timer + - wxTIMER_ONE_SHOT: Start a one shot timer + Alternatively, use StartOnce(). If the timer was already running, it will be stopped by this method before restarting it. */ - bool Start(int milliseconds = -1, bool oneShot = false); + virtual bool Start(int milliseconds = -1, bool oneShot = wxTIMER_CONTINUOUS); + + /** + Starts the timer for a once-only notification. + + This is a simple wrapper for Start() with @c wxTIMER_ONE_SHOT parameter. + + @since 2.9.5 + */ + bool StartOnce(int milliseconds = -1); /** Stops the timer. */ - void Stop(); + virtual void Stop(); }; +/** + @class wxTimerRunner + + Starts the timer in its ctor, stops in the dtor. +*/ +class wxTimerRunner +{ +public: + wxTimerRunner(wxTimer& timer); + wxTimerRunner(wxTimer& timer, int milli, bool oneShot = false); + void Start(int milli, bool oneShot = false); + ~wxTimerRunner(); +}; /** @class wxTimerEvent - wxTimerEvent object is passed to the event handler of timer events. + wxTimerEvent object is passed to the event handler of timer events + (see wxTimer::SetOwner). For example: @@ -143,11 +182,12 @@ public: private: wxTimer m_timer; + wxDECLARE_EVENT_TABLE(); }; - BEGIN_EVENT_TABLE(MyFrame, wxFrame) + wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_TIMER(TIMER_ID, MyFrame::OnTimer) - END_EVENT_TABLE() + wxEND_EVENT_TABLE() MyFrame::MyFrame() : m_timer(this, TIMER_ID) @@ -169,6 +209,9 @@ public: class wxTimerEvent : public wxEvent { public: + wxTimerEvent(); + wxTimerEvent(wxTimer& timer); + /** Returns the interval of the timer which generated this event. */ @@ -177,6 +220,6 @@ public: /** Returns the timer object which generated this event. */ - wxTimer GetTimer() const; + wxTimer& GetTimer() const; };