Eclipse Building Commercial-Quality Plug-ins Second Edition

Eclipse Building Commercial-Quality Plug-ins Second Edition Eric Clayberg Dan Rubel v:addison-wesley Upper Saddle River, NJ Boston Indianapolis San Francisco New York Toronto Montreal London Munich Paris Madrid Capetown Sydney Tokyo Singapore Mexico City

Foreword by Skip McGaughey xxxi Foreword by Simon Archer xxxiii Preface xxxv Chapter 1 Using Eclipse Tools 1 1.1 Getting Started 1 1.1.1 Getting Eclipse 1 1.1.2 Installation 3 1.2 The Eclipse Workbench 3 1.2.1 Perspectives, views, and editors 5 1.2.2 Actions 11 1.3 Setting Up Your Environment 14 1.3.1 Workbench preferences 15 1.3.2 Java preferences 17 1.3.3 Importing and exporting preferences 18 ix

x Contents 1.4 Creating a Project 19 1.4.1 Using the new Java Project wizard 19 1.4.2.classpath and.project files 22 1.4.3 Using the Java Package wizard 24 1.4.4 Using the Java Class wizard 24 1.5 Navigating 26 1.5.1 Open Type dialog 26 1.5.2 Type Hierarchy view 27 1.5.3 Go to Line 27 1.5.4 Outline view 27 1.6 Searching 28 1.6.1 File Search 28 1.6.2 Java Search 30 1.6.3 Other Search menu options 31 1.6.4 Working sets 32 1.7 Writing Code 34 1.7.1 Java editor 34 1.7.2 Templates 39 1.7.3 Refactoring 41 1.7.4 Local history 44 1.7.5 File extension associations 46 1.8 Team Development Using CVS 48 1.8.1 Getting started with CVS 49 1.8.2 Checking out a project from CVS 50 1.8.3 Synchronizing with the repository 51 1.8.4 Comparing and replacing resources 52 1.8.5 CVS Label decorators 53

xi 1.9 Running Applications 54 1.9.1 Launching Java applications 55 1.9.2 Launch configurations 56 1.10 Introduction to Debugging 58 1.10.1 1.10.2 1.10.3 1.10.4 Setting breakpoints 58 Using the Debug view 60 Using the Variables view 60 Using the Expressions view 60 1.11 Introduction to Testing 61 1.11.1 Creating test cases 61 1.11.2 Running test cases 62 1.12 Summary 63 Chapter 2 A Simple Plug-in Example 65 2.1 The Favorites Plug-in 65 2.2 Creating a Plug-in Project 66 2.2.1 New Plug-in Project wizard 66 2.2.2 Define the plug-in 67 2.2.3 Define the view 69 2.3 Reviewing the Generated Code 71 2.3.1 The Plug-in manifests 71 2.3.2 The Plug-in dass 77 2.3.3 The Favorites view 78 2.4 Building a Product 81 2.4.1 Building manually 81 2.4.2 Building with Apache Ant 83

xii Contents 2.5 Installing and Running the Product 86 2.6 Debugging the Product 88 2.6.1 Creating a configuration 88 2.6.2 Selecting plug-ins and fragments 89 2.6.3 Launching the Runtime Workbench 90 2.7 PDE Views 90 2.7.1 The Plug-in Registry view 90 2.7.2 The Plug-ins view 91 2.7.3 The Plug-in Dependencies view 91 2.8 Writing Plug-in Tests 92 2.8.1 Test preparation 92 2.8.2 Creating a Plug-in test project 92 2.8.3 Creating a Plug-in test 93 2.8.4 Running a Plug-in test 97 2.8.5 Uninstalling the Favorites plug-in 98 2.9 Summary 98 Chapter 3 Eclipse Infrastructure 101 3.1 Structural Overview 101 3.1.1 Plug-in structure 102 3.1.2 Workspace 104 3.2 Plug-in Directory or JAR file 104 3.2.1 Link files 105 3.2.2 Hybrid approach 106 3.3 Plug-in Manifest 107 3.3.1 Plug-in declaration 108 3.3.2 Plug-in runtime 110 3.3.3 Plug-in dependencies 110 3.3.4 Extensions and extension points 112

