AltList

A modern AppList alternative

The main focus of this dependency is to be an easy to use and easy to customize framework to handle per app preferences. Unlike AppLists ALApplicationList class, AltList does not have a way to get installed applications yourself, as stock iOS classes like LSApplicationWorkspace and LSApplicationProxy (MobileCoreService / CoreServices framework) can already do that. Communication to SpringBoard is not needed for this.

Example uses:

// get LSApplicationProxy of all installed applications
NSArray<LSApplicationProxy*>* allInstalledApplications = [[LSApplicationWorkspace defaultWorkspace] atl_allInstalledApplications];

// get LSApplicationProxy for one application
LSApplicationProxy* appProxy = [LSApplicationProxy applicationProxyForIdentifier:@"com.yourapp.yourapp"];

Features

• Uses LSApplicationWorkspace, not dependent on RocketBootstrap / SpringBoard injection
• Supports search bars
• Supports application sections (similar to AppList)
• Supports alphabetic indexing if only one section is specified
• Doesn't reinvent the wheel
• Supports iOS 7 and up

Installation

Run install_to_theos.sh and add it to the makefile of your project:

<YOUR_PROJECT>_EXTRA_FRAMEWORKS = AltList

Then you can import it using #import <AltList/AltList.h> or just use the classes below in your preferences plist.

Documentation

AltList features three PSListController subclasses that can be used from your preference bundle or application. Unlike AppList it is highly customizable, so if you want to adapt something you can just make a subclass and specify that instead.

All classes can be configured via values in your plist.

Plist-Only approach

For very simple preferences, it is possible to use AltList straight from your entry.plist without implementing any class. For an example check out AltListTestBundlelessPreferences.

ATLApplicationSection

Just like the original AppList, AltList allows you to specify the sections of applications it should display.

AltList ships with a few stock section types:

• All: All Applications, including hidden ones
• System: System Applications (e.g. App Store, Safari)
• User: User installed applications (e.g. Reddit, Instagram)
• Hidden: Hidden applications (e.g. InCallService, Carplay Settings)
• Visible: All applications that are not hidden (e.g. System and User applications)

The stock section types already have predicates and localized names. Custom sections are also supported and allow you to specify your own section name and predicate. If you want your custom section name to be localized: the value you set will be passed to the localizedStringForString of your ListController (see below).

Key	Type	Fallback	Usage
sectionType	String (All/System/User/Hidden/Visible/Custom)	Visible	Type of the section, see above
sectionName	String	@""	For custom sections, name of the section
sectionPredicate	String	@""	For custom sections, predicate to filter the applications, check out the LSApplicationProxy headers for possible values to use
customClass	String	@""	Custom subclass of ATLApplicationSection to use, in case you want to implement even more custom behaviour

ATLApplicationListControllerBase

ATLApplicationListControllerBase is the base class inherited by the other classes, it has several features that apply to all classes below.

Keys

Key	Type	Fallback	Usage
sections	Array	One Visible section	Array of dictionaries that represent the sections in which the applications are shown
useSearchBar	Boolean	false	Whether there should be a search bar at the top that allows to search for applications (Example)
hideSearchBarWhileScrolling	Boolean	false	When useSearchBar is enabled, whether the search bar should be hidden while scrolling (Always true on iOS 10 and below) (Example)
includeIdentifiersInSearch	Boolean	false	When useSearchBar is enabled, whether it should be possible to search for apps by their identifier. When this is false, it is only possible to search for apps by their name.
showIdentifiersAsSubtitle	Boolean	false	Whether the application identifiers should be shown in the subtitle (Example)
alphabeticIndexingEnabled	Boolean	false	When there is only one section, whether to section and index it by the starting letters (Example)
hideAlphabeticSectionHeaders	Boolean	false	When alphabeticIndexingEnabled is true, whether to hide the sections that contain the first letters (Example)
localizationBundlePath	String	@""	Path to the bundle that should be used for localizing custom section titles

Methods (Can be overwritten by subclasses for customization)

Method	Purpose
- (void)loadPreferences	Load the preference value that the list controller will display
- (void)savePreferences	Save preferences when they have changed
- (void)prepareForPopulatingSections	Initialize stuff that needs to be done before the populating starts
- (NSString*)localizedStringForString:(NSString*)string	Localize string if possible from internal AltList bundle or the localization bundle specified by localizationBundlePath
- (void)reloadApplications	Reload applications and specifiers
- (BOOL)shouldHideApplicationSpecifiers	Whether any specifier at all should be hidden (internally used for search bar)
- (BOOL)shouldHideApplicationSpecifier:(PSSpecifier*)specifier	Whether the specifier specifier should be hidden (internally used for search bar)
- (BOOL)shouldShowSubtitles	Whether subtitles should be shown on the application cells
- (NSString*)subtitleForApplicationWithIdentifier:(NSString*)applicationID	The subtitle that should be displayed in the cell for the specific application that's passed as applicationID
- (PSCellType)cellTypeForApplicationCells	Cell type for the application cells
- (Class)customCellClassForCellType:(PSCellType)cellType	Custom cell class for the application cells
- (Class)detailControllerClassForSpecifierOfApplicationProxy:(LSApplicationProxy*)applicationProxy	detailControllerClass to be used by the application specifiers
- (SEL)getterForSpecifierOfApplicationProxy:(LSApplicationProxy*)applicationProxy	getter to be used by the application specifiers
- (SEL)setterForSpecifierOfApplicationProxy:(LSApplicationProxy*)applicationProxy	setter to be used by the application specifiers
- (PSSpecifier*)createSpecifierForApplicationProxy:(LSApplicationProxy*)applicationProxy	Create a specifier for the application represented by applicationProxy
- (NSArray*)createSpecifiersForApplicationSection:(ATLApplicationSection*)section	Create the specicifers for a whole application section represented by section (Calls the method above)

