A class to asynchronously scan for details about the files in a directory. More...

#include <juce_DirectoryContentsList.h>

Inheritance diagram for juce::DirectoryContentsList:

Collaboration diagram for juce::DirectoryContentsList:

[legend]

Classes
struct	FileInfo
	Contains cached information about one of the files in a DirectoryContentsList. More...

Public Member Functions
	DirectoryContentsList (const FileFilter *fileFilter, TimeSliceThread &threadToUse)
	Creates a directory list. More...

	~DirectoryContentsList () override
	Destructor. More...

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster. More...

void	clear ()
	Clears the list, and stops the thread scanning for files. More...

bool	contains (const File &) const
	Returns true if the list contains the specified file. More...

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...

const File &	getDirectory () const noexcept
	Returns the directory that's currently being used. More...

File	getFile (int index) const
	Returns one of the files in the list. More...

bool	getFileInfo (int index, FileInfo &resultInfo) const
	Returns the cached information about one of the files in the list. More...

const FileFilter *	getFilter () const noexcept
	Returns the file filter being used. More...

int	getNumFiles () const noexcept
	Returns the number of files currently available in the list. More...

TimeSliceThread &	getTimeSliceThread () const noexcept

bool	ignoresHiddenFiles () const
	Returns true if hidden files are ignored. More...

bool	isFindingDirectories () const noexcept
	Returns true if this list contains directories. More...

bool	isFindingFiles () const noexcept
	Returns true if this list contains files. More...

bool	isStillLoading () const
	True if the background thread hasn't yet finished scanning for files. More...

void	refresh ()
	Clears the list and restarts scanning the directory for files. More...

void	removeAllChangeListeners ()
	Removes all listeners from the list. More...

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list. More...

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners. More...

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners. More...

void	setDirectory (const File &directory, bool includeDirectories, bool includeFiles)
	Sets the directory to look in for files. More...

void	setFileFilter (const FileFilter *newFileFilter)
	Replaces the current FileFilter. More...

void	setIgnoresHiddenFiles (bool shouldIgnoreHiddenFiles)
	Tells the list whether or not to ignore hidden files. More...

Private Member Functions
bool	addFile (const File &, bool isDir, int64 fileSize, Time modTime, Time creationTime, bool isReadOnly)

void	callListeners ()

void	changed ()

bool	checkNextFile (bool &hasChanged)

void	setTypeFlags (int)

void	stopSearching ()

int	useTimeSlice () override
	Called back by a TimeSliceThread. More...

Private Attributes
std::atomic< bool >	anyListeners { false }

ChangeBroadcasterCallback	broadcastCallback

ListenerList< ChangeListener >	changeListeners

const FileFilter *	fileFilter = nullptr

std::unique_ptr< RangedDirectoryIterator >	fileFindHandle

CriticalSection	fileListLock

OwnedArray< FileInfo >	files

int	fileTypeFlags = File::ignoreHiddenFiles \| File::findFiles

bool	isSearching = false

Time	nextCallTime

File	root

std::atomic< bool >	shouldStop { true }

TimeSliceThread &	thread

bool	wasEmpty = true

Detailed Description

A class to asynchronously scan for details about the files in a directory.

This keeps a list of files and some information about them, using a background thread to scan for more files. As files are found, it broadcasts change messages to tell any listeners.

See also: FileListComponent, FileBrowserComponent

@tags{GUI}

Constructor & Destructor Documentation

◆ DirectoryContentsList()

juce::DirectoryContentsList::DirectoryContentsList	(	const FileFilter *	fileFilter,
		TimeSliceThread &	threadToUse
	)

Creates a directory list.

To set the directory it should point to, use setDirectory(), which will also start it scanning for files on the background thread.

When the background thread finds and adds new files to this list, the ChangeBroadcaster class will send a change message, so you can register listeners and update them when the list changes.

Parameters

fileFilter	an optional filter to select which files are included in the list. If this is nullptr, then all files and directories are included. Make sure that the filter doesn't get deleted during the lifetime of this object
threadToUse	a thread object that this list can use to scan for files as a background task. Make sure that the thread you give it has been started, or you won't get any files!

◆ ~DirectoryContentsList()

juce::DirectoryContentsList::~DirectoryContentsList ( )

override

Destructor.

Member Function Documentation

◆ addChangeListener()

