X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/906c935a80b10d53cecf57f71ab5f3f4f1d529ec..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/fswatcher.h diff --git a/interface/wx/fswatcher.h b/interface/wx/fswatcher.h index dffeabd023..c89ae09c51 100644 --- a/interface/wx/fswatcher.h +++ b/interface/wx/fswatcher.h @@ -3,7 +3,6 @@ // Purpose: wxFileSystemWatcher // Author: Bartosz Bekier // Created: 2009-05-23 -// RCS-ID: $Id$ // Copyright: (c) 2009 Bartosz Bekier // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -60,37 +59,51 @@ public: to this directory itself or its immediate children will generate the events. Use AddTree() to monitor the directory recursively. + 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. + 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 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. + 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); /** 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); @@ -132,7 +145,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 @@ -143,6 +156,13 @@ public: class wxFileSystemWatcherEvent : public wxEvent { public: + wxFileSystemWatcherEvent(int changeType = 0, 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. */ @@ -182,27 +202,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 };