CepheiPrefs — List Controllers Reference


                    
                    
                    HBAboutListController

The HBAboutListController class in CepheiPrefs provides a list controller with functions that would typically be used on an “about” page. It includes two class methods you can override to provide a developer website and donation URL, and a class method to provide an email address so the user can send the developer an email right from the tweak’s settings.

There is a sample of an HBAboutListController implemented in the Cephei demo preferences. See the Cephei readme for details.

Example Usage

<dict>
    <key>cell</key>
    <string>PSLinkCell</string>
    <key>cellClass</key>
    <string>HBLinkTableCell</string>
    <key>label</key>
    <string>Visit Website</string>
    <key>url</key>
    <string>https://hashbang.productions/</string>
</dict>
<dict>
    <key>cell</key>
    <string>PSGroupCell</string>
    <key>label</key>
    <string>Experiencing issues?</string>
</dict>
<dict>
    <key>action</key>
    <string>hb_sendSupportEmail</string>
    <key>cell</key>
    <string>PSLinkCell</string>
    <key>label</key>
    <string>Email Support</string>
</dict>
<dict>
    <key>cell</key>
    <string>PSGroupCell</string>
    <key>footerText</key>
    <string>If you like this tweak, please consider a donation.</string>
</dict>
<dict>
    <key>cell</key>
    <string>PSLinkCell</string>
    <key>cellClass</key>
    <string>HBLinkTableCell</string>
    <key>label</key>
    <string>Donate</string>
    <key>url</key>
    <string>https://hashbang.productions/donate/</string>
</dict>

Declaration

Objective-C

@interface HBAboutListController : HBListController

Swift

class HBAboutListController : HBListController


                    
                    
                    HBListController

The HBListController class in CepheiPrefs provides a list controller with various conveniences such as a unique tint color for the list controllers within a preference bundle, and bug fixes for common issues within the Settings app and Preferences framework. In particular, a bug with the list controller’s content disappearing after closing the Settings app and opening it again is worked around, as well as an issue on iOS 7 where in some cases a cell may stay highlighted after being tapped.

It includes two class methods you can override to return the name of a Preferences specifier property list, and various methods to control appearance of the interface.

If you use HBLinkTableCell or subclasses such as HBTwitterCell and HBPackageTableCell, it is recommended to subclass from HBListController on the view controller classes containing these cells to use CepheiPrefs’s built-in callback actions. If you do not subclass from HBListController, you will need to implement action methods yourself.

Specifier Parameters

HBListController extends specifiers with the following parameters:

pl_filter	Optional. Supports additional filters that decide whether a specifier should be displayed, as specified below.
iconImageSystem	Optional. Supports displaying a system image as the cell icon, as specified below.
leftImageSystem	Optional. Supports displaying a system image as the icon to the left of a PSSliderCell’s slider control, as specified below.
rightImageSystem	Optional. Supports displaying a system image as the icon to the right of a PSSliderCell’s slider control, as specified below.

PreferenceLoader Filter Parameters

The pl_filter key is inherited from PreferenceLoader’s libprefs, and can be used to specify CoreFoundation version criteria for a specifier. Specifiers that do not meet the pl_filter criteria will be discarded.

The version number of CoreFoundation is often used as a stable method of checking the operating system version in use. It has the benefit of increasing in predictable amounts (to the next hundred or more) for each major revision of Apple’s OS platforms, and it is typically roughly the same between all Apple OS platforms at any point in time.

CoreFoundationVersion

Optional. An array of one or two CoreFoundation version numbers in decimal (<real>). If one number is present, this is a minimum bound. The current device’s CoreFoundation version must be greater than or equal to this number. If two numbers are present, the first number is the lower bound, and the second number is one more than the upper bound. The current device’s CoreFoundation version must be greater than or equal to the first number, and less than (but not equal to) the second number.

Example Usage

<!-- Will only display on iOS 12.0 (CF 1556.0) or newer: -->
<dict>
    <key>cell</key>
    <string>PSSwitchCell</string>
    <key>label</key>
    <string>My iOS 12+ Only Feature</string>
    <key>pl_filter</key>
    <dict>
        <key>CoreFoundationVersion</key>
        <array>
            <real>1556.00</real>
        </array>
    </dict>
</dict>

<!-- Will only display between iOS 7.0 (CF 847.20) and 12.0 (CF 1556.00): -->
<dict>
    <key>cell</key>
    <string>PSSwitchCell</string>
    <key>label</key>
    <string>My iOS 7-11 Only Feature</string>
    <key>pl_filter</key>
    <dict>
        <key>CoreFoundationVersion</key>
        <array>
            <real>847.20</real>
            <real>1556.00</real>
        </array>
    </dict>
