テキストエディタのコマンドは、基本的に、環境設定で機能割り当てできるように なっていますが、このうちのほとんどのコマンドは、本関数で実行することができます。

引数の id には、コマンドの識別値を指定します。 大抵のコマンドは、この id の指定だけで済みます。 この値は、インクルードファイル EditCmds.h を 見れば分かりますが、このファイル内には、もう少し便利なマクロが定義されています。 例えば、選択範囲の半角空白をタブに変換するのに、
　　::Apsaly.ExecCmd( 248 );
と書く代わりに、マクロを使って、
　　#SpaceToTab;
と書くことができます。なお、このマクロを使う時は、 それより前に（通常はプログラムの最初に）、
　　#include <EditCmds.h>
を書いておく必要があります。

引数の name には、登録名を指定します。この指定が必要なのは、ユーザーが登録した 拡張コマンドを実行する場合だけです。例えば、
　　::Apsaly.ExecCmd( 10, "ユーザーメニュー(1)" );
のようになります。これは、マクロを使えば、
　　#ExtUserMenu( "ユーザーメニュー(1)" );
と書くことができます。

引数の file には、ファイル名を指定します。この指定が必要なのは、慣用語句入力を 実行する場合だけです。この場合、name には、項目名を指定します。例えば、
　　::Apsaly.ExecCmd( 13, "標題部挿入( *.h 用 )", "C.ptx" ); のようになります。これは、マクロを使えば、
　　#ExtInputPhrase( "標題部挿入( *.h 用 )", "C.ptx" );
と書くことができます。

本関数の返値は、正常終了時、null 以外に、不正終了時、null になります。

本エディタを起動する時のコマンド引数については、 「起動コマンド引数」で説明していますが、 本 OpenFile 関数では、これらの引数の指定で、編集ファイルを開くことができます。
本関数の引数 cmds には、起動コマンド引数の文字列を指定します。 もし、この中に、ファイルの規定がない場合、「無題」ファイルが開かれます。
本関数の返値は、本関数が開いた編集ファイルの数になります。
本関数で編集ファイルを開くと、アクティブウィンドウが変わりますが、 現スクリプトの操作対象の編集ウィンドウは変わりません。

(1)「無題」ファイルを開く場合：
　　::Apsaly.OpenFile( "" );

