avoid infinite recursion for richtooltops, (hopefully) fixes #15070

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

diff --git a/interface/wx/fswatcher.h b/interface/wx/fswatcher.h
index 37167c7d75c789c65214764b1bf0ed4ebc9e81aa..5857d69260779f2a68faa15b3b94a13db30a1a98 100644 (file)
--- a/interface/wx/fswatcher.h
+++ b/interface/wx/fswatcher.h
@@ -24,54 +24,15 @@
 
     For the full list of change types that are reported see wxFSWFlags.
 
 
     For the full list of change types that are reported see wxFSWFlags.
 

-    There are three different ways to use this class:
-
-     - You may derive a new class from wxFileSystemWatcher and override the
-       wxFileSystemWatcher::OnChange member to perform the required action
-       when file system change occurrs. Additionally you may also want to
-       override wxFileSystemWatcher::OnWarning and
-       wxFileSystemWatcher::OnError to be notified when an error condition
-       arises.
-     - You may use a derived class and the @c EVT_FSWATCHER macro or
-       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
+    This class notifies the application about the file system changes by
+    sending events of wxFileSystemWatcherEvent class. By default these events
+    are sent to the wxFileSystemWatcher object itself so you can derive from it
+    and use the event table @c EVT_FSWATCHER macro to handle these events in a
+    derived class method. Alternatively, you can use
+    wxFileSystemWatcher::SetOwner() to send the events to another object. Or
+    you could use wxEvtHandler::Connect() with @c wxEVT_FSWATCHER to handle
+    these events in any other object. See the fswatcher sample for an example
+    of the latter approach.

 
     @library{wxbase}
     @category{file}
 
     @library{wxbase}
     @category{file}


@@ -82,9 +43,7 @@ class wxFileSystemWatcher: public wxEvtHandler
 {
 public:
     /**
 {
 public:
     /**

-        Default constructor. If you create file system watcher using it you have
-        to either call SetOwner() and connect an event handler or override
-        OnChange(), OnWarning() and OnError().
+        Default constructor.

      */
     wxFileSystemWatcher();
 
      */
     wxFileSystemWatcher();
 


@@ -95,33 +54,57 @@ public:
     virtual ~wxFileSystemWatcher();
 
     /**
     virtual ~wxFileSystemWatcher();
 
     /**

-        Adds @a path to currently watched files. Optionally a filter can be
-        specified to receive only events of particular type.
+        Adds @a path to currently watched files.

 
 

-        Any events concerning this particular path will be sent either to
-        connected handler or passed to OnChange(), OnWarning() or OnError().
+        The @a path argument can currently only be a directory and any changes
+        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
-        as well.
+        Note that on platforms that use symbolic links, you should consider the
+        possibility that @a path is a symlink. To watch the symlink itself and
+        not its target you may call wxFileName::DontFollowLink() on @a path.
+
+        @param path
+            The name of the path to watch.
+        @param events
+            An optional filter to receive only events of particular types.
+            This is currently implemented only for GTK.

      */
     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
 
     /**
      */
     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
-        include only files matching that particular mask.
+        This is the same as Add(), but also recursively adds every
+        file/directory in the tree rooted at @a path.
+
+        Additionally a file mask can be specified to include only files
+        matching that particular mask.
+
+        This method is implemented efficiently on MSW, but should be used with
+        care on other platforms for directories with lots of children (e.g. the
+        root directory) as it calls Add() for each subdirectory, potentially
+        creating a lot of watches and taking a long time to execute.
+
+        Note that on platforms that use symbolic links, you will probably want
+        to have called wxFileName::DontFollowLink on @a path. This is especially
+        important if the symlink targets may themselves be watched.

      */
     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
      */
     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,

-                        const wxString& filter = wxEmptyString) = 0;
+                         const wxString& filter = wxEmptyString);

 
     /**
         Removes @a path from the list of watched paths.
 
     /**
         Removes @a path from the list of watched paths.

+
+        See the comment in Add() about symbolic links. @a path should treat
+        symbolic links in the same way as in the original Add() call.

      */
     virtual bool Remove(const wxFileName& path);
 
     /**
      */
     virtual bool Remove(const wxFileName& path);
 
     /**

-        Same as Remove(), but also removes every file/directory belonging to
-        the tree rooted at @a path.
+        This is the same as Remove(), but also removes every file/directory
+        belonging to the tree rooted at @a path.
+
+        See the comment in AddTree() about symbolic links. @a path should treat
+        symbolic links in the same way as in the original AddTree() call.

      */
     virtual bool RemoveTree(const wxFileName& path);
 
      */
     virtual bool RemoveTree(const wxFileName& path);
 


@@ -147,9 +130,8 @@ public:
     /**
         Associates the file system watcher with the given @a handler object.
 
     /**
         Associates the file system watcher with the given @a handler object.
 

-        Basically this means that all events will be passed to this handler
-        object unless you have change the default behaviour by overriding
-        OnChange(), OnWarning() or OnError().
+        All the events generated by this object will be passed to the specified
+        owner.

      */
     void SetOwner(wxEvtHandler* handler);
 };
      */
     void SetOwner(wxEvtHandler* handler);
 };


