FileUtils

This read-only property returns the current list of paths getMultiPathUrl() uses to find a URL. The order of this list determines the search order: the path with index 0 is searched first, then index 1 and so on.

To modify the searchPaths list property use the function addSearchPath().

By default, the searchPaths contains the Documents directory

See also addSearchPath(), removeSearchPath(), and getMultiPathUrl().

Adds absoluteSearchPath to the searchPaths list property. The absoluteSearchPath must start with a "/" on Linux-based platforms and with C:\ or another valid drive letter on Windows. To receive the absolute path to one of the supported Storage Location directories, use storageLocation().

If no searchPathIndex is supplied, the absoluteSearchPath is appended to the end of the searchPaths property. This means it gets searched after all other searchPaths. You can define the order of the insertion by setting the searchPathIndex to anything between 0 and the size of the array.

See also getMultiPathUrl(), removeSearchPath(), and searchPaths.

Copy a file given by the source path to the destination path.

Both paths can either be absolute or relative to the DocumentsLocation.

This function is shorthand for reading the file's text contents with readFileBytes() and then writing back with writeFile().

Returns result

See also readFile(), writeFile(), listFiles(), and removeDir().

Returns the file name of the file at filePath.

This removes the directory from the path and keeps just the file name. If the optional parameter cropFileExtension is true, the file's extension is also removed.

Example usage:

 //returns "file.txt"
 var fileName = FileUtils.cropPathAndKeepFilename("/path/to/file/file.txt")

 //returns "file"
 var fileNameWithoutExtension = FileUtils.cropPathAndKeepFilename("/path/to/file/file.txt", true)

See also stripSchemeFromUrl(), getUrlByAddingSchemeToFilename(), and getAbsolutePathFromUrlString().

A default writable directory used for relative paths inside most FileUtils functions. This is the same as calling storageLocation(FileUtils.DocumentsLocation).

See also storageLocation().

Returns the base path of the QML engine. This is the file path to the initial QML file that loads your app or game.

See also engineBaseUrlPath() and qmlEngineBaseUrlForObject().

Returns the base path of the QML engine as a file://, assets:/ or qrc:/ URL. This is the file path to the initial QML file that loads your app or game.

See also engineBasePath().

Returns true if the file at filePath exists.

See also existsFileFromUrl(), existsFileWithoutAdoptions(), and findFileOrDirectoryIncludingResources().

Returns true if the file at fileUrl exists.

URLs with the file:// scheme are supported.

See also existsFile().

Returns true if the file at filePath exists.

See also existsFile().

Returns the absolute path to a file at filePath, if it exists.

filePath can either be an absolute path, or a path relative to the engineBasePath(). This works for both loading QML files from the file system and from QRC resources.

The return value is an absolute path if any file could be found. Otherwise it is an empty string.

Returns the absolute path to the directory of the file at filePath.

This removes the protocol scheme and the file name.

See also stripSchemeFromUrl(), getUrlByAddingSchemeToFilename(), and cropPathAndKeepFilename().

Returns the base path of the given sourceObject as string.

You can pass a QML object and retrieve the folder its QML file is located in. This can be used with getPathUrl() to load files located in the same folder as other QML files.

See also getPathUrl().

Returns a valid URL to a file using the searchPaths. This method looks up the file represented by fileUrl in each search path, in order.

If fileUrl is an absolute URL, the method looks up this absolute path first. If this file does not exist, it searches for the file name of the URL in the searchPaths.

If it is a relative URL, it appends it to each search path to check if that file exists. You can supply a contextObject, it looks up this object's getBasePath() as absolute path before the searchPaths. You can also omit contextObject, in this case it uses the engineBasePath() as context path.

If it finds any file this way, it returns a valid absolute URL to this file. If it can't find any file, in neither of the searchPaths and also not in the absolute provided location, it returns an empty URL.

You can call this function with DownloadableResource, which automatically registers its storagePath as search path. Thus you can use downloaded and extracted files with getMultiPathUrl().

The following example looks for an image called "testImage.png" in the app directory, i.e. in the same folder as the qml file. If it does not exist there, it searches in the Documents directory and in all searchPaths.

 import QtQuick
 import Felgo

 GameWindow {

   Scene {
     id: scene

     Image {
       // if found in the folder of this qml file then use the image from the FileUtils.ApplicationsLocation
       // if not found in the ApplicationsLocation, search for it in the DocumentsLocation and then in the searchPaths
       source: FileUtils.getMultiPathUrl("testImage.png", scene)
     }

   }
 }

