From 2b6259fe1cb44d5834ce7c12c032ba5a1e66d232 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Tue, 3 May 2011 23:31:43 +0000 Subject: [PATCH] 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 | 94 +++++++++++++--------------------------- 1 file changed, 31 insertions(+), 63 deletions(-) diff --git a/interface/wx/fswatcher.h b/interface/wx/fswatcher.h index 37167c7d75..cc2a55bfcb 100644 --- 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. - 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} @@ -82,9 +43,7 @@ class wxFileSystemWatcher: public wxEvtHandler { 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(); @@ -95,24 +54,34 @@ public: 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. + @param path + 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 - include only files matching that particular mask. + 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 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; + const wxString& filter = wxEmptyString) = 0; /** Removes @a path from the list of watched paths. @@ -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 - 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); };