Bracket開発操作手順のヒント

Application Init

あなたが、utils/AppInit内で定義される起動の間、待つことができる2つの主要なマイルストーンです。

• htmlReadyは、Bracketsの最初のDOMの内容が読み込まれる時、知らせます。 （テンプレートは、変換された文字列が含まれるために、Mustacheによって、レンダリングされます）一旦、イベントが発生すると、静的なDOM要素の問い合わせは、安全です。 拡張機能は、このイベントを待つ必要はありません。－それらは、常に、その後に、読み込まれます。 しかし、中心的なモジュールは、DOMを問い合わせる前に、このイベントのために、待機する必要があります。
• appReadyは、拡張機能が読み込みを完了した時を知らせます。初めに開いたプロジェクトが、読み込まれます。 そして、最後に開かれるエディタ/ドキュメントが、読み込まれます。このイベントのために待機することは、通常、拡張機能やコアのために 必要ではありません(原文リンク)。

$(document).readyやwindow.onloadのような、他のイベントに依存しません。

目に見えないけれど重要な部分：総合的なBracketsの起動シーケンスは、以下ように展開します。：

1. グローバルなサードパーティ製のライブラリ（jQuery、Less、Mustache）を読み込みます。
2. RequireJSは、特定のグローバル・シムを設定するmain.jsブートストラッパーを読み込みます。（例えば、Compatibility.jsモジュール）
3. 中心的なBracketsモジュール（そして、CodeMirror、Lodash）を読み込み、メイン・スタートアップのエントリーポイントに達します。：brackets.js
4. View-状態の環境設定が、読み込まれます（brackets.jsの一番下）
5. 中心となる静的なHTML構造が作成されます。（brackets.jsの_beforeHTMLReady（））
6. アプリケーション全体にわたるDOMイベント・ハンドラが、インストールされます。
7. htmlReadyイベントが、発生します。（_beforeHTMLReady（）が返された後、一番下のbrackets.js）
8. CodeMirrorモードは、読み込まれ、そして、グローバルな環境設定が、読み込みまれます。（brackets.js内の_onReady()）
9. 拡張機能が、読み込まれます。：組み込み優先です。続いて、user/dev拡張機能（ExtensionLoader.init()が呼び出されます）
10. 最初のプロジェクトが、読み込まれます。：ファイル・ツリーが、埋め込まれます。作業設定が、復元され、そして、アクティブ・ドキュメントが、開かれます。 （ProjectManager.openProject()が呼び出されます。MainViewManager内で「projectOpen」ハンドラが続きます）
11. 11. appReadyイベントが、発生します。

Bracketsの新しいバージョンが利用できる場合、更新された通知ダイアログは、手順7の後、いつでも表示されるかもしれません。

Asynchronous APIs

Bracketsの多くの操作は、非同期でそれらの結果を返します。－例えば、それらが、ファイルI/Oを必要とするため。 これらのAPIは、成功/失敗を聞き取り、結果を取得するために使用することができる、 jQuery Promise(原文リンク)オブジェクトを返します。

（並列、あるいは、シリアルで）一連の非同期動作で作業するため、Async utilsモジュールが、役に立つかもしれません。

Core Classes

• エディタは、（CodeMirrorの部品を包む）Viewを表現します。 －フルサイズのエディタやインライン・エディタのいずれか、エディタは、フォーカスを持つことができます。 カーソル位置、選択やスクロール位置を取得して/設定するために、Editorオブジェクトを使用します。 すべてのエディタは、ドキュメントに添付されます。（editor.documentを通してアクセス可能です）
• ドキュメントは、Modelを表現します。（ファイルのテキストの内容）。 テキストへの変更を取得するために、あるいは、テキストを変更の変更を聞き取るために、Documentオブジェクトを使用します。 一つのDocumentに複数のEditorsを添付できるかもしれません。 （例えば、フルサイズのエディタは、インライン・エディタを追加します） すべてのDocumentは、ディスク上のファイルと関連付けられます。（document.fileを通してアクセス可能です）
• ファイルは、ディスク上のファイルを表現します。それは、ほとんど、飾りのない文字列のパスと同じくらい軽量です： あなたは、実際に、その上、ディスク上のファイルに、読み込む、あるいは、配置すること無しで、FileSystem.getFileForPath()を通して、 同期してファイル・オブジェクトを取得することができます。

How to get a Document

• あなたが、エディタ上で操作している場合、Editor.documentを使用します。

  エディタを取得する方法：

  How to get an Editor:

  • EditorManager.getFocusedEditor()は、フォーカスを持っているエディタを返します。;インライン・エディタかもしれません。フォーカスが、検索バーのような、どこか他にある場合、nullです。
  • EditorManager.getActiveEditor()は類似していますが、フォーカスが、エディタ以外の場所の場合、それは、Editorが、最後にフォーカスを持っている場所を返します。（すなわち、検索バー/ダイアログ/その他が閉じるとき、フォーカスが、Editorに戻るでしょう）
  • EditorManager.getCurrentFullEditor()は、現在、表示されるフルサイズのエディタを返します。（あるいは、フォーカスが、検索バーのような、他のUIにある場合、さらに、フォーカスは、現在、その中のインライン・エディタ内にあります）DocumentManager.getCurrentDocument()を使用することと同義です。
