Anhang C. QML Schnittstelle

QML Skripte lassen sich über das Kontextmenü der Dateiliste aufrufen und in den Einstellungen auf der Seite Benutzerbefehle setzen. Die dortigen Beispielskripte bieten eine Vorlage für die Programmierung eigener Skripte. Codiert wird in JavaScript, hier das obligate "Hello World":

import Kid3 1.0

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

Wird dieses Skript unter /path/to/Example.qml abgespeichert, so kann als Benutzerbefehl @qml /path/to/Example.qml definiert werden. Wenn als Name QML Test gesetzt und Ausgabe aktiviert wird, so lässt sich das Skript über den Kontextmenüpunkt QML Test der Dateiliste starten, und die Ausgabe ist im Fenster sichtbar.

Leider lassen sich mit neueren Qt-Versionen QML-Skripte nicht mehr mit dem Programm qml starten (z.B. qml -apptype widget -I /usr/lib/kid3/plugins/imports /pfad/zu/Example.qml). Aber kid3-cli bietet mit execute eine Alternative an, um QML-Skripte von der Kommandozeile aus zu starten.

kid3-cli -c "execute @qml /pfad/zu/Example.qml"

Um die Titel im Tag 2 aller Dateien des aktuellen Ordners aufzulisten, könnte folgendes Skript verwendet werden:

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())
  }
}

Wenn sich viele Dateien im Ordner befinden, blockiert ein solches Skript die Benutzeroberfläche für einige Zeit. Für längere Aktionen sollte man daher kurze Pausen einlegen. Die unten stehende Alternative lagert die Arbeit an einer einzelnen Datei in eine Funktion aus. Diese ruft sich am Ende mit einem Timeout von 1 ms wieder selbst auf, sofern noch weitere Dateien zu bearbeiten sind. Dadurch bleibt das GUI auch während dem Ablauf des Skripts benutzbar.

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()
  }
}

Mit app.firstFile() und app.nextFile() werden alle Dateien des aktuellen Ordners bearbeitet. Falls es nur die ausgewählten Dateien sein sollen, so sollten stattdessen firstFile() und nextFile() verwendet werden, diese Funktionen sind in der Komponente Kid3Script enthalten. Das folgende Beispiel kopiert bloß die CD-Nummer- und Copyright-Frames der ausgewählten Datei.

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()
  }
}

Weitere Beispiele sind bei Kid3 dabei und bereits bei den Benutzerbefehlen eingetragen.