Professional Eclipse 3 for Java Developers 2006 phần 7 doc

After you enter all the options and press the Finish button, the necessary classes and packages are generated, and the necessary entries are added to the manifest file plugin.xml. In this case, these are entries for the new category and the new view. After saving these files (Ctrl+S), you can execute the plug-in immediately by invoking Run > Run as… > Run-time Workbench. 340 Chapter 11 Figure 11.10 On the third wizard page you can specify additional options for the new view. I will discuss actions in the Actions section and event processing in the section “Event Processing in the Eclipse Workbench.” First, the new view is invisible (if you did not check the option Add the View to the Resource Perspective). With the function Window > Show View > Other… you can select the new view in the Videoclips category and open it. This gives you a relatively well-instrumented tree-based view, as shown in Figure 11.11. What remains is to equip this view with an application-specific domain model. Template-based extension points thus offer the possibility of producing premanufactured application components with just a few mouse clicks. Instead of having to hunt through dozens of APIs, you can obtain well-functioning code that you need only modify according to your requirements. 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 340 Figure 11.11 The Schema Editor If you want to define your own extension points (as discussed previously), it makes sense to define schemas with these extension points, too. These schemas can guide programmers through the specifica- tion of extension point parameters, as you have already had seen in the section “The Most Important SDK Extension Points.” Eclipse uses a subset of the XML Schema language to define such schemas. In some respects, however, such as namespace usage or the spelling of some tags, the dialect used in Eclipse differs from the stan- dard defined by the World Wide Web Consortium (W3C). For this reason, Eclipse schemas have the file extension .exsd instead of the usual .xsd extension. Fortunately, Eclipse provides a Schema Editor that you can use to create schemas without detailed knowledge of the schema language syntax. With the help of this schema editor, you can easily create arbitrarily complex descriptions of extension points. Schema Elements A schema consists of one or several named elements. In addition, it is possible to decorate these elements with attributes. Elements are first defined independently of each other in the left-hand part of the 341 Developing Plug-ins for the Eclipse Platform 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 341 Schema Editor. Here you must specify the name of each element. You can also add icons to them. Under Label Attribute you can specify which of the element’s attributes specifies the display label of the element. Attributes You have the choice between attribute types (Kind): ❑ An attribute of type java will later specify the path of a Java class. In this case, you should specify the full path of an interface or of a superclass in the attribute BasedOn. Eclipse can later use this information to generate the method stubs of such a class. ❑ An attribute of type resource will later specify the path of a workspace resource. ❑ An attribute of type string will later contain a data value. The specification “string” is a bit misleading at this point. In fact, this attribute type allows two different data types: Boolean attributes (boolean) can accept the values true and false, and string attributes (string) can accept any character string. It is possible to restrict the possible values by specifying an enumeration under Restriction. Under the Use entry, you can determine whether the attribute must be specified (required) or is optional. In addition, you can specify a default value in the Value entry if you specified the value default under the Use entry. Schema Structure If you defined several elements, you must organize them into a tree structure. This is done in the right- hand part of the Schema Editor (see Figure 11.12). Each schema must consist of a single root element— the first element in the element list in the left-hand-side window of the editor—to which the other elements are connected directly or indirectly. 342 Chapter 11 Figure 11.12 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 342 Each element within this tree represents either a tree node with child elements or a leaf node. For each tree node with child elements, you can specify a branching type by selecting from four connectors: ❑ Sequence. This connector organizes its child nodes into an ordered list. Schema instances must follow the sequence of child nodes in this node. ❑ All. This connector organizes the child nodes in an unordered list. Schema instances may use a different order of child nodes as specified for this node. ❑ Choice. This connector describes an alternative. In a concrete instance of the schema, only one child node from the Choice list must be specified. ❑ Group. This connector is not available in the W3C standard and seems to be quite superfluous. Sequence, All, and Choice are sufficient for the construction of schema trees. All of these connectors can be nested to an arbitrary depth. In addition, you may specify a repetition fac- tor for each connector and each element. You can specify a lower bound (minOccurs) and an upper bound (maxOccurs) for repetitions. By specifying minOccurs="0" you can define optional tree nodes. If a node can be repeated without an upper bound, you can specify maxOccurs="unbounded". The previous figure shows the schema editor with the opened schema file vFilter.exsd. At the left you see a list of XML elements with their attributes. The window on the right shows the child elements for the element extension. The Description window at the bottom allows you to specify element-specific and attribute-specific documentation. You can enter additional documentation on the Documentation page. New Schema File When you create a new schema file (File > New > Other > Plug-in Development > Extension Point Schema), the wizard first prompts you for four values: ❑ The ID of the plug-in for which the schema file is created ❑ The ID of the extension point relative to the plug-in ❑ The name of the extension point for display purposes ❑ The name of the new schema file The new schema file already contains the root element extension with the attributes point, id, and name. You will usually leave this element unmodified, since it only describes general properties of the extension point. Application-specific elements are created by pressing New Element and then connecting the new element directly or indirectly to the root element. Documentation The Schema Editor is able to generate an HTML reference document from the defined schema. You can get a preview of this document with the context function Preview Reference Document. 343 Developing Plug-ins for the Eclipse Platform 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 343 Components of the Eclipse User Interface Applications written as Eclipse plug-ins that want to use the Eclipse user interface (UI) will in one form or the other use components of the Eclipse UI as clients. These components are deployed in the plug-ins that begin with org.eclipse.ui. You can use all of these components in your own programs as long as they are not contained in packages with the name part “internal.” The Eclipse UI consists on the one hand of plug-ins that provide a certain infrastructure such as the sup- port for forms (discussed next) and for Cheat Sheets (discussed later) and on the other hand of plug-ins that implement the workbench itself (discussed previously). In addition, there are the plug-ins for the help system (see the section “The Help System”). The workbench itself is divided into a generic, resource-independent part and an IDE-specific part that relates to the components of the Eclipse Workspace. All resource-dependent plug-ins and packages have the name part “ide.” These parts cannot be used in the context of the Rich Client Platform (see Chapter 14). Forms Eclipse 2 already had components for a forms-based user interface, but these components were used only internally for implementing the manifest and schema editors. With Eclipse 3 this functionality has been packaged into the separate plug-in org.eclipse.ui.forms and the API was published. Application programmers have now a powerful means of creating forms-based views and editors. An example is found in Chapter 15. Basics Forms mostly use SWT GUI elements, which we have already discussed in Chapter 8. However, these elements are configured in a different way, and additional elements have been added (such as two new layout managers and a hyperlink element). Since the correct configuration is essential for the consistent construction of a form, you should refrain from creating SWT GUI elements using constructors when using them for a form. Instead, the forms plug-in provides via its FormToolkit class various factory methods. In Listing 11.2 you will see how the working area of a view (see the “Views” section) can be filled with a form. public void createPartControl(Composite parent) { // Create FormToolkit instance toolkit = new FormToolkit(parent.getDisplay()); // Create ScrolledForm instance form = toolkit.createScrolledForm(parent); // Create title form.setText("Forms in Eclipse"); // Use a Gridlayout with two columns GridLayout layout = new GridLayout(2, false); // Fetch the form’s container with getBody() // (Composite) form.getBody().setLayout(layout); // Create Hyperlink and add Listener Hyperlink link = toolkit.createHyperlink(form.getBody(), "I want a click!", SWT.WRAP); GridData gd = new GridData(); gd.horizontalSpan = 2; link.setLayoutData(gd); 344 Chapter 11 Listing 11.2 (Continues) 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 344 link.addHyperlinkListener(new HyperlinkAdapter() { public void linkActivated(HyperlinkEvent e) { System.out.println("Hyperlink was activated!"); } }); // Create Label Label label1 = toolkit.createLabel(form.getBody(), "Input field 1:"); // Create text element and place behind label Text text1 = toolkit.createText(form.getBody(), "Default text"); text1.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); // Create Label Label label2 = toolkit.createLabel(form.getBody(), "Input field 2:"); // Create text element with right alignment Text text2 = new Text(form.getBody(), SWT.RIGHT); // and adapt to forms conventions toolkit.adapt(text2, true, true); text2.setText("475"); text2.setLayoutData(new GridData(GridData.FILL_HORIZONTAL)); // Enforce a tree border instead of a text border text2.setData(FormToolkit.KEY_DRAW_BORDER, FormToolkit.TREE_BORDER); // Create button Button button = toolkit.createButton(form.getBody(), "check me", SWT.CHECK); gd = new GridData(); gd.horizontalSpan = 2; button.setLayoutData(gd); // Make sure that borders are drawn on all platforms toolkit.paintBordersFor(form.getBody()); } Listing 11.2 (Continued) Here I have demonstrated quite a few techniques. First, I created a ScrolledForm, that is, a form that shows a scrollbar when space becomes scarce. If you don’t want scrollbars, just use the class Form. Here I have used a GridLayout in the usual way. I have added a Hyperlink element and defined some event processing. Hyperlinks behave just like normal buttons (pushbuttons) but look like text (as a matter of fact, they can be equipped with images, too). The Hyperlink, the following Labels, and the first Text object are all created with the factory methods of the FormToolkit. The Composite contained in the ScrolledForm is specified as a parent container. This container can be retrieved via the method getBody(). For a change, I have created the second Text object in usual way via its constructor. In this case, it was necessary to call the FormToolkit method adapt() for this object to configure it according to the forms standards. For this Text object I have also enforced a different border style. Since borders are not drawn natively on some platforms, I have made sure by calling the method paintBordersFor() that the borders are drawn by the FormToolkit itself with the help of a PaintListener. Figure 11.13 shows how the form looks. If you reduce the size of the window sufficiently, scrollbars will appear automatically. 345 Developing Plug-ins for the Eclipse Platform 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 345 Figure 11.13 Layouts The forms package provides two additional layout classes that are better suited to the specific require- ment of a form than the standard layouts from the SWT plug-in. TableWrapLayout Using a GridLayout for forms has a disadvantage: long labels and hyperlinks are not wrapped if space becomes scarce. To solve this problem, the class TableWrapLayout was introduced. This layout man- ager works similarly to the GridLayout (see the section “The GridLayout Class” in Chapter 8), except that it is able to wrap long elements. TableWrapLayout cooperates with the class TableWrapData with which you can configure the single GUI elements within a layout. For the layout algorithms, the class TableWrapLayout follows the W3C recommendations for the layout of tables in HTML pages. ColumnLayout Another new layout manager is the class ColumnLayout. This class works similarly to a vertical RowLayout (see section “The RowLayout Class” in Chapter 8) but is able to distribute its elements dynamically into several columns, keeping these columns at approximately the same height. You can specify a minimum and maximum number of columns for a ColumnLayout. The default is one to three columns. A good example for ColumnLayout is the Overview page in the manifest editor (see “The Plug-in Manifest” section). Collapsible GUI Elements Two classes enable the end user to collapse and expand parts of a form: ExpandableComposite and Section. ExpandableComposite Instances of class ExpandableComposite are created in the usual way with the factory class FormToolkit and are used as a container for collapsible contents: ExpandableComposite ec = toolkit.createExpandableComposite(form .getBody(), ExpandableComposite.TREE_NODE); 346 Chapter 11 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 346 Such an ExpandableComposite has a control element for collapsing and expanding it, and usually it has a title line, too. ec.setText("This is the title"); Clicking the title line has the same effect as clicking the control element. The behavior and the appear- ance of an ExpandableComposite can be influenced with the following style constants: TREE_NODE The control element looks like the control element of a tree node (+). TWISTIE A small triangle is used as a control element. EXPANDED The ExpandableComposite is initially in an expanded state. COMPACT The size of the content is considered only for computing the width of the ExpandableComposite when it is expanded. NO_TITLE The title line is not displayed. TITLE_BAR The background of the title line is filled with decoration. FOCUS_TITLE The title line can get the focus. CLIENT_INDENT The content of the ExpandableComposite is left-aligned with the title line. Its content is assigned to an ExpandableComposite with the help of the method setClient(): Label client = toolkit.createLabel(ec, someText, SWT.WRAP); ec.setClient(client); When the end user clicks the control element of an ExpandableComposite, an ExpansionEvent is created. This event must be processed with an ExpansionListener or an ExpansionAdapter. When doing so, it is necessary to force the form to reposition its contents by calling its method reflow(): ec.addExpansionListener(new ExpansionAdapter() { public void expansionStateChanged(ExpansionEvent e) { form.reflow(true); } }); Section The class Section is a subclass of the class ExpandableComposites. This class also allows you to use a separator and to define a description text that is displayed below the separator. The following example demonstrates the usage of the class Section: Section section = toolkit.createSection(form.getBody(), Section.DESCRIPTION | Section.TWISTIE | Section.EXPANDED); section.addExpansionListener(new ExpansionAdapter() { public void expansionStateChanged(ExpansionEvent e) { 347 Developing Plug-ins for the Eclipse Platform 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 347 form.reflow(true); } }); section.setText("The Question"); toolkit.createCompositeSeparator(section); section.setDescription("Select the one or the other"); Composite content = toolkit.createComposite(section); content.setLayout(new GridLayout()); toolkit.createButton(content, "to be", SWT.RADIO); toolkit.createButton(content, "not to be", SWT.RADIO); section.setClient(content); Figure 11.14 shows the section implemented, first in its initial state and then after the user clicked the control element. 348 Chapter 11 Figure 11.14 Text Markup The class FormText by far exceeds the text representation functionality achievable with Labels. There are three operation modes that can you can control via the parameters of the method setText(): ❑ Normal text (Label mode) ❑ Automatic transformation of URLs into Hyperlink objects ❑ Text with XML mark-up The last mode is the most powerful, so I want to discuss it in more detail. The following example shows the application of class FormText using XML markup: FormText rtext = toolkit.createFormText(form.getBody(), true); String data = "<form><p>You can find some more information about <b>Eclipse</b>" + " at the <a href=\"http://www.eclipse.org\">eclipse.org</a>" + " web site.</p></form>"; rtext.setText(data, true, false); rtext.addHyperlinkListener(new HyperlinkAdapter() { public void linkActivated(HyperlinkEvent e) { System.out.println("URL was activated: " + e.getLabel() + ", " + e.getHref()); } }); As you can see, the marked-up text must be included in the <form> </form> tags. Individual para- graphs are separated from each other via <p> </p> or <li> </li>. <li> denotes list elements and can be configured with the following attributes: 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 348 style Specify “text“ or “bullet“ or “image.“ value Specifies in the case of “bullet“ the text to be used as a bullet point. In the case of “image“ the image key is specified. vspace If “false“ is specified, no distance is inserted between list entries. The default value is “true.“ indent Horizontal body indent in pixels. bindent Horizontal indent of bullet point in pixels. For <p> paragraphs only the attribute vspace can be specified. Within a paragraph the following markup is possible: <b> </b> Bold text. <span> </span> Text color and text font can be specified with the attributes color and font. <a href="href"> Hyperlink. The target is specified in the attribute href. </a> <img href="ikey"/> An image specified by the key defined in the href attribute. As shown here, images are identified via key values. The same is true for colors and fonts. The particular keys must be associated with suitable Image, Color, and Font instances via the FormText methods setImage(), setColor(), and setFont(). Colors used by the forms subsystem can be obtained from the FormToolkit: toolkit.getColors().getColor(FormColors.TITLE)); As you can see, the class FormText provides some powerful text-representation functions, but by far it cannot reach the representational power of HTML. The number of markup elements is restricted, and it is not possible to nest markup elements. If you require advanced HTML functionality, you should use the Browser widget discussed in the section “The Browser Widget” in Chapter 8. Resource Management If you use several forms within an application, you should share the resources (colors and fonts) used in these forms for reasons of efficiency. In such a case it is recommended to use a repository for colors, an instance of the class FormColors. When you create a FormToolkit, you pass the FormColors instance to the FormToolkit as a parameter, so that the FormToolkit leaves the management of col- ors to the central FormColors instance. In addition, you don’t need a separate FormToolkit for each form—you should always share a FormToolkit instance between forms with a similar lifecycle. If a FormToolkit instance is no longer required, you should release it with its dispose() method. You should also dispose of the FormColors instance when the lifecycle of the plug-in ends. As far as fonts are concerned, you should use only fonts used by the Eclipse platform itself (JFaceResources). This prevents problems with fonts that might not be available on all platforms. 349 Developing Plug-ins for the Eclipse Platform 0470020059 Eclipse Ch 11.qxd 10/13/04 3:54 PM Page 349 [...]... the registered form parts Depending on their state, these form parts are then redrawn, and the method reflow() is executed automatically for the form For implementing IFormPart instances you can subclass the class AbstractFormPart A specialized class SectionFormPart is available for form parts that consist of only a Section instance The Master-Details-Block A popular design pattern for forms-based user... construction with 36 0 Developing Plug-ins for the Eclipse Platform plain SWT elements, page construction with an inner editor (IEditorPart), and forms-based page construction with an IFormPage instance Such instances must be derived from the class FormPage If such an instance is created, a ScrolledForm instance is created internally and wrapped into a ManagedForm (see the “Forms” section) Subclasses of FormPage... editor by an IDocumentProvider instance This allows several editors to access the same document IDocumentProvider manages documents of type IDocument, as discussed in “Text Processing Base Classes” section in Chapter 9 IDocumentProviders are responsible for saving and restoring the managed documents The AbstractTextEditor uses the methods of the registered IDocumentProvider instance when performing editor... separate a data model from its representation For form-based user interfaces this is achieved with the class ManagedForm When a ManagedForm instance is created, a ScrolledForm instance and a FormToolkit are passed to it If not, it will itself create such objects With the method addPart() you can the add form parts in the form of IFormPart instances to the ManagedForm With the method setInput() you can set... 10 35 2 Developing Plug-ins for the Eclipse Platform In an open architecture such as the Eclipse platform, however, this concept is not flexible enough Since the platform can be extended at any time with new plug-ins, you cannot assume a fixed configuration; by using “hard-wired” event processing between components, you would prevent further extensions of a given configuration For this reason, the Eclipse. .. resource-specific dialogs and dialogs for IDE functions are contained in the package org .eclipse. ui.ide.dialogs Figure 11.20 shows the hierarchy of Dialog classes in the package org .eclipse. ui.dialog 37 2 Developing Plug-ins for the Eclipse Platform Figure 11.20 All of these Dialog classes are based on the abstract class SelectionDialog, which is itself based on the JFace class (and therefore, too, on the JFace class... attributes defined for the action CheckSpelling from Chapter 13 Figure 11.19 Actions can be defined in various extension points, such as org .eclipse. ui.actionSets, org .eclipse. ui.editorActions, and org .eclipse. ui.viewActions (see “The Most Important SDK Extension Points”) For each action you can specify the following attributes: id label 36 8 A unique identifier of the action A display text for the action,... Instead, they show the state information of the active editor or of the workbench Figure 11. 17 shows the hierarchy of view types The grayed-out components cannot be instantiated or subclassed ViewPart BookmarkNavigator PageBookView AbstractDebugView Figure 11. 17 36 2 ResourceNavigator ContentOutline PropertySheet TaskList Developing Plug-ins for the Eclipse Platform The Eclipse SDK comes with a variety... Further information about menu managers can be found in the “Actions” section That section also describes how to construct context menus for views, just as it is done for editors The ResourceNavigator Class The ResourceNavigator class implements the navigator for the Eclipse workspace resource (see Figure 11.18) Clients can configure the navigator via the IResourceNavigator interface Figure 11.18 36 3 Chapter... instead uses the internal classes TaskView and ProblemView 36 6 Developing Plug-ins for the Eclipse Platform Actions From time to time, I have mentioned the concept of actions In Eclipse, this idea represents an abstract user action, such as writing to a file, searching for a string in text, or jumping to a marker Actions are represented in Eclipse by the JFace interface IAction (see the section “The . Reference Document. 34 3 Developing Plug-ins for the Eclipse Platform 0 470 020059 Eclipse Ch 11.qxd 10/ 13/ 04 3: 54 PM Page 34 3 Components of the Eclipse User Interface Applications written as Eclipse plug-ins. scrollbars will appear automatically. 34 5 Developing Plug-ins for the Eclipse Platform 0 470 020059 Eclipse Ch 11.qxd 10/ 13/ 04 3: 54 PM Page 34 5 Figure 11. 13 Layouts The forms package provides two additional. Component was made visible (IPartListener2). 35 3 Developing Plug-ins for the Eclipse Platform 0 470 020059 Eclipse Ch 11.qxd 10/ 13/ 04 3: 55 PM Page 35 3 Selection Events Selection events occur when