GUI Plugins (Toolbars, Menus, Panels)

The @GuiPlugin annotation allows you to extend the Hop GUI without subclassing existing GUI classes. A class marked with @GuiPlugin is scanned for contribution annotations that attach buttons, menus, shortcuts, tabs, or custom composite panels to existing GUI elements.

Common Contribution Annotations

Annotation Functionality

Annotation	Functionality
`@GuiToolbarElement`	Adds a button, toggle, or custom composite widget to an existing toolbar.
`@GuiToolbarElementFilter`	Conditionally shows or hides a toolbar element based on context.
`@GuiMenuElement`	Adds a menu entry into the top-level Hop GUI menu bar.
`@GuiContextAction`	Adds an action to canvas right-click context menus.
`@GuiWidgetElement`	Declares a settings widget (text, metadata combo, checkbox, file browser) inside dialogs.
`@GuiTab`	Adds a new tab to an existing tab folder.

@GuiToolbarElement

Adds a button, toggle, or custom composite widget to an existing toolbar.

@GuiToolbarElementFilter

Conditionally shows or hides a toolbar element based on context.

@GuiMenuElement

Adds a menu entry into the top-level Hop GUI menu bar.

@GuiContextAction

Adds an action to canvas right-click context menus.

@GuiWidgetElement

Declares a settings widget (text, metadata combo, checkbox, file browser) inside dialogs.

@GuiTab

Adds a new tab to an existing tab folder.

1. Adding a Toolbar Button

Toolbar elements bind to a parent container via parentId and sort alphabetically by id (conventionally using numeric prefixes):

java

import org.apache.hop.core.gui.plugin.GuiPlugin;
import org.apache.hop.core.gui.plugin.toolbar.GuiToolbarElement;
import org.apache.hop.core.gui.plugin.toolbar.GuiToolbarElementType;
import org.apache.hop.ui.hopgui.HopGui;

@GuiPlugin
public class CustomToolbarItem {

  public static final String TOOLBAR_ITEM_ID = "10500-my-custom-action";

  @GuiToolbarElement(
      root = HopGui.ID_MAIN_TOOLBAR,
      id = TOOLBAR_ITEM_ID,
      type = GuiToolbarElementType.BUTTON,
      image = "custom-action.svg",
      toolTip = "Execute Custom Task"
  )
  public void executeAction() {
    HopGui hopGui = HopGui.getInstance();
    // Perform action
    hopGui.getLog().logBasic("Custom toolbar action executed!");
  }
}

2. Adding Custom Panels and Widgets to Toolbars

Toolbars can also host complex composites (such as combo boxes, search bars, or progress meters) by specifying type = GuiToolbarElementType.CUSTOM:

java

import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Combo;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;

@GuiPlugin
public class SearchLocationItem {

  @GuiToolbarElement(
      root = HopGui.ID_MAIN_TOOLBAR,
      id = "20000-search-location",
      type = GuiToolbarElementType.CUSTOM
  )
  public Control createSearchControl(Composite parent) {
    Combo combo = new Combo(parent, SWT.DROP_DOWN | SWT.READ_ONLY);
    combo.setItems("All", "Pipelines", "Workflows", "Metadata");
    combo.select(0);
    return combo;
  }
}

3. Declarative Dialog Widgets (`@GuiWidgetElement`)

Annotate fields on the metadata class instead of laying out SWT controls by hand. Field types, groups, and the dialog open() recipe are Annotation derived widgets.

Concrete Codebase Examples

ui/src/main/java/org/apache/hop/ui/hopgui/notifications/NotificationToolbarItem.java: Toolbar button contributed with @GuiToolbarElement.
ui/src/main/java/org/apache/hop/ui/core/gui/GuiCompositeWidgets.java: Turns @GuiWidgetElement annotations into SWT controls.