357 lines
12 KiB
Objective-C
357 lines
12 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: wx/fswatcher.h
|
|
// Purpose: wxFileSystemWatcher
|
|
// Author: Bartosz Bekier
|
|
// Created: 2009-05-23
|
|
// Copyright: (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxFileSystemWatcher
|
|
|
|
The wxFileSystemWatcher class allows receiving notifications of file
|
|
system changes.
|
|
|
|
@note Implementation limitations: this class is currently implemented for
|
|
MSW, macOS and GTK ports but doesn't detect all changes correctly
|
|
everywhere: under MSW accessing the file is not detected (only
|
|
modifying it is) and under macOS neither accessing nor modifying is
|
|
detected (only creating and deleting files is). Moreover, macOS
|
|
version doesn't currently collapse pairs of create/delete events in a
|
|
rename event, unlike the other ones.
|
|
|
|
@note The application's event loop needs to be running before a
|
|
wxFileSystemWatcher can be properly created, and that is why one
|
|
should not be created too early during application startup.
|
|
If you intend to create a wxFileSystemWatcher at startup, you can
|
|
override wxAppConsole::OnEventLoopEnter() to ensure it is not done
|
|
too early.
|
|
|
|
For the full list of change types that are reported see wxFSWFlags.
|
|
|
|
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}
|
|
|
|
@since 2.9.1
|
|
*/
|
|
class wxFileSystemWatcher: public wxEvtHandler
|
|
{
|
|
public:
|
|
/**
|
|
Default constructor.
|
|
*/
|
|
wxFileSystemWatcher();
|
|
|
|
/**
|
|
Destructor. Stops all paths from being watched and frees any system
|
|
resources used by this file system watcher object.
|
|
*/
|
|
virtual ~wxFileSystemWatcher();
|
|
|
|
/**
|
|
Adds @a path to currently watched files.
|
|
|
|
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 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 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 and macOS, 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);
|
|
|
|
/**
|
|
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);
|
|
|
|
/**
|
|
Clears the list of currently watched paths.
|
|
*/
|
|
virtual bool RemoveAll();
|
|
|
|
/**
|
|
Returns the number of currently watched paths.
|
|
|
|
@see GetWatchedPaths()
|
|
*/
|
|
int GetWatchedPathsCount() const;
|
|
|
|
/**
|
|
Retrieves all watched paths and places them in @a paths. Returns
|
|
the number of watched paths, which is also the number of entries added
|
|
to @a paths.
|
|
*/
|
|
int GetWatchedPaths(wxArrayString* paths) const;
|
|
|
|
/**
|
|
Associates the file system watcher with the given @a handler object.
|
|
|
|
All the events generated by this object will be passed to the specified
|
|
owner.
|
|
*/
|
|
void SetOwner(wxEvtHandler* handler);
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxFileSystemWatcherEvent
|
|
|
|
A class of events sent when a file system event occurs. Types of events
|
|
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{wxbase}
|
|
@category{events}
|
|
|
|
@see wxFileSystemWatcher
|
|
@see @ref overview_events
|
|
|
|
@since 2.9.1
|
|
*/
|
|
class wxFileSystemWatcherEvent : public wxEvent
|
|
{
|
|
public:
|
|
wxFileSystemWatcherEvent(int changeType = 0,
|
|
int watchid = wxID_ANY);
|
|
wxFileSystemWatcherEvent(int changeType,
|
|
wxFSWWarningType warningType,
|
|
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.
|
|
*/
|
|
const wxFileName& GetPath() const;
|
|
|
|
/**
|
|
Returns the new path of the renamed file/directory if this is a rename
|
|
event.
|
|
|
|
Otherwise it returns the same path as GetPath().
|
|
*/
|
|
const wxFileName& GetNewPath() const;
|
|
|
|
/**
|
|
Returns the type of file system change that occurred. See wxFSWFlags for
|
|
the list of possible file system change types.
|
|
*/
|
|
int GetChangeType() const;
|
|
|
|
/**
|
|
Returns @c true if this error is an error event
|
|
|
|
Error event is an event generated when a warning or error condition
|
|
arises.
|
|
*/
|
|
bool IsError() const;
|
|
|
|
/**
|
|
Return a description of the warning or error if this is an error event.
|
|
|
|
This string may be empty if the exact reason for the error or the
|
|
warning is not known.
|
|
*/
|
|
wxString GetErrorDescription() const;
|
|
|
|
/**
|
|
Return the type of the warning if this event is a warning one.
|
|
|
|
If this is not a warning event, i.e. if GetChangeType() doesn't include
|
|
::wxFSW_EVENT_WARNING, returns ::wxFSW_WARNING_NONE.
|
|
|
|
@since 3.0
|
|
*/
|
|
wxFSWWarningType GetWarningType() const;
|
|
|
|
/**
|
|
Returns a wxString describing an event, useful for logging, debugging
|
|
or testing.
|
|
*/
|
|
wxString ToString() const;
|
|
};
|
|
|
|
wxEventType wxEVT_FSWATCHER;
|
|
|
|
/**
|
|
These are the possible types of file system change events.
|
|
|
|
Not all of these events are reported on all platforms currently.
|
|
|
|
@since 2.9.1
|
|
*/
|
|
enum wxFSWFlags
|
|
{
|
|
/// 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 macOS this event is only detected when watching entire trees. When
|
|
watching directories, separate ::wxFSW_EVENT_CREATE and
|
|
::wxFSW_EVENT_DELETE events are detected instead.
|
|
*/
|
|
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 macOS this event is only detected when watching entire trees.
|
|
*/
|
|
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 and macOS.
|
|
Under macOS this event is only detected when watching entire trees.
|
|
|
|
@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 and macOS.
|
|
Under macOS this event is only detected when watching entire trees.
|
|
|
|
@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.
|
|
|
|
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_ATTRIB |
|
|
wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
|
|
};
|
|
|
|
/**
|
|
Possible warning types for the warning events generated by
|
|
wxFileSystemWatcher.
|
|
|
|
@since 3.0
|
|
*/
|
|
enum wxFSWWarningType
|
|
{
|
|
/**
|
|
This is not a warning at all.
|
|
*/
|
|
wxFSW_WARNING_NONE,
|
|
|
|
/**
|
|
A generic warning.
|
|
|
|
Further information may be provided in the user-readable message
|
|
available from wxFileSystemWatcherEvent::GetErrorDescription()
|
|
*/
|
|
wxFSW_WARNING_GENERAL,
|
|
|
|
/**
|
|
An overflow event.
|
|
|
|
This warning indicates that some file system changes were not signaled
|
|
by any events, usually because there were too many of them and the
|
|
internally used queue has overflown. If such event is received it is
|
|
recommended to completely rescan the files or directories being
|
|
monitored.
|
|
*/
|
|
wxFSW_WARNING_OVERFLOW
|
|
};
|