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     All of these events are reported on all supported platforms.
 189
 190     @since 2.9.1
 191  */
 192 enum wxFSWFlags
 193 {
 194     wxFSW_EVENT_CREATE = 0x01,  ///< File or directory was created
 195     wxFSW_EVENT_DELETE = 0x02,  ///< File or directory was deleted
 196     wxFSW_EVENT_RENAME = 0x04,  ///< File or directory was renamed
 197     wxFSW_EVENT_MODIFY = 0x08,  ///< File or directory was modified
 198     wxFSW_EVENT_ACCESS = 0x10,  ///< File or directory was accessed
 199
 200     wxFSW_EVENT_WARNING = 0x20, ///< A warning condition arose.
 201     wxFSW_EVENT_ERROR = 0x40,   ///< An error condition arose.
 202
 203     wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
 204                          wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
 205                          wxFSW_EVENT_ACCESS |
 206                          wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
 207 };
 208