QNWhiteBoardSDK-iOS
QNWhiteBoardSDK 是七牛推出的一款适用于 iOS 平台的白板 SDK，提供了包括白板，同步在线在内的多种功能，支持高度定制以及二次开发。
基本介绍
ios版本的白板控件的类前缀都是QNWhiteBoard,framework的名字是QNWhiteBoardSDK.framework，framework本身是不包含各种界面控件，例如工具栏，页导航等，这些界面实现都归到示例项目中，如果需要可以加入到自己的工程中或者修改成自己的样式。 其中最重要的是3个类
QNWhiteboardControl是所有用户主动方法的接口类。
QNWhiteboardDelegate是白板事件回调的接口。
QNWhiteBoardViewController是基本界面，可以加入到自己的界面或者直接继承,并且QNWhiteBoardViewController已经实现了QNWhiteBoardViewController接口。
直接使用白板控件
白板控件的ViewController叫做QNWhiteBoardViewController，可以直接放置到自己的界面中，也可以继承，然后自定义自己的实现 初始化之后，需要调用白板的
initializeWhiteboard视图初始化完毕后调用此接口来初始化白板closeWhiteboard在视图被销毁时调用此接口关闭白板
白板截图
仅在QNWhiteBoardViewController附加到布局中时有效（即必须有可见的白板），屏幕截图是需要直接调用QNWhiteBoardViewController的如下方法，无论是否在主线程都可以调用，返回是直接返回一个临时地址，存储了snapshot的图片，回调一定不是在主线程中。
-(void)snapShot:(CGRect)rect_ callback:(void(^)(NSString * _Nullable))callback_;
加入房间
首先访问自己的服务器获取要加入的RTC房间的roomToken,QNWhiteboardJoinRoomConfig等参数（房间的创建和token的生成由服务器对接SDK服务端接口）。此接口需要在白板初始化完成之后来进行
首先构建进房参数来加入房间。
QNWhiteboardJoinRoomConfig *config = [[QNWhiteboardJoinRoomConfig alloc]init];
config.aspectRatio = 0.5;
config.title = @"3bdhajfjsa";
[[QNWhiteboardControl instance] joinRoom:self.roomToken config:config];
如果加入房间成功，会收到onJoinSuccess回调，如果加入失败会收到onJoinFailed回调。
关闭并离开房间
房间关闭时，或者在ViewController.viewDidDispear时，必须调用leaveRoom来退出房间并释放资源，
此方法会同时完成离开房间和资源释放.
(#autoremovewhiteboardlistener)类型的事件监听器（推荐），多次执行是安全的。
通常情况会把它放在ViewDidDisappear中执行，比如：
-(void)viewDidDisappear:(BOOL)animated
{
if(self.isMovingFromParentViewController)
{
//离开房间先
[[QNWhiteboardControl instance] leaveRoom];
//销毁各种资源
[super closeWhiteboard];
}
}
关键方法
- 所有用户可以主动调用的方法都是QNWhiteboardControl类的方法。
- 使用QNWhiteboardControl的类方法前，先通过
instance静态方法获取到QNWhiteboardControl的唯一实例。
| 方法名称 | 方法描述 |
|---|---|
| joinRoom | 进入白板房间 |
| leaveRoom | 离开白板房间 |
| addListener | 添加一个白板事件监听器 |
| removeListener | 移除一个白板事件监听器 |
| clearListener | 清空所有白板监听器 |
主动控制的方法
| 方法名称 | 方法描述 |
|---|---|
| setDefaultInputMode | 设置白板的默认初始输入模式配置 |
| setRetry | 设置白板断线自动重连次数 |
| setInputMode | 改变白板的输入模式 |
| setBackgroundColor | 设置白板背景色 |
| scroll | 垂直滚动白板显示区 |
| newBoardPage | 新建白板页 |
| insertBoardPage | 插入新白板页 |
| jumpBoardPage | 跳转到目标白板页 |
| preBoardPage | 后退到上一页 |
| nextBoardPage | 前进到下一页 |
| deleteBoardPage | 删除白板页 |
| insertFile | 向当前白板页中插入文件 |
| jumpFilePage | 文件翻页 |
| deleteFile | 删除文件 |
| recover | 撤销一次擦除的笔迹 |
| screenshots | 白板截图 |
获取白板当前属性的方法
| 方法名称 | 方法描述 |
|---|---|
| getStatus | 获取白板当前状态 |
| getRoom | 获取当前加入的房间信息 |
| getMe | 获取当前房间中的个人信息 |
| getUsers | 获取当前房间中的用户列表 |
| getPageList | 获取当前白板的全部页信息列表 |
| getCurrentPage | 获取当前白板页信息 |
| getBackgroundColor | 获取当前显示的白板背景色 |
| getInputConfig | 获取当前使用的白板输入模式 |
| getActiveWidget | 获取当前被激活操作的widget |
| canRecovery | 是否存在可还原的笔迹 |
| getViewport | 获取当前白板的窗口尺寸信息 |
添加事件监听器
- 通过调用[[QNWhiteboardControl instance] addListener]可以添加事件监听器，可以在任何时期添加，包括进入白板之前。
- 所有的事件都在QNWhiteboardDelegate接口中。如果添加此类的直接子类作为监听器，则添加后必须由用户手动调用[[QNWhiteboardControl instance] removeListener来移除。此方式通常用于在房间外监听房间中发生的事并记录日志或触发某些全局事件时使用。
| 事件名称 | 事件描述 |
|---|---|
| onJoinSuccess | 成功加入白板房间 |
| onJoinFailed | 加入房间失败 |
| onReconnecting | 白板正在自动重连 |
| onReconnected | 自动重连成功 |
| onDisconnected | 房间彻底断开连接 |
| onBoardStatusChanged | 白板房间状态变化 |
| onUserList | 当前已经在房间中的用户列表 |
| onUserJoin | 有其它用户加入了房间 |
| onUserLeave | 有其它用户离开了房间 |
| onBoardPageList | 白板页信息列表 |
| onCurrentBoardPageChanged | 白板当前页变化 |
| onBoardPageInfoChanged | 某一个白板页信息变化 |
| onBoardSizeChanged | 白板的虚拟大小发生变化 |
| onBoardScroll | 白板内发生滚动 |
| onBackgroundColorChanged | 白板背景色变化 |
| onWidgetActive | 有widget被激活 |
| onFilePageChanged | 文件被翻页 |
| onWidgetActionEvent | widget被执行了某些关键动作 |
| onRecoveryStateChanged | 笔迹回收站状态变化 |
QNWhiteboardControl
所有白板SDK的主动用户接口，所有接口线程安全
joinRoom
-(void)joinRoom:(QNWhiteBoardJoinInfo *)roomInfo_ member:(QNWhiteBoardRoomMember *)me_
进入白板房间
只有此方法执行成功才能连通白板，目前sdk仅支持同时进入一个房间，多次调用是安全的，但仅有第一次调用的参数有效，后续调用会被忽略，如需进入其它房间，需要先执行leaveRoom。
加入成功后本地会收到onJoinSuccess回调，加入失败则会收到onJoinFailed回调。 同时远端用户会收到onUserJoin回调。
如果已经加入成功但是发生了掉线，则SDK会尝试自动重连，并收到onReconnecting回调。 重连次数可以通过setRetry修改，重连成功后会收到onReconnected，重连失败会收到onDisconnected，此时必须用户手动调用此方法重新加入房间。
| 参数 | 描述 |
|---|---|
| roomInfo | 房间信息 |
| me | 身份信息 |
leaveRoom
-(void)leaveRoom
离开白板房间
该方法会断开白板连接并释放资源，同时会清理所有的QNWhiteboardDelegate的监听器。 多次调用是安全的。 离开白板后远端用户会收到onUserLeave回调。
addListener
-(void)addListener:(id<QNWhiteboardDelegate>)delegate_
添加一个白板事件监听器
可以在joinRoom之前或之后添加
| 参数 | 描述 |
|---|---|
| delegate_ | 事件监听回调 |
removeListener
-(void)removeListener:(id<QNWhiteboardDelegate>)delegate_
移除一个白板事件监听器
可在任何时候调用。
| 参数 | 描述 |
|---|---|
| delegate_ | 监听器实例 |
clearListener
-(void)clearListener
清空所有白板监听器
可在任何时候调用。
| 参数 | 描述 |
|---|---|
| listener | 截图回调，在非主线程回调，截图成功会返回UIImage对象，失败返回null |
setDefaultInputMode
-(void)setDefaultInputMode:(QNWhiteBoardInputConfig *)config_
设置白板的默认初始输入模式配置
在joinRoom之前调用有效，已经进入房间时调用此方法不会改变当前的输入模式，仅会影响下次进入房间的输入模式。 如需改变当前房间中的输入模式，请调用setInputMode方法。
此方法用于预先设定加入房间后的初始输入配置，反复加入离开房间不会影响此默认设置。 默认设置不会随setInputMode方法改变，即一次设定长期有效。
| 参数 | 描述 |
|---|---|
| config_ | 输入模式配置 |
setRetry
-(void)setRetry:(int)count_
设置白板断线自动重连次数
默认为10次，设为0表示不自动重连。
| 参数 | 描述 |
|---|---|
| count_ | 重连次数 |
setInputMode
-(void)setInputMode:(QNWhiteBoardInputConfig*)config_
改变白板的输入模式
此方法用于已经连通白板房间时改变用户对白板的输入模式，包括例如笔迹的粗细和颜色等。
| 参数 | 描述 |
|---|---|
| config_ | 输入模式配置 |
setBackgroundColor
-(void)setBackgroundColor:(NSString *)color_
设置白板背景色 格式为“#AARRGGBB”
用于在白板房间中改变当前白板页的背景色，未进入房间调用无效。
- 仅能改变当前页面的背景以及此后新增的页面背景，不会影响已经存在的页面背景。
- 如需设定新房间的初始背景色，请在服务器创建房间时设定。
| 参数 | 描述 |
|---|---|
| color_ | 颜色值，不支持透明度 |
scroll
-(void)scroll:(float)offsetY_
垂直滚动白板显示区
- 目前白板是一个纵向可滚动（高大于宽）的矩形，通常白板的可视区WhiteBoardViewport不能呈现完整白板，需要通过滚动来控制可见区。
- 白板内部可以通过用户的双指操作来滚动白板，无需外部干涉，此方法的目的是方便用户实现类似top按钮或滚动条功能。
无论是调用此方法还是用户通过白板手势滚动了白板（包括远程用户滚动白板），都会触发onBoardScroll回调。
| 参数 | 描述 |
|---|---|
| offsetY | 白板的垂直偏移量，此值为总量而非增量，当前值在WhiteBoardViewport中描述 |
newBoardPage
-(void)newBoardPage
新增白板页
在房间中调用可以在当前页列表末尾插入一个新的页面并会自动跳转到这个新页面。
页面创建成功后用户会收到onCurrentBoardPageChanged、onBoardPageList、onBoardPageInfoChanged三个回调。
insertBoardPage
-(void)insertBoardPage:(NSString *)pageId_
插入新白板页
在指定的页面之前插入一个新白板页，同时白板会自动跳转到新插入的页面。
页面创建成功后用户会收到onCurrentBoardPageChanged、onBoardPageList、onBoardPageInfoChanged三个回调。
| 参数 | 描述 |
|---|---|
| pageId | 目标插入位置的页id，此id来自于页数据，可通过getPageList或getCurrentPage获取页列表或当前显示页数据，也可通过onBoardPageList和onCurrentBoardPageChanged回调来收集 |
jumpBoardPage
-(void)insertBoardPage:(NSString *)pageId_
跳转到指定白板页
直接跳页的实现方式。
跳转成功后用户会收到onCurrentBoardPageChanged、onBoardPageInfoChanged回调。
| 参数 | 描述 |
|---|---|
| pageId_ | 跳转目标的页id，此id来自于页数据，可通过getPageList或getCurrentPage获取页列表或当前显示页数据，也可通过onBoardPageList和onCurrentBoardPageChanged回调来收集 |
preBoardPage
-(void)preBoardPage;
返回到上一页
成功后用户会收到onCurrentBoardPageChanged、onBoardPageInfoChanged回调。
nextBoardPage
-(void)nextBoardPage
前进到下一页
成功后用户会收到onCurrentBoardPageChanged、onBoardPageInfoChanged回调。
deleteBoardPage
-(void)deleteBoardPage:(NSString *)pageId_
删除白板页
删除成功后一定会收到onBoardPageList回调，如果删除的是当前页会同时触发onCurrentBoardPageChanged， 如果删除当前页是仅有的一页，白板会删除当前页并立即创建一个新的空白页，效果类似与清空白板。
| 参数 | 描述 |
|---|---|
| pageId_ | 要删除的页id，此id来自于页数据，可通过getPageList或getCurrentPage获取页列表或当前显示页数据，也可通过onBoardPageList和onCurrentBoardPageChanged回调来收集 |
insertFile
-(void)insertFile:(QNWhiteBoardFileInfo *)config_
向当前白板页中插入文件
支持的格式有图片jpg,png 文档pdf,doc,docx,dot,wps,wpt,dotx,docm,dotm,rtf 演示文稿ppt,pptx,pot,potx,pps,ppsx,dps,dpt,pptm,potm,ppsm 表格xls,xlsx,xlt,et,ett,xltx,csv,xlsb,xlsm,xltm 如果试图插入不支持的文件类型则会被忽略。
图片尽量上传2K及以下的尺寸，否则某些老旧设备可能无法加载。 office文件需要在线转换格式，所以画面呈现会相对慢一些。
文件插入后会收到大量onWidgetActionEvent回调（与房间人数有关），此回调仅表达了导致文件状态变化的用户信息和此用户的加载情况， 通常用于在界面上表达房间中各成员对此文件的加载状态。
| 参数 | 描述 |
|---|---|
| config_ | 文件配置信息 |
jumpFilePage
-(void)jumpFilePage:(NSString *)widgetId_ pageNo:(int)pageNo_
文件翻页
对于可翻页的文件，如pdf和office文件，通过调用此方法可以使文件跳到指定序号的页面。
翻页成功后会收到onFilePageChanged回调。
| 参数 | 描述 |
|---|---|
| widgetId_ | 文件的widgetId，每个文件都有一个id，可以通过getActiveWidget方法获取当前用户正在操作的Widget，也可以通过onWidgetActive收集当前正在操作的Widget |
| pageNo_ | 跳转的目标页号，从1开始，如果序号超出文件范围，跳转会失败并忽略 |
deleteFile
-(void)deleteFile:(nonnull NSString *)widgetId_
删除文件
删除后会触发onWidgetActionEvent回调，如果删除的文件是当前正在激活的widget，则会收到onWidgetActive回调，并且参数为null。
| 参数 | 描述 |
|---|---|
| widgetId_ | 文件的widgetId，每个文件都有一个id，可以通过getActiveWidget方法获取当前用户正在操作的Widget，也可以通过onWidgetActive收集当前正在操作的Widget |
recover
-(void)recover
还原最近一次擦除的笔迹
在输入模式为橡皮模式QNWBInputModeErase时，本用户擦除的笔迹可以通过调用此方法来还原（回滚）。 一次擦除的笔迹指的是用户从落下手指移动擦除线条到抬起手指为止期间擦掉的所有线条。
- 当切换到其它输入模式或者白板翻页后擦除的笔迹缓存将会清空，将无法再还原擦掉的笔迹，即此方法仅在QNWBInputModeErase模式下有效。
- 此方法多次调用是安全的。
- 判断当前是否有可还原的笔迹可以通过调用canRecovery或监听onRecoveryStateChanged回调获知。
getStatus
-(QNWBBoardStatus)getStatus
获取白板当前状态
也可以监听onBoardStatusChanged。
- 返回
- 当前的白板状态QNWBBoardStatus。
getRoom
-(QNWhiteBoardRoom *)getRoom
获取当前加入的房间信息
与监听onJoinSuccess获得的信息一致。
- 返回
- 房间信息QNWhiteBoardRoom，如果未加入房间则会返回null。
getMe
-(QNWhiteBoardRoomMember *)getMe
获取当前房间中的个人信息
与监听onJoinSuccess获得的信息一致。
- 返回
- 自己的成员信息QNWhiteBoardRoomMember，如果未加入房间则会返回null。
getUsers
-(NSArray<QNWhiteBoardRoomMember *> *)getUsers
获取当前房间中的全部用户列表（包括自己）
此列表与监听onUserList，onUserJoin，onUserLeave收集获得的列表一致。
- 返回
- 一个只读的QNWhiteBoardRoomMember成员信息列表，如果未加入房间则会返回空列表。
getPageList
-(NSArray<QNWhiteBoardPageInfo *> *)getPageList
获取当前白板的全部页信息列表
此列表与监听onBoardPageList，onBoardPageInfoChanged处理后获得的列表一致。
- 返回
- 一个只读的QNWhiteBoardPageInfo白板页信息列表，如果未加入房间则会返回空列表。
getCurrentPage
-(QNWhiteBoardPageInfo *)getCurrentPage
获取当前显示的白板页信息
此信息与监听onCurrentBoardPageChanged获得的信息一致。
- 返回
- 当前白板页信息QNWhiteBoardPageInfo，如果未加入房间则会返回null。
getBackgroundColor
-(NSString *)getBackgroundColor
获取当前白板页的背景色
此值与监听onBackgroundColorChanged获得的颜色一致。 可通过调用setBackgroundColor改变当前白板页的背景。 默认背景色由服务器创建房间时指定。
- 返回
- 当前白板页颜色值，如果未加入房间则会返回一个固定值。
getInputConfig
-(QNWhiteBoardInputConfig *)getInputConfig
获取白板当前的输入模式
- 返回
- 通过setInputMode设置的QNWhiteBoardInputConfig，如果未加入房间则会返回默认配置，默认值可通过setDefaultInputMode设置。
getActiveWidget
-(QNActiveWidgetInfo *)getActiveWidget
获取当前被激活操作的widget信息
此信息与监听onWidgetActive获得的数据一致。
- 返回
- QNActiveWidgetInfo，如果当前用户没有操作过任何widget或者用户未加入房间则会返回null。
canRecovery
-(BOOL)CanRecovery
是否存在可还原的笔迹（擦除还原，仅对笔迹有效）
此值与监听onRecoveryStateChanged回调获取的值一致。
getViewport
-(QNWhiteBoardInfo *)getViewport;
获取当前白板的可视区信息，包括白板的大小和偏移
此数据与监听onBoardSizeChanged和onBoardScroll获取的数据一致。 滚动白板可由用户双指手势拖动白板，也可通过程序主动调用scroll完成。
- 返回
- 白板的可视区WhiteBoardViewport，通常此值是跟随用户滚动白板而变化，如果未加入房间则会返回nil
QNWhiteboardDelegate
所有的白板事件的监听器，所有事件响应均在主线程回调。 可通过addListener添加。
onJoinSuccess
-(void) onJoinSuccess:(QNWhiteBoardRoom *)room_ who:(QNWhiteBoardRoomMember *)me_
成功加入白板房间
joinRoom成功后的第一个关键事件（onBoardStatusChanged返回QNWBBoardStatusSuccessful会先一步触发）。 在这里可以处理一些加入房间成功时的初始化工作。
- 在断线重连成功时同样会触发此事件，之后才会触发onReconnected事件。
| 参数 | 描述 |
|---|---|
| room_ | 房间信息 |
| me_ | 个人信息，由joinRoom传递的QNWhiteBoardJoinInfo中携带的信息 |
onJoinFailed
-(void) onJoinFailed:(int)errorCode_
加入房间失败
joinRoom执行失败后触发，因为并没有成功加入房间，所以不会执行自动重连。 失败后需要用户重新调用joinRoom来加入房间。 如果已经成功加入了房间但是发生了断线则会触发onReconnecting尝试自动重连，重连失败则会触发onDisconnected，而不会触发本事件。
| 参数 | 描述 |
|---|---|
| errorCode | 失败错误码 |
onReconnecting
-(void) onReconnecting:(int)time_
白板正在自动重连
当白板连接意外断开比如网络波动等，白板会自动尝试重连，在每次尝试开始时会触发此事件。 重连成功后会先触发onJoinSuccess后触发onReconnected， 重连次数达到上限后会触发失败事件onDisconnected。 首次调用joinRoom失败不会自动重连，而是触发onJoinFailed。
重连次数默认10次，可通过setRetry修改。
| 参数 | 描述 |
|---|---|
| times_ | 当前为第几次重试 |
onReconnected
-(void)onReconnected
自动重连成功
onDisconnected
-(void)onDisconnected
自动重连失败，白板彻底断开连接
即在onReconnecting重试次数达到上限后触发， 此时需要用户重新执行joinRoom加入房间。
onBoardStatusChanged
-(void) onBoardStatusChanged:(QNWBBoardStatus)status_
白板房间状态变化
从joinRoom到leaveRoom之间，只要白板房间的状态发生变化就会触发此事件。 同时此事件触发早于onJoinSuccess，onJoinFailed，onReconnecting等独立事件。 比如调用joinRoom后会立即触发QNWBBoardStatusLoading的变化，onJoinSuccess触发之前会先触发QNWBBoardStatusSuccessful的变化。
| 参数 | 描述 |
|---|---|
| status_ | 新的白板状态 |
onUserList
-(void) onUserList:(NSArray *)users_
当前已经在房间中的用户列表（包括自己）
加入房间后会触发一次返回已经在房间中的用户，自动重连成功后也会触发。
- 如果自己管理用户列表，需要以此回调的作为列表初始数据，并且在重连成功后重置初始列表。
- 后续的远端用户进出事件由onUserJoin和onUserLeave反馈。
- getUsers总是获取当前的完整用户列表。
| 参数 | 描述 |
|---|---|
| user_) | 已经在房间中的用户信息QNWhiteBoardRoomMember列表，此列表为只读列表 |
onUserJoin
-(void) onUserJoin:(QNWhiteBoardRoomMember *)user_
有远端用户加入了房间
- 如果自己维护用户列表，注意更新列表数据
| 参数 | 描述 |
|---|---|
| user_ | 用户信息 |
onUserLeave
-(void) onUserLeave:(QNWhiteBoardRoomMember *)user_
有远端用户离开了房间
- 如果自己维护用户列表，注意更新列表数据
| 参数 | 描述 |
|---|---|
| user_ | 用户信息 |
onBoardPageList
-(void) onBoardPageList:(NSArray *)list_
白板页信息列表
在首次进入房间和白板页列表结构变化时触发，比如新增页，删除页等等。 仅翻页不会触发此事件。
| 参数 | 描述 |
|---|---|
| list | 白板页信息WhiteBoardPage的只读列表，也可以通过getPageList获得 |
onCurrentBoardPageChanged
-(void)onCurrentBoardPageChanged:(QNWhiteBoardPageInfo *)page_
白板当前页改变
在首次加入房间后和翻页时触发，新增页由于会自动切换到新页面，所以也会触发。
| 参数 | 描述 |
|---|---|
| page_ | 当前显示的白板页信息，也可以通过getCurrentPage获得 |
onBoardPageInfoChanged
-(void)onBoardPageInfoChanged:(QNWhiteBoardPageInfo *)page_
某一个白板页信息变化
目前仅白板页的缩略图地址发生变化时才会触发此事件，每当白板发生翻页时都会自动更新上一个页面的缩略图， 所以通常情况下此事件触发的白板页信息不是当前正在显示的页面。
- 由于页号QNWhiteBoardPageInfo.page的变化是新增和删除页导致，可能同时影响大量的页信息，所以页号变化没有单独的事件，只能监听onBoardPageList观察整个列表的变化。
| 参数 | 描述 |
|---|---|
| page_ | 有参数变化的新的页信息，当前仅有缩略图地址变化QNWhiteBoardPageInfo.thumbnails |
onBoardSizeChanged
-(void)onBoardSizeChanged:(QNWhiteBoardInfo*)info_
白板大小变化（虚拟大小）
在白板设定的虚拟大小变化时触发，首次进入白板一定会触发一次。
| 参数 | 描述 |
|---|---|
| info_ | 白板的可视区数据 |
onBoardScroll
-(void)onBoardScroll:(QNWhiteBoardInfo*)info_
白板滚动
白板内发生滚动时触发，主动调用scroll也会触发，首次进入白板也会触发。
| 参数 | 描述 |
|---|---|
| info_ | 白板的可视区数据 |
onBackgroundColorChanged
-(void)onBackgroundColorChanged:(NSString *)backgroundColor
白板背景色改变
当前的白板背景色变化时触发，首次进入白板也会触发。 可通过setBackgroundColor随时改变背景色。
| 参数 | 描述 |
|---|---|
| backgroundColor | 新的颜色值 |
onWidgetActive
-(void)onWidgetActive:(QNActiveWidgetInfo * _Nullable)info
有新的widget被激活
用户书写或操作白板时会激活被操作的widget，同时触发此事件，比如移动文件时会收到被移动的文件信息，在白板上写字时会收到白板的信息。 当此widget是文件且此文件发生翻页后会再次触发此事件，同时也会触发onFilePageChanged。
| 参数 | 描述 |
|---|---|
| info | 当前激活的widget信息，null表示用户还没有操作，比如刚刚翻页后 |
onFilePageChanged
-(void)onFilePageChanged:(QNActiveWidgetInfo *)info
文件页改变
当文件被翻页时触发，同时会触发onWidgetActive。 当前仅被激活的文件发生翻页时才会收到此事件。 文件翻页可通过调用jumpFilePage实现。
| 参数 | 描述 |
|---|---|
| info | 新的widget信息 |
onWidgetActionEvent
-(void)onWidgetActionEvent:(QNWhiteBoardWidgetActionEvent *)event
widget被执行了某些关键动作
比如有人插入文件或删除文件会收到此事件。 同时每个远端用户的文件加载情况也会触发此事件，通过此事件可以观察到每个人文件加载成功或失败情况。
- 当前仅文件和图片widget会触发此事件。
| 参数 | 描述 |
|---|---|
| event | widget事件信息 |
onRecoveryStateChanged
-(void)onRecoveryStateChanged:(BOOL)isEmpty
笔迹回收站空与非空的状态变化
当在擦除模式QNWBInputModeErase擦除笔迹时被擦除的笔迹会移动到回收站导致回收站不为空，会触发此事件。 当反复调用还原笔迹recover导致回收站为空时会触发此事件。 当从擦除模式切换到其他模式或白板翻页后会自动清空回收站，同样有可能触发此事件。
| 参数 | 描述 |
|---|---|
| isEmpty | true表示回收站为空，false表示不为空，此时可以通过recover来还原一次擦除操作 |
ScreenshotsCallback
截图完成回调
screenshots中使用。
ScreenshotsCallback.done
void done(@Nullable Bitmap bitmap)
截图完成
| 参数 | 描述 |
|---|---|
| bitmap | 截图得到的位图，如果为null表示截图失败，位图大小等于WhiteBoardView的像素大小 |
WhiteBoardView
白板的显示控件，用于显示白板内容，当前仅支持同时显示一个白板，如果同时放置了多个白板控件，仅最后一个控件会刷新内容。 布局时此控件的大小最好设定为与白板的虚拟大小WhiteBoardSize的宽高比保持一致，否则多余的边缘会留白。
QNWhiteBoardJoinInfo
加入房间时的参数配置
构造函数
-(instancetype)initWithParam:(NSString *)appId_ room:(NSString *)roomId_ user:(NSString *)userId_ token:(NSString *)token_
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| appId_ | String | 否 | SDK分配的应用id |
| roomId_ | String | 否 | 白板的房间id，房间通常由服务器创建 |
| userId_ | String | 否 | 用户业务系统中的稳定用户id |
| token_ | String | 否 | 每次加入房间时生成的标识符，与appId，roomId，userId关联，通常由服务器生成 |
QNWhiteBoardInputConfig
输入模式配置 此类仅提供静态工厂方法。
普通笔
+(instancetype)instanceWithPen:(NSString *)color_ thickness:(float)thickness_
创建一个笔书写输入模式配置
| 参数 | 描述 |
|---|---|
| color_ | 笔颜色，支持透明度，适当的透明度可以看作是马克笔实现 |
| thickness_ | 笔粗细，必须大于0 |
激光笔
+(instancetype)instanceWithLaser:(QNWBPenStyle)laserType_
创建一个激光笔输入模式配置
激光笔是一种瞬时的位置指示型输入模式，指示手指位置的内容。
| 参数 | 描述 |
|---|---|
| laserType_ | 激光笔类型 |
橡皮
+(instancetype)instanceWithErase:(float)size_
创建一个橡皮（擦除）输入模式配置
| 参数 | 描述 |
|---|---|
| size_ | 橡皮面积 |
几何图形
+(instancetype)instanceWithGeometry:(QNWBGeometryType)geometryType_ color:(NSString *)color_ thickness:(float)thickNess_
创建一个几何图形输入模式配置
| 参数 | 描述 |
|---|---|
| geometryType_ | 图形类型 |
| color_ | 图形边框的颜色 |
| thickness_ | 图形边框粗细 |
InputConfig.select
+(instancetype)instanceWithSelect
创建一个选择输入模式配置
此模式可以在白板中框选内容。
QNWhiteBoardFileInfo
向白板插入文件时描述文件信息的配置
构造函数
-(instancetype)initWithParams:(NSString * _Nonnull)path_ withName:(NSString * _Nullable)name_ withLeft:(NSInteger)left_ withTop:(NSInteger)top_ withWidth:(NSInteger)width_ withHeight:(NSInteger)height_;
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| path_ | String | 否 | 要插入的文件，此文件必须有支持的类型后缀，否则会被系统忽略，支持的类型参考insertFile |
| name_ | String | 是 | 指定文件的实际名称，留空会使用file的名称，此名称不会影响系统对file类型的校验，仅做标识用途，比如file本身是随机串文件名，此处可以赋予它有意义的文件名，此名称会在QNActiveWidgetInfo中拿到 |
| left_ | int | 否 | 插入文件时的初始位置的左上角横坐标，默认为0 |
| top_ | int | 否 | 插入文件时的初始位置的左上角纵坐标，默认为0 |
| width_ | int | 否 | 插入文件时的默认宽度，默认为文件的实际宽度 |
| height_ | int | 否 | 插入文件时的默认高度，默认为文件的实际高度 |
QNActiveWidgetInfo
被激活的widget信息
白板中的一切都是widget，包括白板，文件，图片，选择框等等，具体参考QNWBWidgetType。 当用户操作了一个widget或者在它上面书写时，这个widget会被激活，会触发onWidgetActive事件。
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| widgetId | String | 否 | widgetId，此widget的唯一标识符，后续对widget的操作都会用到此id，比如jumpFilePage和deleteFile |
| type | LATWidgetType | 否 | 指示了此widget的类型 |
| userId | String | 是 | 此widget创建者的userId，通常白板页是没有创建者的，由服务器创建 |
| name | String | 是 | widget名称，如果此widget是文件或图片时 |
| resourceId | String | 是 | 资源id，sdk内部用于标识实际文件的索引，用户通常无需关心 |
| path | String | 是 | 文件路径，如果widget是文件或图片，此为它的本地路径（如果插入的原文件是office文件，则此路径是它转换后的pdf路径，并非原始文件） |
| currentPageNumber | int | 否 | 如果widget是文件时，此为当前文件的页码，从1开始 |
| pageCount | int | 否 | 如果widget是文件时，此为文件的总页数（如果原文件是office文件，则此页数是转换成pdf后的实际页数） |
QNWhiteBoardRoom
房间信息
加入白板房间成功后会收到此数据。
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| roomId | String | 否 | 房间的id，与joinRoom时的roomId一致 |
| fileGroupId | String | 否 | 白板中的文件在服务器存储的文件组id，用户无需关心 |
| chatRoomId | int | 否 | 房间中的聊天室id，暂不支持 |
QNWhiteBoardRoomMember
房间中的成员信息
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| userId | String | 否 | 用户业务系统中的稳定用户id |
| sessionId | String | 否 | 用户会话id，用于唯一标识用户，如果成员在joinRoom时未传递此参数，则此参数会由白板自动生成 |
| roleId | int | 否 | 角色id，默认为0，通常用来标识此用户身份，方便定制用户权限系统 |
| nickname | String | 是 | 用户名或昵称 |
| avatar | String | 是 | 用户头像地址 |
QNWhiteBoardPageInfo
白板页信息
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| pageId | String | 否 | 白板页id，每个页面的唯一标识符，后续对白板页的操作会用到，比如jumpBoardPage，deleteBoardPage等 |
| pageNumber | int | 否 | 页面序号，从1开始，标识了此页是白板中的第几页 |
| thumbUrl | String | 否 | 白板页缩略图url，没有时为空字符串 |
QNWhiteBoardInfo
白板的基本信息
此信息的数值基于白板内部的虚拟大小和坐标系，并非实际渲染窗口的纹理大小（实际的纹理大小由QNWhiteBoardViewController的像素大小决定）。 以下参数由服务器创建白板房间时指定，通常在一个房间中此信息是固定不变的。
| 参数 | 类型 | 描述 |
|---|---|---|
| maxWidth | int | 白板最大宽度 |
| maxHeight | int | 白板最大高度 |
| displayWidth | int | 白板显示宽度（可视区的宽度，当前仅支持与maxWidth保持一致，即只能垂直延展） |
| displayHeight | int | 白板显示高度（可视区的高度，当此参数小于maxHeight时白板可上下滚动） |
| offsetX | float | 当前白板水平偏移（当前仅支持垂直滚动，所以此值总是0） |
| offsetY | float | 当前白板垂直偏移 |
QNWhiteBoardWidgetActionEvent
widget动作事件
描述了对文件或图片的关键操作信息，包括加载情况，由谁插入或删除等。 由onWidgetActionEvent提供。
| 参数 | 类型 | 可空 | 描述 |
|---|---|---|---|
| sessionId | String | 否 | 动作发出者的sessionId |
| type | WidgetType | 否 | widget类型 |
| action | WidgetAction | 否 | 动作类型 |
| name | String | 是 | widget名称 |
QNWBBoardStatus
白板房间状态枚举
QNWBBoardStatusIdle
空闲状态，表示没有进入白板
QNWBBoardStatusLoading
正在进入白板，即调用joinRoom之后到成功或失败之前的状态。
QNWBBoardStatusSuccessful
加入白板成功
QNWBBoardStatusFailed
加入白板失败
QNWBBoardStatusReconnecting
白板正在重连
QNWBGeometryType
几何图形类型
在QNWBGeometryType中指定要绘制的几何图形。
| 名称 | 图形 |
|---|---|
| QNWBGeometryTypeRectangle | 矩形 |
| QNWBGeometryTypeCircle | 圆形 |
| QNWBGeometryTypeLine | 直线 |
| QNWBGeometryTypeArrow | 箭头 |
QNWBPenStyle
激光笔类型
在InputConfig.laserPen中指定激光指示点的样式。
| 名称 | 样式 |
|---|---|
| QNWBPenStyleLaserTypeDot | 圆点 |
| QNWBPenStyleLaserTypeHand | 手形图标 |
| QNWBPenStyleLasterTypeWhiteArrow | 白色箭头 |
| QNWBPenStyleLaserTypeBlackArrow | 黑色箭头 |
QNWBWidgetType
widget类型，白板中的一切都是widget
| 名称 | 类型 |
|---|---|
| QNWBWidgetTypeBoard | 白板 |
| QNWBWidgetTypeFile | 文件，包括pdf和office |
| QNWBWidgetTypeImage | 图片，jpg和png |
| QNWBWidgetTypeGeometry | 几何图形，由InputConfig.geometry模式绘制 |
| QNWBWidgetTypeSelection | 选择框，由InputConfig.select模式选中的内容 |
QNWBWidgetAction
widget动作类型
在onWidgetActionEvent中指示widget具体发生的动作事件。
| 名称 | 事件 |
|---|---|
| QNWBWidgetActionUpload | 开始上传/插入新widget |
| QNWBWidgetActionDelete | 删除widget |
| QNWBWidgetActionSuccess | widget加载成功 |
| QNWBWidgetActionFailed | widget加载失败 |
ErrorCode
错误码
| 名称 | 值 | 错误含义 |
|---|---|---|
| 100 | 网络不可用 | |
| 101 | 服务器错误或繁忙 | |
| 200 | appId不存在 | |
| 201 | roomId不存在 | |
| 202 | userId为空 | |
| 203 | token错误 | |
| 300 | 连接房间失败 | |
| 301 | 等待页数据下发超时 | |
| 302 | 房间连接中断，可能是网络波动，也可能是房间中传输了错误数据导致被服务器切断 |