Flipswitch: Difference between revisions

From iPhone Development Wiki
m (→‎Simple method: Info.plist example link.)
(→‎How to make a template bundle: Added "blendMode" key)
Line 222: Line 222:
| cutoutBlur || float || Blur for cutout mask. || 0.0 to 1.0 || 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
| color || string || Hex color for current layer. || "#000000" to "#FFFFFF" || "#000000" || ''type'' = "glyph" && ''filename'' = nil
|-
| blendMode || string || Blend mode for compositing layers. || ''CGBlendMode'' || kCGBlendModeNormal || ''type'' = "image"
|}
|}


Line 233: Line 235:
It is possible to use a <code>layer</code> for each state by creating new <code>layers</code> arrays named <code>layers-on</code>, <code>layers-off</code> or <code>layers-indeterminate</code>.
It is possible to use a <code>layer</code> for each state by creating new <code>layers</code> arrays named <code>layers-on</code>, <code>layers-off</code> or <code>layers-indeterminate</code>.


''For more information, see [https://github.com/a3tweaks/Flipswitch/blob/master/FSSwitchPanel.m#L307 this resource]''
The hex string in <code>color</code> is formatted #''RRGGBB''.


''To do: add [https://github.com/a3tweaks/Flipswitch/commit/382977bff27c8b1398575b9b23db7977cd1000a1 blendMode] key.''
For more information on existing blend modes and their effects, see [https://developer.apple.com/library/ios/documentation/GraphicsImaging/Reference/CGContext/index.html#//apple_ref/c/tdef/CGBlendMode Apple's documentation].


== How to show switches ==
== How to show switches ==

Revision as of 21:21, 21 September 2014

Flipswitch
Cydia Package
Developer Ryan Petrich, Jack Willis
Package ID libflipswitch
Latest Version 1.0.4


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 there are two methods, with or without code. It is recommended to add a glyph so your switch has a visual representation.

Simple method

This only requires an Info.plist added in your switch folder. This plist file should contain the basic keys for describing a bundle plus the following keys:

key type description
NSPrincipalClass string Class name to be used for the switch.
defaults string User defaults associated with this switch.
key string Key to be modified on the switch's defaults.
default string Default value of the switch.
negate array Save the opposite value.
PostNotification string Notification string to be posted when a change happens.
alternate-action-url string URL to be opened when holding the switch.
lazy-load BOOL Use FSLazySwitch as NSPrincipalClass if set to true.

Set NSPrincipalClass to FSPreferenceSwitchDataSource for your switch.

See AirplaneMode and other switches for reference.

Advanced method

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. Here's a sample of a basic switch implementation template:

// Return the current state of the switch.
- (FSSwitchState)stateForSwitchIdentifier:(NSString *)switchIdentifier {
        return (getSwitchState())?FSSwitchStateOn:FSSwitchStateOff;
}

// Set a new state for the switch.
- (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;
}

// Provide a proper title instead of its bundle ID:
- (NSString *)titleForSwitchIdentifier:(NSString *)switchIdentifier {
	return @"my switch";
}

// Do something different when holding the switch
- (void)applyAlternateActionForSwitchIdentifier:(NSString *)switchIdentifier {
	// ...
	return;
}

If - (void)applyAlternateActionForSwitchIdentifier:(NSString *)switchIdentifier; is not implemented, Flipswitch will try to open a URL specified in the "alternate-action-url" key inside the Resources/Info.plist file

You will find the protocol with the list of methods to implement in FSSwitchDataSource.h located in your switch folder.

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 provide preferences

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
blendMode string Blend mode for compositing layers. CGBlendMode kCGBlendModeNormal type = "image"

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.

The hex string in color is formatted #RRGGBB.

For more information on existing blend modes and their effects, see Apple's documentation.

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?)

External links