Displayer | Agora Interactive Whiteboard Web SDK API Reference

The Displayer interface is the basic interface for interactive whiteboard rooms.

Type parameters

CALLBACKS: DisplayerCallbacks

Hierarchy

Displayer
- Room

Index

Properties

callbacks

callbacks: Callbacks<CALLBACKS>

Callbacks. Refer to the following example to set a callback:

example

// Listens for the onSliceChanged callback
function sliceChangeCallback(slice) {

}

// Registers the callback
displayer.callbacks.on("onSliceChanged", sliceChangeCallback);

// Unregisters the callback
displayer.callbacks.off("onSliceChanged", sliceChangeCallback);

// Sets the callback to occur once only
displayer.callbacks.once("onSliceChanged", function(slice) {

});

deviceType

deviceType: DeviceType

The user's device type, which determines how the SDK handles mouse and touch events.

disableCameraTransform

disableCameraTransform: boolean

Whether to disable the user from adjusting (moving or zooming) the view through touchscreen gestures or mousewheel movement:

true: Disable the user from adjusting the view.
false: (Default) Enable the user to adjust the view.

Note

This method does not affect the setCameraBound, moveCamera, or moveCameraToContain methods.

disableOthersSelectingBox

disableOthersSelectingBox: boolean

Whether to disable the highlighted box when another user puts their cursor on an object on the whiteboard:

since

2.12.0

true: Disable the highlighted box.
false: (Default) Enable the highlighted box.

Note

This property does not affect the highlighted box of the local user.

enableWriteNow

enableWriteNow: boolean

Whether the user currently has write permission:

since

2.10.0

true: The user has write permission.
false: The user does not have write permission.

handToolActive

handToolActive: boolean

Whether to enable the hand tool:

true: Enable the hand tool.
false: Disable the hand tool.

handToolKey

handToolKey: string | undefined

The hotkeys for the hand tool. The user can use the hand tool to move the page. If you set this property to undefined, the hand tool has no hotkeys.

observerId

observerId: number

The ID of the user.

In a live Interactive Whiteboard room, observerId is the ID of the local user.

region

region: string

The data center, which supports the following values:

`region`	Data center	Service area
`us-sv`	Silicon Valley, United States	North America and South America
`sg`	Singapore	Singapore, East Asia, and Southeast Asia
`in-mum`	Mumbai, India	India
`eu`	Frankfurt, Europe	Europe
`cn-hz`	Hangzhou, China	Areas not covered by other data centers

screenType

screenType: ScreenType

The user's screen type, which is used to adjust parameters for gesture recognition.

slice

slice: string

The unique identifier (UUID) of the current slice.

state

state: DisplayerState

The state of the Displayer object.

version

version: string

The version of the current SDK.

since: 2.13.14

Methods

addMagixEventListener

addMagixEventListener(event: string, listener: EventListener, options?: MagixEventListenerOptions): void
addMagixEventListener(event: string, listener: EventsListener, fireInterval: number): void

- Defined in index-en.d.ts:1867
Adds a listener for a customized event.

You can receive the customized event callback after a successful call of this method.

Note

The SDK triggers only one callback for the customized events with the same name.

Parameters
- event: string
  
  The name of the customized event to be listened for.
- listener: EventListener
  
  The customized event callback. See EventListener. If you add multiple callbacks for the same event, the callback added later overrides the one added earlier.
- Optional options: MagixEventListenerOptions
  
  Since v2.15.2. Options for setting a custom event listener. See MagixEventListenerOptions.
Returns void
- Defined in index-en.d.ts:1893
Adds a high-frequency listener for a customized event.

You can receive the customized event callback after a successful call of this method.

Note

The SDK triggers only one callback for the customized events with the sane name.
example
```
function listener(events) {
    for (const event of events) {
    }
}
displayer.addMagixEventListener("my-event", listener, 100);
```
Parameters
- event: string
  
  The name of the customized event to be listened for.
