synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / timer.h

diff --git a/interface/wx/timer.h b/interface/wx/timer.h
index 49de74c8ef1aaffd87a33c9a20baded614ee260a..054e890057f9bf26988e56d96c5e2a148aa7bd50 100644 (file)
--- a/interface/wx/timer.h
+++ b/interface/wx/timer.h
@@ -3,34 +3,41 @@
 // Purpose:     interface of wxTimer
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // 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
 /**
     @class wxTimer

-    @wxheader{timer.h}

 
 

-    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:
 
 
     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.
 
 
     @note A timer can only be used from the main thread.
 


@@ -42,19 +49,23 @@
 class wxTimer : public wxEvtHandler
 {
 public:
 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();
     */
     wxTimer();

+
+    /**
+        Creates a timer and associates it with @a owner.
+        Please see SetOwner() for the description of parameters.
+    */

     wxTimer(wxEvtHandler* owner, int id = -1);
     wxTimer(wxEvtHandler* owner, int id = -1);

-    //@}

 
     /**
         Destructor. Stops the timer if it is running.
     */
 
     /**
         Destructor. Stops the timer if it is running.
     */

-    ~wxTimer();
+    virtual ~wxTimer();

 
     /**
         Returns the ID of the events generated by this timer.
 
     /**
         Returns the ID of the events generated by this timer.


@@ -68,14 +79,15 @@ public:
 
     /**
         Returns the current @e owner of the timer.
 
     /**
         Returns the current @e owner of the timer.

+

         If non-@NULL this is the event handler which will receive the
         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;
 
     */
     bool IsOneShot() const;
 


@@ -87,14 +99,20 @@ public:
     /**
         This member should be overridden by the user if the default constructor was
         used and SetOwner() wasn't called.
     /**
         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.
         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);
 
     */
     void SetOwner(wxEvtHandler* owner, int id = -1);
 


@@ -102,37 +120,45 @@ 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).
         (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

 
 

-        wxTIMER_ONE_SHOT
-
-        Start a one shot 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.

 
 

+        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

         If the timer was already running, it will be stopped by this method before
         restarting it.
     */
         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 = false);

 
     /**
         Stops the timer.
     */
 
     /**
         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
 
 /**
     @class wxTimerEvent

-    @wxheader{timer.h}

 
 

-    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:
 
 
     For example:
 


@@ -145,11 +171,12 @@ public:
 
     private:
         wxTimer m_timer;
 
     private:
         wxTimer m_timer;

+        wxDECLARE_EVENT_TABLE();

     };
 
     };
 

-    BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)

         EVT_TIMER(TIMER_ID, MyFrame::OnTimer)
         EVT_TIMER(TIMER_ID, MyFrame::OnTimer)

-    END_EVENT_TABLE()
+    wxEND_EVENT_TABLE()

 
     MyFrame::MyFrame()
            : m_timer(this, TIMER_ID)
 
     MyFrame::MyFrame()
            : m_timer(this, TIMER_ID)


@@ -171,6 +198,9 @@ public:
 class wxTimerEvent : public wxEvent
 {
 public:
 class wxTimerEvent : public wxEvent
 {
 public:

+    wxTimerEvent();
+    wxTimerEvent(wxTimer& timer);
+

     /**
         Returns the interval of the timer which generated this event.
     */
     /**
         Returns the interval of the timer which generated this event.
     */


@@ -179,6 +209,6 @@ public:
     /**
         Returns the timer object which generated this event.
     */
     /**
         Returns the timer object which generated this event.
     */

-    wxTimer GetTimer() const;
+    wxTimer& GetTimer() const;

 };
 
 };