void juce::ChangeBroadcaster::addChangeListener ( ChangeListener * listener )

inherited

Registers a listener to receive change callbacks from this broadcaster.

Trying to add a listener that's already on the list will have no effect.

◆ addFile()

bool juce::DirectoryContentsList::addFile	(	const File &	,
		bool	isDir,
		int64	fileSize,
		Time	modTime,
		Time	creationTime,
		bool	isReadOnly
	)

private

◆ callListeners()

void juce::ChangeBroadcaster::callListeners ( )

privateinherited

◆ changed()

void juce::DirectoryContentsList::changed ( )

private

◆ checkNextFile()

bool juce::DirectoryContentsList::checkNextFile ( bool & hasChanged )

private

◆ clear()

void juce::DirectoryContentsList::clear ( )

Clears the list, and stops the thread scanning for files.

◆ contains()

bool juce::DirectoryContentsList::contains ( const File & ) const

Returns true if the list contains the specified file.

◆ dispatchPendingMessages()

void juce::ChangeBroadcaster::dispatchPendingMessages ( )

inherited

If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

For thread-safety reasons, you must only call this method on the main message thread.

◆ getDirectory()

const File& juce::DirectoryContentsList::getDirectory ( ) const

inlinenoexcept

Returns the directory that's currently being used.

◆ getFile()

File juce::DirectoryContentsList::getFile ( int index ) const

Returns one of the files in the list.

Parameters

index should be less than getNumFiles(). If this is out-of-range, the return value will be a default File() object

See also: getNumFiles, getFileInfo

◆ getFileInfo()

bool juce::DirectoryContentsList::getFileInfo	(	int	index,
		FileInfo &	resultInfo
	)		const

Returns the cached information about one of the files in the list.

If the index is in-range, this will return true and will copy the file's details to the structure that is passed-in.

If it returns false, then the index wasn't in range, and the structure won't be affected.

See also: getNumFiles, getFile

◆ getFilter()

const FileFilter* juce::DirectoryContentsList::getFilter ( ) const

inlinenoexcept

Returns the file filter being used.

The filter is specified in the constructor.

◆ getNumFiles()

int juce::DirectoryContentsList::getNumFiles ( ) const

noexcept

Returns the number of files currently available in the list.

The info about one of these files can be retrieved with getFileInfo() or getFile().

Obviously as the background thread runs and scans the directory for files, this number will change.

See also: getFileInfo, getFile

◆ getTimeSliceThread()

TimeSliceThread& juce::DirectoryContentsList::getTimeSliceThread ( ) const

inlinenoexcept

◆ ignoresHiddenFiles()

bool juce::DirectoryContentsList::ignoresHiddenFiles ( ) const

Returns true if hidden files are ignored.

See also: setIgnoresHiddenFiles

◆ isFindingDirectories()

bool juce::DirectoryContentsList::isFindingDirectories ( ) const

inlinenoexcept

Returns true if this list contains directories.

See also: setDirectory

References juce::File::findDirectories.

◆ isFindingFiles()

bool juce::DirectoryContentsList::isFindingFiles ( ) const

inlinenoexcept

Returns true if this list contains files.

See also: setDirectory

References juce::File::findFiles.

◆ isStillLoading()

bool juce::DirectoryContentsList::isStillLoading ( ) const

True if the background thread hasn't yet finished scanning for files.

◆ refresh()

void juce::DirectoryContentsList::refresh ( )

Clears the list and restarts scanning the directory for files.

◆ removeAllChangeListeners()

void juce::ChangeBroadcaster::removeAllChangeListeners ( )

inherited

Removes all listeners from the list.

◆ removeChangeListener()

void juce::ChangeBroadcaster::removeChangeListener ( ChangeListener * listener )

inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ sendChangeMessage()

void juce::ChangeBroadcaster::sendChangeMessage ( )

inherited

Causes an asynchronous change message to be sent to all the registered listeners.

The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void juce::ChangeBroadcaster::sendSynchronousChangeMessage ( )

inherited

Sends a synchronous change message to all the registered listeners.

This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.

See also: dispatchPendingMessages

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ setDirectory()

void juce::DirectoryContentsList::setDirectory	(	const File &	directory,
		bool	includeDirectories,
		bool	includeFiles
	)

Sets the directory to look in for files.

