= Eva Framework =

== 简介 ==
Eva Framework是一个高度可扩展的WoW插件快速开发框架.
  开发人员: [[simonw]]... 期望更多开发者的加入, 这是我们自己的Framework
  
  Doc: http://wiki.cwowaddon.com/EVA

  Svn: http://woweva.googlecode.com

  Site: http://sites.google.com/a/cwowaddon.com/eva

  Publish: http://bbs.cwowaddon.com/thread-585-1-1.html

== 优势 ==
 * 轻量, 高效, 框架本身内存占用不超过100k, 以实用为准则, 并没有为实现某些花哨的开发能力而创建操作大量的对象.
 * 封装了WoW插件引擎模型内部的复杂性, 为WoW中所有请求提供了统一接口, 开发者无需再去关心如何处理请求, 只需关注请求来临时做什么. 框架侵入性极低, 开发者可以轻易的将插件转移入或转移出框架.
 * 强大的命令调用引擎, 支持单功能调用, 组功能调用, 能够通过延时模拟多线程.
 * 强大的框架级动态控制能力, 开发者可以随时加载卸载插件, 启用停止插件内部任意功能, 甚至能够动态改变UI请求方式, 统一管理请求层面对象及变量范围, 从而能在一定程度上避免由于开发者知识不足或失误所造成的变量范围混乱, 频繁创建无用对象等缺陷.
 * 使开发变的层次清晰, 框架支持层次式开发, 使您的插件变得层次结构情绪, 易于阅读与维护.
 *  稳定, 开发者无需担心因WoW版本的变更而导致框架频繁变更, 框架的抽象是基于WoW插件引擎的核心机制, 不牵扯具体API, 最好的例子便是[[WoW]]1.x变更到2.x时导致大量插件失效, 而Eva只是针对lua5.0升级至5.1的一个语法改变后即可正常使用.
 * 学习曲线平滑, 降低了WoW插件的开发难度, 接口少而简单, 面向对象的调用方式, 非常容易上手即使您没有插件开发经验.

== 技术详情 ==
 * 库与框架的不同
  * 库, 为应用提供了常见的功能调用, 你的插件需要主动调用库.
  * 框架, 包含一个库, 插件需要按照框架规范编程, 由框架主动调用插件来执行. 是应用开发的更高级形式.

=== 插件执行流程图 ===
{{attachment:eva.jpg}}

== 应用概览 ==
{{{#!lua
--[[
blockN = {
	Name = "block name",
	Description = "Description of cmd",
	Enabled = true,
	Type = "Public"|"Private"|"System",
	RequestTypes = {"Event", "SlashCommand", "FrameEvent", "KeyBinding", "UserEvent", ...},
	Events = {"eventNameN", ...},
	FrameEvents = {"frameNameN:eventNameN", ...},
	UserEvents = {"userEventNameN", ...},
	SlashCommands = {"slashCommandN", ...},
	KeyBindings = {"keyN", ...},
	CustomKeyBinding = customFunction,
	Commands = {
		GTimer = {Interval = N, Times =N},
		Timer = {Interval = N, Times =N},
		ThreadMode = "Single"|"Multi",
		{Description = "cmd notes", Function = customFunctionN, Timer = {Interval = N, Times =N}},
		...
	}
}
addon = Eva.Addon:New()
addon:add(EVA.Block:New(block1))
addon:add(EVA.Block:New(block2))
...

Eva.AddonRegistry:Add(addon)
]]
}}}

== 接口API文档 ==
=== AddonRegistry ===
插件注册表, 包含多个Addon, 管理所有注册于其中的基于Eva的插件. 负责插件的装载与卸载.
{{{#!lua
--添加一个addon
AddonRegistry:Add(addon)

--注册/装载一个addon
AddonRegistry:Register(addon)

--卸载一个addon
AddonRegistry:Unregister(addon)

--通过addon的字符串名称取得addon
AddonRegistry:GetChild(addonname)

--获取总共的addon数目
AddonRegistry:Count()
}}}

=== Addon ===
插件, 包含多个Block, 负责管理插件基本属性如名称,版本,描述等, 同时负责关键值改变的刷新.
{{{#!lua
--字符串, addon的名字, 需全局唯一
Addon.Name

--字符串, addon版本
Addon.Version

--字符串, 采用的哪个Eva版本开发的
Addon.EvaVersion

--布尔值, 是否允许动态加载
Addon.CanEnabled

--布尔值, 是否允许动态卸载
Addon.CanDisabled

--函数, 加载前执行
Addon.OnRegister

--函数, 卸载后执行
Addon.OnUnregister

--检测addon开发使用的EVA版本与用户的EVA的不同
--返回值, 整数, 1:= 2:> 3:< 4:Invalid
Addon:CheckEvaVersion()

--通过Block字符串名称获得Block
Addon:GetChild(blockname)

--查询addon内Block的数目
Addon:Count()
}}}

