CuePointManager

Kind of class:class
Inherits from:none
Classpath:mx.video.CuePointManager
File last modified:Tuesday, 18 December 2007, 16:18:43

Event dispatched when a cue point is reached. Event Object has an
info property that contains the info object received by the
NetStream.onCuePoint callback for FLV cue points or
the object passed into the AS cue point APIs for AS cue points.

Component metadata:
    Event
    "cuePoint"

    Summary


    Constructor
    Class properties
    Instance properties
    Class methods
    • cuePointCompare (time:Number, name:String, cuePoint:Object) : Number
      • Takes two cue point Objects and returns -1 if first sorts
    • deepCopyObject (obj:Object, recurseLevel:Number) : Object
      • Used to make copies of cue point objects.
    Instance methods

    Constructor

    CuePointManager

    function CuePointManager (
    owner:FLVPlayback, id:Number)

    Constructor.

    Class properties

    cuePointsReplace

    static private cuePointsReplace:Array = [
    (read)

    DEFAULT_LINEAR_SEARCH_TOLERANCE

    static private DEFAULT_LINEAR_SEARCH_TOLERANCE:Number = 50
    (read)

    Instance properties

    _asCuePointIndex

    private _asCuePointIndex:Number
    (read)

    _asCuePointTolerance

    private _asCuePointTolerance:Number
    (read)

    _disabledCuePoints

    private _disabledCuePoints:Array
    (read)

    _disabledCuePointsByNameOnly

    private _disabledCuePointsByNameOnly:Object
    (read)

    _id

    private _id:Number
    (read)

    _linearSearchTolerance

    private _linearSearchTolerance:Number
    (read)

    _metadataLoaded

    private _metadataLoaded:Boolean
    (read)

    _owner

    private _owner:FLVPlayback
    (read)

    allCuePoints

    allCuePoints:Array
    (read)

    asCuePoints

    asCuePoints:Array
    (read)

    eventCuePoints

    eventCuePoints:Array
    (read)

    flvCuePoints

    flvCuePoints:Array
    (read)

    id

    id:Number
    (read)

    corresponds to _vp and _cpMgr array index in FLVPlayback

    metadataLoaded

    metadataLoaded:Boolean
    (read)

    read only, has metadata been loaded

    playheadUpdateInterval

    playheadUpdateInterval:Number
    (write)

    Set by FLVPlayback to update _asCuePointTolerance

    Class methods

    cuePointCompare

    static private function cuePointCompare (
    time:Number, name:String, cuePoint:Object) : Number

    Takes two cue point Objects and returns -1 if first sorts
    before second, 1 if second sorts before first and 0 if they are
    equal. First compares times with millisecond precision. If
    they match, compares name if name parameter is not null or undefined.

    deepCopyObject

    static private function deepCopyObject (
    obj:Object, recurseLevel:Number) : Object

    Used to make copies of cue point objects.

    Instance methods

    addASCuePoint

    function addASCuePoint (
    timeOrCuePoint:Object, name:String, parameters:Object) : Object

    Add an ActionScript cue point.

    It is legal to add multiple AS cue points with the same
    name and time. When removeASCuePoint is called with this
    name and time, all will be removed.

    Parameters:
    timeOrCuePoint:
    If Object, then object describing the cue
    point. Must have a name:String and time:Number (in seconds)
    property. May have a parameters:Object property that holds
    name/value pairs. May have type:String set to "actionscript",
    if it is missing or set to something else it will be set
    automatically. If the Object does not conform to these
    conventions, a VideoError will be thrown.

    If Number, then time for new cue point to be added
    and name parameter must follow.

    name :
    Name for cuePoint if timeOrCuePoint parameter
    is a Number.
    parameters :
    Optional parameters for cuePoint if
    timeOrCuePoint parameter is a Number.
    Returns:
    • A copy of the cuePoint Object added. The copy has the
      following additional properties:
      • array - the array of all AS cue points. Treat
        this array as read only as adding, removing or editing objects
        within it can cause cue points to malfunction.
      • index - the index into the array for the
        returned cuepoint.
    Throws:
    See also:

    addOrDisable

    private function addOrDisable (
    disable:Boolean, cuePoint:Object) : Void

    Used by processCuePointsProperty

    dispatchASCuePoints

    function dispatchASCuePoints (
    ) : Void

    Called by FLVPlayback on "playheadUpdate" event
    to throw "cuePoint" events when appropriate.

    getCuePoint

    function getCuePoint (
    cuePointArray:Array, closeIsOK:Boolean, timeNameOrCuePoint:Object) : Object

    Search for a cue point in the given array at the given time
    and/or with given name.

    Parameters:
    closeIsOK :
    If true, the behavior differs depending on the
    parameters passed in:
    • If name is null or undefined, then if the specific time is
      not found then the closest time earlier than that is returned.
      If there is no cue point earlier than time, the first cue point
      is returned.
    • If time is null, undefined or less than 0 then the first
      cue point with the given name is returned.
    • If time and name are both defined then the closest cue
      point, then if the specific time and name is not found then the
      closest time earlier than that with that name is returned. If
      there is no cue point with that name and with an earlier time,
      then the first cue point with that name is returned. If there
      is no cue point with that name, null is returned.
    • If time is null, undefined or less than 0 and name is null
      or undefined, a VideoError is thrown.

    If closeIsOK is false the behavior is:

    • If name is null or undefined and there is a cue point with
      exactly that time, it is returned. Otherwise null is
      returned.
    • If time is null, undefined or less than 0 then the first
      cue point with the given name is returned.
    • If time and name are both defined and there is a cue point
      with exactly that time and name, it is returned. Otherwise null
      is returned.
    • If time is null, undefined or less than 0 and name is null
      or undefined, a VideoError is thrown.
    timeOrCuePoint:
    If String, then name for search. If
    Number, then time for search. If Object, then cuepoint object
    containing time and/or name parameters for search.
    Returns:
    • null if no match was found, otherwise
      copy of cuePoint object with additional properties:
      • array - the array that was searched. Treat
        this array as read only as adding, removing or editing objects
        within it can cause cue points to malfunction.
      • index - the index into the array for the
        returned cuepoint.
    See also:

    getCuePointIndex

    private function getCuePointIndex (
    cuePointArray:Array, closeIsOK:Boolean, time:Number, name:String, start:Number, len:Number) : Number

    Search for a cue point in an array sorted by time. See
    closeIsOK parameter for search rules.
    Parameters:
    cuePointArray:
    array to search
    closeIsOK :
    If true, the behavior differs depending on the
    parameters passed in:
    • If name is null or undefined, then if the specific time is
      not found then the closest time earlier than that is returned.
      If there is no cue point earlier than time, the first cue point
      is returned.
    • If time is null, undefined or less than 0 then the first
      cue point with the given name is returned.
    • If time and name are both defined then the closest cue
      point, then if the specific time and name is not found then the
      closest time earlier than that with that name is returned. If
      there is no cue point with that name and with an earlier time,
      then the first cue point with that name is returned. If there
      is no cue point with that name, null is returned.
    • If time is null, undefined or less than 0 and name is null
      or undefined, a VideoError is thrown.

    If closeIsOK is false the behavior is:

    • If name is null or undefined and there is a cue point with
      exactly that time, it is returned. Otherwise null is
      returned.
    • If time is null, undefined or less than 0 then the first
      cue point with the given name is returned.
    • If time and name are both defined and there is a cue point
      with exactly that time and name, it is returned. Otherwise null
      is returned.
    • If time is null, undefined or less than 0 and name is null
      or undefined, a VideoError is thrown.
    time :
    search criteria
    name :
    search criteria
    start :
    index of first item to be searched, used for
    recursive implementation, defaults to 0 if undefined
    len :
    length of array to search, used for recursive
    implementation, defaults to cuePointArray.length if undefined
    Returns:
    • index for cue point in given array or -1 if no match found
    Throws:
    • VideoError if time and/or name parameters are bad
    See also:

    getNextCuePointIndexWithName

    private function getNextCuePointIndexWithName (
    name:String, array:Array, index:Number) : Number

    Given a name, array and index, returns the next cue point in
    that array after given index with the same name. Returns null
    if no cue point after that one with that name. Throws
    VideoError if argument is invalid.

    Returns:
    • index for cue point in given array or -1 if no match found

    getNextCuePointWithName

    function getNextCuePointWithName (
    cuePoint:Object) : Object

    Given a cue point object returned from getCuePoint (needs
    the index and array properties added to those cue points),
    returns the next cue point in that array after that one with
    the same name. Returns null if no cue point after that one
    with that name. Throws VideoError if argument is invalid.

    Returns:
    • null if no match was found, otherwise
      copy of cuePoint object with additional properties:
      • array - the array that was searched. Treat
        this array as read only as adding, removing or editing objects
        within it can cause cue points to malfunction.
      • index - the index into the array for the
        returned cuepoint.

    insertCuePoint

    private function insertCuePoint (
    insertIndex:Number, cuePointArray:Array, cuePoint:Object) : Array

    inserts cue points into array

    isFLVCuePointEnabled

    function isFLVCuePointEnabled (
    timeNameOrCuePoint:Object) : Boolean

    Returns false if FLV embedded cue point is disabled by
    ActionScript. Cue points are disabled via setting the
    cuePoints property or by calling
    setFLVCuePointEnabled().

    The return value from this function is only meaningful when
    metadata is true. It always returns false
    when it is null.

    Parameters:
    timeNameOrCuePoint:
    If string, name of cue point to
    check; return false only if ALL cue points with this name are
    disabled. If number, time of cue point to check. If Object,
    then object with name and time properties, check cue point that
    matches both name and time.
    Returns:
    • false if cue point(s) is found and is disabled, true
      either if no such cue point exists or if it is not disabled.
      If time given is undefined, null or less than 0 then returns
      false only if all cue points with this name are disabled.

      The return value from this function is only meaningful when
      metadata is true. It always returns true when it
      is false.

    See also:

    processCuePointsProperty

    function processCuePointsProperty (
    cuePoints:Array) : Void

    Process Array passed into FLVPlayback cuePoints property.
    Array actually holds name value pairs. Each cue point starts
    with 5 pairs: t,time,n,name,t,type,d,disabled,p,numparams.
    time is a Number in milliseconds (e.g. 3000 = 3 seconds), name
    is a String, type is a Number (0 = event, 1 = navigation, 2 =
    actionscript), disabled is a Number (0 for false, 1 for true)
    and numparams is a Number. After this, there are numparams
    name/value pairs which could be any simple type.

    Note that all Strings are escaped with html/xml entities for
    ampersand (&), double quote ("), single quote (')
    and comma (,), so must be unescaped.

    See also:

    processFLVCuePoints

    function processFLVCuePoints (
    metadataCuePoints:Array) : Void

    Called by FLVPlayback "metadataReceived" event handler to process flv
    embedded cue points array.

    removeASCuePoint

    function removeASCuePoint (
    timeNameOrCuePoint:Object) : Object

    Remove an ActionScript cue point from the currently
    loaded FLV. Only the name and time properties are used
    from the cuePoint parameter to find the cue point to be
    removed.

    If multiple AS cue points match the search criteria, only
    one will be removed. To remove all, call this function
    repeatedly in a loop with the same parameters until it returns
    null.

    Parameters:
    timeNameOrCuePoint:
    If string, name of cue point to
    remove; remove first cue point with this name. If number, time
    of cue point to remove; remove first cue point at this time.
    If Object, then object with name and time properties, remove
    cue point with both this name and time.
    Returns:
    • The cue point that was removed. If there was no
      matching cue point then null is returned.
    See also:

    removeCuePoints

    private function removeCuePoints (
    cuePointArray:Array, cuePoint:Object) : Number

    removes enabled cue points from _disabledCuePoints

    reset

    function reset (
    )

    Reset cue point lists

    resetASCuePointIndex

    function resetASCuePointIndex (
    time:Number) : Void

    When our place in the stream is changed, this is called
    to reset our index into actionscript cue point array.
    Another method is used when AS cue points are added
    are removed.

    setFLVCuePointEnabled

    function setFLVCuePointEnabled (
    enabled:Boolean, timeNameOrCuePoint:Object) : Number

    Enable or disable one or more FLV cue point. Disabled cue
    points are disabled for being dispatched as events and
    navigating to them with seekToPrevNavCuePoint(),
    seekToNextNavCuePoint() and
    seekToNavCuePoint().

    If this API is called just after setting the
    contentPath property or if no FLV is loaded, then
    the cue point will be enabled or disabled in the FLV to be
    loaded. Otherwise, it will be enabled or disabled in the
    currently loaded FLV (even if it is called immediately before
    setting the contentPath property to load another
    FLV).

    Changes caused by calls to this function will not be
    reflected in results returned from
    isFLVCuePointEnabled until
    metadataLoaded is true.

    Parameters:
    enabled :
    whether to enable or disable FLV cue point
    timeNameOrCuePoint:
    If string, name of cue point to
    enable/disable. If number, time of cue point to
    enable/disable. If Object, then object with name and time
    properties, enable/disable cue point that matches both name and
    time.
    Returns:
    • If metadataLoaded is true, returns number
      of cue points whose enabled state was changed. If
      metadataLoaded is false, always returns -1.
    See also:

    unescape

    private function unescape (
    origStr:String) : String

    Used by processCuePointsProperty