interface/wx/fswatcher.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/fswatcher.h
   3 // Purpose:     wxFileSystemWatcher
   4 // Author:      Bartosz Bekier
   5 // Created:     2009-05-23
   6 // Copyright:   (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com>
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     @class wxFileSystemWatcher
  12
  13     The wxFileSystemWatcher class allows to receive notifications of file
  14     system changes.
  15
  16     @note Implementation limitations: this class is currently implemented for
  17           MSW, OS X and GTK ports but doesn't detect all changes correctly
  18           everywhere: under MSW accessing the file is not detected (only
  19           modifying it is) and under OS X neither accessing nor modifying is
  20           detected (only creating and deleting files is). Moreover, OS X
  21           version doesn't currently collapse pairs of create/delete events in a
  22           rename event, unlike the other ones.
  23
  24     For the full list of change types that are reported see wxFSWFlags.
  25
  26     This class notifies the application about the file system changes by
  27     sending events of wxFileSystemWatcherEvent class. By default these events
  28     are sent to the wxFileSystemWatcher object itself so you can derive from it
  29     and use the event table @c EVT_FSWATCHER macro to handle these events in a
  30     derived class method. Alternatively, you can use
  31     wxFileSystemWatcher::SetOwner() to send the events to another object. Or
  32     you could use wxEvtHandler::Connect() with @c wxEVT_FSWATCHER to handle
  33     these events in any other object. See the fswatcher sample for an example
  34     of the latter approach.
  35
  36     @library{wxbase}
  37     @category{file}
  38
  39     @since 2.9.1
  40  */
  41 class wxFileSystemWatcher: public wxEvtHandler
  42 {
  43 public:
  44     /**
  45         Default constructor.
  46      */
  47     wxFileSystemWatcher();
  48
  49     /**
  50         Destructor. Stops all paths from being watched and frees any system
  51         resources used by this file system watcher object.
  52      */
  53     virtual ~wxFileSystemWatcher();
  54
  55     /**
  56         Adds @a path to currently watched files.
  57
  58         The @a path argument can currently only be a directory and any changes
  59         to this directory itself or its immediate children will generate the
  60         events. Use AddTree() to monitor the directory recursively.
  61
  62         Note that on platforms that use symbolic links, you should consider the
  63         possibility that @a path is a symlink. To watch the symlink itself and
  64         not its target you may call wxFileName::DontFollowLink() on @a path.
  65
  66         @param path
  67             The name of the path to watch.
  68         @param events
  69             An optional filter to receive only events of particular types.
  70             This is currently implemented only for GTK.
  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 = 0, 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         The item's metadata was changed, e.g.\ its permissions or timestamps.
 252
 253         This event is currently only detected under Linux.
 254
 255         @since 2.9.5
 256      */
 257     wxFSW_EVENT_ATTRIB = 0x20,
 258
 259     /**
 260         The file system containing a watched item was unmounted.
 261
 262         wxFSW_EVENT_UNMOUNT cannot be set; unmount events are produced automatically. This flag
 263         is therefore not included in wxFSW_EVENT_ALL.
 264
 265         This event is currently only detected under Linux.
 266
 267         @since 2.9.5
 268     */
 269     wxFSW_EVENT_UNMOUNT = 0x2000,
 270
 271     /**
 272         A warning condition arose.
 273
 274         This is something that probably needs to be shown to the user in an
 275         interactive program as it can indicate a relatively serious problem,
 276         e.g. some events could have been missed because of an overflow. But
 277         more events will still be coming in the future, unlike for the error
 278         condition below.
 279      */
 280     wxFSW_EVENT_WARNING = 0x40,
 281
 282     /**
 283         An error condition arose.
 284
 285         Errors are fatal, i.e. no more events will be reported after an error
 286         and the program can stop watching the directories currently being
 287         monitored.
 288     */
 289     wxFSW_EVENT_ERROR = 0x80,
 290
 291     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 292                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 293                          wxFSW_EVENT_ACCESS | wxFSW_EVENT_ATTRIB |
 294                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 295 };
 296