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}
{
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();
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);
virtual bool RemoveAll();
/**
- Returns the number of watched paths
+ Returns the number of currently watched paths.
+
+ @see GetWatchedPaths()
*/
- int GetWatchedPathCount() const;
+ int GetWatchedPathsCount() const;
/**
Retrieves all watched paths and places them in @a paths. Returns
/**
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);
-
-protected:
- /**
- You may either connect your event handler to intercept file system
- watcher events or override this member and handle them here.
-
- Perform whatever action which is to be taken on file system change.
- */
- virtual void OnChange(int changeType, const wxFileName& path,
- const wxFileName& newPath);
-
- /**
- You may either connect your event handler to intercept file system
- watcher events or override this member and handle them here.
-
- Perform whatever action which is to be taken when a warning condition
- arises.
- */
- virtual void OnWarning(const wxString& errorMessage);
-
- /**
- You may either connect your event handler to intercept file system
- watcher events or override this member and handle them here.
-
- Perform whatever action which is to be taken when an error condition
- arises.
- */
- virtual void OnError(const wxString& errorMessage);
};
@class wxFileSystemWatcherEvent
A class of events sent when a file system event occurs. Types of events
- reported may vary depending on a platfrom, however all platforms report
+ reported may vary depending on a platform, however all platforms report
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, 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