This page documents the event handler pattern used uniformly across all patternfly-java components. It covers the functional interface types in org.patternfly.handler, the on<Event>() registration convention, how handlers are stored (as lists), and how they are fired. It also covers the item lifecycle handlers (AddItemHandler, UpdateItemHandler, RemoveItemHandler) and the AurHandler helper.
For how components use these handlers as part of their fluent builder API, see 4.1. For collection lifecycle management (add/remove/update items in HasItems), see 4.2. For specific component event APIs, see the component pages starting at 5.
All shared handler types live in the org.patternfly.handler package, inside the patternfly-java-core module. Each is a @FunctionalInterface, making lambda expressions the idiomatic registration syntax.
| Interface | Method | Parameters |
|---|---|---|
ChangeHandler<C, V> | onChange | (Event e, C component, V value) |
SelectHandler<T> | onSelect | (Event e, T item, boolean selected) |
MultiSelectHandler<C, T> | onSelect | (Event e, C component, List<T> items) |
ToggleHandler<C> | onToggle | (Event e, C component, boolean expanded) |
CloseHandler<T> | onClose | (Event e, T component) |
ComponentHandler<C> | handle | (Event e, C component) |
ResizeHandler | onResize | (breakpoint-specific parameters) |
Item lifecycle handlers live in org.patternfly.component and are used with HasItems:
| Interface | Fired When |
|---|---|
AddItemHandler<C, S> | An item is added to a HasItems component |
UpdateItemHandler<C, S> | An item is updated in a HasItems component |
RemoveItemHandler<C, S> | An item is removed from a HasItems component |
C is the parent component type; S extends HasIdentifier<?, ?> is the child item type.
Sources: components/src/main/java/org/patternfly/component/menu/Menu.java109-111 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java86-87 components/src/main/java/org/patternfly/component/tree/TreeView.java98-100 components/src/main/java/org/patternfly/component/tabs/Tabs.java140-142
Handler Interface Hierarchy
Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java194-207 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java226-232
on<Event>() ConventionEvery event hook follows a uniform signature:
public ComponentType on<Event>(HandlerType handler) {
this.handlerList.add(handler);
return this;
}
on<Event> (e.g., onToggle, onSingleSelect, onClose)this, enabling fluent chaining with other builder callson<Event>() method add multiple handlers; all fire in orderFrom components/src/main/java/org/patternfly/component/menu/Menu.java217-225:
From components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java226-234:
Sources: components/src/main/java/org/patternfly/component/menu/Menu.java210-225 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java224-234 components/src/main/java/org/patternfly/component/tabs/Tabs.java140-143
Each component stores its handlers in a private final List<HandlerType> field, initialized in the constructor. The following table shows representative examples:
| Component | Field Name | Type |
|---|---|---|
Menu | selectHandler | List<SelectHandler<MenuItem>> |
Menu | multiSelectHandler | List<MultiSelectHandler<Menu, MenuItem>> |
MenuToggleMenu<B> | toggleHandler | List<ToggleHandler<B>> |
MenuToggleMenu<B> | loadedHandler | List<ComponentHandler<B>> |
MenuItem | onClickHandler | List<ComponentHandler<MenuItem>> |
TreeView | selectHandler | List<SelectHandler<TreeViewItem>> |
TreeView | multiSelectHandler | List<MultiSelectHandler<TreeView, TreeViewItem>> |
TreeView | toggleHandler | List<ToggleHandler<TreeViewItem>> |
Tabs | selectHandler | List<SelectHandler<Tab>> |
Tabs | closeHandler | List<CloseHandler<Tab>> |
Tabs | toggleHandler | List<ToggleHandler<Tabs>> |
Navigation | selectHandler | List<SelectHandler<NavigationItem>> |
TreeViewItem | toggleHandler | List<ToggleHandler<TreeViewItem>> |
LabelGroup | closeHandler | List<CloseHandler<...>> |
Sources: components/src/main/java/org/patternfly/component/menu/Menu.java108-111 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java86-88 components/src/main/java/org/patternfly/component/menu/MenuItem.java163-164 components/src/main/java/org/patternfly/component/tree/TreeView.java98-100 components/src/main/java/org/patternfly/component/tabs/Tabs.java140-142
When the triggering condition occurs (a DOM click, a keyboard event, a programmatic state change), the component iterates its handler list and invokes each handler.
Firing a SelectHandler — from components/src/main/java/org/patternfly/component/menu/Menu.java430-432:
Firing a MultiSelectHandler — from components/src/main/java/org/patternfly/component/menu/Menu.java434-439:
Firing a ToggleHandler (collapse path) — from components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java239-247:
Firing a ComponentHandler (loaded) — from components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java256-260:
A key detail: when a handler fires programmatically (not from a real user gesture), the event is a synthetic new Event(""). This lets handlers inspect the event type when needed, while still working when invoked programmatically.
Sources: components/src/main/java/org/patternfly/component/menu/Menu.java430-440 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java239-262
Sequence: registration → trigger → fire
Sources: components/src/main/java/org/patternfly/component/menu/Menu.java212-225 components/src/main/java/org/patternfly/component/menu/Menu.java330-354 components/src/main/java/org/patternfly/component/menu/Menu.java430-440
AurHandlerComponents that implement HasItems expose three lifecycle hooks via AurHandler. AurHandler is a helper class that stores the three lists internally and delegates onAdd, onUpdate, and onRemove registrations:
From components/src/main/java/org/patternfly/component/tree/TreeView.java97 and components/src/main/java/org/patternfly/component/tree/TreeView.java194-207:
The add() method in TreeView calls aur.added(item) after appending the item to the DOM, which fires the registered AddItemHandler lambdas. Similarly removed() fires RemoveItemHandler lambdas.
AurHandler is used in: TreeView, TreeViewItem, Navigation, NavigationGroup, ExpandableNavigationGroup, Tabs, JumpLinks, AlertGroup, LabelGroup, ToolbarContent, and others.
Sources: components/src/main/java/org/patternfly/component/tree/TreeView.java97 components/src/main/java/org/patternfly/component/tree/TreeView.java152-157 components/src/main/java/org/patternfly/component/tree/TreeView.java194-207 components/src/main/java/org/patternfly/component/HasItems.java1-50
Which handler types each major component uses
Sources: components/src/main/java/org/patternfly/component/menu/Menu.java210-225 components/src/main/java/org/patternfly/component/menu/MenuToggleMenu.java224-234 components/src/main/java/org/patternfly/component/tree/TreeView.java192-215 components/src/main/java/org/patternfly/component/tabs/Tabs.java140-143 components/src/main/java/org/patternfly/component/navigation/Navigation.java43-44
Some components define their own functional interfaces outside org.patternfly.handler for domain-specific callbacks:
| Interface | Package | Purpose |
|---|---|---|
MenuActionHandler | o.p.component.menu | Fired when an action-type MenuItem is activated |
SearchFilter | o.p.component.menu | Predicate deciding which MenuItems match a search string |
NoResults | o.p.component.menu | Factory for a MenuItem displayed when search yields no matches |
These follow the same on<Event>() registration convention:
From components/src/main/java/org/patternfly/component/menu/MenuSearch.java110-126:
The same onSearch / onNoResults pattern appears on SingleTypeahead and MultiTypeahead via the Typeahead<M> interface in components/src/main/java/org/patternfly/component/menu/Typeahead.java
Sources: components/src/main/java/org/patternfly/component/menu/MenuSearch.java98-126 components/src/main/java/org/patternfly/component/menu/SingleTypeahead.java115-125 components/src/main/java/org/patternfly/component/menu/MultiTypeahead.java143-155
As of version 0.2.9, all components support registering multiple handlers for the same event. Each call to on<Event>() appends to the list rather than replacing. All registered handlers fire in registration order.
This applies uniformly to every on<Event>() method in the library. There is no built-in mechanism to deregister an individual handler after registration; the list is package-private or private.
Sources: CHANGELOG.md296-300
Refresh this wiki