#ifndef FILESANDPATHS_H
#define FILESANDPATHS_H
#include <QString>
#include <QFile>
/** \brief A macro that makes it easy to import a file's contents into a variable
*
* The macro declares a static QString variable \a variableName and fills it (once only,
* the first time this code is encountered) with the contents of the file \a fileName.
*
* Example use:
* \code
* function exampleFunction ()
* {
* STRING_FILE_RESOURCE( myVar, "~/.profile" ) // note, no semicolon
* // do something with the data, such as:
* qDebug() << "Contents of .profile:" << myVar;
* }
* \endcode
*/
#define STRING_FILE_RESOURCE(variableName,fileName) \
static QString variableName; \
if ( variableName.isEmpty() ) { \
QFile f( fileName ); \
if ( f.open( QIODevice::ReadOnly ) ) \
variableName = QTextStream( &f ).readAll(); \
}
/** \brief The folder in which the application executable or bundle sits (OS-dependent)
*
* On Linux or Windows, this returns the path to the folder containing the application
* executable. On OS X, this returns the path to the folder containing the application
* bundle.
*/
QString applicationFolder ();
/** \brief The folder in which built-in font files are stored
*
* Built-in fonts include DejaVu, Chunk, and Symbola.
*
* During development, these fonts will be kept in a specific location in the Subversion
* repository, but during release, they will appear in an installed location. This function
* returns the path to those fonts by checking to see if they appear in the location they
* would if this were a developer's working copy of the repository, and if that fails, then
* where they would be if this were an installation of Lurch. The result is cached so that
* the check to the filesystem happens only once per run of the application.
*/
QString builtInFontsFolder ();
/** \brief The full paths to all built-in fonts
*
* This function uses builtInFontsFolder() to find the fonts, either in a developer's working
* copy or an installation. Then it searches that folder for all the font files mentioned
* in the documentation for builtInFontsFolder().
*
* This returns the list of fonts, which should be 23 true-type font files. If fewer than
* 23 are returned (usually zero in such a case) then some essential font files could not
* be found. Thus this routine can be used to get the fonts if they're available, or notice
* a problem if they're not.
*/
QStringList builtInFontFiles ();
/** \brief Install all built-in fonts into the running application, and return any error messages
*
* This calls QFontDatabase::addApplicationFont() for every font given by builtInFontFiles().
* Any failures or other errors will be reported by a nonempty return value from this
* function. If the return value from this function is an empty string, then no errors
* took place and the fonts were installed smoothly.
*/
QString installBuiltInFonts ();
/** \brief The default search path, added the first time the application is run
*
* The first time Lurch is run, if it does not have any settings, a default username
* is added as well as this search path as the only search path. It points to the location
* in which we place all the <code>.lurch</code> files that we bundle with the application.
*
* The return value will have been passed through QFileInfo::canonicalFilePath(), so that it
* can be compared string-wise with elements of the search paths as stored in the user's
* settings, which have also been passed through QFileInfo::canonicalFilePath() by
* LurchPathTracker.
*
* If the application is being run from a developer's working copy, the libraries folder
* nearest the application (e.g., trunk/libraries) is returned. If it is being run from
* an installation directory instead, the libraries folder in the installation is returned.
* This may return an empty string if the installation directory has been deleted, or the
* executable is in neither of those two places.
*/
QString defaultSearchPath ();
/** \brief The help subdirectory of defaultSearchPath(), where all built-in help documents
* are stored
*
* \see defaultSearchPath()
*/
QString defaultHelpSearchPath ();
/** \brief Whether the given file is on the given list
*
* The comparison is not done using string equality, but rather both are converted into
* QFileInfo objects and the operator==() comparison for that class is used. This does
* require that .canonicalFileName() has already been used to create the strings in the
* lists, however.
*/
bool fileOnList ( const QString& filename, const QStringList& filenames );
/** \brief A filename (complete with system-appropriate path) for where to store an autosave file
*
* The filename will be unique because it will be an encoding of the current date and time at
* which this function was called, down to milliseconds precision. It will be like the following
* example, except with a system-specific path preceding the filename.
*
* <code>Autosave on Fri June 11 2010 10:22:51:063.lurch</code>
*
* It uses QDateTime::toString() with the following format string, producing output like the
* above example.
*
* <code>ddd MMMM d yyyy hh:mm:ss:zzz</code>
*
* If the system-specific path in which the given filename sits did not exist before this
* function was called, this function creates it.
* In applications that do not use the QtGui module (e.g., unit tests), this does not use a
* system-specific temporary folder, but rather the folder in which the application
* (e.g., the test) is being run.
*/
QString autoSaveFilePath ();
/** \brief All auto-save files currently on disk
*
* Because the auto-save filenames returned from autoSaveFilePath() are user-specific, this will
* be a list of all files of the form "Autosave on *.lurch" in the folder in which that user's
* autosave files would reside. This function can be used on Lurch startup to check whether
* any such files remain from the last run of Lurch, which would indicate that the program
* terminated abnormally, and perhaps the user has data they would like to recover from these
* files.
*/
QStringList allAutoSaveFiles ();
/** \brief The path to a temporary storage folder
*
* In applications that use the QtGui module, this uses QDesktopServices to find the location
* of appropriate temporary storage for the platform on which Lurch is being run.
* In applications that do not use the QtGui module (e.g., unit tests), this yields the
* folder in which the application (e.g., the test) is being run.
*/
QString temporaryFolder ();
/** \brief The most recently used path when opening/saving a document
*
* This is stored so that the user has the expected experience of having the File > Open
* dialog (or File > Save as, etc.) return to the same folder as the user last had it in.
*
* On the first Launch of Lurch, this is QDir::homePath(), but ever after that, it is
* the last folder into which a document was saved or from which one was loaded, as tracked
* by setLastUsedPath(), which stores its value in the settings across app launches.
*
* \see setLastUsedPath()
*/
QString lastUsedPath ();
/** \brief Store the value of a path into the user's settings as the last save path
*
* For how this is used, see lastUsedPath(). It can be updated (and stored in settings)
* by calling this function.
*
* \see lastUsedPath()
*/
void setLastUsedPath ( QString newPath );
// PROFILE_START();
// ...
// PROFILE_STEP("did something");
// ...
// PROFILE_STEP("in loop at point" << i);
// ...
#define PROFILE_START QTime t = QTime::currentTime
#define PROFILE_STEP(x) qDebug() << x << t.msecsTo( QTime::currentTime() ) << "ms"; \
t = QTime::currentTime()
#endif // FILESANDPATHS_H