// All class methods imply a handle parameter in the JSON params object (see examples).
namespace Pixera
{
// Ui namespace is only accessible from plugins hosted in Pixera, i.e. it is
// not relevant to external API access.
namespace Ui
{
   handle getComboBoxWithId(double id);

   class ComboBox
   {
      null clear();
      null addItem(string item,int id);
      null setSelectedId(int id);
      int getSelectedId();
   }
}

namespace Utility
{
   // Outputs a debug string into the Pixera log and returns the same string in
   // the reply.
   string outputDebug(string message);
   int getApiRevision();

   // Experimental. Currently only relevant to Javascript interpretation within Pixera.
   null requestCallback(string functionName);
}

namespace Screens
{
   // Screen name as shown in the inspector.
   handle getScreenWithName(string name);

   // This function was introduced for test purposes, is not typical of the API
   // and is likely to be removed soon. Do not use it in shipping products!
   // The function sets the position of the screen with the given name.
   // The recommended way of doing this is to first use getScreenWithName(.) and
   // then Screen.setPosition(.).
   null setNamedScreenPosition(string name,double xPos,double yPos,double zPos);

   // Returns handles to all screens currently used in the Screens tab.
   handle[] getScreens();

   class Screen
   {
      // The position units are as in the inspector, i.e. meters.
      boolean setPosition(double xPos,double yPos,double zPos);
      string getName();
   }
}

namespace Resources
{
   // Returns handles to all resources (including within subfolders) in the resource
   // tree in the Compositing tab.
   handle[] getResources();

   // Returns a handle to a folder in the resource tree. The namePath
   // specifies the folder by starting from the root and then listing
   // all the names as seen in the resources tree separated by forward
   // slashes, e.g. "Media/Std Backgrounds/Atmospherics".
   handle getResourceFolderWithNamePath(string namePath);

   class ResourceFolder
   {
      // Returns handles to all the resources that are directly in one folder (i.e. does not consider subfolders).
      handle[] getResources();
   }

   class Resource
   {
      string getName();

      // Returns an id based on the handle. This is currently necessary in some situations
      // because some API implementations can not yet consume handles as parameters.
      double getId();

      // Returns the png thumbnail data of the resource in a base 64 string. This is the
      // image that is shown in the resource tree. Its resolution is currently 256 * 174
      // pixels.
      string getThumbnailAsBase64();
   }
}

namespace Timelines
{
   // Returns the handle of the timeline at the (zero-based) index in
   // the Timelines listing of the Compositing tab.
   handle getTimelineAtIndex(int index);

   // Returns the handle of the timeline with the given name (as shown in the 
   // timeline list).
   handle getTimelineFromName(string name);

   // Returns handles to all timelines.
   handle[] getTimelines();

   class Timeline
   {
      // Sets the current position of the timeline. The unit is frames. Use getFps(.) to
      // relate the frames to seconds.
      // This method will likely be changed in future versions of the API (but the original
      // maintained for backwards compatibility) to make it consistent with getCurrentTime(.).
      boolean setCurrentFrame(int time);

      // Gets the current position of the timeline in frames. Use getFps(.) to relate
      // the frames to seconds.
      double getCurrentTime();

      // Sets the transport mode.
      // 1: Play
      // 2: Pause
      // 3: Stop
      boolean setTransportMode(int mode);

      // Returns the frames per second value used as a time base.
      double getFps();

      // Returns the name of the timeline with the given handle.
      string getName();
      null store();

      // Returns a handle to the layer in the timeline at the (zero-based) index in
      // the order as shown in the Pixera Timeline interface.
      handle getLayerAtIndex(int index);

      // Creates a layer and returns a handle to it.
      handle createLayer();

      // Returns the handles of all cues in chronological order.
      handle[] getCues();

      // Returns the handle of the cue with the given Index. 
      // Order of indices is in chronological order.
      handle getCueAtIndex(int index);

      // Returns the handle of the cue with the given name.
      // If multiple cues have the same name, the handle to the first match will be returned.
      handle getCueFromName(string name);

