This is not a beginner’s a article, and this is not a tutorial. This is just the technical aspects of Sideswitch Toggles (a tutorial may soon follow). If you have never written an App Store app or you don’t the basics of jailbreak development (IE: The THEOS makefile).
Please note that there is no “Sideswitch Template” for THEOS yet as I haven’t made one, but with this article you will be able to build Sideswitch Toggles without the need of a template – Maybe, maybe I will create a nic.tar template for it in the future, but if you feel like doing it before me, please go ahead and let me know so other people can use it too.
1) A Note on the name, “Sideswitch Toggles”
When I first started writing Sideswitch Toggles, the original name was “Cydeswitch Toggles”, as I believe it is a very clever name for this toggle. But, when I first attempted to submit it to BigBoss Repo, I was told that no other devs use “Cy-” anywhere on their tweak names as a “respect to Saurik”. I respect Saurik for everything he has done, so I have changed the name to “Sideswitch Toggles” ever since. All the work was done when I attempted to publish it, so it will be common to find the word “Cydeswitch” instead of “Sideswitch” anywhere in this article, as it will be in all the Source Code I have published for this project. Please just ignore the “Cy-” and consider “Cydeswitch” was the beta name of this project.
Some things have been kept due to legacy issues: All the default toggles that were made at first were developed during the “Beta” stage of the tweak, so their identifiers and many other resources contain “Cydeswitch” in their names and in other places. Sideswitch toggles require to comply with the “Cydeswitch” protocol, and this won’t be changed in the near future. Finally, by convention, but not enforced, all Sideswitch Toggles begin their names with “CT” (CTAirplaneMode, CTWiFiToggle, etc..), this is also a legacy convention from the original name. CT stands for Cydeswitch Toggle.
2) Extensible Architecture.
Sideswitch Toggles is just one of the many toggles that can be extended by developers on Cydia. Sideswitch’s extensible architecture is pretty simple. Ultimately all your code and resources are compiled into a simple .bundle that can later be used by the Sideswitch tweak to execute your toggle’s code.
All toggles are installed in the /Library/Sideswitch/plugins directory. This is a hard coded directory and it cannot be changed by the user. This “forced” directory is there to facilitate the installation and removal of Sideswitch bundles. If not installed by Cydia, users can also simply SSH into their devices or access the device’s filesystem with other methods and move the .bundle files into this directory. Sideswitch will automatically pick up all the installed plugins and display them. This directory should be used exclusively by Sideswitch, and no other files should be put in it other than Sideswitch plugins.
3) Sideswitch Toggles Bundle And Bundle Structure.
At the very least, a Sideswitch bundle (we will simply call Sideswitch bundles “plugins” from now on, not to be confused with “plugins” in other context) contains two required files: The plugin binary to be executed when the switch is toggled, and an Info.plist file. You can include other files if necessary, by placing them in your project’s Resources directory.
Please note that bundles cannot be unloaded from memory. This is not a limitation imposed by myself or by Sideswitch but rather a limitation imposed by NSBundle. Sideswitch uses NSBundles to do it’s job, and as Apple states in its Bundle Programming Guide, once bundles are loaded, they cannot be unloaded. One way to go around this is to Respring the device. For this reason, it is very, very important that your plugin is as light-weight as possible, and that you don’t leak memory. If your plugin leaks memory, the system leaks memory, and that leads to system crashes. Most trivial tweaks won’t have to worry about this. Avoid heavy resources such as big images or sounds.
4) The Info.plist File.
The Info.plist file should at the very least include two keys:
* CFBundleExecutable: This is the name of the Executable. It’s recommended this key is present in the Info.plist, but if it isn’t, Sideswitch will look for an executable named like the bundle without the “.bundle” extension. If your bundle is called MyPlugin.bundle, Sideswitch will look for and try to execute MyPlugin (A default behaviour of NSBundle). It is recommended that this Key, the .bundle name, and the executable name have the same name.
* CFBundleDisplayName: This key is required. This key holds the string that will be displayed in the UITableViewCell in Sideswitch’s Settings page. If this key is missing, your plugin’s cell will be empty with no text. You can add other keys as you see fit, but keep in mind Sideswitch will have nothing to do with them. It is recommended but not required to add a key showing the current version of the plugin, but that can also be done in the package’s control file.
5) Developing Sideswitch Toggles.
Since there is no Sideswitch template at the time of this writing, you have to build the project’s structure yourself. Hopefully this will change in the future. Sideswitch Toggles projects have at the very least the following structure:
- control - theos (symlink to the THEOS install directory). - Resources/ -- Info.plist - Makefile - Sideswitch.h - [YourMainClass].mm
5.1) The Control File.
The control file here is like any other control file for a Cydia package.
The symlink to THEOS as present in all other THEOS projects.
5.3) The Resources Directory.
Like any other project type, all the files you want to be present in the plugin itself are to be put here. Your Info.plist file should be placed here.
5.4) The Basic Makefile.
Like all THEOS projects, Sideswitch Toggles projects require a Makefile. The Makefile is very minimal and it requires at least these five lines:
include theos/makefiles/common.mk BUNDLE_NAME = [THE BUNDLE NAME] * [THE BUNDLE NAME]_FILES = [ALL YOUR COMPILABLE FILES] ** [THE BUNDLE NAME]_INSTALL_PATH = /Library/Sideswitch/plugins include $(THEOS_MAKE_PATH)/bundle.mk
Asterisks are not part of the Makefile. They mean the following:
* : The bundle name will be the physical name of the bundle. [YOUR BUNDLE NAME].bundle
** : All the linkable files for your project, including your main .m file.
5.5) The Sideswitch.h File.
The Sideswitch header contains the “Cydeswitch” protocol. This file is required and your main class must conform to it. Here is the Cydeswitch Protocol:
@protocol Cydeswitch @required -(void)ringerHasBeenMuted; -(void)ringerHasBeenUnmuted; @optional -(NSNumber *)shouldBeMuted; -(NSNumber *)shouldBeUnmuted; -(void)ringerWillBeMuted; -(void)ringerWillBeUnmuted; @end
Since your main class must conform to this protocol, it is required to implement the -(void)ringerHasBeenMuted and -(void)ringerHasBeenUnmuted methods. You can deduce their use fairly easily: The former method is called when the user sets their phone to “silent”, AKA when the hardware switch is “orange. The latter is called when the opposite is true: When the user wants the toggle to be “on” and when the hardware switch is “gray”. You can optionally implement other methods: -(NSNumber *)shouldBeMuted -(NSNumber *)shouldBeUnmuted These two methods will be called when the switch is toggled, but the actual software toggling will be decided by your code whether it should execute or not. Please note that these methods return NSNumber and not BOOL: This is because the compiler doesn’t like it when you deal with anything else other than Objective-C in this context (BOOL is not an Objective-C data type). These methods should therefore return an NSNumber initialized with numberWithBool:
return [NSNumber numberWithBool:YES];
If you don’t implement these methods they are assumed to return YES by default. The other optional methods are:
These methods are called before the actual toggling takes place. Use them if your tweak requires an overhead or “extra work” to work properly.
4.6) Your Main Class File.
Your main class is required otherwise you won’t have a plugin at all. Like stated earlier, it needs to conform to the Cydeswitch protocol. Your main class is responsible for actually toggling things in the system. You can of course add more source code as you need, and files, but this is the very minimum required to write Sideswitch toggles.
After reading this, you should be ready to write your own Sideswitch toggles. A “template” (not really a template – More like the directory structure) for Sideswitch Toggles projects can be downloaded from my Github (check Downloads tab). Make sure you modify all the files that are in ALL CAPS.
For better understanding, you can download the source for all the default toggles included with Sideswitch: Airplane Mode, Wi-Fi, Bluetooth, and Do Not Disturb. They are collectively stored in a super bundle called CTPremiumPack. You can find it in the Downloads tab.
Jan 4, 2014 at 4:20 PM (America/La_Paz): Fixed the article’s markup and sourcecode tags.
May 26, 2013 at 12:50 AM (America/La_Paz): Changed all appearances of “Cydeswitch” to “Sideswitch”. Other pre-publication fixes.
May 9, 2013 at 8:30 PM (America/La_Paz): First version of this document.