xiii 3.4 Plug-in Class 114 3.4.1 Startup and shutdown 114 3.4.2 Early plug-in startup 114 3.4.3 Static plug-in resources 115 3.4.4 Plug-in preferences 116 3.4.5 Plug-in configuration files 116 3.4.6 Plugin and AbstractUlPlugin 118 3.5 Plug-in Model 119 3.5.1 Platform 119 3.5.2 Plug-ins and Bundles 120 3.5.3 Plug-in extension registry 121 3.6 Logging 122 3.6.1 Status objects 123 3.6.2 The Error Log view 124 3.7 Eclipse Plug-ins 124 3.8 Summary 125 Chapter 4 The Standard Widget Toolkit 127 _ 4.1 SWT History and Goals 127 4.2 SWT Widgets 130 4.2.1 Simple stand-alone example 130 4.2.2 Widget lifecycle 133 4.2.3 Widget events 134 4.2.4 Abstract widget classes 136 4.2.5 Top-level classes 140 4.2.6 Useful widgets 143 4.2.7 Menus 166

xiv Contents 4.3 Layout Management 170 4.3.1 FillLayout 170 4.3.2 RowLayout 171 4.3.3 GridLayout 174 4.3.4 FormLayout 177 4.4 Resource Management 180 4.4.1 Colors 180 4.4.2 Fonts 181 4.4.3 Images 181 4.5 Summary 181 Chapter 5 JFace Viewers 185 5.1 List-Oriented Viewers 185 5.1.1 Label providers 186 5.1.2 Content providers 187 5.1.3 Viewer sorters 189 5.1.4 Viewer filters 189 5.1.5 StructuredViewer dass 190 5.1.6 ListViewer dass 192 5.1.7 TableViewer dass 195 5.1.8 TreeViewer dass 199 5.2 Text Viewers 203 5.3 Summary 206 Chapter 6 Actions 207 6.1 IAction versus IActionDelegate 207 6.2 Workbench Window Actions 209 6.2.1 Defining a workbench window menu 209 6.2.2 Groups in a menu 212

xv 6.2.3 Defining a menu item and toolbar button 212 6.2.4 Action images 214 6.2.5 Insertion points 215 6.2.6 Creating an action delegate 216 6.2.7 Manually testing the new action 219 6.2.8 Adding a test for the new action 220 6.2.9 Discussion 222 6.3 Object Actions 224 6.3.1 Defining an object-based action 224 6.3.2 Action filtering and enablement 227 6.3.3 IObjectActionDelegate 233 6.3.4 Creating an object-based submenu 234 6.3.5 Manually testing the new action 235 6.3.6 Adding a test for the new action 235 6.4 View Actions 237 6.4.1 Defining a view context submenu 237 6.4.2 Defining a view context menu action 238 6.4.3 IViewActionDelegate 240 6.4.4 Defining a view toolbar action 240 6.4.5 Defining a view pull-down submenu and action 241 6.4.6 Manually testing the new actions 242 6.4.7 Adding tests for the new actions 242 6.4.8 View context menu identifiers 242 6.5 Editor Actions 244 6.5.1 Defining an editor context menu 245 6.5.2 Defining an editor context action 246 6.5.3 IEditorActionDelegate 246 6.5.4 Defining an editor top-level menu 247 6.5.5 Defining an editor top-level action 248

xvi Contents 6.5.6 Defining an editor toolbar action 249 6.5.7 Adding tests for the new actions 250 6.5.8 Editor context menu identifiers 250 6.6 Key Bindings 251 6.6.1 Categories 252 6.6.2 Commands 252 6.6.3 Key bindings 252 6.6.4 Associating commands with actions 255 6.6.5 Keyboard accessibility 255 6.7 RFRS Considerations 256 6.7.1 Global action labels (RFRS 5.3.5.1) 257 6.8 Summary 257 Chapter 7 Views 259 7.1 View Declaration 261 7.1.1 Declaring a view category 261 7.1.2 Declaring a view 262 7.2 View Part 263 7.2.1 7.2.2 7.2.3 7.2.4 7.2.5 7.2.6 7.2.7 7.2.8 View methods 263 View controls 264 View model 265 Content provider 276 Label provider 277 Viewer sorter 278 Viewer filters 281 View selection 282 7.3 View Actions 283 7.3.1 Model actions 283 7.3.2 Context menu 283