(2) 特定のファイルを開いて、そのテキストの末尾にカーソルを移動する場合：
　　::Apsaly.OpenFile( "/je file.txt" );
　なお、この場合、ファイル名の指定が相対パスなので、カレントパスに注意する 必要があります。

    ::Apsaly.OpenFile( 
        ##/e"C++" /zS /n1820 /i0 /o25 /k180 ##
        ##/+l+w-f+N+D+T+F+S3 /X21 /Y25 /W780 /H680 ##
        ##D:\Documents\Temp\Text1.txt## );

なお、##〜## の文字列表記に関しては、MikoScript の言語仕様を参照方。

各編集ウィンドウは、それぞれ固有の識別値を持っています。 この識別値は、その編集ウィンドウが開かれる時に割り当てられ、 その編集ウィンドウが閉じるまで、その値は変わりません。 本エディタが存続中、１度割り当てられた識別値と同じ値が、 他の編集ウィンドウに再度割り当てられることはありません。 この識別値は、本エディタが存続中に開いた全ての編集ウィンドウにおいて、 それぞれ固有の値になります。なお、この識別値が、0 になることはありません。

各編集ウィンドウは、開かれた順番も管理されています。 例えば、編集ウィンドウＡが開かれて、その次に編集ウィンドウＢが開かれた場合、 順方向の順番は、編集ウィンドウＡ → 編集ウィンドウＢになり、 逆方向の順番は、編集ウィンドウＢ → 編集ウィンドウＡになります。

本関数は、引数で指定された順番または回数と起点に対応する編集ウィンドウの識別値を返します。 それに対応するウィンドウがなければ、0 を返します。

引数 s は、次の値で起点となる編集ウィンドウを指定します。

　　=0:　現操作対象の編集ウィンドウ
　　=1:　現アクティブウィンドウ
　　=2:　最も新しい編集ウィンドウ
　　=3:　最も古い編集ウィンドウ
この引数が省略された時は、s = 0 として扱われます。

引数 t が無効の場合：

　　n > 0 の時、起点から順方向に +n 番目
　　n < 0 の時、起点から逆方向に -n 番目
　　n = 0 の時、起点自身
この引数が省略された時は、n = 0 として扱われます。

引数 t が有効の場合：

　　n > 0 の時、起点から順方向に +n 回目
　　n < 0 の時、起点から逆方向に -n 回目
　　n = 0 の時、起点自身
この引数が省略された時は、n = 1 として扱われます。

　type = 0:　フルパス名
　　　 = 1:　フォルダのフルパス名（末尾の \ なし）
　　　 = 2:　ファイル名のみ（拡張子あり）or テキスト題名
　　　 = 3:　ファイル名のみ（拡張子なし）or テキスト題名
　　　 = 4:　拡張子（ピリオッドは含まない）
　type 省略の場合、=0 に解釈

  for( i = 0 ;; i++ )
  {
      if(( id = ::Apsaly.GetWindowId( i, 3 )) == 0 )
          break;
      print ::Apsaly.GetFileName( id );
  }

  #include <EditCmds.h>
  #FileNew;
  ::Apsaly.TargetWindow( ::Apsaly.GetWindowId( 0, 2 ) );
  ::Apsaly.Insert( "Hello!\r\n" );

次のスクリプトは、現在開いている編集ウィンドウのうちのどれかに、 Hello.mc という名前の編集ファイルがあれば、 その編集ウィンドウをアクティブウィンドウに設定します。

  for( i = 0 ;; i++ )
  {
      if(( id = ::Apsaly.GetWindowId( i )) == 0 )
          break;
      if( ::Apsaly.GetFileName( id )
                 'wcmp( $"*\Hello.mc" ) == 0 )
      {
          ::Apsaly.ActiveWindow( id );
          break;
      }
  }

　　"clip"    :　クリップボード
　　"find"    :　検索文字列
　　"repl"    :　置換文字列
　　"file"    :　最近使ったファイル
　　"path"    :　最近使ったフォルダ
　　"session" :　最近使ったセッション
　　"project" :　最近使ったプロジェクト
　　"program" :　外部プログラムの実行コマンド
　　"script"  :　スクリプトの実行コマンド
　　"g-file"  :　Grepファイル
　　"g-path"  :　Grepフォルダ
　　"ime"     :　ＩＭＥ変換結果
　　"yomi"    :　ＩＭＥ変換よみ（変換前のカナ文字列）

本関数の返値は、引数 h の履歴が有効な場合、次のようになります。
　引数 i が数値で、その値がインデックスとして、
　　　有効なら、その要素の文字列
　　　無効なら、空の文字列
　引数 i が省略／不正なら、その履歴の要素数

本関数は、引数 h が省略／不正の時、null を返えします。

  N = ::Apsaly.GetHist( "clip" );
  for( i = 0 ; i < N ; i++ )
      print ::Apsaly.GetHist( "clip", i );

クリップボード履歴には、現状、本エディタがクリップボードに格納した 文字列（の先頭から最大で 1024 バイトまで）だけが記録されています。 そのサイズを超える部分や、他のプログラムが格納した文字列は、 記録されていません。

ＩＭＥ変換よみの字種は、ＩＭＥよっては、半角カタカナの場合もあります。 これを全角ひらかなにするには、例えば、次のようにします。
　　::Apsaly.GetHist("yomi",0)'toZenk'toHira

引数 string は、検索文字列を指定します。 これには、正規表現も使用できます。
引数 mode は、検索モードの文字列を指定します。この文字列は、
　　RWIZKDSGE@nX （但し n は数字 ）
の文字を使って表わしますが、 この表記は、入力リストファイルフォーマットの 〈モード〉の部分と同じです。具体的には、検索モードのところで説明しています。 mode の指定がない場合、検索モードは、更新されずに、現設定のままになります。 全モードを OFF にするには、空文字列を指定します。

本関数は、検索条件を設定するだけで、検索は行ないません。 この条件で、実際に検索を行なうには、FindFwd() か FindBwd() 関数を実行する必要があります。 本関数が設定した検索条件は、「検索ダイアログボックス」等に 反映されます。また、履歴にも登録されます。そのため、検索文字列は、検索ダイアログボックス での設定と同様に、1 字以上 400 字以下（半角単位）の制限があります。

本関数は、正常終了の時、0 を返します。
mode で正規表現が指定されている場合（ つまり、mode 内に R の文字を含む場合 ）、 string の文字列は、正規表現として解釈されますが、それに文法エラーがあると、 本関数は、その内容を示す正の整数値を返します。 この値は、次のようなビット構成で、各文法エラーの有無を示します。
　　Bit-0 　丸括弧の対応がとれていない
　　Bit-1 　モード指定の # に続く文字が不正
　　Bit-2 　参照指定の @ に続く文字が不正
　　Bit-3 　反復回数指定 {...} の記述が不正
　　Bit-4 　反復対象が不正
　　Bit-5 　文字集合 [...] の記述が不正
　　Bit-6 　先読み位置規定の #^ に続く文字が不正
　　Bit-7 　グループ照合の @[n] の記述が不正
　　Bit-8 　通過カウント演算の記述が不正
　　Bit-9 　特別パターン規定の記述が不正
　　Bit-10　文字コード指定 \Xnnnn, \Jnnnn の値が不正
　　その他のビットは、全て 0 です。
正規表現に文法エラーがあっても、適当に解釈されて、検索条件は設定（更新）されます。

本エディタでは、検索は補助スレッドが行ないます。そのため、 このスレッドが他の作業中の時に、本関数を実行しても、検索条件は正常に設定されません。 そのような場合、本関数は、適当な負の値（ 現状、-99 ）を返します。

・"ABC" という文字列を検索して選択する条件を設定：
　　::Apsaly.SetFindCond( "ABC", "G" );

・"ABC" という文字列を含む行を検索する条件を設定：
　　::Apsaly.SetFindCond( $"^.*ABC.*$", "R" );

・"イロハ" という文字列を、全角／半角、ひらかな／カタカナの区別なしに検索して 選択する条件を設定：
　　::Apsaly.SetFindCond( "イロハ", "ZKG" );

引数 string は、置換文字列を指定します。 これには、各種のメタ文字も使用できます。
引数 mode は、置換モードの文字列を指定します。この文字列は、
　　CAM
の文字を使って表わしますが、 この表記は、入力リストファイルフォーマットの 〈モード〉の部分と同じです。具体的には、置換モードのところで説明しています。 mode の指定がない場合、置換モードは、更新されずに、現設定のままになります。 全モードを OFF にするには、空文字列を指定します。

本関数は、置換条件を設定するだけで、置換は行ないません。 この条件で、実際に置換を行なうには、FindFwd() か FindBwd() 関数を実行する必要があります。その際、当関数の 第３引数を 1 に指定して、置換のための検索を行なわせる必要があります。

本関数が設定した置換条件は、「置換ダイアログボックス」等に 反映されます。また、履歴にも登録されます。そのため、置換文字列は、置換ダイアログボックス での設定と同様に、0 字以上 240 字以下（半角単位）の制限があります。

本関数は、正常終了の時、0 を返します。

本エディタでは、置換のための検索は補助スレッドが行ないます。そのため、 このスレッドが他の作業中の時に、本関数を実行しても、置換条件は正常に設定されません。 そのような場合、本関数は、適当な負の値（ 現状、-99 ）を返します。

・"XYZ" という文字列に置換する条件を設定：
　　::Apsaly.SetReplCond( "XYZ", "" );

・"ABC" という文字列を検索して、"XYZ" という文字列に置換（置換の際には確認ボックスを表示）
　　::Apsaly.SetFindCond( "ABC", "G" );
　　::Apsaly.SetReplCond( "XYZ", "C" );
　　::Apsaly.FindFwd( , , 1 );

・上のプログラムで置換条件を次のように変えると、全置換になる：
　　::Apsaly.SetReplCond( "XYZ", "A" );

　　Bit-7〜0:    赤レベル（ 256 段階 ）
　　Bit-15〜8:   緑レベル（ 256 段階 ）
　　Bit-23〜16:  青レベル（ 256 段階 ）

　　Bit-0:　文字を着色するか否か
　　Bit-1:　背景を着色するか否か
　　Bit-2:　太字にするか否か
　　Bit-3:　下線を付けるか否か

・8 番目の着色形態を、文字色：赤、背景色：明紫、太字：なし、下線：なし に設定：
　　::Apsaly.SetTintSpec( 8, 0x0000FF, 0xFFD8FF, 0b0011 );

・10 番目の着色形態を、文字色：青、背景色：なし、太字：あり、下線：なし に設定：
　　::Apsaly.SetTintSpec( 10, 0xFF0000, , 0b0101 );

  ( fc, bc, style ) = ::Apsaly.GetTintSpec( 5 );
  print fc'x(6), bc'x(6), style'b(4);

編集ウィンドウで挿入される文字の着色形態は、デフォールトの汎用着色番号で 規定されます。つまり、この着色番号を設定すると、それ以降に挿入される文字はすべて、 その着色形態になります。この着色番号は、各編集ウィンドウごとに個別に 設定できます。

引数 i には、着色番号を指定します。この値が 1 〜 31 の時、 今後挿入される文字は、その番号に対応する着色形態になります。
この値が 0 の時は、今後の挿入文字は、無着色になります。
この値が上記以外、または、省略なら、挿入文字の着色は、現状のまま変わりません。

引数 w には、本設定／取得の対象となる編集ウィンドウの識別番号を指定します。 （この識別番号に関しては、GetWindowId() 関数参照 ） この引数が省略／不正の時は、現操作中の編集ウィンドウが対象になります。

本関数の返値は、本処理の最終時点でのデフォールトの汎用着色番号になります。 但し、対象の編集ウィンドウない等の異常時には、-1 になります。

  ::Apsaly.DefTintId( 5 );

  ::Apsaly.DefTintId( 0 );

  ::Apsaly.DefTintId( 4, 1 );

レポートウィンドウは、スクリプトから各種の処理結果を出力するための編集ウィンドウで、 -Report- というタイトルになっています。 このウィンドウは、スクリプトコンソールウィンドウ（ -Script- というタイトルのウィンドウ）と 若干似ていますが、スクリプトからは、通常の編集ウィンドウと同様の扱いができます。

引数 text には、挿入するテキストを指定します。
引数 tint には、挿入するテキストの着色番号を指定します。
引数 tint の値が 1 〜 31 の時、それに対応する着色形態で、 引数 text の文字列が挿入されます。
引数 tint の値が 0 の時、無着色で、引数 text の文字列が挿入されます。
引数 tint の値がそれ以外の時、または、省略された時、 デフォールトの汎用着色番号（ DefTintId() 関数参照 ） に対応する着色形態で、挿入されます。

本関数は、指定されたテキストを正常に挿入した時に、正の整数値を返します。 また、挿入テキストが無いか、無指定の時に、0 を返します。 もしエラーになれば、負の整数値を返します。

  ::Apsaly.Report( "Hello, world.\r\n", 5 );

引数 page には、ヘルプのページを規定する文字列を指定します。 これは、そのページが格納されているファイル名になります。 例えば、「プロジェクト管理」は、"Project.html" という名前のファイルに 格納されています。

ページ内の特定場所を表示するには、ファイル名の直後に「#名前」を付けます。 この名前は、<A NAME="..."> で設定されている ... の部分の文字列になります。 例えば、スクリプトの「カーソル移動」関数のところは、 "ScriptMxObjFncG1.html#MoveTo" と指定します。

各ページが格納されているファイル名や、ページ内の特定場所を示す名前については、 ここでは明記しませんが、Apsaly のホームページで、対象となるところのハイパーリンクを見ると分かります。

引数 page を省略すると、先頭ページが表示されます。

返値は、ヘルプが正常に表示された時、真値(1)に、さもなければ、偽値(0) になります。

  ::Apsaly.Help( "Project.html#TreeHandling" );

引数 text に文字列が指定された場合、それに対応する読み上げを開始します。

引数 text に次の数値が指定された場合、それに対応する制御を行ないます。

　=0:　読み上げを中断（順番待ちのものも全て）
　=1:　読み上げを一時停止
　=2:　読み上げを再開（一時停止解除）

引数 flags は、下記のビットが 1 の時に、それに対応する意味を持ちます。 下記以外のビットには特別な意味はありません。

引数 flags が省略／不正時、flags = 0 と同等です。その場合、 XML タグは、text の最初の文字が、< の時のみ、有効（一時的）です。 なお、XML タグについては、下記の補説で説明します。

本関数の返値は、次のようになります。

正常終了時：
　> 0:　発声ストリーム識別番号（下記参照）
　= 0:　音声出力なし（読み上げの中断等の場合）
エラー時：
　= -1:　音声合成エンジンが未搭載 or 準備エラー
　= -2:　特典ライセンスなし（注意欄参照）
　= -3:　読み上げ実行エラー
　= -4:　待ち行列が満杯
　= -5:　読み上げテキスト処理エラー
　= -6:　引数不正

　本関数で、読み上げを開始した時、本関数は、その読み上げが完了するのを待たずに、 即時に戻って来ます。その際、前回の読み上げが終っていなければ、今回の読み上げは、 待ち行列に入れられます。本関数の返値が「発声ストリーム識別番号（上記参照）」の場合、 その値は、その時点での待ち行列の順位になります。

　本関数で開始した読み上げが、完了するのを待つには、TraceSpeaking() 関数を使います。また、この関数で、 現在の読み上げが、対象の文字列内のどの位置まで進んでいるのかを知ることができます。

　読み上げの「中断」は、即時に行なわれますが、「一時停止」は、 適当な区切り（通常、単語の境目）で行なわれます。

　読み上げの「一時停止」に関しては、次の点に留意する必要があります。 「一時停止」中に、新たに読み上げを開始しても、それは待ち行列に入ります。 「一時停止」中に「一時停止」を行なった場合、 それと同じ回数分の「再開」を行なって初めて、一時停止状態が解除されます。 「一時停止」状態は、現スクリプトの終了後も継続します。 「一時停止」状態は、読み上げの「中断」で解消されます。

　読み上げ対象の文字列内に、XML タグを介入させることによって、 読み上げの 速度, 音量, 音高 などだけではなく、さまざまな指定が できるようになっています。⇒ 参照

　XML タグの効果は、「一時的」と「恒久的」の場合があります。 これは、引数 flags で指定できます。 一時的の場合、本関数の実行に対してのみ有効です。 恒久的の場合、本エディタを終了するまで、その効果が継続します。

　引数 text をファイル名として、そのファイルの内容を読み上げる 場合（ 引数 flags の bit-2 が 1 の時 ）、そのテキストの文字コード符号化方式は、 基本的には、使用する音声合成エンジンに依存します。 標準的には、BOM 付きの UTF-16(LE) や UTF-8 なら支障なさそうです。

次のスクリプトを実行すると、「ハローワールド」と発声します。

  ::Apsaly.Speak( "Hello world" );

次のスクリプトは、読み上げを中断します。

  ::Apsaly.Speak( 0 );

次のスクリプトは、通常の半分の音量で読み上げます。

  ::Apsaly.Speak( $'<volume level="50">'
        "This volume level is 50%." );

　本関数で読み上げを行なうには、SAPI 5 対応の音声合成エンジンが インストールされている必要があります。 ちなみに、Windows XP, Vista では、英語の音声合成エンジンが標準で 搭載されています。日本語を読み上げるには、日本語の音声合成エンジンが 別途必要です。

　本関数は、ご寄付を頂いた方への「特典」になっています。特典がないと、本エディタの起動後、 本関数を使うスクリプトの起動回数が３回を超えると、 本関数は、無効になります。

引数 s には、読み上げ状況を取得する対象の「発声ストリーム 識別番号」（ Speak() 関数の返値参照 ）を指定します。 この引数が、省略／不正の時は、現発声ストリームを対象とします。

本関数の返値は、次のようになります。

　>= 0:　現在読み上げ中のテキスト内の位置
　= -1:　未だ発声待ち状態
　= -2:　対象の発声ストリーム無し or 既に発声終了

　ここで、テキスト内の位置というのは、読み上げ中のテキストの先頭からの 文字数になります。これは、バイト数でも、文字コードインデックス値でもありません。

次のスクリプトは、読み上げを開始してから、その読み上げが終了するまで待ちます。

  ::Apsaly.Speak( "Hello, I'm glad to speak." );
  while( ::Apsaly.TraceSpeaking() != -2 )
      'sleep(10);

なお、このように、本関数で読み上げ状況をポーリングする場合、 無駄なＣＰＵ時間を浪費しないように、必ず 'sleep を行なう必要があります。

次のスクリプトは、現カーソル行の先頭から行末までを、読み上げます。 その際、現読み上げ位置に、カーソルが逐次移動します。

  text = ::Apsaly.GetLineText();
  if( ! text )
      return;
  if( ::Apsaly.Speak( text ) <= 0 )
      return;
  cur_li = 'LLi;  // 発声対象の論理行インデックス
  pre_ki = -1;    // 前回の読み上げ位置
  for( ;; 'sleep(10) )
  {
      switch( cur_ki = ::Apsaly.TraceSpeaking() )
      {
        case -1:  continue;   // 発声開始待ち
        case -2:  quit;       // 発声終了
        default:  break;      // 発声中
      }
      if( cur_ki > pre_ki )
      {
          ::Apsaly.MoveTo( cur_li'LLi, cur_ki'LKn );
          pre_ki = cur_ki;
      }
  }
  ::Apsaly.MoveTo( 'LineEnd );

引数 s には、次のどれかの数値を指定します。

　s = 0:  聞き取り終了
　s = 1:  聞き取り開始（Ａ）
　s = 2:  聞き取り開始（Ｂ）

聞き取り開始（Ａ）と（Ｂ）は、どちらも、音声認識エンジンを起動します。 その時、聞き取りの状況を示すダイアログボックスが表示されます。 音声認識エンジンは、入力音声に対する聞き取りが確定すると、 その認識結果を、本エディタに通知します。

聞き取り開始（Ａ）の場合、その認識結果は、現スクリプトにイベントとして 送られます。これをスクリプトで取得するには、 GetEvent() 関数を使います。

聞き取り開始（Ｂ）の場合、その認識結果は、現編集テキストのカーソル位置に 挿入されます。なお、挿入位置直前と、認識結果の文字列の先頭で、 英数字が連続する場合には見にくくなるので、その間に空白が自動的に挿入されます。

聞き取りの終了は、本関数で行なうか、または、上記ダイアログボックス内の 「終了」ボタンを押します。

引数 s が、省略／上記以外／不正の時は、何も行なわずに、 現在の聞き取り状態を返します。

本関数の返値は、次のようになります。

　=  0:  聞き取りは、行なわれていない
　=  1:  聞き取り実行中（Ａ）
　=  2:  聞き取り実行中（Ｂ）
　= -1:  聞き取り実行不能（音声認識エンジン未搭載等）
　= -2:  特典ライセンスなし（注意欄参照）

聞き取り実行中（Ａ）と（Ｂ）は、それぞれ、上記の聞き取り開始（Ａ）と（Ｂ）に 対応します。

次のスクリプトを実行すると、聞き取りが開始されて、その認識が確定するごとに、 その結果の文字列が、現カーソル位置に挿入されます。

  ::Apsaly.Dictate(2);

次のスクリプトは、聞き取りを開始して、その認識が確定するごとに、 その結果の文字列を、コンソールウィンドウにプリントします。

  #include <Event.h>
  if( ::Apsaly.Dictate(1) < 0 )
      return;
  for( ;; )
  {
      ( ev, tv ) = ::Apsaly.GetEvent();
      if( ev'type == "string"  &&  tv != null )
          print ev;
      else
      if( #IsSpRecoEndEvent( ev ) )
          break;  // 聞き取りダイアログでの終了時
  }

　本関数で聞き取りを行なうには、SAPI 5 対応の音声認識エンジンが インストールされている必要があります。ちなみに、このエンジンは、 英語だけでなく日本語でも、フリーで使えるものがあります。

　本関数は、ご寄付を頂いた方への「特典」になっています。特典がないと、本エディタの起動後、 本関数を使うスクリプトの起動回数が３回を超えると、 本関数は、無効になります。