Add comprehensive UI Event Reference documentation for Eclipse E4

[Copilot]

Developers working with Eclipse E4 UI events had to guess event usage, payloads, and applicability by digging through source code. No single reference documented the semantic overview of available events, when they fire, and what data they carry.

Changes

Added docs/e4/UIEventReference.md (1,573 lines) providing:

• Event fundamentals: Subscription patterns (DI vs IEventBroker), event properties (EventTags), event types (SET/ADD/REMOVE/MOVE), utility methods
• Complete event catalog organized by category:
  • UI Lifecycle (activation, perspective operations, app startup/shutdown, theme changes)
  • Element containers (selected element, children modifications)
  • UI elements (visibility, rendering, widget lifecycle, parent relationships)
  • Labels (text, icons, tooltips)
  • Parts, perspectives, windows (menus, toolbars, trim bars)
  • Commands, handlers, bindings
  • State tracking (dirty state, tags, persisted/transient data)
  • Renderer events (enablement updates)
• Practical examples: Each event type includes code showing proper subscription, payload extraction, and common filtering patterns
• Best practices: Event filtering, collection handling, avoiding cycles, cleanup patterns
• Common use cases: Part tracking, perspective monitoring, dirty state management, tag-based behavior

Example

Listen to perspective switches in a part stack:

@Inject
@Optional
public void trackPerspective(
        @UIEventTopic(UIEvents.ElementContainer.TOPIC_SELECTEDELEMENT) Event event) {
    
    Object element = event.getProperty(UIEvents.EventTags.ELEMENT);
    
    if (element instanceof MPerspectiveStack) {
        MPerspective persp = (MPerspective) event.getProperty(UIEvents.EventTags.NEW_VALUE);
        // React to perspective change
    }
}

Links to source code (UIEvents.java, UIEventPublisher.java), platform examples (PerspectiveSwitcher, PartRenderingEngine), and external tutorials included for deeper exploration.

Original prompt

Describe the different UI events and their payloads

We have Event_Processing.md that generally describes events and we have docs/Event_Model.md that quite basically describe using Dependency Injection

Also a short section about UI Model Events but most of it is described in the code bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/UIEvents.java and this is heavily used
acrross the codebase. Also there are some tutorials covering some specific topics here https://www.vogella.com/tutorials/Eclipse4ModelEvents/article.html and https://www.vogella.com/tutorials/Eclipse4EventSystem/article.html

But when it comes to using them one most of the time has to guess a little bit for what use cases what event is used what are the payloads and so on.

Because of that we want a new file docs/e4/UIEventReference.md that should give a good semantic overview, so we do not need to goo to much into the details (we can link the other documents for reference or enhance them if needed)
or have excessive code snippets but instead having a good reference to look thorugh e.g. one might wonder how to listen to perspective changes, enablment changes or selection of parts in part stacks.

This is very important for our users so we need to be clear and complete!

We can then give a short example for each with the important payloads e.g.

--

Some Headline e.g. Listen to elementcontainer changes

Eelement Containers that produces this event are: A, B, C and the topic allows to be informed about blabla.

You usually would use it in your code like this

@Inject
@optional
public void subscribeTopicSelectedElement(
@EventTopic(UIEvents.ElementContainer.TOPIC_SELECTEDELEMENT) Event event) {
Object newValue = event.getProperty(EventTags.NEW_VALUE);

}

And now list what could newValue be?!? Are there more interesting things? Maybe a table would be good here

As the java documentation is rather vague we need to carefully and completely investigate the source code where such events are produced to recover the details, we also should look at the code smaples where it is used in this repository and the related repositories at https://github.com/eclipse-platform/eclipse.platform and https://github.com/eclipse-pde/eclipse.pde!

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.