xvü 7.3.3 Toolbar buttons 287 7.3.4 Pull-down menu 287 7.3.5 Keyboard actions 288 7.3.6 Global actions 289 7.3.7 Clipboard actions 290 7.3.8 Drag-and-drop support 294 7.3.9 Inline editing 301 7.4 Linking the View 305 7.4.1 Selection provider 305 7.4.2 Adaptable objects 306 7.4.3 Selection listener 306 7.4.4 Opening an editor 307 7.5 Saving View State 308 7.5.1 Saving local view information 308 7.5.2 Saving global view information 311 7.6 Testing 314 7.7 Image Caching 315 7.8 Auto-sizing Table Columns 316 7.9 RFRS Considerations 319 7.9.1 Views for navigation (RFRS 3.5.15) 319 7.9.2 Views save immediately (RFRS 3.5.16) 320 7.9.3 View initialization (RFRS 3.5.17) 320 7.9.4 View global actions (RFRS 3.5.18) 320 7.9.5 Persist view state (RFRS 3.5.19) 321 7.9.6 Register context menus (RFRS 5.3.5.8) 321 7.9.7 Action filters for views (RFRS 5.3.5.9) 322 7.10 Summary 323

xviii Contents Chapter 8 Editors 325 8.1 Editor Declaration 326 8.2 Editor Part 330 8.2.1 Editor methods 330 8.2.2 Editor controls 331 8.2.3 Editor model 335 8.2.4 Content provider 341 8.2.5 Label provider 342 8.3 Editing 344 8.3.1 Cell editors 344 8.3.2 Cell modifiers 345 8.3.3 Change listeners 347 8.3.4 Cell validators 348 8.3.5 Editing versus selecting 349 8.4 Editor Lifecycle 350 8.4.1 Dirty editors 351 8.4.2 Switching pages 352 8.4.3 Saving content 353 8.5 Editor Actions 354 8.5.1 Context menu 354 8.5.2 Editor contributor 357 8.5.3 Undo/Redo 362 8.5.4 Clipboard actions 369 8.6 Linking the Editor 369 8.7 RFRS Considerations 369 8.7.1 Using an editor to edit or browse (RFRS 3.5.9) 370 8.7.2 Editor lifecycle (RFRS 3.5.10) 370 8.7.3 Accessing global actions (RFRS 3.5.11) 371

xix 8.7.4 Closing when the object is deleted (RFRS 3.5.12) 371 8.7.5 Synchronize external changes (RFRS 3.5.14) 372 8.7.6 Registering editor menus (RFRS 5.3.5.2) 372 8.7.7 Editor action filters (RFRS 5.3.5.3) 373 8.7.8 Unsaved editor modifications (RFRS 5.3.5.4) 373 8.7.9 Prefix dirty resources (RFRS 5.3.5.5) 373 8.7.10 Editor outline view (RFRS 5.3.5.6) 374 8.7.11 Synchronize with outline view (RFRS 5.3.5.7) 374 8.8 Summary 374 Chapter 9 Resource Change Tracking 375 9.1 IResourceChangeListener 375 9.1.1 IResourceChangeEvent 376 9.1.2 IResourceDelta 377 9.2 Processing Change Events 379 9.3 Batching Change Events 382 9.4 Progress Monitor 383 9.4.1 IProgressMonitor 383 9.4.2 Classes for displaying progress 384 9.4.3 Workbench window status bar 385 9.4.4 IProgressService 386 9.5 Delayed Changed Events 387 9.6 Summary 388 Chapter 10 Perspectives 389 10.1 Creating a Perspective 389 10.1.1 Perspective extension point 390 10.1.2 Perspective factories 392 10.1.3 IPageLayout 395

