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     There are three different ways to use this class:
  28
  29      - You may derive a new class from wxFileSystemWatcher and override the
  30        wxFileSystemWatcher::OnChange member to perform the required action
  31        when file system change occurrs. Additionally you may also want to
  32        override wxFileSystemWatcher::OnWarning and
  33        wxFileSystemWatcher::OnError to be notified when an error condition
  34        arises.
  35      - You may use a derived class and the @c EVT_FSWATCHER macro or
  36        wxEvtHandler::Connect to redirect events to an event handler defined in
  37        the derived class. If the default constructor is used, the file system
  38        watcher object will be its own owner object, since it is derived from
  39        wxEvtHandler.
  40      - You may redirect the notifications of file system changes as well as of
  41        error conditions to any wxEvtHandler derived object by using
  42        wxFileSystemWatcher::SetOwner.
  43        Then use the @c EVT_FSWATCHER macro or wxEvtHandler::Connect to send the
  44        events to the event handler which will receive wxFileSystemWatcherEvent.
  45
  46     For example:
  47
  48     @code
  49     class MyWatcher : public wxFileSystemWatcher
  50     {
  51     protected:
  52         void OnChange(int changeType, const wxFileName& path, const wxFileName& newPath)
  53         {
  54             // do whatever you like with the event
  55         }
  56     };
  57
  58     class MyApp : public wxApp
  59     {
  60     public:
  61         ...
  62         void OnEventLoopEnter(wxEventLoopBase* WXUNUSED(loop))
  63         {
  64             // you have to construct the watcher here, because it needs an active loop
  65             m_watcher = new MyWatcher();
  66
  67             // please notify me when a new log file is created
  68             m_watcher->Add(wxFileName::DirName("/var/log", wxFSW_EVENT_CREATE);
  69         }
  70
  71     private:
  72         MyWatcher* m_watcher;
  73     };
  74     @endcode
  75
  76     @library{wxbase}
  77     @category{file}
  78
  79     @since 2.9.1
  80  */
  81 class wxFileSystemWatcher: public wxEvtHandler
  82 {
  83 public:
  84     /**
  85         Default constructor. If you create file system watcher using it you have
  86         to either call SetOwner() and connect an event handler or override
  87         OnChange(), OnWarning() and OnError().
  88      */
  89     wxFileSystemWatcher();
  90
  91     /**
  92         Destructor. Stops all paths from being watched and frees any system
  93         resources used by this file system watcher object.
  94      */
  95     virtual ~wxFileSystemWatcher();
  96
  97     /**
  98         Adds @a path to currently watched files. Optionally a filter can be
  99         specified to receive only events of particular type.
 100
 101         Any events concerning this particular path will be sent either to
 102         connected handler or passed to OnChange(), OnWarning() or OnError().
 103
 104         @note When adding a directory, immediate children will be watched
 105         as well.
 106      */
 107     virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
 108
 109     /**
 110         This is the same as Add(), but recursively adds every file/directory in
 111         the tree rooted at @a path. Additionally a file mask can be specified to
 112         include only files matching that particular mask.
 113      */
 114     virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
 115                         const wxString& filter = wxEmptyString) = 0;
 116
 117     /**
 118         Removes @a path from the list of watched paths.
 119      */
 120     virtual bool Remove(const wxFileName& path);
 121
 122     /**
 123         Same as Remove(), but also removes every file/directory belonging to
 124         the tree rooted at @a path.
 125      */
 126     virtual bool RemoveTree(const wxFileName& path);
 127
 128     /**
 129         Clears the list of currently watched paths.
 130      */
 131     virtual bool RemoveAll();
 132
 133     /**
 134         Returns the number of currently watched paths.
 135
 136         @see GetWatchedPaths()
 137      */
 138     int GetWatchedPathsCount() const;
 139
 140     /**
 141         Retrieves all watched paths and places them in @a paths. Returns
 142         the number of watched paths, which is also the number of entries added
 143         to @a paths.
 144      */
 145     int GetWatchedPaths(wxArrayString* paths) const;
 146
 147     /**
 148         Associates the file system watcher with the given @a handler object.
 149
 150         Basically this means that all events will be passed to this handler
 151         object unless you have change the default behaviour by overriding
 152         OnChange(), OnWarning() or OnError().
 153      */
 154     void SetOwner(wxEvtHandler* handler);
 155
 156 protected:
 157     /**
 158         You may either connect your event handler to intercept file system
 159         watcher events or override this member and handle them here.
 160
 161         Perform whatever action which is to be taken on file system change.
 162      */
 163     virtual void OnChange(int changeType, const wxFileName& path,
 164                                         const wxFileName& newPath);
 165
 166     /**
 167         You may either connect your event handler to intercept file system
 168         watcher events or override this member and handle them here.
 169
 170         Perform whatever action which is to be taken when a warning condition
 171         arises.
 172      */
 173     virtual void OnWarning(const wxString& errorMessage);
 174
 175     /**
 176         You may either connect your event handler to intercept file system
 177         watcher events or override this member and handle them here.
 178
 179         Perform whatever action which is to be taken when an error condition
 180         arises.
 181      */
 182     virtual void OnError(const wxString& errorMessage);
 183 };
 184
 185
 186
 187 /**
 188     @class wxFileSystemWatcherEvent
 189
 190     A class of events sent when a file system event occurs. Types of events
 191     reported may vary depending on a platfrom, however all platforms report
 192     at least creation of new file/directory and access, modification, move
 193     (rename) or deletion of an existing one.
 194
 195     @library{wxcore}
 196     @category{events}
 197
 198     @see wxFileSystemWatcher
 199     @see @ref overview_events
 200
 201     @since 2.9.1
 202 */
 203 class wxFileSystemWatcherEvent : public wxEvent
 204 {
 205 public:
 206     /**
 207         Returns the path at which the event occurred.
 208      */
 209     const wxFileName& GetPath() const;
 210
 211     /**
 212         Returns the new path of the renamed file/directory if this is a rename
 213         event.
 214
 215         Otherwise it returns the same path as GetPath().
 216      */
 217     const wxFileName& GetNewPath() const;
 218
 219     /**
 220         Returns the type of file system change that occurred. See wxFSWFlags for
 221         the list of possible file system change types.
 222      */
 223     int GetChangeType() const;
 224
 225     /**
 226         Returns @c true if this error is an error event
 227
 228         Error event is an event generated when a warning or error condition
 229         arises.
 230      */
 231     bool IsError() const;
 232
 233     /**
 234         Return a description of the warning or error if this is an error event.
 235      */
 236     wxString GetErrorDescription() const;
 237
 238     /**
 239         Returns a wxString describing an event, useful for logging, debugging
 240         or testing.
 241      */
 242     wxString ToString() const;
 243 };
 244
 245
 246 /**
 247     These are the possible types of file system change events.
 248     All of these events are reported on all supported platforms.
 249
 250     @since 2.9.1
 251  */
 252 enum wxFSWFlags
 253 {
 254     wxFSW_EVENT_CREATE = 0x01,  ///< File or directory was created
 255     wxFSW_EVENT_DELETE = 0x02,  ///< File or directory was deleted
 256     wxFSW_EVENT_RENAME = 0x04,  ///< File or directory was renamed
 257     wxFSW_EVENT_MODIFY = 0x08,  ///< File or directory was modified
 258     wxFSW_EVENT_ACCESS = 0x10,  ///< File or directory was accessed
 259
 260     wxFSW_EVENT_WARNING = 0x20, ///< A warning condition arose.
 261     wxFSW_EVENT_ERROR = 0x40,   ///< An error condition arose.
 262
 263     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 264                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 265                          wxFSW_EVENT_ACCESS |
 266                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 267 };
 268