設定 (Preferences)

ワークベンチは汎用設定アーキテクチャーをインプリメントします。このアーキテクチャーによって、プラグインは、ユーザー設定値の保管、および「ワークベンチ設定 (Workbench Preferences)」ダイアログへの設定ページの追加が可能になります。README ツールの例をもう一度検証して、このインプリメンテーションがどのように行われるのかを確認し、次に設定ページをビルドするための基礎的なサポートを確認します。

org.eclipse.ui.preferencePages

org.eclipse.ui.preferencePages 拡張ポイントによって、ユーザーはページを「ワークベンチ設定 (Workbench preferences)」ダイアログ (「Window」->「設定 (Preferences)」と選択) に追加できます。「設定 (Preferences)」ダイアログは、ユーザー設定エントリーの階層リストを表示します。それぞれのエントリーは、対応する選択時の設定ページを表示します。

README ツールはこの拡張ポイントを使用して、「README 例設定 (Readme Example preferences)」ページを追加します。

<extension
    point = "org.eclipse.ui.preferencePages">
    <page 
        id="org.eclipse.ui.examples.readmetool.Page1"
        class="org.eclipse.ui.examples.readmetool.ReadmePreferencePage"
        name="Readme Example">
    </page>
</extension>

このマークアップは、ReadmePreferencePage クラスがインプリメントする "README 例 (Readme Example)" という名前の設定ページを定義します。このクラスは IWorkbenchPreferencePage インターフェースをインプリメントする必要があります。

ワークベンチは PreferenceManager を使用して、設定ツリーのすべてのノードおよびその対応するページのリストを保持します。このリストは、 プラグイン・コードをまったく実行しなくても、プラグイン・レジストリーの情報で初期化できます。  ユーザー・プラグインの設定ダイアログ (左側の "README 例 (Readme Example)" エントリー) への追加は、 すべてのユーザーのコードが実行される前に表示されます。

"README 例 (Readme Example)" 設定は、左側の設定ツリーの最上位に追加されます。 これはなぜでしょうか。これは追加される設定ページが、 カテゴリー属性が指定されていない限り、ツリーのルートとして追加されるためです。(カテゴリーという名前は誤解を招きやすい名前です。 誤解を避けるには、パスという名前の方がいいかもしれません。)カテゴリー属性は、 親ページの ID (またはルートからの一連の ID) を指定します。たとえば、以下のマークアップは 2 番めの README ツール設定ページ "README 例の子ページ (Readme Example Child Page)" を、オリジナル・ページの子として作成します。

<extension
    point = "org.eclipse.ui.preferencePages">
    <page 
        id="org.eclipse.ui.examples.readmetool.Page1"
        class="org.eclipse.ui.examples.readmetool.ReadmePreferencePage"
        name="Readme Example">
    </page>    
    <page 
        id="org.eclipse.ui.examples.readmetool.Page2"
        class="org.eclipse.ui.examples.readmetool.ReadmePreferencePage2"
        name="Readme Example Child Page"
        category="org.eclipse.ui.examples.readmetool.Page1>
    </page>
</extension>

ユーザーが左側のツリーの設定ページのエントリーを選択すると、 ワークベンチは拡張定義で指定されたクラスを使用して、設定ページを作成し、表示します。  このアクションがプラグインを起動します (他のユーザー操作によってそのプラグインがまだ起動されていない場合)。

設定ページ

ページの定義

設定ページのインプリメントはウィザードのページ作成に似ています。設定ページはページ内容を表す SWT コントロールを作成し、 すべての関連するイベントに対するリスナーを追加する createContents メソッドを提供します。 このページは、ページ内のすべてのコントロールの親となるコンポジットの作成および戻しを実行します。  以下の断片的な例は関連する部分を示しています。

protected Control createContents(Composite parent)
{
    ...
    //composite_textField << parent
    Composite composite_textField = createComposite(parent, 2);
    Label label_textField = createLabel(composite_textField, "Text Field"); 
    textField = createTextField(composite_textField);
    pushButton_textField = createPushButton(composite_textField, "Change");

    //composite_tab << parent
    Composite composite_tab = createComposite(parent, 2);
    Label label1 = createLabel(composite_tab, "Radio Button Options");

    tabForward(composite_tab);
    //radio button composite << tab composite
    Composite composite_radioButton = createComposite(composite_tab, 1);
    radioButton1 = createRadioButton(composite_radioButton, "Radio button 1");
    radioButton2 = createRadioButton(composite_radioButton, "Radio button 2");
    radioButton3 = createRadioButton(composite_radioButton, "Radio button 3");
    ...
    initializeValues();
    ...
    return new Composite(parent, SWT.NULL);
}

このメソッドの大部分のコードは、コントロールの作成およびレイアウトに関連しています。 このためここではこれらを解説しません。  以下の図は対応するページがどのように表示されるかを示しています。

この他の設定ページの基本的な機能は、performOk メッセージに対応することです。通常このメソッドは、 ユーザー設定の更新および保管を行ない、必要であれば、他のプラグイン・オブジェクトを更新して設定の変更を反映します。

設定ページは、設定ストアを戻してその値を保管するために、doGetPreferenceStore() メソッドをオーバーライドする必要があります。

プラグイン設定ストア

設定ストアの特質はダイアログ設定に似ています。ダイアログ設定 (Dialog settings) において、 AbstractUIPlugin クラスがプラグインのライフ・タイム中にどのようにダイアログ設定を保持するかを確認しました。同様のストラテジーが、ユーザー設定のために採用されています。ユーザー・プラグインは、設定ストアにエントリーを追加して、ユーザーがユーザー設定ページの設定を変更すると、値を更新できます。 プラットフォームは、ユーザー・プラグインの作業ディレクトリーにこれらの値を保管し、保管された設定によって設定ストアを初期化します。

