Attachment 70384 Details for Bug 187678 – Proposition of doc 003

[patch] Proposition of doc 003

patch_187678_20070606_2.txt (text/plain), 15.78 KB, created by Krzysztof Michalski

on 2007-06-06 13:47:54 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: Krzysztof Michalski

Created: 2007-06-06 13:47:54 EDT

Size: 15.78 KB

patch

obsolete

>### 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 @@
> 	<topic label="Dialogs and wizards"  href="guide/dialogs.htm">
> 		<topic label="Standard dialogs" href="guide/dialogs_standard.htm" />
> 		<topic label="Application dialogs" href="guide/dialogs_applications.htm" />
>+		<topic label="Search Dialog" href="guide/dialogs_FilteredItemsSelectionDialog.htm">
>+			<topic label="Contributing a Search Dialog" href="guide/dialogs_FilteredItemsSelectionDialog_example.htm" />
>+			<topic label="Advanced using of Search Dialog" href="guide/dialogs_FilteredItemsSelectionDialog_example_advanced.htm" />
>+		</topic>
> 		<topic label="Dialog settings" href="guide/dialogs_settings.htm" />
> 		<topic label="Wizards" href="guide/dialogs_wizards.htm" />
> 		<topic label="Workbench wizard extension points" href="guide/dialogs_wizards_extensions.htm" >
>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 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<html>
>+<head>
>+<meta name="copyright"
>+	content="Copyright (c) IBM Corporation and others 2000, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
>+<meta http-equiv="Content-Style-Type" content="text/css">
>+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1"
>+	type="text/css">
>+<script language="JavaScript"
>+	src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
>+<title>Contributing a Search Dialog</title>
>+</head>
>+<body>
>+
>+<h2>Advanced use of the Search Dialog</h2>
>+
>+This section will present present how to extend basic functionality of
>+our example Search Dialog.
>+<br>
>+
>+<a href="#history">Add selected items history</a>
>+<br />
>+<a href="#filter">Extend filter functionality</a>
>+<br />
>+<a href="#checkbox">Extra check-box</a>
>+<br />
>+
>+
>+
>+<h3><a name="history">Adding history of selected items</a></h3>
>+<ul>
>+	<li>To achieve that, firstly we extend <em>FilteredItemsSelectionDialog#SelectionHistory</em>
>+	and implement abstract methods for saving and loading objects. Eg.:</li>
>+	<pre>
>+  	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$
>+		}
>+
>+	}
>+  </pre>
>+
>+	<li>Next we should set our implementation of SelectionHistory on
>+	dialog. <pre>
>+  	setSelectionHistory(new ResourceSelectionHistory());
>+  </pre></li>
>+	<li>Finally, we make sure that our dialog works properly. You
>+	should see a dialog similar to the one below:
>+	<p align="center"><img
>+		src="images/filteredResourcesSelectionDialogExampleAdvance1.png"
>+		border="0" alt="Image of a simple search dialog"></p>
>+	</li>
>+</ul>
>+
>+
>+<h3><a name="filter">Extend filter functionality</a></h3>
>+<p>Especially we want to filter all strings which start with lower
>+case character.</p>
>+<ul>
>+	<li>Extend <em>FilteredItemsSelectionDialog#ItemsFilter</em>,
>+	implement necessary abstract methods and override <em>equalsFilter(ItemsFilter)</em>
>+	and <em>isSubFilter(ItemsFilter)</em>. 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.: <pre>
>+  	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;
>+		}
>+
>+	}
>+	</pre></li>
>+	<li>Override <i>createFilter()</i> method: <pre>
>+  	protected ItemsFilter createFilter() {
>+		return new ResourceFilter();
>+	}
>+  </pre></li>
>+	<li>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:
>+	<p align="center"><img
>+		src="images/filteredResourcesSelectionDialogExampleAdvance2.png"
>+		border="0" alt="Image of a simple search dialog"></p>
>+	</li>
>+</ul>
>+
>+<h3><a name="checkbox">Adding an extra widget and context menu
>+entry</a></h3>
>+<p>We will use the check-box and the menu action to indicate whether
>+to filter string starting with lower case character.</p>
>+<ul>
>+	<li>Extend dialog's content area by implementing <em>createExtendedContentArea(Composite)</em>
>+	method: <pre>
>+  	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;
>+	}
>+  	</pre></li>
>+	<li>Next, create new Action and add it to the menu by overriding <em>fillViewMenu(IMenuManager)</em>.
>+	Eg.: <pre>
>+  	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();
>+			}
>+		}
>+	}
>+  </pre> <pre> 
>+  	protected void fillViewMenu(IMenuManager menuManager) {
>+		super.fillViewMenu(menuManager);
>+		menuManager.add(showOnlyLowerCaseStringsAction);
>+	}
>+  </pre></li>
>+
>+	<li>The last step is to make sure that our dialog works properly.
>+	You should see a dialog similar to the one below:
>+	<p align="center"><img
>+		src="images/filteredResourcesSelectionDialogExampleAdvance3.png"
>+		border="0" alt="Image of a simple search dialog"></p>
>+	</li>
>+
>+</ul>
>+
>+</body>
>+</html>
>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 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<html>
>+<head>
>+<meta name="copyright"
>+	content="Copyright (c) IBM Corporation and others 2000, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
>+<meta http-equiv="Content-Style-Type" content="text/css">
>+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1"
>+	type="text/css">
>+<script language="JavaScript"
>+	src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
>+<title>Contributing a Search Dialog</title>
>+</head>
>+<body>
>+
>+<h2>Contributing a Search Dialog</h2>
>+<p>We will now contribute a very basic search dialog. It's purpose
>+is to illustrate the steps needed to contribute a <a
>+	href="../reference/api/org/eclipse/ui/dialogs/FilteredItemsSelectionDialog.html">
>+<b> FilteredItemsSelectionDialog</b></a> implementation.</p>
>+
>+<ol>
>+	<li>
>+	<p>Create a class extending <em>org.eclipse.ui.dialogs.FilteredItemsSelectionDialog</em>.
>+	Let's name it <em>FilteredResourcesSelectionDialogExample</em>.</p>
>+	</li>
>+	<li>
>+	<p>Choose a source of resources which will be used during
>+	filtering. In our example we will generate our own set of resources as
>+	below:</p>
>+	<pre>
>+	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);
>+		}
>+	}
>+		</pre></li>
>+	<li>
>+	<p>Now, let's implement abstract methods from the <em>FilteredItemsSelectionDialog</em>
>+	class.</p>
>+	<ul>
>+		<li><em>createExtendedContentArea(Composite)</em>: 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.: <pre>
>+	protected Control createExtendedContentArea(Composite parent) {
>+		return null;
>+	}
>+		</pre></li>
>+
>+		<li><em>createFilter()</em>: Creates a new instance of a filter.
>+		In the simplest implementation you should also extend <em>
>+		FilteredItemsSelectionDialog#ItemsFilter </em> and implement necessary
>+		methods. Eg.: <pre>
>+	protected ItemsFilter createFilter() {
>+		return new ItemsFilter() {
>+		
>+			public boolean matchItem(Object item) {
>+				return matches(item.toString());
>+			}
>+		
>+			public boolean isConsistentItem(Object item) {
>+				return true;
>+			}
>+		
>+		};
>+	}
>+		</pre></li>
>+
>+		<li><em>
>+		fillContentProvider(FilteredItemsSelectionDialog.AbstractContentProvider,
>+		FilteredItemsSelectionDialog.ItemsFilter,
>+		org.eclipse.core.runtime.IProgressMonitor)</em>: Fills the content provider
>+		with matching items. Eg.: <pre>
>+	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();
>+		
>+	}
>+		</pre></li>
>+
>+		<li><em>getDialogSettings()</em>: Returns settings of the dialog.
>+		Returned object can't be null. Eg.:<pre>
>+	protected IDialogSettings getDialogSettings() {
>+		return new DialogSettings("TEST"); //$NON-NLS-1$
>+	}
>+		</pre></li>
>+
>+		<li><em>getElementName(Object)</em>: Returns a name for the given
>+		object. It is used to check duplicates. Eg.: <pre>
>+	public String getElementName(Object item) {
>+		return item.toString();
>+	}
>+		</pre></li>
>+
>+		<li><em>getItemsComparator()</em>: Returns a comparator used to
>+		sort items. Eg.: <pre>
>+	protected Comparator getItemsComparator() {
>+		return new Comparator() {
>+		
>+			public int compare(Object arg0, Object arg1) {
>+				return arg0.toString().compareTo(arg1.toString());
>+			}
>+		
>+		};
>+	}
>+		</pre></li>
>+
>+		<li><em>validateItem(Object)</em>: Validates an item. Eg.: <pre>
>+	protected IStatus validateItem(Object item) {
>+		return new Status(IStatus.OK, WorkbenchPlugin.PI_WORKBENCH, 0, "", null); //$NON-NLS-1$
>+	}
>+		</pre></li>
>+
>+	</ul>
>+	</li>
>+
>+	<li>
>+	<p>The last step is to make sure our simple search dialog works.
>+	You should see a dialog similar to the one below:</p>
>+	<p align="center"><img
>+		src="images/filteredResourcesSelectionDialogExample.png" border="0"
>+		alt="Screen shot of a simple search dialog"></p>
>+	</li>
>+</body>
>+</html>
>Index: guide/dialogs_FilteredItemsSelectionDialog.htm
>===================================================================
>RCS file: guide/dialogs_FilteredItemsSelectionDialog.htm
>diff -N guide/dialogs_FilteredItemsSelectionDialog.htm
>--- /dev/null	1 Jan 1970 00:00:00 -0000
>+++ guide/dialogs_FilteredItemsSelectionDialog.htm	1 Jan 1970 00:00:00 -0000
>@@ -0,0 +1,46 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<HTML>
>+<HEAD>
>+
>+<meta name="copyright"
>+	content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+
>+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
>+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
>+
>+<link rel="stylesheet" type="text/css" HREF="../book.css">
>+<TITLE>Search Dialog</TITLE>
>+
>+
>+</HEAD>
>+<BODY BGCOLOR="#ffffff">
>+
>+<h2>Search Dialog</h2>
>+<P><a
>+	href="../reference/api/org/eclipse/ui/dialogs/FilteredItemsSelectionDialog.html">
>+<b>FilteredItemsSelectionDialog</b></a> 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.
>+<P>Features of the new search dialogs:
>+<ul>
>+	<li>Multi-selection</li>
>+	<li>Details field shows details of focused element (it can be seen
>+	in multiple selection mode)</li>
>+	<li>Uses JFace viewers, content and label providers</li>
>+	<li>History of already selected elements</li>
>+	<li>Supports for regExp pattern matching and camelCase matching.
>+	To filter all elements it uses <a
>+		href="../reference/api/org/eclipse/ui/dialogs/SearchPattern.html"><b>SearchPattern</b></a></li>
>+</ul>
>+
>+For more information see:
>+<br />
>+<a href="dialogs_FilteredItemsSelectionDialog_example.htm"> <b>
>+Contributing a Search Dialog</b></a>
>+<br />
>+<a href="dialogs_FilteredItemsSelectionDialog_example_advaned.htm">
>+<b> Advanced using of Search Dialog</b></a>
>+
>+</BODY>
>+</HTML>

Actions: View | Diff

Attachments on bug 187678: 69680 | 70340 | 70341 | 70342 | 70343 | 70344 | 70384 | 70550 | 70612 | 70614 | 70671 | 70672 | 70673 | 70674 | 70710 | 70713 | 70717 | 70840 | 70858 | 70888 | 70894 | 70986 | 70992