Cross-platform file system watcher for monitoring folder changes. More...

#include <gin_filesystemwatcher.h>

Classes
class	Listener
	Listener interface for receiving file system change notifications. More...

Public Types
enum	FileSystemEvent { undefined , fileCreated , fileDeleted , fileUpdated , fileRenamedOldName , fileRenamedNewName }
	File system event types for change notifications. More...

Public Member Functions
	FileSystemWatcher ()
	~FileSystemWatcher ()
void	coalesceEvents (int windowMS)
	All events that arrive withing the time window for a particular file will be coalesced into one event with the type of the most recent event.
void	addFolder (const juce::File &folder)
	Adds a folder to be watched.
void	removeFolder (const juce::File &folder)
	Removes a folder from being watched.
void	removeAllFolders ()
	Removes all folders from being watched.
juce::Array< juce::File >	getWatchedFolders ()
	Gets a list of folders being watched.
void	addListener (Listener *newListener)
	Registers a listener to be told when things happen to the text.
void	removeListener (Listener *listener)
	Deregisters a listener.

Detailed Description

Cross-platform file system watcher for monitoring folder changes.

FileSystemWatcher provides real-time notifications when files are created, modified, deleted, or renamed in watched folders. It uses platform-specific APIs (FSEvents on macOS, ReadDirectoryChangesW on Windows, inotify on Linux) for efficient monitoring without polling.

Key Features:

Real-time file system change notifications
Recursive subfolder watching (macOS and Windows)
Event coalescing to reduce callback frequency
Multiple folder watching
Create, modify, delete, and rename event tracking
Listener pattern for callbacks
Cross-platform (macOS, Windows, Linux)

Platform Differences:

macOS/Windows: Recursively watches all subfolders automatically
Linux: Only watches the specified folder (not subfolders)

Event Coalescing: The watcher can coalesce multiple events for the same file within a time window into a single event, reducing callback overhead when files change rapidly (e.g., during a build process or file copy).

Usage:

class MyFileMonitor : public FileSystemWatcher::Listener
{
public:
    void folderChanged(const File& folder) override
    {
        // Refresh file browser for this folder
        refreshBrowser(folder);
    }
 
    void fileChanged(const File& file, FileSystemEvent event) override
    {
        if (event == fileUpdated && file.hasFileExtension(".txt"))
            reloadTextFile(file);
    }
};
 
FileSystemWatcher watcher;
watcher.addFolder(File("/path/to/watch"));
watcher.coalesceEvents(100);  // Coalesce events within 100ms
 
MyFileMonitor monitor;
watcher.addListener(&monitor);
 
// Watcher runs in background, calling listener on message thread

Thread Safety:

addFolder/removeFolder are thread-safe
Listener callbacks are called on the message thread
Safe to add/remove listeners from any thread

See also: Listener, FileSystemEvent

Member Enumeration Documentation

◆ FileSystemEvent

enum FileSystemWatcher::FileSystemEvent

File system event types for change notifications.

FileSystemEvent describes what happened to a file in a watched folder. Rename events generate two separate callbacks: one with fileRenamedOldName for the original filename, and one with fileRenamedNewName for the new filename.

Events:

undefined: Unknown or unrecognized event
fileCreated: New file was created
fileDeleted: Existing file was deleted
fileUpdated: Existing file was modified
fileRenamedOldName: File was renamed (this is the old name)
fileRenamedNewName: File was renamed (this is the new name)

Note: Rename operations typically generate two events:

fileRenamedOldName with the original filename
fileRenamedNewName with the new filename

See also: FileSystemWatcher, Listener

Enumerator
undefined	Unknown event.
fileCreated	File was created.
fileDeleted	File was deleted.
fileUpdated	File was modified.
fileRenamedOldName	File renamed (old name).
fileRenamedNewName	File renamed (new name).

Constructor & Destructor Documentation

◆ FileSystemWatcher()

FileSystemWatcher::FileSystemWatcher ( )

Referenced by removeListener().

◆ ~FileSystemWatcher()

FileSystemWatcher::~FileSystemWatcher ( )

Member Function Documentation

◆ coalesceEvents()

void FileSystemWatcher::coalesceEvents ( int windowMS )

All events that arrive withing the time window for a particular file will be coalesced into one event with the type of the most recent event.

◆ addFolder()

void FileSystemWatcher::addFolder ( const juce::File & folder )

Adds a folder to be watched.

◆ removeFolder()

void FileSystemWatcher::removeFolder ( const juce::File & folder )

Removes a folder from being watched.

◆ removeAllFolders()

void FileSystemWatcher::removeAllFolders ( )

Removes all folders from being watched.

◆ getWatchedFolders()

juce::Array< juce::File > FileSystemWatcher::getWatchedFolders ( )

Gets a list of folders being watched.

◆ addListener()

void FileSystemWatcher::addListener ( Listener * newListener )

Registers a listener to be told when things happen to the text.

See also: removeListener

◆ removeListener()

void FileSystemWatcher::removeListener ( Listener * listener )

Deregisters a listener.

See also: addListener

References FileSystemWatcher().

The documentation for this class was generated from the following file:

gin_filesystemwatcher.h

Classes

Public Types

Public Member Functions