This post is about a fairly niche subject, namely developing software for jailbroken devices. So if you’re not interested or even know what Activator is, I suppose you can skip this post.

It also assumes a basic level of developing tweaks already.

30 second overview

To get an overview of Activator, let’s take a simple look at what is required to get it working. Then we will go over each part in a little bit more detail, with examples.

First, you need to implement a class that follows the LAListener protocol (more on this later). You will then create an instance of this class, for example in %ctor, and send the object into Activator.

At this point, your object will show up in the Activator application. Then you can pick an event, such as “Status bar left swipe” and assign your object to it. So when “Status bar left swipe” happens, Activator knows that it is your object that is listening for the event and pass it along.

When your object receives the event, it is up to you to do something useful.

That’s the basics, now let’s check out some code.

Alertivator

We are going to implement an example tweak, Alertivator, which is a object that listens for Activator events.

The code for the project can be found at my Github repo https://github.com/jontelang/Alertivator/.

Project setup

I will keep this super brief, as the post is more Activator usage and not “general library usage”.

The Makefile, you need to tell theos that we will link our tweak with the Activator library. You can do this by adding this to the Makefile.

Alertivator_LIBRARIES = activator

You might also need to get the actual library. You can get it by downloading the latest version of Activator on your device, then go into iFile at the path /usr/lib/libactivator.dylib. You take this file and add it into your theos folder in the subfolder named lib.

It can also be a good idea to make your tweak depend on Activator, so that when it is installed you also install Activator automaticall. Do this by adding a dependency of Activator into your control file. Like this.

Depends: mobilesubstrate, libactivator

That it for the boring setup phase, now let’s get into the actual tweak development.

Creating our class

Since this is such a simple tweak, this is all the code that is required in the actual tweak.

#include "activatorheaders/libactivator.h"

@interface Alertivator : NSObject <LAListener>
@end

@implementation Alertivator

- (void)activator:(LAActivator *)activator 
     receiveEvent:(LAEvent *)event 
  forListenerName:(NSString *)listenerName{
    // Show alert here
}

@end

Let’s go through each part.

The first part is simple, it imports the headers for Activator. This way, your tweak will know about the interfaces and protocols of Activator. You can find the most up to date headers at rpetrichs repo.

The second part, the @interface, is nothing special except that it says that our class conforms to the <LAListener> protocol. This means that we are following Activators set way of creating the class, so when it tries to ask our class for information it knows where to look. Or when it tries to send us a message, it knows where to send it.

The third part, the actual implementation of the class, is equally simple. It contains only one method, a method declared in the header files. Within this method, we will display an alert but I have removed that code because it is not important.

In the “30 seconds overview” I said that we will send our class/object into Activator. When we assign “Status bar left slide” to our object (the listener) Activator will take that object, and call this method.

Registering into Activator

So we now have tweak with a class, we can install the tweak but Activator has no way of knowing that we want to communicate with it. So what we need to do is to tell it about our class.

Here’s the code. Again, simple.

static Alertivator *alertivatorInstance;

%ctor{
    alertivatorInstance = [[Alertivator alloc] init];
    [[LAActivator sharedInstance] registerListener:alertivatorInstance 
                                           forName:@"alertivator"];
}

We simply create a static instance of our class and send it into Activator via an shared instance, this requires that Activator is installed.

We also assign a name to our instance, “alertivator”. This is visual representation of what happens.

So now when we go into the Activator app, we pick event. So when we pick e.g. the event “Status bar left swipe”, we can further pick what object should listen to it.

At this point, everything should actually work and when you swipe left on the status bar, you should get a popup. But we’re not done yet, because I think presentation is important.

Adding metadata into Activator app for our listener

As you can see in the screenshot, our listener entry is kind of ugly. There’s no icon, no nice name and no description like in the other actions.

When Activator shows the various listeners, it will look for icons/titles/descriptions in a specific folder on your device. That folder is /Library/Activator/Listeners/your_listener_name/. So in our case it would look for icons and such inside /Library/Activator/Listeners/alertivator/.

At the very minimum, we need an icon and a plist with a title/description. The icon should be named Icon-small@2x.png and have the size 58x58px (you can add a 1x and 3x if you want as well). There should also be a Info.plist file with content like this:

{
    title = "Alertivator - show";
    description = "Shows an alert";
}

When that’s done this is what our file system should look like.

And once we install this onto our device, now Activator should look something like this.

Nice.

Closing notes

At this stage you should have a working tweak that listens to Activator events and shows up nicely in the Activator app. There are LOADS of things you can do differently to get this running, this is just the way I learned how to do it. For example, you can define the “nice” icons/titles/descriptions that shows up in the app entirely in code within your object. You can add preference panels for your tweaks that loads the “listener picker” entirely therein, use Activator without needing it installed and even create your own events. I suggest you take a look at this page on the iphone dev wiki and the headers for libactivator itself.

Next steps

In the next part, I will show how to make a tweak that can work with Activator - but doesn’t depend on it being installed. For example, my tweak Snapper depended on Activator, but loads of people requested to use it without it. In Snapper 2, I implemented it in a way where you can use it with Activator, but it doesn’t need it to be installed.