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
 157
 158
 159 /**
 160     @class wxFileSystemWatcherEvent
 161
 162     A class of events sent when a file system event occurs. Types of events
 163     reported may vary depending on a platfrom, however all platforms report
 164     at least creation of new file/directory and access, modification, move
 165     (rename) or deletion of an existing one.
 166
 167     @library{wxcore}
 168     @category{events}
 169
 170     @see wxFileSystemWatcher
 171     @see @ref overview_events
 172
 173     @since 2.9.1
 174 */
 175 class wxFileSystemWatcherEvent : public wxEvent
 176 {
 177 public:
 178     /**
 179         Returns the path at which the event occurred.
 180      */
 181     const wxFileName& GetPath() const;
 182
 183     /**
 184         Returns the new path of the renamed file/directory if this is a rename
 185         event.
 186
 187         Otherwise it returns the same path as GetPath().
 188      */
 189     const wxFileName& GetNewPath() const;
 190
 191     /**
 192         Returns the type of file system change that occurred. See wxFSWFlags for
 193         the list of possible file system change types.
 194      */
 195     int GetChangeType() const;
 196
 197     /**
 198         Returns @c true if this error is an error event
 199
 200         Error event is an event generated when a warning or error condition
 201         arises.
 202      */
 203     bool IsError() const;
 204
 205     /**
 206         Return a description of the warning or error if this is an error event.
 207      */
 208     wxString GetErrorDescription() const;
 209
 210     /**
 211         Returns a wxString describing an event, useful for logging, debugging
 212         or testing.
 213      */
 214     wxString ToString() const;
 215 };
 216
 217
 218 /**
 219     These are the possible types of file system change events.
 220     All of these events are reported on all supported platforms.
 221
 222     @since 2.9.1
 223  */
 224 enum wxFSWFlags
 225 {
 226     wxFSW_EVENT_CREATE = 0x01,  ///< File or directory was created
 227     wxFSW_EVENT_DELETE = 0x02,  ///< File or directory was deleted
 228     wxFSW_EVENT_RENAME = 0x04,  ///< File or directory was renamed
 229     wxFSW_EVENT_MODIFY = 0x08,  ///< File or directory was modified
 230     wxFSW_EVENT_ACCESS = 0x10,  ///< File or directory was accessed
 231
 232     wxFSW_EVENT_WARNING = 0x20, ///< A warning condition arose.
 233     wxFSW_EVENT_ERROR = 0x40,   ///< An error condition arose.
 234
 235     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 236                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 237                          wxFSW_EVENT_ACCESS |
 238                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 239 };
 240