EventGhost for Android For Developers

What Can Developers do with EventGhost for Android?

EventGhost for Android provides developers the ability to do a few things:

• Generate Events that users can hook up to a Macro to perform an action when the event occurs
• Listen for Events that have been generated or received from an EventGhost server
• Send Events directly to EventGhost servers
• Load a Layout that exists in the EventGhost for Android application
• Create Plugins that extend the EventGhost for Android application

How do I implement this into my application?

A java class is provided for interested developers which makes implementing EventGhost for Android actions quite simple.

EventGhostIntent.java – Version 1.0 (June 5, 2011)

What are EventGhost for Android Plugins?

Plugins provide easy access for users to functionality that extends EventGhost for Android. The app provides a manage plugins screen for the user to configure, disable or uninstall plugins. You can create plugins that either generate actions, or perform some action. The user can then create Macros which allow them to configure the events or actions to their liking. The plugin system provides an easy way to manage per macros settings for your plugin by creating Configure Plugin screens.

Do I have to create a plugin for EventGhost for Android to be useful to my application?

It is recommended (but not required) for you to create a plugin if possible. This makes it easier for users because they have one place to go to manage settings for the EventGhost for Android app. In addition, the plugin system makes creating Macro-specific actions much easier by maintaining per macro settings for your plugin through a Configure screen that you create.

Whether you create a plugin or not, as long as you use the correct permissions and intent actions, you can generate, receive or send events from your own application – or call other intent actions such as loading a specific layout.

Generating Events

Any application can generate events that will be useful to EventGhost for Android users. If you are writing, for instance, a music app, you can send an event that says ‘Playing Music’. This allows EventGhost for Android users to optionally make an action occur, like turning up the volume or performing some other action (controlled by plugins).

To generate an event from your application:

• Include the GENERATE_EVENTS permission in your AndroidManifest.xml: com.timhoeck.android.eventghost.permission.GENERATE_EVENTS
• Create an intent with the GENERATE_EVENT action (com.timhoeck.android.eventghost.action.GENERATE_EVENT

//Constants
private static final String ACTION_GENERATE_EVENT = "com.timhoeck.android.eventghost.action.GENERATE_EVENT";
private static final String EXTRA_EVENT = "event";
private static final String EXTRA_PAYLOAD = "payload";
private static final String EXTRA_FROM = "from_name";

//Sample Code
Intent generate = new Intent(ACTION_GENERATE_EVENT)
generate.putExtra(EXTRA_EVENT, "MyEvent");
generate.putExtra(EXTRA_PAYLOAD, "Event Info goes goes here");
generate.putExtra(EXTRA_FROM, "MyApp");
sendBroadcast(generate);

EXTRA information that you can supply when generating the event:

EXTRA_EVENT = The event to generate
EXTRA_PAYLOAD = Additional info about the event
EXTRA_FROM = Where the event came from, i.e. your App Name

You will need to request the proper permissions in your AndroidManifest.xml to receive the events. Don’t forget to register your BroadcastReceiver:

Receiving Events

If you want to be notified of all incoming events, and deal with them on your own in your app:

• Include the RECEIVE_EVENTS permission in your AndroidManifest.xml (com.timhoeck.android.eventghost.permission.RECEIVE_EVENTS)
• Create a broadcast receiver with an Intent filter including the RECEIVED_EVENT action (com.timhoeck.android.eventghost.action.RECEIVE_EVENT)

//Constants
private static final String ACTION_RECEIVED_EVENT = "com.timhoeck.android.eventghost.action.RECEIVED_EVENT";
private static final String EXTRA_EVENT = "event";
private static final String EXTRA_PAYLOAD = "payload";
private static final String EXTRA_FROM = "from_name";
private static final ArrayList EXTRA_SERVER_NAMES = "server_names";
private static final ArrayList EXTRA_SERVER_IDS = "server_ids";
private static final ArrayList EXTRA_LAYOUTS = "layouts";

//Sample Code

public class ExampleEventReceiver extends BroadcastReceiver {
    private static final String TAG = "ExampleEventReceiver";

        @Override
        public void onReceive(Context context, Intent intent) {
            if (intent.getAction().equals(ACTION_RECEIVED_EVENT) {
              String event = intent.getStringExtra(EXTRA_EVENT);
              String payload = intent.getStringExtra(EXTRA_PAYLOAD);
              Log.i(TAG, "Received event:" + event + " with payload " + payload + ", time to do something");
              // do something here
            }
        }

    }

}

EXTRA information that is available when you receive the broadcast:
EXTRA_EVENT = The event that was received
EXTRA_PAYLOAD = Additional info about the event
EXTRA_FROM = Where the event came from, either an EventGhost server or another app
EXTRA_SERVER_NAMES = A list of the server names the user has setup
EXTRA_SERVER_IDS = A list of the server ids, which is needed to send an event to a server

You will need to request the proper permissions in your AndroidManifest.xml to receive the events. Don’t forget to register your BroadcastReceiver:

Sending Events

Note: You should typically use GENERATE_EVENT instead of SEND_EVENT. This is because generating an event allows the user to decide what action to take, by configuring a macro with the generated event and their requested action.

Any application can send events directly to an EventGhost server.  This is typically not recommended, unless you have a good reason for doing it. Typically, you should just use GENERATE_EVENT, and let the user decide whether they want the event to be sent to an EventGhost server, or perform some other action.

To send an event from your application:

• Include the SEND_EVENTS permission in your AndroidManifest.xml: (com.timhoeck.android.eventghost.permission.SEND_EVENTS)
• Create an intent with the SEND_EVENT action (com.timhoeck.android.eventghost.action.SEND_EVENT)

//Constants
private static final String ACTION_SEND_EVENT = "com.timhoeck.android.eventghost.action.SEND_EVENT";
private static final String EXTRA_EVENT = "event";
private static final String EXTRA_PAYLOAD = "payload";
private static final String EXTRA_SERVER_ID = "server_id";

//Sample Code
Intent myevent = new Intent(ACTION_SEND_EVENT)
myevent .putExtra(EXTRA_EVENT, "MyEvent");
myevent.putExtra(EXTRA_PAYLOAD, "Event Info goes goes here");
sendBroadcast(myevent);

By default, the event will be sent to the users default EventGhost server. If you want to specify a server, you must use EXTRA_SERVER_NAMES and EXTRA_SERVER_IDS that are provided to Plugins or to a RECEIVED_EVENT broadcast. The server names are provided in case you want to display them to the user – or find a specific server by name. To send to a specific server, you need to send EXTRA_SERVER_ID with the corresponding server id from the provided lists of names and ids.

You will need to request the proper permissions in your AndroidManifest.xml to send the event:

How to Create a Plugin

To create a plugin, you must do the following:

• Implement a Broadcast Receiver with the appropriate intent filter action: ACTION_EXECUTE_PLUGIN (com.timhoeck.android.eventghost.action.EXECUTE_PLUGIN)
• Add the appropriate META_DATA to your Broadcast Receiver
• 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. This is no longer supported.

Implement a Broadcast Receiver

An EventGhost plugin is implemented as a broadcast receiver. For Macro plugins, this receiver will be called when the Macros event has been received. For Generic plugins, you don’t have to use this receiver for your actions, but it is required that it exists for your plugin to be found, regardless of if you use it.
The following is an example EventGhost for Android Plugin service:

<pre>
<pre>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
        }

    }

}</pre>
</pre>

