darktable user manual

Додавання простого прискорювача

So far, all our scripts have done things during startup. This is of limited use and doesn’t allow us to react to user actions. To do more advanced things we need to register a function that will be called on a given event. The most common event to react to is a keyboard shortcut.

darktable = require "darktable"

local function hello_shortcut(event, shortcut)
darktable.print("Hello, I just received '"..event..
       "' with parameter '"..shortcut.."'")
end

darktable.register_event("hello shortcut",
       "shortcut",hello_shortcut,
       "A shortcut that prints its parameters")

Тепер запустіть Darktable, перейдіть до “Налаштування > Клавіатурні прискорювачі > Lua > A shortcut that prints its parameters”, призначте прискорювач і спробуйте. Ви повинні побачити приємне повідомлення, надруковане на екрані.

Давайте розглянемо код детально. Спочатку ми визначаємо функцію, яка приймає два рядки як вхідні параметри. Перший – це тип ініційованої події (“shortcut”), а другий – назва цього прискорювача (“A shortcut that prints its parameters”). Сама функція викликає darktable.print, що надрукує повідомлення у вигляді накладеного тексту в головному вікні.

Як тільки ця функція визначена, ми реєструємо її як функцію зворотного виклику для прискорювача. Для цього ми викликаємо darktable.register_event, що є загальною функцією для всіх типів подій. Ми повідомляємо їй, що реєструємо подію типу “прискорювач” з назвою “hello shortcut”, тоді передаємо їй функцію зворотного виклику при настанні цієї події і, нарешті, даємо рядок для опису прискорювача у вікні налаштувань.

Давайте спробуємо прискорювач, який є трохи більш інтерактивним. Він перегляне зображення, в яких користувач зараз зацікавлений (вибрані або під вказівником миші), і збільшить їх рейтинг:

darktable = require "darktable"

darktable.register_event("increase rating","shortcut",
  function(event,shortcut)
    local images = darktable.gui.action_images
    for _,v in pairs(images) do
      v.rating = v.rating + 1
    end
  end,"Increase the rating of an image")

На даний момент більшість цього коду має бути зрозумілою. Лише пару приміток:

  • Замість того, щоб оголошувати функцію та посилатися на неї, ми оголошуємо її безпосередньо у виклику darktable.register_event, це абсолютно еквівалентно, але трохи компактніше.

  • image.rating – це поле, яке дає рейтинг будь-якого зображення (від 0 до 5 зірок, -1 означає відхилене).

  • darktable.gui.action_images – таблиця, що містить усі зображення, які нас цікавлять. Darktable діятиме на вибрані зображення, якщо вибрано будь-яке зображення, і на зображення під мишею, якщо жодне зображення не вибрано. Ця функція дозволяє легко слідувати логіці інтерфейсу Darktable в Lua.

Якщо вибрати зображення та натиснути прискорювач кілька разів, спочатку це буде працювати коректно, але коли ви досягли п’яти зірок, Darktable на консолі почне відображати таку помилку:

<![CDATA[
LUA ERROR : rating too high : 6
stack traceback:
   [C]: in ?
   [C]: in ?
   [C]: in metamethod 'newindex'
   ./configdir/luarc:10: in function <./configdir/luarc:7>
   [C]: in ?
   [C]: in ?
  ]]>

This is lua’s way of reporting errors. We have attempted to set a rating of 6 to an image, but a rating can only go as high as 5. It would be trivial to add a check, but let’s show how to catch the error instead:

darktable.register_event("increase rating","shortcut",
  function(event,shortcut)
    local images = darktable.gui.action_images
    for _,v in pairs(images) do
      result,message = pcall(function()
        v.rating = v.rating + 1
        end)
      if not result then
        darktable.print_error("could not increase rating of image "..
          tostring(v).." : "..message)
      end
    end
  end,"Increase the rating of an image")

pcall запустить свій перший аргумент і вловить будь-який виняток, викликаний ним. Якщо немає винятку, він поверне true плюс будь-який результат, повернутий функцією. Якщо є виняток, він поверне “false” та повідомлення про помилку винятку. Ми просто перевіряємо ці результати та друкуємо їх на консолі.

Translations