See also addSearchPath(), removeSearchPath(), and searchPaths.

Returns the full URL to the path of source and the appended relative filePath.

source can either be a QML object or an absolute URL or file path. If source is an object, the path used is the absolute path to its QML file using getBasePath().

Following example displays an image located in the same folder as some other QML file:

 import QtQuick
 import Felgo

 import "subdirectory"

 GameWindow {

   Scene {
     id: scene

     // SomeObject.qml is located in another directory
     SomeObject {
       id: someObject
     }

     // someImage.png is in the same directory as SomeObject.qml
     Image {
       source: FileUtils.getPathUrl("someImage.png", someObject)
     }
   }
 }

If source is a URL or a string, the path used is source itself. You can retrieve absolute paths with storageLocation() or getMultiPathUrl().

When filePath is "first-image.png" and the source is "file://somePath/particles/second-image.png" it returns "file://somePath/particles/first-image.png".

Following example lists all files from the source folder of the initialValue (../assets/img/). Afterwards it adds the returned names to the source path of the initialValue. Now the file paths in the files array can be used by components in other QML files to load the images without using relative paths which would not work in other QML files.

 import QtQuick
 import Felgo

 GameWindow {

   Scene {
     id: scene

     property url initialValue: "../assets/img/stars.png"

     Component.onCompleted: {
       // list image files in the directory of the source image.
       var stringList = FileUtils.listFiles(initialValue, ["*.png"])
       // fire.png, water.png, ...

       // Create file list with all images
       var files = []
       for(var i = 0; i < stringList.length; i++){
         // get a path from the initialValue and adds the names of the image list
         // ../assets/img/fire.png, ../assets/img/water.png, ...
         var fileurl = FileUtils.getPathUrl(stringList[i], initialValue)
         files[i] = fileurl
       }
       console.debug(JSON.stringify(files))
     }
   }
 }

See also listFiles(), storageLocation(), getMultiPathUrl(), and getBasePath().

Returns the filePath as a file://, assets:/ or qrc:/ URL.

See also stripSchemeFromUrl(), stripSchemeFromUrl(), and cropPathAndKeepFilename().

Lists and returns files from a path depending on the nameFilter containing an array of strings. If no name filter was used all files are listed in the defined location.

The path contains the relative or absolute path. If path is relative, the files are listed in the DocumentsLocation directory.

The name filter may define which files should be listed. Following example lists all files with .json and .txt file ending. The files are listed from the directory of the current QML file.

To list all files in the Documents directory, use a relative path.

 import QtQuick
 import Felgo

 GameWindow {
   id: window

   Scene {
     id: scene

     Component.onCompleted: {
       // this will return ["config.json"], as a config.json file is placed in the same directory as the main.qml file
       var stringList = FileUtils.listFiles(Qt.resolvedUrl("."), ["*.json", "*.txt"])
       console.log("All .json and .txt files in app:\n" + stringList.join(", "))

       // this will return all files in the FileUtils.DocumentsLocation
       stringList = FileUtils.listFiles(".", ["*.json", "*.txt"])
       console.log("All .json and .txt files in documents:\n" + stringList.join(", "))
     }
   }
 }

For a more detailed example read Write, List, Read Files.

See also readFile() and writeFile().

Opens the file or directory fileName with an external application. This is the same as calling NativeUtils::openUrl() with a file:// URL.

The parameter fileName can be an absolute or relative file or directory path. In this case it creates the URL by calling getUrlByAddingSchemeToFilename(). It can also be of url type with the file:// protocol.

If fileName points to a directory, it opens the directory in the default file browser. If fileName points to a file, it opens the file with the default app associated with the file type, if one exists.

Use this example code to open a file called pdf-test.pdf from the app assets with the default PDF viewer. The PDF file is located relative to the current QML file:

 import Felgo
 import QtQuick

 App {
   id: app

   Component.onCompleted: {
     FileUtils.openFile(Qt.resolvedUrl("../assets/pdf-test.pdf"))
   }
 }

