Contributing a Search Dialog

### Eclipse Workspace Patch 1.0 #P org.eclipse.platform.doc.isv Index: topics_Guide.xml =================================================================== RCS file: /cvsroot/eclipse/org.eclipse.platform.doc.isv/topics_Guide.xml,v retrieving revision 1.161 diff -u -r1.161 topics_Guide.xml --- topics_Guide.xml 6 Jun 2007 17:01:11 -0000 1.161 +++ topics_Guide.xml 6 Jun 2007 17:46:51 -0000 @@ -69,6 +69,10 @@ + + + + Index: guide/dialogs_FilteredItemsSelectionDialog_example_advanced.htm =================================================================== RCS file: guide/dialogs_FilteredItemsSelectionDialog_example_advanced.htm diff -N guide/dialogs_FilteredItemsSelectionDialog_example_advanced.htm --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ guide/dialogs_FilteredItemsSelectionDialog_example_advanced.htm 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,192 @@ + + + + + + + + +Contributing a Search Dialog + + + +

Advanced use of the Search Dialog

+ +This section will present present how to extend basic functionality of +our example Search Dialog. +
+ +Add selected items history +
+Extend filter functionality +
+Extra check-box +
+ + + +

Adding history of selected items

To achieve that, firstly we extend FilteredItemsSelectionDialog#SelectionHistory + and implement abstract methods for saving and loading objects. Eg.:

+  	private class ResourceSelectionHistory extends SelectionHistory {
+
+		/*
+		 * (non-Javadoc)
+		 * 
+		 * @see org.eclipse.ui.dialogs.FilteredItemsSelectionDialog.SelectionHistory#restoreItemFromMemento(org.eclipse.ui.IMemento)
+		 */
+		protected Object restoreItemFromMemento(IMemento element) {
+			return element.getString("resource"); //$NON-NLS-1$
+		}
+
+		/*
+		 * (non-Javadoc)
+		 * 
+		 * @see org.eclipse.ui.dialogs.FilteredItemsSelectionDialog.SelectionHistory#storeItemToMemento(java.lang.Object,
+		 *      org.eclipse.ui.IMemento)
+		 */
+		protected void storeItemToMemento(Object item, IMemento element) {
+			element.putString("resource", item.toString()); //$NON-NLS-1$
+		}
+
+	}
+

Next we should set our implementation of SelectionHistory on + dialog.
```
+  	setSelectionHistory(new ResourceSelectionHistory());
+  
```
Finally, we make sure that our dialog works properly. You + should see a dialog similar to the one below: +
+

+ + +

Extend filter functionality

Especially we want to filter all strings which start with lower +case character.

Extend FilteredItemsSelectionDialog#ItemsFilter, + implement necessary abstract methods and override equalsFilter(ItemsFilter) + and isSubFilter(ItemsFilter). This two method decide about + filtering method. If last used filter equals to the new one we do + nothing - we simply show the last filtering result. If the new filter + is a sub-filter of the last applied filter we search elements using + cache only. Eg.:

+  	private boolean onlyLowerCase = true;
+  	
+  	private class ResourceFilter extends ItemsFilter {
+
+		public final boolean onlyLowerCase = FilteredResourcesSelectionDialog.this.onlyLowerCase;
+
+		public boolean matchItem(Object item) {
+			String resource = item.toString();
+			if (onlyLowerCase && Character.isUpperCase(resource.charAt(0)))
+				return false;
+			return matches(resource);
+		}
+
+		public boolean equalsFilter(ItemsFilter filter) {
+			ResourceFilter resourceFilter = (ResourceFilter) filter;
+			if (onlyLowerCase != resourceFilter.onlyLowerCase)
+				return false;
+			return super.equalsFilter(filter);
+		}
+
+		public boolean isSubFilter(ItemsFilter filter) {
+			ResourceFilter resourceFilter = (ResourceFilter) filter;
+			if (onlyLowerCase == resourceFilter.onlyLowerCase)
+				return false;
+			return super.isSubFilter(filter);
+		}
+
+		public boolean isConsistentItem(Object item) {
+			return true;
+		}
+
+	}
+

Override createFilter() method:

+  	protected ItemsFilter createFilter() {
+		return new ResourceFilter();
+	}
+

The last step is to make sure that our dialog strings starts + with lower case. You should see a dialog similar to the one below: +
+

+ +

Adding an extra widget and context menu +entry

We will use the check-box and the menu action to indicate whether +to filter string starting with lower case character.

Extend dialog's content area by implementing createExtendedContentArea(Composite) + method:

+  	private Button checkButton;
+  	
+  	protected Control createExtendedContentArea(Composite parent) {
+		checkButton = new Button(parent, SWT.CHECK);
+		checkButton.setText("Only Lower Case Strings"); //$NON-NLS-1$
+		checkButton.addSelectionListener(new SelectionListener() {
+			public void widgetDefaultSelected(SelectionEvent e) {
+			}
+
+			public void widgetSelected(SelectionEvent e) {
+				if (onlyLowerCase != ((Button) e.widget).getSelection()) {
+				onlyLowerCase = ((Button) e.widget).getSelection();
+				applyFilter();
+				}
+			}
+		});
+		return checkButton;
+	}
+

Next, create new Action and add it to the menu by overriding fillViewMenu(IMenuManager). + Eg.:

