1、牛牛截图控件桌面版调用说明本说明文档旨在对截图控件的 API 进行说明，指导调用者顺利的将截图控件集成进第三方产品中，使第三方产品也能拥有完美的牛牛截图功能。控件有三个接口：InitScreenCaptureW，InitCaptureParamW 以及StartScreenCaptureW，具体可以参考调用NiuniuCapturedemo_Window_source.zip。对于上述三个接口，也可以使用不带 W 的版本，区别在于传递字符串时不使用Unicode 编码，而直接使用 Ansi 字符串即可: InitScreenCapture，InitCaptureParam 以及 StartSc
2、reenCapture。接口的具体描述如下：1. 接口初始化接口 int InitScreenCaptureW(const wchar_t* szAuth);此接口函数用于初始化截图控件的授权信息，默认的授权码为：“niuniu“.参数说明：参数名 参数类型 参数说明 备注szAuth 字符串 接口调用的授权码默认的授权码为：“niuniu“2. 参数初始化接口int InitCaptureParamW(int flag, unsigned long flagvalue);此接口函数用于初始化截图各个状态下的界面的显示效果，如果不调用，则以默认值处理。参数说明：参数名 参数类型 参数说明 备注
3、flag int 要设置的参数项 此处对应的枚举ExtendFlagTypeEnum的整形值 flagvalue unsigned long设置的参数值 根据不同的枚举来设置不同的值 枚举定义如下:typedef enum ExtendFlagTypeEnumemPensize = 1, / emDrawType, / emTrackColor, / emEditBorderColor, / emTransparent, / emWindowAware,emDetectSubWindowRect,emSetSaveName,emSetMagnifierBkColor, /设置放大镜的背景色，不
4、设置则透明emSetMagnifierLogoText, /设置放大镜上的LOGO字符，可提示快捷键，如：牛牛截图(CTRL + SHIFT + A)emSetWatermarkPictureType=20, /设置水印的类型emSetWatermarkPicturePath, /设置水印的路径emSetWatermarkTextType, /设置水印文字的类型emSetWatermarkTextValue, /设置水印文字emSetMosaicType, /设置马赛克类型，1为矩形，2为画线emSetToolbarText, /设置工具栏上的各按钮的tooltip及显示的文字;枚举项的说明如
5、下：枚举参数名 枚举对应数值参数值说明 备注emPensize 1 设置画笔大小 如不设置，默认为 2emDrawType 2 设置是腾讯风格还是 360 风格0 表示腾讯风格，1表示 360 风格emTrackColor 3 Track 及自动识别的边框的颜色如：RGB(255, 0, 0)emEditBorderColor 4 文本输入框的边框颜色 如：RGB(0, 174, 255)emTransparent 5 工具栏的透明度 默认为 220emWindowAware 6 设置是否禁用随着 DPI 放大，flagvalue 传递任意值均可此项设置非常重要，相当于调用SetProcess
6、DPIAware，如果不设置，在高DPI 的环境下，截图将会错乱,请在程序窗口创建前调用emDetectSubWindowRect7 是否自动检测子窗口，暂时无用未使用emSetSaveName 8 设置保存时的文件名称 如：const wchar_t* szName = L“测试名“;InitCaptureParam(emSetSaveName, (unsigned long) szName);注：免费版本此接口无效，将会显示默认值emSetMagnifierBkColor9 用于设置放大镜的背景色 一般不建议设置，默认透明即可emSetMagnifierLogoText10 设置放大镜上的
7、显示的LOGO 文字 如：const wchar_t* szLogoName = L“测试名“;InitCaptureParam(emSetMagnifierLogoText, (unsigned long) szLogoName);注：免费版本此接口无效，将会显示默认值 以下是水印设置功能，如果不需要则无需关注 emSetWatermarkPictureType20 用于设置水印图片的绘制方式此参数设置具有默认值，仅在授权版本中才可修改设置，具体见下面的水印图片说明emSetWatermarkPicturePath21 用于设置水印图片的路径 注：此处的路径需要使用 Unicode 编码em
8、SetWatermarkTextType22 用于设置水印文字绘制方式 此参数设置具有默认值，仅在授权版本中才可修改设置，具体见下面的水印文字设置说明emSetWatermarkTextValue23 用于设置水印文字 注：此处的文字需要使用 Unicode 编码emSetMosaicType 24 设置马赛克类型 1 为矩形，2 为画线emSetToolbarText 25 设置工具栏图标的 tooltip 此参数设置具有默认及完成按钮的文字，用于支持多语言环境下的截图支持值，仅在授权版本中才可修改设置，具体见下面的设置图标TOOLTIP 说明a). 水印图片设置参数说明：此处的参数值是一个
9、字符串，以|为分割符，如：/nShowType|nMinWidth|nMinHeight|nMaxWidth|nMaxHeight|nShowOffset未授权时，此参数对应的设置将采用默认值，不可修改；默认支持的图片大小为200*200，超过此大小的地方，将仅显示是在 200*200 范围内的图片。各字段意义如下：参数名 参数值说明 备注nShowType 设置绘制类型 1 表示在中间显示水印；2 表示在右下显示水印；3 表示复合类型默认在中间添加水印，当满足宽与高大于 maxwidth及 maxheight 时同时在个角显示水印默认类型为 1 nMinWidthnMinHeight设置图片
10、绘制水印图片的最小尺寸 当图片尺寸宽或高小于设置时，则不会绘制水印默认：60*60nMaxWidthnMaxHeight当宽度与高度大于 MAX 设置时将会在个角显示水印这两个选项仅在nShowType 为 3 时有效默认：600*600nShowOffset 控制在显示水印时的偏移中间显示不生效，同时控制各角的偏移例如：如显示在左上角时，此偏移表示离左边及上边的偏移值默认 20示例：const wchar_t* szWatermarkFlag = L“3|100|100|400|400|20“;b).水印文字的设置说明：此处的参数值是一个字符串，以|为分割符，如：/nShowType|nMi
11、nWidth|nMinHeight|nVerticalInterval|nOffset|nFontSize|nIsBold|nTextWidth|nTextHeight|colorText/colorText 的值为：A,R,G,B未授权时，此参数对应的设置将采用默认值，不可修改。各字段意义如下：参数名 参数值说明 备注nShowType 设置绘制类型 1 表示在中间显示水印文字；2 表示在右下显示水印文字；3 表示复合类型，在图中间从上至下循环添加45 度倾斜的水印文字默认类型为 3 nMinWidthnMinHeight设置图片绘制水印图片的最小尺寸 当图片尺寸宽或高小于设置时，则不会绘制
12、水印默认 60,60nVerticalInterval 循环绘制倾斜水印文字的间隔高度 此选项仅在 nShowType为 3 时有效默认 150nOffset 控制在显示水印文字时的偏移中间显示不生效 在 nShowType 为 2 时有效，表示离右下角的偏移；在 nShowType 为 3 时，表示顶部起始位置的偏移默认 20nFontSize 水印文字的字号 默认 20nIsBold 水印文字是否加粗 默认否nTextWidth 水印文字所占的宽度，当字所占宽度超过这个宽度时，将不会显示 建议在设置中测试好宽度再进行二次设置默认 150nTextHeight 水印文字所占的高度 建议在设置
13、中测试好宽度再进行二次设置默认 50colorText 以逗号为分隔的 ARGB 色彩设置 如：55,255,0,0 表示透明度是 55 的红色默认：#66333333示例：const wchar_t* szWaterTextFlag = L“3|60|60|150|20|20|0|200|50|80,55,55,55“;c).工具栏图标 tooltip 设置说明：此处的参数值是一个字符串，以|为分割符，如：/tipRectangle|tipCircle|tipArrow|tipBrush|tipGlitter|tipMosaic|tipText|tipUndo|tipSave|tipCanc
14、el|tipFinish|txtFinish未授权时，此参数对应的设置将采用默认值，不可修改。各字段意义如下：参数名 参数值说明 备注tipRectangle 设置矩形按钮的 tooltip 默认为：“矩形工具”tipCircle 设置椭圆按钮的 tooltip 默认为：“椭圆工具”tipArrow 设置箭头按钮的 tooltip 默认为：“箭头工具”tipBrush 设置画刷按钮的 tooltip 默认为：“画刷工具”tipGlitter 设置荧光笔按钮的 tooltip 默认为：“荧光笔工具”tipMosaic 设置马赛克按钮的 tooltip 默认为：“马赛克工具”tipText 设置文
15、字按钮的 tooltip 默认为：“文字工具”tipUndo 设置撤销按钮的 tooltip 默认为：“撤销”tipSave 设置保存按钮的 tooltip 默认为：“保存”tipCancel 设置取消按钮的 tooltip 默认为：“结束截图”tipFinish 设置完成按钮的 tooltip 默认为：“完成截图”txtFinish 设置完成按钮的显示文字 默认为：“完 成 ” 示例：const wchar_t* sz ToolbarText = L“Rectangle|Circle|Arrow|Brush|Glitter|Mosaic|Text|Undo|Save|Cancel|Finis
16、h|Finish“;3. 启动截图接口int StartScreenCaptureW(const wchar_t* szDefaultSavePath, void* pCallBack, unsigned long hWndNotice, unsigned int noticeMsg, unsigned long hwndHideWhenCapture, int autoCapture, int x, int y, int width, int height);此接口用于实际的截图调用，传递相关的截图控制参数，控制截图时的行为，以及告知截图完成时消息通知的方法。参数说明：参数名 参数类型 参数
17、说明 备注szDefaultSavePath 字符串 用于指定在截图完成时自动保存的文件路径如：c:test.jpg，如果此字符串为空，则完成时将只写入剪贴板注：这是一个 UNICODE 编码的字符串pCallBack Void* 用于指定在截图完成时自动回调的函数用于通知调用程序截图的响应事件完成、取消、保存，具体回调函数的原型见下面的介绍hWndNotice UINTnoticeMsg UINT用于指定截图完成时发送通知的窗口句柄及发送的消息用于通知调用程序截图完成，截图完成时，控件将会发送消息：:PostMessage(hWndNotice, noticeMsg, 1, 1);hwndH
18、ideWhenCaptureUINT 用于指定在截图时要隐藏掉的窗口 主要适用于在截图时需要隐藏当前窗口的情况此处如果传递 NULL，则截图时直接截图autoCapture int 标识截图的方式 此参数共有三个值：0：表示普通截图1：表示截取指定区域，区域由x、y、width、height 参数指定2：表示截取当前桌面x inty intwidth intheight int指定截图的区域 这 4 个值仅在参数autoCapture 的值为1 时会起作用pCallBack 回调函数的参数说明：参数名 参数类型 参数说明 备注nType Int 表示截图处理类型 1 表示截图完成；2 表示截图
19、被取消；3 表示执行了图片保存x inty intwidth intheight int完成截图后返回截图的区域坐标szInfo 字符串 额外信息 当 type 为 3 时，此值表示保存的路径注：这是一个 UTF8 编码的字符串可以在程序中使用 LoadLibrary 的方式加载此控件，进行初始化后，直接调用启动截图的函数即可 以下是在 C+程序中的调用示例，其他语言均可通过类似的方式实现加载:typedef int (_stdcall *FnStartScreenCaptureW)(const wchar_t* szDefaultSavePath, void* pCallBack, UINT
20、_PTR hWndNotice, UINT_PTR noticeMsg, UINT_PTR hwndHideWhenCapture, int autoCapture, int x, int y, int width, int height);FnStartScreenCaptureW gl_StartScreenCapture = NULL;typedef int (_stdcall *FnInitScreenCaptureW)(const wchar_t* szAuth);FnInitScreenCaptureW gl_InitCapture = NULL;typedef int (_std
21、call *FnInitCaptureParamW)(int flag, UINT_PTR flagvalue);FnInitCaptureParamW gl_InitCaptureParam = NULL;/加载截图控件string strDllPath = GetCurrentPathA() + “NiuniuCapture.dll“;#ifdef _X64strDllPath = GetCurrentPathA() + “NiuniuCapturex64.dll“;#endifm_hModule = LoadLibrary(strDllPath.c_str();DWORD dRet =
22、GetLastError();gl_StartScreenCapture = (FnStartScreenCaptureW)GetProcAddress(m_hModule, “StartScreenCaptureW“);gl_InitCapture = (FnInitScreenCaptureW)GetProcAddress(m_hModule, “InitScreenCaptureW“);gl_InitCaptureParam = (FnInitCaptureParamW)GetProcAddress(m_hModule, “InitCaptureParamW“);/此处可直接传递niun
23、iu 作为授权密码 gl_InitCapture(L“niuniu“);gl_InitCaptureParam(ExtendFlagTypeEnum:emPensize, 2); /画笔线宽wstring strSavePath = L“牛牛截图“;gl_InitCaptureParam(ExtendFlagTypeEnum:emSetSaveName, (UINT_PTR)strSavePath.c_str(); /设置保存时的开始文字gl_InitCaptureParam(ExtendFlagTypeEnum:emSetMagnifierBkColor, RGB(255, 255, 255
24、); /设置放大镜的背景色，不设置则透明/以下可以设置放大镜上的LOGO文字，如果不设置，默认显示“ 牛牛截图”/gl_InitCaptureParam(ExtendFlagTypeEnum:emSetMagnifierLogoText, (UINT_PTR)“牛牛截图(Ctrl+Shift+A)“);wstring strMagnifierLogoText = L“ 可通过接口设置名称“;gl_InitCaptureParam(ExtendFlagTypeEnum:emSetMagnifierLogoText, (UINT_PTR)strMagnifierLogoText.c_str();/
25、以下是在实际截图时的参数传递 /截图时传递窗口句柄及消息，在截图完成后，控件将会发送此消息到这个窗口句柄上 m_ StartScreenCapture (L“, NULL, (unsigned long)m_hWnd, WM_USER + 1111, 0, 0, 0, 0, 0, 0);/或者定义一个回调函数，传递给接口，截图完成后，此函数将会被调用，并将截图的区域的坐标及宽度、高度反馈回来 HWND gl_hWnd = NULL;void CaptureNotice(int nType, int x, int y, int width, int height, const char* szI
26、nfo)switch(nType)case 1:SetDlgItemText(IDC_STATIC_NOTICE, “截图完毕“);break;case 2:SetDlgItemText(IDC_STATIC_NOTICE, “您取消了截图“);break;case 3:SetDlgItemText(IDC_STATIC_NOTICE, “您保存了截图“);break;m_ StartScreenCapture (“, CaptureNotice, NULL, NULL, 0, 0, 0, 0, 0, 0);4. 启动独立进程截图的接口方式为了解决某些语言集成难度较大，时间成本较高的问题。我们
27、现在提供了一种独立exe的形式，在目标语言框架下，只要启动我们的截图exe程序，并且等待其结束，根据进程退出的返回值，判断截图结果，进一步进行处理即可。这种集成方式的优点在于几乎没有集成的技术门槛，能够快速的集成；缺点在于每次截图都新打开一个进程，性能会较DLL集成方式要差一点。1). exe截图方式共需要如下几个文件，各自职能描述如下：文件名称 格式 作用描述 备注NiuniuCapture.dll dll 承载截图的核心功能NiuniuCapture.exe Exe 封装截图功能，提供命令行截图接口capture.ini ini 截图的常规配置放到ini文件中由于进程截图方式是一次性交互，
28、所能传递的信息有限，故此处将配置信息放到ini文件中2). capture.ini配置信息的详情描述如下：此配置文件采用截图控件参数的枚举值为key，各自配置其选项，Capture.exe会读取每一个配置项进行设置。3). NiuniuCapture.exe的命令行参数及返回值启动截图的主要参数，通过命令行参数传入，savepath需要传递完整的路径。a) 接口格式如下：NiuniuCapture.exe authcode,savepath,hideCurrentWindow,autoCaptureFlag,xPos,yPos,nWidth,nHeight参数名 参数类型 参数说明 备注authcode 字符串 授权密码savepath 字符串 用于指定在截图完成时自动保存的文件路径如：c:test.jpg，如果此字符串为空，则完成时将只写入剪贴板注：这是一个 UNICODE 编码的字符串hwndHideWhenCaptureUINT 用于指定在截图时要隐藏掉的窗口 主要适用于在截图时需要隐藏当前窗口的情况此处如果传递 NULL，则截图时直接截图autoCapture int 标识截图的方式 此参数共有三个值：0：表示普通截图1：表示截取指定区域，区域由
