StoryboardManager Class Reference

The StoryboardManager JavaScript class. Access the main storyboard project and its components. More...

Public Slots

Queries - Sequences
int numberOfSequencesInProject ()
 Return the number of sequences in the project. More...
 
String sequenceInProject (int i)
 Return the sequenceId of the ith sequence in project. More...
 
String sequenceIdOfScene (String &sceneId)
 Return sequenceId of the sequence of the given scene. More...
 
Queries - Scenes
int numberOfScenesInSequence (String &sequenceId)
 Return the number of scenes in a sequence. More...
 
String sceneInSequence (String &sequenceId, int i)
 Return sceneId of the ith scene in sequence. More...
 
int numberOfScenesInProject ()
 Return the number of scenes in project. More...
 
String sceneInProject (int i)
 Return the sceneId of the ith scene in project. More...
 
String sceneIdOfPanel (String &panelId)
 Return the sceneId of the panel. More...
 
Queries - Panels
int numberOfPanelsInScene (String &sceneId)
 Return the number of panels in a scene. More...
 
String panelInScene (String &sceneId, int index)
 Return the panelId of the ith panel in the scene. More...
 
int numberOfPanelsInProject ()
 Return the number of panels in project. More...
 
String panelInProject (int i)
 Return panelId of the ith panel in the project. More...
 
Queries - General
String nameOfSequence (String &sequenceId)
 Return the name of the sequence. More...
 
String nameOfScene (String &sceneId)
 Return the name of the scene. More...
 
String nameOfPanel (String &panelId)
 Return the name of the panel. More...
 
String sequenceId (String &sequenceName)
 Return the unique id of the sequence. More...
 
String sceneId (String &sequenceName, String &sceneName)
 Return the unique id of the scene. More...
 
String panelId (String &sequenceName, String &sceneName, String &panelName)
 Return the unique id of the panel. More...
 
String actNameOfScene (String &shotId)
 Return the name of the act. More...
 
Commands to create/rename/delete
String createSequence (String &firstShotId, String &lastShotId)
 Create a new sequence. More...
 
String insertScene (bool after, String &shotId, String &name)
 Insert a new scene. More...
 
String appendScene (String &name)
 Append a scene at the end of the project. More...
 
String insertPanel (bool after, String &panelId, String &name)
 Insert a new panel. More...
 
String appendPanel (String &name)
 Append a panel at the end of the project. More...
 
bool splitPanel (String &panelId, unsigned int atFrame)
 Split a panel into 2 panels. More...
 
bool deleteSequence (String &seqId)
 Delete a sequence. More...
 
bool deleteScene (String &sceneId)
 Delete a scene. More...
 
bool deletePanel (String &panelId)
 Deletes a panel. More...
 
bool renameSequence (String &seqId, String &newName)
 Rename a sequence. More...
 
bool renameScene (String &sceneId, String &newName)
 Rename a scene. More...
 
String getValidSceneName (String &sceneId, String &baseName)
 Returns baseName if valid and unused or return a valid name based on baseName and naming rules. Returns empty string in case of error. More...
 
bool renamePanel (String &panelId, String &newName)
 Rename a panel. More...
 
int getPanelDuration (String &panelId)
 Get the panel Duration. More...
 
bool setPanelDuration (String &panelId, int frames)
 Set the panel duration. More...
 
void setPanelColor (String &panelId, QScriptValue &color)
 
String getPanelColor (String &panelId)
 
int sceneStartFrame (String &shotId)
 Return the start frame of a scene. More...
 
int sceneEndFrame (String &shotId)
 Return the last frame of a scene. More...
 
Transition Queries

For the sake of clarity, the trx is always associated with the shot to its right.

StringList scenesWithTrx ()
 Return a list of the sceneIds of scenes that have leading transitions. More...
 
String sceneIdOfTrx (String &trxId)
 Return the sceneId of the shot to the right of the transition. More...
 
String trxIdOfScene (String &shotId)
 Return the transition ID of the transition to the left of the shot. More...
 
bool sceneHasTrx (String &shotId)
 Return whether a scene has a leading transition. More...
 
String trxType (String &trxId)
 Return a string identifying the transition type. More...
 
