Appendice C. Interfaccia QML

Gli script QML possono essere richiamati tramite il menu contestuale dell'elenco file e possono essere impostati nella scheda Azioni dell'utente della finestra delle impostazioni. Gli script impostati lì possono essere utilizzati come esempi per programmare script personalizzati. QML utilizza JavaScript ecco il «Ciao mondo» obbligatorio:

import Kid3 1.0

Kid3Script {
  onRun: {
    console.log("Ciao mondo, la cartella è", app.dirName)
    Qt.quit()
  }
}

Se questo script viene salvato come /percorso/a/Esempio.qml, il comando utente può essere definito come @qml/percorso/a/Esempio.qml con nome Test QML e Risultato selezionati. Può quindi essere avviato utilizzando l'elemento Test QML nel menu contestuale dell'elenco dei file e il risultato sarà visibile nella finestra.

Sfortunatamente, avviando gli script QML utilizzando qml (ad es. qml -apptype widget -I /usr/lib/kid3/plugins/imports /percorso/a/Esempio.qml) non funziona correttamente nelle versioni recenti di Qt. kid3-cli offre un modo alternativo per eseguire uno script QML dalla riga di comando utilizzando il suo comando execute.

kid3-cli -c "execute @qml /percorso/a/Esempio.qml"

Per elencare i titoli nei tag 2 di tutti i file nella cartella attuale, è possibile utilizzare il seguente script:

import Kid3 1.0

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

Se la cartella contiene molti file, uno script del genere potrebbe bloccare l'interfaccia utente per qualche tempo. Per operazioni più lunghe, dovrebbe quindi avere una pausa di tanto in tanto. L'implementazione alternativa di seguito ha il compito per un singolo file spostato in una funzione. Questa funzione si richiama alla fine con un timeout di 1 ms, dato che è necessario elaborare più file. Questo assicurerà che la GUI rimanga reattiva mentre lo script è in esecuzione.

import Kid3 1.0

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

    app.firstFile()
    doWork()
  }
}

Quando si utilizza app.firstFile() con app.nextFile(), saranno elaborati tutti i file della cartella attuale. Se sono interessati solo i file selezionati, utilizzare invece firstFile() e nextFile(), queste sono funzioni utili del componente Kid3Script. L'esempio seguente è uno script che copia solo il numero del disco e i frame del copyright del file selezionato.

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

Altri script di esempio sono forniti da Kid3 e sono già registrati come comandi dell'utente.