heronarts.lx

Class LXComponent

java.lang.Object

heronarts.lx.LXComponent

All Implemented Interfaces:

LXPath, LXSerializable, LXParameterListener

Direct Known Subclasses:

LXAudioComponent, LXClipEngine, LXEngine, LXFixture, LXMidiEngine, LXMixerEngine, LXModulatorComponent, LXOscEngine, LXOutput, LXPalette, LXParameterModulation, LXRunnableComponent, LXScheduledProject, LXScheduler, LXSnapshot, LXSnapshotEngine, LXStructure, LXSwatch

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	LXComponent.Placeholder A market interface for a Placeholder component that is used when an LXComponent class implementation is missing at runtime.
static interface	LXComponent.Renamable Marker interface for components which can have their label changed.

Nested classes/interfaces inherited from interface heronarts.lx.LXSerializable

LXSerializable.Utils

Field Summary

Fields

Modifier and Type	Field and Description
MutableParameter	controlSurfaceSemaphore A semaphore used to keep count of how many remote control surfaces may be controlling this component.
static String	KEY_CLASS
static String	KEY_COMPONENT_ID
static String	KEY_ID
static String	KEY_PARAMETER_PATH
static String	KEY_PATH
StringParameter	label The user-facing label of this component.
protected LX	lx The LX instance that this component belongs to.
DiscreteColorParameter	modulationColor A color used to identify this component when it or one of its parameters is used as a modulation source.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LXComponent() Creates a new component with no ID and not part of the LX hierarchy.
protected	LXComponent(LX lx) Creates a new component as part of an LX hierarchy.
protected	LXComponent(LX lx, int id) Creates a new component as part of the LX hierarchy.
protected	LXComponent(LX lx, int id, String label) Creates a new component as part of the LX hierarchy.
protected	LXComponent(LX lx, String label) Creates a new component as part of the LX hierarchy.

Method Summary

Modifier and Type	Method and Description
protected LXComponent	addArray(String path, List<? extends LXComponent> childArray) Registers an array of subcomponents with this component.
protected LXComponent	addChild(String path, LXComponent child) Registers a child component with this component.
protected LXComponent	addInternalParameter(String path, LXParameter parameter) Internal implementation parameters.
protected LXComponent	addParameter(LXParameter parameter) Deprecated.
protected LXComponent	addParameter(String path, LXParameter parameter) Adds a parameter to the component at a fixed path.
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.
protected LXComponent	copyParameters(LXComponent that) Utility method to copy all parameter values from another component.
void	dispose() Invoked when a component is being removed from the system and will no longer be used at all.
LXComponent	getChild(String path) Accesses the child component object at a given path.
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
static String	getComponentName(Class<? extends LXComponent> component, String suffix) Gets the name of a component class, with a suffix removed
static String	getComponentName(LXComponent component, String suffix) Gets the name of an LXComponent object with suffix removed
int	getId() Accessor for the global id of this component.
String	getLabel() Accessor for the user-facing label of this component.
LX	getLX() Accessor to the LX instance that this component is part of.
String	getOscAddress() Gets the OSC address for this object
String	getOscLabel() Gets the OSC-friendly label for this object
String	getOscPath() Accessor for this component's OSC path relative to its parent.
LXParameter	getParameter(String path) Accessor for parameter at a given path
Collection<LXParameter>	getParameters() Returns a read-only view of all the parameters in this component.
LXComponent	getParent() Accessor for the parent component.
String	getPath() Accessor for the path of this object.
boolean	handleOscMessage(OscMessage message, String[] parts, int index) Handles an OSC message sent to this component.
void	load(LX lx, JsonObject obj) Loads the LX component.
protected static void	loadParameters(LXComponent component, JsonObject obj, Map<String,LXParameter> parameters) Utility function to load a set of parameters
void	onParameterChanged(LXParameter parameter) Subclasses are free to override this if desired.
protected LXComponent	removeParameter(LXParameter parameter) Removes a parameter from the component.
protected LXComponent	removeParameter(String path) Removes a parameter from the component.
void	save(LX lx, JsonObject obj) Serializes the LX component.
protected static void	saveParameters(LXComponent component, JsonObject obj, Map<String,LXParameter> parameters) Utility function to serialize a set of parameters
protected LXComponent	setParent(LXComponent parent) Registers this component with a parent object in the hierarchy.
String	toString() Returns a useful debug string for the component, indicating the class name along with the ID number and the canonical path
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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface heronarts.lx.LXPath

get, get, getCanonicalLabel, getCanonicalLabel, getCanonicalPath, getCanonicalPath, getComponent, getComponent, getParameter, getParameter

Field Detail

lx

protected LX lx

The LX instance that this component belongs to.

label

public final StringParameter label

The user-facing label of this component. May be editable if this LXComponent class implements the LXComponent.Renamable interface.

modulationColor

public final DiscreteColorParameter modulationColor

A color used to identify this component when it or one of its parameters is used as a modulation source.

controlSurfaceSemaphore

public final MutableParameter controlSurfaceSemaphore

A semaphore used to keep count of how many remote control surfaces may be controlling this component. This may be used by UI implementations to indicate to the user that this component is under remote control.

KEY_ID

public static final String KEY_ID

See Also:

Constant Field Values

KEY_CLASS

public static final String KEY_CLASS

See Also:

Constant Field Values

KEY_COMPONENT_ID

public static final String KEY_COMPONENT_ID

See Also:

Constant Field Values

KEY_PARAMETER_PATH

public static final String KEY_PARAMETER_PATH

See Also:

Constant Field Values

KEY_PATH

public static final String KEY_PATH

See Also:

Constant Field Values

Constructor Detail

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 Detail

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

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

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

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

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

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

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

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

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(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

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

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

saveParameters

protected static void saveParameters(LXComponent component,
                                     JsonObject obj,
                                     Map<String,LXParameter> parameters)

Utility function to serialize a set of parameters

Parameters:

component - Component that owns the parameters

obj - JsonObject to serialize to

parameters - Map of parameters to serialize

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