Enable and disable the whiteboard

Android

The component corresponding to the Whiteboard widget is named AgoraEduWhiteBoardComponent, and the widget ID can be obtained using AgoraWidgetDefaultId.WhiteBoard.id. Use this component to turn the Whiteboard on or off.

To enable or disable the Whiteboard, you monitor the status changes of the Whiteboard caused by the teacher client and adjust the UI accordingly. See initView() in the file AgoraEduUIKit/src/main/java/com/agora/edu/component/whiteboard/AgoraEduWhiteBoardComponent.kt for the logic of registering observers, listening for active states, and creating or destroying Whiteboard components in the methods.

If you want to open and close the Whiteboard by yourself, you can refer to the following code examples:

• To turn on the Whiteboard, add the following code to the file where the button to open the Whiteboard is located:

  val info = AgoraWidgetRoomPropsUpdateReq(state = 1)
  eduContext?.widgetContext()?.setWidgetActive(AgoraWidgetDefaultId.WhiteBoard.id, info)

• To close the Whiteboard, add the following code to the file where the button to close the Whiteboard is located:

  eduContext?.widgetContext()?.setWidgetInActive(AgoraWidgetDefaultId.WhiteBoard.id)

• To register an observer, use the following code:

  eduContext?.widgetContext()?.addWidgetActiveObserver(widgetActiveObserver, AgoraWidgetDefaultId.LargeWindow.id)

• To monitor the status of the widget, use the following code:

  private val widgetActiveObserver = object : AgoraWidgetActiveObserver {
      override fun onWidgetActive(widgetId: String) {
          // The Whiteboard has been created, here is the child thread
          if (widgetId == AgoraWidgetDefaultId.WhiteBoard.id) {
  
          }
      }
  
      override fun onWidgetInActive(widgetId: String) {
          // The Whiteboard has been removed, here is the child thread
          if (widgetId == AgoraWidgetDefaultId.WhiteBoard.id) {
  
          }
      }
  }

API Reference

AgoraWidgetContext

create

fun create(config: AgoraWidgetConfig): AgoraBaseWidget?

Create a Widget object instance.

Parameter:

• config: The configuration information of this Widget object.

Return: Widget instance, empty means creation failed.

getWidgetConfig

fun getWidgetConfig(widgetId: String): AgoraWidgetConfig?

Get the configuration information of a registered Widget.

Parameter:

• widgetId: The unique identifier of the Widget.

Return: An AgoraWidgetConfig object.

setWidgetActive

fun setWidgetActive(widgetId: String, ownerUserUuid: String? = null,
                    roomProperties: Map<String, Any>? = null,
                    callback: EduContextCallback<Unit>? = null)

Activate a Widget.

Parameter:

• widgetId: Widget's unique identifier.
• ownerUserUuid: UserUuid of the user who owns the currently activated Widget.
• roomProperties: Initialized room properties.
• callback: Callback listener for activation operation.

Return: After the operation is successful, you will receive the callback of AgoraWidgetActiveObserver.onWidgetActive.

setWidgetInActive

fun setWidgetInActive(widgetId: String, isRemove: Boolean = false, callback: EduContextCallback<Unit>? = null)

Unregister the specified Widget.

Parameter:

• widgetId: Widget's unique identifier.
• isRemove: Whether to completely delete all information of this Widget in the current classroom:
  • true: Delete completely. All information under roomProperties.widgets.'widgetId' and userProperties.widgets.'widgetId' will be removed.
  • false: Only set roomProperties.widgets.'widgetId'.state to '0', that is, set the current Widget as inactive. No matter what this value is passed, it will receive the callback of AgoraWidgetActiveObserver.onWidgetInActive.
• callback: Callback listener for logout operation.

getWidgetActive

fun getWidgetActive(widgetId: String): Boolean

Get the activation state of a Widget.

Parameter:

• widgetId: Widget's unique identifier.

Return: Boolean indicating the activation state of a Widget.

getAllWidgetActive

fun getAllWidgetActive(): Map<String, Boolean>

Get the activation status of all registered Widgets.

Return: Map holding the activation statuses of all registered Widgets.

addWidgetActiveObserver

fun addWidgetActiveObserver(observer: AgoraWidgetActiveObserver, widgetId: String)

Add an AgoraWidgetActiveObserver listener to monitor whether this Widget is active.

Parameter:

• observer: AgoraWidgetActiveObserver listener to add.
• widgetId: Widget's unique identifier.

removeWidgetActiveObserver

fun removeWidgetActiveObserver(observer: AgoraWidgetActiveObserver, widgetId: String)

