Form Guide

In Nukkit-MOT, forms are divided into four types: Modal, Simple, Custom, and Dialog.

note

The Dialog type was added in PR#71 (version 1.20.30) and requires entity binding to function.

Modal Form

FormWindowModal are used for simple confirmation or cancellation actions.

Usage Example

form/DemoModalForm.java

package cn.nukkitmot.exampleplugin.form;

import cn.nukkit.Player;
import cn.nukkit.form.handler.FormResponseHandler;
import cn.nukkit.form.window.FormWindowModal;

public class DemoModalForm {
    public static void open(Player player) {
        FormWindowModal form = new FormWindowModal("Title", "Description", "true", "false");
        // Set actions for confirm and cancel
        form.addHandler(FormResponseHandler.withoutPlayer(ignored -> {
            if (form.wasClosed()) return;
            if (form.getResponse().getClickedButtonId() == 0) {
                // User clicked the true button
            } else {
                // User clicked the false button
            }
        }));
        // Show the form to the player
        player.showFormWindow(form);
    }
}

Simple Form

FormWindowSimple provide a richer selection of buttons.

Usage Example

form/DemoSimpleForm.java

package cn.nukkitmot.exampleplugin.form;

import cn.nukkit.Player;
import cn.nukkit.form.element.ElementButton;
import cn.nukkit.form.handler.FormResponseHandler;
import cn.nukkit.form.window.FormWindowSimple;

public class DemoSimpleForm {
    public static void open(Player player) {
        FormWindowSimple form = new FormWindowSimple("Title", "Description");
        // Add buttons
        form.addButton(new ElementButton("Button 1"));
        form.addButton(new ElementButton("Button 2"));
        form.addButton(new ElementButton("Button 3"));
        // Set button click handling
        form.addHandler(FormResponseHandler.withoutPlayer(ignored -> {
            if (form.wasClosed()) return;
            int buttonIndex = form.getResponse().getClickedButtonId(); // Get the clicked button index
            String buttonText = form.getResponse().getClickedButton().getText(); // Get the clicked button text
            switch (buttonIndex) {
                case 0:
                    // Handle button 1 action
                    break;
                case 1:
                    // Handle button 2 action
                    break;
                case 2:
                    // Handle button 3 action
                    break;
                default:
                    // Default handling
                    break;
            }
        }));
        // Show the form to the player
        player.showFormWindow(form);
    }
}

Components

Component Name	Description	Reference
Button	A button for simple click actions, can include images	ElementButton

Custom Form

FormWindowCustom allow developers to customize the content and interaction of the form, including text input boxes, dropdowns, etc.

Usage Example

form/DemoCustomForm.java

package cn.nukkitmot.exampleplugin.form;

import cn.nukkit.Player;
import cn.nukkit.form.element.ElementDropdown;
import cn.nukkit.form.element.ElementInput;
import cn.nukkit.form.handler.FormResponseHandler;
import cn.nukkit.form.window.FormWindowCustom;

import java.util.Arrays;

public class DemoCustomForm {
    public static void open(Player player) {
        FormWindowCustom form = new FormWindowCustom("Title");
        // Add elements
        form.addElement(new ElementInput("Text Input", "Default Value"));
        form.addElement(new ElementDropdown("Dropdown", Arrays.asList("Option 1", "Option 2", "Option 3")));
        // Set submission action
        form.addHandler(FormResponseHandler.withoutPlayer(ignored -> {
            if (form.wasClosed()) return;
            String inputText = form.getResponse().getInputResponse(0); // Get the text input value
            int selectedIndex = form.getResponse().getDropdownResponse(1).getElementID(); // Get the dropdown selection index
            String selectedText = form.getResponse().getDropdownResponse(1).getElementContent(); // Get the dropdown selection text
            // Handle user-submitted data
        }));
        // Show the form to the player
        player.showFormWindow(form);
    }
}

Components

Component Name	Description	Reference
Dropdown	A dropdown, displays a list of options for user selection	ElementDropdown
Input	Text input box, allows users to input strings	ElementInput
Label	Label, adds text labels to the form	ElementLabel
Slider	Horizontal slider, allows sliding to obtain numeric values after setting min and max values	ElementSlider
StepSlider	Step-based horizontal slider, parameter as a string	ElementStepSlider
Toggle	Toggle switch, accepts boolean values	ElementToggle

Dialog Form

FormWindowDialog are a special type of form that requires binding to an entity to function. The entity cannot be a player.

ScrollingTextDialog are enhanced versions of dialogs that provide scrolling text features.

Usage Example

normal

form/DemoDialogForm.java

package cn.nukkitmot.exampleplugin.form;

import cn.nukkit.Player;
import cn.nukkit.entity.Entity;
import cn.nukkit.form.window.FormWindowDialog;

public class DemoDialogForm {
    public static void open(Player player, Entity entity) {
        FormWindowDialog form = new FormWindowDialog("Title", "Description", entity);
        // Add options
        form.addButton("Option 1");
        form.addButton("Option 2");
        // Set submission action
        form.addHandler((player_, response) -> {
            String buttonText = response.getClickedButton().getName(); // Get the clicked button text
            // Handle user-submitted data
        });
        // Show the dialog to the player
        form.send(player);
    }
}

scrolling text

form/DemoScrollingTextDialog.java

package cn.nukkitmot.exampleplugin.form;

import cn.nukkit.Player;
import cn.nukkit.entity.Entity;
import cn.nukkit.form.window.FormWindowDialog;
import cn.nukkit.form.window.ScrollingTextDialog;

public class DemoScrollingTextDialog {
    public static void open(Player player, Entity entity) {
        FormWindowDialog dialog = new FormWindowDialog("Title", "Description", entity);
        // Add options
        dialog.addButton("Option 1");
        dialog.addButton("Option 2");
        // Set submission action
        dialog.addHandler((player_, response) -> {
            String buttonText = response.getClickedButton().getName(); // Get the clicked button text
            // Handle user-submitted data
        });
        ScrollingTextDialog form = new ScrollingTextDialog(player, dialog, 1);
        // Show the dialog to the player
        form.send(player);
    }
}