=== Block ===
功能集, 一个插件可以包含多个Block, Block是最基本的单位, 用于处理某一个对外功能.

{{{#!lua
--字符串, 功能集的名字.
Block.Name

--字符串, 功能集的功能描述.
Block.Description

--布尔值, 开关.
Block.Enabled

--字符串枚举, 可见性类型标识.
--取值, Public(公共的), Private(私有的), System(系统的)
Block.Type

--字符串数组, 请求类型.
--取值, Event(事件), SlashCommand, FrameEvent(UI窗体的事件), KeyBinding(按键绑定), UserEvent(用户自定义事件)
Block.RequestType

--字符串数组, 监听事件的集合.
Block.Events

--字符串数组, 监听UI窗体控件事件的集合.
Block.FrameEvents

--字符串数组, 监听SlashCommand的集合.
Block.SlashCommands

--字符串数组, 监听按键绑定的按键集合.
Block.KeyBindings

--字符串数组, 监听用户自定义事件的集合.
Block.UserEvents

--函数, 处理自定义按键绑定设置, 设置此项则KeyBindings失效.
Block.CustomKeyBinding

--对象, 动作组, 命令集合控制. 包含若干子属性.
Block.Commands, 对象, 动作组, 命令集合控制.

--Timer对象, 控制组的Timer.
Block.Commands.GTimer

--Timer对象, 为组中每个动作设置的默认Timer.
Block.Commands.Timer

--枚举字符串, 线程模式. 取值, Single(单线程), Multi(多线程)
Block.Commands.ThreadMode

--Command数组中包含多个Command, Command对象, 组成动作组的具体动作.
Block.Commands[i]

--字符串, 动作的描述.
Block.Commands[i].Description

--函数或字符串, 动作执行的函数.
Block.Commands[i].Function

--Timer对象, 描述本动作的延时与执行次数.
Block.Commands[i].Timer

--当对Block的请求部分做了动态更改后需调用才能生效.
Block:Refresh()

--直接调度运行Block
Block:Run()
}}}

=== Timer ===
控制程序的延时.
{{{#!lua
--非负有理数, 间隔时间, 秒
Timer.Interval

--整数, 循环次数, 当为负值无限循环
Timer.Times

--开始
Timer:Start()

--立即激活
Timer:ActiveNow()

--恢复
Timer:Resume()

--暂停
Timer:Pause()

--结束
Timer:End()

--终结, 不再调用下一个Timer
Timer:Terminate()

--重置
Timer:Reset()
}}}

=== Context ===
系统上下文.
{{{#!lua
--公共参数:

--Block对象, 当前请求的block
Context.Block

--字符串, 请求类型
Context.RequestType

--------------------------------------------------
--------------------------------------------------
--当为以下特定请求类型时系统上下文有其特定参数.


--SlashCommand参数:

--字符串, SlashCommand第一个空格后的所有字符串
Context.Slash_Arg

--字符串数组, 解析后的Slash_Arg按照空格切分开
Context.Slash_Args


--Event参数:

--字符串, 请求的事件名称
Context.Event_Name

--字符串数组, 事件传入的所有参数, 从1-9
Context.Event_Args


--FrameEvent参数:继承Event所有参数

--字符串, 请求的UI窗体控件名称
Context.Frame_Name


--KeyBinding参数:

--窗体对象, 引发按键的窗体
Context.Key_Frame

--字符串, 引发按键窗体的Unit指向
Context.Key_Unit

--字符串, 引发按键的按键名称
Context.Key_Button
}}}

=== 2个自定义扩展的例子 ===
{{{#!lua
--字符串数组, 请求类型.
--取值, 继承标准参数, EventChatCommand(Event扩展, 聊天事件命令), EventChatWords(Event扩展, 聊天事件模糊匹配),
Block.RequestType

--对象, 功能集的权限控制. 默认为空, 即无权限设置.
Block.Permission

--字符串数组, 允许列表.
Block.Permission.AllowList

--字符串数组, 拒绝列表, 拒绝优先.
Block.Permission.DenyList

--字符串, 当请求为EventChatCommand时有效, 匹配命令. 同样适用于Command[i].
Commands.ChatCommand

--对象, 当请求为EventChatWords时有效, 模糊匹配. 同样适用于Command[i].
Commands.ChatWords

--字符串数组, 允许词汇列表.
Commands.ChatWords.AllowList

--字符串数组, 拒绝词汇列表, 拒绝优先.
Commands.ChatWords.DenyList


--EventChatWords参数:继承Event所有参数

--字符串, 传入的聊天字符串
Context.Event_ChatMessage

--字符串, 聊天信息发送者
Context.Event_Sender


--EventChatCommand 参数:继承Event, EventChatWords所有参数

--字符串, 从Event_ChatMessage中解析出的命令
Context.Event_ChatCommand

--字符串数组, 从Event_ChatMessage中解析出的参数数组
Context.Event_ChatArgs
}}}

----
[[插件类]]