Package jmri.jmrix.loconet.sdf

Class SdfMacro

  • All Implemented Interfaces:
    SdfConstants
    Direct Known Subclasses:
    BranchTo, ChannelStart, CommentMacro, DelaySound, EndSound, FourByteMacro, GenerateTrigger, InitiateSound, LabelMacro, LoadModifier, MaskCompare, Play, SdlVersion, SkemeStart, SkipOnTrigger, TwoByteMacro
    public abstract class SdfMacro
extends java.lang.Object
implements SdfConstants
    Common base for all the SDF macros defined by Digitrax for their sound definition language.

    Each macro has a number of descriptive forms:

    name()
    Just the name, in MPASM form.
    toString()
    A brief description, with a terminating newline
    oneInstructionString()
    The entire single instruction in MPASM from, with a terminating newline
    allInstructionString()
    The instruction and all those logically grouped within it.
    SdfMacro and its subclasses don't do the notification needed to be Models in an MVC edit paradyme. This is because there are a lot of SdfMacros in realistic sound file, and the per-object overhead needed would be too large. Hence (or perhaps because of no need), there is no support for simultaneous editing of a single macro instruction updating multiple windows. You can have multiple editors open on a single SdfBuffer, but these are not interlocked against each other. (We could fix this by having a shared pool of "objects to be notified of changes in the SdfBuffer, acccessed by reference during editing (to avoid another dependency), but that's a project for another day)

    • Field Detail

      • children

        java.util.ArrayList<SdfMacro> children
        Local member hold list of child (contained) instructions

    • Method Detail

      • name

        public abstract java.lang.String name()
        Name used by the macro in the SDF definition
        Returns:
        Fixed name associated with this type of instructio

      • length

        public abstract int length()
        Provide number of bytes defined by this macro
        Returns:
        Fixed numher of bytes defined (a constant for the instruction type)

      • toString

        public abstract java.lang.String toString()
        Provide a single-line simplified representation, including the trailing newline. This is used e.g. in the tree format section of the EditorFrame.
        Overrides:
        toString in class java.lang.Object
        Returns:
        newline-terminated string; never null

      • oneInstructionString

        public abstract java.lang.String oneInstructionString()
        Provide single instruction in MPASM format, including the trailing newline.
        Returns:
        Newline terminated string, never null

      • allInstructionString

        public abstract java.lang.String allInstructionString​(java.lang.String indent)
        Provide instructions in MPASM format, including the trailing newline and all nested instructions.
        Parameters:
        indent - String inserted at the start of each output line, typically some number of spaces.
        Returns:
        Newline terminated string, never null

      • getChildren

        public java.util.List<SdfMacro> getChildren()
        Access child (nested) instructions.
        Returns:
        List of children, which will be null except in case of nesting.

      • totalLength

        public int totalLength()
        Total length, including contained instructions
        Returns:
        length of all parts

      • loadByteArray

        public void loadByteArray​(SdfBuffer buffer)
        Store into a buffer.

        This provides a default implementation for children, but each subclass needs to store its own data with setAtIndexAndInc().

        Parameters:
        buffer - load with all children

      • decodeInstruction

        public static SdfMacro decodeInstruction​(SdfBuffer buff)
        Get the next instruction macro in a buffer.

        Note this uses the index contained in the SdfBuffer implementation, and has the side-effect of bumping that forward.

        Parameters:
        buff - The SdfBuffer being scanned for instruction macros.
        Returns:
        Object of SdfMacro subtype for specific next instruction

      • decodeFlags

        java.lang.String decodeFlags​(int input,
                             int[] values,
                             int[] masks,
                             java.lang.String[] labels)
        Service method to unpack various bit-coded values for display, using a mask array.

        Note that multiple values can be returned, e.g. this can be used to scan for individual bits set in a variable.

        Parameters:
        input - Single value to be matched
        values - Array of possible values which the input might match
        masks - Array of masks to be applied when comparing against the corresponding items in the values array. This is separate for each possible value to e.g. allow the encoding of a set of independent bits.
        labels - Should there be a match-under-mask of a value, the corresponding label is returned
        Returns:
        "+" separated list of labels, or "<ERROR>" if none matched

      • decodeState

        java.lang.String decodeState​(int input,
                             int[] values,
                             java.lang.String[] labels)