Apèndix C. Interfície QML

Els scripts QML es poden invocar a través del menú contextual de la llista de fitxers i es poden configurar a la pestanya Accions de l'usuari del diàleg de configuració. Els scripts que s'estableixen allà es poden emprar com a exemples per a programar scripts personalitzats. El QML fa servir JavaScript, aquí teniu l'obligatori «Hola món»:

import Kid3 1.0

Kid3Script {
  onRun: {
    console.log("Hola món, la carpeta és", app.dirName)
    Qt.quit()
  }
}

Si aquest script es desa com /camí/a/Exemple.qml, l'ordre d'usuari es pot definir com a @qml /camí/a/Exemple.qml amb el nom Prova de QML i Sortida marcades. Després es podrà iniciar emprant l'element Prova de QML al menú contextual de la llista de fitxers, i la sortida serà visible a la finestra.

Malauradament, iniciar els scripts en QML emprant qml (p. ex., qml -apptype widget -I /usr/lib/kid3/plugins/imports /camí/a/Exemple.qml) està trencat en les versions recents de les Qt. Però el kid3-cli ofereix una forma alternativa d'executar un script en QML des de la línia d'ordres utilitzant la seva ordre execute.

kid3-cli -c "execute @qml /camí/a/Exemple.qml"

Per a llistar els títols a les etiquetes 2 de tots els fitxers en la carpeta actual, es podria emprar el següent script:

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

Si la carpeta conté molts fitxers, aquest script podria bloquejar la interfície d'usuari durant algun temps. Per a operacions més llargues, aquest hauria de disposar d'un descans de tant en tant. La següent implementació alternativa té la feina per a un sol fitxer mogut a una funció. Aquesta funció s'invoca amb un temps d'espera d'1 ms al final, atès que s'han de processar més fitxers. Això assegurarà que la IGU segueixi responent mentre s'executa l'script.

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

En emprar app.firstFile() amb app.nextFile(), es processaran tots els fitxers de la carpeta actual. Si només es veuen afectats els fitxers seleccionats, utilitzeu firstFile() i NextFile() en el seu lloc, aquestes són funcions convenients del component Kid3Script. El següent exemple és un script que només copia els marcs de número del disc i drets d'autor del fitxer seleccionat.

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

Amb el Kid3 venen més scripts d'exemple i ja estan registrats com a ordres d'usuari.