Introduction

At the core of the Appetizer API is its event based system. It is this system that allows hooking into the application and triggering a script as a result of a user action. Listening to an event is always done in the same way:

objectRef:addEventListener("eventName", "eventListener")

The code above means that when the "eventName" event of "objectRef" occurs, the "eventListener" function is going to be called. To put this into practice, start by creating a new plugin folder following the instruction of the previous tutorial, and create a new "main.lua" file.

1. Create a new option button

Option buttons are the small buttons displayed on the option panel. They can be customized and it is possible to associate any sort of actions with them. We are going to create one of these buttons and make it add a new icon to the dock.

To create a new option button, type-in this code:

-- Create a new button
myButton = OptionButton:new()
 
-- Also give it a name - it will be used later
-- to check that the right button was clicked
myButton:setName("tutorialButton")
 
-- Add it to the option panel
-- Note that "optionPanel" is one of the global
-- objects that are available to all the plugins
optionPanel:addButton(myButton)

To test the plugin, save your script and run Appetizer. You should now see a new button in the option panel. At this stage, the button doesn't do anything yet, so we need to tell it what to do when it is clicked. As mentioned previously, this is done by creating a new event listener function and associating it with the button.

2. Creating the event listener

First of all, create the event listener function:

-- The event listener function always receives an "event" parameter
function myButton_click(event)
    -- This event object includes a reference to the sender
    -- In this instance, the button
    button = event.sender
    trace(button:getName(), " was clicked")
 
    -- Create a new shortcut
    newShortcut = DockItem:new()
    newShortcut:setPath("$(MyDocuments)")
    newShortcut:autoSetName()
 
    -- Add it to the dock
    appetizer:getDockItemsRoot():addChild(newShortcut)
end

Here the function is called myButton_click but note that it can be called anything. When it is called by the event dispatcher, it receives an event parameter, which contains, among others, a reference to the sender (in this instance, the button). So you can easily know which object called what by checking event.sender. In the example above, we use this reference to show the name of the button in a debug message.

3. Registering the event listener

Now, in order for this event listener to be called, we need to tie it to the button object. This is done with one simple line:

myButton:addEventListener("click", "myButton_click")

In English, this means: when myButton dispatches the click event, call myButton_click. If you try running the plugin, clicking the button should now add a shortcut to the "My Documents" folder onto the dock. Additionally, if the log window is open, you should see a debug message.

4. Full tutorial code

Below is the full code used in this tutorial:

-- Create a new button
myButton = OptionButton:new()
 
-- Also give it a name - it will be used later
-- to check that the right button was clicked
myButton:setName("tutorialButton")
 
-- Add it to the option panel
-- Note that "optionPanel" is one of the global
-- objects that are available to all the plugins
optionPanel:addButton(myButton)
 
-- The event listener function always receives an "event" parameter
function myButton_click(event)
    -- This event object includes a reference to the sender
    -- In this instance, the button
    button = event.sender
    trace(button:getName(), " was clicked")
 
    -- Create a new shortcut
    newShortcut = DockItem:new()
    newShortcut:setPath("$(MyDocuments)")
    newShortcut:autoSetName()
 
    -- Add it to the dock
    appetizer:getDockItemsRoot():addChild(newShortcut)
end
 
-- Register the event listener
myButton:addEventListener("click", "myButton_click")

Further information

Different objects dispatches different events. To view the full list of the events that might be dispatched by an object, have a look at the Appetizer API Reference. Objects that dispatch events have a small table on top, which gives the name of the events and when it is dispatched. In particular, have a look at the Application and OptionButton classes.