Class KartSequence
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!
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
Builder which has to be used in order to construct new KartSequences.static class
Instruction class, represents a single instruction (opcode + operand). -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
addInstruction
(KartSequence.Instruction instruction) Adds the given instruction to the end of the sequence.void
addInstruction
(KartSequence.Instruction.OpCode opcode, short operand) Adds a new instruction with the given opcode and operand to the end of the sequence.static String[]
availableSequences
(android.content.Context context) Returns a list of the available kart sequence files.static KartSequence.Builder
Builder()
Creates and returns a new Builder in order to construct a Kart sequence.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.void
insertInstruction
(int index, KartSequence.Instruction instruction) Adds the given instruction to the given index of the sequence.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.static KartSequence
Tries to load a kart sequence from the given XML file.static KartSequence
loadFromBundle
(android.os.Bundle bundle) Tries to load a kart sequence from the given bundle.void
removeInstruction
(int index) Removes the instruction at the given index from the sequence.void
Saves the sequence as XML file inside the application's private data location.void
saveToBundle
(android.os.Bundle bundle) Saves the sequence to the given bundle.int
size()
Returns the number of instructions in the sequence.
-
Constructor Details
-
KartSequence
public KartSequence()
-
-
Method Details
-
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
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
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
Adds the given instruction to the end of the sequence.
- Parameters:
instruction
- Instruction to add to the end of the sequence.
-
insertInstruction
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
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
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
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.
-