+  	private class ShowOnlyLowerCaseStringsAction extends Action {
+
+		/**
+		 * Creates a new instance of the action.
+		 */
+		public ShowOnlyLowerCaseStringsAction() {
+			super("Only Lower Case String", //$NON-NLS-1$
+					IAction.AS_CHECK_BOX);
+		}
+
+		public void run() {
+			if (FilteredResourcesSelectionDialog.this.onlyLowerCase != isChecked()) {
+				FilteredResourcesSelectionDialog.this.onlyLowerCase = isChecked();
+				applyFilter();
+			}
+		}
+	}
+

 
+  	protected void fillViewMenu(IMenuManager menuManager) {
+		super.fillViewMenu(menuManager);
+		menuManager.add(showOnlyLowerCaseStringsAction);
+	}
+

The last step is to make sure that our dialog works properly. + You should see a dialog similar to the one below: +
+

+ + + Index: guide/dialogs_FilteredItemsSelectionDialog_example.htm =================================================================== RCS file: guide/dialogs_FilteredItemsSelectionDialog_example.htm diff -N guide/dialogs_FilteredItemsSelectionDialog_example.htm --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ guide/dialogs_FilteredItemsSelectionDialog_example.htm 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,152 @@ + + + + + + + + +Contributing a Search Dialog + + + +

Contributing a Search Dialog

We will now contribute a very basic search dialog. It's purpose +is to illustrate the steps needed to contribute a + FilteredItemsSelectionDialog implementation.

+ +

+
Create a class extending org.eclipse.ui.dialogs.FilteredItemsSelectionDialog. + Let's name it FilteredResourcesSelectionDialogExample.
+

Choose a source of resources which will be used during + filtering. In our example we will generate our own set of resources as + below:

+	private static ArrayList resources = new ArrayList();
+	
+	static {
+		
+		generateRescourcesTestCases('A', 'C', 8, ""); //$NON-NLS-1$
+		
+		generateRescourcesTestCases('a', 'c', 4, ""); //$NON-NLS-1$
+		
+	}
+	
+	private static void generateRescourcesTestCases(char startChar, char endChar, int length, String resource){
+		for (char ch = startChar; ch <= endChar; ch++) {
+			String res = resource + String.valueOf(ch);
+			if (length == res.length()) 
+				resources.add(res);
+			else if ((res.trim().length() % 2) == 0)
+					generateRescourcesTestCases(Character.toUpperCase((char)(startChar + 1)), Character.toUpperCase((char)(endChar + 1)), length, res);
+				else 
+					generateRescourcesTestCases(Character.toLowerCase((char)(startChar + 1)), Character.toLowerCase((char)(endChar + 1)), length, res);
+		}
+	}
+

Now, let's implement abstract methods from the FilteredItemsSelectionDialog + class.

createExtendedContentArea(Composite): The method + creates an extra content area located above the details. Due to the + fact that it is supposed to be the simplest example we will return + null for an extended area. This way there will be no extra field + added. Eg.:
```
+	protected Control createExtendedContentArea(Composite parent) {
+		return null;
+	}
+		
```

createFilter(): Creates a new instance of a filter. + In the simplest implementation you should also extend + FilteredItemsSelectionDialog#ItemsFilter and implement necessary + methods. Eg.:

+	protected ItemsFilter createFilter() {
+		return new ItemsFilter() {
+		
+			public boolean matchItem(Object item) {
+				return matches(item.toString());
+			}
+		
+			public boolean isConsistentItem(Object item) {
+				return true;
+			}
+		
+		};
+	}
+

+ fillContentProvider(FilteredItemsSelectionDialog.AbstractContentProvider, + FilteredItemsSelectionDialog.ItemsFilter, + org.eclipse.core.runtime.IProgressMonitor): Fills the content provider + with matching items. Eg.:

+	protected void fillContentProvider(AbstractContentProvider contentProvider,
+			ItemsFilter itemsFilter, IProgressMonitor progressMonitor)
+			throws CoreException {
+
+		progressMonitor.beginTask("Searching", resources.size()); //$NON-NLS-1$
+		
+		for (Iterator iter = resources.iterator(); iter.hasNext();) {
+			contentProvider.add(iter.next(), itemsFilter);
+			progressMonitor.worked(1);
+		}
+		
+		progressMonitor.done();
+		
+	}
+

getDialogSettings(): Returns settings of the dialog. + Returned object can't be null. Eg.:

+	protected IDialogSettings getDialogSettings() {
+		return new DialogSettings("TEST"); //$NON-NLS-1$
+	}
+

getElementName(Object): Returns a name for the given + object. It is used to check duplicates. Eg.:
```
+	public String getElementName(Object item) {
+		return item.toString();
+	}
+		
```

getItemsComparator(): Returns a comparator used to + sort items. Eg.:

+	protected Comparator getItemsComparator() {
+		return new Comparator() {
+		
+			public int compare(Object arg0, Object arg1) {
+				return arg0.toString().compareTo(arg1.toString());
+			}
+		
+		};
+	}
+

validateItem(Object): Validates an item. Eg.:

+	protected IStatus validateItem(Object item) {
+		return new Status(IStatus.OK, WorkbenchPlugin.PI_WORKBENCH, 0, "", null); //$NON-NLS-1$
+	}
+

+
The last step is to make sure our simple search dialog works. + You should see a dialog similar to the one below:
+
+

Search Dialog

+FilteredItemsSelectionDialog is a base dialog for searching +elements inside Eclipse. Since 3.3 version of Eclipse SDK it's used as +base dialog to resource and type search dialogs. It provides common look +and functionality for these two dialogs. +

Features of the new search dialogs: +

Multi-selection
Details field shows details of focused element (it can be seen + in multiple selection mode)
Uses JFace viewers, content and label providers
History of already selected elements
Supports for regExp pattern matching and camelCase matching. + To filter all elements it uses SearchPattern

+Contributing a Search Dialog

+ Advanced using of Search Dialog