Edison 脚本参考
=======================

0. 脚本
----------
- 脚本必须在 .edscript 文件内
- 一个脚本的头部开始必须是这样: 
     script "Pulse generator" language "pascal";
  language(语言)可以是 "pascal", "javascript" 或 "basic"
- 附加 units/modules 可以是常规 .pas/.js/.bas 文件



1. 全局变量
-------------------
CRLF			string		显示多行消息
Editor			TEditor		Edison 的一个实例作为波形编辑器
EditorSample		TSample		采样的一个实例加载到 Edison 波形编辑器中
ScriptPath		string		脚本文件被执行路径



2. 全局函数
-------------------
ProgressMsg		procedure ProgressMsg(const Msg:String;Pos,Total:Integer);			在 Edison/FL 中显示一个进度消息
ShowMessage		procedure ShowMessage(const s: string);						显示一个消息对话框



3. Delphi/Windows 函数
---------------------------
Dec    			procedure dec_(var Value, Decrement: integer);		减去一个整数值
FloatToStr		function FloatToStr(Value: extended): string;		转换一个浮点值为一个字符串
Inc			procedure inc_(var Value, Increment: integer);		加上一个整数值
IntToStr		function IntToStr(Value: integer): string;		转换一个整数值为一个字符串
Round			function Round(Value: double): integer;			四舍五入一个浮点值为一个整数
TimeGetTime		function timeGetTime: integer; stdcall;			返回 Windows 自启动以来运行的时间 ms 数(可以用于脚本的时间部分)