      // Creates a cue on the timeline with the given handle and returns its handle.
      handle createCue(string name,double time,int operation);
   }

   class Layer
   {
      // Returns a node immediately below the layer based on the name displayed in the 
      // Timeline UI (e.g. the "Position" node below a standard layer).
      handle getNodeWithName(string name);

      // Assigns a resource to the layer. The id is conceptually the handle but the
      // handle can not be passed directly for some implementations of the API. Therefore,
      // Resource.getId() should be used to fill this parameter.
      null assignResource(double id);

      // Creates a clip and returns a handle to it.
      handle createClip();

      // Creates a clip at the given time and returns a handle to it.
      handle createClipAtTime(double time);
   }

   class Clip
   {
      // Returns an id based on the handle. This is currently necessary in some situations
      // because some API implementations can not yet consume handles as parameters. 
      double getId();

      // Returns a handle to the timeline in which the clip is situated.
      handle getTimeline();
      double getTime();
      double getDuration();

      // Assigns a resource to the resource parameter within the clip.
      // Conceptually, the resId is a handle but the handle can not be passed directly for
      // some implementations of the API. Therefore, Resource.getId() should be used to
      // fill this parameter.
      null assignResource(double resId);

      // Creates a key at the given time with the given value in the clip parameter specified by
      // namePath, with the parts of namePath consisting of the strings shown in the timeline UI.
      // E.g. "Position/x" refers to the parameter responsible for the x position of the layer.
      // The name of this method may be changed in future versions of the API to reflect the 
      // "key" (instead of "event") terminology.
      null createEvent(string namePath,double time,double value);
   }


   // Returns a handle for the node specified by id after checking that a node with the id exists.
   // Conceptually, the id and the handle are the same but some implementations of the API can not
   // yet consume handles as parameters, making it necessary to translate between the two occasionally.
   handle getNodeFromId(double id);

   class Node
   {
      // Returns a handle to a parameter node child with the given name. E.g. if the current
      // node is the "Position" folder then the name "x" would return the parameter node
      // representing the x position of the layer.
      handle getParamWithName(string name);

      // Sets the values of the children of the node in the order that they are displayed
      // in the timeline. This allows e.g. setting the x, y, and z values of a node with
      // one invocation.
      null setValues(double[] values);

      // Returns a handle to the timeline that holds the node.
      handle getTimeline();
   }

   class Param
   {
      null setValue(double value);
   }

   class Cue
   {
      // Returns the name of the Cue with the give handle.
      string getName();

      // Sets Name of Cue with given handle.
      boolean setName(string name);

      // Returns operation mode of cue with given handle.
      // 0: None
      // 1: Play
      // 2: Pause
      // 3: Stop
      // 4: Jump
      int getOperation();

      // Sets operation mode for cue with given handle:
      // 0: None
      // 1: Play
      // 2: Pause
      // 3: Stop
      // 4: Jump
      boolean setOperation(int operation);

      // Returns jump mode of cue with given handle.
      // 0: None
      // 1: To time
      // 2: To cue
      int getJumpMode();

      // Sets jump mode of cue with given handle, this does only affect the cue
      // if it has its operation set to jump.
      // 0: None
      // 1: To time
      // 2: To cue
      boolean setJumpMode(int jumpMode);

      // Returns the time in frames of the jump goal of the cue with the given handle.
      double getJumpGoalTime();

      // Sets the time where the timline should jump to if the cue with the given handle is reached.
      // This only affects the cue if it's set to jumpToTime.
      boolean setJumpGoalTime(double time);

      // Returns the name of the cue the time line should jump to if the cue with the given handle is reached.
      string getJumpGoalLabel();

      // Returns the handle of the cue the time line should jump to if the cue with the given handle is reached.
      handle getJumpGoalCue();

      // Sets the name of the cue to wich the timeline should jump if the cue with the given handle is reached.
      // This only affects the cue if it's set to jumpToLabel.
      boolean setJumpGoalLabel(string jumpGoalLabel);
   }
}

}