xx Contents 10.2 Enhancing an Existing Perspective 396 10.2.1 Adding views and placeholders 398 10.2.2 Adding shortcuts 400 10.2.3 Adding action sets 402 10.3 RFRS Considerations 403 10.3.1 Create for Jong-lived tasks (RFRS 5.3.5.10) 403 10.3.2 Extend existing perspectives (RFRS 5.3.5.11) 404 10.3.3 Add actions to window menu (RFRS 5.3.5.15) 404 10.4 Summary 404 Chapter 11 Dialogs and Wizards 405 11.1 Dialogs 405 11.1.1 SWT dialogs versus JFace dialogs 406 11.1.2 Common SWT dialogs 406 11.1.3 Common JFace dialogs 407 11.1.4 Creating a JFace dialog 410 11.1.5 Dialog units 412 11.1.6 Initial dialog location and size 413 11.1.7 Resizable dialogs 414 11.1.8 Favorites view filter dialog 416 11.1.9 Details dialog 420 11.1.10 Opening a dialog finding a parent shell 428 11.2 Wizards 430 11.2.1 11.2.2 11.2.3 11.2.4 11.2.5 11.2.6 IWizard 431 IWizardPage 433 IWizardContainer 434 Nested wizards 435 Launching a wizard 435 Wizard example 439

xxi 11.2.7 Dialog settings 441 11.2.8 Page content based on selection 441 11.2.9 Page content based on previous page 447 11.3 RFRS Considerations 449 11.3.1 Wizard look and feel (RFRS 3.5.2) 449 11.3.2 Open new file in editor (RFRS 3.5.6) 449 11.3.3 New project switches perspective (RFRS 3.5.7) 449 11.3.4 Show new object (RFRS 3.5.8) 450 11.3.5 One-page wizard buttons (RFRS 5.3.5.13) 450 11.4 Summary 450 Chapter 12 Preference Pages 451 12.1 Creating a Preference Page 451 12.2 Preference Page APIs 453 12.2.1 FieldEditorPreferencePage 455 12.2.2 Field editors 456 12.2.3 PreferencePage 460 12.2.4 Favorites preference page 461 12.2.5 Validation 463 12.2.6 Nested preference pages 464 12.2.7 Tabbed preference pages 466 12.3 Preference APIs 467 12.3.1 Default preferences 468 12.3.2 Accessing preferences 469 12.3.3 Specifying default values programmatically 471 12.3.4 Specifying default values in a file 472 12.3.5 Hooking up the Favorites view 473 12.3.6 Listening for preference changes 474

12.4 RFRS Considerations 474 12.4.1 Preferences dialog use (RFRS 3.5.25) 475 12.5 Summary 475 Chapter 13 Properties 477 13.1 Creating Properties 477 13.1.1 Favoriteltem properties 478 13.1.2 Resource properties 479 13.2 Displaying Properties in the Properties Dialog 481 13.2.1 Declaring a Property page 481 13.2.2 Creating a resource Property page 485 13.2.3 Creating a Favorites item resource page 487 13.2.4 Opening the Properties dialog 488 13.3 Displaying Properties in the Properties View 489 13.3.1 Properties view API 490 13.3.2 Favorite properties in the Properties view 492 13.4 Property Pages Reused as Preference Pages 493 13.5 RFRS Considerations 495 13.5.1 Properties views for quick access (RFRS 3.5.21) 495 13.6 Summary 495 Chapter 14 Builders, Markers, and Natures 497 14.1 Builders 499 14.1.1 Declaring a builder 499 14.1.2 IncrementalProjectBuilder 502 14.1.3 Derived resources 509 14.1.4 Associating a builder with a project 509 14.1.5 Invoking builders 512

