Widgets/Custom

Widget Group

Widget Group

The Widget Group is a powerful tool allowing users to create custom widgets by grouping other widgets together. It enables users to encapsulate complex workflows into reusable components with input ports, output ports, and settings.

 

Custom Settings

The Widget Group widget offers customization through its settings panel. Each setting has the following properties:



Widget Details

  • Name (DataType: String): The name of the custom widget. This field is required

  • Description (DataType: String): The description of the custom widget. This field is optional. It is best practice to provide a useful description for your widget.

  • Color (DataType: String): The color of the custom widget. The default color is #4E3EFF

  • Icon: The icon of the custom widget. The default icon is folder



Input Ports

The Widget Group widget can have any number of inputs, each with its own data type. By default, it starts with a single input:

  • input (DataType: Anything): The default input port that accepts any type of data


Output Ports

The Widget Group widget can have any number of outputs, each with its own data type. By default, it starts with a single output:

  • output (DataType: Anything): The default output port that can transmit any type of data


Settings

Users can further customize their widget via the Setting Tab. Customized setting is called an Element. Click on “+ Element” to add. To see the values (eg. Default, Mix and Max) users can click on the Gear icon next to your Element.

  • Field Type – The type of input field. Each field type has its own configuration options:

    • Text (DataType: String): A UI field for string inputs

      • For string inputs
      • Placeholder text
      • Default value
      • Password mode (hide input) - When enabled, values are hidden and displayed as asterisks (***)
      • Multiline support - When enabled, the Text field becomes a long text input field
      • Width/Height (for text areas)

    • Number (DataType: Number):

      • For numeric inputs
      • Placeholder text
      • Default value

    • Slider (DataType: Number):

      • For numeric inputs with a range
      • Minimum value
      • Maximum value
      • Step size
      • Default value

    • Dropdown (DataType: String):

      • For selecting from predefined options
      • List of options
      • Default value

    • Checkbox (DataType: Boolean):

      • For boolean inputs
      • Default value - Specifies whether the checkbox is selected by default

    • MultiSelect (DataType: Array):

      • For selecting multiple options
      • List of options
      • Default values - A comma-separated list of values that are selected by default

  • Label (DataType: String): A human-readable label that describes the setting

  • Hidden Field (DataType: Boolean): When enabled, the setting is only visible when users enter the widget's Custom Settings

  • Variable Name (DataType: String): The name of the variable that will store the setting value. This name is used to access the setting value in your widget's logic. For example, you can use Kemu.variable.onUIValueChange() to detect changes originating from UI elements defined in these settings. These listeners allow your custom widget to react dynamically to user input or configuration changes.

For instance, if you define a variable name My.Custom.Var for a UI field (e.g., a Text input or Slider in the settings), you would use onUIValueChange in the following way:

Kemu.variable.onUIValueChange('My.Custom.Var', async (evt) => {
  // This function will be called whenever the UI element's value changes
  console.log('My UI element value:', evt.value);
});

The event object (evt) passed to the handler has the following structure (VarValueChangeEvt):

  • value: The new value of the variable
  • type: The DataType of the variable
  • varName: The name of the variable that changed (for onUIValueChange, this will be the internally-scoped name, e.g., "UI:My.Custom.Var")
  • isUIElement: A boolean indicating if the change originated from a UI element
  • setByWidgetType: The WidgetType of the widget that set the value
  • setByWidgetId: The ID of the widget that set the value

To obtain the current value of a UI field variable, you can also use Kemu.variable.getUIValue():

const variable = Kemu.variable.getUIValue('my-var-name');
console.log(`The value of the UI field (type ${variable.type}) variable is ${variable.value}`);

Important: This function is only available from inside WidgetGroups with pre-defined UI field variables. Attempting to read a field variable from outside a WidgetGroup will throw an error.


Help Documentation

You can add Help Documentation to your custom widget. Displayed when users click on the widget's help icon (?). The Help Documentation supports markdown formatting, allowing you to:

  • Add headings, lists, and tables
  • Include code blocks with syntax highlighting
  • Add links and images
  • Format text with bold, italic, and other styles

 

Creating a Custom Widget

