Dialogs and Wizards

1. Dialogs and Wizards Cheng-Chia Chen Wu Kun-Tse

2. Outline • Introduction • Extending the Preferences Dialog to Add Our Own Tool Options • Using Property Pages to Remember Something Special About a Resource • Using Wizards to Extend Workbench Resource Creation and Import/Export Support • Summary • Reference

3. Introduction • We will discuss the various types of dialogs and wizards that are available in Eclipse and how we can use and extend them as we develop our tools. • Dialogs and wizards define a framework for building complex interactions with the user. • The reusable dialogs provided will improve our tool development productivity, but the real value is the consistency of your tool with respect to the other tools that have been integrated with Eclipse.

4. Introduction (cont.) • The workbench implements a generic preferences architecture • that allows plug-ins to store user preference values and contribute a preference page to the workbench preferences dialog. • Property pages are very similar to preference pages. • The primary difference is that property pages are associated with a particular resource, while preferences are associated with the plug-in itself. • Wizards are used to guide the user through a sequenced set of tasks.

5. Preference API • provides access to simple string-based key/value pair storage in a flat structure. • like Java Properties • location: <ws>\.metadata\.plugins\<plugin>\pref_store.ini • Ex: • #Mon Mar 20 12:00:00 EST 2006 • a.b.c=true • a.b.d=a default value

6. Values associated with a preference • current value • set by end-user • default value • set by plug-in designer • default-default value • set by Eclipse designer • boolean  false; • numeric(int,long, float, double)  0 or 0.0 • String ””. • Current value is stored only if it is different from its default value. • default values of all preferences for a plug-in can be specified in a file preference.ini in the plugin.

7. Preference store access. • Plugin.getPluginPreferences() • need to call savePluginPreferences() to save the result when it is shutdown. • AbstractUIPlugin.getPreferenceStore() • automatically saved when plguin stoped.

8. Preference access • get current value : • getBoolean(String key): boolean • getString(String) : String • getXxxx(String) : xxxx • where xxxx is int, long, float or double. • get default value: • getDefault<type>(key) : <type> • where type is boolean, String, int, long, float and double.

9. set current value: • setValue(Strign key, <type> value ) • <type> is any of the above six types. • set default value: • setDefault(key, <type> value ). • default = current ? • isDefault(key) • setToDefault(key) : • = set(key, getDefault(key) )

10. contains(key) : boolean • get(key) != default-default value  true. • defaultPropertyNames() : List<String> • list of keys that have a non default-default default value. • propertyNames() : List<String> • list of keys with current value != default value. • load(Stream); store(Stream) • needsSaving(): boolean • dirty since last store().

11. Specify default values • By a file called preferences.ini • at the root of your plugin. • Programmatically (using extension). • <extension point=“org.eclipse.core.rutime.preferences” • <initializer class=“myplugin.id.MyPrefInitializer”> • </>

