Appendix C. QML Interface

QML scripts can be invoked via the context menu of the file list and can be set in the tab User Actions of the settings dialog. The scripts which are set there can be used as examples to program custom scripts. QML uses JavaScript, here is the obligatory "Hello World":

import Kid3 1.0

Kid3Script {
  onRun: {
    console.log("Hello world, folder is", app.dirName)
    Qt.quit()
  }
}

If this script is saved as /path/to/Example.qml, the user command can be defined as @qml /path/to/Example.qml with name QML Test and Output checked. It can then be started using the QML Test item in the file list context menu, and the output will be visible in the window.

Unfortunately, starting the QML scripts using the qml (e.g. qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml) is broken in recent versions of Qt. But kid3-cli offers an alternative way to run a QML script from the command line using its execute command.

kid3-cli -c "execute @qml /path/to/Example.qml"

To list the titles in the tags 2 of all files in the current folder, the following script could be used:

import Kid3 1.0

Kid3Script {
  onRun: {
    app.firstFile()
    do {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        console.log(app.getFrame(tagv2, "title"))
      }
    } while (app.nextFile())
  }
}

If the folder contains many files, such a script might block the user interface for some time. For longer operations, it should therefore have a break from time to time. The alternative implementation below has the work for a single file moved out into a function. This function invokes itself with a timeout of 1 ms at the end, given that more files have to be processed. This will ensure that the GUI remains responsive while the script is running.

import Kid3 1.0

Kid3Script {
  onRun: {
    function doWork() {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        console.log(app.getFrame(tagv2, "title"))
      }
      if (!app.nextFile()) {
        Qt.quit()
      } else {
        setTimeout(doWork, 1)
      }
    }

    app.firstFile()
    doWork()
  }
}

When using app.firstFile() with app.nextFile(), all files of the current folder will be processed. If only the selected files shall be affected, use firstFile() and nextFile() instead, these are convenience functions of the Kid3Script component. The following example is a script which copies only the disc number and copyright frames of the selected file.

import Kid3 1.1

Kid3Script {
  onRun: {
    function doWork() {
      if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) {
        app.setFrame(tagv2, "*.selected", false)
        app.setFrame(tagv2, "discnumber.selected", true)
        app.setFrame(tagv2, "copyright.selected", true)
        app.copyTags(tagv2)
      }
      if (!nextFile()) {
        Qt.quit()
      } else {
        setTimeout(doWork, 1)
      }
    }

    firstFile()
    doWork()
  }
}

More example scripts come with Kid3 and are already registered as user commands.