Delete an AgoraWidgetActiveObserver listener.

Parameter:

• observer: AgoraWidgetActiveObserver listener to remove.
• widgetId: Widget's unique identifier.

addWidgetMessageObserver

fun addWidgetMessageObserver(observer: AgoraWidgetMessageObserver, widgetId: String)

Add an AgoraWidgetMessageObserver listener to listen to all messages sent by this Widget.

Parameter:

• observer: AgoraWidgetMessageObserver listener to add.
• widgetId: Widget's unique identifier.

removeWidgetMessageObserver

fun removeWidgetMessageObserver(observer: AgoraWidgetMessageObserver, widgetId: String)

Delete an AgoraWidgetMessageObserver listener.

Parameter:

• observer: AgoraWidgetMessageObserver listener to remove.
• widgetId: Widget's unique identifier.

sendMessageToWidget

fun sendMessageToWidget(msg: String, widgetId: String)

Send a message to a Widget.

Parameter:

• msg: Message to send.
• widgetId: Widget's unique identifier.

iOS

In Flexible Classroom, the implementation logic of opening and closing the Whiteboard is located in the CloudClass-iOS/SDKs/AgoraEduUI/Classes/Components/Flat/FcrBoardUIComponent.swift file. Take the following steps to manage the Whiteboard:

1. Add an observer to monitor widget activity

   // add WidgetActivityObserver
   widgetController.add(self)

2. When the state of the Whiteboard widget activity changes, onWidgetActive or onWidgetInactive is called. When the status is active, open the Whiteboard by creating a Whiteboard Widget object; when the status is inactive, close the Whiteboard by destroying the Whiteboard Widget object as follows:

   extension FcrBoardUIComponent: AgoraWidgetActivityObserver {
       func onWidgetActive(_ widgetId: String) {
           guard widgetId == BoardWidgetId else {
               return
           }
   
           initWidget()
       }
   
       func onWidgetInactive(_ widgetId: String) {
           guard widgetId == BoardWidgetId else {
               return
           }
   
           deinitWidget()
       }
   }

API Reference

AgoraWidgetContext

create

AgoraBaseWidget create(AgoraWidgetConfig config)

Creates a widget object.

Parameter:

• config: The initialization configurations of the widget object.

Return: An AgoraBaseWidget object.

setWidgetActive

void setWidgetActive(String widgetId,
                     String ownerUuid,
                     Map<String: Any> roomProperties,
                     AgoraWidgetFrame syncFrame,
                     Callback<Void> success,
                     Callback<Error> failure)

Sets the widget state as active.

Parameter:

• widgetId: The widget ID.
• ownerUuid: (Nullable) The ID of the user to whom the widget belongs. When the user goes offline, the onWidgetInactive callback will be triggered for the widgets owned by this user.
• roomProperties: (Nullable) The room properties related to the widget.
• syncFrame: (Nullable) The size and position of the widget.
• success: The method call succeeds.
• failure: The method call fails, the SDK returns an error.

setWidgetInactive

void setWidgetInactive(String widgetId,
                       Callback<Void> success,
                       Callback<Error> failure)

Sets the widget state as inactive.

Parameter:

• widgetId: The widget ID.
• roomProperties: (Nullable) The room properties related to the widget.
• success: The method call succeeds.
• failure: The method call fails, the SDK returns an error.

getWidgetActivity

Bool getWidgetActivity(String widgetId)

Gets the state of a specified widget.

Parameter:

• widgetId: The widget ID.

Return: Whether the widget is active or not.

getWidgetConfigs

Array<AgoraWidgetConfig> getWidgetConfigs()

Gets the configurations of all widgets.

Return: An array of the AgoraWidgetConfig objects.

getWidgetConfig

AgoraWidgetConfig getWidgetConfig(String widgetId)

Gets the configurations of a specified widget.

Parameter:

• widgetId: The widget ID.

Return: An AgoraWidgetConfig object.

addWidgetActiveObserver

AgoraWidgetError addWidgetActiveObserver(AgoraWidgetActiveObserver observer,
                                         String widgetId)

Registers an observer to observe the state of a specified widget. When the state of the widget changes, the SDK triggers a callback.

Parameter:

• observer: See AgoraWidgetActiveObserver.
• widgetId: The widget ID.

Return: When the widget ID is not valid, the SDK returns an error.

removeWidgetActiveObserver

AgoraWidgetError removeWidgetActiveObserver(AgoraWidgetActiveObserver observer,
                                            String widgetId)

Registers the observer of a specified widget.

Parameter:

• observer: See AgoraWidgetActiveObserver.
• widgetId: The widget ID.

Return: When the widget ID is not valid, the SDK returns an error.

AgoraWidgetActiveObserver

onWidgetActive

void onWidgetActive(String widgetId)

Occurs when the widget state changes to active.

Parameter:

• widgetId: The widget ID.

onWidgetInactive

void onWidgetInactive(String widgetId)

Occurs when the widget state changes to inactive.

Parameter:

• widgetId: The widget ID.

Web

The whiteboard module in Flexible Classroom is implemented based on AgoraWidget. You can turn the whiteboard module on or off in the classroom by setting the widget state as active or inactive.

After disabling the whiteboard module, drawing tools including pencil, text box, shape, and eraser will no longer be available and users cannot upload, delete, or display class files on the whiteboard. Other features that do not rely on the whiteboard, such as uploading or deleting class files, pop-up quiz, count-down timer, and screen sharing will not be affected.

Turn the whiteboard on or off

The Whiteboard interface is packaged in the file packages/agora-classroom-sdk/src/infra/stores/common/base.ts, and the whiteboard-related interface is in the file packages/agora-classroom-sdk/src/infra/protocol/board.ts.

get boardApi() {
    return EduUIStoreBase._boardApi;
}

To enable or disable the Whiteboard, you monitor the status change of the Whiteboard caused by the teacher client and adjust the UI accordingly.

Call the Whiteboard-related interfaces boardApi.enable() and boardApi.disable() to turn the Whiteboard on or off.

// Enable the Whiteboard
this.boardApi.enable();
...

// Disable the Whiteboard
this.boardApi.disable();

API reference

connected

Query whether the Whiteboard is connected to the server.

@computed
get connected() {
  return this.connState === BoardConnectionState.Connected;
}

return value

• true: connected.
• false: not connected.

mounted

Query whether the Whiteboard is mounted.

@computed
get mounted() {
  return this.mountState === BoardMountState.Mounted;
}

return value

• true: Mounted.
• false: not mounted.

granted

Query whether the user has the permission to operate the Whiteboard.

@computed
get granted() {
  return this.hasPrivilege();
}

return value

• true: Have permission.
• false: No permission.

enable

Connect and turn on the Whiteboard.

enable() {
this._sendBoardCommandMessage(AgoraExtensionRoomEvent.ToggleBoard, true);
}

disable

Disconnect and turn off the Whiteboard.

disable() {
  this._sendBoardCommandMessage(AgoraExtensionRoomEvent.ToggleBoard, false);
}

Electron

The whiteboard module in Flexible Classroom is implemented based on AgoraWidget. You can turn the whiteboard module on or off in the classroom by setting the widget state as active or inactive.

After disabling the whiteboard module, drawing tools including pencil, text box, shape, and eraser will no longer be available and users cannot upload, delete, or display class files on the whiteboard. Other features that do not rely on the whiteboard, such as uploading or deleting class files, pop-up quiz, count-down timer, and screen sharing will not be affected.

Turn the whiteboard on or off

The Whiteboard interface is packaged in the file packages/agora-classroom-sdk/src/infra/stores/common/base.ts, and the whiteboard-related interface is in the file packages/agora-classroom-sdk/src/infra/protocol/board.ts.

get boardApi() {
    return EduUIStoreBase._boardApi;
}

To enable or disable the Whiteboard, you monitor the status change of the Whiteboard caused by the teacher client and adjust the UI accordingly.

Call the Whiteboard-related interfaces boardApi.enable() and boardApi.disable() to turn the Whiteboard on or off.

// Enable the Whiteboard
this.boardApi.enable();
...

// Disable the Whiteboard
this.boardApi.disable();

API reference

connected

Query whether the Whiteboard is connected to the server.

@computed
get connected() {
  return this.connState === BoardConnectionState.Connected;
}

return value

• true: connected.
• false: not connected.

mounted

Query whether the Whiteboard is mounted.

@computed
get mounted() {
  return this.mountState === BoardMountState.Mounted;
}

return value

• true: Mounted.
• false: not mounted.

granted

Query whether the user has the permission to operate the Whiteboard.

@computed
get granted() {
  return this.hasPrivilege();
}

return value

• true: Have permission.
• false: No permission.

enable

Connect and turn on the Whiteboard.

enable() {
this._sendBoardCommandMessage(AgoraExtensionRoomEvent.ToggleBoard, true);
}

disable

Disconnect and turn off the Whiteboard.

disable() {
  this._sendBoardCommandMessage(AgoraExtensionRoomEvent.ToggleBoard, false);
}