To create a new custom widget:

  1. Right-click on the workspace and select "Create custom widget" from the context menu
  2. In the "Create" custom widget` modal:
    • Enter a descriptive name for your widget
    • Add a description to help others understand its purpose (optional)
    • Choose a color to visually identify your widget (optional)
    • Define the input and output port names that your widget will use
    • Click "Save" to create the widget
  3. Your new custom widget will appear in the workspace
  4. Double-click the widget to enter its internal workspace (indicated by a dark background)



Defining the Logic of the Custom Widget

Inside the internal workspace, follow these steps:

  1. Drag and drop widgets from the widget drawer to create your desired logic
  2. Connect the widgets together to build your workflow
  3. Connect your custom input and output ports (displayed on the left and right edges of the workspace) to ensure your logic receives and transmits data correctly

Creating custom widget logic



Saving the Custom Widget

While in the internal workspace (dark screen):

  1. In the left sidebar menu, click on the Save Widget icon (box with an upward arrow ⬆️) to save your changes
  2. Your saved widget will appear in the "Custom Widgets" → "My Widgets" drawer, ready to be reused in any workspace
  3. Each time you save your widget, its version number increases by one (hover over the widget to see the current version)

Important: Whenever you make changes to your custom widget, you must follow the steps outlined above to save your changes, otherwise changes will not be preserved.




Exiting the Custom Widget Workspace

To return to the main workspace:

  1. Click the "Workspace" breadcrumb link in the top-right corner

Exiting the Custom Widget workspace



Editing a Custom Widget

To modify your custom widget's settings:

  1. Right-click on the widget to open the context menu
  2. Select "Edit group" to access the settings panel where you can modify:
    • Basic properties (name, description, color, icon)
    • Input and output ports
    • Widget-specific settings
    • Help documentation

 

Examples


Basic Custom Widget

This example demonstrates how to create a simple custom widget that processes a number input and displays the result:

Drag the example onto the workspace to explore and experiment!



In this example:

  1. A custom widget named Number Processor is created
  2. The widget has a single input port (in) that receives numbers
  3. It has a single output port (out) that transmits the processed result
  4. The Slider widget is used to send values (from 0 to 10) to the custom widget
  5. Inside the custom widget, the input number is multiplied by 2 (as defined in the internal logic)
  6. The result is transmitted to the Display widget, which shows the output on the screen

 

Advanced Custom Widget: Rect Widget with Dynamic Output

This example demonstrates how to create a custom Rect widget that transmits a rectangle object based on user-configurable sliders for its position and size. The widget exposes a single output port (rect) of type Rect, and its values are dynamically updated whenever you change any of the slider settings.


Required Configuration




Step 1: Configure the Custom Widget Details

  • Create a new Custom Widget
  • Set the widget name to Rect.
  • Remove all input ports.
  • Add an output port named rect and set its Data Type to Rect.

Step 2: Configure the Custom Widget Settings

  • Create four Slider fields: top, left, width, and height.

  • Set the Variable Name for each slider to Rect.top, Rect.left, Rect.width, and Rect.height respectively.

  • Ensure all fields are visible by unchecking the Hidden Field option for each one.

  • Click Save to apply your settings.


Step 3: Define the Custom Widget Logic

  • Double-click the Rect custom widget to enter its internal workspace.

  • Drag a Script widget into the workspace and replace its code with the following:

// No inputs for this widget
const getWidgetInputs = () => [];
// One output: 'rect' of type DataType.Rect
const getWidgetOutputs = () => [{ name: 'rect', type: DataType.Rect }];

// Store the latest values for the rectangle
let lastValues = {
  left: 0,
  top: 0,
  width: 100,
  height: 100,
};

// Helper function to send the current rectangle to the output port
const dispatchRect = () => {
  return sendToPort('rect', {
    type: DataType.Rect,
    value: lastValues,
  });
};

// Listen for changes to each slider variable and update the rectangle
Kemu.variable.onUIValueChange('Rect.top', async (event) => {
  lastValues.top = event.value;
  dispatchRect();
});

Kemu.variable.onUIValueChange('Rect.left', async (event) => {
  lastValues.left = event.value;
  dispatchRect();
});

Kemu.variable.onUIValueChange('Rect.width', async (event) => {
  lastValues.width = event.value;
  dispatchRect();
});

Kemu.variable.onUIValueChange('Rect.height', async (event) => {
  lastValues.height = event.value;
  dispatchRect();
});

// Load the initial UI values and initialize our local var
const main = async() => {
  const { value: top } = Kemu.variable.getUIValue('Rect.top');
  const { value: left } = Kemu.variable.getUIValue('Rect.left');
  const { value: width } = Kemu.variable.getUIValue('Rect.width');
  const { value: height } = Kemu.variable.getUIValue('Rect.height');
  
  lastValues.top = top;
  lastValues.left = left;
  lastValues.width = width;
  lastValues.height = height;
}

  • Connect the Script widget's output port to the rect output port of the custom widget.

  • Click the Save Widget icon to save your changes.

  • Exit the widget's internal workspace.

Your Rect custom widget is now ready to use in your recipe


Drag the example onto the workspace to explore and experiment!



In this example:

  1. A custom widget named Rect is created
  2. The widget has no input ports
  3. It has a single output port (rect) that transmits the rectangle area
  4. The rectangular area values top, left, width, and height are set by adjusting the Rect widget's sliders alongside the source image
  5. The Extract Image widget takes the original image and the rectangle values from the custom Rect widget
  6. The extracted image is generated using the Rect widget's values and shown in the Display widget

 

📌 Additional Notes

  • Custom widgets can be shared with other users through collections
  • The widget automatically handles port mapping between inner and outer connections
  • Custom widgets can be used to create reusable components and simplify complex workflows
  • Custom settings can be used to configure widget behavior without modifying the internal workflow
  • Custom widgets can be used to create domain-specific solutions and extend Kemu's functionality

 

Glossary

  • Input Port

    A connection point on the left side of a widget that receives data from other widgets.

  • Output Port

    A connection point on the right side of a widget that transmits data to other widgets.

  • Internal Workspace

    The dark-background workspace inside a custom widget where you define its internal logic.

  • Settings

    Configuration options that allow users to customize the behavior of a widget without modifying its internal logic.

  • Variable Name

    A unique identifier used to access setting values in the widget's logic (e.g., My.Custom.Var).

  • DataType

    The type of data that a port can handle (e.g., String, Number, Rect).

  • UI Field

    A user interface element in the settings panel that allows users to configure widget behavior.

  • Collection

    A way to share custom widgets with other users.