Eclipse: Building Commercial-Quality Plug-Ins

Intended for Java tool developers who may or may not be familiar with Eclipse, this guide introduces the Eclipse development environment, outlines the process of building a simple plug-in, and describes the standard widget toolkit and JFace. It then shows how to use actions, views, editors, change tracking, perspectives, dialogs, wizards, preference pages, properties, builders, markers, natures, and extension points in an example “favorites” plug-in”

---

Table of contents :
Preface……Page 1
1 Using Eclipse Tools……Page 15
1.1.1. Getting Eclipse……Page 16
1.1.2. Installation……Page 19
1.2. The Eclipse Workbench……Page 20
1.2.1. Perspectives, Views & Editors……Page 22
1.2.2. Actions……Page 33
1.3. Setting Up Your Environment……Page 39
1.3.1. Workbench Preferences……Page 41
1.3.2. Java Preferences……Page 42
1.3.3. Importing and Exporting Preferences……Page 44
1.4. Creating a Project……Page 46
1.4.1. Using the New Java Project Wizard……Page 47
1.4.2. .classpath and .project files……Page 52
1.4.3. Using the Java Package Wizard……Page 56
1.4.4. Using the Java Class Wizard……Page 57
1.5. Navigating……Page 59
1.5.1. Open Type Dialog……Page 60
1.5.2. Type Hierarchy View……Page 62
1.5.3. Go to Line……Page 63
1.5.4. Outline View……Page 64
1.6. Searching……Page 65
1.6.1. File Search……Page 66
1.6.2. Java Search……Page 69
1.6.3. Other Search Menu Options……Page 72
1.6.4. Working Sets……Page 74
1.7. Writing Code……Page 78
1.7.1. Java Editor……Page 79
1.7.2. Templates……Page 88
1.7.3. Refactoring……Page 92
1.7.4. Local History……Page 97
1.7.5. File Extension Associations……Page 101
1.8. Team Development Using CVS……Page 105
1.8.1. Getting Started with CVS……Page 106
1.8.2. Checking Out a Project from CVS……Page 109
1.8.3. Synchronizing with the Repository……Page 110
1.8.4. Comparing & Replacing Resources……Page 112
1.8.5. CVS Label Decorators……Page 114
1.9.1. Launching Java Applications……Page 116
1.9.2. Launch Configurations……Page 119
1.10. Introduction to Debugging……Page 122
1.10.1. Setting Breakpoints……Page 123
1.10.3. Using the Variables view……Page 126
1.10.4. Using the Expressions view……Page 127
1.11.1. Creating Test Cases……Page 129
1.11.2. Running Test Cases……Page 131
1.12. Summary……Page 133
2 Simple Plug-in Example……Page 135
2.1. The Favorites plug-in……Page 136
2.2.1. New plug-in project wizard……Page 137
2.2.2. Define the Plug-in……Page 143
2.2.3. Define the view……Page 145
2.2.4. Project welcome page……Page 148
2.3.1. The plug-in manifest……Page 150
2.3.2. The plug-in class……Page 161
2.3.3. The Favorites View……Page 163
2.4.1. Building manually……Page 167
2.4.2. Building with Apache Ant……Page 171
2.5. Installing and running the product……Page 175
2.6. Debugging the product……Page 177
2.6.1. Creating a configuration……Page 178
2.6.2. Selecting plug-ins and fragments……Page 179
2.6.3. Launching the Runtime Workbench……Page 180
2.7.1. The Plug-in Registry view……Page 182
2.7.2. The Plug-in view……Page 184
2.7.3. The Plug-in Dependency view……Page 185
2.8.1 Installing PDE JUnit……Page 186
2.8.2 Creating a plug-in test project……Page 188
2.8.3 Creating a plug-in test……Page 189
2.8.4 Running a plug-in test……Page 193
2.8.5 Uninstalling the favorites plug-in……Page 195
3.1. Overview……Page 198
3.1.1. Plug-in structure……Page 200
3.2. Plug-in directory……Page 202
3.2.1. Link files……Page 204
3.2.2. Hybrid approach……Page 207
3.3. Plug-in manifest……Page 208
3.3.1. Plug-in declaration……Page 209
3.3.2. Plug-in runtime……Page 213
3.3.3. Plug-in dependencies……Page 215
3.3.4. Extensions and extension points……Page 218
3.4. Plug-in class……Page 221
3.4.1 Startup and shutdown……Page 222
3.4.2. Early plug-in startup……Page 223
3.4.3. Static plug-in resources……Page 224
3.4.4. Plug-in preferences……Page 225
3.4.5. Plugin and AbstractUIPlugin……Page 227
3.5. Plug-in model……Page 229
3.5.1. Plug-in registry……Page 230
3.5.2. Plug-in descriptor……Page 231
3.6. Logging……Page 233
3.6.1. Status objects……Page 236
3.6.2. The Error Log view……Page 237
3.7. Eclipse plug-ins……Page 238
4 Simple Widget Toolkit……Page 241
4.1. SWT History and Goals……Page 242
4.2.1. Simple Standalone Example……Page 248
4.2.2. Widget Life Cycle……Page 255
4.2.3. Widget Events……Page 257
4.2.4. Abstract Widget Classes……Page 260
4.2.5. Top-Level Classes……Page 269
4.2.6. Useful Widgets……Page 278
4.2.7. Menus……Page 322
4.3. Layout Management……Page 328
4.3. FillLayout……Page 329
4.3.2. RowLayout……Page 331
4.3.3. GridLayout……Page 335
4.3.4. FormLayout……Page 341
4.4. Resource Management……Page 348
4.4.2. Fonts……Page 349
.4.3. Images……Page 350
4.5. Summary……Page 351
5 JFace Viewers……Page 353
5.1. List-oriented Viewers……Page 354
5.1.1. Label Providers……Page 356
5.1.2. Content Providers……Page 358
5.1.3. Viewer Sorters……Page 360
5.1.4. Viewer Filters……Page 362
5.1.5. StructuredViewer……Page 364
5.1.6. ListViewers……Page 368
5.1.7. TableViewers……Page 372
5.1.8. TreeViewers……Page 380
5.2. Text Viewers……Page 387
5.3. Summary……Page 391
6 Actions……Page 393
6.1. IAction versus IActionDelegate……Page 394
6.2.1. Defining a workbench window menu……Page 397
6.2.2. Groups in a menu……Page 404
6.2.3. Defining a menu item and toolbar button……Page 405
6.2.4. Action images……Page 409
6.2.5. Insertion points……Page 411
6.2.6. Creating an action delegate……Page 413
6.2.7. Manually testing the new action……Page 417
6.2.8. Adding a test for the new action……Page 418
6.2.9. Discussion……Page 421
6.3. Object Actions……Page 424
6.3.1. Defining an object based action……Page 425
6.3.2. Action filtering and enablement……Page 428
6.3.3. IObjectActionDelegate……Page 438
6.3.4. Creating an object based sub-menu……Page 439
6.3.5. Manually testing the new action……Page 441
6.3.6. Adding a test for the new action……Page 442
6.4. View Actions……Page 444
6.4.1. Defining a view context sub-menu……Page 445
6.4.2. Defining a view context menu action……Page 448
6.4.4. Defining a view toolbar action……Page 451
6.4.5. Defining a view pulldown sub-menu and action……Page 454
6.4.6. Manually testing the new actions……Page 456
6.4.8. View context menu identifiers……Page 457
6.5. Editor Actions……Page 461
6.5.1. Defining an editor context menu……Page 462
6.5.2. Defining an editor context action……Page 464
6.5.3. IEditorActionDelegate……Page 466
6.5.4. Defining an editor top level menu……Page 467
6.5.5. Defining an editor top level action……Page 469
6.5.8. Editor context menu identifiers……Page 473
6.6. Key Bindings……Page 476
6.6.1. Categories……Page 477
6.6.2. Commands……Page 478
6.6.3. Key Bindings……Page 479
6.6.5. Keyboard accessibility……Page 482
6.7. RFWS Considerations……Page 485
6.7.1 Global Action Labels……Page 486
6.7.2 Action Enablement Delay……Page 487
6.8. Summary……Page 489
7 Views……Page 490
7.1.1. Declaring a View Category……Page 493
7.1.2. Declaring a View……Page 495
7.2.1. View Methods……Page 498
7.2.2. View Controls……Page 499
7.2.3. View Model……Page 501
7.2.4. Content Provider……Page 515
7.2.5. Label Provider……Page 517
7.2.6. Viewer Sorter……Page 519
7.2.7. Viewer Filters……Page 522
7.3. View Actions……Page 525
7.3.1. Model Actions……Page 526
7.3.2. Context Menu……Page 527
7.3.3. Toolbar Buttons……Page 532
7.3.4. Pulldown Menu……Page 533
7.3.5. Keyboard Actions……Page 535
7.3.6. Global Actions……Page 536
7.3.7. Clipboard Actions……Page 537
7.3.8. Drag and Drop Support……Page 543
7.3.9. Inline Editing……Page 557
7.4. Linking the View……Page 563
7.4.2. Adaptable Objects……Page 564
7.4.3. Selection Listener……Page 565
7.5.1. Saving local view information……Page 567
7.5.2. Saving global view information……Page 571
7.6. Testing……Page 575
7.7. Image Caching……Page 576
7.8. Autosizing table columns……Page 578
7.9. RFWS Considerations……Page 581
7.9.2. Views Save Immediately……Page 582
7.9.3. View or Views……Page 583
7.9.4. View Initialization……Page 584
7.9.5. Selection oriented actions……Page 585
7.9.6. Register context menus……Page 586
7.9.7. Action filters for views……Page 587
7.9.8. View global actions from menubar……Page 588
7.10. Summary……Page 590
8 Editors……Page 592
8.1. Editor Declaration……Page 594
8.2. Editor Part……Page 600
8.2.1. Editor Methods……Page 601
8.2.2. Editor Controls……Page 604
8.2.3. Editor Model……Page 609
8.2.4. Content Provider……Page 617
8.2.5. Label Provider……Page 619
8.3. Editing……Page 622
8.3.1. Cell Editors……Page 623
8.3.2. Cell Modifiers……Page 624
8.3.3. Change Listeners……Page 626
8.3.4. Cell Validators……Page 628
8.3.5. Editing versus Selecting……Page 630
8.4. Editor Lifecycle……Page 632
8.4.1. Dirty Editors……Page 633
8.4.1. Switching Pages……Page 634
8.4.2. Saving Content……Page 637
8.5.1. Context Menu……Page 638
8.5.2. Editor Contributor……Page 644
8.5.3. Undo/Redo……Page 652
8.4. Linking the Editor……Page 657
8.5.1. Using an editor to edit or browse……Page 658
8.5.2. Editor lifecycle……Page 659
8.5.3. Single editor instance per input……Page 660
8.5.4. Separate editors for each input……Page 661
8.5.5. Accessing global actions from the menubar……Page 662
8.5.6. Registering editor menus……Page 663
8.5.8. Closing the editor when the object is deleted……Page 664
8.5.9. Unsaved editor modifications……Page 665
8.5.10. Prefix dirty resources……Page 666
8.5.11. Editor outline view……Page 667
8.5.13. Synchronize with external changes……Page 668
8.6. Summary……Page 669
9 Resource change tracking……Page 670
9.1 IResourceChangeListener……Page 671
9.1.1 IResourceChangeEvent……Page 672
9.1.2 IResourceDelta……Page 674
9.2 Processing change events……Page 678
9.3 Batching change events……Page 682
9.4.1. IProgressMonitor……Page 685
9.4.2. Classes for displaying progress……Page 687
9.4.3. Workbench window status bar……Page 688
9.5 Delayed changed events……Page 690
9.6. RFWS Considerations……Page 692
9.7. Summary……Page 693
10 Perspectives……Page 694
10.1. Creating a Perspective……Page 695
10.1.1. Perspective Extension Point……Page 697
10.1.2. Perspective factories……Page 701
10.1.3. IPageLayout……Page 705
10.2. Enhancing an Existing Perspective……Page 707
10.2.1. Adding Views and Placeholders……Page 711
10.2.2. Adding Shortcuts……Page 714
10.2.3. Adding Action Sets……Page 719
10.3.1. Create Perspective for Long-lived tasks……Page 722
10.3.2. New View for Existing Perspectives……Page 723
10.3.4. Adding Perspective Actions to Window Menu……Page 724
10.3.5. Newly Opened Perspectives……Page 725
10.4. Summary……Page 726
11 Dialogs and Wizards……Page 727
11.1 Dialogs……Page 728
11.1.1 SWT Dialogs versus JFace Dialogs……Page 729
11.1.2 Common SWT Dialogs……Page 730
11.1.3 Common JFace Dialogs……Page 732
11.1.4 Creating a JFace dialog……Page 738
11.1.5 Dialog Units……Page 742
11.1.6 Initial dialog location and size……Page 744
11.1.7 Resizable Dialogs……Page 746
11.1.8 Favorites view filter dialog……Page 749
11.1.9 Details Dialog……Page 755
11.1.10. Opening a dialog – finding a parent shell……Page 767
11.2 Wizards……Page 770
11.2.1 IWizard……Page 772
11.2.2 IWizardPage……Page 775
11.2.3 IWizardContainer……Page 778
11.2.5 Launching a Wizard……Page 780
11.2.6 Wizard Example……Page 788
11.2.7 Dialog Settings……Page 790
11.2.8 Page content based on selection……Page 792
11.2.9 Page content based on prior page……Page 799
11.3.2. Slush bucket widget usage……Page 802
11.3.3. Use wizards for multi-step tasks……Page 803
11.3.5. Wizard field initialization……Page 804
11.3.6. Wizard data validation……Page 806
11.3.8. Open new file in editor……Page 807
11.3.10. Show new object……Page 808
11.4 Summary……Page 809
12 Preference Pages……Page 810
12.1. Creating a preference page……Page 811
12.2. Preference page APIs……Page 816
12.2.1. FieldEditorPreferencePage……Page 819
12.2.2. Field editors……Page 822
12.2.3. PreferencePage……Page 829
12.2.4. Favorites preference page……Page 832
12.2.5. Validation……Page 834
12.2.6. Nested preference pages……Page 836
12.2.7. Tabbed preference pages……Page 840
12.3. Preference APIs……Page 842
12.3.1. Default Preferences……Page 843
12.3.2. Accessing Preferences……Page 845
12.3.3. Specifying default values programmatically……Page 851
12.3.4. Specifying default values in a file……Page 852
12.3.5. Hooking up the Favorites view……Page 853
12.3.6. Listening for preference changes……Page 854
12.4.1. Preference dialog use……Page 856
12.4.2. Preference dialog misuse……Page 857
12.5. Summary……Page 858
13 Properties……Page 859
13.1.1. FavoriteItem properties……Page 860
13.1.2. Resource properties……Page 863
13.2. Displaying properties in the properties dialog……Page 866
13.2.1. Declaring a property page……Page 867
13.2.2. Creating a resource property page……Page 874
13.2.3. Creating a Favorites item resource page……Page 877
13.2.4. Opening the Properties Dialog……Page 879
13.3. Displaying properties in the property view……Page 880
13.3.1. Properties view API……Page 883
13.3.2. Favorite properties in the Properties view……Page 886
13.4. Property pages reused as preference pages……Page 889
13.5. RFWS Considerations……Page 891
13.5.2. Properties Dialog for expensive calculations……Page 892
13.5.3. Properties Dialog for complex relationships……Page 893
13.6. Summary……Page 894
14 Builders, Markers, and Natures……Page 896
14.1. Builders……Page 899
14.1.1. Declaring a builder……Page 900
14.1.2. IncrementalProjectBuilder……Page 905
14.1.4. Associating a builder with a project……Page 915
14.1.5. Invoking builders……Page 918
14.2. Markers……Page 920
14.2.1. Marker types……Page 921
14.2.2. Creating and deleting markers……Page 925
14.2.3. Marker attributes……Page 929
14.2.4. Marker resolution – Quick fix……Page 936
14.2.5. Finding markers……Page 943
14.3. Natures……Page 944
14.3.1. Declaring a nature……Page 946
14.3.2. Associating builders and natures……Page 949
14.3.3. IProjectNature……Page 950
14.3.4. Required natures……Page 952
14.3.5. Conflicting natures……Page 953
14.3.6. Nature image……Page 954
14.3.7. Associating a nature with a project……Page 955
14.4.1. Use builders to convert resources……Page 958
14.4.2. Builders must be added by natures……Page 959
14.4.4. Do not misuse the term “build”……Page 960
14.4.5. Mark builder-created resources as “derived”……Page 961
14.4.6. Use IResourceProxy objects when possible……Page 962
14.5. Summary……Page 963
15 Implementing Help……Page 964
15.1. Using Help……Page 965
15.2. Implementing Help……Page 970
15.2.1. Creating a new Help project……Page 971
15.2.2. Plug-in manifest files……Page 981
15.2.3. Table of contents (toc) files……Page 984
15.2.4. Creating HTML content……Page 988
15.3. Context-Sensitive “Infopop” Help (F1)……Page 990
15.3.1. Associating context IDs with items……Page 992
15.3.2. WorkbenchHelp API……Page 994
15.3.3. Creating the infopop content……Page 995
15.3.4. Contexts Extension Point……Page 997
15.4. Accessing Help Programmatically……Page 1002
15.4.1. Opening a specific help page……Page 1003
15.4.2. Opening a web page……Page 1005
15.5.2. Provide help through the Workbench help system……Page 1007
15.5.3. Include proper Eclipse acknowledgement……Page 1008
15.5.5. Context help activated using F1……Page 1010
15.5.6. Implement active help……Page 1011
15.5.8. Use of additional documentation……Page 1012
15.5.9. Pre-build help indexes……Page 1013
15.6. Summary……Page 1014
16 Internationalization……Page 1015
16.1. Externalizing the Plug-in Manifest……Page 1016
16.2. Externalizing Plug-in Strings……Page 1020
16.3. Using Fragments……Page 1035
16.3.1. New fragment project wizard……Page 1037
16.3.2. Fragment manifest file……Page 1045
16.3.3. Fragment project contents……Page 1049
16.4. Summary……Page 1050
17 Creating New Extension Points……Page 1052
17.1. The extension point mechanism……Page 1053
17.2.1. Creating an extension-point……Page 1056
17.2.2. Creating an extension-point schema……Page 1059
17.2.3. Extension-point elements and attributes……Page 1062
17.2.4. Extension-point element grammar……Page 1069
17.3. Code behind an extension-point……Page 1073
17.3.1. Parsing the extension information……Page 1074
17.3.2. Constructing proxies……Page 1076
17.3.3. Creating executable extensions……Page 1080
17.3.4. Clean up……Page 1083
17.4. Extension-point documentation……Page 1084
17.5. Using the extension-point……Page 1088
17.5.1. Naming conventions……Page 1091
17.5.2. Document extension points……Page 1092
17.5.4. Treat plug-in registry as read-only……Page 1093
17.5.5. Log errors……Page 1094
17.6. Summary……Page 1095
18 Features & Branding……Page 1096
18.1.1. Creating a new Feature project……Page 1099
18.1.2. Feature manifest files……Page 1105
18.1.3. Feature manifest editor……Page 1106
18.2. Branding……Page 1121
18.2.1. The about.html file……Page 1122
18.2.2. The about.ini file……Page 1124
18.2.3. The welcome.xml file……Page 1130
18.2.4. Primary feature file……Page 1134
18.3. Update Sites……Page 1135
18.3.1. Creating an update site project……Page 1136
18.3.2. The site.xml file……Page 1140
18.3.3. The update web site……Page 1146
18.3.4. Revisiting the feature manifest……Page 1147
18.3.5. Accessing the update site……Page 1149
18.4. RFWS Considerations……Page 1154
18.4.2. Branded feature visibility……Page 1155
18.4.4. about.html file contents……Page 1156
18.4.5. Splash screen restrictions……Page 1157
18.5. Summary……Page 1158
19 Building a product……Page 1160
19.1.1. Build projects……Page 1161
19.1.2. Build targets……Page 1162
19.1.3. Build tasks……Page 1166
19.1.4. Build properties……Page 1172
19.1.5. task……Page 1184
19.1.7. Headless Ant……Page 1186
19.1.6. Ant Extensions……Page 1189
19.2.1. Auto generated build script……Page 1192
19.2.2. Refactoring the Favorites build script……Page 1197
19.2.3. Compiling during the build process……Page 1204
19.2.4. Single versus multiple binaries……Page 1207
19.2.5. Editing the same source with different versions of E……Page 1208
19.2.6. Building against different versions of Eclipse……Page 1211
19.2.7. Classpath tools……Page 1225
19.2.8. Building against Eclipse 2.1……Page 1227
19.2.9. Retargeting source code……Page 1229
19.2.10. Version checking……Page 1231
19.2.11. Building for Internationalization……Page 1233
19.3. Summary……Page 1235
20 Advanced Topics……Page 1237
20.1. Advanced Search – Reference Projects……Page 1238
20.2 Accessing Internal Code……Page 1240
20.2.1 Eclipse newsgroup……Page 1241
20.2.2 Bugzilla – Eclipse bug tracking system……Page 1242
20.2.3 Options for accessing internal code……Page 1243
20.2.4 How Eclipse is different……Page 1244
20.2.5 ClassLoader tricks……Page 1245
20.2.6 Using Fragments……Page 1247
20.3.1. IAdaptable……Page 1249
20.3.2. Using adapters……Page 1250
20.3.3. Adapter factory……Page 1251
20.4 Opening a browser or creating an email……Page 1255
20.4.1. OpenBrowserAction……Page 1256
20.4.2. LaunchURL……Page 1261
20.5. Types specified in an extension-point……Page 1262
20.5.1. Parameterized types……Page 1263
20.5.2. Referencing a class in a different plug-in……Page 1267
20.6. Modifying Eclipse to find part identifiers……Page 1268
20.6.1. Modifying the Eclipse base……Page 1269
20.6.2. Creating the global action……Page 1272
20.6.4. Submitting the change to Eclipse……Page 1275
20.7. Label decorators……Page 1277
20.7.1. Declaring a label decorator……Page 1279
20.7.2. ILightweightLabelDecorator……Page 1282
20.7.3. Decorative label decorators……Page 1285
20.8. Background tasks – Jobs API……Page 1287
20.9. Project class loader……Page 1291
20.10. OSGi bundles and the 3.0 runtime……Page 1298
20.11. Conclusion……Page 1302
A. Eclipse Plug-ins & Resources……Page 1304
A.1. Plug-ins……Page 1305
A.1.1. CodePro Studio……Page 1306
A.1.2. EclipseProfiler……Page 1308
A.1.3. EclipseUML……Page 1309
A.1.4. MyEclipse Enterprise Workbench……Page 1311
A.1.5. SWT Designer……Page 1313
A.1.6. XMLBuddy……Page 1315
A.2.1 Eclipse.org……Page 1317
A.2.4 Eclipse Wiki Wiki……Page 1319
A.2.8 Coloring editor……Page 1320
A.2.11 IBM Eclipse Research……Page 1321
A.2.15 Sangam: XP programming for Eclipse……Page 1322
A.2.16 Wiki editor for Eclipse……Page 1323
B. The RFWS Program……Page 1324
Trademarks……Page 1327