int trxLength (String &trxId)
 Return the length of the transition. More...
 
Transition Commands to create/delete/modify
String createTrx (String &shotId, unsigned int length, String &stringType, int angle=90, bool reverse=false)
 Create a transition ( at the beginning of the target shot ), and return the unique ID of the transition. More...
 
bool modifyTrx (String &trxId, String &stringType, int angle=90, bool reverse=false)
 Modify the transition. More...
 
bool resizeTrx (String &trxId, unsigned int length)
 Resize a transition. More...
 
bool deleteTrx (String &trxId)
 Delete a transition. More...
 

Metadata Commands to Access/Modify

QScriptValue getProjectMetadata (String &name, String &type=QNTR("string"))
 Return the project metadata object corresponding to the given name and type. More...
 
QScriptValue getProjectMetadatas ()
 Return the list of metadatas for the current project. More...
 
void setProjectMetadata (QScriptValue &meta)
 Either inserts a new project metadata object or sets the value of an existing project metadata object. More...
 
bool removeProjectMetadata (QScriptValue &meta)
 Removes a project metadata object from the list of project metadata objects. More...
 
QScriptValue getPanelMetadata (String &panelId, String &name, String &type=QNTR("string"))
 Return the panel metadata object corresponding to the given name and type. More...
 
QScriptValue getPanelMetadatas (String &panelId)
 Return the list of metadatas for the specified panel. More...
 
void setPanelMetadata (String &panelId, QScriptValue &meta)
 Either inserts a new project metadata object or sets the value of an existing project metadata object. More...
 
bool removePanelMetadata (String &panelId, QScriptValue &meta)
 Removes a project metadata object from the list of project metadata objects. More...
 

Detailed Description

The StoryboardManager JavaScript class. Access the main storyboard project and its components.

It can be used to query the sequences, scenes, panels and transitions of the project. As well, it can be used to create, delete or rename project objects.

Scenes, Panels and Transitions are identified by a unique id. For the sake of clarity, a transition is considered to belong to the shot to it's right. Or, the shot owns the transition to it's left.

The following examples are provided:

function projectQuery()
{
var storyboard = new StoryboardManager();
// Iterate through all sequences
var nbSeqs = storyboard.numberOfSequencesInProject();
for ( var i =0; i < nbSeqs; ++i )
{
var id = storyboard.sequenceInProject( i );
System.println( "Sequence is " + id + " : " + storyboard.nameOfSequence( id ) ) ;
var nbScenes = storyboard.numberOfScenesInSequence( id );
for ( var j = 0; j < nbScenes; ++ j )
{
var sceneId = storyboard.sceneInSequence( id, j );
System.println( " scene is " + sceneId + " : " + storyboard.nameOfScene( sceneId ) ) ;
}
}
// Alternatively, iterate through all scenes.
var nbShots = storyboard.numberOfScenesInProject();
for ( var i =0; i < nbShots; ++i )
{
var sceneId = storyboard.sceneInProject(i);
var seqId = storyboard.sequenceIdOfScene( sceneId );
System.println( "Scene is " + sceneId + ": " + storyboard.nameOfScene( sceneId ) + " sequence is " + storyboard.nameOfSequence( seqId)) ;
}
}
function transitionQuery()
{
var sb = new StoryboardManager();
var sceneList = sb.scenesWithTrx();
for ( var i = 0; i < sceneList.length; ++i )
{
var trxId = sb.trxIdOfScene( sceneList[i] );
System.println(sb.nameOfScene( sceneList[i] )
+ " has a transition of type "
+ sb.trxType( trxId )
+ " and of length "
+ sb.trxLength( trxId ));
}
}

Member Function Documentation

◆ actNameOfScene

String StoryboardManager::actNameOfScene ( String &  shotId)
slot

Return the name of the act.

Parameters
shotId- unique ID of scene
Returns
A string containing the name of the act.
//this example script will print the act name of each scene in the message log
var storyboard = new StoryboardManager();
var nbShots = storyboard.numberOfScenesInProject();
for ( var i =0; i < nbShots; ++i )
{
var sceneId = storyboard.sceneInProject(i);
var actName = storyboard.actNameOfScene(sceneId);
MessageLog.trace("Act name of scene " + storyboard.nameOfScene(sceneId) + " is "+ actName);
}

