UDIG Developer Guide : 2 Adding History to Dialogs and Wizards
This page last changed on Nov 19, 2005 by jgarnett.
Adding History to Dialogs and WizardsOverviewIt is often beneficial to add a 'history' to some of the widgets to increase the useability of a wizard or dialog. This article will explain how to use Eclipse's IDialogSettings interface to achieve this easily and will show how it was implemented in uDig's WMS Wizard. The terms wizard and dialog are interchangeable in this document. Here is a screenshot of the WMS Wizard, displaying the rememberance of previously-entered URLs. Here is what the contents of the file look like when saved out to disk: dialog_settings.xml <?xml version="1.0" encoding="UTF-8"?> <section name="Workbench"> <section name="WMS_WIZARD"> <list key="WMS_RECENT"> <item value="http://wms.cits.rncan.gc.ca/cgi-bin/cubeserv.cgi?VERSION=1.1.0&REQUEST=GetCapabilities"/> <item value="http://www2.dmsolutions.ca/cgi-bin/mswms_gmap?VERSION=1.1.0&REQUEST=GetCapabilities"/> </list> </section> </section> The overview: IDialogSettingsThe JavaDoc for IDialogSettings can be viewed here. The interesting methods are:
Dialog settings are used to store information about particular dialogs. The settings are stored in the plugin's runtime workspace. Because each plugin can have more than one dialog or wizard, the settings are divided up into sections designated by a string. To create a new section, call settings.addNewSection("example_id"). Values saved into a dialog can be any primitive type, a String or array of Strings. An array of Strings is the most interesting for dialogs, as they often use combo boxes for fields with history. The loading and saving is handled by the plugin class. An ExampleThe WMS Wizard inside uDig has been converted to use IDialogSettings to store previously entered URLs. Initializing the settingsWMSWizardPage.java private static final String WMS_WIZARD = "WMS_WIZARD"; //$NON-NLS-1$ private IDialogSettings settings; public WMSWizardPage() { ... settings = WmsPlugin.getDefault().getDialogSettings().getSection(WMS_WIZARD); if (settings == null) { settings = WmsPlugin.getDefault().getDialogSettings().addNewSection(WMS_WIZARD); } } This code accesses the previously entered values stored at the section named 'WMS_WIZARD'. If they don't exist (settings == null), the section must be added. Reading the settingsThe code in WMSWizardPage that instantiates the widgets is also responsible for populating those widgets with previously entered values. WMSWizardPage.java private static final String WMS_RECENT = "WMS_RECENT"; //$NON-NLS-1$ public void createControl(Composite parent) { String[] recentWMSs = settings.getArray(WMS_RECENT); if (recentWMSs == null) { recentWMSs = new String[0]; } ... url = new Combo(composite, SWT.BORDER); url.setItems(recentWMSs); ... } This code accesses all the values stored at the key 'WMS_RECENT'. If no values are there, it will return null. Later on, the Combo widget 'url' has its items set to those values. Saving the settingsSaving the settings is a little more complicated than using them. The IDialogSettings interface only allows an entire key to be saved at once, so we must add our new history item to the array and save it again. Some convienence code has been taken from the org.eclipse.team.internal.ccvs.ui.wizards.ConfigurationWizardMainPage class to make this job easy. The addToHistory methods also limit the size of the history for each widget. Simply alter the value of COMBO_HISTORY_LENGTH to change the size. The only one here you should have to alter is saveWidgetValues(). Simply create a key (WMS_RECENT) for each widget, retrieve the previous values, and call addToHistory, passing in the value from the widget as well. After that, just add the key and the values to the IDialogSettings. WMSWizardPage.java private static final int COMBO_HISTORY_LENGTH = 15; /** * Saves the widget values */ private void saveWidgetValues() { // Update history if (settings != null) { String[] recentWMSs = settings.getArray(WMS_RECENT); if (recentWMSs == null) { recentWMSs = new String[0]; } recentWMSs = addToHistory(recentWMSs, url.getText()); settings.put(WMS_RECENT, recentWMSs); } } /** * Adds an entry to a history, while taking care of duplicate history items * and excessively long histories. The assumption is made that all histories * should be of length <code>COMBO_HISTORY_LENGTH</code>. * * @param history the current history * @param newEntry the entry to add to the history * @return the history with the new entry appended * Stolen from org.eclipse.team.internal.ccvs.ui.wizards.ConfigurationWizardMainPage */ private String[] addToHistory(String[] history, String newEntry) { ArrayList<String> l = new ArrayList<String>(Arrays.asList(history)); addToHistory(l, newEntry); String[] r = new String[l.size()]; l.toArray(r); return r; } /** * Adds an entry to a history, while taking care of duplicate history items * and excessively long histories. The assumption is made that all histories * should be of length <code>COMBO_HISTORY_LENGTH</code>. * * @param history the current history * @param newEntry the entry to add to the history * Stolen from org.eclipse.team.internal.ccvs.ui.wizards.ConfigurationWizardMainPage */ private void addToHistory(List<String> history, String newEntry) { history.remove(newEntry); history.add(0,newEntry); // since only one new item was added, we can be over the limit // by at most one item if (history.size() > COMBO_HISTORY_LENGTH) { history.remove(COMBO_HISTORY_LENGTH); } } Once saveWidgetValues() is configured, you simply need to call it when your dialog or wizard is done. /* * Success! Store the URL in history. */ saveWidgetValues(); |
![]() |
Document generated by Confluence on Nov 19, 2005 20:02 |