Apsaly オブジェクトのメンバー関数 (3)

　Apsalyオブジェクトのメンバー関数は、次のように、３グループに分類されています。

（１）現編集ウィンドウを対象とする関数

（２）全編集ウィンドウ共通の関数

（３）プロジェクト関連の関数

　ここでは、このうち（３）のグループの関数について、詳しく説明します。これらの関数は、基本的に、プロジェクト管理ウィンドウ内にツリービューとして表示されているプロジェクトに対する操作を行ないます。

■予備知識

●プロジェクト関数の呼び出し方（簡略記法）

　プロジェクト関数は、Apsaly オブジェクト内の Project という「箱」の中に、まとめられています。そのため、その関数をコールするには、

    ::Apsaly.Project.関数名( 引数列 )

という書式になります。この書式を、スクリプト内で何箇所も使う必要がある時は煩わしいので、いろいろな簡略記法が使えるようになっています（⇒参考）。ここでは、もう１つ別の方法を説明します。まず、次のように、::Apsaly.Project への参照を適当な変数に代入しておきます。

    Proj := ::Apsaly.Project;

なお、これはあくまで、参照の代入であって、::Apsaly.Project の複製の代入ではありません。さて、こうしておけば、それ以降、プロジェクト関連の関数は、次の書式でコールできます。

    Proj::関数名( 引数列 )

ちなみに、この書き方は、以降の幾つかの用例で、使われています。

●プロジェクトツリー内のノードの識別値

　プロジェクトツリー内の各ノードには、それぞれ、固有の識別値が割り当てられています。この値は、ハンドル値とも呼ばれていますが、これで、特定のノードを指定します。

　この識別値は、全てのプロジェクト関数の引数になっています。この引数が、省略されたり、0 が指定された場合、プロジェクトツリー内で現在選択されているノードが対象になります。

　この識別値は、幾つかのプロジェクト関数の返値になっています。この返値が、0 の場合、エラーまたは対象ノードが無いことを示します。一方、対象ノードがあれば、この返値は、非 0 の値になります。

■メンバー関数一覧（３）

関数名	概要説明
Project.GetNodeHv	指定位置のノードの識別値を取得
Project.GetNodeAttr	ノードの属性を取得
Project.SetNodeAttr	ノードの属性を設定
Project.GetNodeType	ノードの種類を取得
Project.GetNodeDepth	ノードの深さを取得
Project.SelectNode	ノードを選択
Project.InsertNode	ノードを追加
Project.DeleteNode	ノードを削除
Project.SortNodes	ノード内を並べ替え
Project.GetXmlText	サブツリーのＸＭＬ表現を取得
Project.PutXmlText	ＸＭＬ表現のサブツリーを追加
Project.GetNodeText	ノードのテキスト情報を取得
Project.SetNodeText	ノードにテキストを設定
Project.ExecNode	ノードを実行
Project.EditNode	ノードを編集
Project.FilePath	プロジェクト格納ファイルの設定／取得

■メンバー関数詳説（３）

Project.GetNodeHv( hv, ps )

機能：

ノード hv を基準にして指定位置 ps にあるノードの識別値を取得します。

説明：

引数 hv には、基準となるノードの識別値を指定します（⇒参照）。
引数 ps には、その基準ノードに対する対象ノードの位置を示す、以下の数値または文字列を指定します。

引数値	対象ノードの位置
0 or "root"	ルートノード（プロジェクトノード）
1 or "up"	上位ノード
2 or "down"	下位の先頭ノード
3 or "next"	同位の次ノード
4 or "prev"	同位の前ノード
5 or "first"	同位の先頭ノード
6 or "last"	同位の最後ノード
7 or "fore"	展開表示上の次ノード
8 or "back"	展開表示上の前ノード
（省略）	現選択ノード（ hv も省略のこと）

本関数の返値は、対象ノードの識別値です。もし、対象ノードが無ければ、0 を返します。

用例：

