Ambient — Alpha オートメーション オブジェクト モデル

Alpha プラグインで使用するオブジェクトのドキュメントです。

このドキュメントは暫定的なものであり、記述されている内容は将来変更される可能性があります。また Alpha の実装状況などにより、実装されていないオブジェクト、メンバも多数存在します。

このリファレンスはスクリプトユーザ向けです。型名などはネイティブユーザが使用するものとは異なります。例えば論理型 (boolean) や文字列 (string) はスクリプト環境の適切なデータ型を意味しますが、実際は OLE 型である VARIANT_BOOL や BSTR を使用します。

バージョン

Ambient 0.5.3α

ホームページ

<http://www.interq.or.jp/student/exeal/dss/res/alpha/>

<http://sourceforge.jp/projects/alpha/>

Contents

• インターフェイス (オブジェクト)
  • IApplication : IDispatch (Application オブジェクト) - Alpha のルートオブジェクト
  • IDocuments : IDispatch (Documents コレクション) - アプリケーションが開いている全てのドキュメント
  • IDocument : IDispatch (Document オブジェクト) - 開いているドキュメント
  • IHTMLDocument : IDocument (HTMLDocument オブジェクト) - HTML ドキュメント
  • ITextDocument : IDocument (TextDocument オブジェクト) - テキストドキュメント
  • ITextProcessor : IDispatch (TextProcessor オブジェクト) - テキストエディタ
  • ITextSelection : IDispatch (TextSelection オブジェクト) - キャレットと選択範囲の操作
  • ITextRanges : IDispatch (TextRanges コレクション) - ドキュメントの断片のコレクション
  • ITextRange : IDispatch (TextRange オブジェクト) - ドキュメントの断片
  • ITextPoint : IDispatch (TextPoint オブジェクト) - ドキュメントの特定の位置
  • IEditPoint : ITextPoint (EditPoint オブジェクト) - ドキュメントの編集可能な特定の位置
  • IScriptHost : IDispatch (ScriptHost オブジェクト) - スクリプトホスト
  • IArguments : IDispatch (Arguments コレクション) - 引数
  • INamedArguments : IDispatch (NamedArguments コレクション) - 名前付き引数
  • IUnnamedArguments : IDispatch (UnnamedArguments コレクション) - 名前無し引数
• 列挙
  • WindowState - ウィンドウ状態
  • FileShareMode - ファイルの共有モード
  • BreakType - 改行コード
  • FindTextFlags - 検索条件
  • ConvertType - 部分テキスト変換フラグ
  • CharCountBehavior - 文字数カウント方法
• その他
  • オブジェクト階層 - 階層図
  • コードページの一覧 - IDocuments::Open 、IDocument::Save で使用する Windows コードページ
  • 使用例
  • 更新履歴

オブジェクト階層

Alpha のオブジェクトモデルは以下のとおりです (未実装のものも含まれています)。

IApplication インターフェイス (Application オブジェクト)

Application オブジェクトは Alpha 自体を表現し、Alpha オブジェクトモデルの最上位オブジェクトになります。Alpha の他のオブジェクト (ホスト以外) にアクセスするにはこのオブジェクトを経由する必要があります。

スクリプト中でこのオブジェクトを参照するには識別子 Ambient か Alpha を使用します (後者は古い名前)

IDocuments インターフェイス (Documents コレクション)

開いている全てのドキュメントです。ドキュメント全体を統括します。このオブジェクトはコレクションです。

IDocument インターフェイス (Document オブジェクト)

開いているドキュメントです。

IHTMLDocument インターフェイス (HTMLDocument オブジェクト)

仕様が決まっていません (MSXML のものとは異なります)。

ITextDocument インターフェイス (TextDocument オブジェクト)

テキストエディタで編集中のドキュメントです。IDocument のメンバを全て継承します。

ITextProcessor インターフェイス (TextProcessor オブジェクト)

ドキュメントの編集を行います。このオブジェクトにはデフォルトメンバはありません。

ITextSelection インターフェイス (TextSelection オブジェクト)

選択範囲、キャレットの操作を行います。Ambient オブジェクトモデルにおける行位置、文字位置、ドキュメント先頭からの絶対オフセットは全て0から始まります。

ITextRanges インターフェイス (TextRanges コレクション)

TextRange のコレクションです。

ITextRange インターフェイス (TextRange オブジェクト)

2つの TextPoint からなるドキュメントの特定の範囲です。

ITextPoint インターフェイス (TextPoint オブジェクト)

ドキュメント中の位置を表します。

IEditPoint インターフェイス (EditPoint オブジェクト)

