Once you understand the scene structure and identification as well as the rules for adding, deleting, and changing scenes, you can call APIs of the whiteboard SDK to manage scenes and build multi-scene whiteboard applications according to your business needs.
This page describes how to call APIs provided by the whiteboard SDK to get scene information, insert new scenes, switch, move, and delete scenes, and clear all the contents of a scene.
The Agora Interactive Whiteboard SDK provides the following methods in the Room
interface for managing scenes:
Methods | Description |
---|---|
SceneState |
Gets the information of the currently displayed scene. |
entireScenes |
Gets the information of all scenes in the current room. |
scenePathType |
Gets the type of the scene path. |
putScenes |
Inserts multiples scenes under the specified scene directory. |
setScenePath |
Switches to the specified scene. |
setSceneIndex |
Switches to the specified scene under the current scene directory. |
moveScene |
Moves or renames a scene. |
removeScenes |
Deletes a scene or a scene directory. |
cleanCurrentScene |
Clears all contents on the current scene. |
To follow the procedure on this page, ensure that you have integrated the Agora Interactive Whiteboard SDK into your project and implemented joining a room. For details, see Join a Whiteboard Room.
The following section extends the Join a Whiteboard Room sample code to show the implementation of scene management.
After successfully joining the whiteboard room, you can call the following methods to get the scene information:
SceneState
: Gets the information of the scene that is currently displayed on the whiteboard. The information includes the scene path, name, and index. entireScenes
: Gets the information of all scenes in the current room. For example, to get the information of the current scene, you can add the following lines to the joinWhiteboard.js
file:
whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {
room.bindHtmlElement(document.getElementById("whiteboard"));
// Add the following code to get the path, name, and index of the current scene.
var sceneState = room.state.sceneState;
console.log("scene path:", sceneState.scenePath);
console.log("scene name:", sceneState.sceneName);
console.log("scene index:", sceneState.index);
}).catch(function(err) {
console.error(err);
});
Save the changes, refresh the index.html
page, and open the console of your browser. You can see the following information on the console:
[White] join room success
scene path: /init
scene name: init
scene index: 0
In a newly created whiteboard room, there is only one default initial scene, whose path is /init
, name is init
, and index is 0
.
The whiteboard SDK provides the putScenes
method to insert new scenes in a specified scene directory and display images or web pages on scenes.
When calling putScenes
, you need to pass in the following parameters:
path
: The path of a scene directory, which must start with /
and cannot be the path of a scene.
scenes
: An array of scenes. A single scene contains the following fields:
name
: Name of the scene.ppt
: (Optional) The image or web page to be displayed in the scene. Each scene can display only one image or web page. You can also use PptDescription
to set the width, height, resource path, or preview of the image or web page. index
: (Optional) The index number of the first scene to be inserted in the scene directory. The index numbers of subsequent scenes increase sequentially. The index number of a scene starts from 0.
For example, add the following lines to the joinWhiteboard.js
file to insert two new scenes in the root scene directory (new-page5
, which has an image, and new-page6
, which is blank):
whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {
room.bindHtmlElement(document.getElementById("whiteboard"));
// Create new scenes and insert them to the specified scene directory.
var scenes = [
{name: "new-page5",
ppt:"https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"},
{name: "new-page6"},
]
room.putScenes("/", scenes, 1);
// Output a list of all scenes in the room.
var scenemap = room.entireScenes();
console.log("scene map:", scenemap);
}).catch(function(err) {
console.error(err);
});
Save the changes, and refresh the index.html
page. You can see the following information on the browser's console:
{
"/": [
{name: "init", ppt: undefined},
{name: "new-page5", ppt: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"},
{name: "new-page6", ppt: undefined},
],
}
However, after calling putScenes
to insert new scenes, the SDK does not directly switch to the newly inserted scene. You need to call setScenePath
or setSceneIndex
to switch to a specified scene.
The whiteboard SDK provides the following methods to switch scenes:
setScenePath
: Switches to a scene by specifying the path of the scene. This method can switch to any scene in the current room.setSceneIndex
: Switches to a scene by specifying the index number of the scene. This method can only switch to a scene in the current scene directory.Now you can call the two methods to switch to the new scenes inserted in the Add scenes[Add scenes] section.
To switch to new-page5
by specifying its path, add the following line after room.putScenes("/", scenes);
in the previous example code:
room.setScenePath("/new-page5");
After saving the changes and refreshing the index.html
page, you can see the new scene with an image on the whiteboard. The information of the current scene output on the console is as follows:
[White] join room success
scene path: /new-page5
scene name: new-page5
scene index: 1
You can call setSceneIndex
and pass in index number 2
to switch to scene new-page6
:
room.setSceneIndex(2);
Save the changes, and refresh the index.html
page. You can see the blank new scene display in the whiteboard room. You can also check the current scene information on the console to verify the switch is successful.
You can call moveScene
and pass in the original scene path and the target scene path to move a scene or rename a scene.
For example, to move the new-page5
scene to a new scene directory, SceneC
, add the following code after room.putScenes("/", scenes);
:
room.moveScene("/new-page5", "/sceneC/new-page5");
After saving the changes and refreshing the index.html
page, you can see the following information under the scene map
section on the browser's console:
{
"/": [
{name: "init", ppt: undefined},
{name: "new-page6", ppt: undefined},
],
"/sceneC": [
{name: "new-page5", ppt: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"},
],
}
This information shows that new-page5
is successfully moved to sceneC
.
To rename a scene, keep the scene directories unchanged and only change the scene name in the target scene path. For example, to rename new-page5
to new-page7
, add the following code:
room.moveScene("/new-page5", "/new-page7");
You can call cleanCurrentScene
to clear all contents on the current scene. This method does not clear the image or web page displayed on the scene by default, however. If you need to clear the image or web page as well, call cleanCurrentScene(false)
.
For example, add the following code in the joinWhiteboard.js
file to clear the current scene:
room.cleanCurrentScene();
After saving the changes and refreshing the index.html
page, you can see the scene is cleared.
You can call removeScenes
and pass in the path of a scene or a scene directory to delete a scene or all scenes under a scene directory.
For example, to remove all scenes under the root scene directory, add the following code in the joinWhiteboard.js
file:
room.removeScenes("/");
Save the changes, and refresh the index.html
page. Check the scene map
information output on the browser's console and you can see there is only one scene with the path /init
in the room. This is the scene the SDK creates automatically after all scenes in the room are deleted.
Once you grasp the basic operations of scenes, you can refer to Display Files for instructions on creating a set of scenes to display a complete file.