次のスクリプトは、現プロジェクトのルートノードから下へ１つずつ順に走査して、各ノードの名前をプリントします。

  Proj := ::Apsaly.Project;
  for( hv = Proj::GetNodeHv( 0, "root" ) ;
       hv != 0 ;
       hv = Proj::GetNodeHv( hv, "fore" ) )
  {
      print "  "'rep( Proj::GetNodeDepth( hv ) )  // 字下げ
            + Proj::GetNodeAttr( hv, "title" );
  }

この例は、サンプルスクリプトフォルダ内の ProjTreeDump.mc にあります。

Project.GetNodeAttr( hv, attr )

機能：

ノード hv の属性 attr の値（文字列）を取得します。

説明：

引数 hv には、対象となるノードの識別値を指定します（⇒参照）。
引数 attr には、属性名を指定します。この属性名が、以下の文字列の場合、特別な意味（用途）があります。なお、それ以外は任意に使用できます。

属性名	属性の意味（用途）
"title"	ノードの名前
"icon"	ノードのアイコン番号（「補説」参照）
"path"	参照先のファイルパス（相対パス or 絶対パス）
"args"	参照先のファイルの実行時の引数
"expand"	ノードが展開されているか否か（「補説」参照）
"info"	ステータスバーに表示する文字列
"tip"	ツールチップに表示する文字列

本関数の返値は、その属性の文字列です。その属性が無い時は、null を返します。

用例：

次のスクリプトは、現プロジェクトのルートノードから下へ順に１つずつ各ノードを走査して、参照先のファイルがあれば、そのパスをプリントします。

  Proj := ::Apsaly.Project;
  for( hv = Proj::GetNodeHv( 0, "root" ) ;
       hv != 0 ;
       hv = Proj::GetNodeHv( hv, "fore" ) )
  {
      path = Proj::GetNodeAttr( hv, "path" );
      if( path )
          print path;
  }

補説：

"icon" 属性は、ノードのアイコンがデフォールトでない時、アイコン画像のインデックス値で、設定されています。ノードのアイコンがデフォールトの時（つまり、デフォールトのアイコンが表示されている時）は、設定されていません。

"expand" 属性が "yes" の時、対象ノードは展開されています（つまり、その直下のノード群を見せる状態になっています）。一方、 "expand" 属性が無いか "no" の時、対象ノードは折り畳まれています（つまり、その直下のノード群を隠す状態になっています）。

Project.SetNodeAttr( hv, attr, value )

機能：	ノード hv の属性 attr に属性値 value を設定します。
説明：	引数 hv には、対象となるノードの識別値を指定します（⇒参照）。引数 attr には、属性名を指定します。この属性名の特別な意味（用途）に関しては、.GetNodeAttr() の場合と同様です。引数 value には、その属性の値となる文字列を指定します（数値は不可）。引数 value を省略、または、null を指定すると、その属性は、削除されます。本関数は、その処理が成功なら #TRUE を返し、失敗なら #FALSE を返します。
用例：	(1) 現選択ノードに、現編集ファイルのフルパスを設定します。 ::Apsaly.Project.SetNodeAttr( 0, "path", ::Apsaly.GetFileName() ); (2) 現選択ノードのアイコンを２番目のアイコンに変更します。 ::Apsaly.Project.SetNodeAttr( , "icon", "2" ); (3) 現選択ノードの情報としてステータスバーに「Hello」と表示します。 ::Apsaly.Project.SetNodeAttr( , "info", "Hello" );
補説：	"expand" 属性に "yes" に設定すると、その対象ノードが展開されます（つまり、その直下のノード群を見せる状態になります）。また、"expand" 属性に "no" を設定すると、その対象ノードが折り畳まれます（つまり、その直下のノード群を隠す状態になります）。なお、"expand" 属性を削除しても、その対象ノードの展開／折り畳み状態は、変わりません。
注意：	"icon" 属性には、アイコン画像のインデックスを指定しますが、現状、設定できるのは、2 以上の値（を示す文字列、つまり、"2", "3", "4", "5" ... ）に限定されます。 "icon" 属性は、プロジェクトノード（ルートノード）では、設定できません。 "title" 属性は、どのノードでも、変更できますが、削除はできません。

