add MarkerCollection methods

docsforadobe · Aug 28, 2020 · 49d8eab · 49d8eab
1 parent 9a4fa21
commit 49d8eab
Show file tree

Hide file tree

Showing 3 changed files with 205 additions and 19 deletions.
diff --git a/docs/collection/markercollection.rst b/docs/collection/markercollection.rst
@@ -5,7 +5,8 @@
 MarkerCollection object
 ################################################
 
-``app.project.sequences[index].markers``
+|   ``app.project.sequences[index].markers``
+|   ``app.project.rootItem.children[index].getMarkers()``
 
 The MarkerCollection object represents a collection of :ref:`Marker objects <marker>` in a :ref:`projectItem` and :ref:`sequence`. 
 
@@ -22,12 +23,182 @@ Attributes
 MarkerCollection.numMarkers
 *********************************************
 
-``app.project.sequences[index].markers.numMarkers``
+|   ``app.project.sequences[index].markers.numMarkers``
+|   ``app.project.rootItem.children[index].getMarkers().numMarkers``
 
 **Description**
 
-The total number of marker objects in the sequence.
+The count of marker objects in the project item or sequence.
 
 **Type**
 
 Integer, read-only.
+
+----
+
+=======
+Methods
+=======
+
+.. _markerCollection.createMarker:
+
+MarkerCollection.createMarker()
+*********************************************
+
+|   ``app.project.sequences[index].markers.createMarker(time)``
+|   ``app.project.rootItem.children[index].getMarkers().createMarker(time)``
+
+**Description**
+
+Create a new :ref:`marker` on a project item or a sequence.
+
+**Parameters**
+
+================  ===========  =======================
+Argument          Type         Description
+================  ===========  =======================
+``time``          ``Float``    A time, in seconds, where marker should be created.
+================  ===========  =======================
+
+**Returns**
+
+:ref:`marker` if successful.
+
+----
+
+.. _markerCollection.deleteMarker:
+
+MarkerCollection.deleteMarker()
+*********************************************
+
+|   ``app.project.sequences[index].markers.deleteMarker(marker)``
+|   ``app.project.rootItem.children[index].getMarkers().deleteMarker(marker)``
+
+**Description**
+
+Remove a given marker object from a collection.
+
+**Parameters**
+
+================  =============  =======================
+Argument          Type           Description
+================  =============  =======================
+``marker``        :ref:`marker`  A marker object to remove from collection.
+================  =============  =======================
+
+**Returns**
+
+``Boolean``.
+
+**Examples**
+
+Remove all markers from the active sequence
+
+.. code:: javascript
+
+    var markers = app.project.activeSequence.markers;
+    var marker = markers.getFirstMarker();
+    var count = markers.numMarkers;
+
+    while (marker) {
+        markers.deleteMarker(marker);
+        marker = markers.getFirstMarker();
+    }
+
+    alert('Removed ' + count.toString() + ' markers');
+
+----
+
+.. _markerCollection.getFirstMarker:
+
+MarkerCollection.getFirstMarker()
+*********************************************
+
+|   ``app.project.sequences[index].markers.getFirstMarker()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker()``
+
+**Description**
+
+Retrieve the first marker object, sorted by time in seconds, on a given project item or sequence.
+
+**Parameters**
+
+None.
+
+**Returns**
+
+:ref:`marker` or ``undefined``.
+
+----
+
+.. _markerCollection.getLastMarker:
+
+MarkerCollection.getLastMarker()
+*********************************************
+
+|   ``app.project.sequences[index].markers.getLastMarker()``
+|   ``app.project.rootItem.children[index].getMarkers().getLastMarker()``
+
+**Description**
+
+Retrieve the very last marker object, sorted by time in seconds, on a given project item or sequence.
+
+**Parameters**
+
+None.
+
+**Returns**
+
+:ref:`marker` or ``undefined``.
+
+----
+
+.. _markerCollection.getNextMarker:
+
+MarkerCollection.getNextMarker()
+*********************************************
+
+|   ``app.project.sequences[index].markers.getNextMarker(currentMarker)``
+|   ``app.project.rootItem.children[index].getMarkers().getNextMarker(currentMarker)``
+
+**Description**
+
+Get the next available marker, sorted by seconds, starting from a given one.
+
+**Parameters**
+
+==================  =============  =======================
+Argument            Type           Description
+==================  =============  =======================
+``currentMarker``   :ref:`marker`  A starting marker object, from which to get a next one.
+==================  =============  =======================
+
+**Returns**
+
+:ref:`marker` or ``undefined``.
+
+----
+
+.. _markerCollection.getPrevMarker:
+
+MarkerCollection.getPrevMarker()
+*********************************************
+
+|   ``app.project.sequences[index].markers.getPrevMarker(currentMarker)``
+|   ``app.project.rootItem.children[index].getMarkers().getPrevMarker(currentMarker)``
+
+**Description**
+
+Get the previous available marker, sorted by seconds, starting from a given one.
+
+**Parameters**
+
+==================  =============  =======================
+Argument            Type           Description
+==================  =============  =======================
+``currentMarker``   :ref:`marker`  A starting marker object, from which to get a previous one.
+==================  =============  =======================
+
+**Returns**
+
+:ref:`marker` or ``undefined``.
diff --git a/docs/general/marker.rst b/docs/general/marker.rst
@@ -5,7 +5,8 @@
 Marker object
 ==========================
 