xxiii 14.2 Markers 512 14.2.1 Marker types 513 14.2.2 Creating and deleting markers 515 14.2.3 Marker attributes 517 14.2.4 Marker resolution quick fix 520 14.2.5 Finding markers 525 14.3 Natures 525 14.3.1 Declaring a nature 526 14.3.2 Associating builders and natures 528 14.3.3 IProjectNature 529 14.3.4 Required natures 530 14.3.5 Conflicting natures 531 14.3.6 Nature image 531 14.3.7 Associating a nature with a project 532 14.4 RFRS Considerations 535 14.4.1 Use builders to convert resources (RFRS 3.8.1) 535 14.4.2 Do not replace existing builders (RFRS 3.8.3) 535 14.4.3 Do not misuse the term "build" (RFRS 5.3.8.1) 535 14.4.4 Mark created resources as "derived" (RFRS 5.3.8.2) 536 14.4.5 Respond to clean-build requests (RFRS 5.3.8.3) 536 14.4.6 Use IResourceProxy when possible (RFRS 5.3.8.4) 537 14.4.7 Builders must be added by natures (RFRS 5.3.8.5) 537 14.5 Summary 537 Chapter 15 Implementing Help 539 15.1 Using Help 539 15.2 Implementing Help 542 15.2.1 Creating a new help project 543 15.2.2 Plug-in manifest files 547

xxiv Contents 15.2.3 Table of contents (toc) files 548 15.2.4 Creating HTML content 551 15.3 Context-Sensitive Help (F1) 552 15.3.1 Associating context IDs with items 553 15.3.2 IWorkbenchHelpSystem API 555 15.3.3 Creating context-sensitive help content 556 15.3.4 Context extension point 557 15.3.5 Marker help 560 15.4 Accessing Help Programmatically 560 15.4.1 Opening a specific help page 561 15.4.2 Opening a Web page 562 15.5 Cheat Sheets 563 15.5.1 Using a cheat sheet 563 15.5.2 Creating a simple cheat sheet 565 15.5.3 Adding cheat sheet actions 568 15.6 RFRS Considerations 570 15.6.1 Provide help through help system (RFRS 3.7.2) 570 15.6.2 Provide all help via the help system (RFRS 5.3.7.1) 571 15.6.3 Context help activated using F1 (RFRS 5.3.7.2) 571 15.6.4 Implement active help (RFRS 5.3.7.3) 572 15.6.5 Use of stand-alone help (RFRS 5.3.7.4) 572 15.6.6 Use of additional documentation (RFRS 5.3.7.5) 572 15.6.7 Provide an overview of tasks flow (RFRS 5.3.5.34) 573 15.6.8 Illustrate only one task (RFRS 5.3.5.35) 573 15.6.9 Provide help link with each step (RFRS 5.3.5.36) 573 15.7 Summary 574

xxv Chapter 16 Internationalization 575 16.1 Externalizing the Plug-in Manifest 576 16.2 Externalizing Plug-in Strings 578 16.3 Using Fragments 587 16.3.1 New Fragment Project wizard 588 16.3.2 Fragment manifest file 591 16.3.3 Fragment project contents 593 16.4 Summary 594 Chapter 17 Creating New Extension Points 595 17.1 The Extension Point Mechanism 595 17.2 Defining an Extension Point 597 17.2.1 Creating an extension point 597 17.2.2 Creating an extension point schema 599 17.2.3 Extension point elements and attributes 601 17.2.4 Extension point element grammar 605 17.3 Code Behind an Extension Point 607 17.3.1 Parsing extension information 607 17.3.2 Constructing proxies 609 17.3.3 Creating executable extensions 611 17.3.4 Cleanup 613 17.4 Extension Point Documentation 614 17.5 Using the Extension Point 615 17.6 RFRS Considerations 617 17.6.1 Document extension points (RFRS 3.10.5) 617 17.6.2 Log errors (RFRS 5.3.10.1) 618 17.7 Summary 618

xxvi Contents Chapter 18 Features, Branding, and Updates 619 18.1 Feature Projects 620 18.1.1 Creating a new feature project 621 18.1.2 Feature manifest files 623 18.1.3 Feature manifest editor 624 18.2 Branding 631 18.2.1 The about.html file 632 18.2.2 The about.ini file 633 18.2.3 Product branding 635 18.3 Update Sites 637 18.3.1 Creating an update site project 637 18.3.2 The site.xml file 639 18.3.3 The update Web site 642 18.3.4 Revisiting the feature manifest 643 18.3.5 Accessing the update site 643 18.4 RFRS Considerations 647 18.4.1 Do not override product branding (RFRS 3.1.8) 647 18.4.2 Branded feature visibility (RFRS 5.3.1.9) 647 18.4.3 Include attribution information (RFRS 5.3.1.10) 647 18.4.4 about.html file contents (RFRS 5.3.1.11) 648 18.4.5 Splash screen restrictions (RFRS 5.3.1.12) 648 18.5 Summary 648 Chapter 19 Building a Product 651 19.1 A Brief Introduction to Ant 651 19.1.1 Build projects 651 19.1.2 Build targets 652 19.1.3 Build tasks 653 19.1.4 Build properties 657

