HBPreferences Class Reference

Inherits from NSObject
Declared in HBPreferences.h

Initializing an HBPreferences Object

+ preferencesForIdentifier:

Creates an instance of the class for the specified identifier.

+ (instancetype)preferencesForIdentifier:(NSString *)identifier

Parameters

identifier

The identifier to be used. This is usually the same as the package identifier of the tweak.

Return Value

An autoreleased instance of HBPreferences for the specified identifier.

Declared In

HBPreferences.h

– initWithIdentifier:

Initializes an instance of the class for the specified identifier.

- (instancetype)initWithIdentifier:(NSString *)identifier

Parameters

identifier

The identifier to be used. This is usually the same as the package identifier of the tweak.

Return Value

An autoreleased instance of HBPreferences for the specified identifier.

Declared In

HBPreferences.h

  identifier

The preferences identifier provided at initialisation.

@property (nonatomic, retain, readonly) NSString *identifier

Declared In

HBPreferences.h

Synchronizing Preferences

– synchronize

Synchronizes preferences data to prevent race conditions.

- (BOOL)synchronize

Return Value

YES if synchronization was successful, NO if an error occurred.

Discussion

On iOS 8.0 and later, waits until all communications between the cfprefsd daemon and the current process have completed, preventing race conditions and guaranteeing no data will be lost. Prior to iOS 8.0, writes all pending changes to preference data to permanent storage, and reads latest preference data from permanent storage.

Do not use this method directly unless you have a specific need. HBPreferences will synchronize automatically when needed. For further information on what this method does and when to use it, refer to NSUserDefaults in Practice § “Sharing Defaults Between Programs”.

Declared In

HBPreferences.h

Getting Preference Values

– dictionaryRepresentation

Returns a dictionary that contains all preferences that are set.

- (NSDictionary<NSString*,id> *)dictionaryRepresentation

Return Value

A dictionary containing all keys and values.

Discussion

This does not include default values.

Declared In

HBPreferences.h

Registering Default Preference Values

  defaults

The default preferences to be used when no value has been set by the user.

@property (nonatomic, copy, readonly) NSMutableDictionary<NSString*id> *defaults

Discussion

You may modify the values of this dictionary directly.

Declared In

HBPreferences.h

– registerDefaults:

Adds the contents of the specified dictionary to the defaults property.

- (void)registerDefaults:(NSDictionary<NSString*,id> *)defaultValues

Parameters

defaultValues

The dictionary of keys and values you want to register.

Discussion

Merges the provided dictionary with the mutable dictionary found on the defaults property. Provided as a convenience for converting code from using NSUserDefaults.

Declared In

HBPreferences.h

– objectForKey:

Returns the object associated with the specified key.

- (id)objectForKey:(NSString *)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The object associated with the specified key.

Discussion

If the preference is not yet set, returns the default. If no default is set, returns nil.

Warning: You must manually synchronize preferences or use registerObject:default:forKey: for this value to be updated when running on iOS 7 or older.

Declared In

HBPreferences.h

– integerForKey:

Returns the integer value associated with the specified key.

- (NSInteger)integerForKey:(NSString *)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The integer value associated with the specified key.

Discussion

If the preference is not yet set, returns the default. If no default is set, returns nil.

See Also

Declared In

HBPreferences.h

– unsignedIntegerForKey:

Returns the unsigned integer value associated with the specified key.

- (NSUInteger)unsignedIntegerForKey:(NSString *)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The unsigned integer value associated with the specified key.

Discussion

If the preference is not yet set, returns the default. If no default is set, returns nil.

See Also

Declared In

HBPreferences.h

– floatForKey:

Returns the floating-point value associated with the specified key.

- (CGFloat)floatForKey:(NSString *)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The floating-point value associated with the specified key.

Discussion

If the preference is not yet set, returns the default. If no default is set, returns nil.

See Also

Declared In

HBPreferences.h

– doubleForKey:

Returns the double value associated with the specified key.

- (double)doubleForKey:(NSString *)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The double value associated with the specified key.

Discussion

If the preference is not yet set, returns the default. If no default is set, returns nil.

See Also

Declared In

HBPreferences.h

– boolForKey:

Returns the Boolean value associated with the specified key.

- (BOOL)boolForKey:(NSString *)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The Boolean value associated with the specified key.

Discussion

If the preference is not yet set, returns the default. If no default is set, returns nil.

See Also

Declared In

HBPreferences.h

– objectForKeyedSubscript:

Returns the value associated with a given key.

- (id)objectForKeyedSubscript:(id)key

Parameters

key

The key for which to return the corresponding value.

Return Value

The value associated with the specified key.

Discussion

This method behaves the same as objectForKey:.

See Also

Declared In

HBPreferences.h

– objectForKey:default:

