Package ch.hevs.kart

Class KartSequence

java.lang.Object
ch.hevs.kart.KartSequence
public class KartSequence extends Object

A KartSequence is a step-by-step sequence of commands that can be uploaded to a Kart.

The Kart's sequence player executes one instruction after another and supports a well defined set of opcodes along with their arguments. This class allows to generate those vm commands by exposing a simple interface to construct the sequence. Using the method KartV1.run(KartSequence) the sequence can be uploaded to the kart and getting started.

The builder pattern (KartSequence.Builder) can be used in order to construct such a sequence. Sequences can be saved and loaded to/from xml files by using the methods save(java.lang.String, android.content.Context) and load(java.lang.String, android.content.Context).

IMPORTANT: This feature is experimental: This means that there might be still bugs and the sequence player might not be implemented on all Karts!

  • Constructor Details

    • KartSequence

      public KartSequence()

  • Method Details

    • Builder

      @NonNull public static KartSequence.Builder Builder()

      Creates and returns a new Builder in order to construct a Kart sequence. See the KartSequence.Builder documentation for available commands a sequence can be made of.

      Returns:
      New KartSequence Builder.

    • size

      public int size()

      Returns the number of instructions in the sequence.

      Returns:
      Number of instructions.

    • getInstruction

      @Nullable public KartSequence.Instruction getInstruction(int index)

      Returns a reference to the instruction at the given index in order to modify the instruction or null if the index is outside the sequence bounds.

      Parameters:
      index - Index of the instruction in the sequence.
      Returns:
      Reference to the instruction.

    • addInstruction

      public void addInstruction(@Nullable KartSequence.Instruction.OpCode opcode, short operand)

      Adds a new instruction with the given opcode and operand to the end of the sequence.

      Parameters:
      opcode - Instruction's opcode.
      operand - Instruction's operand.

    • addInstruction

      public void addInstruction(@Nullable KartSequence.Instruction instruction)

      Adds the given instruction to the end of the sequence.

      Parameters:
      instruction - Instruction to add to the end of the sequence.

    • insertInstruction

      public void insertInstruction(int index, KartSequence.Instruction.OpCode opcode, short operand)

      Adds a new instruction with the given opcode and operand to the given index of the sequence. Shifts the instruction currently at that position and any subsequent elements downwards.

      Parameters:
      index - Index at which the instruction has to be inserted.
      opcode - Instruction's opcode.
      operand - Instruction's operand.

    • insertInstruction

      public void insertInstruction(int index, @Nullable KartSequence.Instruction instruction)

      Adds the given instruction to the given index of the sequence. Shifts the instruction currently at that position and any subsequent elements downwards.

      Parameters:
      index - Index at which the instruction has to be inserted.
      instruction - Instruction to insert into the sequence.

    • removeInstruction

      public void removeInstruction(int index)

      Removes the instruction at the given index from the sequence.

      Parameters:
      index - Index of the sequence to remove.

    • save

      public void save(@NonNull String filename, @NonNull android.content.Context context) throws IOException

      Saves the sequence as XML file inside the application's private data location. The suffix ".kartseq" will be added to the filename that is actually saved.

      Parameters:
      filename - Filename for the sequence.
      context - Android context (needed to open output stream).
      Throws:
      IOException - If the sequence could not be serialized to the file.

    • load

      public static KartSequence load(@NonNull String filename, @NonNull android.content.Context context) throws IOException, org.xmlpull.v1.XmlPullParserException

      Tries to load a kart sequence from the given XML file. Note that the file suffix ".kartseq" is automatically added to the file name.

      Parameters:
      filename - File name of the sequence to load.
      context - Android application context (needed to open input stream).
      Returns:
      Loaded kart sequence.
      Throws:
      IOException - Thrown if the file does not exists or is invalid.
      org.xmlpull.v1.XmlPullParserException - Thrown if there was an error parsing the file's XML content.

    • availableSequences

      @NonNull public static String[] availableSequences(@NonNull android.content.Context context)

      Returns a list of the available kart sequence files. Note that the file suffix is removed from the file names.

      Parameters:
      context - Android application context (needed to enumerate the files).
      Returns:
      Sequence files names that can be loaded, or an empty array if no sequence have been found.

    • saveToBundle

      public void saveToBundle(@NonNull android.os.Bundle bundle)

      Saves the sequence to the given bundle.

      Parameters:
      bundle - Bundle to save the sequence to.

    • loadFromBundle

      public static KartSequence loadFromBundle(@NonNull android.os.Bundle bundle)

      Tries to load a kart sequence from the given bundle.

      Parameters:
      bundle - Bundle to load the sequence from.
      Returns:
      Kart sequence or nil if no sequence was saved to the bundle before.