API QML

L'API può essere facilmente esplorata utilizzando la console QML, disponibile come script di esempio con un'interfaccia utente.

Kid3Script

Kid3Script è un normale componente QML situato nella cartella delle estensioni. È possibile utilizzare anche un altro componente QML. L'uso di Kid3Script semplifica l'avvio della funzione di script utilizzando il gestore di segnali onRun. Inoltre offre alcune funzioni:

onRun: gestore dei segnali che è invocato quando lo script è avviato
tagv1, tagv2, tagv2v1: costanti per i parametri dei tag
script: accesso alle funzioni di scripting
configs: accesso agli oggetti di configurazione
getArguments(): elenco degli argomenti degli script
isStandalone(): vero se lo script non era stato avviato dall'interno di Kid3
setTimeout(callback, ritardo): avvia callback dopo ms di ritardo
firstFile(): al primo file selezionato
nextFile(): al successivo file selezionato

Funzioni per creare script

Come JavaScript e quindi anche QML ha solo un insieme limitato di funzioni per gli script, l'oggetto script ha alcuni metodi aggiuntivi, ad esempio:

script.properties (oggetto): stringa con proprietà Qt
script.writeFile (percorsoFile, dati): scrivere i dati nel file, vero se OK
script.readFile (percorsoFile): leggere i dati dal file
script.removeFile (percorsoFile): eliminare il file, vero se OK
script.fileExists (percorsoFile): vero se il file esiste
script.fileIsWritable (percorsoFile): vero se il file è scrivibile
script.getFilePermissions (percorsoFile): ottenere bit dei permessi del file
script.setFilePermissions (percorsoFile, bitModalità): impostare i bit dei permessi del file
script.classifyFile (percorsoFile): ottenere la classe del file (cartella "/", collegamento simbolico "@", exe "*",
  file " ")
script.renameFile (vecchioNome, nuovoNome): rinominare il file, vero se OK
script.copyFile (origine, destinazione): copiare il file, vero se OK
script.makeDir (percorso): creare la cartella, vero se OK
script.removeDir (percorso): rimuovere la cartella, vero se OK
script.tempPath (): percorso della cartella temporanea
script.musicPath (): percorso della cartella musicale
script.listDir (percorso, [filtriNome], [classificare]): elencare le voci della cartella
script.system (programma, [arg], [msec]): avviare un comando di sistema in modo sincrono,
  [codice di uscita, standard output, standard error] se non scade il tempo limite
script.systemAsync (programma, [arg], [callback]): avviare un comando di sistema in modo comando
asincrono, la callback sarà invocata con [codice di uscita, standard output, standard
error]
script.getEnv (nomeVar): ottenere il valore della variabile d'ambiente
script.setEnv (nomeVar, valore): impostare il valore della variabile d'ambiente
script.getQtVersion (): stringa versione Qt, ad es. "5.4.1"
script.getDataMd5 (dati): ottenere la stringa esadecimale dell'hash MD5 dei dati
script.getDataSize (dati): ottenere la dimensione dell'array di byte
script.dataToImage (dati, [formato]): creare un'immagine da byte di dati
script.dataFromImage (img, [formato]): ottenere byte di dati dall'immagine
script.loadImage (percorsoFile): caricare un'immagine da un file
script.saveImage (img, percorsoFile, [formato]): salvare un'immagine in un file, vero se OK
script.imageProperties (img): ottenere le proprietà di un'immagine, una mappa contenente
  "larghezza", "altezza", "profondità" e "colorCount", vuoto se l'immagini non è valida
script.scaleImage (img, larghezza, [altezza]): ridimensionare un'immagine, restituisce un'immagine ridimensionata

Contesto dell'applicazione

Utilizzando QML, gran parte delle funzioni di Kid3 sono accessibili. L'API è simile a quella utilizzata per D-Bus. Per i dettagli, consultare le rispettive note.