◆ appendPanel

String StoryboardManager::appendPanel ( String &  name)
slot

Append a panel at the end of the project.

Parameters
name- name of new scene

◆ appendScene

String StoryboardManager::appendScene ( String &  name)
slot

Append a scene at the end of the project.

Parameters
name- name of new scene

◆ createSequence

String StoryboardManager::createSequence ( String &  firstShotId,
String &  lastShotId 
)
slot

Create a new sequence.

Parameters
firstShotId- sceneId of first targetShot
lastShotId- sceneId of last targetShot

◆ createTrx

String StoryboardManager::createTrx ( String &  shotId,
unsigned int  length,
String &  stringType,
int  angle = 90,
bool  reverse = false 
)
slot

Create a transition ( at the beginning of the target shot ), and return the unique ID of the transition.

Parameters
shotId- unique ID of the shot
length- length of transition, must be less than the length of the preceding panel
stringType- "wipe", "dissolve", "edge wipe", "clock wipe" or "slide"
angle- angle in degrees ( used for wipes )
reverse- bool to reverse the wipe direction.

◆ deletePanel

bool StoryboardManager::deletePanel ( String &  panelId)
slot

Deletes a panel.

Parameters
panelId- panelId of target panel

◆ deleteScene

bool StoryboardManager::deleteScene ( String &  sceneId)
slot

Delete a scene.

Parameters
sceneId- sceneId of target scene

◆ deleteSequence

bool StoryboardManager::deleteSequence ( String &  seqId)
slot

Delete a sequence.

Parameters
seqId- sceneId of sequence

◆ deleteTrx

bool StoryboardManager::deleteTrx ( String &  trxId)
slot

Delete a transition.

Parameters
trxId- unique ID of the transition

◆ getPanelColor

String StoryboardManager::getPanelColor ( String &  panelId)
slot

Get the color of the panel.

Parameters
panelId- panelId of the target panel
Returns
String of the panel's color name.

◆ getPanelDuration

int StoryboardManager::getPanelDuration ( String &  panelId)
slot

Get the panel Duration.

Parameters
panelId- panelId of target panel

◆ getPanelMetadata

QScriptValue StoryboardManager::getPanelMetadata ( String &  panelId,
String &  name,
String &  type = QNTR("string") 
)
slot

Return the panel metadata object corresponding to the given name and type.

Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Storyboard Pro",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Parameters
name: The name of the metadata object.
type: The metadata type.
Returns
A metadata object.

◆ getPanelMetadatas

QScriptValue StoryboardManager::getPanelMetadatas ( String &  panelId)
slot

Return the list of metadatas for the specified panel.

This method returns an array of javascript objects where each object represent a single metadata object. Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Storyboard Pro",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Returns
An array of metadata objects.

◆ getProjectMetadata

QScriptValue StoryboardManager::getProjectMetadata ( String &  name,
String &  type = QNTR("string") 
)
slot

Return the project metadata object corresponding to the given name and type.

Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Storyboard Pro",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Parameters
name: The name of the metadata object.
type: The metadata type.
Returns
A metadata object.

◆ getProjectMetadatas

QScriptValue StoryboardManager::getProjectMetadatas ( )
slot

Return the list of metadatas for the current project.

This method returns an array of javascript objects where each object represent a single metadata object. Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Storyboard Pro",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Returns
An array of metadata objects.

◆ getValidSceneName

String StoryboardManager::getValidSceneName ( String &  sceneId,
String &  baseName 
)
slot

Returns baseName if valid and unused or return a valid name based on baseName and naming rules. Returns empty string in case of error.

Parameters
sceneId- sceneId of target scene
baseName- name

◆ insertPanel

String StoryboardManager::insertPanel ( bool  after,
String &  panelId,
String &  name 
)
slot

Insert a new panel.

Parameters
after- whether the panel should be created after the target panel
panelId- panelId of target panel
name- name of new scene

◆ insertScene

String StoryboardManager::insertScene ( bool  after,
String &  shotId,
String &  name 
)
slot

Insert a new scene.

Parameters
after- whether the scene should be created after the target Shot
shotId- sceneId of targetShot
name- name of new scene