Returns the object associated with the specified key, or if no user preference is set, the provided default.

- (id)objectForKey:(NSString *)key default:(nullable id)defaultValue

Parameters

key

The key for which to return the corresponding value.

defaultValue

The default value to use when no user preference is set.

Return Value

The object associated with the specified key, or the default value.

Declared In

HBPreferences.h

– integerForKey:default:

Returns the integer value associated with the specified key, or if no user preference is set, the provided default.

- (NSInteger)integerForKey:(NSString *)key default:(NSInteger)defaultValue

Parameters

key

The key for which to return the corresponding value.

defaultValue

The default value to use when no user preference is set.

Return Value

The integer value associated with the specified key, or the default value.

Declared In

HBPreferences.h

– unsignedIntegerForKey:default:

Returns the unsigned integer value associated with the specified key, or if no user preference is set, the provided default.

- (NSUInteger)unsignedIntegerForKey:(NSString *)key default:(NSUInteger)defaultValue

Parameters

key

The key for which to return the corresponding value.

defaultValue

The default value to use when no user preference is set.

Return Value

The unsigned integer value associated with the specified key, or the default value.

Declared In

HBPreferences.h

– floatForKey:default:

Returns the floating-point value associated with the specified key, or if no user preference is set, the provided default.

- (CGFloat)floatForKey:(NSString *)key default:(CGFloat)defaultValue

Parameters

key

The key for which to return the corresponding value.

defaultValue

The default value to use when no user preference is set.

Return Value

The floating-point value associated with the specified key, or the default value.

Declared In

HBPreferences.h

– doubleForKey:default:

Returns the double value associated with the specified key, or if no user preference is set, the provided default.

- (double)doubleForKey:(NSString *)key default:(double)defaultValue

Parameters

key

The key for which to return the corresponding value.

defaultValue

The default value to use when no user preference is set.

Return Value

The double value associated with the specified key, or the default value.

Declared In

HBPreferences.h

– boolForKey:default:

Returns the Boolean value associated with the specified key, or if no user preference is set, the provided default.

- (BOOL)boolForKey:(NSString *)key default:(BOOL)defaultValue

Parameters

key

The key for which to return the corresponding value.

defaultValue

The default value to use when no user preference is set.

Return Value

The Boolean value associated with the specified key, or the default value.

Declared In

HBPreferences.h

Setting Preference Values

– setObject:forKey:

Sets the value of the specified key.

- (void)setObject:(nullable id)value forKey:(NSString *)key

Parameters

value

The object to store in the preferences.

key

The key with which to associate with the value.

Discussion

You should only call these methods if you are certain that the process is running as the mobile user.

Exceptions

HBPreferencesNotMobileException

Thrown when the method is called by a process not running as the mobile user.

Declared In

HBPreferences.h

– setInteger:forKey:

Sets the value of the specified key to the specified integer value.

- (void)setInteger:(NSInteger)value forKey:(NSString *)key

Parameters

value

The integer value to store in the preferences.

key

The key with which to associate with the value.

Discussion

This is a convenience method that calls setObject:forKey:. See the discussion of that method for more details.

Declared In

HBPreferences.h

– setUnsignedInteger:forKey:

Sets the value of the specified key to the specified unsigned integer value.

- (void)setUnsignedInteger:(NSUInteger)value forKey:(NSString *)key

Parameters

value

The unsigned integer value to store in the preferences.

key

The key with which to associate with the value.

Discussion

This is a convenience method that calls setObject:forKey:. See the discussion of that method for more details.

Declared In

HBPreferences.h

– setFloat:forKey:

Sets the value of the specified key to the specified floating-point value.

- (void)setFloat:(CGFloat)value forKey:(NSString *)key

Parameters

value

The floating-point value to store in the preferences.

key

The key with which to associate with the value.

Discussion

This is a convenience method that calls setObject:forKey:. See the discussion of that method for more details.

Declared In

HBPreferences.h

– setDouble:forKey:

Sets the value of the specified key to the specified double value.

- (void)setDouble:(double)value forKey:(NSString *)key

Parameters

value

The double value to store in the preferences.

key

The key with which to associate with the value.

Discussion

This is a convenience method that calls setObject:forKey:. See the discussion of that method for more details.

Declared In

HBPreferences.h

– setBool:forKey:

Sets the value of the specified key to the specified Boolean value.

- (void)setBool:(BOOL)value forKey:(NSString *)key

Parameters

value

The Boolean value to store in the preferences.

key

The key with which to associate with the value.

Discussion

This is a convenience method that calls setObject:forKey:. See the discussion of that method for more details.

Declared In

HBPreferences.h

– setObject:forKeyedSubscript:

Sets the value of the specified key to the specified value.

- (void)setObject:(nullable id)object forKeyedSubscript:(id)key

Parameters

object

The value to store in the preferences.

