基本介绍

ios版本的白板控件的类前缀都是QNWhiteBoard,framework的名字是QNWhiteBoardSDK.framework，framework本身是不包含各种界面控件，例如工具栏，页导航等，这些界面实现都归到示例项目中，如果需要可以加入到自己的工程中或者修改成自己的样式。
其中最重要的是3个类

QNWhiteboardControl是所有用户主动方法的接口类。

QNWhiteboardDelegate是白板事件回调的接口。

QNWhiteBoardViewController是基本界面，可以加入到自己的界面或者直接继承,并且QNWhiteBoardViewController已经实现了QNWhiteBoardViewController接口。

直接使用白板控件

白板控件的ViewController叫做QNWhiteBoardViewController，可以直接放置到自己的界面中，也可以继承，然后自定义自己的实现
初始化之后，需要调用白板的

• initializeWhiteboard视图初始化完毕后调用此接口来初始化白板
• closeWhiteboard 在视图被销毁时调用此接口关闭白板

在两个接口调用中间

-(void)viewDidLoad
{
    [super initalizeWhiteboard];
    //接下来可以加入房间了
}

-(void)viewDidDisappear:(BOOL)animated
{
    if(self.isMovingFromParentViewController)
    {
        //离开房间先
        [[QNWhiteboardControl instance] leaveRoom];
		//销毁各种资源
        [super closeWhiteboard];
    
    }
}

白板截图

仅在QNWhiteBoardViewController附加到布局中时有效（即必须有可见的白板），屏幕截图是需要直接调用QNWhiteBoardViewController的如下方法，无论是否在主线程都可以调用，返回是直接返回一个临时地址，存储了snapshot的图片，回调一定不是在主线程中。

-(void)snapShot:(CGRect)rect_ callback:(void(^)(NSString * _Nullable))callback_;

加入房间

首先访问自己的服务器获取要加入的白板房间的roomId,token,appId等参数（房间的创建和token的生成由服务器对接SDK服务端接口）。此接口需要在白板初始化完成之后来进行

首先构建进房参数QNWhiteBoardJoinInfo和QNWhiteBoardRoomMember然后执行QNWhiteboardControl来加入房间。

    QNWhiteBoardJoinInfo * joinInfo = [[QNWhiteBoardJoinInfo alloc] initWithParam:appId room:roomId user:userId  token:token];
    QNWhiteBoardRoomMember * member = [[QNWhiteBoardRoomMember alloc] initWithParams:userId session:nil role:6 name:nil avatar:nil];
    [[QNWhiteboardControl instance] joinRoom:joinInfo member:member];

如果加入房间成功，会收到onJoinSuccess回调，如果加入失败会收到onJoinFailed回调。

关闭并离开房间

