921e411cc1
Document that such extra events may occur and generally improve the event types documentation. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@70074 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
255 lines
7.7 KiB
Objective-C
255 lines
7.7 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: wx/fswatcher.h
|
|
// Purpose: wxFileSystemWatcher
|
|
// Author: Bartosz Bekier
|
|
// Created: 2009-05-23
|
|
// RCS-ID: $Id$
|
|
// Copyright: (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxFileSystemWatcher
|
|
|
|
The wxFileSystemWatcher class allows to receive notifications of file
|
|
system changes.
|
|
|
|
@note Implementation limitations: this class is currently implemented for
|
|
MSW, OS X 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 OS X neither accessing nor modifying is
|
|
detected (only creating and deleting files is). Moreover, OS X
|
|
version doesn't currently collapse pairs of create/delete events in a
|
|
rename event, unlike the other ones.
|
|
|
|
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.
|
|
|
|
@param path
|
|
The name of the path to watch.
|
|
@param events
|
|
An optional filter to receive only events of particular types.
|
|
*/
|
|
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 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.
|
|
*/
|
|
virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
|
|
const wxString& filter = wxEmptyString);
|
|
|
|
/**
|
|
Removes @a path from the list of watched paths.
|
|
*/
|
|
virtual bool Remove(const wxFileName& path);
|
|
|
|
/**
|
|
Same as Remove(), but also removes every file/directory belonging to
|
|
the tree rooted at @a path.
|
|
*/
|
|
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{wxcore}
|
|
@category{events}
|
|
|
|
@see wxFileSystemWatcher
|
|
@see @ref overview_events
|
|
|
|
@since 2.9.1
|
|
*/
|
|
class wxFileSystemWatcherEvent : public wxEvent
|
|
{
|
|
public:
|
|
/**
|
|
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.
|
|
*/
|
|
wxString GetErrorDescription() const;
|
|
|
|
/**
|
|
Returns a wxString describing an event, useful for logging, debugging
|
|
or testing.
|
|
*/
|
|
wxString ToString() const;
|
|
};
|
|
|
|
|
|
/**
|
|
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 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,
|
|
|
|
/**
|
|
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 = 0x20,
|
|
|
|
/**
|
|
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 = 0x40,
|
|
|
|
wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
|
|
wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
|
|
wxFSW_EVENT_ACCESS |
|
|
wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
|
|
};
|
|
|