API em QML

A API pode ser explorada de forma simples com a Consola de QML, que está disponível como um programa de exemplo com uma interface de utilizador.

Kid3Script

O Kid3Script é um componente normal de QML que se localiza dentro da pasta de 'plugins'. Poderá usar outro componente de QML também. Ao usar o Kid3Script, fica mais fácil iniciar a função do programa com a rotina onRun. Para além disso, oferece algumas funções:

onRun: Tratamento de evento que é invocado quando o programa é iniciado
tagv1, tagv2, tagv2v1: Constantes para os parâmetros de marcas
script: Acesso às funções de programação
configs: Acesso às funções de configuração
getArguments(): Lista de argumentos do programa
isStandalone(): verdadeiro se o programa não foi iniciado dentro do Kid3
setTimeout(rotina, atraso): Inicia a rotina ao fim de 'atraso' ms
firstFile(): Para o primeiro ficheiro seleccionado
nextFile(): Para o ficheiro seguinte seleccionado

Funções de Programação

Como o JavaScript e, por inerência, também o QML só têm um conjunto limitado de funções de programação, o objecto script tem alguns métodos adicionais, por exemplo:

script.properties(obj): Texto com as propriedades do Qt
script.writeFile(localFicheiro, dados): Grava os dados no ficheiro, verdadeiro se OK
script.readFile(localFicheiro): Lê dados do ficheiro
script.removeFile(localFicheiro): Apaga o ficheiro, verdadeiro se OK
script.fileExists(localFicheiro): verdadeiro se o ficheiro existe
script.fileIsWritable(localFicheiro): verdadeiro se o ficheiro pode ser gravado
script.getFilePermissions(localFicheiro): Obtém os bits do modo de permissão do ficheiro
script.setFilePermissions(localFicheiro, bitsModo): Altera os bits do modo de permissão do ficheiro
script.classifyFile(localFicheiro): Obtém a classe do ficheiro (pasta "/", ligação simb. "@", exe "*",
  ficheiro " ")
script.renameFile(nomeAntigo, nomeNovo): Muda o nome do ficheiro, verdadeiro se OK
script.copyFile(origem, destino): Copia o ficheiro, verdadeiro se OK
script.makeDir(local): Cria a pasta, verdadeiro se OK
script.removeDir(local): Remove a pasta, verdadeiro se OK
script.tempLocal(): Localização da pasta temporária
script.musicPath(): Localização da pasta de músicas
script.listDir(local, [filtrosNomes], [classificar]): Enumera os itens da pasta
script.system(programa, [args], [ms]): Inicia de forma síncrona um comando do sistema,
  [código de saída, standard output, standard error] caso não expire o tempo-limite
script.systemAsync(programa, [args], [rotina]): Invoca de forma assíncrona um comando do
sistema, sendo a 'rotina' invocada com o [código de saída, standard output, standard error]
script.getEnv(nomeVar): Devolve o valor da variável de ambiente
script.setEnv(nomeVar, valor): Altera o valor da variável de ambiente
script.getQtVersion(): Texto da versão do Qt, p.ex. "5.4.1"
script.getDataMd5(dados): Devolve o texto hexadecimal do código MD5 dos dados
script.getDataSize(dados): Devolve o tamanho da lista de 'bytes'
script.dataToImage(dados, [formato]): Cria uma imagem a partir dos 'bytes' de dados
script.dataFromImage(imagem, [formato]): Obtém os 'bytes' de dados a partir da imagem
script.loadImage(localFicheiro): Carrega uma imagem de um ficheiro
script.saveImage(img, localFicheiro, [formato]): Grava uma imagem para um ficheiro; verdadeiro se OK
script.imageProperties(img): Obtém as propriedades de uma imagem, sendo um mapa que contém os valores "width", "height", "depth" e "colorCount", vazio se a imagem for inválida
script.scaleImage(img, largura, [altura]): Ajusta a escala de uma imagem, devolvendo a imagem ajustada

Contexto da Aplicação

