Migrating the FAQ and all sub-pages to mark-down

Author: vogella

docs/FAQ/FAQ_Actions,_commands,_operations,_jobs:_What_does_it_all_mean.md

@@ -0,0 +1,44 @@
+
+
+FAQ Actions, commands, operations, jobs: What does it all mean?
+===============================================================
+
+Many terms are thrown around in Eclipse for units of functionality or behavior: runnables, actions, commands, operations, and jobs, among others. Here is a high- level view of the terms to help you keep things straight.
+
+Contents
+--------
+
+*   [1 Actions](#Actions)
+*   [2 Commands](#Commands)
+*   [3 Operations](#Operations)
+*   [4 Jobs](#Jobs)
+*   [5 See Also](#See-Also)
+
+Actions
+-------
+
+As a plug-in writer, you will be interested mostly in _actions_. When a toolbar button or a menu item is clicked or when a defined key sequence is invoked, the run method of some action is invoked. Actions generally do not care about how or when they are invoked, although they often require extra context information, such as the current selection or view. Actions that are contributed to the workbench declaratively in plugin.xml defer the actual work to an _action delegate_.
+
+_Note: When using action delegates, keep in mind that your implementing classes must provide a no argument constructor for RCP to hook the two together._
+
+Commands
+--------
+
+_Commands_ are a meta-level glue that the platform uses to manage and organize actions. As a plug-in writer, you will never write code for a command directly, but you will use the org.eclipse.ui.commands extension point to define key bindings for your actions and to group your actions into configurations and contexts.
+
+Operations
+----------
+
+_Operations_ aren't an official part of the workbench API, but the term tends to be used for a long-running unit of behavior. Any work that might take a second or more should really be inside an operation. The official designation for operations in the API is IRunnableWithProgress, but the term _operation_ tends to be used in its place because it is easier to say and remember. Operations are executed within an IRunnableContext. The context manages the execution of the operation in a non-UI thread so that the UI stays alive and painting. The context provides progress feedback to the user and support for cancellation.
+
+Jobs
+----
+
+_Jobs_, introduced in Eclipse 3.0, are operations that run in the background. The user is typically prevented from doing anything while an operation is running but is free to continue working when a job is running. Operations and jobs belong together, but jobs needed to live at a lower level in the plug-in architecture to make them usable by non-UI components.
+
+See Also
+--------
+
+*   [FAQ Does the platform have support for concurrency?](./FAQ_Does_the_platform_have_support_for_concurrency.md "FAQ Does the platform have support for concurrency?")
+*   [FAQ What are IWorkspaceRunnable, IRunnableWithProgress, and WorkspaceModifyOperation?](./FAQ_What_are_IWorkspaceRunnable,_IRunnableWithProgress,_and_WorkspaceModifyOperation.md "FAQ What are IWorkspaceRunnable, IRunnableWithProgress, and WorkspaceModifyOperation?")
+

docs/FAQ/FAQ_Are_there_any_special_Eclipse_UI_guidelines.md

@@ -0,0 +1,19 @@
+
+
+FAQ Are there any special Eclipse UI guidelines?
+================================================
+
+  
+
+  
+A wealth of Eclipse UI guidelines exists. Mentioning any in this single FAQ would seem to do no justice to Nick Edgar, Kevin Haaland, Jin Li, and Kimberley Peter. Please refer to their online Eclipse article Eclipse User Interface Guidelines. In their seminal work, they brush on such topics as icon sizes and color palettes, wizards, editors, dialogs, commands, views, perspectives, windows, properties, widgets, navigators, tasks, preferences, outlines, properties, bookmarks, text editors, the flat-look design, accelerators, best practices, and a checklist for developers.
+
+In fact, the 100-page article is a great source of inspiration for any plug-in developer. Study it before you create any Eclipse plug-in with a visual representation to avoid mistakes made by others and to learn from the experts how to design high-quality UI designs.
+
+See Also:
+---------
+
+Online article on UI Guidelines ([http://eclipse.org/articles](http://eclipse.org/articles)). 
+
+There is a partly obsolete article with eclipse [2.1 UI Guidelines](https://www.eclipse.org/articles/Article-UI-Guidelines/Index.html)
+

docs/FAQ/FAQ_Are_there_any_visual_composition_editors_available_for_SWT.md

@@ -0,0 +1,36 @@
+
+
+FAQ Are there any visual composition editors available for SWT?
+===============================================================
+
+Several free and commercial products provide visual composition editors, or GUI builders, for SWT. These tools are especially appealing to people who are not yet skilled in all the intricacies of the SWT layout mechanisms and do not yet know what kinds of widgets are available to choose from.
+
+After doing an informal poll, we discovered that none of the respondents in the Eclipse development team uses a visual builder to implement Eclipse. The UI for Eclipse is written manually in SWT, using an additional UI framework called JFace to take care of some of the repetitive aspects of writing UIs. Furthermore, when defining a new dialog, the developers often use the Monkey see, monkey do rule: They first find one that is close to the intended result; then, the new UI is cloned from the inspiration source and modified until it fits the needs of the new application.
+
+With the growing popularity of SWT, more and more developers want to prototype and develop user interfaces with SWT. Visual builders help less experienced developers by eliminating most of the guesswork from the UI design labor. Widgets can be selected from a panel, and attributes can be chosen and assigned values from a limited set of options. The most successful builders offer fully synchronized views of the UI being developed and the generated source code to implement the UI.
+
+Visual builders have been a long time coming for SWT, but a number of free and commercial GUI builders are finally available.
+
+Free Plug-ins
+-------------
+
+*   [_The Eclipse Visual Editor Project_](https://wiki.eclipse.org/Visual_Editor_Project). The goal of this Eclipse project is to build a framework for creating Eclipse-based GUI builders. This project follows the general Eclipse philosophy of creating a platform- and language-independent framework, with language- and platform-specific layers on top. This project provides GUI builders for SWT/RCP and Swing applications.
+
+*   _V4ALL Assisi GUI-Builder_. This SourceForge GUI builder project targets both SWT and Swing. So far, it is the work of a single developer, and there does not appear to be much activity on it.
+
+*   [_JellySWT_](http://jakarta.apache.org/commons/jelly/jellyswt.html). Jelly is a scripting engine that uses XML as its scripting language. The goal of JellySWT is to allow you to describe a UI by using Jelly script and then have it generate the Java code automatically. The idea is that it takes care of the tedious layout code for you. This isn't really a visual composition editor, but it is a GUI builder of sorts.
+
+Commercial Plug-ins
+-------------------
+
+*   [_SWT designer_](http://www.swt-designer.com). This commercial plug-in to Eclipse, which targets only SWT, is fairly new as a commercial product but is based on an open source project that has been around for a while and has a strong following.
+
+*   [_SWT GUI Builder_](http://www.swtguibuilder.com). This commercial plug-in provides a visual editor for SWT only. The company also sells a product called Swing2SWT that ports Swing applications to SWT.
+
+*   [_Jigloo GUI Builder_](http://www.cloudgarden.com/jigloo). This fairly new GUI builder for both SWT and Swing is a commercial product, but a free version is licensed for noncommercial use only.
+
+See Also:
+---------
+
+*   [FAQ What open source projects are based on Eclipse?](./FAQ_What_open_source_projects_are_based_on_Eclipse.md "FAQ What open source projects are based on Eclipse?")
+

docs/FAQ/FAQ_Can_I_activate_my_plug-in_when_the_workbench_starts.md

@@ -0,0 +1,16 @@
+
+
+FAQ Can I activate my plug-in when the workbench starts?
+========================================================
+
+You shouldn't. The principle of lazy plug-in activation is very important in a platform with an open-ended set of plug-ins. All plug-in writers like to think that their plug-in are important enough to contravene this rule, but when an Eclipse install can contain thousands of plug-ins, you have to keep the big picture in mind. Having said that, you can use a mechanism to activate your plug-in when the workbench starts. In special circumstances or for hobby plug-ins that aren't meant for wider use, you can use the org.eclipse.ui.startup extension point to activate your plug-in as soon as the workbench starts up.
+
+The startup extension point allows you to specify a class that implements the IStartup interface. If you omit the class attribute from the extension, your Plugin subclass will be used and therefore must implement IStartup. This class will be loaded in a background thread after the workbench starts, and its earlyStartup method will be run. As always, however, your Plugin class will be loaded first, and its startup method will be called before any other classes are loaded. The earlyStartup method essentially lets you distinguish eager activation from normal plug-in activation.
+
+Note that even when this extension point is used, the user can always veto the eager activation from the **Workbench > Startup** preference page. This illustrates the general Eclipse principle that the user is always the final arbiter when conflicting demands on the platform are made. This also means that you can't rely on eager activation in a production environment. You will always need a fallback strategy when the user decides that your plug-in isn't as important as you thought it was.
+
+See Also:
+---------
+
+*   [FAQ When does a plug-in get started?](./FAQ_When_does_a_plug-in_get_started.md "FAQ When does a plug-in get started?")
+

docs/FAQ/FAQ_Can_I_add_icons_declared_by_my_plugin.md

@@ -0,0 +1,33 @@
+
+
+FAQ Can I add icons declared by my plugin.xml in the runtime JAR?
+=================================================================
+
+No. Statically declared plug-in icons are not meant to be in the runtime JAR because Eclipse wants to load plug-ins lazily. In other words, during loading of the platform, the platform loader reads only the plugin.xml file and will use the icons that are declared there. Only when the plug-in is really needed is the JAR opened; the class loader starts loading classes, and the plug-in is activated.
+
+The structure of a plug-in roughly looks like this:
+
+     plugin.xml         // used by platform loader
+     icons/
+         delete.gif     // icons used in the toolbar, and so on.
+         create.jpg
+     code.jar         // jar (class files + resources)
+
+Plug-in activation is a process that requires considerable memory and central processing unit (CPU) cycles. To speed up load time of the platform, opening the runtime JAR is avoided for as long as possible.
+
+  
+
+Of course, images included in a runtime JAR can be used by plug-in code using standard Java resource-loading techniques, such as getResource on a given Java class or by using a class loader.
+
+  
+
+  
+
+See Also:
+---------
+
+[FAQ\_How\_do\_I\_add\_images\_and\_other\_resources\_to\_a\_runtime\_JAR_file?](./FAQ_How_do_I_add_images_and_other_resources_to_a_runtime_JAR_file.md "FAQ How do I add images and other resources to a runtime JAR file?")
+
+  
+[FAQ\_When\_does\_a\_plug-in\_get\_started?](./FAQ_When_does_a_plug-in_get_started.md "FAQ When does a plug-in get started?")
+

docs/FAQ/FAQ_Can_I_create_an_application_that_doesn't_have_a_data_location.md

@@ -0,0 +1,24 @@
+
+
+FAQ Can I create an application that doesn't have a data location?
+==================================================================
+
+  
+
+  
+
+Yes you can, if you are very careful. In Eclipse 3.0, the base Eclipse runtime was designed to be able to run without any data location at all. If you have a carefully crafted RCP application, you might be able to get away with not having a data location. To launch an Eclipse application with no data location at all, use the special -data @none command-line argument:
+
+   eclipse -data @none -application your.app.id
+
+If you do this, an error will occur if any plug-in attempts to access the platform instance location, including the plug-in metadata location. In other words, this configuration makes sense only for a tightly controlled application in which you are absolutely certain that the instance location will never be used.
+
+One advantage of this approach is that multiple instances of your application can run simultaneously without forcing the user to pick a different data location for each one. For most RCP applications, this type of configuration is too constrictive. A better approach for applications that don't need to store any interesting state is to pick a random location in a scratch directory, such as the directory provided by System.getProperty("java.io.tmpdir"). This will ensure that your application does not fail if a plug-in is installed that does want to access the instance location.
+
+  
+
+See Also:
+---------
+
+[FAQ\_How\_do\_I\_specify\_where\_application\_data\_is_stored?](./FAQ_How_do_I_specify_where_application_data_is_stored.md "FAQ How do I specify where application data is stored?")
+

docs/FAQ/FAQ_Can_I_create_an_application_that_doesn't_have_views_or_editors.md

@@ -0,0 +1,50 @@
+
+
+FAQ Can I create an application that doesn't have views or editors?
+===================================================================
+
+When you create an RCP application using a workbench advisor, you are still constrained to using the standard Eclipse UI constructs of views, editors, and perspectives. If you have very different UI requirements but still want to use the plug-in infrastructure, you can always create an application built on only SWT and JFace. This has been possible since the first release of Eclipse as SWT and JFace have no other dependencies outside the base runtime plug-in. JFace provides a basic ApplicationWindow with optional menus, toolbar, and status line.
+
+  
+Configuration of a JFace application works through subclassing rather than plugging in an advisor. Your application needs to subclass the JFace class called ApplicationWindow and override the various methods that are used to customize the appearance and behavior of the window. The following is a simple JFace application window from the FAQ examples plug-in. As with other applications, you begin by creating a class that implements IPlatformRunnable:
+
+   public class JFaceApp implements IPlatformRunnable {
+      public Object run(Object args) throws Exception {
+         Display display = new Display();
+         JFaceAppWindow window = new JFaceAppWindow();
+         window.open();
+         Shell shell = window.getShell();
+         while (!shell.isDisposed()) {
+            if (!display.readAndDispatch())
+               display.sleep();
+         }
+         return EXIT_OK;
+      }
+   }
+
+JFaceAppWindow is a subclass of the framework class ApplicationWindow. The subclass creates a simple window with a menu bar, a status line, and a single button inside the main window that is used to exit the application (Figure 16.2).
+
+Complete source for the class can be found in the FAQ Examples plug-in, but here is the basic structure:
+
+   public class JFaceAppWindow extends ApplicationWindow {
+      public JFaceAppWindow() {
+         super(null);
+         addMenuBar();
+         addStatusLine();
+      }
+      protected void configureShell(Shell shell) {
+         super.configureShell(shell);
+         shell.setText("Simple JFace Application");
+      }
+      ...
+   }
+
+The subclass also needs to override the createContents method to create the SWT widgets that will appear in the window's main content area. Override createMenuManager to populate the window's menus, createToolBarManager to populate the toolbar, and so on. If you browse through the ApplicationWindow class, you will see that many other hook methods allow your application to customize the appearance of the top-level window.
+
+  
+
+See Also:
+---------
+
+[FAQ\_How\_do\_I\_build\_menus\_and\_toolbars\_programmatically?](./FAQ_How_do_I_build_menus_and_toolbars_programmatically.md "FAQ How do I build menus and toolbars programmatically?")
+

docs/FAQ/FAQ_Can_I_create_resources_that_don't_reside_in_the_file_system.md

@@ -0,0 +1,13 @@
+
+
+FAQ Can I create resources that don't reside in the file system?
+================================================================
+
+No. Resources are strictly a file system-based model. They cannot be used to represent files on a remote server or in a database. Although this prevents a large amount of the platform's functionality from being used for nonlocal applications, there were strong architectural reasons for taking this approach. A principal design goal of Eclipse from the start was to enable it to interoperate smoothly with other tools. Because most tools operate on resources in the file system, this is an important medium for interaction between applications. If Eclipse were built on an abstract resource model with no necessary connection with the file system, interaction between Eclipse plug-ins and non-Eclipse-aware tools would be very difficult.
+
+  
+Having said that, nothing requires you to use IResource as your model layer. Almost none of the base platform is tied to resources, and the text-editing framework can also operate on non-IResource models. If you want to build plug-ins that operate on files located remotely, you can define your own model layer to represent them and build views and editors that interact with that remote model rather than with the strictly local IResource model. In Eclipse 3.0, the RCP has no relationship at all with the IResource-based workspace. Only the Eclipse IDE plug-ins still retain a dependency on this model.
+
+  
+If you use resources, you will be tied to the local file system, but you will have a common layer that allows you to interoperate seamlessly with other tools. If you don't want to be tied to the local file system, you can build your own model at the expense of lost integration with plug-ins that are not aware of it. Seamless integration of disparate tools based on a completely abstract resource model is a lofty idea, but like many lofty ideas, it is one that has yet to take flight.
+

docs/FAQ/FAQ_Can_I_get_my_documentation_in_PDF_form,_please.md

@@ -0,0 +1,17 @@
+
+
+FAQ Can I get my documentation in PDF form, please?
+===================================================
+
+PDF documentation is only available for Eclipse [3.1](https://www.eclipse.org/documentation/), but is no longer available for new releases.
+
+When you download Eclipse code, documentation is provided in the form of HTML files, made accessible through a table of contents contained in a file called toc.xml. The contents of the HTML files can be browsed and searched easily with the Eclipse help system (see **Help > Help Contents**). The same information can be found online at the Eclipse documentation Web site.
+
+Converting HTML to PDF form is somewhat labor-intensive. Although tools are available, such as HTMLDOC, to automatically convert HTML to PDF, the exact selection of files to include in the PDF and in what order requires some extra work. The best approach is to start with the toc.xml file and either write a conversion script or develop an Eclipse plug-in, as is done in the tocviewer plug-in used to write this book.
+
+See Also:
+---------
+
+*   HTMLDOC by Easy Software Products ([http://www.easysw.com/htmldoc](http://www.easysw.com/htmldoc))
+*   eclipse.org documentation page ([https://www.eclipse.org/documentation](https://www.eclipse.org/documentation))
+