- listener: EventsListener
  
  The customized events callback. See EventsListener. If you add multiple callbacks for the same event, the callback added later overrides the one added earlier.
- fireInterval: number
  
  The interval (ms) at which the SDK triggers the callback. The minimum interval is 500 ms. The SDK automatically adjusts the value smaller than 500 to 500.
Returns void

bindHtmlElement

bindHtmlElement(element: HTMLDivElement | null): void

- Defined in index-en.d.ts:1744
Binds the whiteboard to an HTML container.

Parameters
- element: HTMLDivElement | null
  
  The HTML container for the whiteboard. You can unbind the whiteboard by setting this parameter to null.
Returns void

convertToPointInWorld

convertToPointInWorld(point: { x: number; y: number }): { x: number; y: number }

- Defined in index-en.d.ts:1764
Converts the coordinates of a point on the whiteboard.

This method converts the coordinates of the screen coordinate system (taking the upper left corner as the origin) to the coordinates of the world coordinate system (taking the center of the initial whiteboard as the origin).

Parameters
- point: { x: number; y: number }
  
  The coordinates of the point in the screen coordinate system.
  - x: number
    
    The X coordinate of the point in the screen coordinate system.
  - y: number
    
    The Y coordinate of the point in the screen coordinate system.
Returns { x: number; y: number }

The coordinates of the point in the world coordinate system.
- x: number
  
  The X coordinate of the point in the world coordinate system.
- y: number
  
  The Y coordinate of the point in the world coordinate system.

createScenesCallback

createScenesCallback(path: string, callbacks?: Partial<ScenesCallbacks>): ScenesCallbacksNode | null

- Defined in index-en.d.ts:1710
Creates a listener object for a scene directory.

After the listener object is successfully created, when the scenes and subdirectories in the specified scene directory change, the SDK triggers the callbacks you have registered in ScenesCallbacks to report the scene events. When you no longer need the created listener, call dispose to release the listener object.
note
- Call this method after joining the whiteboard room.
- You can create only one listener object for each scene directory. If you need to create a new listener object, you must call dispose to release the created listener object first.
Parameters
- path: string
  
  The path of the scene directory. If you pass in a scene path, the SDK sets the listened object to its parent scene directory.
- Optional callbacks: Partial<ScenesCallbacks>
  
  The callbacks to be listened to. See ScenesCallbacks.
Returns ScenesCallbacksNode | null
- The ScenesCallbacksNode object if the method call succeeds.
- null if the method call fails. The method call can fail because the specified scene directory does not exist.

entireScenes

entireScenes(): SceneMap

- Defined in index-en.d.ts:1933
Gets information about all scenes in the room.

Returns SceneMap

Information about all scenes in the room.

fillSceneSnapshot

fillSceneSnapshot(scenePath: string, div: HTMLElement, width: number, height: number): void

- Defined in index-en.d.ts:1822
Generates the snapshot of the specified scene.

Parameters
- scenePath: string
  
  The path of the specified scene.
- div: HTMLElement
  
  The div for the snapshot.
- width: number
  
  The width of the snapshot. This parameter is optional since v2.3.8. If you do not set this parameter, it is set to the width of the div for the snapshot.
- height: number
  
  The height of the snapshot. This parameter is optional since v2.3.8. If you do not set this parameter, it is set to the height of the div for the snapshot.
Returns void

generateScreenshot

generateScreenshot(scenePath?: string, width?: number, height?: number): Promise<string>

- Defined in index-en.d.ts:1810
Generates the screenshot of the specified scene.

Parameters
- Optional scenePath: string
  
  The path of the scene. You can get the current scenePath via room.state.sceneState.scenePath.
- Optional width: number
  
  The width of the screenshot.
- Optional height: number
  
  The height of the screenshot.
Returns Promise<string>

The URL address of the screenshot.

Note

