IconBundles is an add-on to WinterBoard, the iOS theming platform, that saves you time when customizing homescreen icons.
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
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/ firstname.lastname@example.org icon-72.png email@example.com com.company.sampleapp/ Icon-120.png Icon-144.png com.company.otherapp/ AppIconfirstname.lastname@example.org AppIconemail@example.com AppIconfirstname.lastname@example.org
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.
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.
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):
||Required for iPad and iPad mini.|
||@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:
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
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.
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.