Tutorials

tutorial 06: main files drop list

Welcome to this tutorial on working with the main file drop list. The main file drop list is the primary user interaction in magnetron.app

In this tutorial you will learn to:

  • Add and remove files from the file list
  • Set the file message and tooltip
  • Set the file icon and color
  • Get and set the file group index

To set up a testing environment, add some files to the app's file list by opening the 'App' popup menu and selecting 'Add file(s)'. Then click on the 'App' tab in the bottom half of the magnetron.dev editor window.

Use a previous tutorial to create a base for this one. And remove the main() function content if any. First, let's get the current file objects using the getFiles() function.

var files = getFiles();

The resulting array contains objects with the file path and index. You can print the contents of the current list using echo(objectToString(getFiles())), which will produce a result like this in the console:

[
    {
        "idpath": "C:\\file.txt:0",
        "path": "C:\\file.txt",
        "index": 0
    },
    {
        "idpath": "C:\\file.txt:1",
        "path": "C:\\file.txt",
        "index": 1
    },
    {
        "idpath": "C:\\other_file.txt:0",
        "path": "C:\\other_file.txt",
        "index": 0
    }
]

Note that the index value is used to differentiate between duplicate files, while the index of the list itself reflects the file order set by the user. These indexes can be useful for specific recipes that use multiple files.

Properties

Next, let's create a function called SetProperties() which we will call from the main function. Within this function, we will request the files object with all file list data using getFiles(). Then, we will iterate through all items in the list using a for loop.

function SetProperties()
{
    var files = getFiles();
    for (i=0;i<files.length;i++)
    {
    }
}

Within the loop, we will add three examples to change the properties of the existing files in the list. First, we will request more information about the file path using getPathInfo(files[i]["path"]) and merge the resulting object with the original file object using mergeObject(infoObject, files[i]).

Then, we will get the size of the file in bytes using getFileBytes(files[i]) and add it as a custom value to the file object using files[i]["bytes"] = getFileBytes(files[i]). To remove this value, we can use the removeProperty() function.

var infoObject = getPathInfo(files[i]["path"]);

files[i] = mergeObject(infoObject, files[i]);

files[i]["bytes"] = getFileBytes(files[i]);

files[i] = removeProperty(files[i], "bytes");

You can also directly manipulate the file properties without getting the full list, but you will still need the path and index of each file. Use the getFileProperty(files[i].path, "mykeyvalue"), setFileProperty(files[i].path, "mykeyvalue", "mytestvalue"), and removeFileProperty(files[i].path, "mykeyvalue") functions to do this.

Group

The group index is part of the interaction with the file list and acts as an indication for the user. The user can drop files on top of each other to group them, but this number can also be added or changed from the recipe itself. To set the group numbers, use the setFileProperty() function to set the "group" property to a group index value like so: setFileProperty(files[i].path, "group", 1). This might be useful depending on your recipe.

Update

Now, let's update the file list with the modified file objects using the setFiles() function.

setFiles(files);

You can also add files or change the complete file list by adding a new object with a valid path value (and optional index) to an existing file list. For example:

function AddFile()
{
    var files = getFiles();
    var filepath = openFileDialog("select a file", folders.temp, "*.txt");
    files.push({ "path": filepath, "index" : 0 });
    setFiles(files);
}

Call this function from your 'main' function to test it.

Finally, note these convenience functions for setting file property values for the file list interaction:

  • "file_status" -> setFileStatus(path, index, "text")
  • "file_tooltip" -> setFileTooltip(path, index, "text")
  • "file_icon" -> setFileIcon(path, index, "CheckCircleO")
  • "file_iconcolor" -> setFileIconColor(path, index, "FF3aac4d")

Check out more details about each function here /syntax/filelist/.

That concludes this tutorial on working with the main file drop list in magnetron.app. With these techniques, you should now be able to add, remove, and modify files in the list as well as set various properties and colors.

Here is a complete source example:

function main()
{
    SetProperties();
    AddFile();
}

function SetProperties()
{
    var files = getFiles();
    for (i=0;i<files.length;i++)
    {
        var infoObject = getPathInfo(files[i]["path"]);
        files[i] = mergeObject(infoObject, files[i]);
        files[i]["bytes"] = getFileBytes(files[i]);
        files[i] = removeProperty(files[i], "bytes");
        setFileProperty(files[i].path, "mykeyvalue", "mytestvalue");
        echo(getFileProperty(files[i].path, "mykeyvalue"));
        removeFileProperty(files[i].path, "mykeyvalue");
        setFileProperty(files[i].path, "group", 1);
    }

    setFiles(files);
}


function AddFile()
{
    var files = getFiles();
    var filepath = openFileDialog("select a file", folders.temp, "*.txt");
    files.push({ "path": filepath, "index" : 0 });
    setFiles(files);
}