API de QML

L'API es pot explorar amb facilitat utilitzant la consola QML, la qual està disponible com un script d'exemple amb una interfície d'usuari.

Kid3Script

El Kid3Script és un component QML regular ubicat a dins de la carpeta del connector. També podria emprar un altre connector QML. L'ús del Kid3Script facilita l'inici de la funció de script utilitzant el controlador del senyal onRun. A més ofereix algunes funcions:

onRun: controlador del senyal que s'invoca quan s'inicia l'script
tagv1, tagv2, tagv2v1: constants per als paràmetres d'etiqueta
script: accés a les funcions per a la creació de scripts
configs: accés als objectes de la configuració
getArguments(): llista d'arguments de l'script
isStandalone(): cert si l'script no es va iniciar des del Kid3
setTimeout (crida de retorn, retard): inicia la crida de retorn després del retard en ms
firstFile(): al primer fitxer seleccionat
NextFile(): al següent fitxer seleccionat

Funcions de creació de scripts

Com al JavaScript, el QML també té només un conjunt limitat de funcions per a la creació de scripts, l'objecte script té alguns mètodes addicionals, per exemple:

script.properties(obj): cadena amb les propietats de les Qt
script.writeFile(filePath, dades): escriu les dades al fitxer, cert si va bé
script.readFile(filePath): llegeix les dades del fitxer
script.removeFile(filePath): elimina un fitxer, cert si va bé
script.fileExists(filePath): cert si el fitxer existeix
script.fileIsWritable(filePath): cert si el fitxer és d'escriptura
script.getFilePermissions(filePath): obté els bits per al mode de permís del fitxer
script.setFilePermissions(filePath, modeBits): estableix els bits per al mode de permís del fitxer
script.classifyFile(filePath): obté la classe de fitxer (carpeta «/», enllaç simbòlic «@», executable «*», fitxer «»)
script.renameFile(oldname, NEWNAME): canvia el nom del fitxer, cert si va bé
script.copyFile(font, dest): copia un fitxer, cert si va bé
script.makeDir(camí): crea una carpeta, cert si va bé
script.removeDir(camí): elimina una carpeta, cert si va bé
script.tempPath(): camí de la carpeta temporal
script.musicPath(): camí de la carpeta de música
script.listDir(camí, [nameFilters], [classify]): llista les entrades de la carpeta
script.system(programa, [args], [msecs]): inicia de mode sincrònic una ordre del sistema, [codi de sortida, sortida estàndard, error estàndard] si no és temps d'espera
script.systemAsync(programa, [args], [callback]): inicia una ordre del sistema en el mode asíncron, la crida de retorn es cridarà amb [codi de sortida, sortida estàndard, error estàndard]
script.getEnv(varname): obté el valor de la variable d'entorn
script.setEnv(varname, valor): estableix el valor a partir de la variable d'entorn
script.getQtVersion(): cadena de versió de les Qt, p. ex., «5.4.1»
script.getDataMd5(dades): obté una cadena hexadecimal per a la suma MD5 de les dades
script.getDataSize(data): obté la mida de la matriu de bytes
script.dataToImage(dades, [format]): crea una imatge a partir dels bytes de les dades
script.dataFromImage(imatge, [format]): obté els bytes de les dades de la imatge
script.loadImage(filePath): carrega una imatge des d'un fitxer
script.saveImage(imatge, filePath, [format]): desa una imatge en un fitxer, cert si va bé
script.imageProperties(imatge): obté les propietats d'una imatge, un mapa que contindrà  «amplada», «alçada», «profunditat» i «colorCount», buit si la imatge no és vàlida
script.scaleImage(imatge, amplada, [alt]): escala una imatge, retornarà una imatge escalada

Context de l'aplicació

Emprant QML, es pot accedir a una gran part de les funcions del Kid3. L'API és similar a la utilitzada per al D-Bus. Per a més detalls, consulteu les respectives notes.

app.openDirectory(camí): obre la carpeta
app.unloadAllTags(): descarrega totes les etiquetes
app.saveDirectory(): desa la carpeta
app.revertFileModifications(): reverteix
app.importTags(etiqueta, camí, fmtIdx): importa el fitxer
app.importFromTags(etiqueta, font, extracció): importa des de les etiquetes
app.importFromTagsToSelection(etiqueta, font, extracció): importa des de les etiquetes dels fitxers seleccionats
app.downloadImage(url, allFilesInDir): descarrega la imatge
app.exportTags(etiqueta, camí, fmtIdx): fitxer d'exportació
app.writePlaylist(): escriu una llista de reproducció
app.getPlaylistItems(camí): obté els elements d'una llista de reproducció
app.setPlaylistItems(camí, elements): estableix els elements d'una llista de reproducció
app.selectAllFiles(): ho selecciona tot
app.deselectAllFiles(): desselecciona
app.firstFile([select], [onlyTaggedFiles]): al primer fitxer
app.nextFile([select], [onlyTaggedFiles]): al següent fitxer
app.previousFile([select], [onlyTaggedFiles]): al fitxer anterior
app.selectCurrentFile([select]): selecciona el fitxer actual
app.selectFile(camí, [select]): selecciona un fitxer específic
app.getSelectedFilePaths([onlyTaggedFiles]): obté els camins dels fitxers seleccionats
app.requestExpandFileList(): ho expandeix tot
app.applyFilenameFormat(): aplica el format al nom del fitxer
app.applyTagFormat(): aplicar el format a l'etiqueta
app.applyTextEncoding(): aplica la codificació del text
app.numberTracks(núm., total, etiqueta, [options]): números de peça
app.applyFilter(expr): filtre
app.convertToId3v23(): converteix ID3 versió 2.4.0 a 2.3.0
app.convertToId3v24(): converteix ID3 versió 2.3.0 a 2.4.0
app.getFilenameFromTags(etiqueta): nom de fitxer a partir de les etiquetes
app.getTagsFromFilename(etiqueta): nom de fitxer a les etiquetes
app.getAllFrames(etiqueta): obté un objecte amb tots els marcs
app.getFrame(etiqueta, nom): obté un marc
app.setFrame(etiqueta, nom, valor): estableix un marc
app.getPictureData(): obté les dades a partir del marc de la imatge
app.setPictureData(dades): estableix les dades al marc de la imatge
app.copyToOtherTag(etiqueta): etiquetes a altres etiquetes
app.copyTags(etiqueta): copia
app.pasteTags(etiqueta): enganxa
app.removeTags(etiqueta): elimina
app.playAudio(): reprodueix
app.readConfig(): llegeix la configuració
app.applyChangedConfiguration(): aplica la configuració
app.dirName: nom de la carpeta
app.selectionInfo.fileName: nom del fitxer
app.selectionInfo.filePath: camí absolut cap al fitxer
app.selectionInfo.detailInfo: detalls del format
app.selectionInfo.tag(Frame.Tag_1).tagFormat: format de l'etiqueta 1
app.selectionInfo.tag(Frame.Tag_2).tagFormat: format de l'etiqueta 2
app.selectionInfo.formatString(etiqueta, format): substitueix els codis en una cadena de format
app.selectFileName(subtítol, carpeta, filtre, desa el fitxer): obre el diàleg de fitxers i en selecciona un
app.selectDirName(títol, carpeta): obre el diàleg de fitxers per a seleccionar una carpeta

Per a operacions asíncrones, les crides de retorn podran connectar-se amb els senyals.

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

Configuració dels objectes

Es pot accedir a les diferents seccions de configuració a través de mètodes de configs. Les seves propietats es poden llistar a la consola QML.

script.properties(configs.networkConfig())

Es poden establir les propietats:

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