• ファイルのためのDocumentを取得するには、DocumentManager.getDocumentForPath()を使用します。これは、非同期で帰ります。なぜなら、それは、ディスクからファイルの内容を読み込む必要があるかもしれません。
• あなたが、ファイルが、既に開かれていると確信している場合、あなたは、その代わりに、同期するDocumentManager.getOpenDocumentForPath()を使用することができます。－しかし、それは、あなたが間違っている場合、nullを返します。

Proper Document usage

ドキュメントは、広範囲に追跡されます。そして、このように、参照は、特定の状況を計算する必要があります。

あなたが、関数を呼び出す間、Document上へ保持しているだけである場合、 続いて、あなたは、明確に、これについて気にする必要がありません。EditorCommandHandlersのテキスト編集用コマンドは、この優れた例です。

もし、あなたが、そうでない場合、...

• あなたが、後でアクセスをしたいために、ドキュメントのオブジェクトをプロパティに格納します。
• Documentを取得する、非同期で何かを行う、そして、その次に、それが、完了したのち、再び、同じDocumentポインターを呼び出す
• イベント・リスナーをDocumentに添付する

...続いて、あなたは、更に慎重になる必要があります。これら全ての場合において、あなたが、それを取り出したあと、あなたは、DocumentでaddRef()を呼び出す必要があります。そして、その次に、後で、あなたが、それを使用して行うとき、releaseRef()を呼び出します。（例えば、あなたが、プロパティを示すnull を外に出す/重ね書きをするとき、あるいは、あなたのリスナーを分離します）

あなたが、releaseRef()を呼び出すまで、Documentとその完全なテキストの内容は、記憶され、維持されています。このように、可能であれば、Document上へ保持することは、避けたほうがよいでしょう。多くの場合、あなたは、実際に、ファイル・パスを格納することができます。そして、あなたが、それを必要とする時々、Documentを再取り出します。

あなたが、イベント・リスナーをDocumentに添付している場合：

Making edits

Documentのテキストの内容を修正するために、Document.replaceRange()を使用します。あなたが、一つのユーザーの行動の結果として、それを複数回呼び出すことになる場合、Document.batchOperation()内の、それらのすべてのバッチ処理を確実に行うために、あなたのすべての呼び出しを一つのUndo/Redoエントリーにラップします。

多くの場合、あなたが、新しい1種類の編集を実装している場合、あなたは、複数選択を処理したいでしょう。 詳細については、エディタで選択するAPIの変更 (原文リンク)と 複数選択による編集の実行(原文リンク)を参照してください。

Menus and Keyboard Shortcuts

すべてのメニュー項目とショートカットは、Commandを呼び出します。－基本的に、実際、オブジェクトは、enabled/disabledのように、ハンドラ関数、ラベル文字列といくつかの状態が含まれています。CommandManagerは、Commandオブジェクトに「コマンドのID」文字列のマッピングを持っています。メニューは、メニュー項目からコマンドIDへのマッピングを持っています。そして、KeyBindingManagerは、キー割り当てからコマンドIDまでマッピングを持っています。中心的なBracketsのすべてのコマンドIDは、Command内の定数として一覧にされます。

メニュー項目やキーボードショートカットを追加するには、拡張機能を記述する方法 (原文リンク)を参照してください。

Writing a New Inline Editor (Quick Edit)

拡張機能を記述する方法 (原文リンク)を参照してください。

Read/Write Files

一般に、あなたは、ユーザーが、編集するかもしれないファイルの内容を読み込むために、Document（上記を参考）を使用したいと思うでしょう。 あなたが、Documentを経由してファイルを変更する場合、それは、自動的に、ユーザー履歴に保存されていない変更として記録されるでしょう。

いくつかの事例が、あります。ユーザー文書として扱うことなく、あなたは、単純に、設定ファイルを読み込みたいかもしれません。 そのための、Bracketsは、ローカルファイルへ、直接アクセスするために、FileSystem API (原文リンク)を提供しています。 ここに、単純にファイルを読み込む方法があります。：

// 非同期で完了します

// FileSystemError定数の１つ

// On Windows, paths look like "C:/foo/bar.txt"
// On Mac, paths look like "/foo/bar.txt"
// Windowsでは、パスは「C：/foo/bar.txt」のように見えます
// Macでは、パスは「/foo/bar.txt」のように見えます


var file = FileSystem.getFileForPath(localPath);

var promise = FileUtils.readAsText(file);  // completes asynchronously // 非同期で完了します
promise.done(function (text) {
    console.log("The contents of the file are:\n" + text);
})
.fail(function (errorCode) {
    console.log("Error: " + errorCode);  // one of the FileSystemError constants  // FileSystemError定数の１つ

});

OSに関係なく、Bracketsのパスが、常に「/」セパレーターを使用することに注意してください。 詳細に付いては、パス形式(原文リンク)を、お読みください。

Accessing Node Modules from Brackets

Bracketsノードの工程：開発者のための概要 (原文リンク)を参照してください。