The following example uses DownloadableResource to download a PDF file to the user's documents directory. It then opens it with the default PDF viewer:

 import Felgo
 import QtQuick

 App {
   id: app

   DownloadableResource {
     source: "http://www.orimi.com/pdf-test.pdf"
     storageLocation: FileUtils.DocumentsLocation
     storageName: "pdf-test.pdf"
     extractAsPackage: false

     Component.onCompleted: {
       if(status === DownloadableResource.UnAvailable) {
         download()
       } else {
         openDownloadedFile()
       }
     }

     onStatusChanged: openDownloadedFile()

     function openDownloadedFile() {
       if(status === DownloadableResource.Available) {
         FileUtils.openFile(storagePath)
       }
     }
   }
 }

This method returns true if the file was opened successfully. It returns false if the platform cannot open this file type or directory.

Returns the base path of the object's QML engine. This is the QML file path to the root of object's QML tree.

If object is in the same QML context as the current QML file, this is the same as engineBasePath().

See also engineBasePath().

Reads a text file from fileName and returns the content of the file as string. If no file was found or an error occurred, it returns an empty string.

The fileName parameter contains the name with extension and its relative or absolute path. If the path is relative, the file is read relative to the DocumentsLocation directory.

Following code reads a file from a subfolder in the application directory. It then reads a file from a subfolder of the Documents directory:

 import QtQuick
 import Felgo

 GameWindow {
   id: window

   Scene {
     id: scene

     // URL property is relative to this QML file
     property url configFile: "subfolder/file.json"

     Component.onCompleted: {
       var relativeData = FileUtils.readFile(configFile)
       // alternatively you can also call it directly, but you need Qt.resolvedUrl()
       // var data = FileUtils.readFile(Qt.resolvedUrl("subfolder/file.json"))
       console.log(relativeData)

       // this file name is relative to FileUtils.Documents
       var documentsData = FileUtils.readFile("subfolder/file.json")
       console.log(documentsData)
     }
   }
 }

The default path of the Documents directory depends on the target platform. See Storage Location for more information.

For a more detailed example see the section Write, List, Read Files.

See also readFileBytes(), readFileBase64(), writeFile(), copyFile(), listFiles(), and removeDir().

Reads a binary file from fileName and returns the content of the file as a base64 encoded string. If no file was found or an error occurred, it returns an empty string.

The fileName parameter contains the name with extension and its relative or absolute path. If the path is relative, the file is read relative to the DocumentsLocation directory.

The default path of the Documents directory depends on the target platform. See Storage Location for more information.

For additional information see the section Write, List, Read Files.

The following example reads an image file in Base64 encoding and passes the data to AppImage for display. This is only for demonstration purposes. In an actual project you would e.g. upload the Base64 data to a backend or run other custom processing.

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Base64 Example"

       Column {
         anchors {
           left: parent.left
           right: parent.right
           margins: dp(30)
         }

         AppImage {
           id: img
           width: parent.width
           height: width
           fillMode: Image.PreserveAspectFit
           anchors.horizontalCenter: parent.horizontalCenter
         }

         AppButton {
           text: "Read Base64"
           anchors.horizontalCenter: parent.horizontalCenter
           onClicked: {
             let fileLocation = FileUtils.storageLocation(FileUtils.DocumentsLocation, "felgo-logo.png")
             let dataBase64 = FileUtils.readFileBase64(fileLocation)
             img.source = "data:image/png;base64," + dataBase64
           }
         }
       }
     }
   }
 }

This method was introduced in Felgo 4.2.0.

See also readFile(), writeFile(), copyFile(), listFiles(), and removeDir().

Reads a binary file from fileName and returns the content of the file as byte buffer. If no file was found or an error occurred, it returns an empty buffer.

The fileName parameter contains the name with extension and its relative or absolute path. If the path is relative, the file is read relative to the DocumentsLocation directory.

Following code reads a file from a subfolder in the application directory. It then reads a file from a subfolder of the Documents directory:

 import QtQuick
 import Felgo

 GameWindow {
   id: window

   Scene {
     id: scene

     // URL property is relative to this QML file
     property url imageFile: "subfolder/file.jpeg"

     Component.onCompleted: {
       var relativeData = FileUtils.readFileBytes(configFile)
       // alternatively you can also call it directly, but you need Qt.resolvedUrl()
       // var data = FileUtils.readFileBytes(Qt.resolvedUrl("subfolder/file.jpeg"))
       console.log("Image file size: " + relativeData.byteLength)

       // this file name is relative to FileUtils.Documents
       var documentsData = FileUtils.readFile("subfolder/file.jpeg")
       console.log("Image file size: " + documentsData.byteLength)
     }
   }
 }