房间关闭时，或者在ViewController.viewDidDispear时，必须调用leaveRoom来退出房间并释放资源，
此方法会同时完成离开房间和资源释放.
(#autoremovewhiteboardlistener)类型的事件监听器（推荐），多次执行是安全的。

通常情况会把它放在ViewDidDisappear中执行，比如：

-(void)viewDidDisappear:(BOOL)animated
{
    if(self.isMovingFromParentViewController)
    {
        //离开房间先
        [[QNWhiteboardControl instance] leaveRoom];
		//销毁各种资源
        [super closeWhiteboard];
    
    }
}

关键方法

• 所有用户可以主动调用的方法都是QNWhiteboardControl类的方法。
• 使用QNWhiteboardControl的类方法前，先通过instance静态方法获取到QNWhiteboardControl的唯一实例。

主动控制的方法

获取白板当前属性的方法

添加事件监听器

• 通过调用[[QNWhiteboardControl instance] addListener]可以添加事件监听器，可以在任何时期添加，包括进入白板之前。
• 所有的事件都在QNWhiteboardDelegate接口中。如果添加此类的直接子类作为监听器，则添加后必须由用户手动调用[[QNWhiteboardControl instance] removeListener来移除。此方式通常用于在房间外监听房间中发生的事并记录日志或触发某些全局事件时使用。

QNWhiteboardControl

所有白板SDK的主动用户接口，所有接口线程安全

joinRoom

-(void)joinRoom:(QNWhiteBoardJoinInfo *)roomInfo_ member:(QNWhiteBoardRoomMember *)me_

进入白板房间

只有此方法执行成功才能连通白板，目前sdk仅支持同时进入一个房间，多次调用是安全的，但仅有第一次调用的参数有效，后续调用会被忽略，如需进入其它房间，需要先执行leaveRoom。

加入成功后本地会收到onJoinSuccess回调，加入失败则会收到onJoinFailed回调。
同时远端用户会收到onUserJoin回调。

如果已经加入成功但是发生了掉线，则SDK会尝试自动重连，并收到onReconnecting回调。
重连次数可以通过setRetry修改，重连成功后会收到onReconnected，重连失败会收到onDisconnected，此时必须用户手动调用此方法重新加入房间。

leaveRoom

-(void)leaveRoom

离开白板房间

该方法会断开白板连接并释放资源，同时会清理所有的QNWhiteboardDelegate的监听器。
多次调用是安全的。
离开白板后远端用户会收到onUserLeave回调。

addListener

-(void)addListener:(id<QNWhiteboardDelegate>)delegate_

添加一个白板事件监听器

可以在joinRoom之前或之后添加

removeListener

-(void)removeListener:(id<QNWhiteboardDelegate>)delegate_

移除一个白板事件监听器

可在任何时候调用。

clearListener

-(void)clearListener

清空所有白板监听器

可在任何时候调用。

setDefaultInputMode

-(void)setDefaultInputMode:(QNWhiteBoardInputConfig *)config_

设置白板的默认初始输入模式配置

在joinRoom之前调用有效，已经进入房间时调用此方法不会改变当前的输入模式，仅会影响下次进入房间的输入模式。
如需改变当前房间中的输入模式，请调用setInputMode方法。

此方法用于预先设定加入房间后的初始输入配置，反复加入离开房间不会影响此默认设置。
默认设置不会随setInputMode方法改变，即一次设定长期有效。

setRetry

-(void)setRetry:(int)count_

设置白板断线自动重连次数

默认为10次，设为0表示不自动重连。

setInputMode

-(void)setInputMode:(QNWhiteBoardInputConfig*)config_

改变白板的输入模式

此方法用于已经连通白板房间时改变用户对白板的输入模式，包括例如笔迹的粗细和颜色等。

setBackgroundColor

-(void)setBackgroundColor:(NSString *)color_

设置白板背景色 格式为“#AARRGGBB”

用于在白板房间中改变当前白板页的背景色，未进入房间调用无效。

• 仅能改变当前页面的背景以及此后新增的页面背景，不会影响已经存在的页面背景。
• 如需设定新房间的初始背景色，请在服务器创建房间时设定。

scroll

-(void)scroll:(float)offsetY_

垂直滚动白板显示区

• 目前白板是一个纵向可滚动（高大于宽）的矩形，通常白板的可视区WhiteBoardViewport不能呈现完整白板，需要通过滚动来控制可见区。
• 白板内部可以通过用户的双指操作来滚动白板，无需外部干涉，此方法的目的是方便用户实现类似top按钮或滚动条功能。

无论是调用此方法还是用户通过白板手势滚动了白板（包括远程用户滚动白板），都会触发onBoardScroll回调。

newBoardPage

-(void)newBoardPage

新增白板页

在房间中调用可以在当前页列表末尾插入一个新的页面并会自动跳转到这个新页面。

页面创建成功后用户会收到onCurrentBoardPageChanged、onBoardPageList、onBoardPageInfoChanged三个回调。

insertBoardPage

-(void)insertBoardPage:(NSString *)pageId_

插入新白板页

在指定的页面之前插入一个新白板页，同时白板会自动跳转到新插入的页面。

页面创建成功后用户会收到onCurrentBoardPageChanged、onBoardPageList、onBoardPageInfoChanged三个回调。

jumpBoardPage

-(void)insertBoardPage:(NSString *)pageId_

跳转到指定白板页

直接跳页的实现方式。

跳转成功后用户会收到onCurrentBoardPageChanged、onBoardPageInfoChanged回调。

preBoardPage

-(void)preBoardPage;

返回到上一页

成功后用户会收到onCurrentBoardPageChanged、onBoardPageInfoChanged回调。

nextBoardPage

-(void)nextBoardPage

前进到下一页

成功后用户会收到onCurrentBoardPageChanged、onBoardPageInfoChanged回调。

deleteBoardPage

-(void)deleteBoardPage:(NSString *)pageId_

删除白板页

删除成功后一定会收到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回调（与房间人数有关），此回调仅表达了导致文件状态变化的用户信息和此用户的加载情况，
通常用于在界面上表达房间中各成员对此文件的加载状态。

jumpFilePage

-(void)jumpFilePage:(NSString *)widgetId_ pageNo:(int)pageNo_

文件翻页

对于可翻页的文件，如pdf和office文件，通过调用此方法可以使文件跳到指定序号的页面。

翻页成功后会收到onFilePageChanged回调。

deleteFile

-(void)deleteFile:(nonnull NSString *)widgetId_

删除文件

删除后会触发onWidgetActionEvent回调，如果删除的文件是当前正在激活的widget，则会收到onWidgetActive回调，并且参数为null。

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回调获取的值一致。

• 返回
  • 如果为YES表示有可还原的笔迹，此时可通过调用recover来还原一次擦除操作。NO时调用recover无效。

getViewport

-(QNWhiteBoardInfo *)getViewport;

获取当前白板的可视区信息，包括白板的大小和偏移

此数据与监听onBoardSizeChanged和onBoardScroll获取的数据一致。
滚动白板可由用户双指手势拖动白板，也可通过程序主动调用scroll完成。

• 返回
  • 白板的可视区WhiteBoardViewport，通常此值是跟随用户滚动白板而变化，如果未加入房间则会返回nil

QNWhiteboardDelegate

所有的白板事件的监听器，所有事件响应均在主线程回调。
可通过addListener添加。

onJoinSuccess

-(void) onJoinSuccess:(QNWhiteBoardRoom *)room_ who:(QNWhiteBoardRoomMember *)me_

成功加入白板房间

joinRoom成功后的第一个关键事件（onBoardStatusChanged返回QNWBBoardStatusSuccessful会先一步触发）。
在这里可以处理一些加入房间成功时的初始化工作。

• 在断线重连成功时同样会触发此事件，之后才会触发onReconnected事件。

onJoinFailed

-(void) onJoinFailed:(int)errorCode_

加入房间失败

joinRoom执行失败后触发，因为并没有成功加入房间，所以不会执行自动重连。
失败后需要用户重新调用joinRoom来加入房间。
如果已经成功加入了房间但是发生了断线则会触发onReconnecting尝试自动重连，重连失败则会触发onDisconnected，而不会触发本事件。

onReconnecting

-(void) onReconnecting:(int)time_

白板正在自动重连

当白板连接意外断开比如网络波动等，白板会自动尝试重连，在每次尝试开始时会触发此事件。
重连成功后会先触发onJoinSuccess后触发onReconnected，
重连次数达到上限后会触发失败事件onDisconnected。
首次调用joinRoom失败不会自动重连，而是触发onJoinFailed。

重连次数默认10次，可通过setRetry修改。

onReconnected

-(void)onReconnected

自动重连成功

参考onReconnecting。

onDisconnected

-(void)onDisconnected

自动重连失败，白板彻底断开连接

即在onReconnecting重试次数达到上限后触发，
此时需要用户重新执行joinRoom加入房间。

onBoardStatusChanged

-(void) onBoardStatusChanged:(QNWBBoardStatus)status_

白板房间状态变化

从joinRoom到leaveRoom之间，只要白板房间的状态发生变化就会触发此事件。
同时此事件触发早于onJoinSuccess，onJoinFailed，onReconnecting等独立事件。
比如调用joinRoom后会立即触发QNWBBoardStatusLoading的变化，onJoinSuccess触发之前会先触发QNWBBoardStatusSuccessful的变化。

onUserList

-(void) onUserList:(NSArray *)users_

当前已经在房间中的用户列表（包括自己）

加入房间后会触发一次返回已经在房间中的用户，自动重连成功后也会触发。

• 如果自己管理用户列表，需要以此回调的作为列表初始数据，并且在重连成功后重置初始列表。
• 后续的远端用户进出事件由onUserJoin和onUserLeave反馈。
• getUsers总是获取当前的完整用户列表。

onUserJoin

-(void) onUserJoin:(QNWhiteBoardRoomMember *)user_

有远端用户加入了房间

• 如果自己维护用户列表，注意更新列表数据

onUserLeave

-(void) onUserLeave:(QNWhiteBoardRoomMember *)user_

有远端用户离开了房间

• 如果自己维护用户列表，注意更新列表数据

onBoardPageList

-(void) onBoardPageList:(NSArray *)list_

白板页信息列表

在首次进入房间和白板页列表结构变化时触发，比如新增页，删除页等等。
仅翻页不会触发此事件。

onCurrentBoardPageChanged

-(void)onCurrentBoardPageChanged:(QNWhiteBoardPageInfo *)page_

白板当前页改变

在首次加入房间后和翻页时触发，新增页由于会自动切换到新页面，所以也会触发。

onBoardPageInfoChanged

-(void)onBoardPageInfoChanged:(QNWhiteBoardPageInfo *)page_

某一个白板页信息变化

目前仅白板页的缩略图地址发生变化时才会触发此事件，每当白板发生翻页时都会自动更新上一个页面的缩略图，
所以通常情况下此事件触发的白板页信息不是当前正在显示的页面。

• 由于页号QNWhiteBoardPageInfo.page的变化是新增和删除页导致，可能同时影响大量的页信息，所以页号变化没有单独的事件，只能监听onBoardPageList观察整个列表的变化。

onBoardSizeChanged

-(void)onBoardSizeChanged:(QNWhiteBoardInfo*)info_

白板大小变化（虚拟大小）

在白板设定的虚拟大小变化时触发，首次进入白板一定会触发一次。

onBoardScroll

-(void)onBoardScroll:(QNWhiteBoardInfo*)info_

白板滚动

白板内发生滚动时触发，主动调用scroll也会触发，首次进入白板也会触发。

onBackgroundColorChanged

-(void)onBackgroundColorChanged:(NSString *)backgroundColor

白板背景色改变

当前的白板背景色变化时触发，首次进入白板也会触发。
可通过setBackgroundColor随时改变背景色。

onWidgetActive

-(void)onWidgetActive:(QNActiveWidgetInfo * _Nullable)info

有新的widget被激活

用户书写或操作白板时会激活被操作的widget，同时触发此事件，比如移动文件时会收到被移动的文件信息，在白板上写字时会收到白板的信息。
当此widget是文件且此文件发生翻页后会再次触发此事件，同时也会触发onFilePageChanged。

onFilePageChanged

-(void)onFilePageChanged:(QNActiveWidgetInfo *)info

文件页改变

当文件被翻页时触发，同时会触发onWidgetActive。
当前仅被激活的文件发生翻页时才会收到此事件。
文件翻页可通过调用jumpFilePage实现。

onWidgetActionEvent

-(void)onWidgetActionEvent:(QNWhiteBoardWidgetActionEvent *)event

widget被执行了某些关键动作

比如有人插入文件或删除文件会收到此事件。
同时每个远端用户的文件加载情况也会触发此事件，通过此事件可以观察到每个人文件加载成功或失败情况。

• 当前仅文件和图片widget会触发此事件。

onRecoveryStateChanged

-(void)onRecoveryStateChanged:(BOOL)isEmpty

笔迹回收站空与非空的状态变化

当在擦除模式QNWBInputModeErase擦除笔迹时被擦除的笔迹会移动到回收站导致回收站不为空，会触发此事件。
当反复调用还原笔迹recover导致回收站为空时会触发此事件。
当从擦除模式切换到其他模式或白板翻页后会自动清空回收站，同样有可能触发此事件。

ScreenshotsCallback

截图完成回调

screenshots中使用。

ScreenshotsCallback.done

void done(@Nullable Bitmap bitmap)

截图完成

WhiteBoardView

白板的显示控件，用于显示白板内容，当前仅支持同时显示一个白板，如果同时放置了多个白板控件，仅最后一个控件会刷新内容。
布局时此控件的大小最好设定为与白板的虚拟大小WhiteBoardSize的宽高比保持一致，否则多余的边缘会留白。

QNWhiteBoardJoinInfo

加入房间时的参数配置

构造函数
-(instancetype)initWithParam:(NSString *)appId_ room:(NSString *)roomId_ user:(NSString *)userId_ token:(NSString *)token_

QNWhiteBoardInputConfig

输入模式配置
此类仅提供静态工厂方法。

普通笔

+(instancetype)instanceWithPen:(NSString *)color_ thickness:(float)thickness_

创建一个笔书写输入模式配置

激光笔

+(instancetype)instanceWithLaser:(QNWBPenStyle)laserType_

创建一个激光笔输入模式配置

激光笔是一种瞬时的位置指示型输入模式，指示手指位置的内容。

橡皮

+(instancetype)instanceWithErase:(float)size_

创建一个橡皮（擦除）输入模式配置

几何图形

+(instancetype)instanceWithGeometry:(QNWBGeometryType)geometryType_ color:(NSString *)color_ thickness:(float)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_;

QNActiveWidgetInfo

被激活的widget信息

白板中的一切都是widget，包括白板，文件，图片，选择框等等，具体参考QNWBWidgetType。
当用户操作了一个widget或者在它上面书写时，这个widget会被激活，会触发onWidgetActive事件。

QNWhiteBoardRoom

房间信息

加入白板房间成功后会收到此数据。

QNWhiteBoardRoomMember

房间中的成员信息

QNWhiteBoardPageInfo

白板页信息

QNWhiteBoardInfo

白板的基本信息

此信息的数值基于白板内部的虚拟大小和坐标系，并非实际渲染窗口的纹理大小（实际的纹理大小由QNWhiteBoardViewController的像素大小决定）。
以下参数由服务器创建白板房间时指定，通常在一个房间中此信息是固定不变的。

QNWhiteBoardWidgetActionEvent

widget动作事件

描述了对文件或图片的关键操作信息，包括加载情况，由谁插入或删除等。
由onWidgetActionEvent提供。

QNWBBoardStatus

白板房间状态枚举

QNWBBoardStatusIdle

空闲状态，表示没有进入白板

QNWBBoardStatusLoading

正在进入白板，即调用joinRoom之后到成功或失败之前的状态。

QNWBBoardStatusSuccessful

加入白板成功

QNWBBoardStatusFailed

加入白板失败

QNWBBoardStatusReconnecting

白板正在重连

QNWBGeometryType

几何图形类型

在QNWBGeometryType中指定要绘制的几何图形。

QNWBPenStyle

激光笔类型

在InputConfig.laserPen中指定激光指示点的样式。

QNWBWidgetType

widget类型，白板中的一切都是widget

QNWBWidgetAction

widget动作类型

在onWidgetActionEvent中指示widget具体发生的动作事件。

ErrorCode

错误码