Project.GetNodeType( hv )

機能：

ノード hv の種類を取得します。

説明：

引数 hv には、対象ノードの識別値を指定します（⇒参照）。
本関数は、対象ノードの種類を示す次の数値を返します。

返値	ノードの種類
1	プロジェクトノード
2	分類ノード
3	テキストノード
4	ファイル参照ノード（⇒「補説」）
<=0	エラー（対象ノードなし等）

補説：

ファイル参照ノードの参照先には、ファイル、フォルダー、ＵＲＬがありますが、どの場合でも、ノードの種類としては、4 になります。

Project.GetNodeDepth( hv )

機能：	ノード hv の階層の深さを取得します。
説明：	引数 hv には、対象ノードの識別値を指定します（⇒参照）。本関数は、プロジェクトツリー内で、その対象のノードがある階層の深さを返します。この深さを示す値は、プロジェクトノード（ルートノード）が 1 で、以降 1 階層深くなるごとに 1 ずつ増えます。なお、エラー時（対象ノードない等の場合）は、本関数は、0 以下の値を返します。
用例：	.GetNodeHv() の用例参照。ここでは、各ノードの深さに応じて、各行頭の字下げが深くなるようになっています。

Project.SelectNode( hv )

機能：	ノード hv を選択状態にします。
説明：	引数 hv には、対象ノードの識別値を指定します（⇒参照）。プロジェクトのツリービュー内で選択されるのは、１つのノードだけです。複数のノードは選択できません。選択されたノードは、ハイライト表示されます。本関数は、その処理に成功すれば #TRUE を返し、失敗すれば #FALSE を返します。
用例：	次のスクリプトは、ノードの選択を、現ノードからそのルートノード（プロジェクトノード）へ移します。 ::Apsaly.Project.SelectNode( ::Apsaly.Project.GetNodeHv( ,"root" ));

Project.InsertNode( hv, at, type, name, path )

機能：

ノード hv を基準にして指定位置 at に新規ノードを追加（挿入）します。

説明：

引数 hv には、基準となるノードの識別値を指定します（⇒参照）。
引数 at には、その基準ノードに対する新規ノードの追加位置を、以下の数値または文字列で指定します。

引数 at の値	新規ノードの追加位置
0 or "first-in"	基準ノードの中の先頭へ
1 or "last-in"	基準ノードの中の最後へ
2 or "next"	基準ノードの次へ
3 or "prev"	基準ノードの前へ

引数 type には、追加する新規ノードの種類を、以下の数値または文字列で指定します。

引数 type の値	新規ノードの種類
0 or "project"	プロジェクトノード（ルートノード）
1 or "branch"	分類ノード
2 or "text"	テキストノード
3 or "file"	ファイル参照ノード

引数 name には、追加する新規ノードの名前（ノードのタイトル）の文字列を指定します。
引数 path には、追加する新規ノードの種類に応じて、以下の値を指定します。

新規ノードの種類	引数 path に指定する値
プロジェクトノード	プロジェクトファイル名（ ⇒補説）
分類ノード	（指定不要）
テキストノード	（指定不要）
ファイル参照ノード	参照先（ ⇒補説）

本関数は、その処理に成功すれば、追加した新規ノードの識別値を返します。失敗すれば、0 を返します。

補説：

引数 path に「プロジェクトファイル名」を指定する場合、それは、相対パスでも絶対パスでも構いません。相対パスの場合、カレントパスが基準になります。

引数 path に「参照先」を指定する場合、それは、ファイル、フォルダ、ＵＲＬのどれかになります。ファイルまたはフォルダの場合、相対パスでも絶対パスでも構いません。相対パスの場合、プロジェクトファイルの格納フォルダが基準になります。

用例：

(1) 次のスクリプトは、現選択ノードの次に「第１章」という分類ノードを追加します。

  ::Apsaly.Project.InsertNode( , "next", "branch", "第１章" );

