Програмний інтерфейс QML

Із програмним інтерфейсом доволі просто ознайомитися за допомогою консолі QML, яку включено як приклад скрипту із інтерфейсом користувача.

Kid3Script

Kid3Script — звичайний компонент QML, який зберігається у теці додатків. Ви можете скористатися будь-яким іншим компонентом QML. Використання Kid3Script спрощує запуск функції скрипту за допомогою обробника сигналів onRun. Крім того, у ньому передбачено декілька функцій:

onRun: обробник сигналів, який викликається під час запуску скрипту
tagv1, tagv2, tagv2v1: сталі для параметрів міток
script: доступ до функцій скриптів
configs: доступ до об'єктів налаштувань
getArguments(): список аргументів скрипту
isStandalone(): true, якщо скрипт не було запущено з Kid3
setTimeout(callback, delay): запускає зворотний виклик після затримки, яку слід вказувати у мілісекундах
firstFile(): до першого позначеного файла
nextFile(): до наступного позначеного файла

Функції скриптів

У JavaScript, а отже і у QML, для скриптів можна використовувати доволі обмежену множину функцій. У об'єкта script є деякі додаткові методи, зокрема такі:

script.properties(obj): рядок із властивостями Qt
script.writeFile(filePath, data): записати дані до файла; true, якщо запис вдалий
script.readFile(filePath): прочитати дані з файла
script.removeFile(filePath): вилучити файл; true, якщо вилучення вдале
script.fileExists(filePath): true, якщо файл існує
script.fileIsWritable(filePath): true, якщо файл придатний до запису
script.getFilePermissions(filePath): отримати бітову карту режиму доступу до файла
script.setFilePermissions(filePath, modeBits): встановити бітову карту режиму доступу до файла
script.classifyFile(filePath): отримати клас файла (тека — «/», символічне посилання — «@»,
  виконуваний файл — «*», просто файл — « »)
script.renameFile(oldName, newName): перейменувати файл; true, якщо перейменування вдале
script.copyFile(source, dest): скопіювати файл; true, якщо копіювання вдале
script.makeDir(path): створити теку; true, якщо створення вдале
script.removeDir(path): вилучити теку; true, якщо вилучення вдале
script.tempPath(): шлях до теки тимчасових даних
script.musicPath(): шлях до теки із музикою
script.listDir(path, [nameFilters], [classify]): список записів у теці
script.system(program, [аргументи], [мілісекунди]): синхронно запустити загальносистемну команду,
  [код виходу, стандартне виведення, стандартна помилка], якщо не перевищено час очікування
script.systemAsync(program, [аргументи], [зворотний виклик]): асинхронно запустити загальносистемну команду;
зворотний виклик буде виконано із даними [код виходу, стандартне виведення, стандартна
помилка]
script.getEnv(varName): отримати значення змінної середовища
script.setEnv(varName, value): встановити значення змінної середовища
script.getQtVersion(): рядок версії Qt, наприклад «5.4.1»
script.getDataMd5(data): отримати шістнадцятковий рядок хешу MD5 для даних
script.getDataSize(data): отримати розмір байтового масиву
script.dataToImage(data, [формат]): створити зображення з байтів даних
script.dataFromImage(img, [формат]): отримати байти даних із зображення
script.loadImage(filePath): завантажити зображення з файла
script.saveImage(img, filePath, [формат]): зберегти зображення до файла; true, якщо збереження вдале
script.imageProperties(img): отримати властивості зображення; карта, яка містить
  значення «width», «height», «depth» та «colorCount»; порожнє значення, якщо зображення некоректне
script.scaleImage(зображення, ширина, [висота]): масштабувати зображення; повертає масштабоване зображення

Контекст програми

За допомогою QML можна отримати доступ до значної кількості функціональних можливостей Kid3. Програмний інтерфейс є подібним до використаного для D-Bus. Щоб дізнатися більше, зверніться до відповідних нотаток.

app.openDirectory(path): відкрити теку
app.unloadAllTags(): вивантажити усі мітки
app.saveDirectory(): зберегти теку
app.revertFileModifications(): скасувати
app.importTags(tag, path, fmtIdx): імпортувати файл
app.importFromTags(tag, source, extraction): імпортувати дані з міток
app.importFromTagsToSelection(tag, source, extraction): імпортувати дані з міток позначених файлів
app.downloadImage(url, allFilesInDir): отримати зображення
app.exportTags(tag, path, fmtIdx): експортувати файл
app.writePlaylist(): записати список відтворення
app.getPlaylistItems(path): отримати пункти списку відтворення
app.setPlaylistItems(path, items): встановити пункти списку відтворення
app.selectAllFiles(): позначити усе
app.deselectAllFiles(): зняти позначення з усього
app.firstFile([select], [onlyTaggedFiles]): до першого файла
app.nextFile([select], [onlyTaggedFiles]): до наступного файла
app.previousFile([select], [onlyTaggedFiles]): до попереднього файла
app.selectCurrentFile([select]): позначити поточний файл
app.selectFile(path, [select]): позначити певний файл
app.getSelectedFilePaths([onlyTaggedFiles]): отримати шляхи до позначених файлів
app.requestExpandFileList(): розгорнути усе
app.applyFilenameFormat(): застосувати формат назв файлів
app.applyTagFormat(): застосувати формат міток
app.applyTextEncoding(): застосувати кодування тексту
app.numberTracks(nr, total, tag, [параметри]): нумерувати доріжки
app.applyFilter(expr): фільтрувати
app.convertToId3v23(): перетворити ID3v2.4.0 на ID3v2.3.0
app.convertToId3v24(): перетворити ID3v2.3.0 на ID3v2.4.0
app.getFilenameFromTags(tag): назва файла з міток
app.getTagsFromFilename(tag): мітки з назви файла
app.getAllFrames(tag): отримати об'єкт із усіма кадрами
app.getFrame(tag, name): отримати кадр
app.setFrame(tag, name, value): встановити кадр
app.getPictureData(): отримати дані з кадру зображення
app.setPictureData(data): встановити дані у кадрі зображення
app.copyToOtherTag(tag): мітки за іншими мітками
app.copyTags(tag): копіювати
app.pasteTags(tag): вставити
app.removeTags(tag): вилучити
app.playAudio(): відтворити
app.readConfig(): прочитати налаштування
app.applyChangedConfiguration(): застосувати налаштування
app.dirName: назва теки
app.selectionInfo.fileName: назва файла
app.selectionInfo.filePath: абсолютний шлях до файла
app.selectionInfo.detailInfo: дані щодо формату
app.selectionInfo.tag(Frame.Tag_1).tagFormat: формат мітки 1
app.selectionInfo.tag(Frame.Tag_2).tagFormat: формат мітки 2
app.selectionInfo.formatString(tag, format): замінити коди у рядку форматування
app.selectFileName(caption, dir, filter, saveFile): відкрити діалогове вікно вибору файла
app.selectDirName(caption, dir): відкрити діалогове вікно вибору теки

Для асинхронних дій зворотні виклики можна з'єднувати із сигналами.

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

Об'єкти налаштовування

Доступ до різних розділів налаштовування можна отримати за допомогою методів configs. Список їхніх властивостей можна переглянути за допомогою консолі QML.

script.properties(configs.networkConfig())

Можна встановити такі властивості:

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