IconBundles

IconBundles is an add-on to WinterBoard, the iOS theming platform, that saves you time when customizing homescreen icons.


Why

In 2007, a popular method of customization was SummerBoard, which cleverly hooked into the system and was much safer than its alternatives. For designers, SummerBoard made icon customization really simple; you just plopped a bunch of PNG files into a folder called Icons. Each image filename needed to match the name of the corresponding app. So, a typical theme's directory structure looked like this:

My Theme/
    Wallpaper.png
    Dock.png
    Icons/
        Phone.png
        iPod.png
        Safari.png

Two of the main issues with SummerBoard were (1) themes did not localize easily, meaning that in most cases icons would break for users that spoke a different language than the theme author (consider Teléfono.png), and (2) the functionality of SummerBoard was limited — you could only customize a few specific images.


With the introduction of iPhone OS 2.0 in 2008, Jay Freeman (saurik) created a drastically improved successor to SummerBoard called WinterBoard. Fortunately, WinterBoard has been maintained well and is compatible with iPhone OS 2.0 through iOS 8. It has become the standard for theming.


While WinterBoard supports legacy themes, using SummerBoard's method has been discouraged moving forward. A new paradigm was introduced using a folder named Bundles:

My Theme/
    Wallpaper.png
    Bundles/
        com.apple.mobilephone/
            icon.png
        com.apple.mobileipod/
            icon.png

Sub-folders are placed inside the Bundles folder, each named by an app's bundle identifier. Inside a bundle ID folder, PNG files are placed and named to correspond with the original PNG filename in the target app. The positives to this approach are that (1) localization is no longer an issue, (2) the amount of customizable assets throughout iOS is much greater, and (3) it supports the increasing variety of iOS device screen resolutions and pixel densities. However, in reality modern themes look more like this:

My Theme/
    Wallpaper@2x.png
    Bundles/
        com.apple.switchboard/
            icon@2x.png
            icon-72.png
            icon-72@2x.png
        com.company.sampleapp/
            Icon-120.png
            Icon-144.png
        com.company.otherapp/
            AppIcon~ipad@2x.png
            AppIcon~iphone@2x.png
            AppIcon~iphone@3x.png

As you can see, this can get convoluted rather quickly — icon filenames are inconsistent as they are decided upon by developers. For theme designers, this is a time sink; they have to spend time looking up the correct filenames for each and every app. Worse yet, app developers and Apple themselves can change icon filenames in updates, breaking existing themes. If a theme author abandons their work, the community is left with a bunch of half-working themes and very few people are motivated to fix them. The Bundles method, while elegant in many ways, is not perfect for theming icons.


I created IconBundles with the intention of combining the simplicity of SummerBoard's Icons folder with the speed, flexibility, and future-proof nature of WinterBoard's Bundles folder. In fact, if you are a theme designer, I have not yet thought of a reason why you would not want to use IconBundles; it saves an immense amount of time and hassle. Read below to see how it works.


How to Use

Create an IconBundles folder in your theme. Drop in PNG images named with each app's bundle identifier. The following extensions may be necessary to add to your filename (and they are case sensitive):

~ipad Required for iPad and iPad mini.
@2x or @3x @2x required for Retina display devices.
@3x required for Retina HD display devices (iPhone 6 Plus).
Only one of these extensions can be used per filename (not both).

In the end, your filenames should look something like this:

com.apple.Music@2x.png
com.apple.Music~ipad@2x.png

Images are automatically scaled for use in Spotlight and Notification Center — you do not need to provide separate images for those cases.


You can also tell IconBundles to mask your icons. Masking rounds and resizes icons to produce the standard iOS icon look. To do so, create an Info.plist file in the root folder of your theme and set the key IB-MaskIcons to true like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>IB-MaskIcons</key>
	<true/>
</dict>
</plist>

If your icons have a transparent background or are already rounded, you should not do this. IB-MaskIcons defaults to false.


Where to Download

IconBundles is available as a free download from Cydia on jailbroken iOS devices and is compatible with iOS 5.0 through 8.1.


Contribute

This tweak is open source. If you are a themer and have a feature request or a bug to report, please do so by filing an issue on the Github repository. If you are a developer, code improvements are greatly appreciated; just submit a pull request.