|
| 1 | +# Eclipse 4 Model |
| 2 | + |
| 3 | +## Contributing to the E4 Application Model |
| 4 | + |
| 5 | +This document provides guidance on contributing to the Eclipse 4 application model through model fragments and extensions. |
| 6 | + |
| 7 | +## Model Fragments |
| 8 | + |
| 9 | +Model fragments allow you to contribute UI elements to the E4 application model declaratively. All E4 contributions are made through model fragments rather than traditional Eclipse 3.x extension points. |
| 10 | + |
| 11 | +### Creating a Model Fragment |
| 12 | + |
| 13 | +1. **Create the fragment file**: Create a `fragment.e4xmi` file in your bundle's root or in a `model/` folder. |
| 14 | + |
| 15 | +2. **Register in plugin.xml**: Add an extension to your plugin.xml: |
| 16 | + ```xml |
| 17 | + <extension |
| 18 | + id="fragment" |
| 19 | + point="org.eclipse.e4.workbench.model"> |
| 20 | + <fragment |
| 21 | + uri="fragment.e4xmi"> |
| 22 | + </fragment> |
| 23 | + </extension> |
| 24 | + ``` |
| 25 | + |
| 26 | +3. **Edit with E4 Model Editor**: Open the fragment.e4xmi with the "Eclipse 4 Model Editor" (right-click → Open With → E4 Model Editor). |
| 27 | + |
| 28 | +### Fragment Structure |
| 29 | + |
| 30 | +A basic fragment structure looks like: |
| 31 | + |
| 32 | +```xml |
| 33 | +<?xml version="1.0" encoding="ASCII"?> |
| 34 | +<fragment:ModelFragments xmi:version="2.0" |
| 35 | + xmlns:xmi="http://www.omg.org/XMI" |
| 36 | + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| 37 | + xmlns:commands="http://www.eclipse.org/ui/2010/UIModel/application/commands" |
| 38 | + xmlns:fragment="http://www.eclipse.org/ui/2010/UIModel/fragment"> |
| 39 | + <!-- fragments go here --> |
| 40 | +</fragment:ModelFragments> |
| 41 | +``` |
| 42 | + |
| 43 | +### Types of Contributions |
| 44 | + |
| 45 | +Model fragments can contribute various elements: |
| 46 | + |
| 47 | +- **Commands**: Define semantic actions |
| 48 | +- **Handlers**: Implement command behavior |
| 49 | +- **Parts (Views/Editors)**: UI containers via PartDescriptors |
| 50 | +- **Menu Contributions**: Menus, toolbars, and context menus |
| 51 | +- **Key Bindings**: Keyboard shortcuts |
| 52 | +- **Addons**: Application lifecycle hooks |
| 53 | + |
| 54 | +### String Model Fragments |
| 55 | + |
| 56 | +The most common fragment type is `StringModelFragment`, which targets a specific feature of a parent element: |
| 57 | + |
| 58 | +```xml |
| 59 | +<fragments xsi:type="fragment:StringModelFragment" |
| 60 | + featurename="commands" |
| 61 | + parentElementId="org.eclipse.e4.legacy.ide.application"> |
| 62 | + <elements xsi:type="commands:Command" |
| 63 | + elementId="com.example.mycommand" |
| 64 | + commandName="My Command"/> |
| 65 | +</fragments> |
| 66 | +``` |
| 67 | + |
| 68 | +Key attributes: |
| 69 | +- **featurename**: The model feature to contribute to (e.g., `commands`, `handlers`, `descriptors`, `menuContributions`) |
| 70 | +- **parentElementId**: The ID of the parent element (typically your application ID or `org.eclipse.e4.legacy.ide.application`) |
| 71 | + |
| 72 | +### Importing Model Elements |
| 73 | + |
| 74 | +To reference elements defined in other fragments or the application model: |
| 75 | + |
| 76 | +1. Select "Imports" in the fragment editor |
| 77 | +2. Add the appropriate import type (Command, Part, etc.) |
| 78 | +3. Set the Element ID to match the target element's ID |
| 79 | + |
| 80 | +**Note**: Only fragments can import elements from the application model or other fragments. Application models cannot import from fragments. |
| 81 | + |
| 82 | +### Element IDs |
| 83 | + |
| 84 | +- Element IDs (`elementId`) are used to identify model elements |
| 85 | +- Unlike EMF's internal `xmi:id`, element IDs should be human-readable |
| 86 | +- For certain elements (like Commands), element IDs must be unique |
| 87 | +- When migrating from E3, always preserve the original IDs |
| 88 | + |
| 89 | +### Model Editor Tips |
| 90 | + |
| 91 | +- Use the E4 Model Editor (included in Eclipse IDE for RCP development) |
| 92 | +- The editor provides validation and helps ensure proper model structure |
| 93 | +- Changes to fragments require `-clearPersistedState` flag during development to see effects |
| 94 | + |
| 95 | +## Application Model |
| 96 | + |
| 97 | +The application model (`Application.e4xmi`) defines the core structure of your E4 application: |
| 98 | + |
| 99 | +- **Windows**: Top-level containers |
| 100 | +- **Perspectives**: Layouts of parts |
| 101 | +- **Part Stacks**: Containers for parts (views/editors) |
| 102 | +- **Trim Bars**: Toolbars and status bars |
| 103 | +- **Handlers**: Global command handlers |
| 104 | +- **Bindings**: Key bindings |
| 105 | +- **Snippets**: Reusable UI fragments |
| 106 | + |
| 107 | +## Additional Resources |
| 108 | + |
| 109 | +- [Eclipse4 RCP FAQ](Eclipse4_RCP_FAQ.md) - Common questions about E4 |
| 110 | +- [Eclipse4 Migration Guide](Eclipse4_Migration.md) - Migrating from E3 to E4 |
| 111 | +- [Eclipse Wiki - Contributing to the Model](https://wiki.eclipse.org/Eclipse4/RCP/Modeled_UI/Contributing_to_the_Model) - Detailed Wiki article |
| 112 | + |
| 113 | +## Best Practices |
| 114 | + |
| 115 | +1. **Use meaningful element IDs**: Choose descriptive IDs that clearly indicate purpose |
| 116 | +2. **Keep fragments focused**: Create separate fragments for different contribution types |
| 117 | +3. **Document your model**: Add descriptions to help others understand your contributions |
| 118 | +4. **Test with -clearPersistedState**: Model changes only apply when state is cleared |
| 119 | +5. **Preserve E3 IDs when migrating**: Maintain compatibility by keeping the same IDs |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +*This guide is maintained as part of the Eclipse Platform UI project and evolves with the codebase.* |
0 commit comments