◆ modifyTrx

bool StoryboardManager::modifyTrx ( String &  trxId,
String &  stringType,
int  angle = 90,
bool  reverse = false 
)
slot

Modify the transition.

Parameters
trxId- unique ID of the transition
stringType- "wipe", "dissolve", "edge wipe", "clock wipe" or "slide"
angle- angle in degrees ( used for wipes )
reverse- bool to reverse the wipe direction.

◆ nameOfPanel

String StoryboardManager::nameOfPanel ( String &  panelId)
slot

Return the name of the panel.

Parameters
panelId- unique id of panel

◆ nameOfScene

String StoryboardManager::nameOfScene ( String &  sceneId)
slot

Return the name of the scene.

Parameters
sceneId- unique id of scene

◆ nameOfSequence

String StoryboardManager::nameOfSequence ( String &  sequenceId)
slot

Return the name of the sequence.

Parameters
sequenceId- unique id of sequence

◆ numberOfPanelsInProject

int StoryboardManager::numberOfPanelsInProject ( )
slot

Return the number of panels in project.

◆ numberOfPanelsInScene

int StoryboardManager::numberOfPanelsInScene ( String &  sceneId)
slot

Return the number of panels in a scene.

Parameters
sceneId- unique id of scene

◆ numberOfScenesInProject

int StoryboardManager::numberOfScenesInProject ( )
slot

Return the number of scenes in project.

◆ numberOfScenesInSequence

int StoryboardManager::numberOfScenesInSequence ( String &  sequenceId)
slot

Return the number of scenes in a sequence.

Parameters
sequenceId- unique id of sequence

◆ numberOfSequencesInProject

int StoryboardManager::numberOfSequencesInProject ( )
slot

Return the number of sequences in the project.

◆ panelId

String StoryboardManager::panelId ( String &  sequenceName,
String &  sceneName,
String &  panelName 
)
slot

Return the unique id of the panel.

Parameters
sequenceName- name of sequence
sceneName- name of scene
panelName- name of panel

◆ panelInProject

String StoryboardManager::panelInProject ( int  i)
slot

Return panelId of the ith panel in the project.

Parameters
i- index of the panel in the project

◆ panelInScene

String StoryboardManager::panelInScene ( String &  sceneId,
int  index 
)
slot

Return the panelId of the ith panel in the scene.

Parameters
sceneId- unique id of the scene
index- panel index in the scene

◆ removePanelMetadata

bool StoryboardManager::removePanelMetadata ( String &  panelId,
QScriptValue &  meta 
)
slot

Removes a project metadata object from the list of project metadata objects.

Parameters
meta: A metadata object.
Returns
true if the project metadata was successfully removed from the list.

◆ removeProjectMetadata

bool StoryboardManager::removeProjectMetadata ( QScriptValue &  meta)
slot

Removes a project metadata object from the list of project metadata objects.

Parameters
meta: A metadata object.
Returns
true if the project metadata was successfully removed from the list.

◆ renamePanel

bool StoryboardManager::renamePanel ( String &  panelId,
String &  newName 
)
slot

Rename a panel.

Parameters
panelId- panelId of target panel
newName- new name

◆ renameScene

bool StoryboardManager::renameScene ( String &  sceneId,
String &  newName 
)
slot

Rename a scene.

Parameters
sceneId- sceneId of target scene
newName- new name

◆ renameSequence

bool StoryboardManager::renameSequence ( String &  seqId,
String &  newName 
)
slot

Rename a sequence.

Parameters
seqId- sequenceId of target sequence
newName- new name

◆ resizeTrx

bool StoryboardManager::resizeTrx ( String &  trxId,
unsigned int  length 
)
slot

Resize a transition.

Parameters
trxId- unique ID of the transition
length- length of transition

◆ sceneEndFrame

int StoryboardManager::sceneEndFrame ( String &  shotId)
slot

Return the last frame of a scene.

Parameters
shotId- unique ID of scene

◆ sceneHasTrx

bool StoryboardManager::sceneHasTrx ( String &  shotId)
slot

Return whether a scene has a leading transition.

Parameters
shotId- unique ID of the scene

◆ sceneId

String StoryboardManager::sceneId ( String &  sequenceName,
String &  sceneName 
)
slot