-``app.project.activeSequence.markers.getFirstMarker()``
+|   ``app.project.activeSequence.markers.getFirstMarker()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker()``
 
 **Description**
 
@@ -22,7 +23,8 @@ Attributes
 Marker.comments
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().comments``
+|   ``app.project.activeSequence.markers.getFirstMarker().comments``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().comments``
 
 **Description**
 
@@ -39,7 +41,8 @@ String; read/write.
 Marker.end
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().end``
+|   ``app.project.activeSequence.markers.getFirstMarker().end``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().end``
 
 **Description**
 
@@ -56,7 +59,8 @@ A :ref:`time` containing the value of the ending of the marker.
 Marker.guid
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().guid``
+|   ``app.project.activeSequence.markers.getFirstMarker().guid``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().guid``
 
 **Description**
 
@@ -73,7 +77,8 @@ String; read-only.
 Marker.name
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().name``
+|   ``app.project.activeSequence.markers.getFirstMarker().name``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().name``
 
 **Description**
 
@@ -90,7 +95,8 @@ String; read/write.
 Marker.start
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().start``
+|   ``app.project.activeSequence.markers.getFirstMarker().start``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().start``
 
 **Description**
 
@@ -107,7 +113,8 @@ A :ref:`time` containing the value of the beginning of the marker.
 Marker.type
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().type``
+|   ``app.project.activeSequence.markers.getFirstMarker().type``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().type``
 
 **Description**
 
@@ -128,7 +135,8 @@ Methods
 Marker.getColorByIndex()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().getColorByIndex(index)``
+|   ``app.project.activeSequence.markers.getFirstMarker().getColorByIndex(index)``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().getColorByIndex(index)``
 
 .. note::
     This functionality was added in Adobe Premire Pro 13.x.
@@ -156,7 +164,8 @@ Returns the color index as an ``Integer``.
 Marker.getWebLinkFrameTarget()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().getWebLinkFrameTarget()``
+|   ``app.project.activeSequence.markers.getFirstMarker().getWebLinkFrameTarget()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().getWebLinkFrameTarget()``
 
 **Description**
 
@@ -177,7 +186,8 @@ Returns a ``String`` containing the frame target, or **0** if unsuccessful.
 Marker.getWebLinkURL()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().getWebLinkURL()``
+|   ``app.project.activeSequence.markers.getFirstMarker().getWebLinkURL()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().getWebLinkURL()``
 
 **Description**
 
@@ -198,7 +208,8 @@ Returns a ``String`` containing the URL, or **0** if unsuccessful.
 Marker.setColorByIndex()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().setColorByIndex(colorIndex, markerIndex)``
+|   ``app.project.activeSequence.markers.getFirstMarker().setColorByIndex(colorIndex, markerIndex)``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().setColorByIndex(colorIndex, markerIndex)``
 
 .. note::
     This functionality was added in Adobe Premire Pro 13.x.
@@ -236,7 +247,8 @@ Returns ``undefined``.
 Marker.setTypeAsChapter()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().setTypeAsChapter()``
+|   ``app.project.activeSequence.markers.getFirstMarker().setTypeAsChapter()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().setTypeAsChapter()``
 
 **Description**
 
@@ -257,7 +269,8 @@ Returns **0** if successful.
 Marker.setTypeAsComment()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().setTypeAsComment()``
+|   ``app.project.activeSequence.markers.getFirstMarker().setTypeAsComment()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().setTypeAsComment()``
 
 **Description**
 
@@ -278,7 +291,8 @@ Returns **0** if successful.
 Marker.setTypeAsSegmentation()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().setTypeAsSegmentation()``
+|   ``app.project.activeSequence.markers.getFirstMarker().setTypeAsSegmentation()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().setTypeAsSegmentation()``
 
 **Description**
 
@@ -299,7 +313,8 @@ Returns **0** if successful.
 Marker.setTypeAsWebLink()
 *********************************************
 
-``app.project.activeSequence.markers.getFirstMarker().setTypeAsWebLink()``
+|   ``app.project.activeSequence.markers.getFirstMarker().setTypeAsWebLink()``
+|   ``app.project.rootItem.children[index].getMarkers().getFirstMarker().setTypeAsWebLink()``
 
 **Description**
 

diff --git a/docs/item/projectitem.rst b/docs/item/projectitem.rst
@@ -566,7 +566,7 @@ ProjectItem.getMarkers()
 
 **Description**
 
-Retrieves the :ref:`Marker <marker>` objects associated with this project item.
+Retrieves the :ref:`markerCollection` associated with this project item.
 
 **Parameters**