@@ -164,7 +146,7 @@ public:
     at least creation of new file/directory and access, modification, move
     (rename) or deletion of an existing one.
 
     at least creation of new file/directory and access, modification, move
     (rename) or deletion of an existing one.
 

-    @library{wxcore}
+    @library{wxbase}

     @category{events}
 
     @see wxFileSystemWatcher
     @category{events}
 
     @see wxFileSystemWatcher


@@ -175,6 +157,13 @@ public:
 class wxFileSystemWatcherEvent : public wxEvent
 {
 public:
 class wxFileSystemWatcherEvent : public wxEvent
 {
 public:

+    wxFileSystemWatcherEvent(int changeType, int watchid = wxID_ANY);
+    wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg,
+                             int watchid = wxID_ANY);
+    wxFileSystemWatcherEvent(int changeType,
+                             const wxFileName& path, const wxFileName& newPath,
+                             int watchid = wxID_ANY);
+

     /**
         Returns the path at which the event occurred.
      */
     /**
         Returns the path at which the event occurred.
      */


@@ -214,27 +203,95 @@ public:
     wxString ToString() const;
 };
 
     wxString ToString() const;
 };
 

+wxEventType wxEVT_FSWATCHER;

 
 /**
     These are the possible types of file system change events.
 
 /**
     These are the possible types of file system change events.

-    All of these events are reported on all supported platforms.
+
+    Not all of these events are reported on all platforms currently.

 
     @since 2.9.1
  */
 enum wxFSWFlags
 {
 
     @since 2.9.1
  */
 enum wxFSWFlags
 {

-    wxFSW_EVENT_CREATE = 0x01,  ///< File or directory was created
-    wxFSW_EVENT_DELETE = 0x02,  ///< File or directory was deleted
-    wxFSW_EVENT_RENAME = 0x04,  ///< File or directory was renamed
-    wxFSW_EVENT_MODIFY = 0x08,  ///< File or directory was modified
-    wxFSW_EVENT_ACCESS = 0x10,  ///< File or directory was accessed
+    /// File or directory was created.
+    wxFSW_EVENT_CREATE = 0x01,
+
+    /// File or directory was deleted.
+    wxFSW_EVENT_DELETE = 0x02,
+
+    /**
+        File or directory was renamed.
+
+        Notice that under MSW this event is sometimes -- although not always --
+        followed by a ::wxFSW_EVENT_MODIFY for the new file.
+
+        Under OS X this event is currently not detected and instead separate
+        ::wxFSW_EVENT_CREATE and ::wxFSW_EVENT_DELETE events are.
+     */
+    wxFSW_EVENT_RENAME = 0x04,
+
+    /**
+        File or directory was modified.
+
+        Depending on the program doing the file modification, multiple such
+        events can be reported for a single logical file update.
+
+        Under OS X this event is currently not detected.
+     */
+    wxFSW_EVENT_MODIFY = 0x08,
+
+    /**
+        File or directory was accessed.
+
+        This event is currently only detected under Linux.
+     */
+    wxFSW_EVENT_ACCESS = 0x10,
+
+    /**
+        The item's metadata was changed, e.g.\ its permissions or timestamps.
+
+        This event is currently only detected under Linux.
+
+        @since 2.9.5
+     */
+    wxFSW_EVENT_ATTRIB = 0x20,
+
+    /**
+        The file system containing a watched item was unmounted.
+
+        wxFSW_EVENT_UNMOUNT cannot be set; unmount events are produced automatically. This flag
+        is therefore not included in wxFSW_EVENT_ALL.
+
+        This event is currently only detected under Linux.
+
+        @since 2.9.5
+    */
+    wxFSW_EVENT_UNMOUNT = 0x2000,
+
+    /**
+        A warning condition arose.
+
+        This is something that probably needs to be shown to the user in an
+        interactive program as it can indicate a relatively serious problem,
+        e.g. some events could have been missed because of an overflow. But
+        more events will still be coming in the future, unlike for the error
+        condition below.
+     */
+    wxFSW_EVENT_WARNING = 0x40,
+
+    /**
+        An error condition arose.

 
 

-    wxFSW_EVENT_WARNING = 0x20, ///< A warning condition arose.
-    wxFSW_EVENT_ERROR = 0x40,   ///< An error condition arose.
+        Errors are fatal, i.e. no more events will be reported after an error
+        and the program can stop watching the directories currently being
+        monitored.
+    */
+    wxFSW_EVENT_ERROR = 0x80,

 
     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 
     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |

-                         wxFSW_EVENT_ACCESS |
+                         wxFSW_EVENT_ACCESS | wxFSW_EVENT_ATTRIB |

                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 };
 
                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 };