So far, all our scripts have done things during startup. This is of limited use and doesn’t allow us to react to real 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.

1Ansel = require "Ansel"
2
3local function hello_shortcut(event, shortcut)
4Ansel.print("Hello, I just received '"..event..
5       "' with parameter '"..shortcut.."'")
6end
7
8Ansel.register_event("shortcut",hello_shortcut,
9       "A shortcut that prints its parameters")

Now start Ansel, go to “preferences > shortcuts > lua > A shortcut that prints its parameters”, assign a shortcut and try it. You should see a nice message printed on the screen.

Let’s look at the code in detail. We first define a function that takes two strings as input parameters. The first one is the type of event triggered (“shortcut”) and the second is the name of the shortcut (“A shortcut that prints its parameters”). The function itself calls Ansel.print, which will print the message as an overlay in the main window.

Once that function is defined, we register it as a shortcut callback. To do that we call Ansel.register_event which is a generic function for all types of events. We tell it that we are registering a shortcut event, then we give the callback to call and finally, we give the string to use to describe the shortcut in the preferences window.

Let’s try a shortcut that is a little more interactive. This one will look at the images the user is currently interested in (selected or moused-over) and increase their rating:

1Ansel = require "Ansel"
2
3Ansel.register_event("shortcut",function(event,shortcut)
4    local images = Ansel.gui.action_images
5    for _,v in pairs(images) do
6      v.rating = v.rating + 1
7    end
8  end,"Increase the rating of an image")

At this point, most of this code should be self explanatory. Just a couple of notes:

  • Instead of declaring a function and referencing it, we declare it directly in the call to Ansel.register_event this is strictly equivalent but slightly more compact.

  • image.rating is a field that gives the star rating of any image (between 0 and 5 stars, -1 means rejected).

  • Ansel.gui.action_images is a table containing all the images of interest. Ansel will act on selected images if any image is selected, and on the image under the mouse if no image is selected. This function makes it easy to follow Ansel’s UI logic in lua.

If you select an image and press your shortcut a couple of times, it will work correctly at first but when you have reached five stars, Ansel will start showing the following error on the console:

1<![CDATA[
2LUA ERROR : rating too high : 6
3stack traceback:
4   [C]: in ?
5   [C]: in function '__newindex'
6  ./configdir/luarc:10: in function <./configdir/luarc:7>
7      LUA ERROR : rating too high : 6
8  ]]>

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 go the complicated way and catch the error instead:

 1Ansel.register_event("shortcut",function(event,shortcut)
 2    local images = Ansel.gui.action_images
 3    for _,v in pairs(images) do
 4      result,message = pcall(function()
 5        v.rating = v.rating + 1
 6        end)
 7      if not result then
 8        Ansel.print_error("could not increase rating of image "..
 9          tostring(v).." : "..message)
10      end
11    end
12end,"Increase the rating of an image")

pcall will run its first argument and catch any exception thrown by it. If there is no exception it will return true plus any result returned by the function. If there is an exception it will return false and the error message of the exception. We simply test these results and print them to the console.