This page lists SEAL developers' answers to Eclipse-related, frequently asked questions. Each answer has been verified by its author.
Note: If you post a link, please provide a short summary.
General
Terminology
Platform
- #Where can I get more information about the Eclipse Java compiler?
- #Why does Eclipse complain about an already running instance?
- #How does Eclipse load classes?
Plugin Development
Configuration
- #What information do MANIFEST.MF and plugin.xml contain?
- #What happens if I do NOT check "Activate this plug-in when one of its classes is loaded"?
- #How do I create a plugin project that uses an existing SEAL plugin?
- #How do I add a third-party library to SEAL?
- #How do I create a product?
Implementation
- #How can I launch the Eclipse web browser from my plugin?
- #How can my view save data via Eclipse main menu (FILE => Save or Save As...)?
- #How can I notify Eclipse about the change in "dirty"-ness of my WorkbenchPart?
- #What happens when a view is closed?
- #How do I access a file in the plugin programmatically?
- #How can I manipulate the main workbench menu at runtime?
- #How do I open an error dialog?
- #How do I set a retargetable action?
Deployment
- #What should I know about my plugin build configuration?
- #In build.properties, I specified to build a JAR file from my plugin sources. When I deploy my plugin, a class can not be found. What am I doing wrong?
- #How do I generate Javadoc with links to APIs on the web?
- #Should I deploy my pure Java plugin as a JAR file or as a directory?
SWT
- #How can I correctly change the background/foreground color of a button?
- #What should I know about SWT and threads?
- #How do I create a scrollable widget?
Misc. & Fun
- #What are the Eclipse runtime options?
- #How does Eclipse generate the ANT build script (aka build.xml)?
- #Where can I find a copy of the OSGi specification?
- #How can I add functionality to the Eclipse platform?
General
Why does this FAQ exist?
Answered by Sergei Chevtsov, 06-14-2007
There are three reasons for why this FAQ exists:
1) It contains SEAL-specific information.
2) While it is true that you can find all answers about Eclipse on the internet, we found out that they are usually phrased in a very general way and require (too) much time to grasp.
3) Many Eclipse-related questions yield various answers of seemingly unrelated nature. In this FAQ, we only want to give proven and tested information.
Terminology
When should I create a feature for my plugin?
Answered by Sergei Chevtsov, 06-08-2007
If you think that your plug-in is useful on its own, e.g. to the developers of our sister project CSS, you should create a feature for it.
When should I build a source feature/plugin?
Link verified by Sergei Chevtsov, 06-11-2007
A source feature is useful for delivering source code to a developer via Eclipse infrastructure.
Platform
Where can I get more information about the Eclipse Java compiler?
Answered by Sergei Chevtsov, 06-08-2007
http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.jdt.doc.isv/guide/jdt_api_compile.htm
Eclipse uses its own Java compiler that is more flexible than Sun's.
Why does Eclipse complain about an already running instance?
Answered by Sergei Chevtsov, 07-12-2007
(Let's assume that you actually don't have a running instance of Eclipse)
Sometimes when Eclipse exits, it doesn't delete the .metadata/.lock file in your workspace. If you are sure what you're doing, rm it manually.
How does Eclipse load classes?
Answered by Sergei Chevtsov, 08-15-2007
Eclipse utilizes many of its own classloaders.
http://www.eclipsezone.com/articles/eclipse-vms/
Plugin Development
What information do MANIFEST.MF and plugin.xml contain?
Link verified by Sergei Chevtsov, 06-11-2007
http://www-128.ibm.com/developerworks/opensource/library/os-ecl-osgi/#N10091
MANIFEST.MF contains the description of the plugin.
plugin.xml defines extensions that the plugin might contribute.
What happens if I do NOT check "Activate this plug-in when one of its classes is loaded"?
Link verified by Sergei Chevtsov, 08-16-2007
Your MANIFEST.MF file will NOT contain the element "Eclipse-LazyStart: true", and the plugin will be activated when the Eclipse platform starts.
How do I create a plugin project that uses an existing SEAL plugin?
Answered by Sergei Chevtsov, 06-08-2007
1. Setup SEAL target. http://www.slac.stanford.edu/grp/lcls/controls/docs/physics/seal/sealdev.html#target
2. Create a new plugin project in your workspace.
3. Open the MANIFEST.MF file from the META-INF directory.
4. Choose the DEPENDENCIES tab at the bottom of your editor.
5. Click on ADD... in the "Required Plug-ins" section and select the ID of the desired SEAL plug-in.
How do I add a third-party library to SEAL?
Answered by Sergei Chevtsov, 06-08-2007
1. Check out the project "external" from our CVS.
2. Copy your JAR file and, if applicable, the corresponding ZIP file with source code to the top directory of "external".
Some guidelines about naming source ZIP files: http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/preference_pages/source_code_locations.htm
3. Open the MANIFEST.MF file from the META-INF directory of "external".
4. Choose the RUNTIME tab at the bottom of your editor.
5. Click on ADD... in the "Classpath" section and select the new JAR file.
6. Click on ADD.. in the "Exported Packages" section and select all desired packages.
7. Optional: in the build path configuration dialog of the project, attach source from the ZIP file and specify Javadoc location of the library
8. Commit "external" to CVS.
How do I create a product?
Answered by Sergei Chevtsov, 07-30-2007
http://wiki.eclipse.org/FAQ_How_do_I_create_an_Eclipse_product%3F
We recommend that you skip step 2 and press "NEW..." in the overview section of your product file , i.e.:
1. Create a plugin for your product (File > New > Other > Plug-in Development > Plug-in Project).
2. Create a product configuration file (File > New > Other > Plugin Development > Product Configuration). Specify the product id as defined in your plugin manifest. On the "Configuration" tab, list all the plugins belonging to the product. You can also list branding information like the splash screen, icons, the name of your executable, etc.
3. Use the Product export wizard (link from the product editor, or under File > Export) to build, package, and deploy your product.
4. Launch the executable created by the product export (or run plain it with the -product argument to refer to your product).
How can I launch the Eclipse web browser from my plugin?
Link verified by Sergei Chevtsov, 06-08-2007
IWorkbenchBrowserSupport support = PlatformUI.getWorkbench().getBrowserSupport();
IWebBrowser browser = support.createBrowser("someId");
browser.openURL(new URL("http://www.eclipse.org"));
How can my view save data via Eclipse main menu (FILE => Save or Save As...)?
Answered by Sergei Chevtsov, 06-13-2007
Your view must implement ISaveablePart.
Note #1: An editor already implements ISaveablePart.
Note #2: I am not saying that this always is the correct way to save data from a view.
How can I notify Eclipse about the change in "dirty"-ness of my WorkbenchPart?
Answered by Sergei Chevtsov, 07-11-2007
0. Make sure that your WorkbenchPart implements ISaveablePart.
1. Call WorkbenchPart.firePropertyChange(ISaveablePart.PROP_DIRTY).
What happens when a view is closed?
Answered by Sergei Chevtsov, 06-13-2007
http://www.eclipse.org/articles/viewArticle/ViewArticle2.html
When the view is closed the lifecycle is completed.
1. The parent Composite passed to createPartControl is disposed. This children are also implicitly disposed. If you wish to run any code at this time, you must hook the control dispose event.
2. The IViewPart.dispose method is called to terminate the part lifecycle. This is the last method which the workbench will call on the part. It is an ideal time to release any fonts, images, etc.
Note: Although the article is old, this behavior is still valid.
How do I access a file in the plugin programmatically?
Answered by Sergei Chevtsov, 06-14-2007
Basically, use FileLocator .
Similar methods in other classes are deprecated and call FileLocator anyway.
To get a Bundle instance associated with the desired plugin, use ((Plugin)myPlugin).getBundle().
If you can't access the instance of the desired Plugin, then (in addition to yelling at the plugin developer 
) use Platform.getBundle(symbolicName) where "symbolicName" is specified in the plugin's MANIFEST.MF file.
Finally, use new Path(myPath), where "myPath" is relative to the plugin's top directory, to get an instance of IPath.
How can I manipulate the main workbench menu at runtime?
Answered by Sergei Chevtsov, 06-14-2007
http://wiki.eclipse.org/index.php/Menu_Contributions
Not possible yet, but should be in Eclipse 3.3.
How do I open an error dialog?
Answered by Sergei Chevtsov, 07-25-2007
Use ErrorDialog, e.g.:
ErrorDialog.openError(shell, title, null, new Status(IStatus.ERROR, pluginId, IStatus.OK, localizedMessage, exception));
Note: localizedMessage must not be null!
How do I set a retargetable action?
Answered by Sergei Chevtsov, 10-22-2007
Use getViewSite().getActionBars().setGlobalActionHandler(IAction).
What should I know about my plugin build configuration?
Answered by Sergei Chevtsov, 09-06-2007
Pay special attention to where your class files will land.
In build.properties, I specified to build a JAR file from my plugin sources. When I deploy my plugin, a class can not be found. What am I doing wrong?
Answered by Sergei Chevtsov, 07-11-2007
You must add your JAR file to "Bundle-Classpath" in MANIFEST.MF.
Open MANIFEST.MF. Select the RUNTIME tab. Press NEW... button in the CLASSPATH section and type the name of your (future) library.
As of July 2007, we recommend that your plugin stays free of JAR files. If you have an external jar, put it into "edu.stanford.slac.external" and make that plugin required by your plugin.
How do I generate Javadoc with links to APIs on the web?
Answered by Sergei Chevtsov, 07-20-2007
0. If your Javadoc has already been generated using this method:
- 1. Remove existing Javadoc files.
- 2. Go to step 4.
1. Use the Export Wizard to generate Javadoc for your classes. Check "Save the settings as an Ant script" on the last page.
Note: The generated Ant script will have hard-coded classpath, i.e. if you have a required plugin checked out into your workspace, the script won't work next time, unless you check that plugin out, too. To avoid headache, we advise that you close all projects, except the one that you generate JavaDoc for.
2. Open javadoc.xml.
3. For each external API, add the following line as child of <javadoc> element:
<link href="url to the API directory on the web" />
Some of the most common URLs are:
JDK => http://java.sun.com/j2se/1.5.0/docs/api/
Eclipse => http://help.eclipse.org/help33/nftopic/org.eclipse.platform.doc.isv/reference/api/
SEAL plugin => http://www.slac.stanford.edu/grp/lcls/controls/docs/physics/sealPLUGIN_NAME/javadoc/
4. Right click javadoc.xml => "Run As" => "Ant Build".
5. Don't use the Export Wizard to generate Javadoc again.
Should I deploy my pure Java plugin as a JAR file or as a directory?
Answered by Sergei Chevtsov, 07-11-2007
First, you need to know that your plugin will *run* either way, although Eclipse folks claim that performance might differ (surprisingly, JAR-ed plugins are supposed to be better =>
http://www.eclipsezone.com/eclipse/forums/m91980917.html#91980917).
If that's all your plugin is intended for, the choice seems to be entirely up to you.
However, some plugins can be used by other plugins; such plugins expose packages to the clients. You must create a JAR file for a plugin that exposes packages, so that Eclipse's Plug-in Development Environment can locate the exported classes.
Note: if your plugin uses an external library, put it into edu.stanford.slac.external plugin and make that plugin required by your plugin.
SWT
How can I correctly change the background/foreground color of a button?
Answered by Sergei Chevtsov, 06-08-2007
Surprisingly, you can't.
What should I know about SWT and threads?
Answered by Sergei Chevtsov, 06-13-2007
http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/swt_threading.htm
You can only access SWT widgets from a UI thread.
How do I create a scrollable widget?
Answered by Sergei Chevtsov, 06-14-2007
Try specifying the following style bits in the constructor of your widget: SWT.H_SCROLL and/or SWT.V_SCROLL.
If it doesn't work, then you could use the ScrolledComposite class, e.g. =>
http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet5.java?view=co
Misc. & Fun
What are the Eclipse runtime options?
Link verified by Sergei Chevtsov, 07-11-2007
Some of the most useful options are: clean, console, debug (note: it actually enables tracing only), nl, noSplash, password, vm, vmArgs.
How does Eclipse generate the ANT build script (aka build.xml)?
Link verified by Sergei Chevtsov, 06-11-2007
It uses build.properties from your plugin's top directory.
Where can I find a copy of the OSGi specification?
Answered by Sergei Chevtsov, 06-11-2007
Since you have to register to download it from http://www2.osgi.org/Specifications/HomePage, here is a local copy: r4.core.pdf
How can I add functionality to the Eclipse platform?
Answered by Sergei Chevtsov, 06-11-2007
Use adaptor hooks.
http://wiki.eclipse.org/index.php/Adaptor_Hooks
The space below is intentionally left blank.