put wxURI under networking group, next to wxURL

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

diff --git a/interface/wx/event.h b/interface/wx/event.h
index 00c3bcadec6b4558c64c002a74d9fc36a3cb29a9..a8d4459f1e60a99d9b247244942cae56762b1921 100644 (file)
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -83,6 +83,10 @@ public:
         Gets the timestamp for the event. The timestamp is the time in milliseconds
         since some fixed moment (not necessarily the standard Unix Epoch, so only
         differences between the timestamps and not their absolute values usually make sense).
+
+        @warning
+        wxWidgets returns a non-NULL timestamp only for mouse and key events
+        (see wxMouseEvent and wxKeyEvent).
     */
     long GetTimestamp() const;
 
@@ -117,7 +121,7 @@ public:
     /**
         Sets the timestamp for the event.
     */
-    void SetTimestamp(long = 0);
+    void SetTimestamp(long timeStamp = 0);
 
     /**
         Test if this event should be propagated or not, i.e. if the propagation level
@@ -321,7 +325,7 @@ public:
         share the same string buffer internally. Use QueueEvent() to avoid
         this.
 
-        A copy of event is made by the function, so the original can be deleted
+        A copy of @a event is made by the function, so the original can be deleted
         as soon as function returns (it is common that the original is created
         on the stack). This requires that the wxEvent::Clone() method be
         implemented by event so that it can be duplicated and stored until it
@@ -417,8 +421,8 @@ public:
         @param eventSink
             Object whose member function should be called.
     */
-    bool Disconnect(wxEventType eventType = wxEVT_NULL,
-                    wxObjectEventFunction function = NULL,
+    bool Disconnect(wxEventType eventType,
+                    wxObjectEventFunction function,
                     wxObject* userData = NULL,
                     wxEvtHandler* eventSink = NULL);
 
@@ -440,8 +444,8 @@ public:
 
         This overload takes an additional range of source IDs.
     */
-    bool Disconnect(int id, int lastId = wxID_ANY,
-                    wxEventType eventType = wxEVT_NULL,
+    bool Disconnect(int id, int lastId,
+                    wxEventType eventType,
                     wxObjectEventFunction function = NULL,
                     wxObject* userData = NULL,
                     wxEvtHandler* eventSink = NULL);
@@ -1899,15 +1903,15 @@ public:
         The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
         has moved off a tool.
     @event{EVT_COMMAND_LEFT_CLICK(id, func)}
-        Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (Windows 95 and NT only).
+        Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
-        Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (Windows 95 and NT only).
+        Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
-        Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (Windows 95 and NT only).
+        Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_SET_FOCUS(id, func)}
-        Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (Windows 95 and NT only).
+        Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_KILL_FOCUS(id, func)}
-        Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (Windows 95 and NT only).
+        Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_ENTER(id, func)}
         Process a wxEVT_COMMAND_ENTER command, which is generated by a control.
     @endEventTable
@@ -1921,7 +1925,7 @@ public:
     /**
         Constructor.
     */
-    wxCommandEvent(wxEventType commandEventType = 0, int id = 0);
+    wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0);
 
     /**
         Returns client data pointer for a listbox or choice selection event
@@ -2333,13 +2337,10 @@ public:
 
 
 
-/**
-    Indicates how a wxHelpEvent was generated.
-*/
 enum wxHelpEventOrigin
 {
-    wxHE_ORIGIN_UNKNOWN = -1,    /**< unrecognized event source. */
-    wxHE_ORIGIN_KEYBOARD,        /**< event generated from F1 key press. */
+    wxHE_ORIGIN_UNKNOWN = -1,
+    wxHE_ORIGIN_KEYBOARD,
 
     /** event generated by wxContextHelp or from the [?] button on
         the title bar (Windows). */
@@ -2382,13 +2383,26 @@ enum wxHelpEventOrigin
 class wxHelpEvent : public wxCommandEvent
 {
 public:
+    /**
+        Indicates how a wxHelpEvent was generated.
+    */
+    enum Origin
+    {
+        Origin_Unknown,    /**< unrecognized event source. */
+        Origin_Keyboard,   /**< event generated from F1 key press. */
+
+        /** event generated by wxContextHelp or from the [?] button on
+            the title bar (Windows). */
+        Origin_HelpButton
+    };
+
     /**
         Constructor.
     */
     wxHelpEvent(wxEventType type = wxEVT_NULL,
                 wxWindowID winid = 0,
                 const wxPoint& pt = wxDefaultPosition,
-                wxHelpEventOrigin origin = wxHE_ORIGIN_UNKNOWN);
+                wxHelpEvent::Origin origin = Origin_Unknown);
 
     /**
         Returns the origin of the help event which is one of the ::wxHelpEventOrigin
@@ -2851,6 +2865,27 @@ public:
     This allows the wxWindow::Close function to return @true or @false depending
     on whether the close instruction was honoured or not.
 
+    Example of a wxCloseEvent handler:
+
+    @code
+        void MyFrame::OnClose(wxCloseEvent& event)
+        {
+            if ( event.CanVeto() && m_bFileNotSaved )
+            {
+                if ( wxMessageBox("The file has not been saved... continue closing?",
+                                  "Please confirm",
+                                  wxICON_QUESTION | wxYES_NO) != wxYES )
+                {
+                    event.Veto();
+                    return;
+                }
+            }
+
+            Destroy();  // you may also do:  event.Skip();
+                        // since the default event handler does call Destroy(), too
+        }
+    @endcode
+
     The EVT_END_SESSION event is slightly different as it is sent by the system
     when the user session is ending (e.g. because of log out or shutdown) and
     so all windows are being forcefully closed. At least under MSW, after the