喜好設定

工作台實作通用喜好設定架構,允許外掛程式儲存使用者喜好設定值及提供喜好設定 頁資料給工作台喜好設定對話框。我們將再次查看 Readme 工具範例以瞭解其作法, 然後查看一些建置喜好設定頁的基礎支援。

org.eclipse.ui.preferencePages

org.eclipse.ui.preferencePages 延伸點可讓您提供頁面資料給工作台喜好設定(視窗->喜好設定)對話框 。 喜好設定對話框顯示使用者喜好設定項目的階層式清單。選取每一個項目時會顯示一 個對應的喜好設定頁。

Readme 工具使用這個延伸點來新增 Readme Example 喜好設定頁。

<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>

這個標記定義稱為 "Readme Example" 的喜好設定頁,它由類別 ReadmePreferencePage 實作。該類別必須實作 IWorkbenchPreferencePage 介面。

工作台使用 PreferenceManager 將所有節點的清單保存在喜好設定樹狀結構及其對應頁中。此清單可透過外掛程式登 錄中的資訊起始設定,不需要執行任何外掛程式碼。您喜好設定對話框(左 邊的 "Readme Example" 項目)的外掛程式構成要素會在任何程式碼執行前顯 示。

"Readme Example" 喜好設定會新增到左邊喜好設定樹狀結構的最上層。 為什麼呢?因為喜好設定頁構成要素會新增為樹狀結構的根目錄,除非有指定 category 屬性。(category 這個名稱略有誤導。 path 可能比較正確。)category 屬性指定母項頁面的 ID(或 根目錄中 ID 的順序)。例如,下列標記會建立第二個 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>

一旦使用者選取左邊樹狀結構中喜好設定頁的項目,工作台便會利用延伸定義中指定 的類別來建立及顯示喜好設定。這就是啟動外掛程式的動作(如果外 掛程式因另一個使用者作業而尚未啟動)。

喜好設定頁面

定義頁面

實作喜好設定頁面類似為精靈建立頁面。喜好設定頁面提供 createContents 方法來建立代表頁面內容的 SWT 控制項,並為任何感興趣的事件新增接聽器。該頁面負責建立及傳回行為頁面中所有控制項之母項的組合。下列片段顯示重 點:

protected Control createContents(Composite parent)
{
    ...
    //composite_textField <<母項ent
    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);
    //圓鈕組合 << 標籤組合
    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() 方法以傳回儲存其值的喜好 設定儲存庫。

外掛程式喜好設定儲存庫

喜好設定儲存庫本質上類似對話框設定。在對話框設定中,我們看到 AbstractUIPlugin 類別如何在外掛程式生命期限期間維護對話框設定,使用者喜好設定使用相同的策略 。 您的外掛程式可新增項目到喜好設定儲存庫,並在使用者變更您喜好設定頁面中的設 定時更新其值。平台負責將這些值儲存在您外掛程式的工作目錄中,及根據儲存的設 定來起始設定喜好設定儲存庫。

ReadmePreferencePage 中的下列程式碼可取得 ReadmePlugin 的喜 好設定儲存庫。

protected IPreferenceStore doGetPreferenceStore() {

 return ReadmePlugin.getDefault().getPreferenceStore();

}

由於 ReadmePlugin 延伸 AbstractUIPlugin 類別,所以會自動繼承喜好設定儲存庫,這個喜好設定儲存庫根據外掛程式目錄中儲 存的喜好設定檔來起始設定。此 ReadmePlugin 唯一需要做的是實作 方法來將喜好設定起始設定回它們的預設值。第一次顯示喜好設定頁面或使用者按下 喜好設定頁面中的預設值按鈕時,會使用這些值。

protected void initializeDefaultPreferences(IPreferenceStore store) {

 // 第一次開啟「喜好設定」對話框時,

 // 這些設定將顯示出來。

 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));
 ...

當按下確定(或套用)按鈕,喜好設定頁面上控制項現行值應存回喜 好設定儲存庫中。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());

 ...

}

當使用者按下預設值按鈕,平台便會將所有喜好設定儲存值還原成外掛程式 類別中指定的預設值。不過,您的喜好設定頁面負責在喜好設定頁面的控制項中反映 這些預設值。ReadmePreferencePageinitializeDefaults 中實 作這個邏輯。

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 類別,它可建立小組件及實作最常見喜 好設定類型的值設定和擷取程式碼。平台提供欄位編輯器來顯示及更新許多值類型, 包括 boolean、color、string、integer、font 及 file name。

FieldEditorPreferencePage 實作一個頁面,該頁面使用這些欄位編輯器來顯示及儲存頁面上的喜好設定值。

您不需要建立 SWT 控制項來填入其內容,FieldEditorPreferencePage 可建立欄位編輯器來顯示內容。

public void createFieldEditors() {

    // 第一個字串是喜好設定索引鍵名稱
    // 第二個字串是小組件旁邊所顯示的標籤 
    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 控制項被指定其對應喜好設定索引鍵名稱 和文字標籤。建立的控制項種類視欄位編輯器類型而定。例如,boolean 欄位編輯器 建立勾選框。

一旦建立喜好設定頁面與喜好設定儲存庫(在 doGetPreferenceStore 方法 中指定)的關聯性,儲存現行值的程式碼、從喜好設定儲存庫起始設定控制項值的程 式碼,以及將控制項還原成預設值的程式碼皆可在 FieldEditorPreferencePage 中實作。

FieldEditorPreferencePage 將搭配使用格線佈置與一個直欄作為欄位編輯器小組件的預設佈置。 若有特殊佈置需求,您可以置換 createContents 方法。