編集可能な点を表します。ITextPoint のメンバを全て継承します。

IScriptHost インターフェイス (ScriptHost オブジェクト)

スクリプトホストです。このオブジェクトは Windows Script Host の WScript オブジェクトと同じメンバ持ちます Alpha では WScript で参照可能です。

IArguments インターフェイス (Arguments オブジェクト)

スクリプトの引数です。

INamedArguments インターフェイス (NamedArguments オブジェクト)

名前付き引数です。このオブジェクトはコレクションです。

IUnnamedArguments インターフェイス (UnnamedArguments オブジェクト)

名前無し引数です。このオブジェクトはコレクションです。

WindowState

ウィンドウの状態を表します。

FileShareMode

ファイルの共有モードです。

BreakType

改行コードの種類です。

FindTextFlags

ITextProcessor::FindText に使用する検索フラグです。これらの値はビット和で複数指定することができます。ただし AFTF_REGULAREXPRESSION を含めると「検索方向」と「大文字小文字を区別しない」以外のフラグは無視されます。

ConvertType

ITextSelection::Convert 、IEditPoint::Convert に使用する変換フラグです。

CharCountBehavior

IEditPoint の操作における文字数の数え方を表します。

コードページの一覧

ドキュメントの保存などに使用できる Windows コードページは以下の通りです (システムにインストールされていないものは無効です)。コードページ名は Alpha で使用しているものです。

Alpha (及び Ascension) では現在 Windows コードページに基づいて文字コードを管理していますが、Windows コードページに無い文字コードが存在するため、将来は他の識別子を使用する可能性があります。

• *1 - コードページ変換テーブルがインストールされていなくても有効
• *2 - Windows XP のみ?
• *3 - Windows コードページ外

使用例

任意の範囲を選択状態にして置換する

// JScript
var sel = Ambient.ActiveDocument.TextProcessor.Selection;

sel.MoveTo(iLine, iChar); // (iLine, iChar) にキャレットを移動して
sel.CharNext(true, cch);  // そこから cch 文字選択

var selectedText = sel.Text; // 選択範囲のテキストを取得
selectedText = selectedText.toLocaleUpperCase();
sel.Replace(selectedText);   // 置換

キャレットを動かさずに任意の位置のテキストを取得する

' VBScript
Dim pt, txt

' ドキュメントの先頭座標を使って擬似キャレットを作成
Set pt = ActiveDocument.StartPoint.CreateEditPoint()
Call pt.MoveTo(iLine, iChar) ' 擬似キャレットを (iLine, iChar) に移動して
txt = pt.GetText(cch)        ' cch 文字のテキストを取得

Set pt = Nothing             ' 必要ありません

タブを新しく開く → 今日の日付を書き込む → 保存してタブを閉じる

# PerlScript
my $date = localtime(time());
$Ambient->Documents->AddNew();      ' タブを開く
my $doc = $Ambient->ActiveDocument; ' 新しく開いたタブがアクティブになっています
$doc->TextProcessor->Selection->Replace($date);
$doc->Save('sample.txt', 0, 65001); ' LF 、UTF-8 で名前をつけて保存
$doc->Close();                      ' タブを閉じる

1度のアンドゥ (リドゥ) で元に戻せる (やり直せる) 操作の例

アンドゥグループは複数の操作をまとめたもので、1度のアンドゥでまとめて元に戻すことが出来ます。例えば複数の箇所にテキストを挿入するスクリプトジェネレータなどに使用します。

Ambient オブジェクトモデルの幾つかのメソッドは内部でアンドゥグループを作成します。このためスクリプト側で収集中のアンドゥグループが、メソッド呼び出しにより終了してしまう可能性があります。TextSelection のほとんどの編集メソッドは自身でアンドゥグループを作成します。EditPoint は Replace 以外のメソッドはアンドゥグループを作成しません。ただしこれらのセマンティクスは将来変更される可能性があります。

# RubyScript
proc = Ambient.ActiveDocument.TextProcessor
pt = proc.CreateEditPoint(Ambient.ActiveDocument.StartPoint)
proc.BeginEditCollection() # -- アンドゥグループの開始
pt.Insert('xyz')
pt.Copy(-2)
pt.Paste()
pt.CharPrev()
pt.Cut(-1)
pt.MoveToEndOfLine()
pt.Paste()
proc.EndEditCollection()   # -- アンドゥグループの終了
		

更新履歴

0.5.3

ITextProcessor に BeginEditCollection 、EndEditCollection を追加しました

ITextPoint の幾つかのメソッドを IEditPoint に移動しました

IEditPoint に CharCountBehavior 、GetText 、NewLine を追加しました