(2) 次のスクリプトは、現選択ノード内の最後に、「文書(1)」､「文書(2)」､「文書(3)」という３つのテキストノードを追加します。

  Proj := ::Apsaly.Project;
  nd = Proj::GetNodeHv();
  for( i = 1 ; i <= 3 ; i++ )
      Proj::InsertNode( nd, "last-in", "text", "文書(%d)"'fmt(i) );

(3) 「階層付きテキスト」からプロジェクトを生成するスクリプトが、スクリプト標準フォルダ内の ProjFromText.mc にありますが、これも、InsertNode() 関数を使う好例です。

Project.DeleteNode( hv )

機能：	ノード hv を削除します。
説明：	引数 hv には、削除の対象となるノードの識別値を指定します（⇒参照）。本関数は、この対象ノード以下のサブツリーを削除します。この削除の際には、確認のメッセージボックスは表示されずに、即時に削除が行なわれます。本関数は、その処理に成功すれば #TRUE を返し、失敗すれば #FALSE を返します。
用例：	次のスクリプトは、現在選択されているノード以下のサブツリーを削除します。 ::Apsaly.Project.DeleteNode();

Project.SortNodes( hv, so )

機能：	ノード hv 直下の全ノードを名前の昇順または降順に並べ替えます。
説明：	引数 hv には、並べ替えの基準になるノードの識別値を指定します（⇒参照）。この基準ノードの直下にある全サブノードが、並べ替えの対象になります。（ちなみに、この各サブノードのサブノード内は、並べ替えの対象にはなりません。）この並べ替えは、各ノードの名前の昇順または降順になります。引数 so に、0 以上の数値を指定すると、昇順に、0 未満（負値）を指定すると、降順になります。なお、引数 so が省略／不正の時は、昇順として扱われます。本関数は、その処理に成功すれば #TRUE を返し、失敗すれば #FALSE を返します。
用例：	次のスクリプトは、現在選択されているノード直下にある全ノードを、そのノード名の昇順に、並べ替えます。 ::Apsaly.Project.SortNodes();

Project.GetXmlText( hv )

機能：	ノード hv 以下のサブツリーをＸＭＬ表記の文字列にして返します。
説明：	引数 hv には、対象となるノードの識別値を指定します（⇒参照）。本関数は、この対象ノード以下のサブツリーを、ＸＭＬ表記の文字列に変換して返します。なお、エラー時（対象ノードない等の場合）には、本関数は null を返します。
用例：	次のスクリプトは、現在選択されているノード以下のサブツリーをＸＭＬ表記でプリントします。 print ::Apsaly.Project.GetXmlText();
補説：	.GetXmlText() と .PutXmlText() を使えば、プロジェクトツリービュー内の任意のサブツリーを、任意の位置へコピーすることができます。また、.DeleteNode() も使えば、任意の位置へ移動させることもできます。

Project.PutXmlText( hv, at, text )

機能：

ＸＭＬ表記の文字列をサブツリーに変換して指定位置に追加（挿入）します。

説明：

引数 hv には、追加位置の基準になるノードの識別値を指定します（⇒参照）。
引数 at には、この基準ノードに対する追加位置を、次の数値または文字列で指定します。

引数 at の値	サブツリーの追加位置
0 or "first-in"	基準ノードの中の先頭へ
1 or "last-in"	基準ノードの中の最後へ
2 or "next"	基準ノードの次へ
3 or "prev"	基準ノードの前へ

引数 at が省略された時は、「基準ノードの次へ」追加されます。
引数 text には、今回追加するサブツリーを表わすＸＭＬ表記の文字列を指定します。この文字列は、.GetXmlText() で取得した文字列か、または、それに相当する文字列である必要があります。
引数 text が省略された時（または不正の時）、クリップボードの文字列が、そのＸＭＬ表記の文字列として参照されます。
本関数の返値は、今回追加されたサブツリーの代表ノード（最上位ノード）の識別値になります。なお、エラーの場合（ＸＭＬ表記の文字列が不正等の時）、本関数は、0 を返します。

用例：

(1) 次のスクリプトは、クリップボードに格納されている文字列を、サブツリーを表すＸＭＬ表記のテキストとして翻訳して、それを内部形式のサブツリーのデータに変換して、ツリービュー内で現在選択されているノードの次に挿入します。

  ::Apsaly.Project.PutXmlText();

(2) 次のスクリプトは、現選択ノードを、１つ上の階層へ移動します。つまり、現選択ノードを、その上位のノードの次の位置へ移動します。なお、その際、現選択ノード内にサブノードがあれば、そのサブツリーごと移動します。

  Proj := ::Apsaly.Project;

  // 現選択ノードの上位ノード（親ノード）を取得
  UpNode = Proj::GetNodeHv( , "up" );
  if( Proj::GetNodeDepth( UpNode ) <= 1 )
      return;   // 上位ノードが無い場合

  // 現選択ノードのサブツリーのＸＭＬ表記文字列を取得
  CurNode = Proj::GetNodeHv();
  SubTree = Proj::GetXmlText( CurNode );

  // 現サブツリーを上位ノードの次へ移動
  if( Proj::PutXmlText( UpNode, "next", SubTree ))
      Proj::DeleteNode( CurNode );

この例は、サンプルスクリプトフォルダ内の ProjNodeUp.mc にあります。

Project.GetNodeText( hv, sp )

機能：

ノード hv に設定されているテキストデータの情報を取得します。

説明：

引数 hv には、対象となるノードの識別値を指定します（⇒参照）。
引数 sp には、取得する情報（本関数の返値）の種類を、次の文字列で指定します。

引数値	取得情報（本関数の返値）
"text"	テキストの内容（テキストが無い時は null ）
"size"	テキストのサイズ（テキストが無い時は 0 ）
"window"	テキストの編集ウィンドウのＩＤ（ウィンドウが無い時は 0 ）

引数 sp が省略された時は、"text" の指定として解釈されます。

注意：

対象ノードのテキストが編集中の時（つまり、そのテキストの編集ウィンドウが表示されている時）に、本関数から取得されるテキストの内容は、現編集中のテキストの内容になります。なお、それが未保存の場合には、対象ノード内に保管されているテキストの内容と異なる場合があります。

用例：

(1) 次のスクリプトは、現在選択されているノードに設定されているテキストのサイズと内容をプリントします。

  print ::Apsaly.Project.GetNodeText(,"size");
  print ::Apsaly.Project.GetNodeText();

(2) 次のスクリプトは、現プロジェクト内の各ノードに設定されているテキストを、各ノードの深さに応じて、「階層付きテキスト」として、 -Report- ウィンドウにプリントします。

  Proj := ::Apsaly.Project;  // プロジェクト関連メンバー関数への参照
  Print := ::Apsaly.Report;  // -Report- ウィンドウ出力関数への参照

  for( hv = Proj::GetNodeHv( 0, "root" ) ;
       hv != 0 ;
       hv = Proj::GetNodeHv( hv, "fore" ) )
  {
      title =  Proj::GetNodeAttr( hv, "title" );
      if( title'part == "." )     // タイトルの先頭がピリオッド？
          title = " " + title;    // 先頭に半角空白を補充

      // タイトル行のプリント
      if(( depth = Proj::GetNodeDepth( hv ) - 1 ) > 0 )
          Print( "."'rep( depth ) + title + "\r\n" );

      // 本文のプリント
      Text = Proj::GetNodeText( hv );
      if( Text )
          Print( Text'subst( $"^\.", " ." ) );
          //（注）行頭にピリオッドがあれば、行頭に半角空白を補充
  }

この例と同様の実用スクリプトが、スクリプト標準フォルダ内の ProjToText.mc にあります。また、これとは逆に、「階層付きテキスト」からプロジェクトを生成するスクリプトも、スクリプト標準フォルダ内の ProjFromText.mc にあります。

Project.SetNodeText( hv, text )

機能：	ノード hv に指定の text を設定します。
説明：	引数 hv には、対象となるノードの識別値を指定します（⇒参照）。引数 text には、対象ノードに設定するテキストを指定します。引数 text が省略された時（または不正の時）、対象ノードへのテキストの設定は無くなります。本関数は、その処理が成功なら #TRUE を返し、失敗なら #FALSE を返します。
用例：	次のスクリプトは、現選択ノードに、「Hello, world.<改行>」という内容のテキストを設定します。 ::Apsaly.Project.SetNodeText( , "Hello, world.\r\n" );

Project.ExecNode( hv )

機能：	ノード hv の参照ファイルの実行、または、ノードテキストの編集を行ないます。
説明：	引数 hv には、実行対象のノードの識別値を指定します（⇒参照）。本関数は、対象ノードを、次のように実行します。まず、対象ノードに参照先のファイルがある場合、その拡張子（またはタイプ）に関連付けられている「実行プログラム」が、そのファイルを処理します。一方、対象ノードに参照先のファイルがない場合、対象ノードにテキストが設定されていれば、そのテキストの編集を行ないます。さもなければ、何も実行できないので、エラーになります。本関数は、その処理が成功なら #TRUE を返し、失敗なら #FALSE を返します。
用例：	次のスクリプトは、現選択ノードを実行します。 ::Apsaly.Project.ExecNode();

Project.EditNode( hv, nx )

機能：

ノード hv の参照ファイル、または、ノードテキストの編集を開始します。

説明：

引数 hv には、編集対象のノードの識別値を指定します（⇒参照）。

本関数は、対象ノードの編集を、次のように開始します。
対象ノードに参照先のファイルがあれば、そのファイルを本エディタで開きます。その参照ファイルが無ければ、そのノードテキストの編集を行ないます。その際、ノードテキストが無ければ、空のテキストを新規に設定します。このいずれの場合でも、本エディタの編集ウィンドウが表示されます（既に、表示されていれば、それがアクティブになります）。

同一プロジェクト内のノードテキストの編集は、特別な指定が無ければ、排他的になります。つまり、同一プロジェクト内で、あるノードテキストの編集を排他的に開始すると、それまでに行なっていた他の排他的なノードテキストの編集は、自動的に終了します。一方、プロジェクトが異なるか、または、非排他的なノードテキストの編集ウィンドウは、複数同時に開けます。

引数 nx に、#TRUE を指定すると、ノードテキストの編集は、非排他的になり、 #FALSE を指定するか、または省略すると、排他的になります。

本関数は、その処理に成功すれば、その編集ウィンドウの識別値を返します。失敗すれば 0 を返します。

用例：

次のスクリプトは、現選択ノードの排他的な編集を開始します。

  ::Apsaly.Project.EditNode();

Project.FilePath( hv, path )

機能：

ノード hv を含むプロジェクトの格納ファイルのフルパスを取得／設定します。

説明：

引数 hv には、対象とするプロジェクト内の任意のノードの識別値を指定します（⇒参照）。つまり、このノードを含むプロジェクトが、その格納ファイルのフルパスの取得／設定の対象になります。

引数 path を省略した場合、本関数は、対象のプロジェクトが格納されるファイルのフルパスを返します。本関数は、その処理に失敗すれば、null を返します。

引数 path にフルパスを指定した場合、本関数は、それを、対象のプロジェクトが格納されるファイルのフルパスとして設定します。本関数は、その処理に成功すれば #TRUE を返し、失敗すれば #FALSE を返します。なお、引数 path にフルパス以外の値を指定した時、本関数の動作は不定です。

用例：

(1) 次のスクリプトは、現選択ノードを含むプロジェクトの格納ファイルのフルパスをプリントします。

  print ::Apsaly.Project.FilePath();

(2) 次のスクリプトは、現選択ノードを含むプロジェクトの格納ファイルのフルパスを、「D:\Tools\Apsaly\Projects\abc.xpj」に設定します。

  ::Apsaly.Project.FilePath( , $"D:\Tools\Apsaly\Projects\abc.xpj" );