sailfish-components/FileIO/docs/FileIO.md

# FileIO

## General

A QML-Plugin which provides basic file operations.

## Including FileIO in Your Project

First copy the FileIO-directory into your project path somewhere:

    my-project
    |--my-project.pro
    |--src
       |--FileIO
       |  |--src
       |  |--FileIO.pri
       |--my-project.cpp
       
Next include FileIO.pri into my-project.pro:

    TARGET = my-project

    CONFIG += sailfishapp

    SOURCES += src/my-project.cpp

    .
    .
    .
    
    include (src/FileIO/FileIO.pri)
    
Now you can include the header in your main cpp and register the component:

    #include <QtQuick>
    #include <sailfishapp.h>
    #include <QGuiApplication>
    #include "fileio.h"
   
    int main(int argc, char *argv[])
    {
      // Get App and QML-View objects
      QScopedPointer<QGuiApplication> app(SailfishApp::application(argc, argv));
      QScopedPointer<QQuickView> view(SailfishApp::createView());

      // Register FileIO Class
      qmlRegisterType<FileIO, 1>("harbour.my-project.FileIO", 1, 0, "FileIO");

      // Prepare the QML and set Homedir
      view->setSource(SailfishApp::pathTo("qml/my-project.qml"));
      view->show();

      // Run the app
      return app->exec();
    }

Now you can use the FileIO Object in your QML

## Using the QML Object

Here are some short examples:

### Reading Files

    import harbour.my-project.FileIO 1.0
  
    FileIO {
      id: myFile
      source: "/home/nemo/some-file.txt"
      onError: { console.log(msg); }
    }

    var content = myFile.read()

First the FileIO-Plugin is imported in the QML file. Now a FileIO object with the ID myFile is created. The property **source** holds the filename of the file to read or write. The signal **onError** is called when something goes wrong, **msg** contains the error message.

After declaring the object the method **read()** is used, it retuns the contenst of the file as a string.

### Writing files

    import harbour.my-project.FileIO 1.0
    
    FileIO {
      id: myFile
      source: "/home/nemo/some-file.txt"
      onError: { console.log(msg); }
    }

    myFile.write("Hello World")
    
The declaration stays the same as for reading files.

For writing the method **write("content")** is called. This mehtod will write the passed string to the file defined in **source**. The content of the file will be replaced with the content passed to the method.

### Checking if a File Exists

    import harbour.my-project.FileIO 1.0
    
    FileIO { id: fileIO }
   
    if (fileIO.exists("/home/nemo/myfile.txt")) {
      console.log("file exists");
    } else {
      console.log("file does not exists");
    }
    
The method **exists(file)** gets passed the path of the file or directory to check. If the file or directory exists the method will return **true**, otherwise it will return **false**

The method **exists()** can also be called without a parameter, in this case it will check if the file defined in **source** exists.


### Creating Directories

    import harbour.my-project.FileIO 1.0

    FileIO { id: fileIO }
    
    fileIO.mkpath("/tmp/directory");
    
The method **mkpath(directory)** will create the given directory, if it does not exist already. The method will return **true** if the directory exists or was successfully created, otherwise it will return **false**