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     /**
 147         Returns the path at which the event occurred.
 148      */
 149     const wxFileName& GetPath() const;
 150
 151     /**
 152         Returns the new path of the renamed file/directory if this is a rename
 153         event.
 154
 155         Otherwise it returns the same path as GetPath().
 156      */
 157     const wxFileName& GetNewPath() const;
 158
 159     /**
 160         Returns the type of file system change that occurred. See wxFSWFlags for
 161         the list of possible file system change types.
 162      */
 163     int GetChangeType() const;
 164
 165     /**
 166         Returns @c true if this error is an error event
 167
 168         Error event is an event generated when a warning or error condition
 169         arises.
 170      */
 171     bool IsError() const;
 172
 173     /**
 174         Return a description of the warning or error if this is an error event.
 175      */
 176     wxString GetErrorDescription() const;
 177
 178     /**
 179         Returns a wxString describing an event, useful for logging, debugging
 180         or testing.
 181      */
 182     wxString ToString() const;
 183 };
 184
 185
 186 /**
 187     These are the possible types of file system change events.
 188
 189     Not all of these events are reported on all platforms currently.
 190
 191     @since 2.9.1
 192  */
 193 enum wxFSWFlags
 194 {
 195     /// File or directory was created.
 196     wxFSW_EVENT_CREATE = 0x01,
 197
 198     /// File or directory was deleted.
 199     wxFSW_EVENT_DELETE = 0x02,
 200
 201     /**
 202         File or directory was renamed.
 203
 204         Notice that under MSW this event is sometimes -- although not always --
 205         followed by a ::wxFSW_EVENT_MODIFY for the new file.
 206
 207         Under OS X this event is currently not detected and instead separate
 208         ::wxFSW_EVENT_CREATE and ::wxFSW_EVENT_DELETE events are.
 209      */
 210     wxFSW_EVENT_RENAME = 0x04,
 211
 212     /**
 213         File or directory was modified.
 214
 215         Depending on the program doing the file modification, multiple such
 216         events can be reported for a single logical file update.
 217
 218         Under OS X this event is currently not detected.
 219      */
 220     wxFSW_EVENT_MODIFY = 0x08,
 221
 222     /**
 223         File or directory was accessed.
 224
 225         This event is currently only detected under Linux.
 226      */
 227     wxFSW_EVENT_ACCESS = 0x10,
 228
 229     /**
 230         A warning condition arose.
 231
 232         This is something that probably needs to be shown to the user in an
 233         interactive program as it can indicate a relatively serious problem,
 234         e.g. some events could have been missed because of an overflow. But
 235         more events will still be coming in the future, unlike for the error
 236         condition below.
 237      */
 238     wxFSW_EVENT_WARNING = 0x20,
 239
 240     /**
 241         An error condition arose.
 242
 243         Errors are fatal, i.e. no more events will be reported after an error
 244         and the program can stop watching the directories currently being
 245         monitored.
 246     */
 247     wxFSW_EVENT_ERROR = 0x40,
 248
 249     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 250                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 251                          wxFSW_EVENT_ACCESS |
 252                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 253 };
 254