First version of event-dispatcher documentation. #372
Conversation
EHandtkeBasis
requested review from
MatthewHawkins,
bbrennanbasis,
hyyan,
mschned and
nmlynx
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| - Always remove listeners when they're no longer needed to avoid memory leaks. | ||
| - Use the provided event payload methods to access event data efficiently, avoiding unnecessary client-server round-trips. | ||
| - Prefer using component APIs for event handling unless you have advanced requirements. | ||
| - Use registration options (payload, debounce, filter) to optimize performance and event data handling. |
There was a problem hiding this comment.
[webforJ.BeDirect] Avoid using 'optimize performance and event'. Focus more on explicitly giving details about the feature.
| ## Event dispatcher APIs | ||
|
|
||
| [`EventDispatcher`](https://webforj.com/javadoc/com/webforj/dispatcher/EventDispatcher.html) is a minimalistic event manager for dispatching events to listeners. It's not tied to UI components or element events. | ||
|
|
||
| **Available methods:** | ||
|
|
||
| - `addListener(Class<T> eventClass, EventListener<T> listener)`: Registers a listener for a specific event type. Returns a `ListenerRegistration<T>` for later removal. | ||
| - `removeListener(Class<T> eventClass, EventListener<T> listener)`: Removes a specific listener for the given event type. | ||
| - `removeAllListeners(Class<T> eventClass)`: Removes all listeners for a given event type. | ||
| - `removeAllListeners()`: Removes all listeners from the dispatcher. | ||
| - `dispatchEvent(T event)`: Notifies all listeners of the given event. |
There was a problem hiding this comment.
Remove this section, a list of methods is already available in the Java Docs.
| ## Best practices | ||
|
|
||
| - Always remove listeners when they're no longer needed to avoid memory leaks. | ||
| - Use the provided event payload methods to access event data efficiently. | ||
| - Use the EventDispatcher for custom, non-UI event flows. For UI/component events, see the relevant component documentation. |
There was a problem hiding this comment.
The first bullet point in the best practices could be expanded upon into it's own section, covering when to remove listeners, how to, and why. Please be specific when writing why removing listeners prevent memory leaks and avoid using a generic "optimizes performance" explanation.
| statusText.setStyle("border", "2px solid #333"); | ||
| statusText.setStyle("padding", "8px 24px"); | ||
| statusText.setStyle("border-radius", "var(--dwc-border-radius-s)"); | ||
| statusText.setStyle("font-size", "var(--dwc-font-size-l)"); | ||
| statusText.setStyle("background", "var(--dwc-surface-3)"); |
There was a problem hiding this comment.
I highly suggest replacing the multiple setStyle() calls with an InlineStyleSheet annotation and giving the statusText component a class name:
.statusText {
border: 2px solid #333;
border-radius: var(--dwc-border-radius-s);
padding: 8px 24px;
font-size: var(--dwc-font-size-l);
background: var(--dwc-surface-3);
}| dispatcher.addListener(CustomMessageEvent.class, e -> { | ||
| statusText.setText("Received custom event"); | ||
| button.setEnabled(false); | ||
| }); |
There was a problem hiding this comment.
Currently, the dispatcher event can only fire once. Add a way to be able to restart the sample, or create another button that can also fire the dispatcher event with different text.
hyyan
added
the
status: waiting-for-review
No description provided.