acrobat插件开发资料 开发插件和应用程序

第4节 Handling events
你可以使用Acrobat core API操作不同类型的事件。
（1）鼠标点击：
（2）调整光标：
（3）键按下：
第5节 使用插件前缀
第6节 修改Acrobat或Adobe Reader用户接口
第7节 获取和注册对象
第8节 调试插件
第9节 页浏览层
在PluginExportHFTs函数中，一个插件可以导出一些HFTs，打算提供给其它插件使用。这个回调函数应该只导出HFT，不要调用其它Acrobat核心API方法。相关信息请参考第164页的“Working with Host Function Tables”。
注意：这是一个插件能导出HFT的唯一机会。
类型检查只在这时发生 --- 如果宏定义DEBUG被设置为1，当你的插件被编译时。确定它在你的开发环境中被适当地设置，并且在你建立插件的注册版本时移除它。
下述代码例子说明了创建一个回调函数的句法：
AVExecuteProc ExecProcPtr = NULL;
ExecProcPtr= ASCallbackCreateProto(AVExecuteProc, &ShowMessage);
握手和初始化：
Acrobat或Adobe Reader执行握手动作，在每一个插件被打开和载入时。在握手期间，插件说明自己的名字，几个初始化程序，和一个可选择的卸载程序。
一个插件必须执行下面的握手函数：
ACCB1 ASBool ACCB2 PIHandshake(ASUns32 handshakeVersion, void, *hsData)
所有的回调函数必须用Pascal调用惯例声明。为了使你的代码在平台间通用，使用ACCB1 和 ACCB2 宏定义声明你的所有的回调函数：
static ACCB1 const char* ACCB2 ShowMessage(Thing*?foo);
第3节 Notifications
Acrobat core API 提供一个通知机制，以便插件能够与Acrobat或Adobe Reader同步动作。Notifications使插件能够指出自己对一个特定的时间感兴趣（比如一个注释被更改了），并且在每次事件发生的时候，提供一个程序给Acrobat调用。相关信息请参考第151页“Registering for Event Notifications”。
（1）移除并释放所有的菜单条目和其它用户接口元素，HFTs，以及HFTServers。
（2）释放所有内存或所有其他分配的资源。
通常，插件只有在Acrobat退出时卸载。
一个插件的生命周期摘要：
下列步骤描述了一个插件的生命周期：
1. 启动时，Adobe Reader或Acrobat搜索它的插件目录，查找插件文件。
宏定义ASCallbackCreateProto返回一个指定类型的回调函数，用来调用用户自定义的函数，函数的地址作为第二个参数被传递。在这个例子中，函数ShowMessage被转换为一个回调函数，ShowMessage是一个指定动作发生时被调用的用户自定义函数。
宏定义ASCallbackCreateProto返回一个指向函数的指针，此函数能被插件调用或被Acrobat，Adobe Reader调用。如果不再需要，使用ASCallbackDestroy方法除掉回调函数。
ACCB1 ASBool ACCB2 PluginInit(void);
ACCB1 ASBool ACCB2 PluginUnload(void);
所有的回调函数返回true，如果你的插件的声明成功地完成，或者回调函数是可选的并且没有被执行。如果你的插件声明失败，返回false。不管是Acrobat, Adobe Reader，还是一个插件中止握手，Acrobat或Adobe Reader都提示一个警告对话框，在载入其它插件之前显示一个解释摘要。在最少的情况下，一个插件必须执行PluginInit回调。
●PluginImportReplaceAndRegister
●PluginInit
这个顺序建立了关联，在插件和Adobe Reader或Acrobat之间，也在插件和任何其它插件之间。一旦所有的插件被载入，Adobe Reader或Acrobat继续它的自载入过程和启动用户接口。它把任何插件提供的工具添加到工具条和菜单条目上，然后启动用户对话。
在握手期间，插件接收一个hsData数据结构 (在PIVersn.h文件中定义)。Acrobat或Adobe Reader用ASCallbackCreateProto方法，把所有的被传递到这个数据结构里的函数指针转换到回调函数里。关于这个方法的信息，参考文档《Acrobat and PDF Library API Reference》。
1. 找到Adobe Reader或Acrobat菜单条（被AVmenubar对象描述），通过调用AVAppGetMenubar方法：
AVMenubar Themenubar = AVAppGetMenubar();
2. 找到将要包含新菜单命令的菜单，通过调用AVMenubarAcquireMenuByName方法，并传递下列参数：
当创建一个插件时，在思想里遵守如下规则：
1. 不要在你的插件初始化时创建对话框，或做其它可能妨碍Acrobat或Adobe Reader成功启动的工作。应用通过IAC（interapplication communication）被启动，它不会对响应你的对话框有所表现。
2. 执行一个PluginUnload程序，释放分配的内存。这个程序通过在初始化程序中返回false被调用。在正常条件下，这个程序不会被调用，直到用户关闭Acrobat或Adobe Reader。
第2章 理解插件
这一章提供一个总览，插件如何被载入，被初始化，被卸载，以及其它与插件和PDF库应用相关的概念。推荐你在开始开发插件或PDF库应用之前阅读本章节。
第1节 关于插件初始化
这部分描述Acrobat或Adobe Reader执行初始化插件的操作顺序。
插件载入和初始化：
当Acrobat或Adobe Reader启动时，自动检索\Program Files\Adobe\Acrobat\plug_ins目录，定位和载入插件。另外，Acrobat或Adobe Reader也检索包含在这个目录里的子目录。这个检索工作只有一级深度。
头文件DUCallbacks.h声明了所有的回调方法，这些方法必须在你的插件中被定位。下面显示这些回调方法的函数声明：
ACCB1 ASBool ACCB2 PluginExportHFTs(void);
ACCB1 ASBool ACCB2 PluginImportReplaceAndRegister(void);
2. 对于每个插件文件，Adobe Reader或Acrobat都尝试载入这个文件。如果插件被成功载入，Adobe Reader或Acrobat调用PIMain.c中的函数，完成握手过程。
3. Adobe Reader或Acrobat按如下顺序调用回调函数：
●PluginExportHFTs
3.重置任意的Acrobat API的可重置HFT方法。相关信息请参考第174页的“Replacing HFT methods”。
注意：这是一个插件可以导入HFT或重置标准API方法的唯一机会。插件可以在此时为notifications注册，或以后的任何时候。
初始化：
Acrobat或Adobe Reader完整地调用每个插件的PluginImportReplaceAndRegister回调方法之后，继续调用每个插件的PluginInit程序。插件可以使用他们的初始化程序用来钩住Acrobat的用户接口，增加菜单条目，工具条按钮，窗口，等等。也可以在插件运行时修改Acrobat的用户接口。
A menu command --- 菜单命令，菜单的末级，点击后执行相应命令。
第6章 创建菜单和菜单命令
第2节 给菜单增加菜单命令
你可以使用Acrobat core API给一个已存在的菜单增加一个新的菜单命令。例如，你可以添加一个在Acrobat SDK中已命名的菜单命令给Adobe Reader或Acrobat菜单条中的高级菜单条目。为了给一个已存在的菜单增加一个新菜单命令，请参照下面的方法：
Acrobat或AdobБайду номын сангаас Reader在启动时在启动界面最底部一行显示一个进度消息。当每个插件被载入时，进度消息显示插件的名字。Acrobat或Adobe Reader启动时如果SHIFT键被按住，没有插件被载入。同时，如果Acrobat或Adobe Reader运行在被认证模式时，也没有第三方插件被载入。
2.通过调用AVAppRegisterNotification方法，为notifications注册。插件也可以在运行时注册或取消注册。插件可以在任何时候接收到一个notification，在它已完成注册以后，甚至插件的初始化回调函数还没有被调用时。这是可能发生的，如果另一个插件首先初始化并执行了一个操作，比如创建一个PDF文档，这会引起一个notification被发送。插件必须准备好正确地抓住notifications，只要为它们注册了。
如果你的插件需要在所有的插件被初始化后规划一个任务，它应该为AVAppDidInitialize通知注册。这个通知会被调用，当Acrobat已经完成初始化并且将要进入它的事件循环时。
卸载：
插件的PluginUnload程序应该释放插件分配的所有内存，并移除所有它做的用户接口改动。Acrobat调用这个程序，当它终止运行或其它任何握手回调返回false时。这个功能应该执行下列任务：