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