Ao usar o QML, uma grande parte das funções do Kid3 estão disponíveis. A API é semelhante à usada no D-Bus. Para mais detalhes, consulte as notas respectivas.

app.openDirectory(local): Abrir a pasta
app.unloadAllTags(): Fechar todas as marcas
app.saveDirectory(): Grava a pasta
app.revertFileModifications(): Reverter
app.importTags(marca, local, incFmt): Importa o ficheiro
app.importFromTags(marca, origem, extracção): Importa a partir das marcas
app.importFromTagsToSelection(marca, origem, extracção): Importa a partir das marcas dos ficheiros seleccionados
app.downloadImage(url, todosFicheirosNaPasta): Obtém a imagem
app.exportTags(marca, local, indFmt): Exporta o ficheiro
app.writePlaylist(): Grava a lista de reprodução
app.getPlaylistItems(local): Obtém os itens de uma lista de reprodução
app.setPlaylistItems(local, itens): Define os itens de uma lista de reprodução
app.selectAllFiles(): Selecciona tudo
app.deselectAllFiles(): Deselecciona tudo
app.firstFile([seleccionar], [soFicheirosMarcados]): Para o primeiro ficheiro
app.nextFile([seleccionar], [soFicheirosMarcados]): Para o ficheiro seguinte
app.previousFile([seleccionar], [soFicheirosMarcados]): Para o ficheiro anterior
app.selectCurrentFile([seleccionar]): Selecciona o ficheiro actual
app.selectFile(local, [seleccionar]): Selecciona um ficheiro específico
app.getSelectedFilePaths([soFicheirosMarcados]): Obtém as localizações dos ficheiros seleccionados
app.requestExpandFileList(): Expandir tudo
app.applyFilenameFormat(): Aplica o formato dos nomes de ficheiros
app.applyTagFormat(): Aplica o formato das marcas
app.applyTextEncoding(): Aplica a codificação de texto
app.numberTracks(num, total, marca, [opções]): Numera as faixas
app.applyFilter(expr): Filtra
app.convertToId3v23(): Converte de ID3v2.4.0 para ID3v2.3.0
app.convertToId3v24(): Converte de ID3v2.3.0 para ID3v2.4.0
app.getFilenameFromTags(marca): Nome do ficheiro a partir das marcas
app.getTagsFromFilename(marca): Nome do ficheiro para marcas
app.getAllFrames(marca): Obtém o objecto com todos os pacotes
app.getFrame(marca, nome): Obtém o pacote
app.setFrame(marca, nome, valor): Configura o pacote
app.getPictureData(): Obtém os dados do pacote de imagem
app.setPictureData(dados): Modifica os dados do pacote de imagem
app.copyToOtherTag(marca): Copia uma marca para outra
app.copyTags(marca): Copiar
app.pasteTags(marca): Colar
app.removeTags(marca): Remover
app.playAudio(): Reproduzir
app.readConfig(): Lê a configuração
app.applyChangedConfiguration(): Aplica a configuração
app.dirName: Nome da pasta
app.selectionInfo.fileName: Nome do ficheiro
app.selectionInfo.filePath: Localização absoluta do ficheiro
app.selectionInfo.detailInfo: Detalhes do formato
app.selectionInfo.tag(Frame.Tag_1).tagFormat: Formato da marca 1
app.selectionInfo.tag(Frame.Tag_2).tagFormat: Formato da marca 2
app.selectionInfo.formatString(marca, formato): Substitui os códigos no texto do formato
app.selectFileName(titulo, pasta, filtro, gravarFicheiro): Abre uma janela para seleccionar um ficheiro
app.selectDirName(titulo, pasta): Abre a janela de ficheiros para seleccionar uma pasta

Para as operações assíncronas, poderá associar rotinas aos eventos dos sinais.

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

Objectos de Configuração

As diferentes secções de configuração estão acessíveis através de métodos do configs. As suas propriedades poderão ser listadas na consola de QML.

script.properties(configs.networkConfig())

As propriedades poderão ser alteradas:

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