ATLApplicationListSelectionController

ATLApplicationListSelectionController can be used as the detail class of a PSLinkListCell to have a list of applications of which one can be selected. The selected applications bundle identifier will be saved in the preference domain specified via defaults under the specified key. It respects the get / set attributes so by default it will use the readPreferenceValue: and setPreferenceValue:specifier: methods of the PSListController that contains the cell for reading / writing the value. Setting the cellClass to ATLApplicationSelectionCell is recommended so the value preview shows the application name instead of the application bundle identifier.

Example

<dict>
	<key>cell</key>
	<string>PSLinkListCell</string>
	<key>detail</key>
	<string>ATLApplicationListSelectionController</string>
	<key>cellClass</key>
	<string>ATLApplicationSelectionCell</string>
	<key>defaults</key>
	<string>com.yourcompany.yourtweakprefs</string>
	<key>key</key>
	<string>(...)</string>
	<key>label</key>
	<string>(...)</string>
	<key>sections</key>
	<array>
		<dict>
			<key>sectionType</key>
			<string>System</string>
		</dict>
		<dict>
			<key>sectionType</key>
			<string>User</string>
		</dict>
	</array>
	<key>useSearchBar</key>
	<true/>
	<key>hideSearchBarWhileScrolling</key>
	<false/>
</dict>

ATLApplicationListMultiSelectionController

ATLApplicationListSelectionController can be used as the detail class of a PSLinkListCell to have a list of applications where each has a switch next to it. The key defaultApplicationSwitchValue can be set to a boolean and will be used as the default value of the application switches. An array with the application identifiers of the enabled (or disabled when defaultApplicationSwitchValue is true) applications will be saved in the preference domain specified via defaults under the specified key. It respects the get / set attributes so by default it will use the readPreferenceValue: and setPreferenceValue:specifier: methods of the PSListController that contains the cell for reading / writing the value.

Keys

Key	Type	Fallback	Usage
defaultApplicationSwitchValue	Boolean	false	Default value of the application switches

Example

<dict>
	<key>cell</key>
	<string>PSLinkListCell</string>
	<key>detail</key>
	<string>ATLApplicationListMultiSelectionController</string>
	<key>defaults</key>
	<string>(...)</string>
	<key>key</key>
	<string>(...)</string>
	<key>label</key>
	<string>(...)</string>
	<key>sections</key>
	<array>
		<dict>
			<key>sectionType</key>
			<string>Visible</string>
		</dict>
		<dict>
			<key>sectionType</key>
			<string>Hidden</string>
		</dict>
	</array>
	<key>showIdentifiersAsSubtitle</key>
	<true/>
	<key>defaultApplicationSwitchValue</key>
	<false/>
	<key>useSearchBar</key>
	<true/>
</dict>

ATLApplicationListSubcontrollerController

ATLApplicationListSubcontrollerController can be used as the detail class of a PSLinkListCell to have one PSListController per application. The key subcontrollerClass is used to specify the PSListController subclass, although you can also subclass ATLApplicationListSubcontroller instead which has a convienience method to get the application identifier and also automatically reloads the preview string shown in the application list. Preview strings are supported but require you to subclass ATLApplicationListSubcontrollerController and use your subclass instead. In your subclass you need to overwrite the previewStringForApplicationWithIdentifier: method and return the preview string there. Preferences also need to be handled in your PSListController/ATLApplicationListSubcontrollerController subclass, if you want an example for this, check out the Choicy preferences.

Keys

Key	Type	Fallback	Usage
subcontrollerClass	String	None (Required)	Name of the class that should be used for the application subpages

Example

<dict>
	<key>cell</key>
	<string>PSLinkListCell</string>
	<key>detail</key>
	<string>ATLApplicationListSubcontrollerController</string>
	<key>subcontrollerClass</key>
	<string>(...)</string>
	<key>label</key>
	<string>(...)</string>
	<key>sections</key>
	<array>
		<dict>
			<key>sectionType</key>
			<string>Visible</string>
		</dict>
		<dict>
			<key>sectionType</key>
			<string>Hidden</string>
		</dict>
	</array>
	<key>showIdentifiersAsSubtitle</key>
	<true/>
	<key>useSearchBar</key>
	<true/>
</dict>