A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Color, Entity } from '../../types';
import type { World } from '../../ecs/world';
import { px } from '../core/dimension';
import { type UIEventQueue } from '../core/events';
import { TextInput, type TextInputData } from '../text/text-input';
import { TextRenderMode } from '../core/text';
import { spawnUIEntity, type UINodeInit } from '../core/compose';
import { makeWidgetInteractable } from '../input/interactable';
import { themeColors, themeType } from '../theme/tokens';
import { markThemed } from '../theme/theme-style';
export interface TextInputOptions {
world: World;
events: UIEventQueue;
parent?: Entity;
/** CSS-box layout. Default: 220×32. */
node?: UINodeInit;
value?: string;
placeholder?: string;
/** Catalog key for the empty-field hint; requires a Localization resource. */
placeholderI18nKey?: string;
fontFamily?: string;
/** Default: the theme's label size. */
fontSize?: number;
/** 0 = unlimited. */
maxLength?: number;
password?: boolean;
multiline?: boolean;
readOnly?: boolean;
/** Inner horizontal padding in px. Default 6. */
padding?: number;
/** Glyph pipeline for the field text. Default Auto (bitmap unscaled, SDF scaled). */
renderMode?: TextRenderMode;
/** Text / background / placeholder color overrides (theme roles otherwise). */
color?: Color;
backgroundColor?: Color;
placeholderColor?: Color;
disabled?: boolean;
tabIndex?: number;
/** Fires on every edit. */
onChange?: (value: string, entity: Entity) => void;
/** Fires on Enter (single-line). */
onSubmit?: (value: string, entity: Entity) => void;
}
export interface TextInputHandle {
readonly entity: Entity;
getValue(): string;
setValue(value: string): void;
dispose(): void;
}
/**
* Single-call editable text field over the {@link TextInput} component and its
* SDF input plugin (focus, caret, IME gate, clipboard, password masking).
* Colors default to theme roles and re-resolve on `switchTheme`.
*/
export function createTextInput(opts: TextInputOptions): TextInputHandle {
const { world, events } = opts;
const c = themeColors();
const entity = spawnUIEntity({
world,
parent: opts.parent,
node: opts.node ?? { width: px(220), height: px(32) },
});
// Text fields are always focusable — that is what they are for.
makeWidgetInteractable(world, entity, { disabled: opts.disabled, tabIndex: opts.tabIndex });
world.insert(entity, TextInput, {
value: opts.value ?? '',
placeholder: opts.placeholder ?? '',
placeholderI18nKey: opts.placeholderI18nKey ?? '',
placeholderColor: opts.placeholderColor ?? { ...c.text, a: c.text.a * 0.5 },
fontFamily: opts.fontFamily ?? '',
fontSize: opts.fontSize ?? themeType().label,
color: opts.color ?? { ...c.text },
backgroundColor: opts.backgroundColor ?? { ...c.control },
padding: opts.padding ?? 6,
maxLength: opts.maxLength ?? 0,
multiline: opts.multiline ?? false,
password: opts.password ?? false,
readOnly: opts.readOnly ?? false,
focused: false,
cursorPos: (opts.value ?? '').length,
renderMode: opts.renderMode ?? TextRenderMode.Auto,
});
markThemed(world, entity, {
input: {
background: opts.backgroundColor === undefined ? 'control' : undefined,
text: opts.color === undefined ? 'text' : undefined,
placeholder: opts.placeholderColor === undefined ? 'text' : undefined,
},
});
const offChange = opts.onChange
? events.on(entity, 'change', () => {
opts.onChange!((world.get(entity, TextInput) as TextInputData).value, entity);
})
: undefined;
const offSubmit = opts.onSubmit
? events.on(entity, 'submit', () => {
opts.onSubmit!((world.get(entity, TextInput) as TextInputData).value, entity);
})
: undefined;
return {
entity,
getValue: () => (world.get(entity, TextInput) as TextInputData).value,
setValue: (value: string) => {
if ((world.get(entity, TextInput) as TextInputData).value === value) return;
world.update(entity, TextInput, (ti) => {
ti.value = value;
ti.cursorPos = Math.min(ti.cursorPos, value.length);
});
},
dispose: () => {
offChange?.();
offSubmit?.();
if (world.valid(entity)) world.despawn(entity);
},
};
}