Fix wxFileSystemWatcher usage instructions.

Don't mention the virtual OnXXX() functions which were removed from the final
API.

Also mention AddTree() limitations on non-MSW platforms.

See #12847.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@67694 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/fswatcher.h

@@ -24,54 +24,15 @@
 
     For the full list of change types that are reported see wxFSWFlags.
 
-    There are three different ways to use this class:
+    This class notifies the application about the file system changes by
-
+    sending events of wxFileSystemWatcherEvent class. By default these events
-     - You may derive a new class from wxFileSystemWatcher and override the
+    are sent to the wxFileSystemWatcher object itself so you can derive from it
-       wxFileSystemWatcher::OnChange member to perform the required action
+    and use the event table @c EVT_FSWATCHER macro to handle these events in a
-       when file system change occurrs. Additionally you may also want to
+    derived class method. Alternatively, you can use
-       override wxFileSystemWatcher::OnWarning and
+    wxFileSystemWatcher::SetOwner() to send the events to another object. Or
-       wxFileSystemWatcher::OnError to be notified when an error condition
+    you could use wxEvtHandler::Connect() with @c wxEVT_FSWATCHER to handle
-       arises.
+    these events in any other object. See the fswatcher sample for an example
-     - You may use a derived class and the @c EVT_FSWATCHER macro or
+    of the latter approach.
-       wxEvtHandler::Connect to redirect events to an event handler defined in
-       the derived class. If the default constructor is used, the file system
-       watcher object will be its own owner object, since it is derived from
-       wxEvtHandler.
-     - You may redirect the notifications of file system changes as well as of
-       error conditions to any wxEvtHandler derived object by using
-       wxFileSystemWatcher::SetOwner.
-       Then use the @c EVT_FSWATCHER macro or wxEvtHandler::Connect to send the
-       events to the event handler which will receive wxFileSystemWatcherEvent.
-
-    For example:
-
-    @code
-    class MyWatcher : public wxFileSystemWatcher
-    {
-    protected:
-        void OnChange(int changeType, const wxFileName& path, const wxFileName& newPath)
-        {
-            // do whatever you like with the event
-        }
-    };
-
-    class MyApp : public wxApp
-    {
-    public:
-        ...
-        void OnEventLoopEnter(wxEventLoopBase* WXUNUSED(loop))
-        {
-            // you have to construct the watcher here, because it needs an active loop
-            m_watcher = new MyWatcher();
-
-            // please notify me when a new log file is created
-            m_watcher->Add(wxFileName::DirName("/var/log", wxFSW_EVENT_CREATE);
-        }
-
-    private:
-        MyWatcher* m_watcher;
-    };
-    @endcode
 
     @library{wxbase}
     @category{file}
@@ -82,9 +43,7 @@ class wxFileSystemWatcher: public wxEvtHandler
 {
 public:
     /**
-        Default constructor. If you create file system watcher using it you have
+        Default constructor.
-        to either call SetOwner() and connect an event handler or override
-        OnChange(), OnWarning() and OnError().
      */
     wxFileSystemWatcher();
 
@@ -95,21 +54,31 @@ public:
     virtual ~wxFileSystemWatcher();
 
     /**
-        Adds @a path to currently watched files. Optionally a filter can be
+        Adds @a path to currently watched files.
-        specified to receive only events of particular type.
 
-        Any events concerning this particular path will be sent either to
+        The @a path argument can currently only be a directory and any changes
-        connected handler or passed to OnChange(), OnWarning() or OnError().
+        to this directory itself or its immediate children will generate the
+        events. Use AddTree() to monitor the directory recursively.
 
-        @note When adding a directory, immediate children will be watched
+        @param path
-        as well.
+            The name of the path to watch.
+        @param events
+            An optional filter to receive only events of particular types.
      */
     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
 
     /**
         This is the same as Add(), but recursively adds every file/directory in
-        the tree rooted at @a path. Additionally a file mask can be specified to
+        the tree rooted at @a path.
-        include only files matching that particular mask.
+
+        Additionally a file mask can be specified to include only files
+        matching that particular mask.
+
+        This method is implemented efficiently under MSW but shouldn't be used
+        for the directories with a lot of children (such as e.g. the root
+        directory) under the other platforms as it calls Add() there for each
+        subdirectory potentially creating a lot of watches and taking a long
+        time to execute.
      */
     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
                          const wxString& filter = wxEmptyString) = 0;
@@ -147,9 +116,8 @@ public:
     /**
         Associates the file system watcher with the given @a handler object.
 
-        Basically this means that all events will be passed to this handler
+        All the events generated by this object will be passed to the specified
-        object unless you have change the default behaviour by overriding
+        owner.
-        OnChange(), OnWarning() or OnError().
      */
     void SetOwner(wxEvtHandler* handler);
 };