ReadmePreferencePage の以下のコードは、ReadmePlugin の設定ストアを取得します。

protected IPreferenceStore doGetPreferenceStore() {

 return ReadmePlugin.getDefault().getPreferenceStore();

}

ReadmePlugin AbstractUIPlugin クラスを拡張するため、設定ストアを自動的に継承します。この設定ストアは、 プラグインのディレクトリーに保管されている設定ファイルによって初期化されます。 ReadmePlugin が実行すべきことは、 設定をそれらのデフォルト値に初期化するメソッドをインプリメントすることだけです。これらの値は、 設定ページが最初に表示された時、またはユーザーが設定ページの「デフォルト (Defaults)」ボタンを押した時に使用されます。

protected void initializeDefaultPreferences(IPreferenceStore store) {

 // These settings will show up when Preference dialog

 // opens up for the first time.

 store.setDefault(IReadmeConstants.PRE_CHECK1, true);

 store.setDefault(IReadmeConstants.PRE_CHECK2, true);

 store.setDefault(IReadmeConstants.PRE_CHECK3, false);

 store.setDefault(IReadmeConstants.PRE_RADIO_CHOICE, 2);

 store.setDefault(IReadmeConstants.PRE_TEXT, "Default text");

}

注 :  プラグイン用に保管された設定がない場合には、そのプラグインは空の設定ストアを取得します。

設定の検索および保管

ユーザー・プラグインの設定ストアをユーザーの設定ページに関連付けすると、設定の検索および保管のためのロジックをインプリメントできます。

設定ページは、設定ストアの設定値を使用して、その制御値の初期化を行ないます。 この処理は、ダイアログ制御値をダイアログ設定値で初期化するのに似ています。 ReadmePreferencePage は、単一のメソッド initializeValues のすべてのコントロールを初期化します。 このメソッドは、その createContents メソッドから呼び出されます。

private void initializeValues() {

 IPreferenceStore store = getPreferenceStore();

 checkBox1.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK1));

 checkBox2.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK2));

 checkBox3.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK3));
 ...

OK」(または「適用 (Apply)」) ボタンが押されると、 設定ページのコントロールの現行値は、設定ストアに保管し戻される必要があります。ReadmePreferencePage は別のメソッド storeValues にあるこのロジックをインプリメントします。

private void storeValues() {

 IPreferenceStore store = getPreferenceStore();

 store.setValue(IReadmeConstants.PRE_CHECK1, checkBox1.getSelection());

 store.setValue(IReadmeConstants.PRE_CHECK2, checkBox2.getSelection());

 store.setValue(IReadmeConstants.PRE_CHECK3, checkBox3.getSelection());

 ...

}

ユーザーが「デフォルト (Defaults)」ボタンを押すと、プラットフォームはすべての設定ストア値を、プラグイン・クラスで指定されたデフォルト値に復元します。 ただし、ユーザー設定ページは、設定ページのコントロール内のこれらデフォルト値を反映する必要があります。ReadmePreferencePage は、これを initializeDefaults でインプリメントします。

private void initializeDefaults() {

 IPreferenceStore store = getPreferenceStore();

 checkBox1.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK1));

 checkBox2.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK2));

 checkBox3.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK3));

 ...

}

フィールド・エディター

設定ページのインプリメンテーションは基本的に SWT コードです。  SWT コードは、 設定ページコントロールの作成、制御値の設定、および制御値の検索 に使用されます。org.eclipse.jface.preference パッケージは、 ウィジェットを作成し、最も一般的な設定型の値設定コードおよび検索コードをインプリメントする、 フィールド・エディター という名前の helper クラスを提供します。 プラットフォームは、ブール値、色、ストリング、整数、フォント、およびファイル名を含む多数の値の型を表示および更新する、フィールド・エディターを提供します。

FieldEditorPreferencePage は、 ページ上の設定値を表示および保管するこれらフィールド・エディターを使用するページをインプリメントします。

SWT 制御を作成して内容を表す代わりに、FieldEditorPreferencePage は、フィールド・エディターを作成し、内容を表示します。

public void createFieldEditors() {

    // The first string is the preference key name
    // The second string is the label shown next to the widget 
    addField(new BooleanFieldEditor(USE_OLD_MODE, "Use old mode",
        getFieldEditorParent()));

    addField(new StringFieldEditor(APPLICATION_NAME, "Application Name",
        getFieldEditorParent()));

    addField(new ColorFieldEditor(COLOR, "Text Color", getFieldEditorParent()));
    ...

それぞれのフィールド・エディターには、エディターが作成する SWT コントロールに対して、 対応する設定キー名、およびテキスト・ラベルが割り当てられます。 作成されるコントロールの種類は、フィールド・エディターの型によって異なります。たとえば、ブール値フィールド・エディターはチェック・ボックスを作成します。

設定ページは設定ストアに関連付けされている ( doGetPreferenceStore メソッドで指定される) ため、 現行値の保管、設定ストアによる制御値の初期化、およびコントロールのデフォルト値への復元のためのコードは、 すべて FieldEditorPreferencePage にインプリメントすることが可能です。

FieldEditorPreferencePage は、 フィールド・エディター・ウィジェットのデフォルト・レイアウトとして、1 つのカラムに格子レイアウトを使用します。  特別なレイアウト要件には、createContents メソッドをオーバーライドすることができます。