TouchScreen Holograms

TouchScreen Holograms, as first discovered by Asdjke respond intelligently to user input (right or left click). HoloAPI provides an extensive and easy-to-use API to enable TouchScreens for holograms, as documented below. Additionally, HoloAPI comes with a set of in-built commands to enable users to utilise this new technology without the use of the API.

Note: TouchScreen Holograms are available in HoloAPI v1.1.3-SNAPSHOT and later.

---

About TouchScreen Holograms

The following terms will be used throughout this page:

• TouchScreen - refers to a touch-enabled hologram. In HoloAPI, holograms can only be touch-enabled if they have been given active TouchActions to perform.
• TouchAction - refers to any action that a TouchScreen executes. The implementation of TouchActions through the API is covered below

In HoloAPI, TouchActions are fired when a player left or right clicks a hologram. Due to the unique way that HoloAPI handles holograms, TouchActions are only fired for holograms that the interacting player can see.

Commands

HoloAPI comes built-in with various commands to create and manage actions for TouchScreen Holograms.

Command	Permission	Action
/holo touch add <id> <command>	holoapi.holo.touch.add	Add an action for a certain hologram to perform when touched. Actions defined without the use of the API (through this command) may only be commands. The %name% placeholder can be used to define the user that touched the hologram. Commands can be more than one word.
/holo touch add <id> <command> <as_console>	holoapi.holo.touch.add	Same functionality as /holo touch add <command>. <as_console> defines whether the action is performed by the console or the player that touched the hologram
/holo touch remove <id> <touch_id>	holoapi.holo.touch.remove	Remove an action for a TouchScreen hologram, where <touch_id> is the ID of the TouchAction. To remove a command-based Touch Action, simply enter the command"
/holo touch clear <id>	holoapi.holo.touch.clear	Clear all Touch Actions for a particular TouchScreen hologram
/holo touch info <id>	holoapi.holo.touch.info	View information on all Touch Actions for a particular TouchScreen hologram

TouchActions created via commands are saved and retrieved from data files automatically.

TouchScreen Hologram API

In this section of the tutorial, TouchAction refers to the actual class (JavaDocs)

If you are new to implementing HoloAPI in your project, refer to either the API Wiki page or official JavaDocs for help.

Changes to the Hologram class

To start off, the TouchScreen API adds the following methods to the Hologram class:

• addTouchAction(TouchAction) - used for adding TouchActions to a Hologram
• removeTouchAction(TouchAction) - used for removing TouchActions from a Hologram
• clearAllTouchActions() - clears all TouchActions applied to a Hologram
• getAllTouchActions() - Retrieves a list of all TouchActions applied to a Hologram

These methods provide the basic framework for managing TouchScreen Holograms.

TouchAction

The TouchAction class can be used to add certain actions to Holograms when they are interacted with.

TouchActions provide three key methods for management of TouchScreen Holograms: onTouch(Player, Action), getSaveKey() and getDataToSave().

onTouch

The onTouch method in the TouchAction class is automatically called when the Hologram it is applied to is touched. In the following example, a new TouchAction is applied to an existing hologram.

hologram.addTouchAction(new TouchAction() {
    @Override
    public void onTouch(Player who, Action action) {
        who.sendMessage("Hey dude, looks like you " + (action == Action.LEFT_CLICK ? "left" : "right") + "clicked this hologram!");
    }

    @Override
    public String getSaveKey() {
        return "message";
    }

    @Override
    public LinkedHashMap<String, Object> getDataToSave() {
        return null;
    }
});

This example simply sends the interacting player a message, letting them know they touched the Hologram. The getSaveKey and getDataToSave methods are covered below.

Saving Data

HoloAPI allows developers to easily save and load data to TouchScreen holograms conveniently through the HoloAPI Data files.

The getSaveKey method is used by HoloAPI to save data separately for each new TouchAction. If two keys of separate Holograms have identical save keys, data will be overwritten. It is up to the developer to select a unique key to save a TouchAction under. If the save key is null, data will not be saved to file.

The getDataToSave method retrieves a map of data to save to the HoloAPI data files. Entries in the returned map are automatically saved under the appropriate Hologram and TouchAction section of the data file. The following is an example of how this can be implemented.

@Override
public String getSaveKey() {
    return "myAwesomeFunction";
}

@Override
public LinkedHashMap<String, Object> getDataToSave() {
    LinkedHashMap<String, Object> dataMap = new LinkedHashMap<String, Object>();
    dataMap.put("function", 1);
    dataMap.put("isAwesome", true);
    return dataMap;
}

Implementing this into the previous example would look like this:

hologram.addTouchAction(new TouchAction() {
    @Override
    public void onTouch(Player who, Action action) {
        who.sendMessage("Hey dude, looks like you " + (action == Action.LEFT_CLICK ? "left" : "right") + "clicked this hologram!");
    }

    @Override
    public String getSaveKey() {
        return "myAwesomeFunction";
    }

    @Override
    public LinkedHashMap<String, Object> getDataToSave() {
        LinkedHashMap<String, Object> dataMap = new LinkedHashMap<String, Object>();
        dataMap.put("function", 1);
        dataMap.put("isAwesome", true);
        return dataMap;
    }
});

This example saves two values under function and isAwesome. The data file would look like this:

...
touchactions:
    myAwesomeFunction:
        function: 1
        isAwesome: true
...

Loading data from files when Holograms are created is as simple as listening to the HoloTouchActionLoadEvent (JavaDocs). Using the data from the example above, loading data would look something like this:

@EventHandler
    public void onTouchActionLoad(HoloTouchActionLoadEvent event) {
        // Make sure it's what we're looking for
        if (event.getLoadedTouchActionKey().equals("myAwesomeFunction")) {
            // Just in-case (for some reason) the data didn't actually save
            if (event.getConfigMap().get("function") != null) {
                try {
                    Object isAwesome = event.getConfigMap().get("isAwesome");
                    event.getHologram().addTouchAction(new TouchAction((Integer) event.getConfigMap().get("function"), (isAwesome != null && isAwesome instanceof Boolean) ? (Boolean) isAwesome : false));
                } catch (ClassCastException e) {
                    // Something bad happened :(
                }
            }
        }
    }

To finish off this tutorial on implementing TouchScreen Holograms into your plugin using the Developer API, a working example of an extension of TouchActions can be found within HoloAPI:

• CommandTouchAction - Handles commands added as actions through the built-in commands listed above
• CommandTouchActionListener - Handles the automatic loading of command data for TouchScreen Holograms