KarenPrefs is a library that provides various conveniences and enhancements for developers seeking to create preference bundles for their iOS tweaks.
I originally wrote KarenPrefs back in 2013 for use with my tweak mikoto, but only thought about open-sourcing it recently, since I've found it rather useful (especially for when I need to show/hide specifiers according to iOS version, something I use often in mikoto).
KarenPrefs is BSD-licensed. See LICENSE
for more information.
KarenPrefs setup and usage (assuming you already have the latest version of Theos)
git clone https://github.com/angelXwind/KarenPrefs.git
cd KarenPrefs/
make setup
-
In your project's
Makefile
, addkarenprefs
to yourTweakName_LIBRARIES
variable. -
In your project's
control
file, addnet.angelxwind.karenprefs
to theDepends:
field.
This is a PSListController
subclass that basically carries the weight of KarenPrefs' functionality.
In it, I implemented full support for PreferenceLoader's CoreFoundationVersion filters, which is very useful for hiding/showing features according to iOS version.
That aside, I also added a few additional methods.
Here is a description of its basic methods:
-
-(NSString *) karenPrefsLoadFromPlist
— Override this method and return the filename (without.plist
extension) of your desired plist that you want to load specifiers from. Defaults tonil
if not set. This is the only thing you really need to override if you only desire basic functionality (with use of PreferenceLoader filters, etc.) from KarenPrefs. -
-(BOOL) shouldBypassCfprefsd
— If this is overriden to return1
, KarenPrefs will read and write directly from yourplist
file, bypassingcfprefsd
. Use this if you're loading your tweak's preferences directly from yourplist
on iOS 8+. If you usecfprefsd
in your tweak, set this value to0
. Defaults to1
if not set. -
-(NSString *) karenPrefsNavbarIconLoadFromImage
— Override this method and return the filename (without.png
extension) of your desired PNG image that you want to display in the navigation bar. Defaults tonil
if not set. -
-(void) respring
— When called, resprings the device intelligently (killsbackboardd
if running on iOS 6 and above, killsSpringBoard
if running on iOS 5 and below).
Here is a description of its extra "convenience" methods (I use these for the "Credits" views in my tweaks' preferences):
-
-(NSString *) karenPrefsDonateURL
— Override this method and return an URL that you want to open using-(void) openDonate
. -
-(void) openDonate
— When called, opens the URL defined in-(NSString *) karenPrefsDonateURL
in the web browser. Does nothing if-(NSString *) karenPrefsDonateURL
isnil
. -
-(NSString *) karenPrefsSiteURL
— Override this method and return an URL that you want to open using-(void) openSite
. -
-(void) openSite
— When called, opens the URL defined in-(NSString *) karenPrefsSiteURL
in the web browser. Does nothing if-(NSString *) karenPrefsSiteURL
isnil
. -
-(NSString *) karenPrefsRepoURL
— Override this method and return an Cydia/APT repo URL that you want to open using-(void) openRepo
. -
-(void) openRepo
— When called, opens the Cydia/APT repo URL defined in-(NSString *) karenPrefsRepoURL
in the Cydia. If Cydia is not installed (...for whatever reason), then it will display the repo URL in anUIAlertView
. Does nothing if-(NSString *) karenPrefsRepoURL
isnil
. -
-(NSString *) karenPrefsTwitterUsername
— Override this method and return a Twitter username (without the@
username prefix) that you want to open using-(void) openTwitter
. -
-(void) openTwitter
— When called, opens the Twitter username defined in-(NSString *) karenPrefsTwitterUsername
in the official Twitter app. If the Twitter app is not installed, then it will open Twitter's web UI in the system's default browser instead. Does nothing if-(NSString *) karenPrefsTwitterUsername
isnil
. -
-(NSString *) karenPrefsDeviantArtUsername
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) Override this method and return a deviantArt username that you want to open using-(void) openDeviantArt
. -
-(void) openDeviantArt
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) When called, opens the deviantArt username defined in-(NSString *) karenPrefsDeviantArtUsername
in the official deviantArt app. If the deviantArt app is not installed, then it will open deviantArt's web UI in the system's default browser instead. Does nothing if-(NSString *) karenPrefsDeviantArtUsername
isnil
. -
-(NSString *) karenPrefsGitHubUsername
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) Override this method and return a GitHub username that you want to open using-(void) openGitHub
. -
-(void) openGitHub
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) When called, opens the GitHub username defined in-(NSString *) karenPrefsGitHubUsername
in the system's default browser. Does nothing if-(NSString *) karenPrefsGitHubUsername
isnil
. -
-(NSString *) karenPrefsPixivID
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) Override this method and return a Pixiv ID that you want to open using-(void) openPixiv
. -
-(void) openPixiv
— When called, opens the Pixiv ID defined in-(NSString *) karenPrefsPixivID
in the system's default browser. Does nothing if-(NSString *) karenPrefsPixivID
isnil
. -
-(NSString *) karenPrefsTumblrUsername
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) Override this method and return a Tumblr username that you want to open using-(void) openTumblr
. -
-(void) openTumblr
— Requires KarenPrefs version 1.3 or higher. (Depends: net.angelxwind.karenprefs (>= 1.3)
) When called, opens the Tumblr username defined in-(NSString *) karenPrefsTumblrUsername
in the official Tumblr app. If the Tumblr app is not installed, then it will open Tumblr's web UI in the system's default browser instead. Does nothing if-(NSString *) karenPrefsTumblrUsername
isnil
. -
-(UIColor *) karenPrefsCustomTintColor
— Requires KarenPrefs version 1.2 or higher. (Depends: net.angelxwind.karenprefs (>= 1.2)
) Override this method and return anUIColor
to change the tint color of your preference pane. Defaults tonil
if not set.
This is a PSTableCell
subclass that sets an image as its own background.
Override -(NSString *) karenPrefsBannerLoadFromImage
in your subclass's implementation to specify the filename of the PNG image (without the extension!) in your preference bundle that will be used as a banner.
In order to support the entire range of displays, you must have the following variations present in your bundle:
-
Non-Retina Display (iPhone 3GS, etc.):
exampleBanner.png
-
Retina Display (iPhone 4, 5, etc.):
exampleBanner@2x.png
-
4.7-inch Retina HD (iPhone 6, etc.):
exampleBanner-667h@2x.png
-
5.5-inch Retina HD (iPhone 6 Plus, etc.):
exampleBanner@3x.png
-
Super Retina HD Display (iPhone X):
exampleBanner-812h@3x.png
The height can be modified via your specifier plist by adding the height
key/value pair in your property list. (Example: <key>height</key><integer>205</integer>
)
This adds the -(void) animatedExit
method to UIApplication
which when called, will gracefully close the Preferences app with the native iOS "closed app" animation, then terminate the process.
This is a PSTableCell
subclass that has a configurable text color.
Override -(UIColor *) karenPrefsCustomTextColor
in your subclass's implementation to specify the text color of the cell.
This is a KarenPrefsCustomTextColorButtonCell
subclass that changes the text color to black.
Useful if you want a PSButtonCell
on iOS 7 and above with black text instead of the default blue.
This is a KarenPrefsCustomTextColorButtonCell
subclass that changes the text color to red.
Useful for buttons that perform destructive operations (such as "Reset Settings" buttons).
This is a KarenPrefsCustomTextColorButtonCell
subclass that changes the text color to green.
Useful for donation buttons.
This is a KarenPrefsCustomTextColorButtonCell
subclass that changes the text color to purple.
Tested to work on iOS 6/7/8/9/10/11/12/13. Requires KarenPrefs version 1.2 or higher. (Depends: net.angelxwind.karenprefs (>= 1.2)
)
This is a PSSwitchCell
subclass that has a configurable switch color.
Override -(UIColor *) karenPrefsCustomSwitchColor
in your subclass's implementation to specify the color to set the switch to.
Tested to work on 7/8/9/10/11/12/13. Requires KarenPrefs version 1.4 or higher. (Depends: net.angelxwind.karenprefs (>= 1.4)
)
This is a PSListItemsController
subclass that has a configurable tint color.
Override -(UIColor *) karenPrefsCustomTintColor
in your subclass's implementation to specify the color to set the tint color to.
Tested to work on iOS 6/7/8/9/10/11/12/13. Requires KarenPrefs version 1.2 or higher. (Depends: net.angelxwind.karenprefs (>= 1.2)
)
Note that while this does not work on iOS 5, if the preference pane you are using this in also supports iOS 5, you must add -F$(SYSROOT)/System/Library/PrivateFrameworks -weak_framework Preferences
to your TweakName_LDFLAGS
Makefile variable to avoid a crash.
This is a PSSwitchTableCell
subclass that is in a perpetual "on" state. When tapped, the switch will animate itself "bouncing back" to the on state.
In order for this to function properly, you must override -(NSString *) karenPrefsBounceBackObserverName
with the name of an NSNotificationCenter
observer. The way this works is that when the observer is called, the switch will be set to the "on" state.
Useful for communicating to users that there are options that cannot be disabled and are always enabled.
Tested to work on iOS 6/7/8/9/10/11/12/13. Requires KarenPrefs version 1.2 or higher. (Depends: net.angelxwind.karenprefs (>= 1.2)
)
This is a KarenPrefsBounceBackSwitchCell
subclass that has a configurable switch color.
Override -(UIColor *) karenPrefsCustomSwitchColor
in your subclass's implementation to specify the color to set the switch to.
This is a PSEditableTableCell
subclass that just sets -textFieldShouldReturn:textfield
to 1
. For more information on what -(BOOL) textFieldShouldReturn:(UITextField *)textField
controls, consult Apple's official documentation.