</dict>

<!-- Will only display on versions earlier than iOS 12.0 (CF 1556.00): -->
<dict>
    <key>cell</key>
    <string>PSSwitchCell</string>
    <key>label</key>
    <string>My iOS &lt;12 Only Feature</string>
    <key>pl_filter</key>
    <dict>
        <key>CoreFoundationVersion</key>
        <array>
            <real>0.0</real>
            <real>1556.00</real>
        </array>
    </dict>
</dict>

System Icon Parameters

On iOS 13.0 and newer, you can specify a system icon (SF Symbols glyph) to be displayed in a cell. Use the SF Symbols app to find symbol names.

When running on iOS versions earlier than 13.0, icons will not be rendered. This also applies when a symbol name is specified that was added in a later iOS version than is currently in use. In this case, you can supply a PNG icon through the usual means as a fallback.

name	Required. The symbol name to use.
weight	Optional. The weight to render the symbol at. The supported values are: ultraLight, thin, light, regular, medium, semibold, bold, heavy, black. The default is regular.
scale	Optional. The scale to render the symbol at. The supported values are: small, medium, large. The default is medium.
pointSize	Optional. The equivalent font size to render the symbol at. The default is 20.0.
tintColor	Optional. The color to render the icon in. The default is no value, which means the tint color will be inherited from the -[HBAppearanceSettings tintColor]; if neither value is set, the default iOS blue tint color is used. When backgroundColor is set, no value means white (#ffffff) will be used.
backgroundColor	Optional. The background color to use for the symbol. When specified, the symbol will be rendered inside an icon shape of the specified background color. The symbol will be scaled down by 20% to appropriately fit the icon shape. The default is no value, which means no icon shape will be rendered.

Example Usage

<!-- A switch with a two switches symbol as its icon -->
<dict>
    <key>cell</key>
    <string>PSSwitchCell</string>
    <key>label</key>
    <string>Awesome</string>
    <key>iconImageSystem</key>
    <dict>
        <key>name</key>
        <string>switch.2</string>
    </dict>
</dict>

<!-- A link cell with an information symbol as its icon -->
<dict>
    <key>cell</key>
    <string>PSLinkCell</string>
    <key>detail</key>
    <string>HBDemoAboutListController</string>
    <key>isController</key>
    <true/>
    <key>label</key>
    <string>ABOUT</string>
    <key>iconImageSystem</key>
    <dict>
        <key>name</key>
        <string>info.circle</string>
    </dict>
</dict>

<!-- A slider cell with brightness sun symbols on the left and right -->
<dict>
    <key>cell</key>
    <string>PSSliderCell</string>
    <key>min</key>
    <real>1</real>
    <key>max</key>
    <real>15</real>
    <key>leftImageSystem</key>
    <dict>
        <key>name</key>
        <string>sun.min</string>
    </dict>
    <key>rightImageSystem</key>
    <dict>
        <key>name</key>
        <string>sun.max</string>
    </dict>
</dict>

<!-- A link cell with white heart symbol in a red icon shape -->
<dict>
    <key>cell</key>
    <string>PSButtonCell</string>
    <key>cellClass</key>
    <string>HBLinkTableCell</string>
    <key>label</key>
    <string>DONATE</string>
    <key>url</key>
    <string>https://hashbang.productions/</string>
    <key>iconImageSystem</key>
    <dict>
        <key>name</key>
        <string>heart</string>
        <key>backgroundColor</key>
        <string>#ff3b30</string>
    </dict>
</dict>

Declaration

Objective-C

@interface HBListController : PSListController

Swift

class HBListController : PSListController


                    
                    
                    HBRootListController

The HBRootListController class in CepheiPrefs provides a list controller class that should be used as the root of the package’s settings. It includes two class methods you can override to provide a default message and a URL that the user can share via a sharing button displayed to the right of the navigation bar.

It is recommended that you use this class even if its current features aren’t appealing in case of future improvements or code that relies on the presence of an HBRootListController.

Declaration

Objective-C

@interface HBRootListController : HBListController

Swift

class HBRootListController : HBListController


                    
                    
                    PSListController(HBTintAdditions)

The PSListController (HBTintAdditions) class category in CepheiPrefs provides a property for setting the desired appearance settings of the view controller.

Declaration

Objective-C

@interface PSListController (HBTintAdditions)