WinterBoard: A Primer

WinterboardiFans has partnered with William Szilveszter, the creative brainchild behind Jaku, one of the most popular themes available on Cydia for jailbroken devices, to deliver a series revolving around the art of iOS theming. Szilveszter is always available for hire and can be found on Twitter.

Throughout this exclusive series, Szilveszter will share his knowledge and expertise about theming virtually every single aspect of the iPhone, iPod touch and iPad. This week, to start, the Canadian designer details everything you need to know about customizing iOS with WinterBoard. 

WinterBoard

WinterBoard works by intelligently mirroring the contents of the iOS filesystem. What does that mean, and how does that apply to theming? Let me show you. The following is the root of the iOS filesystem, as seen through Panic’s Transmit.

1

folderTip: The definition of “root” is that of the lowest level when we speak of it in terms of filesystems. Root is denoted by the prefix “/”. This prefix is actually quite important. For example: /Library/Themes is completely different from Library/Themes.

The former is located at the heart of the filesystem (root); the lowest level. The latter, is located in the current directory, and that doesn’t have to be root (it could be in your User folder or anywhere else). People often gloss over these as trivial matters, but they are very important, especially when you are dealing with changes to the filesystem. The difference between the two is like telling your friend you are waiting at the Chapters on 3rd and Gastby, rather than Chapters.

Root is also the owner that holds the most privileges of a Unix-based system (iOS is borne from OS X, which is based on Unix), and that’s when we speak of it in terms of accounts/users. When someone says “I just rooted that guys box,” it means that he or she has acquired the highest set of credentials, capable of altering anything.

Naturally, we all try to protect against this, and that’s why Unix-based systems tend to be more secure, because they don’t hand out root access haphazardly. They guard against this by creating separate accounts for their users. Windows, on the other hand, has a slightly different architecture and their “root” accounts are dubbed Administrator.

Most of those directories won’t be of much interest to most of you, but a few are definitely of importance. The Applications directory houses all the default apps and those installed through Cydia. User, which is actually a symlink (a shortcut) to /private/ var/mobile, houses applications installed through the App Store (among your photos, SMS conversations, etc.). That directory is of special importance because that’s essentially you. The user “mobile” is your account.

WinterBoard essentially maps whatever is located within your theme (e.g., Jaku.theme) to the actual files on the device. It only needs two things: the bundle identifier and the file name of the image. Themes are all housed in /Library/Themes/, which is a symlink to /var/stash/Themes/. (I’m only going to talk about the “proper” method of theming, as the SummerBoard mode has long been deprecated and should no longer be used.) The structure here is important.

WinterBoard requires a child folder inside the parent “theme” folder called “Bundles.” I should tell you guys right now, that WinterBoard is case-sensitive. If you call the folder “bundles”, things won’t work. Similarly, if you try to theme an icon that’s named “Icon@2x.png” but call it “icon@2x.png”, it won’t work.

Side Note: A lot of beginners struggle with this, and I wish Jay Freeman actually removed the case-sensitivity, as it only offers a detriment and no additional benefit, but that’s another matter altogether; we work with what we have. I’ll touch on this later, but anyone that’s interested in theming, should be aware of this requirement.

Once you have that structure (e.g., /Library/Themes/Jaku.theme/Bundles), you’ll need to populate that folder. With what? Anything you’d like to change. For example, let’s go ahead and change the default Camera icon, which is located in /Applications/ Camera.app:

As you can see, the application’s icon is called: Camera@2x~iphone.png.

How did I find this out? Honestly, the best way is to copy the Camera.app bundle to your Desktop on OS X. Since Apple’s operating system has native support for iPhone-optimized PNGs, you’ll be able to see thumbnails for them all using Finder (just right click on the .app and select “Show Package Contents.”) Those running Windows will have to de-optimize the PNGs, and that’s a headache. It can be done, but since I run OS X, I’m not familiar with the procedure.

Once you isolate the app’s icon, you still need that Bundle ID. The Bundle ID (e.g., com.apple.camera) is the name of the folder that will house your icon. It’s also what tells WinterBoard what to map. The best way to get the Bundle IDs is again, through OS X. You’ll need a plist editor (either Xcode or equivalent; here I use Xcode). You want the Info.plist located inside the payload (the payload is what .app folders are officially called). Once open, look for the heading “Bundle identifier.”

3

As you can see above, the Bundle ID for the Camera.app is called com.apple.camera. Again, this is case-sensitive. Now that we have those two vital pieces of data, we can theme the camera app. We put them all together and the structure is as follows:

Jaku.theme/Bundles/com.apple.camera/Camera@2x~iphone.png

Even a single typo or improper case, and you’ll see no change. This is not because WinterBoard isn’t working, but rather because it’s trying to match something that actually doesn’t exist. It’s like looking in your fridge for the laundry detergent. You know exactly what you’re looking for, but you’re looking in the wrong place. Theming default apps are rather easy, because they are nicely organized. Your apps, however, aren’t so lucky. They get cryptic folders when they’re installed:

4

This greatly enhances security, but it also makes it difficult to nab the information you’re looking for (the Bundle ID and the icon file name) as you have to drill down into the parent directory. Which may seem like a trivial step, but when you have dozens (or hundreds) of apps installed, it becomes quite tiresome:

