]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: wx/fswatcher.h | |
3 | // Purpose: wxFileSystemWatcher | |
4 | // Author: Bartosz Bekier | |
5 | // Created: 2009-05-23 | |
6 | // Copyright: (c) 2009 Bartosz Bekier <bartosz.bekier@gmail.com> | |
7 | // Licence: wxWindows licence | |
8 | ///////////////////////////////////////////////////////////////////////////// | |
9 | ||
10 | /** | |
11 | @class wxFileSystemWatcher | |
12 | ||
13 | The wxFileSystemWatcher class allows to receive notifications of file | |
14 | system changes. | |
15 | ||
16 | @note Implementation limitations: this class is currently implemented for | |
17 | MSW, OS X and GTK ports but doesn't detect all changes correctly | |
18 | everywhere: under MSW accessing the file is not detected (only | |
19 | modifying it is) and under OS X neither accessing nor modifying is | |
20 | detected (only creating and deleting files is). Moreover, OS X | |
21 | version doesn't currently collapse pairs of create/delete events in a | |
22 | rename event, unlike the other ones. | |
23 | ||
24 | For the full list of change types that are reported see wxFSWFlags. | |
25 | ||
26 | This class notifies the application about the file system changes by | |
27 | sending events of wxFileSystemWatcherEvent class. By default these events | |
28 | are sent to the wxFileSystemWatcher object itself so you can derive from it | |
29 | and use the event table @c EVT_FSWATCHER macro to handle these events in a | |
30 | derived class method. Alternatively, you can use | |
31 | wxFileSystemWatcher::SetOwner() to send the events to another object. Or | |
32 | you could use wxEvtHandler::Connect() with @c wxEVT_FSWATCHER to handle | |
33 | these events in any other object. See the fswatcher sample for an example | |
34 | of the latter approach. | |
35 | ||
36 | @library{wxbase} | |
37 | @category{file} | |
38 | ||
39 | @since 2.9.1 | |
40 | */ | |
41 | class wxFileSystemWatcher: public wxEvtHandler | |
42 | { | |
43 | public: | |
44 | /** | |
45 | Default constructor. | |
46 | */ | |
47 | wxFileSystemWatcher(); | |
48 | ||
49 | /** | |
50 | Destructor. Stops all paths from being watched and frees any system | |
51 | resources used by this file system watcher object. | |
52 | */ | |
53 | virtual ~wxFileSystemWatcher(); | |
54 | ||
55 | /** | |
56 | Adds @a path to currently watched files. | |
57 | ||
58 | The @a path argument can currently only be a directory and any changes | |
59 | to this directory itself or its immediate children will generate the | |
60 | events. Use AddTree() to monitor the directory recursively. | |
61 | ||
62 | Note that on platforms that use symbolic links, you should consider the | |
63 | possibility that @a path is a symlink. To watch the symlink itself and | |
64 | not its target you may call wxFileName::DontFollowLink() on @a path. | |
65 | ||
66 | @param path | |
67 | The name of the path to watch. | |
68 | @param events | |
69 | An optional filter to receive only events of particular types. | |
70 | This is currently implemented only for GTK. | |
71 | */ | |
72 | virtual bool Add(const wxFileName& path, int events = wxFSW_EVENT_ALL); | |
73 | ||
74 | /** | |
75 | This is the same as Add(), but also recursively adds every | |
76 | file/directory in the tree rooted at @a path. | |
77 | ||
78 | Additionally a file mask can be specified to include only files | |
79 | matching that particular mask. | |
80 | ||
81 | This method is implemented efficiently on MSW, but should be used with | |
82 | care on other platforms for directories with lots of children (e.g. the | |
83 | root directory) as it calls Add() for each subdirectory, potentially | |
84 | creating a lot of watches and taking a long time to execute. | |
85 | ||
86 | Note that on platforms that use symbolic links, you will probably want | |
87 | to have called wxFileName::DontFollowLink on @a path. This is especially | |
88 | important if the symlink targets may themselves be watched. | |
89 | */ | |
90 | virtual bool AddTree(const wxFileName& path, int events = wxFSW_EVENT_ALL, | |
91 | const wxString& filter = wxEmptyString); | |
92 | ||
93 | /** | |
94 | Removes @a path from the list of watched paths. | |
95 | ||
96 | See the comment in Add() about symbolic links. @a path should treat | |
97 | symbolic links in the same way as in the original Add() call. | |
98 | */ | |
99 | virtual bool Remove(const wxFileName& path); | |
100 | ||
101 | /** | |
102 | This is the same as Remove(), but also removes every file/directory | |
103 | belonging to the tree rooted at @a path. | |
104 | ||
105 | See the comment in AddTree() about symbolic links. @a path should treat | |
106 | symbolic links in the same way as in the original AddTree() call. | |
107 | */ | |
108 | virtual bool RemoveTree(const wxFileName& path); | |
109 | ||
110 | /** | |
111 | Clears the list of currently watched paths. | |
112 | */ | |
113 | virtual bool RemoveAll(); | |
114 | ||
115 | /** | |
116 | Returns the number of currently watched paths. | |
117 | ||
118 | @see GetWatchedPaths() | |
119 | */ | |
120 | int GetWatchedPathsCount() const; | |
121 | ||
122 | /** | |
123 | Retrieves all watched paths and places them in @a paths. Returns | |
124 | the number of watched paths, which is also the number of entries added | |
125 | to @a paths. | |
126 | */ | |
127 | int GetWatchedPaths(wxArrayString* paths) const; | |
128 | ||
129 | /** | |
130 | Associates the file system watcher with the given @a handler object. | |
131 | ||
132 | All the events generated by this object will be passed to the specified | |
133 | owner. | |
134 | */ | |
135 | void SetOwner(wxEvtHandler* handler); | |
136 | }; | |
137 | ||
138 | ||
139 | ||
140 | /** | |
141 | @class wxFileSystemWatcherEvent | |
142 | ||
143 | A class of events sent when a file system event occurs. Types of events | |
144 | reported may vary depending on a platform, however all platforms report | |
145 | at least creation of new file/directory and access, modification, move | |
146 | (rename) or deletion of an existing one. | |
147 | ||
148 | @library{wxbase} | |
149 | @category{events} | |
150 | ||
151 | @see wxFileSystemWatcher | |
152 | @see @ref overview_events | |
153 | ||
154 | @since 2.9.1 | |
155 | */ | |
156 | class wxFileSystemWatcherEvent : public wxEvent | |
157 | { | |
158 | public: | |
159 | wxFileSystemWatcherEvent(int changeType = 0, int watchid = wxID_ANY); | |
160 | wxFileSystemWatcherEvent(int changeType, const wxString& errorMsg, | |
161 | int watchid = wxID_ANY); | |
162 | wxFileSystemWatcherEvent(int changeType, | |
163 | const wxFileName& path, const wxFileName& newPath, | |
164 | int watchid = wxID_ANY); | |
165 | ||
166 | /** | |
167 | Returns the path at which the event occurred. | |
168 | */ | |
169 | const wxFileName& GetPath() const; | |
170 | ||
171 | /** | |
172 | Returns the new path of the renamed file/directory if this is a rename | |
173 | event. | |
174 | ||
175 | Otherwise it returns the same path as GetPath(). | |
176 | */ | |
177 | const wxFileName& GetNewPath() const; | |
178 | ||
179 | /** | |
180 | Returns the type of file system change that occurred. See wxFSWFlags for | |
181 | the list of possible file system change types. | |
182 | */ | |
183 | int GetChangeType() const; | |
184 | ||
185 | /** | |
186 | Returns @c true if this error is an error event | |
187 | ||
188 | Error event is an event generated when a warning or error condition | |
189 | arises. | |
190 | */ | |
191 | bool IsError() const; | |
192 | ||
193 | /** | |
194 | Return a description of the warning or error if this is an error event. | |
195 | */ | |
196 | wxString GetErrorDescription() const; | |
197 | ||
198 | /** | |
199 | Returns a wxString describing an event, useful for logging, debugging | |
200 | or testing. | |
201 | */ | |
202 | wxString ToString() const; | |
203 | }; | |
204 | ||
205 | wxEventType wxEVT_FSWATCHER; | |
206 | ||
207 | /** | |
208 | These are the possible types of file system change events. | |
209 | ||
210 | Not all of these events are reported on all platforms currently. | |
211 | ||
212 | @since 2.9.1 | |
213 | */ | |
214 | enum wxFSWFlags | |
215 | { | |
216 | /// File or directory was created. | |
217 | wxFSW_EVENT_CREATE = 0x01, | |
218 | ||
219 | /// File or directory was deleted. | |
220 | wxFSW_EVENT_DELETE = 0x02, | |
221 | ||
222 | /** | |
223 | File or directory was renamed. | |
224 | ||
225 | Notice that under MSW this event is sometimes -- although not always -- | |
226 | followed by a ::wxFSW_EVENT_MODIFY for the new file. | |
227 | ||
228 | Under OS X this event is currently not detected and instead separate | |
229 | ::wxFSW_EVENT_CREATE and ::wxFSW_EVENT_DELETE events are. | |
230 | */ | |
231 | wxFSW_EVENT_RENAME = 0x04, | |
232 | ||
233 | /** | |
234 | File or directory was modified. | |
235 | ||
236 | Depending on the program doing the file modification, multiple such | |
237 | events can be reported for a single logical file update. | |
238 | ||
239 | Under OS X this event is currently not detected. | |
240 | */ | |
241 | wxFSW_EVENT_MODIFY = 0x08, | |
242 | ||
243 | /** | |
244 | File or directory was accessed. | |
245 | ||
246 | This event is currently only detected under Linux. | |
247 | */ | |
248 | wxFSW_EVENT_ACCESS = 0x10, | |
249 | ||
250 | /** | |
251 | The item's metadata was changed, e.g.\ its permissions or timestamps. | |
252 | ||
253 | This event is currently only detected under Linux. | |
254 | ||
255 | @since 2.9.5 | |
256 | */ | |
257 | wxFSW_EVENT_ATTRIB = 0x20, | |
258 | ||
259 | /** | |
260 | The file system containing a watched item was unmounted. | |
261 | ||
262 | wxFSW_EVENT_UNMOUNT cannot be set; unmount events are produced automatically. This flag | |
263 | is therefore not included in wxFSW_EVENT_ALL. | |
264 | ||
265 | This event is currently only detected under Linux. | |
266 | ||
267 | @since 2.9.5 | |
268 | */ | |
269 | wxFSW_EVENT_UNMOUNT = 0x2000, | |
270 | ||
271 | /** | |
272 | A warning condition arose. | |
273 | ||
274 | This is something that probably needs to be shown to the user in an | |
275 | interactive program as it can indicate a relatively serious problem, | |
276 | e.g. some events could have been missed because of an overflow. But | |
277 | more events will still be coming in the future, unlike for the error | |
278 | condition below. | |
279 | */ | |
280 | wxFSW_EVENT_WARNING = 0x40, | |
281 | ||
282 | /** | |
283 | An error condition arose. | |
284 | ||
285 | Errors are fatal, i.e. no more events will be reported after an error | |
286 | and the program can stop watching the directories currently being | |
287 | monitored. | |
288 | */ | |
289 | wxFSW_EVENT_ERROR = 0x80, | |
290 | ||
291 | wxFSW_EVENT_ALL = wxFSW_EVENT_CREATE | wxFSW_EVENT_DELETE | | |
292 | wxFSW_EVENT_RENAME | wxFSW_EVENT_MODIFY | | |
293 | wxFSW_EVENT_ACCESS | wxFSW_EVENT_ATTRIB | | |
294 | wxFSW_EVENT_WARNING | wxFSW_EVENT_ERROR | |
295 | }; | |
296 |