12. public class MyPrefInitializer() extends AbstractPreferencesInitializer{ public class MyPrefInitializer() { Preferences p = MyPlugin.getDefault(). getPluginPreferences(); p.setDefault( key1, v1) ; p.setDefault( key2, v2) ; … }

13. Listening for Preferences changing • Implement a PropertyChangeListener • listener = new PropertyChangeListener() { • public void PropertyChange(PropertyChangeEvent e ) { • if( e.getProperty() .equals(key1 ) || • … e.getProperty() .equals(keyK ) ) { • updateMyView() ; }} • Registry with the Preferences: • MyPlugin.getDefault.getPluginPreferences().addPropertyChangeListener( listener); • Unregistry : … • .removePropertyChangeListener(listener).

14. Extending the Preferences Dialog to Add Our Own Tool Options • Preference pages allow you to define settings that the user can use to control tool behavior.

15. Steps to Create a Preference Page 1. Define a preference page extension. 2. Implement a preference page. 3. Define the preference page user interface. 4. Establish default preference setting values. 5. Add preference value logic to the preference page.

16. Define a preference page extension • Add an org.eclipse.ui.preferencePages extension definition to plugin.xml. <extension point="org.eclipse.ui.preferencePages"> <page name="Soln: Basic Preference Page" class="com.ibm.lab.soln.dialogs.MyPrefPageBasic" id="com.ibm.lab.soln.dialogs.prefpage1"> </page> <page name="Soln: FieldEditor Preferences SubPage" category="com.ibm.lab.soln.dialogs.prefpage1" class="com.ibm.lab.soln.dialogs.MyPrefPageFieldEditor" id="com.ibm.lab.soln.dialogs.fieldPrefpage"> </page> </extension>

17. Implement a preference page • Creating a class implementing IWorkbenchPreferencePage, or extends PreferencePage. public class MyPrefPageBasic extends PreferencePage implements IWorkbenchPreferencePage { // The constructor. public MyPrefPageBasic([String title [ ImageDescriptor img]] ) { super( [title [,img]]) ; … } // Initializes the preference page by gettinga local reference to // the Preferences object from the your Plugin. // Triggered only when the page is first accessed. public void init(IWorkbench workbench) { … } // Implement the user interface for the preference page. protected Control createContents(Composite parent) { … } }

18. Implement a preference page (cont.) • To implement support for modifying the preferences displayed, you supply the logic for any displayed push buttons. • Methods to override to customize push button logic for preference pages: • performOK() should be overridden to to savepreference values. performApply() invokes performOK() by default. • call noDefaultAndApplyButton() in init() if do not want Apply and RestorDefault buttons.

19. Define the preference page user interface • We will need to customize the createContents method to add the widgets required in our user interface. protected Control createContents(Composite parent) { // Add layer to parent widget Composite composite = new Composite(parent, SWT.NONE); // Define laout rules for widget placement GridLayout compositeLayout = new GridLayout(); … composite.setLayout(compositeLayout); Label labelN = new Label(group, SWT.NONE); labelN.setText( "Select the number of files to keep in the \nRecent Edits list:"); … // return the widget used as the base for the user interface return composite; }

20. Preference Management in a Plug-in • The preference settings are kept in a preferencestore that is obtained from the associated plug-in and saved as part of the active workspace. • The tasks required to support storing preferences are: • Get the preference store (PreferenceStore or Preferences object) from your plug-in. • Establish any defaults for the preference settings to be supported • Use this object to establish the init and modified contents of your preference page implementation • Make sure the contents of the object are saved to disk when Eclipse shut down • Eclipse provides two options for storing preference settings: • Use the AbstractUIPlugin API and a PreferenceStore object • Use the Plugin API and a Preferences object

21. Establish default preference setting values (deprecated) • use PreferencesInitializer instead. • If your plug-in class has extended AbstractUIPlugin, you could re-implement either of the following methods establish preference-setting defaults. • initializeDefaultPreferences(IPreferenceStore store) • initializeDefaultPluginPreferences() protected void initializeDefaultPreferences(IPreferenceStore store) { // Add an entry for each preference default value. store.setDefault("text_field_key", "myTextDefaultValue"); } protected void initializeDefaultPluginPreferences() { // Add an entry for each preference default value. // Do not send super. getPluginPreferences().setDefault( "text_field_key", "myTextDefaultValue"); }

22. Add preference value logic to the preference page • There are several steps required to integrate our preference page with how the preference setting values will be stored. • Finding the PreferenceStore or Preferences object for our plug-in • Associating a preference page with a preference store • Obtaining preference values for user interface(for Initialization) • Getting defaults values (for restoreDefault) • Saving modified preference setting values (for reuse nex time).

23. Finding the Preference Store or Preferences Object for Our Plug-in • We can get a handle for the object used to store preferences from our plug-in by using either of these methods: • The FieldEditorPreferencePage approach discussed later can only use a PreferenceStore object type. IPreferenceStore ps = DialogPlugin.getDefault().getPreferenceStore(); Preferences prefs = DialogPlugin.getDefault().getPluginPreferences();

24. Associating a Preference Page with a Preference Store • If we get a PreferenceStore object from our plug-in, it can be directly associated with our preference page using the setPreferenceStore method. This is best done in the init method as the page is activated. • The preference page hierarchy does not allow us to associate a Preferences object with the current preference page. We could choose to add an instance variable and set the value ourselves. DialogsPlugin myPlugin = DialogsPlugin.getDefault(); if (myPlugin instanceof AbstractUIPlugin) { AbstractUIPlugin uiPlugin = (AbstractUIPlugin) myPlugin; this.setPreferenceStore(uiPlugin.getPreferenceStore()); } Preferences pref = DialogsPlugin.getDefault().gtePluginPreferences();

25. Obtaining Preference Values for User Interface • We need to show the current preference values in our preference page so that the user can review them for possible modification. • The logic to get a String value for an identified preference setting for use in a UI control is shown below: // PreferenceStore approach textInfo.setText(getPreferenceStore.getString("text_field_key"); // Preferences approach textInfo.setText( // or pref.getString(…) ; myPlugin.getDefault().getPluginPreferences().getString("text_field_key"));

26. Getting Default Values • The RestoreDefaultsbutton in the preference page allows the user to request that the settings be returned to their default values. • If we defined defaults in the plug-in, we can use this logic to obtain those defaults for display in the user interface: // PreferenceStore approach textInfo.setText( getPreferenceStore().getDefaultString( "text_field_key"); // Preferences approach textInfo.setText( myPlugin.getDefault() .getPluginPreferences() .getDefaultString("text_field_key");

27. Saving Modified Preference Setting Values • If the user selects Apply or OK button, you obtain the current preference values from the user interface and modify the associated preference settings. • There is one set method, setValue, which takes keys of the preference setting and the value to be set. // PreferenceStore approach getPreferenceStore().setValue( "text_field_key", textInfo.getText()); // Preferences approach myPlugin.getDefault().getPluginPreferences().setValue( "text_field_key", textInfo.getText());

28. Reacting to Preference Setting Changes • If we need to know when a preference setting changes so that we can dynamically react to the changes, we can ask to be notified by adding a property change listener. // PreferenceStore approach DialogsPlugin .getDefault() .getPreferenceStore() .addPropertyChangeListener( new IPropertyChangeListener() { public void propertyChange(PropertyChangeEvent event) { System.out.println(event.getProperty()); … }; });

29. Reacting to Preference Setting Changes (cont.) // Preferences approach DialogsPlugin .getDefault() .getPluginPreferences() .addPropertyChangeListener( new Preferences.IPropertyChangeListener() { public void propertyChange(Preferences.PropertyChangeEvent event) { System.out.println(event.getProperty()); … }; }); Notes: Although Preferences.PropertyChangeEvent and jface.util.PropertyChangeEvent has the same signature and semantics, they are different classes. Preference.IPropertyChangeListener and o.e.jface.util.IPropertyChangeListener are the similar.

30. PropertyChangeEvent • Extends j.u.EventObject • Constructor • PropertyChangeEvent(Object source, String property, Object oldValue, Object newValue); • Readonly properties: • source/*Preferences*/, property, oldValue, newValue IPropertyChanegListener { void propertyChanged(PropertyChangeEvent) }

31. Building a Field Editor Preference Page • Rather than extending the PreferencePage class above, we can choose to build a field editor preference page. • Steps: • Add a preference page extension. • Implement a class that extends FieldEditorPreferencePage and implements IWorkbenchPreferencePage to build on the field editor processing approach. • Associate a preference store with the preference page. • Implement the creatFieldEditors method to create and add specialized field editors that define the user interface for the page. • Example: • Eclipse Article: Simplifying Preference Pages with Field Editors

32. Field Editors provided • FieldEditor • BooleanFieldEditor, • ColorFieldEditor, • FontFieldEditor, • RadioGroupFieldEditor • ScaleFieldEditor, • ListEditor • PathEditor • StringFieldEditor • IntegerFieldEditor • StringButtonFieldEditor • FileFieldEditor • DirectoryfieldEditor

33. Different Types of Field Editors

35. Using field editors with a FieldEditorPreferencePage • extends FieldEditorPreferencePage • implements IWorkbenchPreferencePage class HTMLPreferencePage extends FieldEditorPreferencePage implements IWorkbenchPreferencePage { // ... }

36. instantiate and set a preference store for the preference page • super(int) requires a layout const • GRID  all fields share a single (one column) GRIDLayout • FLAT  each field handle its own layout. public HTMLPreferencePage() { super(FieldEditorPreferencePage.GRID); // Set the preference store for the preference page. IPreferenceStore store = HTMLEditorPlugin.getDefault().getPreferenceStore(); setPreferenceStore(store); }

37. The HTML Editor Preference Page

38. createFieldEditors() • use addField(FieldEditor) protected void createFieldEditors() { // Initialize all field editors. BooleanFieldEditor formatOnSave = new BooleanFieldEditor( IPreferenceConstants.FORMAT_PREFERENCE, //property "&Format before saving", getFieldEditorParent()); addField(formatOnSave); SpacerFieldEditor spacer1 = new SpacerFieldEditor(getFieldEditorParent()); addField(spacer1); IntegerFieldEditor indentSpaces = new IntegerFieldEditor( IPreferenceConstants.INDENT_PREFERENCE, "&Number of spaces to indent:", getFieldEditorParent()); indentSpaces.setValidRange(0, 10); addField(indentSpaces);

39. SpacerFieldEditor spacer2 = new SpacerFieldEditor( getFieldEditorParent()); addField(spacer2); ColorFieldEditor commentColor = new ColorFieldEditor( IPreferenceConstants.COMMENT_COLOR_PREFERENCE, "C&omments:", getFieldEditorParent()); addField(commentColor); ColorFieldEditor errorColor = … ; addField(errorColor); ColorFieldEditor validColor = …; addField(validColor); FontFieldEditor font = new FontFieldEditor( IPreferenceConstants.FONT_PREFERENCE, "Edito&r font:", getFieldEditorParent()); addField(font); SpacerFieldEditor spacer3 = new SpacerFieldEditor( getFieldEditorParent()); addField(spacer3); FileFieldEditor webBrowser = new FileFieldEditor( IPreferenceConstants.BROWSER_PREFERENCE, "&Web browser:", true, // enforceAbsolute getFieldEditorParent()); addField(webBrowser); }

40. Using field editors with a regular PreferencePage

41. Additional Works need to do • In addition to creating the preference store and instantiating field editors, • you must write code to load preferences, store preferences, and restore defaults. • Without a FieldEditorPreferencePage, you can still take advantage of a field editor's self-validation via the FieldEditor.isValid() method, but you must write the code that calls this method.

42. class ErrorPreferencePage extends PreferencePage implements IWorkbenchPreferencePage { // ... }

43. createContents(Composite) protected Control createContents(Composite parent) { Composite top = new Composite(parent, SWT.LEFT); // Sets the layout data for the top composite's // place in its parent's layout. top.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); // Sets the layout for the top composite's // children to populate. top.setLayout(new GridLayout()); errors = new RadioGroupFieldEditor( IPreferenceConstants.ERRORS_PREFERENCE, // key "Error conditions", 1, // #Column new String[][] { {"Don't show errors",// label IPreferenceConstants.NO_ERRORS }, // value

44. {“Show error if a closing tag is missing”, IPreferenceConstants.ERROR_FOR_MISSING_CLOSING_TAG } }, top/*container*/, true// use group control); errors.setPreferencePage(this); errors.setPreferenceStore(getPreferenceStore()); errors.load(); Label listLabel = new Label(top, SWT.NONE); listLabel.setText("Tags which do not require closing tags:"); exemptTagsList = new List(top, SWT.BORDER); exemptTagsList.setItems( HTMLEditorPlugin.getDefault().getExemptTagsPreference()); // ... // The remainder of the code has been omitted for brevity. // ... return top; }

45. PerformDefaults(),performOK() • needed for regular preference page protected void performDefaults() { errors.loadDefault(); exemptTagsList.setItems( HTMLEditorPlugin.getDefault(). getDefaultExemptTagsPreference()); // getDefaultExemptTagsPreference() is a convenience // method which retrieves the default preference from // the preference store. super.performDefaults(); } public boolean performOk() { errors.store(); HTMLEditorPlugin.getDefault(). setExemptTagsPreference(exemptTagsList.getItems()); return super.performOk(); }

46. Using Property Pages to Remember Something Special About a Resource • The role of a property page is to allow the user to see and modify values associated with a specific object that supports the property dialog in Eclipse.

47. Steps to Create Property Page 1. Define a property page extension. 2. Implement a property page. 3. Define the property page user interface. 4. Add resource property access logic.

48. Defining a Property Page Extension • To add a property page, you create an org.eclipse.ui.propertyPages extension definition in your plug-in manifest. <extension point="org.eclipse.ui.propertyPages"> <page objectClass="org.eclipse.core.resources.IFile" adaptable="true" name="Soln: File Properties“ nameFilter=“*.java” class="com.ibm.lab.soln.dialogs.MyPropertyPage" id="com.ibm.lab.soln.dialogs.proppage1"> </page> </extension>

49. Implementing a Property Page • We define a property page by creating a class that implements the IWorkbenchPropertyPage interface. The easiest way to accomplish this is to extend the PropertyPage class. MyPropertyPage extends PropertyPage implements IWorkbenchPropertyPage { // Creates the user interface for the property page. protected Control createContents(Composite parent) { … } // Methods to override to customize push button logic for property pages performOK() { … } }

50. Defining the Property Page User Interface • We customize the createContents() method to add the controls required in the user interface. protected Control createContents(Composite parent) { // Add layer to parent widget Composite composite = new Composite(parent, SWT.NONE); // Define laout rules for widget placement GridLayout compositeLayout = new GridLayout(); … composite.setLayout(compositeLayout); Label labelB = new Label(group, SWT.NONE); labelB.setText("Select to disable Recent Edits list support:"); … // return the widget used as the base for the user interface return composite; }