// Purpose: wxFileSystemWatcher
// Author: Bartosz Bekier
// Created: 2009-05-23
-// RCS-ID: $Id$
// Copyright: (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
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);
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
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.
*/
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
};
projects / wxWidgets.git / blobdiff