]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/fswatcher.h
support for iPhone callbacks
[wxWidgets.git] / 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 Note that on platforms that use symbolic links, you should consider the
64 possibility that @a path is a symlink. To watch the symlink itself and
65 not its target you may call wxFileName::DontFollowLink() on @a path.
66
67 @param path
68 The name of the path to watch.
69 @param events
70 An optional filter to receive only events of particular types.
71 This is currently implemented only for GTK.
72 */
73 virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL);
74
75 /**
76 This is the same as Add(), but also recursively adds every
77 file/directory in the tree rooted at @a path.
78
79 Additionally a file mask can be specified to include only files
80 matching that particular mask.
81
82 This method is implemented efficiently on MSW, but should be used with
83 care on other platforms for directories with lots of children (e.g. the
84 root directory) as it calls Add() for each subdirectory, potentially
85 creating a lot of watches and taking a long time to execute.
86
87 Note that on platforms that use symbolic links, you will probably want
88 to have called wxFileName::DontFollowLink on @a path. This is especially
89 important if the symlink targets may themselves be watched.
90 */
91 virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL,
92 const wxString& filter = wxEmptyString);
93
94 /**
95 Removes @a path from the list of watched paths.
96
97 See the comment in Add() about symbolic links. @a path should treat
98 symbolic links in the same way as in the original Add() call.
99 */
100 virtual bool Remove(const wxFileName& path);
101
102 /**
103 This is the same as Remove(), but also removes every file/directory
104 belonging to the tree rooted at @a path.
105
106 See the comment in AddTree() about symbolic links. @a path should treat
107 symbolic links in the same way as in the original AddTree() call.
108 */
109 virtual bool RemoveTree(const wxFileName& path);
110
111 /**
112 Clears the list of currently watched paths.
113 */
114 virtual bool RemoveAll();
115
116 /**
117 Returns the number of currently watched paths.
118
119 @see GetWatchedPaths()
120 */
121 int GetWatchedPathsCount() const;
122
123 /**
124 Retrieves all watched paths and places them in @a paths. Returns
125 the number of watched paths, which is also the number of entries added
126 to @a paths.
127 */
128 int GetWatchedPaths(wxArrayString* paths) const;
129
130 /**
131 Associates the file system watcher with the given @a handler object.
132
133 All the events generated by this object will be passed to the specified
134 owner.
135 */
136 void SetOwner(wxEvtHandler* handler);
137 };
138
139
140
141 /**
142 @class wxFileSystemWatcherEvent
143
144 A class of events sent when a file system event occurs. Types of events
145 reported may vary depending on a platform, however all platforms report
146 at least creation of new file/directory and access, modification, move
147 (rename) or deletion of an existing one.
148
149 @library{wxbase}
150 @category{events}
151
152 @see wxFileSystemWatcher
153 @see @ref overview_events
154
155 @since 2.9.1
156 */
157 class wxFileSystemWatcherEvent : public wxEvent
158 {
159 public:
160 wxFileSystemWatcherEvent(int changeType = 0, int watchid = wxID_ANY);
161 wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg,
162 int watchid = wxID_ANY);
163 wxFileSystemWatcherEvent(int changeType,
164 const wxFileName& path, const wxFileName& newPath,
165 int watchid = wxID_ANY);
166
167 /**
168 Returns the path at which the event occurred.
169 */
170 const wxFileName& GetPath() const;
171
172 /**
173 Returns the new path of the renamed file/directory if this is a rename
174 event.
175
176 Otherwise it returns the same path as GetPath().
177 */
178 const wxFileName& GetNewPath() const;
179
180 /**
181 Returns the type of file system change that occurred. See wxFSWFlags for
182 the list of possible file system change types.
183 */
184 int GetChangeType() const;
185
186 /**
187 Returns @c true if this error is an error event
188
189 Error event is an event generated when a warning or error condition
190 arises.
191 */
192 bool IsError() const;
193
194 /**
195 Return a description of the warning or error if this is an error event.
196 */
197 wxString GetErrorDescription() const;
198
199 /**
200 Returns a wxString describing an event, useful for logging, debugging
201 or testing.
202 */
203 wxString ToString() const;
204 };
205
206 wxEventType wxEVT_FSWATCHER;
207
208 /**
209 These are the possible types of file system change events.
210
211 Not all of these events are reported on all platforms currently.
212
213 @since 2.9.1
214 */
215 enum wxFSWFlags
216 {
217 /// File or directory was created.
218 wxFSW_EVENT_CREATE = 0x01,
219
220 /// File or directory was deleted.
221 wxFSW_EVENT_DELETE = 0x02,
222
223 /**
224 File or directory was renamed.
225
226 Notice that under MSW this event is sometimes -- although not always --
227 followed by a ::wxFSW_EVENT_MODIFY for the new file.
228
229 Under OS X this event is currently not detected and instead separate
230 ::wxFSW_EVENT_CREATE and ::wxFSW_EVENT_DELETE events are.
231 */
232 wxFSW_EVENT_RENAME = 0x04,
233
234 /**
235 File or directory was modified.
236
237 Depending on the program doing the file modification, multiple such
238 events can be reported for a single logical file update.
239
240 Under OS X this event is currently not detected.
241 */
242 wxFSW_EVENT_MODIFY = 0x08,
243
244 /**
245 File or directory was accessed.
246
247 This event is currently only detected under Linux.
248 */
249 wxFSW_EVENT_ACCESS = 0x10,
250
251 /**
252 The item's metadata was changed, e.g.\ its permissions or timestamps.
253
254 This event is currently only detected under Linux.
255
256 @since 2.9.5
257 */
258 wxFSW_EVENT_ATTRIB = 0x20,
259
260 /**
261 The file system containing a watched item was unmounted.
262
263 wxFSW_EVENT_UNMOUNT cannot be set; unmount events are produced automatically. This flag
264 is therefore not included in wxFSW_EVENT_ALL.
265
266 This event is currently only detected under Linux.
267
268 @since 2.9.5
269 */
270 wxFSW_EVENT_UNMOUNT = 0x2000,
271
272 /**
273 A warning condition arose.
274
275 This is something that probably needs to be shown to the user in an
276 interactive program as it can indicate a relatively serious problem,
277 e.g. some events could have been missed because of an overflow. But
278 more events will still be coming in the future, unlike for the error
279 condition below.
280 */
281 wxFSW_EVENT_WARNING = 0x40,
282
283 /**
284 An error condition arose.
285
286 Errors are fatal, i.e. no more events will be reported after an error
287 and the program can stop watching the directories currently being
288 monitored.
289 */
290 wxFSW_EVENT_ERROR = 0x80,
291
292 wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE |
293 wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY |
294 wxFSW_EVENT_ACCESS | wxFSW_EVENT_ATTRIB |
295 wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR
296 };
297