If the scene displays an image or dynamic PPT slide, ensure that the storage server of the image or the PPT slide supports cross-origin resource sharing; otherwise, the image or PPT slide may not be shown in the generated screenshot.

getInvisiblePlugin

getInvisiblePlugin<A>(kind: string): InvisiblePlugin<A> | null

- Defined in index-en.d.ts:1752
Gets the specified invisible plugin.

Type parameters
- A: Object
Parameters
- kind: string
  
  The type of the invisible plugin.
Returns InvisiblePlugin<A> | null

The specified invisible plugin.

getScene

getScene(path: string): WhiteScene | undefined

- Defined in index-en.d.ts:1943
Gets the information about a specified scene.

Parameters
- path: string
  
  The path of a scene. Ensure the scene path stars with / and consists of the scene directory and scene name. For example, /math/classA.
Returns WhiteScene | undefined

The information about the specified scene. See WhiteScene.

memberState

memberState(memberId: number): MemberState

- Defined in index-en.d.ts:1718
Gets the state of the whiteboard tool used by the user.

Parameters
- memberId: number
  
  The ID of the user.
Returns MemberState

The state of the whiteboard tool used by the user.

moveCamera

moveCamera(camera: Partial<Camera> & Readonly<{ animationMode?: AnimationMode }>): void

- Defined in index-en.d.ts:1725
Adjusts the view.

Parameters
- camera: Partial<Camera> & Readonly<{ animationMode?: AnimationMode }>
  
  The view configuration. See Camera.
Returns void

moveCameraToContain

moveCameraToContain(rectangle: Rectangle & Readonly<{ animationMode?: AnimationMode }>): void

- Defined in index-en.d.ts:1734
Adjusts the view to ensure the complete display of the view rectangle.

Parameters
- rectangle: Rectangle & Readonly<{ animationMode?: AnimationMode }>
  
  Configuration of the view rectangle. See Rectangle.
Returns void

refreshViewSize

refreshViewSize(): void

- Defined in index-en.d.ts:1684
Refreshes the whiteboard view.

When the whiteboardView changes, you need to call this method to refresh the whiteboard view. This method takes effect only when autoResize is set to false.

Returns void

removeMagixEventListener

removeMagixEventListener(event: string, listener?: EventListener): void

- Defined in index-en.d.ts:1901
Removes a listener for a customized event.

Parameters
- event: string
  
  The name of the event.
- Optional listener: EventListener
  
  The listener you want to remove. If you do not set this parameter, all listeners for the event are removed.
Returns void

scalePptToFit

scalePptToFit(animationMode?: AnimationMode): void

- Defined in index-en.d.ts:1918
Adjusts the view in the specified mode to ensure the complete display of the PPT slide.

since

2.3.18

Parameters
- Optional animationMode: AnimationMode
  
  The animation mode for adjusting the view. See AnimationMode.
Returns void

scenePathType

scenePathType(path: string): ScenePathType

- Defined in index-en.d.ts:1926
Gets the type of the scene path.

Parameters
- path: string
  
  The path of the scene.
Returns ScenePathType

The type of the scene path.

scenePreview

scenePreview(scenePath: string, div: HTMLElement, width: number | undefined, height: number | undefined): void

- Defined in index-en.d.ts:1794
Generates the preview of the specified scene.

Parameters
- scenePath: string
  
  The path of the specified scene.
- div: HTMLElement
  
  The div for the preview.
- width: number | undefined
  
  The width of the preview. This parameter is optional since v2.3.8. If you do not set this parameter, it is set to the width of the div for the preview.
- height: number | undefined
  
  The height of the preview. This parameter is optional since v2.3.8. If you do not set this parameter, it is set to the height of the div for the preview.
Returns void

screenshotToCanvas

screenshotToCanvas(context: CanvasRenderingContext2D, scenePath: string, width: number, height: number, camera: Camera, ratio?: number): void

