[yifanlu]

The Java hook system is almost complete. Here's what the process of making a Java extension is like:

1) Create an "action". An action holds both the menu item itself (text and icon) and what to do when tapped. Here is an example of a class that logs it's name when tapped:

package com.yifanlu.Kindle.Test;

import com.yifanlu.Kindle.KindleLauncher;
import com.yifanlu.Kindle.LauncherAction;

/**
 * This sample action logs the menu item's text value when tapped
 */
public class TestAction extends LauncherAction {

    /**
     * TestAction logs itself when it is called.
     *
     * @param name  The menu item's display text
     * @param priority  The order to display the item.
     *                  If two items have the same priority, they are sorted by name.
     */
    public TestAction(String name, int priority){
        super(name, priority);
    }

    /**
     * This method is called when the menu item is tapped. It will always run in a new thread.
     * Note that we have access to all of the Kindle's Java classes.
     */
    public void doAction() {
        KindleLauncher.LOG.info("Tapped " + getValue() + "!");
    }
}

2) Now we create a class that implements the Menuable interface. The config file will tell the launcher app to load this class. Then whenever the user opens the Launcher, every extension's Menuable class is called to add their menu items into the main launcher.

package com.yifanlu.Kindle.Test;

import com.yifanlu.Kindle.LauncherAction;
import com.yifanlu.Kindle.LauncherMenu;
import com.yifanlu.Kindle.Menuable;

import java.util.ArrayList;
import java.util.Iterator;

/**
 * This Menuable class will add two new options into Launcher's main menu
 */
public class TestMenu implements Menuable {
    /**
     * This ArrayList will store the menu items for our TestMenu
     */
    private ArrayList mItems;

    public TestMenu() {
        mItems = new ArrayList();
    }

    /**
     * Here we create the menu items and add them to the array.
     */
    private void createItems(){
        // The first menu item will be a TestAction that logs when it's tapped.
        // The second parameter in the constructor shows the order to put these items.
        // If two items have the same priority, they are sorted by their name
        TestAction action = new TestAction("Menu Item 1", 5);
        // The next item is a submenu
        LauncherMenu subMenu = new LauncherMenu("Submenu 1", 5);
        // Here we make another TestAction
        TestAction action2 = new TestAction("Submenu Menu Item 1", 0);
        // We add the second TestAction into the submenu
        subMenu.addMenuItem(action2);
        // We add the first TestAction into the main menu
        mItems.add(action);
        // We add the submenu into the main menu
        mItems.add(subMenu);
    }

    public void addItemsToMenu(LauncherMenu menu) {
        // In this example, we only generate the menu items once,
        // but you can do it every time by removing the if statement
        if(mItems.isEmpty()){
            mItems.clear();
            createItems();
        }
        Iterator arrayListIterator = mItems.iterator();
        while(arrayListIterator.hasNext()){
            LauncherAction action = (LauncherAction)arrayListIterator.next();
            // This method is usually called by the main launcher so all the items placed into mItems will show up
            // in the main menu when the user taps "Launcher". If all extensions place multiple menu items into the
            // main menu, it could get messy, so it is recommended that each extension place one submenu menu option
            // into the main menu.
            menu.addMenuItem(action);
        }
    }
}

In this example, the extension "TestMenu" adds two menu items into the launcher. One of them is a TestAction, which logs its name and the other is another menu that shows another TestAction item when clicked.

3) We put these two classes into TestMenu.jar and create a config file (config.xml)

<?xml version="1.0" encoding="UTF-8"?>
<extension>
	<information>
		<name>Test Menu</name>
		<version>1.0</version>
		<author>Yifan Lu</author>
		<id>testmenu</id>
	</information>
	<menus>
		<menu type="java" jar="TestMenu.jar">com.yifanlu.Test.TestMenu</menu>
	</menus>
</extension>

4) We create a folder named "testmenu" and place the two files "config.xml" and "TestMenu.jar" into it. Now we copy "testmenu" to the "extensions" folder on the Kindle and the new menu options will show up in the launcher.

I'll write more about using JSON and native apps to add menu items when I finish the JSON parser.