key

The key with which to associate with the value.

Declared In

HBPreferences.h

Removing Preference Values

– removeObjectForKey:

Removes a given key and its associated value from the dictionary.

- (void)removeObjectForKey:(NSString *)key

Parameters

key

The key to remove.

Discussion

Blocks are called after HBPreferences’ cache of values is updated. The block will also be called immediately after calling this method. See registerObject:default:forKey: for details on how to set up callbacks.

Declared In

HBPreferences.h

– removeAllObjects

Removes all stored preferences.

- (void)removeAllObjects

Discussion

This method acts in the same way as discussed in removeObjectForKey:.

Declared In

HBPreferences.h

Registering Variables

– registerObject:default:forKey:

Register an object to be automatically set to the user’s preference.

- (void)registerObject:(_Nullable id __strong *_Nonnull)object default:(nullable id)defaultValue forKey:(NSString *)key

Parameters

object

The pointer to the object.

defaultValue

The default value to be used if no user preference is set.

key

The key in the preferences property list.

Discussion

If the preference is not yet set, the object will be set to the provided default.

You must post a Darwin notification after updating preferences for this to work. In particular, it must be set to the value of identifier, followed by /ReloadPrefs - for instance, ws.hbang.common.demo/ReloadPrefs. In a Preferences specifier property list, you can use the PostNotification key on your specifiers to achieve this:

<dict>
    ...
    <key>PostNotification</key>
    <string>ws.hbang.common.demo/ReloadPrefs</string>
</dict>

Declared In

HBPreferences.h

– registerInteger:default:forKey:

Register an integer value to be automatically set to the user’s preference.

- (void)registerInteger:(NSInteger *)object default:(NSInteger)defaultValue forKey:(NSString *)key

Parameters

object

The pointer to the integer.

defaultValue

The default value to be used if no user preference is set.

key

The key in the preferences property list.

Discussion

If the preference is not yet set, the object will be set to the provided default.

Declared In

HBPreferences.h

– registerUnsignedInteger:default:forKey:

Register an unsigned integer value to be automatically set to the user’s preference.

- (void)registerUnsignedInteger:(NSUInteger *)object default:(NSUInteger)defaultValue forKey:(NSString *)key

Parameters

object

The pointer to the unsigned integer.

defaultValue

The default value to be used if no user preference is set.

key

The key in the preferences property list.

Discussion

If the preference is not yet set, the object will be set to the provided default.

Declared In

HBPreferences.h

– registerFloat:default:forKey:

Register a floating-point value to be automatically set to the user’s preference.

- (void)registerFloat:(CGFloat *)object default:(CGFloat)defaultValue forKey:(NSString *)key

Parameters

object

The pointer to the integer.

defaultValue

The default value to be used if no user preference is set.

key

The key in the preferences property list.

Discussion

If the preference is not yet set, the object will be set to the provided default.

Declared In

HBPreferences.h

– registerDouble:default:forKey:

Register a double value to be automatically set to the user’s preference.

- (void)registerDouble:(double *)object default:(double)defaultValue forKey:(NSString *)key

Parameters

object

The pointer to the double.

defaultValue

The default value to be used if no user preference is set.

key

The key in the preferences property list.

Discussion

If the preference is not yet set, the object will be set to the provided default.

Declared In

HBPreferences.h

– registerBool:default:forKey:

Register a Boolean value to be automatically set to the user’s preference.

- (void)registerBool:(BOOL *)object default:(BOOL)defaultValue forKey:(NSString *)key

Parameters

object

The pointer to the Boolean.

defaultValue

The default value to be used if no user preference is set.

key

The key in the preferences property list.

Discussion

If the preference is not yet set, the object will be set to the provided default.

Declared In

HBPreferences.h

Preference Change Callbacks

– registerPreferenceChangeBlock:

Register a block to be called when a preference change is detected.

- (void)registerPreferenceChangeBlock:(HBPreferencesChangeCallback)callback

Parameters

callback

A block object called when the specified key’s value changes. The block object takes no parameters and returns no value.

Discussion

Blocks are called after HBPreferences’ cache of values is updated. The block will also be called immediately after calling this method. See registerObject:default:forKey: for details on how to set up callbacks.

Declared In

HBPreferences.h

– registerPreferenceChangeBlock:forKey:

Register a block to be called when a specific preference is changed.

- (void)registerPreferenceChangeBlock:(HBPreferencesValueChangeCallback)callback forKey:(NSString *)key

Parameters

callback

A block object called when the specified key’s value changes. The block object’s parameters are the key and its new value.

key

The key to listen for.

Discussion

Blocks are called after HBPreferences’ cache of values is updated. The block will also be called immediately after calling this method. See registerObject:default:forKey: for details on how to set up callbacks.

Declared In

HBPreferences.h