ControlPoint (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface ControlPoint

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject
  All Known Implementing Classes:
    ControlPointImpl

      public interface ControlPoint
      extends InterchangeObject

  Specifies a value and a time point (position) that is used to specify an effect control value. Control points must be added to a varying value that is then added to the operation group describing the effect.

  For parameters that are a constant value for an operation group, use a constant value.

  See Also:
    `VaryingValue.getControlPoints()`, `TypeDefinitions.ControlPointStrongReference`, `TypeDefinitions.ControlPointStrongReferenceVector`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `ControlPoint` | `clone()` Create a cloned copy of this control point.
    `PropertyValue` | `getControlPointValue()` Returns the control point value at the control point's position (time), which contains the type and value as a property value.
    `EditHintType` | `getEditHint()` Returns the edit hint of the control point, which describes how to alter the position (time) of the operation group is made longer or shorter.
    `Rational` | `getTime()` Returns the time property of this control point, which specifies the time within the varying value segment for which the value is defined.
    `TypeDefinition` | `getTypeDefinition()` Returns the type definition of the value of this control point.
    `void` | `setControlPointTime(Rational controlPointTime)` Sets the position of the control point within an operation group, which specifies the time within the varying value segment for which the value is defined.
    `void` | `setControlPointValue(PropertyValue controlPointValue)` Set the data value describing this control point at the control point's position (time).
    `void` | `setEditHint(EditHintType editHint)` Sets the control point edit hint value, which describes how to alter the position (time) if the operation group is made longer or shorter.

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

- - ### Method Detail

    - #### getTime

          Rational getTime()

      Returns the time property of this control point, which specifies the time within the varying value segment for which the value is defined. The value of the time property should be between&nbps;0 and 1 inclusive.

      Returns:
        Time property of this control point.

    - #### getEditHint

          EditHintType getEditHint()
                            throws PropertyNotPresentException

      Returns the edit hint of the control point, which describes how to alter the position (time) of the operation group is made longer or shorter. This is an optional property.

      Returns:
        A hint to be used if the effect starting time or length is changed during editing.
      Throws:
        `PropertyNotPresentException` - The optional edit hint property is not present for this control point.

    - #### getControlPointValue

          PropertyValue getControlPointValue()

      Returns the control point value at the control point's position (time), which contains the type and value as a property value.

      Returns:
        Control point value.
      See Also:
        `TypeDefinitionIndirect`, `getTypeDefinition()`, `PropertyValue.getType()`, `PropertyValue.getValue()`

    - #### setControlPointTime

          void setControlPointTime(Rational controlPointTime)
                            throws RationalRangeException,
                                   NullPointerException

      Sets the position of the control point within an operation group, which specifies the time within the varying value segment for which the value is defined. The value is expressed as a rational value between from 0 to 1.

      Parameters:
        `controlPointTime` - Control point time.
      Throws:
        `RationalRangeException` - The rational value is outside the range 0 to 1.
        `NullPointerException` - The given time value is `null`.

    - #### setEditHint

          void setEditHint(EditHintType editHint)

      Sets the control point edit hint value, which describes how to alter the position (time) if the operation group is made longer or shorter. Set this optional property to `null` to omit it.

      Parameters:
        `editHint` - Specifies a hint to be used if the effect starting time or length is changed during editing.

    - #### getTypeDefinition

          TypeDefinition getTypeDefinition()

      Returns the type definition of the value of this control point.

      Returns:
        Type definition associated with the control point data value inside this object.
      See Also:
        `TypeDefinitionIndirect`

    - #### setControlPointValue

          void setControlPointValue(PropertyValue controlPointValue)
                             throws NullPointerException,
                                    ClassCastException

      Set the data value describing this control point at the control point's position (time). The value must be a property value containing the type and current value for the control point.

      To create a control value of a specific type, use the `createValue()` method of a `type definition`. To access a type definition, use the `getTypeDefinition()` method as follows:

                controlPoint.setControlPointValue(
                    controlPoint.getTypeDefinition().createValue(42));

      Alternatively, you can retrieve the value of any other property using its property definition. To retrieve the property value of a property called foo from an instance called bar:

                ClassDefinition barClassDef =
                    ClassDefinitionWarehouse.forClass(bar.getClass());
                PropertyDefinition fooDefinition =
                    barClassDef.lookupPropertyDefinition("foo");
                PropertyValue fooValue =
                   fooDefinition.getPropertyValue(bar);

      Parameters:
        `controlPointValue` - The value of this control point at its position (time).
      Throws:
        `NullPointerException` - The given control point value is `null`.
        `ClassCastException` - Cannot cast the given value to the defined type for this control point.
      See Also:
        `TypeDefinition.createValue(Object)`, `PropertyValue.getValue()`, `ConstantValue.setValue(PropertyValue)`

    - #### clone

          ControlPoint clone()

      Create a cloned copy of this control point.

      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this control point.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.