@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
156 lines (155 loc) • 6.55 kB
TypeScript
import type { Context } from "../../engine_context.js";
/** This is the model for the postMessage event that the needle engine will send to create menu items */
export declare type NeedleMenuPostMessageModel = {
type: "needle:menu";
button?: {
label?: string;
/** Google icon name */
icon?: string;
/** currently only URLs are supported */
onclick?: string;
target?: "_blank" | "_self" | "_parent" | "_top";
/** Low priority is icon is on the left, high priority is icon is on the right. Default is 0 */
priority?: number;
};
};
/**
* Used by the NeedleMenuElement to create a button at {@link NeedleMenuElement#appendChild}
*/
export declare type ButtonInfo = {
/** Invoked when the button is clicked */
onClick: (evt: Event) => void;
/** Visible button text */
label: string;
/** Material icon name: https://fonts.google.com/icons */
icon?: string;
/** "left" or "right" to place the icon on the left or right side of the button. Default is "left" */
iconSide?: "left" | "right";
/** Low priority is icon is on the left, high priority is icon is on the right. Default is undefined */
priority?: number;
/** Experimental. Allows to put two buttons in one row for the compact layout */
class?: "row2";
title?: string;
};
/**
* The NeedleMenu is a menu that can be displayed in the needle engine webcomponent or in VR/AR sessions.
* The menu can be used to add buttons to the needle engine that can be used to interact with the application.
* The menu can be positioned at the top or the bottom of the needle engine webcomponent
*
* @example Create a button using the NeedleMenu
* ```typescript
* onStart(ctx => {
* ctx.menu.appendChild({
* label: "Open Google",
* icon: "google",
* onClick: () => { window.open("https://www.google.com", "_blank") }
* });
* })
* ```
*
* Buttons can be added to the menu using the {@link NeedleMenu#appendChild} method or by sending a postMessage event to the needle engine with the type "needle:menu". Use the {@link NeedleMenuPostMessageModel} model to create buttons with postMessage.
* @example Create a button using a postmessage
* ```javascript
* window.postMessage({
* type: "needle:menu",
* button: {
* label: "Open Google",
* icon: "google",
* onclick: "https://www.google.com",
* target: "_blank",
* }
* }, "*");
* ```
*/
export declare class NeedleMenu {
private readonly _context;
private readonly _menu;
private readonly _spatialMenu;
constructor(context: Context);
/** @ignore internal method */
onDestroy(): void;
private onPostMessage;
private onStartXR;
private onExitXR;
/** Experimental: Change the menu position to be at the top or the bottom of the needle engine webcomponent
* @param position "top" or "bottom"
*/
setPosition(position: "top" | "bottom"): void;
/**
* Call to show or hide the menu.
* NOTE: Hiding the menu is a PRO feature and requires a needle engine license. Hiding the menu will not work in production without a license.
*/
setVisible(visible: boolean): void;
/** When set to false, the Needle Engine logo will be hidden. Hiding the logo requires a needle engine license */
showNeedleLogo(visible: boolean): void;
/** @returns true if the logo is visible */
get logoIsVisible(): boolean;
/** When enabled=true the menu will be visible in VR/AR sessions */
showSpatialMenu(enabled: boolean): void;
setSpatialMenuVisible(display: boolean): void;
get spatialMenuIsVisible(): boolean | undefined;
/**
* Call to add or remove a button to the menu to show a QR code for the current page
* If enabled=true then a button will be added to the menu that will show a QR code for the current page when clicked.
*/
showQRCodeButton(enabled: boolean | "desktop-only"): HTMLButtonElement | null;
/** Call to add or remove a button to the menu to mute or unmute the application
* Clicking the button will mute or unmute the application
*/
showAudioPlaybackOption(visible: boolean): void;
private _muteButton?;
showFullscreenOption(visible: boolean): void;
private _fullscreenButton?;
appendChild(child: HTMLElement | ButtonInfo): HTMLElement;
}
export declare class NeedleMenuElement extends HTMLElement {
#private;
static create(): HTMLElement;
static getOrCreate(domElement: HTMLElement, context: Context): NeedleMenuElement;
private _domElement;
private _context;
constructor();
private _sizeChangeInterval;
connectedCallback(): void;
disconnectedCallback(): void;
private _userRequestedLogoVisible?;
showNeedleLogo(visible: boolean): void;
/** @returns true if the logo is visible */
get logoIsVisible(): boolean;
private ___onSetLogoVisible;
setPosition(position: "top" | "bottom"): void;
private _userRequestedMenuVisible?;
setVisible(visible: boolean): void;
/**
* If the menu is in compact mode and the foldout is currently open (to show all menu options) then this will close the foldout
*/
closeFoldout(): void;
private readonly root;
/** wraps the whole content */
private readonly wrapper;
/** contains the buttons and dynamic elements */
private readonly options;
/** contains the needle-logo html element */
private readonly logoContainer;
private readonly compactMenuButton;
private readonly foldout;
append(...nodes: (string | Node)[]): void;
appendChild<T extends Node>(node: T | ButtonInfo): T;
prepend(...nodes: (string | Node)[]): void;
private _isHandlingChange;
/** Called when any change in the web component is detected (including in children and child attributes) */
private onChangeDetected;
private onOptionsChildrenChanged;
private _didSort;
/** checks if the menu has any content and should be rendered at all
* if we dont have any content and logo then we hide the menu
*/
private handleMenuVisible;
/** @returns true if we have any content OR a logo */
get hasAnyContent(): boolean;
get hasAnyVisibleOptions(): boolean;
private _lastAvailableWidthChange;
private _timeoutHandle;
private handleSizeChange;
private ___insertDebugOptions;
}