Custom Widgets 1.20.4

Learn how to create custom widgets for your screens.

WARNING

This page is written for version 1.20.4. Documentation for older versions may be incomplete.

Widgets are essentially containerized rendering components that can be added to a screen, and can be interacted with by the player through various events such as mouse clicks, key presses, and more.

Creating a Widget

There are multiple ways to create a widget class, such as extending AbstractWidget. This class provides a lot of useful utilities, such as managing width, height, position, and handling events - it implements the Renderable, GuiEventListener, NarrationSupplier, and NarratableEntry interfaces:

• Renderable - for rendering - Required to register the widget to the screen via the addRenderableWidget method.
• GuiEventListener - for events - Required if you want to handle events such as mouse clicks, key presses, and more.
• NarrationSupplier - for accessibility - Required to make your widget accessible to screen readers and other accessibility tools.
• NarratableEntry - for selection - Required if you want to make your widget selectable using the Tab key - this also aids in accessibility.

public class CustomWidget extends AbstractWidget {
	public CustomWidget(int x, int y, int width, int height) {
		super(x, y, width, height, Component.empty());
	}

	@Override
	protected void renderWidget(GuiGraphics context, int mouseX, int mouseY, float delta) {
		// We'll just draw a simple rectangle for now.
		// x1, y1, x2, y2, startColor, endColor
		int startColor = 0xFF00FF00; // Green
		int endColor = 0xFF0000FF; // Blue

		context.fillGradient(getX(), getY(), getX() + this.width, getY() + this.height, startColor, endColor);
	}

	@Override
	protected void updateWidgetNarration(NarrationElementOutput builder) {
		// For brevity, we'll just skip this for now - if you want to add narration to your widget, you can do so here.
		return;
	}
}

Adding the Widget to the Screen

Like all widgets, you need to add it to the screen using the addRenderableWidget method, which is provided by the Screen class. Make sure you do this in the init method.

// Add a custom widget to the screen.
// x, y, width, height
CustomWidget customWidget = new CustomWidget(40, 80, 120, 20);
this.addRenderableWidget(customWidget);

Widget Events

You can handle events such as mouse clicks, key presses, by overriding the mouseClicked, afterMouseAction, keyPressed, and other methods.

For example, you can make the widget change color when it's hovered over by using the isHovered() method provided by the AbstractWidget class:

// This is in the "renderWidget" method, so we can check if the mouse is hovering over the widget.
if (isHovered()) {
	startColor = 0xFFFF0000; // Red
	endColor = 0xFF00FFFF; // Cyan
}