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 watched paths
 135      */
 136     int GetWatchedPathCount() const;
 137
 138     /**
 139         Retrieves all watched paths and places them in @a paths. Returns
 140         the number of watched paths, which is also the number of entries added
 141         to @a paths.
 142      */
 143     int GetWatchedPaths(wxArrayString* paths) const;
 144
 145     /**
 146         Associates the file system watcher with the given @a handler object.
 147
 148         Basically this means that all events will be passed to this handler
 149         object unless you have change the default behaviour by overriding
 150         OnChange(), OnWarning() or OnError().
 151      */
 152     void SetOwner(wxEvtHandler* handler);
 153
 154 protected:
 155     /**
 156         You may either connect your event handler to intercept file system
 157         watcher events or override this member and handle them here.
 158
 159         Perform whatever action which is to be taken on file system change.
 160      */
 161     virtual void OnChange(int changeType, const wxFileName& path,
 162                                         const wxFileName& newPath);
 163
 164     /**
 165         You may either connect your event handler to intercept file system
 166         watcher events or override this member and handle them here.
 167
 168         Perform whatever action which is to be taken when a warning condition
 169         arises.
 170      */
 171     virtual void OnWarning(const wxString& errorMessage);
 172
 173     /**
 174         You may either connect your event handler to intercept file system
 175         watcher events or override this member and handle them here.
 176
 177         Perform whatever action which is to be taken when an error condition
 178         arises.
 179      */
 180     virtual void OnError(const wxString& errorMessage);
 181 };
 182
 183
 184
 185 /**
 186     @class wxFileSystemWatcherEvent
 187
 188     A class of events sent when a file system event occurs. Types of events
 189     reported may vary depending on a platfrom, however all platforms report
 190     at least creation of new file/directory and access, modification, move
 191     (rename) or deletion of an existing one.
 192
 193     @library{wxcore}
 194     @category{events}
 195
 196     @see wxFileSystemWatcher
 197     @see @ref overview_events
 198
 199     @since 2.9.1
 200 */
 201 class wxFileSystemWatcherEvent : public wxEvent
 202 {
 203 public:
 204     /**
 205         Returns the path at which the event occurred.
 206      */
 207     const wxFileName& GetPath() const;
 208
 209     /**
 210         Returns the new path of the renamed file/directory if this is a rename
 211         event.
 212
 213         Otherwise it returns the same path as GetPath().
 214      */
 215     const wxFileName& GetNewPath() const;
 216
 217     /**
 218         Returns the type of file system change that occurred. See wxFSWFlags for
 219         the list of possible file system change types.
 220      */
 221     int GetChangeType() const;
 222
 223     /**
 224         Returns @c true if this error is an error event
 225
 226         Error event is an event generated when a warning or error condition
 227         arises.
 228      */
 229     bool IsError() const;
 230
 231     /**
 232         Return a description of the warning or error if this is an error event.
 233      */
 234     wxString GetErrorDescription() const;
 235
 236     /**
 237         Returns a wxString describing an event, useful for logging, debugging
 238         or testing.
 239      */
 240     wxString ToString() const;
 241 };
 242
 243
 244 /**
 245     These are the possible types of file system change events.
 246     All of these events are reported on all supported platforms.
 247
 248     @since 2.9.1
 249  */
 250 enum wxFSWFlags
 251 {
 252     wxFSW_EVENT_CREATE = 0x01,  ///< File or directory was created
 253     wxFSW_EVENT_DELETE = 0x02,  ///< File or directory was deleted
 254     wxFSW_EVENT_RENAME = 0x04,  ///< File or directory was renamed
 255     wxFSW_EVENT_MODIFY = 0x08,  ///< File or directory was modified
 256     wxFSW_EVENT_ACCESS = 0x10,  ///< File or directory was accessed
 257
 258     wxFSW_EVENT_WARNING = 0x20, ///< A warning condition arose.
 259     wxFSW_EVENT_ERROR = 0x40,   ///< An error condition arose.
 260
 261     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 262                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 263                          wxFSW_EVENT_ACCESS |
 264                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 265 };
 266