interface/wx/fswatcher.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/fswatcher.h
   3 // Purpose:     wxFileSystemWatcher
   4 // Author:      Bartosz Bekier
   5 // Created:     2009-05-23
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     @class wxFileSystemWatcher
  13
  14     The wxFileSystemWatcher class allows to receive notifications of file
  15     system changes.
  16
  17     @note Implementation limitations: this class is currently implemented for
  18           MSW, OS X and GTK ports but doesn't detect all changes correctly
  19           everywhere: under MSW accessing the file is not detected (only
  20           modifying it is) and under OS X neither accessing nor modifying is
  21           detected (only creating and deleting files is). Moreover, OS X
  22           version doesn't currently collapse pairs of create/delete events in a
  23           rename event, unlike the other ones.
  24
  25     For the full list of change types that are reported see wxFSWFlags.
  26
  27     This class notifies the application about the file system changes by
  28     sending events of wxFileSystemWatcherEvent class. By default these events
  29     are sent to the wxFileSystemWatcher object itself so you can derive from it
  30     and use the event table @c EVT_FSWATCHER macro to handle these events in a
  31     derived class method. Alternatively, you can use
  32     wxFileSystemWatcher::SetOwner() to send the events to another object. Or
  33     you could use wxEvtHandler::Connect() with @c wxEVT_FSWATCHER to handle
  34     these events in any other object. See the fswatcher sample for an example
  35     of the latter approach.
  36
  37     @library{wxbase}
  38     @category{file}
  39
  40     @since 2.9.1
  41  */
  42 class wxFileSystemWatcher: public wxEvtHandler
  43 {
  44 public:
  45     /**
  46         Default constructor.
  47      */
  48     wxFileSystemWatcher();
  49
  50     /**
  51         Destructor. Stops all paths from being watched and frees any system
  52         resources used by this file system watcher object.
  53      */
  54     virtual ~wxFileSystemWatcher();
  55
  56     /**
  57         Adds @a path to currently watched files.
  58
  59         The @a path argument can currently only be a directory and any changes
  60         to this directory itself or its immediate children will generate the
  61         events. Use AddTree() to monitor the directory recursively.
  62
  63         @param path
  64             The name of the path to watch.
  65         @param events
  66             An optional filter to receive only events of particular types.
  67      */
  68     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
  69
  70     /**
  71         This is the same as Add(), but recursively adds every file/directory in
  72         the tree rooted at @a path.
  73
  74         Additionally a file mask can be specified to include only files
  75         matching that particular mask.
  76
  77         This method is implemented efficiently under MSW but shouldn't be used
  78         for the directories with a lot of children (such as e.g. the root
  79         directory) under the other platforms as it calls Add() there for each
  80         subdirectory potentially creating a lot of watches and taking a long
  81         time to execute.
  82      */
  83     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
  84                          const wxString& filter = wxEmptyString);
  85
  86     /**
  87         Removes @a path from the list of watched paths.
  88      */
  89     virtual bool Remove(const wxFileName& path);
  90
  91     /**
  92         Same as Remove(), but also removes every file/directory belonging to
  93         the tree rooted at @a path.
  94      */
  95     virtual bool RemoveTree(const wxFileName& path);
  96
  97     /**
  98         Clears the list of currently watched paths.
  99      */
 100     virtual bool RemoveAll();
 101
 102     /**
 103         Returns the number of currently watched paths.
 104
 105         @see GetWatchedPaths()
 106      */
 107     int GetWatchedPathsCount() const;
 108
 109     /**
 110         Retrieves all watched paths and places them in @a paths. Returns
 111         the number of watched paths, which is also the number of entries added
 112         to @a paths.
 113      */
 114     int GetWatchedPaths(wxArrayString* paths) const;
 115
 116     /**
 117         Associates the file system watcher with the given @a handler object.
 118
 119         All the events generated by this object will be passed to the specified
 120         owner.
 121      */
 122     void SetOwner(wxEvtHandler* handler);
 123 };
 124
 125
 126
 127 /**
 128     @class wxFileSystemWatcherEvent
 129
 130     A class of events sent when a file system event occurs. Types of events
 131     reported may vary depending on a platform, however all platforms report
 132     at least creation of new file/directory and access, modification, move
 133     (rename) or deletion of an existing one.
 134
 135     @library{wxcore}
 136     @category{events}
 137
 138     @see wxFileSystemWatcher
 139     @see @ref overview_events
 140
 141     @since 2.9.1
 142 */
 143 class wxFileSystemWatcherEvent : public wxEvent
 144 {
 145 public:
 146     wxFileSystemWatcherEvent(int changeType, int watchid = wxID_ANY);
 147     wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg,
 148                              int watchid = wxID_ANY);
 149     wxFileSystemWatcherEvent(int changeType,
 150                              const wxFileName& path, const wxFileName& newPath,
 151                              int watchid = wxID_ANY);
 152
 153     /**
 154         Returns the path at which the event occurred.
 155      */
 156     const wxFileName& GetPath() const;
 157
 158     /**
 159         Returns the new path of the renamed file/directory if this is a rename
 160         event.
 161
 162         Otherwise it returns the same path as GetPath().
 163      */
 164     const wxFileName& GetNewPath() const;
 165
 166     /**
 167         Returns the type of file system change that occurred. See wxFSWFlags for
 168         the list of possible file system change types.
 169      */
 170     int GetChangeType() const;
 171
 172     /**
 173         Returns @c true if this error is an error event
 174
 175         Error event is an event generated when a warning or error condition
 176         arises.
 177      */
 178     bool IsError() const;
 179
 180     /**
 181         Return a description of the warning or error if this is an error event.
 182      */
 183     wxString GetErrorDescription() const;
 184
 185     /**
 186         Returns a wxString describing an event, useful for logging, debugging
 187         or testing.
 188      */
 189     wxString ToString() const;
 190 };
 191
 192 wxEventType wxEVT_FSWATCHER;
 193
 194 /**
 195     These are the possible types of file system change events.
 196
 197     Not all of these events are reported on all platforms currently.
 198
 199     @since 2.9.1
 200  */
 201 enum wxFSWFlags
 202 {
 203     /// File or directory was created.
 204     wxFSW_EVENT_CREATE = 0x01,
 205
 206     /// File or directory was deleted.
 207     wxFSW_EVENT_DELETE = 0x02,
 208
 209     /**
 210         File or directory was renamed.
 211
 212         Notice that under MSW this event is sometimes -- although not always --
 213         followed by a ::wxFSW_EVENT_MODIFY for the new file.
 214
 215         Under OS X this event is currently not detected and instead separate
 216         ::wxFSW_EVENT_CREATE and ::wxFSW_EVENT_DELETE events are.
 217      */
 218     wxFSW_EVENT_RENAME = 0x04,
 219
 220     /**
 221         File or directory was modified.
 222
 223         Depending on the program doing the file modification, multiple such
 224         events can be reported for a single logical file update.
 225
 226         Under OS X this event is currently not detected.
 227      */
 228     wxFSW_EVENT_MODIFY = 0x08,
 229
 230     /**
 231         File or directory was accessed.
 232
 233         This event is currently only detected under Linux.
 234      */
 235     wxFSW_EVENT_ACCESS = 0x10,
 236
 237     /**
 238         A warning condition arose.
 239
 240         This is something that probably needs to be shown to the user in an
 241         interactive program as it can indicate a relatively serious problem,
 242         e.g. some events could have been missed because of an overflow. But
 243         more events will still be coming in the future, unlike for the error
 244         condition below.
 245      */
 246     wxFSW_EVENT_WARNING = 0x20,
 247
 248     /**
 249         An error condition arose.
 250
 251         Errors are fatal, i.e. no more events will be reported after an error
 252         and the program can stop watching the directories currently being
 253         monitored.
 254     */
 255     wxFSW_EVENT_ERROR = 0x40,
 256
 257     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 258                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 259                          wxFSW_EVENT_ACCESS |
 260                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 261 };
 262