xxvii 19.1.5 <antcall> task 664 19.1.6 macrodef 666 19.1.7 Headless Ant 668 19.1.8 Ant extensions 669 19.2 Building the Favorites Product 671 19.2.1 Auto-generated build script 671 19.2.2 Refactoring the Favorites build script 676 19.2.3 Compiling during the build process 689 19.2.4 Single versus multiple binaries 691 19.2.5 Editing with different versions of Eclipse 692 19.2.6 Building against different versions of Eclipse 693 19.2.7 Classpath tools 701 19.2.8 Building against Eclipse 3.0 703 19.2.9 Retargeting source code 705 19.2.10 Version checking 705 19.2.11 Building for internationalization 707 19.3 Summary 707 Chapter 20 Advanced Topics 709 20.1 Advanced Search Reference Projects 710 20.2 Accessing Internal Code 711 20.2.1 Eclipse newsgroup 711 20.2.2 Bugzilla Eclipse bug tracking system 712 20.2.3 Options for accessing internal code 712 20.2.4 How Eclipse is different 713 20.2.5 Related plug-ins 713 20.2.6 Using fragments 714

xxviii Contents 20.3 Adapters 714 20.3.1 IAdaptable 714 20.3.2 Using adapters 715 20.3.3 Adapter factory 715 20.3.4 IWorkbenchAdapter 718 20.4 Opening a Browser or Creating an Email 718 20.4.1 IWorkbenchBrowserSupport 718 20.4.2 LaunchURL 720 20.4.3 OpenEmailAction 720 20.5 Types Specified in an Extension Point 723 20.5.1 Parameterized types 724 20.5.2 Referencing a dass in a different plug-in 726 20.6 Modifying Eclipse to Find Part Identifiers 727 20.6.1 Modifying the Eclipse base 727 20.6.2 Creating the global action 729 20.6.3 Testing the new utility 731 20.6.4 Submitting the change to Eclipse 731 20.7 Label Decorators 732 20.7.1 Declaring a label decorator 733 20.7.2 ILightweightLabelDecorator 734 20.7.3 Decorative label decorators 736 20.7.4 IDecoratorManager 737 20.8 Background Tasks Jobs API 739 20.9 Plug-in ClassLoaders 742 20.10 Early Startup 747 20.10.1 Managing early startup 747 20.10.2 Disabling early startup 748 20.11 Rich Client Platform 748 20.12 Conclusion 749

xxix Appendix A Eclipse Plug-ins and Resources 751 A.1 Plug-ins 751 A.1.1 CodePro AnalytiX and CodePro PlusPak 751 A.1.2 EclipseProfiler 753 A.1.3 EclipseUML 754 A.1.4 MyEclipse Enterprise Workbench 755 A.1.5 WindowBuilder Pro 757 A.1.6 XMLBuddy 759 A.2 Resources 760 A.2.1 Eclipse.org 760 A.2.2 Eclipse Plug-in Central 762 A.2.3 Eclipse plug-in site 762 A.2.4 Eclipse wiki wiki 762 A.2.5 EclipseCon 762 A.2.6 ANTLR plug-in for Eclipse 762 A.2.7 Bugzilla plug-in 762 A.2.8 Coloring editor 762 A.2.9 Eclipse Easter eggs 763 A.2.10 IBM Alphaworks an Eclipse 763 A.2.11 IBM Eclipse research 763 A.2.12 PHP plug-in for Eclipse 763 A.2.13 QNX's Momentics 763 A.2.14 QuickShare: XP programming for Eclipse 763 A.2.15 Sangam: XP programming for Eclipse 763 Appendix B Ready for Rational Software 765 Index 767