Version: 3.3.0
wxFileSystemWatcher Class Reference

#include <wx/fswatcher.h>

+ Inheritance diagram for wxFileSystemWatcher:

Detailed Description

The wxFileSystemWatcher class allows receiving notifications of file system changes.

Note
Implementation limitations: this class is currently implemented for MSW, macOS and GTK ports but doesn't detect all changes correctly everywhere: under MSW accessing the file is not detected (only modifying it is) and under macOS neither accessing nor modifying is detected (only creating and deleting files is). Moreover, macOS version doesn't currently collapse pairs of create/delete events in a rename event, unlike the other ones.
The application's event loop needs to be running before a wxFileSystemWatcher can be properly created, and that is why one should not be created too early during application startup. If you intend to create a wxFileSystemWatcher at startup, you can override wxAppConsole::OnEventLoopEnter() to ensure it is not done too early.

For the full list of change types that are reported see wxFSWFlags.

This class notifies the application about the file system changes by sending events of wxFileSystemWatcherEvent class. By default these events are sent to the wxFileSystemWatcher object itself so you can derive from it and use the event table EVT_FSWATCHER macro to handle these events in a derived class method. Alternatively, you can use wxFileSystemWatcher::SetOwner() to send the events to another object. Or you could use wxEvtHandler::Bind() with wxEVT_FSWATCHER to handle these events in any other object. See the fswatcher sample for an example of the latter approach.

Library:  wxBase
Category:  File Handling
Since
2.9.1

Public Member Functions

 wxFileSystemWatcher ()
 Default constructor. More...
 
virtual ~wxFileSystemWatcher ()
 Destructor. More...
 
virtual bool Add (const wxFileName &path, int events=wxFSW_EVENT_ALL)
 Adds path to currently watched files. More...
 
virtual bool AddTree (const wxFileName &path, int events=wxFSW_EVENT_ALL, const wxString &filter=wxEmptyString)
 This is the same as Add(), but also recursively adds every file/directory in the tree rooted at path. More...
 
virtual bool Remove (const wxFileName &path)
 Removes path from the list of watched paths. More...
 
virtual bool RemoveTree (const wxFileName &path)
 This is the same as Remove(), but also removes every file/directory belonging to the tree rooted at path. More...
 
virtual bool RemoveAll ()
 Clears the list of currently watched paths. More...
 
int GetWatchedPathsCount () const
 Returns the number of currently watched paths. More...
 
int GetWatchedPaths (wxArrayString *paths) const
 Retrieves all watched paths and places them in paths. More...
 
void SetOwner (wxEvtHandler *handler)
 Associates the file system watcher with the given handler object. More...
 
- Public Member Functions inherited from wxEvtHandler
 wxEvtHandler ()
 Constructor. More...
 
virtual ~wxEvtHandler ()
 Destructor. More...
 
virtual void QueueEvent (wxEvent *event)
 Queue event for a later processing. More...
 
virtual void AddPendingEvent (const wxEvent &event)
 Post an event to be processed later. More...
 
template<typename T , typename T1 , ... >
void CallAfter (void(T::*method)(T1,...), T1 x1,...)
 Asynchronously call the given method. More...
 
template<typename T >
void CallAfter (const T &functor)
 Asynchronously call the given functor. More...
 
virtual bool ProcessEvent (wxEvent &event)
 Processes an event, searching event tables and calling zero or more suitable event handler function(s). More...
 
bool ProcessEventLocally (wxEvent &event)
 Try to process the event in this handler and all those chained to it. More...
 
bool SafelyProcessEvent (wxEvent &event)
 Processes an event by calling ProcessEvent() and handles any exceptions that occur in the process. More...
 
void ProcessPendingEvents ()
 Processes the pending events previously queued using QueueEvent() or AddPendingEvent(); you must call this function only if you are sure there are pending events for this handler, otherwise a wxCHECK will fail. More...
 
void DeletePendingEvents ()
 Deletes all events queued on this event handler using QueueEvent() or AddPendingEvent(). More...
 
void Connect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
 Connects the given function dynamically with the event handler, id and event type. More...
 
