Docs | WidgetCenter

Custom Widgets


I’m guessing you arrived here because you’re trying to create your own awesome WidgetCenter widget. If so, welcome! If not, well… I have no idea how you found this page. Creating widgets for WidgetCenter is incredibly simple; by the end of this guide you’ll be pro at it — at least you should be.

Getting Started


To make things even easier, I’ve created a theos NIC template that produces a bare-bones WCWidget project. You can download the template on the libwcwidget project page. If you have no idea what I’m talking about, chances are the rest of this guide won’t make any sense. Time for you to do some studying…

Still here? Awesome. Install the NIC template (copy it to theos/templates/iphone). Before we create a widget, we’re going to need to get a copy of libwcwidget. This is the library that all WCWidgets link against. You can copy the file from your jailbroken iOS device, or simply grab it from the libwcwidget project listed above. Once downloaded, place “libwcwidget.dylib” in your ‘theos/lib’ directory.

We’re ready to roll. You should now see the “iphone/wcwidget” option when you create a new theos project:

Alt text

Go through the prompts, cd into your project directory, make package install, and voila! You have a working WidgetCenter widget!

WCWidget Structure


A simplified breakdown of a WCWidget project is as follows:

WCExampleWidget

WCWidget.h
WCExampleWidget.h
WCExampleWidget.mm
Makefile
control
Resources

Info.plist
Settings.plist
Icon@2x.png

Everything here should be pretty straightforward. More information on widget structure can be found on the WidgetCenter API Reference page. One thing to take note of, WidgetCenter supports inline widget settings. Instead of creating a separate preference-bundle for your widget, settings contained in the “Settings.plist” file will automatically be added to WidgetCenter’s preference pane. Settings are optional, so omitting the file is totally fine too.

Feel free to explore your newly-created project. The best way to learn is to dive right in!

What Now?


The actual code behind a WCWidget is extremely easy to understand. The best way to learn is by simply looking at the default NIC project. As mentioned before, the WidgetCenter API Reference is also a valuable resource. The API reference contains all the code-related details you could ever want to know about the WCWidget class.