]>
Commit | Line | Data |
---|---|---|
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 |