Return the unique id of the scene.

Parameters
sequenceName- name of sequence
sceneName- name of scene

◆ sceneIdOfPanel

String StoryboardManager::sceneIdOfPanel ( String &  panelId)
slot

Return the sceneId of the panel.

Parameters
panelId- unique id of panel

◆ sceneIdOfTrx

String StoryboardManager::sceneIdOfTrx ( String &  trxId)
slot

Return the sceneId of the shot to the right of the transition.

Parameters
trxId- unique ID of the transition

◆ sceneInProject

String StoryboardManager::sceneInProject ( int  i)
slot

Return the sceneId of the ith scene in project.

Parameters
i- index in project

◆ sceneInSequence

String StoryboardManager::sceneInSequence ( String &  sequenceId,
int  i 
)
slot

Return sceneId of the ith scene in sequence.

Parameters
sequenceId- unique id of sequence
i- index in sequence

◆ sceneStartFrame

int StoryboardManager::sceneStartFrame ( String &  shotId)
slot

Return the start frame of a scene.

Parameters
shotId- unique ID of scene

◆ scenesWithTrx

StringList StoryboardManager::scenesWithTrx ( )
slot

Return a list of the sceneIds of scenes that have leading transitions.

◆ sequenceId

String StoryboardManager::sequenceId ( String &  sequenceName)
slot

Return the unique id of the sequence.

Parameters
sequenceName- name of sequence

◆ sequenceIdOfScene

String StoryboardManager::sequenceIdOfScene ( String &  sceneId)
slot

Return sequenceId of the sequence of the given scene.

Parameters
sceneId- unique id of scene

◆ sequenceInProject

String StoryboardManager::sequenceInProject ( int  i)
slot

Return the sequenceId of the ith sequence in project.

Parameters
i- sequence index in the project

◆ setPanelColor

void StoryboardManager::setPanelColor ( String &  panelId,
QScriptValue &  color 
)
slot

Set the panel colour.

Parameters
panelId- panelId of the target panel.
color- numerical value (HEX) or the name (See HTML naming convention) of the color we want to set the panel.

◆ setPanelDuration

bool StoryboardManager::setPanelDuration ( String &  panelId,
int  frames 
)
slot

Set the panel duration.

Parameters
panelId- panelId of target panel
frames- number of frames

◆ setPanelMetadata

void StoryboardManager::setPanelMetadata ( String &  panelId,
QScriptValue &  meta 
)
slot

Either inserts a new project metadata object or sets the value of an existing project metadata object.

If a metadata object already exist with the given name and type properties, then sets its value with the given value property. Otherwise, inserts a new metadata object with the given name, type(default is string), creator(default is executable), version(default is 1.0) and values properties. Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Storyboard Pro",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Parameters
meta: A metadata object.

◆ setProjectMetadata

void StoryboardManager::setProjectMetadata ( QScriptValue &  meta)
slot

Either inserts a new project metadata object or sets the value of an existing project metadata object.

If a metadata object already exist with the given name and type properties, then sets its value with the given value property. Otherwise, inserts a new metadata object with the given name, type(default is string), creator(default is executable), version(default is 1.0) and values properties. Here is an example of a metadata object:

{
"name" : "myMetadata",
"type" : "string",
"creator" : "Storyboard Pro",
"version" : "1.0",
"value" : "foo"
}

Supported values for type are: string, int, double, bool.

Parameters
meta: A metadata object.

◆ splitPanel

bool StoryboardManager::splitPanel ( String &  panelId,
unsigned int  atFrame 
)
slot

Split a panel into 2 panels.

Parameters
panelId- panelId of target panel
atFrame- frame at which to split ( measured from start of project )

◆ trxIdOfScene

String StoryboardManager::trxIdOfScene ( String &  shotId)
slot

Return the transition ID of the transition to the left of the shot.

Parameters
shotId- unique ID of the scene

◆ trxLength

int StoryboardManager::trxLength ( String &  trxId)
slot

Return the length of the transition.

Parameters
trxId- unique ID of the transition

◆ trxType

String StoryboardManager::trxType ( String &  trxId)
slot

Return a string identifying the transition type.

Parameters
trxId- unique ID of the transition