4. Wave 相关类
-----------------------
  // PasteFromTo 模式
  0: insert	插入
  1: replace	替换
  2: mix	混合

  // NormalizeFormat Mode flags (需结合使用)
  NF_NumChannels	: 规格化通道编号
  NF_Format		: 规格化采样格式
  NF_Samplerate		: 规格化采样速率
  NF_All		: 规格化全部(结合所有标识)


  // 区域
  TRegion = class
    constructor Create;				构造函数调用类似这样(区域是一个 TRegion 变量): Region := TRegion.Create;
    procedure Copy(Source: TRegion);		复制来源区域属性到此对象
    property SampleStart: integer;		此区域的开始, 单位是采样
    property SampleEnd: integer;		此区域的结尾, 单位是采样。如果区域大于采样的长度, 区域被一个标记所代替
    property Name: string;			区域的名称(将在 Edison 显示)
    property Info: string;			一些附加字符串信息
    property Time: single;			拍子位置, 主要用于循环转储(如果不支持则是 -1)
    property KeyNum: integer;			链接的 MIDI 音符编号(如果不支持则是 -1)
  end;
  

  // 采样
  TSample = class
    constructor Create;													构造函数调用类似这样: Sample := TSample.Create;
    function GetSampleAt(Position, Channel: integer): single;								检索单个采样的值(位置以采样为单位)
    procedure SetSampleAt(Position, Channel: integer; Value: single);							设置单个采样的值(位置以采样为单位)
    procedure CenterFromTo(x1, x2: integer);										居中采样位置 x1 和 x2 (包含)之间的波形
    function NormalizeFromTo(x1, x2: integer; Vol: single; OnlyIfAbove: boolean = FALSE): single;			规格化采样位置 x1 和 x2 (包含)之间的波形
    procedure AmpFromTo(x1, x2: integer; Vol: single);									放大采样位置 x1 和 x2 (包含)之间的波形
    procedure ReverseFromTo(x1, x2: integer);										反转采样位置 x1 和 x2 (包含)之间的波形
    procedure ReversePolarityFromTo(x1, x2: integer);									反转采样位置 x1 和 x2 (包含)之间波形的极性
    procedure SwapChannelsFromTo(x1, x2: integer);									交换采样位置 x1 和 x2 (包含)之间通道的值, 用于立体声波形
    procedure InsertSilence(x1, x2: integer);										在采样位置 x1 和 x2 (包含)之间插入一个零值采样(静音)区块。这并不改变已存在的采样, 仅在位置 x1 处插入一个新的采样
    procedure SilenceFromTo(x1, x2: integer);										更改位置 x1 和 x2 (包含) 之间的采样值为零
    procedure NoiseFromTo(x1, x2: integer; Mode: integer = 1; Vol: single = 1);						更改位置 x1 和 x2 (包含)之间的值为随机值。模式是 0 (均匀噪声) 或 1 (高斯噪声)
    procedure SineFromTo(x1, x2: integer; Freq, Phase: double; Vol: single = 1);					更改位置 x1 和 x2 (包含)之间的采样为一个正弦波形
    procedure PasteFromTo(aSample: TSample; var x1, x2: integer; Mode: integer = 0);					在点 x1 处插入其它波形文件。采样是否会加长, 取决于模式的值。x1 和 x2 将包含其它波形替换的真实采样位置。模式可以是 0 (插入), 1 (替换) 或 2 (混频)
    procedure LoadFromClipboard;											从剪贴板加载一个波形到此采样对象
    procedure DeleteFromTo(x1, x2: integer; Copy: boolean = FALSE);							删除 x1 到 x2 (包含) 之间的采样
    procedure TrimFromTo(x1, x2: integer);										剪裁 0 到 x1 (包含) 和 x2 到结尾的采样
    function MsToSamples(Time: double): double;										把一个位置值从毫秒转换为采样
    function SamplesToMS(Time: double): double;										把一个位置值从采样转换为毫秒采样
    procedure LoadFromFile(const Filename: string);     								加载一个文件名称。这需要一个完整的文件路径名称。如果需要则使用 ScriptPath 来获得
    procedure LoadFromFile_Ask;                         								显示一个打开对话框, 如果点击确定将加载文件采样
    procedure NormalizeFormat(Source: TSample; Mode: integer = nfAll);							更改此采样的格式以便兼容来源采样的格式。请参阅上面的模式常量
    function GetRegion(Index: integer): TRegion;									检索一个对象的区域索引(在 0 和 RegionCount-1 之间)
    function AddRegion(const SetName: string; SampleStart: integer; SampleEnd: integer = MaxInt): integer;		添加一个新的区域。返回新区域的索引(其它区域可能会移动到其它索引)
    procedure DeleteRegion(Index: integer);										删除索引处一个存在的区域

    property Length: integer;												波形的长度, 单位是采样
    property NumChans: integer;												通道计数
    property Samplerate: integer;											采样速率, 单位是赫兹
    property RegionCount: integer;											区域总数。可以是零或更多
  end;

  // 编辑器
  TEditor = class
    function GetSelectionS(var x1, x2: integer): boolean;		检索在编辑器中选区的开始位置(x1)和结尾位置(x2), 单位是采样
    function GetSelectionMS(var x1, x2: double): boolean;		检索在编辑器中选区的开始位置(x1)和结尾位置(x2), 单位是毫秒
    property Sample: TSample;						编辑器当前加载的采样
  end;



5. 对话框类和函数
-------------------------------
  TInput = class
    property DefaultValue: single;		控件的默认值
    property Value: single;			控件的当前值
    property ValueAsInt: integer;		控件的当前值, 四舍五入到一个整数值
    property Min: single;			控件的最小值
    property Max: single;			控件的最大值
  end;

  TScriptDialog = class
    constructor Create;										构造函数调用类似这样: MyDialog := TScriptDialog.Create;
    function AddInput(const aName: string; Value: single): TInput;				添加一个普通输入控件
    function AddInputKnob(const aName: string; Value, Min, Max: single): TInput;		添加一个旋钮输入控件
    function AddInputCombo(const aName, ValueList: string; Value: integer): TInput;		添加一个组合框输入控件
    function GetInput(const aName: string): TInput;						用指定名称检索输入
    function GetInputValue(const aName: string): single;    					用指定名称检索输入的当前值
    function GetInputValueAsInt(const aName: string): integer;					用指定名称检索输入的当前值, 四舍五入到一个整数值
    function Execute: boolean;									显示对话框。如果用户点击确定则返回 TRUE, 如果对话框被取消则返回 FALSE
  end;

function CreateScriptDialog(const Title, Description: string): TScriptDialog;			创建一个新的脚本对话框。建议使用这个功能来代替直接调用 TScriptDialog 构造函数