Warning! Under construction.

Using AppleScript with GeekTool

Concepts

AppleScript has been introduced in GeekTool because some users wanted to extend possibilities in ways that could not be implemented directly into the software. That's why it is a very powerful tool that will let you go far beyond the standard features of GeekTool.

The structure of scriptability in GeekTool is quite simple. The application object is composed of geeklet objects and group objects.

Each geeklet object has a set of properties and attached groups.

Each group can be set visible or not, this has the same effect as enabling or disabling groups in the menu or in system preferences.

Example

An easy way to get a list of geeklet objects is to run this simple script in Script Editor :

tell application "GeekTool Helper" 
  geeklets
end tell

This produces an output like this :

{ id "FE69128C-1D1B-4D33-9FB2-F64B8225024C" of application "GeekTool Helper",
shell geeklet id "5EBD23B5-E97D-4AFD-A0A7-6D3F8B62747A" of application 
"GeekTool Helper",  id "0C0BCFCB-57E4-4274-88F0-AC7BA0FA2FAF" of application 
"GeekTool Helper",  id "FAB0C00E-9A1E-49A4-8324-9F480874429B" of application 
"GeekTool Helper",  id "D4C60919-ACC9-4150-A41E-084B6D1CC594" of application 
"GeekTool Helper",  id "12BD3CC9-5A3F-4E79-B7F8-BA68F0D4056C" of application 
"GeekTool Helper", file geeklet id "6EF1C15C-BE32-4A43-888E-053C7A266A8E" of 
application "GeekTool Helper",  id "72B437B2-74D5-4683-8C24-FE7701304963" of 
application "GeekTool Helper", shell geeklet id "C9C9717F-51A9-4435-9727-
CDE57E123B3F" of application "GeekTool Helper",  id 
"2124FFC2-46EE-4114-9379-8A65837217ED" of application "GeekTool Helper"}

As you can see, geeklets are referenced by their ID. This ID is generated when you create the Geeklet from System Preferences, and is unique.

A convenient way to get the ID of a given geeklet is to open GeekTool Preferences, select a geeklet, and double click on the bottom of the inspector palette where the ID is displayed. This will copy the ID in the pasteboard.

You can also get a given geeklet by its name, as long as you did set one in the inspector, like this :

tell application "GeekTool Helper" 
  set calGeeklet to first item of (geeklets whose name is "Calendar")
end tell

It should return an output similar to this one :

shell geeklet id "6BCE0EA2-B6CF-4BA0-A5A2-15460A309C55" of application "GeekTool"

Now you know how to reference Geeklets, let's see what you can do with it.

Manipulating Geeklets

This shows how to hide or show individual geeklets :

tell application "GeekTool Helper" 
    set g to geeklet id "CAD821B6-EBC9-42CF-ADDC-AB3A473D1D7B" 
    set visible of g to false
end tell

The only way to get it back is to set the property back to true, or relaunch GeekTool.

This flag will totally ignore groups settings. It will show, or hide a geeklet without checking if the geeklet should be visible or invisible according to currently enabled groups.

Manipulating groups

Here is how you can show or hide groups.

tell application "GeekTool Helper" 
    set twitterGroup to group "Twitter" 
    set visible of twitterGroup to false
end tell

Refreshing geeklets

Another useful feature is the refresh (or refresh all) command

This will refresh all geeklets eligible to a refresh action (not File, which are continuous)

tell application "GeekTool Helper" to refresh all

This will refresh a specific geeklet

tell application "GeekTool Helper" to refresh geeklet id "CAD821B6-EBC9-42CF-ADDC-AB3A473D1D7B"

Note the short notation used here, without tell / end tell block, this is standard AppleScript shortcut.

A long form would be :

tell application "GeekTool Helper" 
    tell geeklet id "CAD821B6-EBC9-42CF-ADDC-AB3A473D1D7B" 
        refresh
    end tell
end tell

Getting GeekTool dictionary

There is a little trick to get the GeekTool dictionary in Script Editor because the actual scriptable application is hidden into the .prefPane bundle.

In Script Editor, open the Library from the Window menu (Or Shift-Command-L)
Go to /Applications directory in the Finder
Right click (or control click) on GeekTool, and choose "Show Package Content"
Go into Contents/PlugIns/
Right click (or control click) on GeekTool.prefPane, and choose "Show Package Content"
Go into Contents/Resources/
Drag and Drop "GeekTool Helper" application to the Library window of Script Editor

A more complex example

This script displays a dialog where you can select one or multiple geeklet to refresh now Courtesy of Philippe M.

tell application "GeekTool Helper" 
    set lsGeeklets to {}
    -- get visible groups
    set lsGroups to every group whose visible is true
    -- build the dialog
    set lsItems to {}
    repeat with aGroup in lsGroups
        set groupName to name of aGroup
        set lsGeeklets to lsGeeklets & (every geeklet whose groups contains aGroup)
    end repeat
    repeat with aGeeklet in lsGeeklets
        set lsItems to lsItems & name of aGeeklet
    end repeat
    -- run the dialog
    set lsChoices to choose from list lsItems with prompt "Select the geeklets to refresh" with multiple selections allowed
    if lsChoices = false then return
    -- refresh the selected geeklets
    repeat with aChoice in lsChoices
        set lsByName to (geeklets whose name is aChoice)
        repeat with aGeeklet in lsByName
            set oneId to id of aGeeklet
            tell geeklet id oneId to refresh
        end repeat
    end repeat
end tell