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         Note that on platforms that use symbolic links, you should consider the
  64         possibility that @a path is a symlink. To watch the symlink itself and
  65         not its target you may call wxFileName::DontFollowLink() on @a path.
  66
  67         @param path
  68             The name of the path to watch.
  69         @param events
  70             An optional filter to receive only events of particular types.
  71      */
  72     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
  73
  74     /**
  75         This is the same as Add(), but also recursively adds every
  76         file/directory in the tree rooted at @a path.
  77
  78         Additionally a file mask can be specified to include only files
  79         matching that particular mask.
  80
  81         This method is implemented efficiently on MSW, but should be used with
  82         care on other platforms for directories with lots of children (e.g. the
  83         root directory) as it calls Add() for each subdirectory, potentially
  84         creating a lot of watches and taking a long time to execute.
  85
  86         Note that on platforms that use symbolic links, you will probably want
  87         to have called wxFileName::DontFollowLink on @a path. This is especially
  88         important if the symlink targets may themselves be watched.
  89      */
  90     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
  91                          const wxString& filter = wxEmptyString);
  92
  93     /**
  94         Removes @a path from the list of watched paths.
  95
  96         See the comment in Add() about symbolic links. @a path should treat
  97         symbolic links in the same way as in the original Add() call.
  98      */
  99     virtual bool Remove(const wxFileName& path);
 100
 101     /**
 102         This is the same as Remove(), but also removes every file/directory
 103         belonging to the tree rooted at @a path.
 104
 105         See the comment in AddTree() about symbolic links. @a path should treat
 106         symbolic links in the same way as in the original AddTree() call.
 107      */
 108     virtual bool RemoveTree(const wxFileName& path);
 109
 110     /**
 111         Clears the list of currently watched paths.
 112      */
 113     virtual bool RemoveAll();
 114
 115     /**
 116         Returns the number of currently watched paths.
 117
 118         @see GetWatchedPaths()
 119      */
 120     int GetWatchedPathsCount() const;
 121
 122     /**
 123         Retrieves all watched paths and places them in @a paths. Returns
 124         the number of watched paths, which is also the number of entries added
 125         to @a paths.
 126      */
 127     int GetWatchedPaths(wxArrayString* paths) const;
 128
 129     /**
 130         Associates the file system watcher with the given @a handler object.
 131
 132         All the events generated by this object will be passed to the specified
 133         owner.
 134      */
 135     void SetOwner(wxEvtHandler* handler);
 136 };
 137
 138
 139
 140 /**
 141     @class wxFileSystemWatcherEvent
 142
 143     A class of events sent when a file system event occurs. Types of events
 144     reported may vary depending on a platform, however all platforms report
 145     at least creation of new file/directory and access, modification, move
 146     (rename) or deletion of an existing one.
 147
 148     @library{wxbase}
 149     @category{events}
 150
 151     @see wxFileSystemWatcher
 152     @see @ref overview_events
 153
 154     @since 2.9.1
 155 */
 156 class wxFileSystemWatcherEvent : public wxEvent
 157 {
 158 public:
 159     wxFileSystemWatcherEvent(int changeType, int watchid = wxID_ANY);
 160     wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg,
 161                              int watchid = wxID_ANY);
 162     wxFileSystemWatcherEvent(int changeType,
 163                              const wxFileName& path, const wxFileName& newPath,
 164                              int watchid = wxID_ANY);
 165
 166     /**
 167         Returns the path at which the event occurred.
 168      */
 169     const wxFileName& GetPath() const;
 170
 171     /**
 172         Returns the new path of the renamed file/directory if this is a rename
 173         event.
 174
 175         Otherwise it returns the same path as GetPath().
 176      */
 177     const wxFileName& GetNewPath() const;
 178
 179     /**
 180         Returns the type of file system change that occurred. See wxFSWFlags for
 181         the list of possible file system change types.
 182      */
 183     int GetChangeType() const;
 184
 185     /**
 186         Returns @c true if this error is an error event
 187
 188         Error event is an event generated when a warning or error condition
 189         arises.
 190      */
 191     bool IsError() const;
 192
 193     /**
 194         Return a description of the warning or error if this is an error event.
 195      */
 196     wxString GetErrorDescription() const;
 197
 198     /**
 199         Returns a wxString describing an event, useful for logging, debugging
 200         or testing.
 201      */
 202     wxString ToString() const;
 203 };
 204
 205 wxEventType wxEVT_FSWATCHER;
 206
 207 /**
 208     These are the possible types of file system change events.
 209
 210     Not all of these events are reported on all platforms currently.
 211
 212     @since 2.9.1
 213  */
 214 enum wxFSWFlags
 215 {
 216     /// File or directory was created.
 217     wxFSW_EVENT_CREATE = 0x01,
 218
 219     /// File or directory was deleted.
 220     wxFSW_EVENT_DELETE = 0x02,
 221
 222     /**
 223         File or directory was renamed.
 224
 225         Notice that under MSW this event is sometimes -- although not always --
 226         followed by a ::wxFSW_EVENT_MODIFY for the new file.
 227
 228         Under OS X this event is currently not detected and instead separate
 229         ::wxFSW_EVENT_CREATE and ::wxFSW_EVENT_DELETE events are.
 230      */
 231     wxFSW_EVENT_RENAME = 0x04,
 232
 233     /**
 234         File or directory was modified.
 235
 236         Depending on the program doing the file modification, multiple such
 237         events can be reported for a single logical file update.
 238
 239         Under OS X this event is currently not detected.
 240      */
 241     wxFSW_EVENT_MODIFY = 0x08,
 242
 243     /**
 244         File or directory was accessed.
 245
 246         This event is currently only detected under Linux.
 247      */
 248     wxFSW_EVENT_ACCESS = 0x10,
 249
 250     /**
 251         A warning condition arose.
 252
 253         This is something that probably needs to be shown to the user in an
 254         interactive program as it can indicate a relatively serious problem,
 255         e.g. some events could have been missed because of an overflow. But
 256         more events will still be coming in the future, unlike for the error
 257         condition below.
 258      */
 259     wxFSW_EVENT_WARNING = 0x20,
 260
 261     /**
 262         An error condition arose.
 263
 264         Errors are fatal, i.e. no more events will be reported after an error
 265         and the program can stop watching the directories currently being
 266         monitored.
 267     */
 268     wxFSW_EVENT_ERROR = 0x40,
 269
 270     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 271                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 272                          wxFSW_EVENT_ACCESS |
 273                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 274 };
 275