Using AppleScript with GeekTool

User documentation
07/23/2009

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" 
  geeklets
end tell
This produces an output like this :
{shell geeklet id "CAD821B6-EBC9-42CF-ADDC-AB3A473D1D7B" of application "GeekTool", 
file geeklet id "6EF1C15C-BE32-4A43-888E-053C7A266A8E" of application "GeekTool", 
shell geeklet id "C9C9717F-51A9-4435-9727-CDE57E123B3F" of application "GeekTool", 
shell geeklet id "329F80B0-EC4C-499F-A4CC-A710A241805B" of application "GeekTool", 
shell geeklet id "75E302A9-1F09-406F-A247-C99125340214" of application "GeekTool", 
image geeklet id "F6C6378E-986D-45BB-8D9E-7DA0A07D5659" of application "GeekTool",
image geeklet id "2E15BC32-1D83-4BB8-A4B9-C935B4EF2204" of application "GeekTool", 
shell geeklet id "6BCE0EA2-B6CF-4BA0-A5A2-15460A309C55" of application "GeekTool"}

...as long as you have existing geeklets.

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" 
  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"

Manipulating Geeklets

This shows how to hide or show individual geeklets :

tell application "GeekTool" 
    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" 
    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" to refresh all

-- This will refresh a specific geeklet
tell application "GeekTool" 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" 
    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 ~/Library/PreferencePanes/ directory in the Finder
  • Right click (or control click) on GeekTool.prefPane, and choose "Show Package Content"
  • Go into Contents/Resources/
  • Drag and Drop GeekTool 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" 
    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

Files