Dev:Libactivator

libactivator is a library used to have a centralized system of activation methods for all of our jailbroken extensions. To accomplish this, the hooks of the activation methods are in one centralized MobileSubstrate plugin, that uses small bundles and preference panes to select the activation method for each plugin.

Developers can customize libactivator in two ways, either by adding custom LAListeners or custom LAEvents. LAListeners are new types of activities. For example, if you have implemented a daemon then you could create a custom listener that would allow users to start or stop the daemon via an action of their choice. For example they would be able to hook up a triple tap of the home button to start or stop your daemon. LAEvents are these actions that can trigger the activities to happen, for example the triple tap of the home button I just mentioned. You could develop your own custom LAEvent, for example another developer built one for unlocking or locking the device. The result was users could then hook up listeners to this unlocking LAEvent, for example turn LTE off when the device is locked, and subsequently turn it on again when unlocked, in certain situations giving the user a battery-life advantage.

= Implementing a LAListener = To implement a LAListener, there are three steps you must follow: adding a plist, implementing the code, and allow users to change activation methods. Optionally, you can also add a method to register your plugin for a certain event on installation, which allows you to implement libactivator without confusing prior users.

Adding a plist
The most simple step. Simply add a plist to your file system in the folder /Library/Activator/Listeners/com.your.packageid/Info.plist. The contents of this file should contain, inserting the proper text:

Other plist keys are requires-event and compatible-modes.

You can also put a 29x29 icon-small.png and icon-small@2x.png in the package folder too.

Integrating the Code
Integrating the code can be done in two different methods, depending on your plugin. If you have an object that is always in memory, you can use method one, otherwise, use method two.

Method One: Add the Code
First, #import  and have your class implement the LAListener protocol.

To register for events, you must add a piece of code to your init method, replacing the parts as needed:

Then, you must also implement two simple delegate methods: In the first method, you should first check if your plugin is already active. If it is active, you should deactivate your plugin and return. Otherwise, just activate your plugin. In addition, in the activator:recieveEvent: method, you must call [event setHandled:YES] if you wish to disable the default OS action for that activation event. If you do not set handled then receive event may be called twice for the same event. In the second method you should simply deactivate your plugin.

The implementation of these methods is left completely up to the programmer. The LAEvent objects can be used to discover more information about the event, such as the type, if you wish to perform a different action based on the type of event. Do not use that information to disable certain types of events for your plugin!

Method Two: New Object
The second method of implementing libactivator is to insert a new class in your code, one instance of which is always initialized, and informs your main classes when an activation event has occurred (so your main plugin can activate). A sample class is provided below with placeholder comments where additional code would be needed:

Allowing Users to Change Activation Methods
The simplest method to allow users to change activation methods is if you use PreferenceLoader and a simple plist format. Then, you can just paste in this code to create a cell that when tapped will allow users to select an activation method (again replacing the package id with the correct one):

A more complex method is to integrate the settings pane directly into your app's navigation controller:

Libactivator 1.1 introduces a global preferences pane and makes neither of these methods required

Default Activation Methods
To implement default activation methods, call assignEvent:toListenerWithName: before registering your listener:

Only supported in libactivator 1.1+

= Implementing a LAEvent =

= Example Projects =