If the directory that's passed in is different to the current one, this will also start the background thread scanning it for files.

◆ setFileFilter()

void juce::DirectoryContentsList::setFileFilter ( const FileFilter * newFileFilter )

Replaces the current FileFilter.

This can be nullptr to have no filter. The DirectoryContentList does not take ownership of this object - it just keeps a pointer to it, so you must manage its lifetime. Note that this only replaces the filter, it doesn't refresh the list - you'll probably want to call refresh() after calling this.

◆ setIgnoresHiddenFiles()

void juce::DirectoryContentsList::setIgnoresHiddenFiles ( bool shouldIgnoreHiddenFiles )

Tells the list whether or not to ignore hidden files.

By default these are ignored.

◆ setTypeFlags()

void juce::DirectoryContentsList::setTypeFlags ( int )

private

◆ stopSearching()

void juce::DirectoryContentsList::stopSearching ( )

private

◆ useTimeSlice()

int juce::DirectoryContentsList::useTimeSlice ( )

overrideprivatevirtual

Called back by a TimeSliceThread.

When you register this class with it, a TimeSliceThread will repeatedly call this method.

The implementation of this method should use its time-slice to do something that's quick - never block for longer than absolutely necessary.

Returns: Your method should return the number of milliseconds which it would like to wait before being called again. Returning 0 will make the thread call again as soon as possible (after possibly servicing other busy clients). If you return a value below zero, your client will be removed from the list of clients, and won't be called again. The value you specify isn't a guarantee, and is only used as a hint by the thread - the actual time before the next callback may be more or less than specified. You can force the TimeSliceThread to wake up and poll again immediately by calling its notify() method.

Implements juce::TimeSliceClient.

Member Data Documentation

◆ anyListeners

std::atomic<bool> juce::ChangeBroadcaster::anyListeners { false }

privateinherited

◆ broadcastCallback

ChangeBroadcasterCallback juce::ChangeBroadcaster::broadcastCallback

privateinherited

◆ changeListeners

ListenerList<ChangeListener> juce::ChangeBroadcaster::changeListeners

privateinherited

◆ fileFilter

const FileFilter* juce::DirectoryContentsList::fileFilter = nullptr

private

◆ fileFindHandle

std::unique_ptr<RangedDirectoryIterator> juce::DirectoryContentsList::fileFindHandle

private

◆ fileListLock

CriticalSection juce::DirectoryContentsList::fileListLock

private

◆ files

OwnedArray<FileInfo> juce::DirectoryContentsList::files

private

◆ fileTypeFlags

int juce::DirectoryContentsList::fileTypeFlags = File::ignoreHiddenFiles | File::findFiles

private

◆ isSearching

bool juce::DirectoryContentsList::isSearching = false

private

◆ nextCallTime

Time juce::TimeSliceClient::nextCallTime

privateinherited

◆ root

File juce::DirectoryContentsList::root

private

◆ shouldStop

std::atomic<bool> juce::DirectoryContentsList::shouldStop { true }

private

◆ thread

TimeSliceThread& juce::DirectoryContentsList::thread

private

◆ wasEmpty

bool juce::DirectoryContentsList::wasEmpty = true

private

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

juce_DirectoryContentsList.h

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DirectoryContentsList()

◆ ~DirectoryContentsList()

Member Function Documentation

◆ addChangeListener()

◆ addFile()

◆ callListeners()

◆ changed()

◆ checkNextFile()

◆ clear()

◆ contains()

◆ dispatchPendingMessages()

◆ getDirectory()

◆ getFile()

◆ getFileInfo()

◆ getFilter()

◆ getNumFiles()

◆ getTimeSliceThread()

◆ ignoresHiddenFiles()

◆ isFindingDirectories()

◆ isFindingFiles()

◆ isStillLoading()

◆ refresh()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

◆ setDirectory()

◆ setFileFilter()

◆ setIgnoresHiddenFiles()

◆ setTypeFlags()

◆ stopSearching()

◆ useTimeSlice()

Member Data Documentation

◆ anyListeners

◆ broadcastCallback

◆ changeListeners

◆ fileFilter

◆ fileFindHandle

◆ fileListLock

◆ files

◆ fileTypeFlags

◆ isSearching

◆ nextCallTime

◆ root

◆ shouldStop

◆ thread

◆ wasEmpty