("How to use this library" standardization) |
(Reordering and added another example tweak) |
||
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. | 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 == | ||
To make a switch you should: implement the code, set a secondary action (optional) and create a glyph. | To make a switch you should: implement the code, set a secondary action (optional) and create a glyph. | ||
=== Implementing the Code === | === Implementing the Code === | ||
Save [https://github.com/a3tweaks/Flipswitch/raw/master/NIC%20Template/iphone_flipswitch_switch.nic.tar this NIC template] to the <code>$THEOS/templates/iphone</code> directory and call <code>$THEOS/bin/nic.pl</code> to get a premade switch. Once built, it will be installed to <code>/Library/Switches/</code>. | Save [https://github.com/a3tweaks/Flipswitch/raw/master/NIC%20Template/iphone_flipswitch_switch.nic.tar this NIC template] to the <code>$THEOS/templates/iphone</code> directory and call <code>$THEOS/bin/nic.pl</code> to get a premade switch. Once built, it will be installed to <code>/Library/Switches/</code>. | ||
There will be 2 methods already written in <code>Switch.x</code>. | There will be 2 methods already written in <code>Switch.x</code>. | ||
The first one will return the current state of the switch. Here's an example: | The first one will return the current state of the switch. Here's an example: | ||
<source lang="c"> | <source lang="c"> | ||
- (FSSwitchState)stateForSwitchIdentifier:(NSString *)switchIdentifier | - (FSSwitchState)stateForSwitchIdentifier:(NSString *)switchIdentifier | ||
Line 24: | Line 28: | ||
} | } | ||
</source> | </source> | ||
Where <code>getSwichState()</code> returns a BOOL. | Where <code>getSwichState()</code> returns a BOOL. | ||
The second method will set a new state for the switch. Here's another example: | The second method will set a new state for the switch. Here's another example: | ||
<source lang="c"> | <source lang="c"> | ||
- (void)applyState:(FSSwitchState)newState forSwitchIdentifier:(NSString *)switchIdentifier | - (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; | |||
} | } | ||
</source> | </source> | ||
Aditionally, you can add this method so your switch has a proper title instead of its bundle ID | Aditionally, you can add this method so your switch has a proper title instead of its bundle ID: | ||
<source lang="c"> | <source lang="c"> | ||
- (NSString *)titleForSwitchIdentifier:(NSString *)switchIdentifier { | - (NSString *)titleForSwitchIdentifier:(NSString *)switchIdentifier { | ||
return @"my switch"; | |||
} | } | ||
</source> | </source> | ||
Line 54: | Line 61: | ||
=== Secondary action === | === Secondary action === | ||
In the file <code>Resources/Info.plist</code> 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 <code>- (void)applyAlternateActionForSwitchIdentifier:(NSString *)switchIdentifier;</code> is not implemented. The default value is "prefs:". | In the file <code>Resources/Info.plist</code> 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 <code>- (void)applyAlternateActionForSwitchIdentifier:(NSString *)switchIdentifier;</code> is not implemented. The default value is "prefs:". | ||
Line 60: | Line 68: | ||
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 <code>on</code> state and one for <code>off</code> state) as black vector images with transparent background. Then, save those vector images as PDF and name them <code>glyph.pdf</code> for the <code>on</code> state and <code>glyph-off.pdf</code> for the <code>off</code> state. You should then move these PDFs to your <code>Resources</code> folder, where an <code>Info.plist</code> file resides. | 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 <code>on</code> state and one for <code>off</code> state) as black vector images with transparent background. Then, save those vector images as PDF and name them <code>glyph.pdf</code> for the <code>on</code> state and <code>glyph-off.pdf</code> for the <code>off</code> state. You should then move these PDFs to your <code>Resources</code> folder, where an <code>Info.plist</code> file resides. | ||
== PreferenceLoader == | |||
=== Simple Approach === | |||
Add the following dictionary to your PreferenceLoader plist to make use of the Flipswitch preference bundle: | |||
<source lang="c"> | |||
<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> | |||
</source> | |||
Extra keys for optimal usage: | |||
{| class="wikitable" | |||
|- | |||
! 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 | |||
|} | |||
== How to make a template bundle == | == 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 <code>Info.plist</code> file and optionally image files. Here is an example of an <code>Info.plist</code>, taken from [https://github.com/rpetrich/SwitchIcons/blob/master/layout/Library/Application%20Support/SwitchIcons/IconTemplate.bundle/Info.plist SwitchIcons]: | 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 <code>Info.plist</code> file and optionally image files. Here is an example of an <code>Info.plist</code>, taken from [https://github.com/rpetrich/SwitchIcons/blob/master/layout/Library/Application%20Support/SwitchIcons/IconTemplate.bundle/Info.plist SwitchIcons]: | ||
<source lang="xml"> | <source lang="xml"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||
Line 114: | Line 169: | ||
<code>layers</code> array can contain dictionaries with the following keys: | <code>layers</code> array can contain dictionaries with the following keys: | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
Line 146: | Line 202: | ||
<code>layers</code> are applied to the button one over the other. | <code>layers</code> are applied to the button one over the other. | ||
If <code>type</code> is "image", the current layer will draw the image found in <code>filename</code>. Best use of this layer could be as a background. | If <code>type</code> is "image", the current layer will draw the image found in <code>filename</code>. Best use of this layer could be as a background. | ||
If <code>type</code> is "glyph", the current layer will use the switch glyph as a mask. When <code>state</code> is present, the <code>layer</code> will select the glyph for said state. If <code>cutout</code> is true, the layer will be composed of only the glyph's borders. | If <code>type</code> is "glyph", the current layer will use the switch glyph as a mask. When <code>state</code> is present, the <code>layer</code> will select the glyph for said state. If <code>cutout</code> is true, the layer will be composed of only the glyph's borders. | ||
Line 156: | Line 214: | ||
The following code can be used to retrieve the full list of switches that '''FlipSwitch''' knows about: | The following code can be used to retrieve the full list of switches that '''FlipSwitch''' knows about: | ||
<source lang="objc"> | <source lang="objc"> | ||
NSBundle *templateBundle = [NSBundle bundleWithPath:@"/path/to/bundle.bundle"]; | NSBundle *templateBundle = [NSBundle bundleWithPath:@"/path/to/bundle.bundle"]; | ||
Line 166: | Line 225: | ||
''Explain how to retrieve the switches from the settings bundle ([https://github.com/uroboro/FlipNC/blob/master/FlipNCController.m#L77 start from here maybe?])'' | ''Explain how to retrieve the switches from the settings bundle ([https://github.com/uroboro/FlipNC/blob/master/FlipNCController.m#L77 start from here maybe?])'' | ||
== External links == | == External links == | ||
Line 214: | Line 231: | ||
* [https://github.com/rpetrich/SwitchIcons On-SpringBoard example usage, SwitchIcons] | * [https://github.com/rpetrich/SwitchIcons On-SpringBoard example usage, SwitchIcons] | ||
* [https://github.com/r-plus/SleipnizerFlipswitch Sample code of Toggle for tweak, SleipnizerFlipswitch] | * [https://github.com/r-plus/SleipnizerFlipswitch Sample code of Toggle for tweak, SleipnizerFlipswitch] | ||
* [https://github.com/uroboro/FlipNC NC widget using templates, showing switches and PreferenceLoader plist, FlipNC] | |||
[[Category:Cydia packages]] | [[Category:Cydia packages]] |
Revision as of 13:59, 11 June 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.
PreferenceLoader
Simple Approach
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 |
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?)