Return NULL from wxWindow::GetCapture() when the capture is being lost.

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

diff --git a/interface/wx/timer.h b/interface/wx/timer.h
index 6d11c2484c8d183d246cbdca81ee19a450bf3af7..6753e2dd12d4126f7d445de7482c7a493af5da03 100644 (file)
--- a/interface/wx/timer.h
+++ b/interface/wx/timer.h
@@ -2,10 +2,18 @@
 // Name:        timer.h
 // 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
 
@@ -74,10 +82,10 @@ public:
         If non-@NULL this is the event handler which will receive the
         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
+        Returns @true if the timer is one shot, i.e.\ if it will stop after firing
         the first notification automatically.
     */
     bool IsOneShot() const;
@@ -92,6 +100,10 @@ public:
         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.
     */
     virtual void Notify();
 
@@ -115,10 +127,21 @@ public:
         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.
     */
-    virtual 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.
@@ -127,11 +150,25 @@ public:
 };
 
 
+/**
+   @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:
 
@@ -144,11 +181,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)
@@ -170,6 +208,9 @@ public:
 class wxTimerEvent : public wxEvent
 {
 public:
+    wxTimerEvent();
+    wxTimerEvent(wxTimer& timer);
+
     /**
         Returns the interval of the timer which generated this event.
     */
@@ -178,6 +219,6 @@ public:
     /**
         Returns the timer object which generated this event.
     */
-    wxTimer GetTimer() const;
+    wxTimer& GetTimer() const;
 };