5

The easiest way around this problem is to pull the information from the actual IPA, which is nothing more than a glorified ZIP file. I use Unarchiver (a free download in the Mac App Store), but anything that can decompress a ZIP file works just fine (even the native Archive Utility in OS X). In iTunes, you can download your app, then click on it, selecting Show in Finder (or Show in Explorer). Once there, simply right click and select the program you’d like to open it with.

6

Once unpacked, you’ll see the folder (in this case, Tweetbot 2.7.3). Open it and drill down until you get to the .app file (inside Payload). Once there, right click, and again, select “Show Package Contents.” You can go right to the Info.plist and pull the Bundle ID (e.g., com.tapbots.Tweetbot). Hunting for the application’s icon file, however, is a bit tricky.

We see that Tapbots didn’t adopt the default naming structure (which tends to be either icon@2x.png or Icon@2x.png). They called their icon AppIcon@2x.png. But thanks to OS X’s native support for optimized PNGs, you can see that Finder has no problem rendering the thumbnails. This makes your life a lot easier.

7

Now that we have those two bits of information, we, again, put it all together:

Jaku.theme/Bundles/com.tapbots.Tweetbot/AppIcon@2x.png

Now if we were to name it:

Jaku.theme/Bundles/com.tapbots/Tweetbot/appicon@2x.png

WinterBoard would replace appicon@2x.png, but since that file doesn’t exist anywhere, you, the user, wouldn’t see a change. The process may seem highly technical and a bit daunting, but once you get into the swing of things, it becomes quite easy.

That is the meat and potatoes of WinterBoard.

A Few Tips

Icon Sizes

  • iPhone Retina icons are 114x114px.
  • Default icons (or apps installed through Cydia) are 118x120px.
  • iPad Retina icons are 144x144px, and default or Cydia apps are 148x150px.
  • Retina, anything, is denoted by the suffix (@2x). They are exactly that, standard resolution graphics x2. So standard iPhone icons (for devices like the 3GS) were 57×57 (57 x 2 = 114). Since Apple (smartly) just doubled the resolution (from 320×480 to 640×960), all they had to do was redraw everything at twice the size for pixel perfect images.
  • WinterBoard can theme almost everything in iOS, provided a PNG exists. But some things are drawn by iOS (we say “by code” when this occurs), and those are outside of its capabilities. When parts of the UI are drawn by code, WinterBoard can’t touch them. The keyboard keys are a prime example of this. There are apps in Cydia that will allow you to theme it, but they work by applying their own layer on top of the standard keyboard, and then theming that. WinterBoard works solely on native files, not code.

Modifying An Existing Theme: Do’s and Don’ts

Don’t just make modifications to an existing theme. Most people simply just throw their own icons onto an author’s theme. Speaking as a theme author, do not do this. Not only does it make it extremely difficult to make backups or changes, but if the author decides to update the package, you’ll lose all the modifications you’ve made.

A better way, is to use the tips outlined above and make your own theme. For example, if you bought Jaku and want to use your own Camera icon, don’t just replace the existing one found in Bundles/com.apple.camera. Copy that folder to a new theme (let’s call it “My Jaku.theme”) and then make the change in there. Once you’ve made that new theme, it will always be safe and it will be easily manageable. Putting it together, it would look like this:

My Jaku.theme/Bundles/com.apple.camera/Camera@2x~iphone.png

To activate it, just select it in WinterBoard, and drag it to the top of the pile. WinterBoard prioritize the items in the list. If you drag it to the top of the list, it will take precedent over the native Jaku theme’s icon. If you drag it under Jaku Essentials (which houses that particular icon), the default Jaku icon will be used to theme the app. By making use of this feature, you can mix and match icons without destroying an author’s theme and will find keeping track of your changes much, much easier.

Don’t just copy 10 different icons all named differently in hopes of getting something to work. If you are trying to theme the Camera app and call your file name Icon@2x.png, but it doesn’t work, don’t just copy the file and rename it icon@2x.png, Camera@2x.png, app-icon@2x.png or whatever else you may “think” it might be. Eventually you may get it to work, but you’ll have 12 different files on your device and when you come back to it down the line, you won’t know which one is the right one.

WinterBoard only needs one file: the right one. If you don’t get it, relax and calmly grab the info from the payload or the Info.plist (a lot of people often mess up on the cases, calling a bundle com.apple.reminders when it should be com.apple.Reminders). Always ensure you have the right file and the right name. You’ll have a much cleaner device with a lot less wasted space.

Do learn a bit about Unix file structure and basic architecture. If this is proving too technical, that’s because it is. We all want pretty phones, but if you want to muddle with the filesystem, you’ll have to start learning how things work. You won’t need to actually learn code, but you’ll have to know what a symlink is or what rwxrwxr-x means. So many people gloss over the rudimentary stuff hoping to comprehend the advanced stage, but that’s just like trying to run before you can crawl.

In the next article in this exclusive series, William Szilveszter will talk about SSH and take a deeper look inside the iOS filesystem to theme more than application icons. Szilveszter is a pixel-perfect graphic designer from Vancouver, British Columbia, Canada, available for hire on his website. He is also the creator of the highly popular Cydia theme Jaku for jailbroken iPhones, iPods and eventually iPads.

Post a response / What do you think?