app.openDirectory(percorso): aprire una cartella
app.unloadAllTags(): scaricare tutti i tag
app.saveDirectory(): salvare una cartella
app.revertFileModifications(): ripristinare
app.importTags(tag, percorso, fmtIdx): importare i file
app.importFromTags(tag, origine, estrazione): importare dai tag
app.importFromTagsToSelection(tag, origine, estrazione): importare dai tag dei file selezionati
app.downloadImage(url, allFilesInDir): scaricare un'immagine
app.exportTags(tag, percorso, fmtIdx): esportare i file
app.writePlaylist(): scaricare una scaletta
app.getPlaylistItems(percorso): ottenere gli elementi di una scaletta
app.setPlaylistItems(percorso, elementi): impostare gli elementi id una scaletta
app.selectAllFiles(): selezionare tutto
app.deselectAllFiles(): deselezionare
app.firstFile([selezione], [soloFileConTag]): al primo file
app.nextFile([selezione], [soloFileConTag]): al file successivo
app.previousFile([selezione], [soloFileConTag]): al file precedente
app.selectCurrentFile([selezione]): selezionare un file attuale
app.selectFile(path, [selezione]): selezionare un file specifico
app.getSelectedFilePaths([soloFileConTag]): ottenere i percorsi dei file selezionati
app.requestExpandFileList(): espandere tutto
app.applyFilenameFormat(): applicare il formato ai nomi dei file
app.applyTagFormat(): applicare il formato al tag
app.applyTextEncoding(): applicare la codifica del testo
app.numberTracks(nr, totale, tag, [opzioni]): Numerare le tracce
app.applyFilter(espressione): filtro
app.convertToId3v23(): convertire ID3v2.4.0 in ID3v2.3.0
app.convertToId3v24(): convertire ID3v2.3.0 in ID3v2.4.0
app.getFilenameFromTags(tag): nomi dei file dai tag
app.getTagsFromFilename(tag): nomi dei file ai tag
app.getAllFrames(tag): ottenere oggetti con tutti i frame
app.getFrame(tag, nome): ottenere un frame
app.setFrame(tag, nome, valore): impostare un frame
app.getPictureData(): ottenere i dati da un frame di immagine
app.setPictureData(dati): impostare i dati in un frame di immagine
app.copyToOtherTag(tag): tag ad altri tag
app.copyTags(tag): copiare
app.pasteTags(tag): incollare
app.removeTags(tag): Rimuovere
app.playAudio(): Riprodurre
app.readConfig(): Leggere la configurazione
app.applyChangedConfiguration(): Applicare la configurazione
app.dirName: Nome della cartella
app.selectionInfo.fileName: Nome del file
app.selectionInfo.filePath: Percorso assoluto del file
app.selectionInfo.detailInfo: Dettagli di formato
app.selectionInfo.tag(Frame.Tag_1).tagFormat: Formato tag 1
app.selectionInfo.tag(Frame.Tag_2).tagFormat: Formato tag 2
app.selectionInfo.formatString(tag, formato): Sostituire i codici nella stringa di formato
app.selectFileName(titolo, cartella, filtro, saveFile): Aprire la finestra per
selezionare un file
app.selectDirName(titolo, cartella): Aprire la finestra per selezionare una cartella

Per operazioni asincrone, le callback possono essere collegate ai segnali.

function automaticImport(profile) {
  function onAutomaticImportFinished() {
    app.batchImporter.finished.disconnect(onAutomaticImportFinished)
  }
  app.batchImporter.finished.connect(onAutomaticImportFinished)
  app.batchImport(profile, tagv2)
}

function renameDirectory(format) {
  function onRenameActionsScheduled() {
    app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
    app.performRenameActions()
  }
  app.renameActionsScheduled.connect(onRenameActionsScheduled)
  app.renameDirectory(tagv2v1, format, false)
}

Oggetti di configurazione

Le diverse sezioni di configurazione sono accessibili tramite i metodi di configs. Le loro proprietà possono essere elencate nella console QML.

script.properties (configs.networkConfig())

È possibile impostare le proprietà:

configs.networkConfig().useProxy = false

configs.batchImportConfig()
configs.exportConfig()
configs.fileConfig()
configs.filenameFormatConfig()
configs.filterConfig()
configs.findReplaceConfig()
configs.guiConfig()
configs.importConfig()
configs.mainWindowConfig()
configs.networkConfig()
configs.numberTracksConfig()
configs.playlistConfig()
configs.renDirConfig()
configs.tagConfig()
configs.tagFormatConfig()
configs.userActionsConfig()