- Defined in index-en.d.ts:1833
Generates the snapshot and writes it into the specified CanvasRenderingContext2D object.

Parameters
- context: CanvasRenderingContext2D
  
  The CanvasRenderingContext2D object.
- scenePath: string
  
  The path of the scene. You can get the current scenePath via room.state.sceneState.scenePath.
- width: number
  
  The width of the snapshot.
- height: number
  
  The height of the snapshot.
- camera: Camera
  
  The description of the view angle. See Camera.
- Optional ratio: number
  
  The device pixel ratio. This parameter is optional. If you do not set this parameter, the default value is 1.
Returns void

screenshotToCanvasAsync

screenshotToCanvasAsync(context: CanvasRenderingContext2D, scenePath: string, width: number, height: number, camera: Camera, ratio?: number, timeout?: number): Promise<void>

- Defined in index-en.d.ts:1851
Generates a screen snapshot and writes it into the specified CanvasRenderingContext2D object after the images in the target scene have finished loading.
note
- This feature is under experimental stage.
- If the images in the target scene fail to load, this function cannot return a screen snapshot. You need to handle the timeout logic yourself.
- If you want to generate a screen snapshot without including images, use screenshotToCanvas.
Parameters
- context: CanvasRenderingContext2D
  
  The CanvasRenderingContext2D object.
- scenePath: string
  
  The path of the scene. You can get the current scenePath via room.state.sceneState.scenePath.
- width: number
  
  The width of the snapshot.
- height: number
  
  The height of the snapshot.
- camera: Camera
  
  The description of the view angle. See Camera.
- Optional ratio: number
  
  The device pixel ratio. This parameter is optional. If you do not set this parameter, the default value is 1.
- Optional timeout: number
  
  The timeout time (ms) for image loading. The default is never to time out and can only be set to a number greater than 0. If the image loading time exceeds this value, the SDK proceeds to the next drawing operation without waiting for the image to complete loading.
Returns Promise<void>

setCameraBound

setCameraBound(cameraBound: CameraBound): void

- Defined in index-en.d.ts:1690
Sets the boundary of the local user's view.

Parameters
- cameraBound: CameraBound
  
  The boundary of the view.
Returns void

waitMagixEvent

waitMagixEvent(filter: EventFilter): Promise<Event>

- Defined in index-en.d.ts:1909
Waits for a customized event.

Parameters
- filter: EventFilter
  
  The event filter.
Returns Promise<Event>

The specified customized event when it occurs.

Type parameters

CALLBACKS: DisplayerCallbacks

Hierarchy

Index

Properties

Methods

Properties

callbacks

deviceType

disableCameraTransform

disableOthersSelectingBox

enableWriteNow

handToolActive

handToolKey

observerId

region

screenType

slice

state

version

Methods

addMagixEventListener

Parameters

event: string

listener: EventListener

Optional options: MagixEventListenerOptions

Returns void

Parameters

event: string

listener: EventsListener

fireInterval: number

Returns void

bindHtmlElement

Parameters

element: HTMLDivElement | null

Returns void

convertToPointInWorld

Parameters

point: { x: number; y: number }

x: number

y: number

Returns { x: number; y: number }

x: number

y: number

createScenesCallback

Parameters

path: string

Optional callbacks: Partial<ScenesCallbacks>

Returns ScenesCallbacksNode | null

entireScenes

Returns SceneMap

fillSceneSnapshot

Parameters

scenePath: string

div: HTMLElement

width: number

height: number

Returns void

generateScreenshot

Parameters

Optional scenePath: string

Optional width: number

Optional height: number

Returns Promise<string>

getInvisiblePlugin

Type parameters

A: Object

Parameters

kind: string

Returns InvisiblePlugin<A> | null

getScene

Parameters

path: string

Returns WhiteScene | undefined

memberState

Parameters

memberId: number

Returns MemberState

moveCamera

Parameters