Iconoclasm Layout Guide

Iconoclasm uses layouts, which tells it how many icons to display on-screen and where to display them. This is a guide on how to create new layouts.

Layouts Explained

Layouts are property list files (plists), stored in /Library/Iconoclasm/Layouts.

There are two types of layouts:

• Grid layouts are defined by having columns (each with an X coordinate) and rows (each with a Y coordinate).
• Freeform layouts let you specify an X/Y coordinate pair for each icon on screen at once.

The origin (0,0) for the coordinate system on iOS is in the upper left. This means that X increases as you go to the right, and Y increases as go to the bottom.

Grid Layouts

Grid layouts have three keys:

• EasyGrid is a boolean key, and must be set to YES.
• Cols is an array containing X coordinates for the leftmost point for the icons in each column.
• Rows is an array containing Y coordinates for the topmost point for the icons in each rows.

Freeform Layouts

Freeform layouts have one key, Origins, which is an array of dictionaries. Each dictionary represents a point, and it has two keys: x and y.

Expanding to the iPad

The above keys are used to create layouts for the iPhone and iPod touch. You can create iPad-specific layouts by using different keys.

• For grid layouts, use Cols-iPad and Rows-iPad for Portrait, and Cols-iPad-Landscape and Rows-iPad-Landscape for Landscape.
• For freeform layouts, use Origins-iPad for Portrait, and use Origins-iPad-Landscape for Landscape.

The same amount of icons must be available in both orientations, or you will be sent into Safe Mode on respring. If you do not provide landscape coordinates, the portrait coordinates will be scaled accordingly.

Speeding Up Respring

Plists can be stored in a variety of different ways; the two most common formats are XML and binary:

• XML is human-readable and editable in any text editor.
• Binary isn't human-readable, but it is much faster than XML files.

If you wish to speed up respring time, consider converting your layout plists to binary. You can do this with Property List Editor (if you have Xcode 3), Xcode (if you have Xcode 4), or plutil.

A Few More Details

• Iconoclasm has resizing math that will scale layouts if an icon list gets resized. If you wish to disable this resizing math, you can set the UseRawPoints boolean key to YES.
• All of the included layouts are available for your perusal in /Library/Iconoclasm/Layouts. Triangle.plist is a freeform layout, whereas the others are grid layouts.

Updates

• Nov 1st: Rewrite of what was once Customizing Iconoclasm.