void Connect (int id, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
 
void Connect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
 
bool Disconnect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
 Disconnects the given function dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed. More...
 
bool Disconnect (int id=wxID_ANY, wxEventType eventType=wxEVT_NULL, wxObjectEventFunction function=nullptr, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
 
bool Disconnect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function=nullptr, wxObject *userData=nullptr, wxEvtHandler *eventSink=nullptr)
 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info. More...
 
template<typename EventTag , typename Functor >
void Bind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
 Binds the given function, functor or method dynamically with the event. More...
 
template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
void Bind (const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
 See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info. More...
 
template<typename EventTag , typename Functor >
bool Unbind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
 Unbinds the given function, functor or method dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed. More...
 
template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
bool Unbind (const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=nullptr)
 See the Unbind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info. More...
 
void * GetClientData () const
 Returns user-supplied client data. More...
 
wxClientDataGetClientObject () const
 Returns a pointer to the user-supplied client data object. More...
 
void SetClientData (void *data)
 Sets user-supplied client data. More...
 
void SetClientObject (wxClientData *data)
 Set the client data object. More...
 
bool GetEvtHandlerEnabled () const
 Returns true if the event handler is enabled, false otherwise. More...
 
wxEvtHandlerGetNextHandler () const
 Returns the pointer to the next handler in the chain. More...
 
wxEvtHandlerGetPreviousHandler () const
 Returns the pointer to the previous handler in the chain. More...
 
void SetEvtHandlerEnabled (bool enabled)
 Enables or disables the event handler. More...
 
virtual void SetNextHandler (wxEvtHandler *handler)
 Sets the pointer to the next handler. More...
 
virtual void SetPreviousHandler (wxEvtHandler *handler)
 Sets the pointer to the previous handler. More...
 
void Unlink ()
 Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted). More...
 
bool IsUnlinked () const
 Returns true if the next and the previous handler pointers of this event handler instance are nullptr. More...
 
- Public Member Functions inherited from wxObject
 wxObject ()
 Default ctor; initializes to nullptr the internal reference data. More...
 
 wxObject (const wxObject &other)
 Copy ctor. More...
 
virtual ~wxObject ()
 Destructor. More...
 
virtual wxClassInfoGetClassInfo () const
 This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
 
wxObjectRefDataGetRefData () const
 Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
 
bool IsKindOf (const wxClassInfo *info) const
 Determines whether this class is a subclass of (or the same class as) the given class. More...
 
bool IsSameAs (const wxObject &obj) const
 Returns true if this object has the same data pointer as obj. More...
 
void Ref (const wxObject &clone)
 Makes this object refer to the data in clone. More...
 
void SetRefData (wxObjectRefData *data)
 Sets the wxObject::m_refData pointer. More...
 
void UnRef ()
 Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
 
void UnShare ()
 This is the same of AllocExclusive() but this method is public. More...
 
void operator delete (void *buf)
 The delete operator is defined for debugging versions of the library only, when the identifier __WXDEBUG__ is defined. More...
 
void * operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
 The new operator is defined for debugging versions of the library only, when the identifier __WXDEBUG__ is defined. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from wxEvtHandler
static void AddFilter (wxEventFilter *filter)
 Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets. More...
 
static void RemoveFilter (wxEventFilter *filter)
 Remove a filter previously installed with AddFilter(). More...
 
- Protected Member Functions inherited from wxEvtHandler
virtual bool TryBefore (wxEvent &event)
 Method called by ProcessEvent() before examining this object event tables. More...
 
virtual bool TryAfter (wxEvent &event)
 Method called by ProcessEvent() as last resort. More...
 
- Protected Member Functions inherited from wxObject
void AllocExclusive ()
 Ensure that this object's data is not shared with any other object. More...
 
virtual wxObjectRefDataCreateRefData () const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
 
virtual wxObjectRefDataCloneRefData (const wxObjectRefData *data) const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
 
- Protected Attributes inherited from wxObject
wxObjectRefDatam_refData
 Pointer to an object which is the object's reference-counted data. More...
 

Constructor & Destructor Documentation

◆ wxFileSystemWatcher()

wxFileSystemWatcher::wxFileSystemWatcher ( )

Default constructor.

◆ ~wxFileSystemWatcher()

virtual wxFileSystemWatcher::~wxFileSystemWatcher ( )
virtual

Destructor.

Stops all paths from being watched and frees any system resources used by this file system watcher object.

Member Function Documentation

◆ Add()

virtual bool wxFileSystemWatcher::Add ( const wxFileName path,
int  events = wxFSW_EVENT_ALL 
)
virtual

Adds path to currently watched files.

The path argument can currently only be a directory and any changes to this directory itself or its immediate children will generate the events. Use AddTree() to monitor the directory recursively.

Note that on platforms that use symbolic links, you should consider the possibility that path is a symlink. To watch the symlink itself and not its target you may call wxFileName::DontFollowLink() on path.

Parameters
pathThe name of the path to watch.
eventsAn optional filter to receive only events of particular types. This is currently implemented only for GTK.

◆ AddTree()

virtual bool wxFileSystemWatcher::AddTree ( const wxFileName path,
int  events = wxFSW_EVENT_ALL,
const wxString filter = wxEmptyString 
)
virtual

This is the same as Add(), but also recursively adds every file/directory in the tree rooted at path.

Additionally a file mask can be specified to include only files matching that particular mask.

This method is implemented efficiently on MSW and macOS, but should be used with care on other platforms for directories with lots of children (e.g. the root directory) as it calls Add() for each subdirectory, potentially creating a lot of watches and taking a long time to execute.

Note that on platforms that use symbolic links, you will probably want to have called wxFileName::DontFollowLink on path. This is especially important if the symlink targets may themselves be watched.

◆ GetWatchedPaths()

int wxFileSystemWatcher::GetWatchedPaths ( wxArrayString paths) const

Retrieves all watched paths and places them in paths.

Returns the number of watched paths, which is also the number of entries added to paths.

◆ GetWatchedPathsCount()

int wxFileSystemWatcher::GetWatchedPathsCount ( ) const

Returns the number of currently watched paths.

See also
GetWatchedPaths()

◆ Remove()

virtual bool wxFileSystemWatcher::Remove ( const wxFileName path)
virtual

Removes path from the list of watched paths.

See the comment in Add() about symbolic links. path should treat symbolic links in the same way as in the original Add() call.

◆ RemoveAll()

virtual bool wxFileSystemWatcher::RemoveAll ( )
virtual

Clears the list of currently watched paths.

◆ RemoveTree()

virtual bool wxFileSystemWatcher::RemoveTree ( const wxFileName path)
virtual

This is the same as Remove(), but also removes every file/directory belonging to the tree rooted at path.

See the comment in AddTree() about symbolic links. path should treat symbolic links in the same way as in the original AddTree() call.

◆ SetOwner()

void wxFileSystemWatcher::SetOwner ( wxEvtHandler handler)

Associates the file system watcher with the given handler object.

All the events generated by this object will be passed to the specified owner.