QML API

De API kan gemakkelijk verkend worden met de QML-console, die beschikbaar is als een voorbeeldscript met een gebruikersinterface.

Kid3Script

Kid3Script is een reguliere QML-component gelokaliseerd in de plug-in-map. U zou evengoed een andere QML-component kunnen gebruiken. Met Kid3Script wordt het makkelijk gemaakt om met de scriptfunctie te beginnen met het signaalafhandelaar onRun. Bovendien biedt het enige functies:

onRun: Signaalbehandelaar die wordt aangeroepen wanneer het script wordt gestart
tagv1, tagv2, tagv2v1: Constanten voor tagparameters
script: Toegang tot scriptfuncties
configs: Toegang tot configuratieobjecten
getArguments(): Lijst met scriptargumenten
isStandalone(): true als het script niet is gestart vanuit Kid3
setTimeout(callback, delay): Start callback na vertraging ms
firstFile(): Naar eerst geselecteerd bestand
nextFile(): Naar volgend geselecteerd bestand

Functies voor scripts

Omdat JavaScript en daarom ook QML slechts een beperkte set functies heeft voor scripts, heeft het object script enige extra methoden, bijvoorbeeld:

script.properties(obj): Tekenreeks met Qt eigenschappen
script.writeFile(filePath, data): Gegevens naar bestand scrijven, true indien OK
script.readFile(filePath): Gegevens lezen uit bestand
script.removeFile(filePath): Bestand verwijderen, true indien OK
script.fileExists(filePath): true indien bestand bestaat
script.fileIsWritable(filePath): true indien bestand is te beschrijven
script.getFilePermissions(filePath): Modusbits van rechten van bestand ophalen
script.setFilePermissions(filePath, modeBits): Modusbits van rechten van bestand instellen
script.classifyFile(filePath): Klasse van bestand ophalen (map "/", symbolische koppeling "@",
 exe "*",  bestand " ")
script.renameFile(oldName, newName): Bestand hernoemen, true indien OK
script.copyFile(source, dest): Bestand kopiëren, true indien OK
script.makeDir(path): Map aanmaken, true indien OK
script.removeDir(path): Map verwijderen, true indien OK
script.tempPath(): Pad naar tijdelijke map
script.musicPath(): Pad naar muziekmap
script.listDir(path, [nameFilters], [classify]): Lijst maken van mapitems
script.system(program, [args], [msecs]): Een systeemcommando synchroon starten,
  [exitcode, standaarduitvoer, standaardrdfouten] indien geen timeout
script.systemAsync(program, [args], [callback]): Een systeemcommando asynchroon starten,
terugaanroep zal aangeroepen worden met [exitcode, standaarduitvoer, 
standaardfouten]
script.getEnv(varName): Haal waarde op van omgevingsvariabele
script.setEnv(varName, value): Stel waarde in van omgevingsvariabele
script.getQtVersion(): Qt versietekenreeks, bijv. "5.4.1"
script.getDataMd5(data): Tekenreeks in hex van de MD5 hash van gegevens
script.getDataSize(data): Grootte van byte-array ophalen
script.dataToImage(data, [format]): Een afbeelding uit gegevensbytes ophalen
script.dataFromImage(img, [format]): Gegevensbytes ophalen uit afbeelding
script.loadImage(filePath): Een afbeelding laden uit een bestand
script.saveImage(img, filePath, [format]): Een afbeelding opslaan naar een bestand, true indien OK
script.imageProperties(img): Eigenschappen ophalen van een afbeelding, map bevattende
  "width", "height", "depth" en "colorCount", leeg indien ongeldige afbeelding
script.scaleImage(img, width, [height]): Schaa een afbeelding, geeft geschaalde afbeelding terug

Context van toepassing

Met gebruik van QML zijn een groot gedeelte van de Kid3-functies toegankelijk. De API is vergelijkbaar met diegene gebruikt voor D-Bus. Voor details wordt u verwezen naar de respectievelijke notities.

app.openDirectory(path): Open map
app.unloadAllTags(): Alle tags ontladen
app.saveDirectory(): Map opslaan
app.revertFileModifications(): Ongedaan maken
app.importTags(tag, path, fmtIdx): Bestand importeren
app.importFromTags(tag, source, extraction): Uit tags importeren
app.importFromTagsToSelection(tag, source, extraction): Uit tags van geselecteerde bestanden importeren
app.downloadImage(url, allFilesInDir): Afbeelding downloaden
app.exportTags(tag, path, fmtIdx): Bestand exporteren
app.writePlaylist(): Afspeellijst schrijven
app.getPlaylistItems(path): Items ophalen uit een afspeellijst
app.setPlaylistItems(path, items): Items instellen van een afspeellijst
app.selectAllFiles(): Alles selecteren
app.deselectAllFiles(): Selectie ongedaan maken
app.firstFile([select], [onlyTaggedFiles]): Naar eerste bestand
app.nextFile([select], [onlyTaggedFiles]): Naar volgende bestand
app.previousFile([select], [onlyTaggedFiles]): Naar vorige bestand
app.selectCurrentFile([select]): Huidige bestand selecteren
app.selectFile(path, [select]): Een specifiek bestand selecteren
app.getSelectedFilePaths([onlyTaggedFiles]): Paden van geselecteerde bestanden ophalen
app.requestExpandFileList(): Alles uitvouwen
app.applyFilenameFormat(): Bestandsnaamformaat toepassen
app.applyTagFormat(): Tagformaat toepassen
app.applyTextEncoding(): Tekstcodering toepassen
app.numberTracks(nr, total, tag, [options]): Aantal tracks
app.applyFilter(expr): Filter
app.convertToId3v23(): ID3v2.4.0 naar ID3v2.3.0 converteren
app.convertToId3v24(): ID3v2.3.0 naar ID3v2.4.0 converteren
app.getFilenameFromTags(tag): Bestandsnaam uit tags
app.getTagsFromFilename(tag): Bestandsnaam naar tags
app.getAllFrames(tag): Object ophalen met alle frames
app.getFrame(tag, name): Frame ophalen
app.setFrame(tag, name, value): Frame instellen
app.getPictureData(): Gegeven uit afbeeldingsframe ophalen
app.setPictureData(data): Gegeven in afbeeldingsframe instellen
app.copyToOtherTag(tag): Tags naar andere tags
app.copyTags(tag): Kopiëren
app.pasteTags(tag): Plakken
app.removeTags(tag): Verwijderen
app.playAudio(): Afspelen
app.readConfig(): Configuratie lezen
app.applyChangedConfiguration(): Configuratie toepassen
app.dirName: Mapnaam
app.selectionInfo.fileName: Bestandsnaam
app.selectionInfo.filePath: Absoluut bestandspad
app.selectionInfo.detailInfo: Formaatdetails
app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 formaat
app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 formaat
app.selectionInfo.formatString(tag, format): Codes invullen in formaattekenreeks
app.selectFileName(caption, dir, filter, saveFile): Bestandsdialoog openen
om een bestand te selecteren
app.selectDirName(caption, dir): Bestandsdialoog openen om een map te selecteren

Voor asynchrone bewerkingen kunnen callbacks verbonden worden met signalen.

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

Configuratieobjecten

De verschillende configuratiesecties zijn toegankelijk via methoden van configs. Hun eigenschappen kunnen getoond worden in het QML-console.

script.properties(configs.networkConfig())

Eigenschappen kunnen ingesteld worden:

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