Introduction

Apple provide a system-wide automation mechanism based on a scripting language called AppleScript. This lets advanced users write a series of instructions which tell applications to do things without needing to point and click. In Mac OS X 10.10, Apple also introduced support for automation using the JavaScript language. This Apple web page web site has a good overview of both.

Add Folder Icons works with this system. You can use it to automate folder icon addition - see the folder automation page for a step-by-step guide. For full technical information about the Add Folder Icons integration with AppleScript and JavaScript, stay on this page.

Basics

Apply and remove

In Add Folder Icons versions 3.0.0 and 3.0.1, Add Folder Icons provides only two very simple commands - apply and remove - which apply or remove customised icons to folders, respectively. This is done without any graphical interruption from Add Folder Icons; unlike when you operate the application manually, you won't get a progress bar or the opportunity to cancel things, so beware. This interruption-free approach lets you start to introduce automatic application of customised folder icons which are updated when folders change, by creating scripts which are saved as Folder Actions. See the folder automation page for more information.

Examples

The apply command is used thus: apply "style name" to { list of POSIX files } where the POSIX file references must all refer to folders. Here, we ask the Finder to let us choose some folders, convert the results from Finder Items into POSIX files and send that over to Add Folder Icons:

tell application "Finder"
  set theFolders to ¬
    choose folder with prompt ¬
      "Select as many folders for icon customisation as you like" with multiple selections allowed
end tell

set thePOSIXFiles to {}

repeat with theFolder in theFolders
  copy {POSIX file (POSIX path of theFolder)} to end of thePOSIXFiles
end repeat

tell application "Add Folder Icons"
  apply "Preset: Classic thumbnails" to thePOSIXFiles
end tell

The remove command just takes a list of POSIX files and removes custom icons from them. Assuming the same thePOSIXFiles list has been set up as in the example above, then:

tell application "Add Folder Icons"
  remove from thePOSIXFiles
end tell
The JavaScript equivalent

First choose and apply the new icons:

finder = Application( 'Finder' );

finder.includeStandardAdditions = true
folders = finder.chooseFolder( {
  withPrompt: 'Select as many folders for icon customisation as you like',
  multipleSelectionsAllowed: true
} );

posixFiles = folders.map(
  function( folder ) { return Path( folder ); }
);

addFolderIcons = Application( 'Add Folder Icons' );
addFolderIcons.apply( 'Preset: Classic thumbnails', { to: posixFiles } );

Then, again assuming the same posixFiles array has been set up as in the example above:

addFolderIcons = Application( 'Add Folder Icons' );
addFolderIcons.remove( { from: posixFiles } );

Application and icon style properties

In Add Folder Icons version 3.0.2, AppleScript support was extended quite a lot. You can query aspects of Add Folder Icons as an application as well as enquire about styles, in a read-only fashion. The application name, version and frontmost properties come from the core suite. The iconStyles enumeration lists all defined styles sorted alphabetically by name, with properties that you can examine through the built-in Script Editor application's dictionary browser - in OS X 10.11 "El Capitan", this is under "File" -> "Open Dictionary...".

Examples

-- Core suite

name of application "Add Folder Icons"
-- => "Add Folder Icons"
version of application "Add Folder Icons"
-- => "3.0.2"
frontmost of application "Add Folder Icons"
-- => 'false' (or 'true'!)
-- Add Folder Icons additions
-- Get a specific icon style by list index, starting from 1

tell application "Add Folder Icons"
  name of icon style 1
end tell
-- => e.g. "Preset: Classic thumbnails"

-- Get a specific icon style by name and read its "show folder
-- in background" property

tell application "Add Folder Icons"
 show folder in background of icon style "Preset: Classic thumbnails"
end tell
-- => '2 or fewer'

-- Let the user choose from a list of styles and store the result in
-- variable "theStyleName"
tell application "Add Folder Icons"
  set theStyleNames to name of icon styles
  set theStyleName to choose from list theStyleNames
end tell
The JavaScript equivalent
// Core suite

addFolderIcons = Application( 'Add Folder Icons' );
addFolderIcons.name(); // Or version(), or frontmost()
// Add Folder Icons additions
// Get a specific icon style by list index, starting from 0
addFolderIcons.iconStyles[ 0 ].name();

// Get a specific icon style by name and read its "show folder
// in background" property
addFolderIcons.iconStyles[ 'Preset: Classic thumbnails' ].showFolderInBackground();

// Let the user choose from a list of styles and store the result in
// variable "styleName"
addFolderIcons.includeStandardAdditions = true;
styleNames = addFolderIcons.iconStyles.name()
styleName  = addFolderIcons.chooseFromList( styleNames )