(Simplify example to use autoreleased objects and properties) |
("How to use this library" standardization) |
||
Line 8: | Line 8: | ||
== How to use this library == | == How to use this library == | ||
Headers are available from [https://github.com/a3tweaks/Flipswitch/tree/master/public Flipswitch's GitHub project] and the library can be found at <code>/usr/lib/libflipswitch.dylib</code> on a device where Flipswitch is installed. If using Theos, place the headers in <code>$THEOS/include/flipswitch</code>, the library in <code>$THEOS/lib/</code> and add <code>flipswitch</code> to the <code>XXX_LIBRARIES</code> Makefile variable. | |||
== How to make a new switch == | == How to make a new switch == |
Revision as of 23:39, 26 May 2014
Flipswitch | |
Cydia Package | |
---|---|
Developer | Ryan Petrich, Jack Willis |
Package ID | libflipswitch |
Latest Version | 1.0.3 |
libflipswitch is a library used to implement a centralized toggle system. Flipswitch switches (or toggles) can be used as extensions of existing tweaks to provide an interface to enable/disable them.
How to use this library
Headers are available from Flipswitch's GitHub project and the library can be found at /usr/lib/libflipswitch.dylib
on a device where Flipswitch is installed. If using Theos, place the headers in $THEOS/include/flipswitch
, the library in $THEOS/lib/
and add flipswitch
to the XXX_LIBRARIES
Makefile variable.
How to make a new switch
To make a switch you should: implement the code, set a secondary action (optional) and create a glyph.
Implementing the Code
Save this NIC template to the $THEOS/templates/iphone
directory and call $THEOS/bin/nic.pl
to get a premade switch. Once built, it will be installed to /Library/Switches/
.
There will be 2 methods already written in Switch.x
.
The first one will return the current state of the switch. Here's an example:
- (FSSwitchState)stateForSwitchIdentifier:(NSString *)switchIdentifier
{
return (getSwitchState())?FSSwitchStateOn:FSSwitchStateOff;
}
Where getSwichState()
returns a BOOL.
The second method will set a new state for the switch. Here's another example:
- (void)applyState:(FSSwitchState)newState forSwitchIdentifier:(NSString *)switchIdentifier
{
switch (newState) {
case FSSwitchStateIndeterminate:
break;
case FSSwitchStateOn:
//enable your tweak
break;
case FSSwitchStateOff:
//disable your tweak
break;
}
return;
}
Aditionally, you can add this method so your switch has a proper title instead of its bundle ID.
- (NSString *)titleForSwitchIdentifier:(NSString *)switchIdentifier {
return @"my switch";
}
You will find the protocol with the list of methods to implement in FSSwitchDataSource.h
located in your switch folder.
Secondary action
In the file Resources/Info.plist
you can find the key "alternate-action-url", which will enable you to open a URI when the secondary action of the switch is invoked, in case - (void)applyAlternateActionForSwitchIdentifier:(NSString *)switchIdentifier;
is not implemented. The default value is "prefs:".
Glyphs
Glyphs are the visual part of the switch that should represent your switch's state. To create one, you have to create at least two icons (one for on
state and one for off
state) as black vector images with transparent background. Then, save those vector images as PDF and name them glyph.pdf
for the on
state and glyph-off.pdf
for the off
state. You should then move these PDFs to your Resources
folder, where an Info.plist
file resides.
How to make a template bundle
These bundles contain information about how a switch glyph (the image that the user sees for a given switch) is rendered when it is used in a button returned by the appropriate method of the FlipSwitch panel. Bundles contain an Info.plist
file and optionally image files. Here is an example of an Info.plist
, taken from SwitchIcons:
<?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>CFBundleDevelopmentRegion</key>
<string>English</string>
<key>CFBundleIdentifier</key>
<string>com.rpetrich.switchicon.icon-template</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundlePackageType</key>
<string>BNDL</string>
<key>CFBundleShortVersionString</key>
<string>1.0.0</string>
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>DTPlatformName</key>
<string>iphoneos</string>
<key>MinimumOSVersion</key>
<string>2.0</string>
<key>width</key>
<integer>59</integer>
<key>height</key>
<integer>60</integer>
<key>layers</key>
<array>
<...>
</array>
</dict>
</plist>
Keys not specified in the following table can use the same values as the example given.
key | type | meaning | |
---|---|---|---|
CFBundleIdentifier | string | Template bundle identifier. | |
width | integer | Width of the icon. | |
height | integer | Height of the icon. | |
layers | array | ... of dictionaries | Change visuals of switch glyph. |
layers
array can contain dictionaries with the following keys:
key | type | meaning | range of values | default value | depends |
---|---|---|---|---|---|
type | string | Layer type. | "image", "glyph" | - | - |
opacity | float | Alpha value for current layer. | 0.0 to 1.0 | 1.0 | - |
x | float | X value for offset position. | - | 0.0 | - |
y | float | Y value for offset position. | - | 0.0 | - |
fileName | string | Image filename without extension. | - | - | - |
blur | float | Blur value for current layer. | 0.0 to 1.0 | 0.0 | type = "glyph" |
size | float | Glyph size. | - | 0 | type = "glyph" |
state | string | Switch state filter. | "on", "off", "indeterminate" | - | type = "glyph" |
cutout | BOOL | Cutout mask flag. | - | NO | type = "glyph" |
cutoutX | float | X offset for cutout mask. | - | 0.0 | type = "glyph" && cutout = YES |
cutoutY | float | Y offset for cutout mask. | - | 0.0 | type = "glyph" && cutout = YES |
cutoutBlur | float | Blur for cutout mask. | 0.0 to 1.0 | 0.0 | type = "glyph" && cutout = YES |
color | string | Hex color for current layer. | "#000000" to "#ffffff" | "#000000" | type = "glyph" && filename = nil |
layers
are applied to the button one over the other.
If type
is "image", the current layer will draw the image found in filename
. Best use of this layer could be as a background.
If type
is "glyph", the current layer will use the switch glyph as a mask. When state
is present, the layer
will select the glyph for said state. If cutout
is true, the layer will be composed of only the glyph's borders.
It is possible to use a layer
for each state by creating new layers
arrays named layers-on
, layers-off
or layers-indeterminate
.
For more information, see this resource
How to show switches
The following code can be used to retrieve the full list of switches that FlipSwitch knows about:
NSBundle *templateBundle = [NSBundle bundleWithPath:@"/path/to/bundle.bundle"];
FSSwitchPanel *fsp = [FSSwitchPanel sharedPanel];
for (NSString *identifier in fsp.switchIdentifiers) {
UIButton *button = [fsp buttonForSwitchIdentifier:identifier usingTemplate:templateBundle];
// ... now you have a button with the style described by the template bundle that you can add to any view
}
Explain how to retrieve the switches from the settings bundle (start from here maybe?)
How to use the Preference Bundle
Add the following dictionary to your PreferenceLoader plist to make use of the Flipswitch preference bundle:
<dict>
<key>cell</key>
<string>PSLinkCell</string>
<key>label</key>
<string>Active Switches</string>
<key>isController</key>
<true/>
<key>bundle</key>
<string>FlipswitchSettings</string>
</dict>
Extra keys for optimal usage:
key | type | description |
---|---|---|
flipswitchTemplateBundle | string | absolute path to a bundle containing a flipswitch template bundle |
flipswitchSettingsFile | string | absolute file path to a settings file |
flipswitchPostNotification | string | notification string to be posted when a change happens |
flipswitchEnabledKey | string | key for array of enabled switches |
flipswitchDisabledKey | string | key for array of disabled switches |
flipswitchDefaultEnabled | array | array of switch identifiers that are in the enabled section by default |
flipswitchDefaultDisabled | array | array of switch identifiers that are in the disabled section by default |
flipswitchSettingsMode | string | set to "enabling" for checkable cells or "reordering" for draggable cells |
flipswitchNewAreDisabled | BOOL | switches not present previously settings file are added to the disabled switches array, if false, they are added to the enabled switches array |
flipswitchThemedInfoDictionary | string | absolute path to a template bundle |