X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d13b34d3f2be575d59747a5926000be7b28a45dc..3b4b952d42608ff90b03c85f961ba10b93bde916:/interface/wx/fswatcher.h diff --git a/interface/wx/fswatcher.h b/interface/wx/fswatcher.h index 37167c7d75..5857d69260 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,33 +54,57 @@ 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. + 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); /** - 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, - const wxString& filter = wxEmptyString) = 0; + const wxString& filter = wxEmptyString); /** 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); /** - 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); @@ -147,9 +130,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); }; @@ -164,7 +146,7 @@ public: 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 @@ -175,6 +157,13 @@ 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. */ @@ -214,27 +203,95 @@ public: wxString ToString() const; }; +wxEventType wxEVT_FSWATCHER; /** 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 { - 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_ACCESS | + wxFSW_EVENT_ACCESS | wxFSW_EVENT_ATTRIB | wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR };