Creating EventGhost for Android Plugins: For Developers
What are EventGhost for Android Plugins?
Plugins allow you to extend the functionality of EventGhost for Android by adding various actions that can be mapped to incoming events, and send events to EventGhost.
Do I have to create a plugin for EventGhost for Android to be useful to my application?
No, you can also send and receive events from your own application, as well as request a specific layout to load. See Broadcasts and Loading Layouts for details. The benefit of making a plugin is allowing EventGhost for Android to handle which event should fire your action – this way you do not have to listen for a specific event, your plugin will be notified when to begin. It also takes care of saving global settings, or event specific settings for your plugin that the user will set.
How to Create a Plugin
To create a plugin, you must do the following:
- Implement a Broadcast Receiver in your application
- Add the appropriate strings to your resources
- Add required permissions to your AndroidManifest.xml
- Optionally create a configuration activity for input from the user
Note: Versions prior to 1.3 of EventGhost (ADC version included) used a Service to implement plugins. Version 1.3 and higher require the use of a broadcast receiver to create your plugin. If your plugin must remain backwards compatible, you will need to use a service, as well as a broadcast receiver. See “Backwords Compatibility” details below to do this.
Implement a Broadcast Receiver
An EventGhost plugin is implemented as a broadcast receiver in your application. For manual plugins (mapped events), this receiver will be called when the event has been received. For automatic plugins, you don’t have to use this receiver for your actions, but it is required that the service exists for your plugin to be found, regardless of if you use it.
The following is an example EventGhost for Android Plugin service:
public class ExamplePlugin extends BroadcastReceiver {
private static final String TAG = "ExamplePlugin";
@Override
public void onReceive(Context context, Intent intent) {
String event = intent.getStringExtra("event");
Log.i(TAG, "Received event:" + event + ", time to perform my action");
// do something here
}
}
}
Your receiver is passed the following values in the intent:
String event: the event that fired up your plugin
String setting1, setting2, settingA, …: each setting that you sent back to EventGhost for Android in your Configuration Activity. These can be any name, with the exception of the other provided values.
StringArrayList layouts: the layouts that the user currently has setup
Backwards Compatibility
Versions prior to 1.3 implemented a service for plugins. If you want your plugin to work with older versions of EG for Android, you must also create a service which performs the same functionality as above. Then make the following changes for your AndroidManifest.xml:
<service android:name="ExampleService">
<intent-filter>
<action android:name="com.timhoeck.android.eventghost.plugin"></action>
<action android:name="com.timhoeck.android.eventghost.EXECUTE_PLUGIN"></action>
</intent-filter>
</service>
Note the addition of the required com.timhoeck.android.eventghost.plugin action, as well as com.timhoeck.android.eventghost.EXECUTE_PLUGIN, which is not the same as what is required with the receiver.
Required String Resources
You are required to make the following strings available in your resources, i.e. your res/values/string.xml:
<string name="egplugin_name">Example Plugin</string> <string name="egplugin_uninstallable">true</string> <string name="egplugin_description">An Example EventGhost for Android Plugin</string> <string name="egplugin_auto">false</string>
egplugin_name: The name of your plugin
egplugin_uninstallable: Should this plugin be uninstallable from within EventGhost for Android
egplugin_description: The description of your plugin
egplugin_auto: Is this plugin an automatic (true) or a manual plugin (false)
Update your AndroidManifest.xml
Your AndroidManifest.xml should include your service – with the receiver intent action, and required permissions:
<receiver android:name="ExamplePlugin">
<intent-filter>
<action android:name="com.timhoeck.android.eventghost.action.EXECUTE_PLUGIN"></action>
</intent-filter>
</receiver>
<uses-permission android:name="com.timhoeck.android.eventghost.permission.RECEIVE_EVENTS"></uses-permission>
<uses-permission android:name="com.timhoeck.android.eventghost.permission.SEND_EVENT"></uses-permission>
Configuration Activity
Some plugins may wish to ask the user for values that will be used when acting on an event, such as a message that will be displayed, or an application that will launch. EventGhost for Android takes care of storing these values, and makes it easy for you to create a configuration window for your plugin. All you need to do is create an Activity and a Layout, with the appropriate settings for your plugin:
SamplePluginConfig.java
public class SamplePluginConfig extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.SamplePluginLayout);
setTitle("Sample Config");
final TextView txtMessage = (TextView) findViewById(R.id.txtMessage);
//retrieve any existing settings from EG for Android
String message = getIntent().getStringExtra("message");
if (message != null) { txtMessage.setText(message); }
Button btnSave = (Button) findViewById(R.id.btnSave);
btnSave.setOnClickListener(new OnClickListener() {
@Override
public void onClick(View view) {
//Send settings back to EG for Android to be saved
Intent results = new Intent();
results.putExtra("message", txtMessage.getText().toString());
setResult(RESULT_OK, results);
finish();
}});
}
}
Your configuration activity is passed the following values:
String setting1, setting2, etc: each setting that you sent back to EventGhost for Android in your Configuration Activity. These settings can be any name, with the exception of other provided values. They must, however, be strings.
StringArrayList layouts: the layouts that the user currently has setup
Note: It is important to setResult() and finish() so that the settings will be returned to EventGhost for Android, and your activity will disappear.
SamplePluginLayout.xml
<?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:orientation="vertical" android:padding="10dip" android:layout_width="fill_parent" android:layout_height="wrap_content" android:minHeight="100dip" android:minWidth="250dip"> <TextView android:layout_width="fill_parent" android:layout_height="wrap_content" android:text="Type a message to be sent when the event occurs"/> <EditText android:layout_height="wrap_content" android:text="An Event Occurred" android:hint="Message" android:layout_width="fill_parent" android:id="@+id/txtMessage"/> <Button android:layout_width="wrap_content" android:layout_height="wrap_content" android:id="@+id/btnSave" android:text="Save Settings"/> </LinearLayout>
You will then need to give this activity the appropriate intent action in your AndroidManifest.xml, depending on if the plugin is an automatic or manual plugin. I would also recommend setting the activity theme to the Dialog theme, but it is not required:
<activity
android:name="SamplePluginConfig"
android:theme="@android:style/Theme.Dialog">
<intent-filter>
<action android:name="com.timhoeck.android.eventghost.plugin.configure.manual"></action>
</intent-filter>
</activity>
Use either com.timhoeck.android.eventghost.plugin.configure.auto or com.timhoeck.android.eventghost.plugin.configure.manual
Automatic vs. Manual
An automatic plugin is one that is not mapped to a specific event. This is typically useful if you are implementing a sending event action, or handling incoming events on your own.
A manual plugin is one which allows the user to map a specific incoming event to the action that the plugin implements. This gives the user control over what event will fire the action.
Broadcasts
Your application doesn’t have to be a plugin. EventGhost for Android makes use of Androids builtin Broadcast receiver/sender to interact with other applications.
Receive Events
You can receive events from EventGhost by implementing a BroadcastReceiver into your application, such as:
public class EventGhostReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
String event = intent.getStringExtra("event");
Log.i("ExampleReceiver", "ExampleReceiver received a broadcast for event: " + event);
}
}
You will need to request the proper permissions in your AndroidManifest.xml to receive the events. Don’t forget to register your BroadcastReceiver:
<receiver android:name="ExampleReceiver">
<intent-filter>
<action android:name="com.timhoeck.android.eventghost.RECEIVED_EVENT"></action>
</intent-filter>
</receiver>
<uses-permission android:name="com.timhoeck.android.eventghost.permission.RECEIVE_EVENTS"></uses-permission>
Send Events
To send events, you will just need to send the appropriate intent:
private static final String ACTION_SEND_EVENT = "com.timhoeck.android.eventghost.SEND_EVENT"; private void sendEventGhostEvent(String event) { Intent i = new Intent(ACTION_SEND_EVENT); i.putExtra("event", event); startActivity(i); }
You will need to request the proper permissions in your AndroidManifest.xml to send the event:
<uses-permission android:name="com.timhoeck.android.eventghost.permission.SEND_EVENT"></uses-permission>
Load Layouts
You can request EventGhost for Android to load a specific layout using the following code:
private final static String ACTION_LOAD_LAYOUT = "com.timhoeck.android.eventghost.LOAD_LAYOUT";
private void loadEventGhostLayout (String name) {
Intent i = new Intent(ACTION_LOAD_LAYOUT);
i.putExtra("name", name);
startActivity(i);
}
Android Developers Blog