Your receiver is passed the following values in the intent:

String event: the event that fired up your plugin
String payload: optional additional information about the event
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 server_names : the names of the EventGhost servers the user has setup
StringArrayList server_ids : the ids of the EventGhost servers that the user has setup
StringArrayList layouts: the layouts that the user currently has setup

Add MetaData to your Broadcast Receiver in your AndroidManifest.xml

You are required to add some metadata to the Broadcast receiver, and other optional metadata:

plugin_name: The name of your plugin

plugin_uninstallable: Should this plugin be uninstallable from within EventGhost for Android. If your app only contains the plugin itself, this should be true, otherwise false

plugin_description: The description of your plugin

plugin_config (optional): The class (Activity) for your Plugins generic configuration or for Generic Plugins Config screen

plugin_macro_config (optional): The class (Activity) for your Macro Plugin Config screen
Update your AndroidManifest.xml
Your AndroidManifest.xml should include your Broadcast Receiver- with the receiver intent action, and required permissions:

Configuration Activity

Some plugins may wish to ask the user for values that will be used when acting on an macro, 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
• StringArrayList server_names: the names of the EventGhost servers the user has setup
• StringArrayList server_ids: the ids of the EventGhost servers the user 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"?-->

<button>

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:

Use either com.timhoeck.android.eventghost.plugin.configure.auto or com.timhoeck.android.eventghost.plugin.configure.manual

Macro vs. Generic

A generic plugin is one that is not tied to a specific event, and cannot be access by the user as a macro. This is typically useful if you are implementing a sending event action, or handling incoming events on your own.
A macro 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.

You will need to request the proper permissions in your AndroidManifest.xml to receive the events. Don’t forget to register your BroadcastReceiver:

Other Intent Actions

Load Layouts

You can request EventGhost for Android to startup and load a specific layout using the following code:

private static final String ACTION_LOAD_LAYOUT = "com.timhoeck.android.eventghost.action.LOAD_LAYOUT";
private static final String EXTRA_NAME = "name";

private void loadEventGhostLayout (String name) {
    Intent i = new Intent(ACTION_LOAD_LAYOUT);
    i.putExtra(EXTRA_NAME, name);
    startActivity(i);
}