The default path of the Documents directory depends on the target platform. See Storage Location for more information.

For a more detailed example see the section Write, List, Read Files.

This method was introduced in Felgo 3.7.1.

See also readFile(), writeFile(), copyFile(), listFiles(), and removeDir().

Removes the directory at dirName recursively with all contained files and sub-directories.

dirName can be an absolute path or a path relative to DocumentsLocation.

Returns true if the directory was removed successfully or if it did not exist before calling the method. Returns false if an existing directory could not be removed.

See also removeFile(), readFile(), writeFile(), listFiles(), and copyFile().

Removes the file at fileName.

fileName can be an absolute path or a path relative to DocumentsLocation.

Returns true if the file was removed successfully or if it did not exist before calling the method. Returns false if an existing file could not be removed.

This method was introduced in Felgo 3.7.1.

See also removeDir(), readFile(), writeFile(), listFiles(), and copyFile().

Removes the search path absoluteSearchPath from the searchPaths property. All occurrences of the path are removed.

See also getMultiPathUrl(), addSearchPath(), and searchPaths.

Writes image to a file at fileName. Returns true if the image was written or false otherwise.

The fileName contains the name with extension and its relative or absolute path. If fileName is relative, the file is written relative to the DocumentsLocation directory.

The image must be of type QImage. To save an image from binary data, use writeFile().

An example usecase is to save the result from Item::grabToImage() with a custom quality:

 Rectangle {
   id: source
   width: 100
   height: 100
   gradient: Gradient {
       GradientStop { position: 0; color: "steelblue" }
       GradientStop { position: 1; color: "black" }
   }
 }

Then call:

 source.grabToImage(function(result) {
   // result.saveToFile("something.jpg"); --> This would compress with a default quality of about 75
   FileUtils.saveImage("something.jpg", result.image, 100); // Uses quality 100
 });

The quality parameter is optional. If provided it must be a value between 0 and 100. If no quality is provided, a platform and format dependent default quality is used.

To write a file to one of the Storage Locations, use storageLocation() for the fileName.

The default path of the Documents directory depends on the target platform. See Storage Location for more information.

See also writeFile().

Returns a writable file path for the specified location represented by one of the Storage Location enum constants using QStandardPaths::writableLocation(). The supported locations depend on the platform. Some might not be available on each platform. The function storageLocation() will then return an empty path.

The optional parameter path is a relative path appended to the storage location. You can also omit path, then the function returns the absolute path to the storage location itself.

For example, you can display an image stored in <Download directory>/_packages/myPackage/myImage.png:

 Image {
   source: FileUtils.storageLocation(FileUtils.DownloadLocation, "_packages/myPackage/myImage.png")
 }

This function ensures that the requested directory exists. If it does not exist it is created automatically. If the directory cannot be created, an empty string is returned.

See also defaultWritablePath().

Returns a textual representation for the specified location represented by one of the Storage Location enum constants using QStandardPaths::displayName().

Returns the fileUrl without the protocol scheme.

The parameter fileUrl can either be of string or URL type.

See also getUrlByAddingSchemeToFilename(), stripSchemeFromUrl(), and cropPathAndKeepFilename().

Writes fileData to a file at fileName. Returns true if the file could be written or false otherwise.

The fileName contains the name with extension and its relative or absolute path. If fileName is relative, the file is written relative to the DocumentsLocation directory.

The fileData can either be a string or a byte buffer. You can thus use any text or binary data. For example, you can use data you previously obtained with readFileBytes().

To write a file to one of the Storage Locations, use storageLocation() for the fileName.

Following code writes a file with a relative path to the Documents directory:

 var success = FileUtils.writeFile("TextFiles/myFile.txt", "test text")

Following code writes a file without a given sub-path directly to the Documents directory:

 var success = FileUtils.writeFile("myFile.txt", "test text")

Following code writes a file without a given sub-path to the Downloads directory:

 var fileName = FileUtils.storageLocation(FileUtils.DownloadLocation, "myFile.txt")
 var success = FileUtils.writeFile(fileName, "test text")

The default path of the Documents directory depends on the target platform. See Storage Location for more information.

For a more detailed example see the section Write, List, Read Files.

See also readFile(), copyFile(), listFiles(), and removeDir().