Package heronarts.lx

Class LXComponent

java.lang.Object
heronarts.lx.LXComponent
All Implemented Interfaces:
LXPath, LXSerializable, LXParameterListener
Direct Known Subclasses:
ADM, ADM.Obj, ImagePattern.Image, LXAudioComponent, LXClipEngine, LXClipEngine.Grid, LXClipLane, LXDmxEngine, LXEngine, LXFixture, LXMidiEngine, LXMidiSurface, LXMidiTemplate, LXMixerEngine, LXModulatorComponent, LXOscConnection, LXOscEngine, LXOutput, LXPalette, LXParameterModulation, LXRunnableComponent, LXScheduledProject, LXScheduler, LXSnapshot, LXSnapshotEngine, LXStructure, LXSwatch, LXViewDefinition, LXViewEngine, SoundStage
public abstract class LXComponent extends Object implements LXPath, LXParameterListener, LXSerializable
Core base class for any component in the LX tree. This class supports the generic encapsulation of an object with an abstract path, which may have a variety of parameters. Changes to the parameters can be sent and received via OSC, and the component can also be serialized and loaded from JSON files.

  • Field Details

  • Constructor Details

    • LXComponent

      protected LXComponent()
      Creates a new component with no ID and not part of the LX hierarchy. This should very rarely be used, except when creating components that will have to be dynamically loaded later, or may never be part of the hierarchy.

    • LXComponent

      protected LXComponent(LX lx)
      Creates a new component as part of an LX hierarchy. An ID will be automatically assigned to this component.
      Parameters:
      lx - LX instance

    • LXComponent

      protected LXComponent(LX lx, String label)
      Creates a new component as part of the LX hierarchy. An ID will be automatically assigned. This component's label will be set to the provided initial value.
      Parameters:
      lx - LX instance
      label - Initial label for the component

    • LXComponent

      protected LXComponent(LX lx, int id)
      Creates a new component as part of the LX hierarchy. It will be explicitly registered with the the given pre-existing ID.
      Parameters:
      lx - LX instance
      id - Fixed ID value to give this component

    • LXComponent

      protected LXComponent(LX lx, int id, String label)
      Creates a new component as part of the LX hierarchy. It will be explicitly registered with the the given pre-existing ID and a given label value.
      Parameters:
      lx - LX instance
      id - Fixed ID value to give this component
      label - Initial label for the component

  • Method Details

    • getComponentName

      public static String getComponentName(Class<? extends LXComponent> component, String suffix)
      Gets the name of a component class, with a suffix removed
      Parameters:
      component - Component class
      suffix - Suffix to remove
      Returns:
      Name of component type

    • getComponentName

      public static String getComponentName(Class<? extends LXComponent> cls)
      Gets the name of a component class, automatically removing the suffix of a generic LX superclass, if one is found
      Parameters:
      cls - Component class
      Returns:
      Name of component class

    • getComponentDescription

      public static String getComponentDescription(Class<? extends LXComponent> cls)
      Gets the description for a component class, if one is available and provided by the description annotation
      Parameters:
      cls - Component class
      Returns:
      Description of component class

    • getComponentName

      public static String getComponentName(LXComponent component, String suffix)
      Gets the name of an LXComponent object with suffix removed
      Parameters:
      component - Component instance
      suffix - Suffix to remove
      Returns:
      Name of component type

    • getLX

      public LX getLX()
      Accessor to the LX instance that this component is part of. Note that this may be null if this is a dynamic component that has not been registered yet.
      Returns:
      LX instance, or null if unregistered

    • getCategory

      public static String getCategory(Class<? extends LXComponent> clazz)

    • addArray

      protected LXComponent addArray(String path, List<? extends LXComponent> childArray)
      Registers an array of subcomponents with this component. They will be accessible via path and OSC queries at the given path from this component.
      Parameters:
      path - Path to register the array at
      childArray - Child objects
      Returns:
      this

    • addChild

      protected LXComponent addChild(String path, LXComponent child)
      Registers a child component with this component. It will be accessible via path and OSC queries relative to this component.
      Parameters:
      path - Path relative to this
      child - The child component
      Returns:
      this

    • getChild

      public LXComponent getChild(String path)
      Accesses the child component object at a given path. This method can only be used for direct descendants. It will not return elements out of a child array.
      Parameters:
      path - Child path
      Returns:
      Child object if exists, or null if not found

    • setParent

      protected final LXComponent setParent(LXComponent parent)
      Registers this component with a parent object in the hierarchy. If this component has not been registered an ID with LX yet but the parent object is,
      Parameters:
      parent - Parent component
      Returns:
      this

    • getParent

      public final LXComponent getParent()
      Accessor for the parent component. May be null if this component has not been registered with any parent.
      Specified by:
      getParent in interface LXPath
      Returns:
      Parent component, or null if none exists.

    • getId

      public final int getId()
      Accessor for the global id of this component. May be @{link #ID_UNASSIGNED} if this has not been assigned yet.
      Returns:
      Global ID or ID_UNASSIGNED

    • getOscPath

      public String getOscPath()
      Accessor for this component's OSC path relative to its parent. This by default is no different from getPath(), but certain subclasses may modify this to support different types of OSC paths that aren't required to match the LX hierarchy.
      Returns:
      Path that this object can be accessed via OSC

    • isValidOscParameter

      public boolean isValidOscParameter(LXParameter parameter)
      Whether a parameter is a valid OSC target, this component must be an instance of LXOscComponent and the parameters needs to be in the normal parameters array, e.g. not an internal parameter
      Parameters:
      parameter - Parameter to check
      Returns:
      If this is a valid OSC parameter

    • contains

      public final boolean contains(LXPath that)
      Determines whether the given LX object is contained by this parent, at any depth in the tree of child components and parameters.
      Parameters:
      that - Potential child object
      Returns:
      true if a child component or parameter, false otherwise

    • getOscLabel

      public String getOscLabel()
      Gets the OSC-friendly label for this object
      Returns:
      This component's label, sanitized to be OSC-compatible

    • getOscAddress

      public String getOscAddress()
      Gets the OSC address for this object
      Returns:
      Full OSC address for this component

    • handleOscMessage

      public boolean handleOscMessage(OscMessage message, String[] parts, int index)
      Handles an OSC message sent to this component. By default this method handles registered components and parameters, but subclasses may override this method to handle different types of OSC messages.
      Parameters:
      message - Full OSC message object
      parts - The OSC address pattern, broken into an array of parts
      index - Which index into the parts array corresponds to this component's children
      Returns:
      true if the OSC message was handled and should be considered consumed, false otherwise

    • toOscQuery

      public JsonObject toOscQuery()

    • toOscQuery

      public JsonObject toOscQuery(LXParameter parameter)

    • toOscQuery

      public JsonObject toOscQuery(LXParameter parameter, LXParameter parent)

    • getPath

      public String getPath()
      Accessor for the path of this object. Returns the path this component was registered with. Some subclasses may override this if path structure is dynamic.
      Specified by:
      getPath in interface LXPath
      Returns:
      path of this component relative to its parent

    • getLabel

      public String getLabel()
      Accessor for the user-facing label of this component. Objects that implement the LXComponent.Renamable interface may allow the user to change this value.
      Specified by:
      getLabel in interface LXPath
      Returns:
      Label for this component

    • getDescription

      public String getDescription()
      Description copied from interface: LXPath
      Returns a contextual help message explaining the purpose of this parameter or component to the user, or null if none is available.
      Specified by:
      getDescription in interface LXPath
      Returns:
      Contextual help string explaining purpose of the element

    • setDescription

      protected LXComponent setDescription(String description)

    • toString

      public String toString()
      Returns a useful debug string for the component, indicating the class name along with the ID number and the canonical path
      Overrides:
      toString in class Object
      Returns:
      Debug string identifying this component

    • toString

      public String toString(LXComponent root)
      Returns a useful debug string for the component, indicating the class name along with the ID number and the canonical path
      Parameters:
      root - Component to simplify path relative to
      Returns:
      Debug string identifying this component

    • assertDisposed

      public static void assertDisposed(LXComponent component)
      A checked version of dispose used by internal engine implementation to ensure that the base class LXComponent.dispose() is always called.
      Parameters:
      component - Component to dispose

    • dispose

      public void dispose()
      Invoked when a component is being removed from the system and will no longer be used at all. This unregisters the component and should free up any resources and parameter listeners. Ideally after this method is called the object should be eligible for garbage collection. Subclasses are generally expected to override this method to handle their particular cleanup work. They should also generally call super.dispose() at the appropriate time to perform the basic cleanup, which may need to happen either before or after cleaning up other objects.

    • addParameter

      @Deprecated protected final LXComponent addParameter(LXParameter parameter)
      Deprecated.
      Adds a parameter to this component, using its label as the path by default. This method is deprecated and heavily discouraged, it is best always to provide a specific path using addParameter(String, LXParameter) instead.
      Parameters:
      parameter - Parameter to add
      Returns:
      this

    • addParameters

      protected final LXComponent addParameters(LXParameter.Collection parameters)
      Add all parameters from a collection of parameters
      Parameters:
      parameters - Collection of parameters
      Returns:
      this

    • addInternalParameter

      protected final LXComponent addInternalParameter(String path, LXParameter parameter)
      Internal implementation parameters. These won't be automatically exposed to the UI or to OSC etc. and will not show up in getParameters() or the general parameter list. They will be saved and loaded however. Subclasses should use this for parameters which manage internal state but should never show up to the end user and will not be available via OSC.
      Parameters:
      path - Path to internal parameter
      parameter - Parameter
      Returns:
      this

    • addParameter

      protected LXComponent addParameter(String path, LXParameter parameter)
      Adds a parameter to the component at a fixed path. The parameter will be registered in the LX hierarchy, and if it is of a listenable type will also send and receive OSC messages. Listenable parameters will also be automatically registered with their parent component as a listener for notifications upon any change of value.
      Parameters:
      path - String key path to the parameter, must be unique
      parameter - Parameter to add to the component
      Returns:
      this

    • addLegacyParameter

      protected LXComponent addLegacyParameter(String legacyPath, LXParameter parameter)
      Adds a redundant legacy parameter path. If a stored file refers to this path which is no longer active, it will load to the new parameter position.
      Parameters:
      legacyPath - Legacy parameter path, not used anymore
      parameter - Parameter that should be loaded
      Returns:
      this

    • addLegacyInternalParameter

      protected LXComponent addLegacyInternalParameter(String legacyPath, LXParameter parameter)
      Adds a redundant internal legacy parameter path. If a stored file refers to this path which is no longer active, it will load to the new parameter position.
      Parameters:
      legacyPath - Legacy internal parameter path, not used anymore
      parameter - Parameter that should be loaded
      Returns:
      this

    • removeParameter

      protected LXComponent removeParameter(String path)
      Removes a parameter from the component. The parameter will be automatically disposed and may never be used again.
      Parameters:
      path - Parameter path
      Returns:
      this

    • removeParameter

      protected LXComponent removeParameter(String path, boolean removeModulations)
      Removes a parameter from the component. The parameter will be automatically disposed and may never be used again.
      Parameters:
      path - Parameter path
      removeModulations - Whether to also explicitly remove modulations to this parameter
      Returns:
      this

    • removeParameter

      protected LXComponent removeParameter(LXParameter parameter)
      Removes a parameter from the component. The parameter will be automatically disposed and may never be used again.
      Parameters:
      parameter - Parameter
      Returns:
      this

    • removeParameter

      protected LXComponent removeParameter(LXParameter parameter, boolean disposeModulations)

    • getParameters

      public final Collection<LXParameter> getParameters()
      Returns a read-only view of all the parameters in this component.
      Returns:
      Unmodifiable collection view of all the parameters

    • hasParameter

      public final boolean hasParameter(String path)
      Whether this component has a parameter at the given path
      Parameters:
      path - Parameter path
      Returns:
      whether that parameter path is used

    • getParameter

      public final LXParameter getParameter(String path)
      Accessor for parameter at a given path
      Parameters:
      path - Path to parameter
      Returns:
      Parameter if it exists, otherwise null

    • onParameterChanged

      public void onParameterChanged(LXParameter parameter)
      Subclasses are free to override this if desired. It will automatically fire for any listenable parameter that is registered with this component.
      Specified by:
      onParameterChanged in interface LXParameterListener
      Parameters:
      parameter - Parameter that has a value change

    • copyParameters

      protected LXComponent copyParameters(LXComponent that)
      Utility method to copy all parameter values from another component. The other component is expected to be of the same type or a super-type as this object.
      Parameters:
      that - Other component
      Returns:
      this

    • loadPreset

      public void loadPreset(File file)

    • savePreset

      public void savePreset(File file)

    • loadParameters

      protected static void loadParameters(LXComponent component, JsonObject obj, Map<String,LXParameter> parameters)
      Utility function to load a set of parameters
      Parameters:
      component - Component that owns the parameters
      obj - JsonObject to serialize to
      parameters - Map of parameters to unserialize

    • save

      public void save(LX lx, JsonObject obj)
      Serializes the LX component. By default, all internal and user-facing parameters are serialized, as well as any explicitly registered child components. Note that child arrays are not serialized, or any other dynamic components. Subclasses may override to perform more saving, and are expected to call super.save(lx, obj) at the appropriate time.
      Specified by:
      save in interface LXSerializable
      Parameters:
      lx - LX instance
      obj - Object to serialize into

    • load

      public void load(LX lx, JsonObject obj)
      Loads the LX component. Restores the ID of the component, as well as its internal and user-facing parameters. Any explicitly registered children will be automatically loaded, so long as they are direct descendants. Dynamic arrays will not be automatically loaded, this is left to subclasses to implement.
      Specified by:
      load in interface LXSerializable
      Parameters:
      lx - LX instance
      obj - Object to deserialize