WebSVN – vanilla-wow-addons – Blame – Rev 1

1

office

1

_____________________________________________________________________________________

Ace

Author: Kaelten (kaelten@gmail.com)

6

Version: 1.3.1

7

Release: 5/12/2006

8

Website: http://www.wowace.com

9

_____________________________________________________________________________________

Ace is a lightweight and powerful addon development system. It is a new approach to

14

addon development, a rethinking from the ground up. Ace provides developers with the

15

tools needed by most addons, freeing them from repeating common tasks and allowing

16

them to jump right into the creative part of building their addons.

17

18

19

_____________________________________________________________________________________

20

21

FEATURES

22

_____________________________________________________________________________________

23

24

So what does Ace have to offer? Here is a brief list of its features:

25

26

- Initializes the addon after variables and character data load.

27

- Simple, flexible, and powerful data management.

28

- Customizable chat command handling.

29

- Improved function and method hooking.

30

- Enhanced event handling with the ability to create custom events.

31

- In-game addon disabling and enabling.

32

- Easy saving of settings per character and per class.

33

- Debug features with optional module.

34

- Built-in myAddons support.

35

36

New features for 1.2! (Requires World of Warcraft client version 1.7+)

37

38

- On-demand loading of addons. (Addons must support this specifically.)

39

- New enable and disable features. (Require UI reload or game restart.)

40

- Script hooking capabilities.

41

42

_____________________________________________________________________________________

43

44

USAGE

45

_____________________________________________________________________________________

46

47

Ace provides some basic commands to the player for managing Ace-derived addons. To

48

use Ace for addon development, see the note below.

--------------

ACE COMMANDS

--------------

/ace

Entered without options, this command will display a list of available options and

57

other available information.

58

59

/ace enable | disable <addon>

60

61

This is a "hard" enable or disable. It does the same thing as when you check or un-

62

check the addon's flag in the AddOns menu of your character screen. When you change

63

this status in game, you must restart the game or reload the UI for the change to

take effect.

/ace info

Display summary information about the addons installed and the loaded profile.

69

70

/ace list [<addon> | loadable | nonace]

71

72

Display a list of currently installed or loadable addons. If /ace list is typed

73

without additional parameters, it will display a list of all currently loaded Ace

addons.

Options:

- <addon> : Type the name of a specific addon to search for. If found, Ace

79

will display whatever information it can. For non-ace addons, or

80

addons that aren't currently loaded, this information will be

81

limited.

82

- ace : List only currently loaded Ace addons.

83

- other : List all other currently loaded addons.

84

- loadable : List all addons that are available to be loaded. This cannot

85

distinguish between Ace and other addons.

86

87

/ace load [auto | off] <addon>

88

89

Load the specified addon if it is not currently loaded. This command will load any

90

addon that is set for loading on demand, not just Ace addons.

Options:

- auto : Automatically load the addon on startup. This state is saved in the

95

current Ace profile, so you can auto-load addons per character or per

96

class.

97

- off : Turn off the automatic loading of an addon in the current Ace profile.

98

Note that the addon cannot be unloaded. It will still remain loaded

99

but will not load automatically the next time you restart the game.

100

101

/ace loadmsg (addon | none | sum)

102

103

Change the load message at game load. 'addon' will display a load message for every

104

addon. 'none' will display no load messages at all. 'sum' will display a summary of

105

the number of addons installed and the loaded profile. A summary is the default.

106

107

/ace profile (char | class | default) [<addon> | all]

108

109

Change the basic profile your character uses. A profile stores a specific set of

110

configurations for your addons. By default, the 'char' and 'class' profiles will

111

be created empty. You must add each addon to the profile individually. So, for

112

example, the first time you run "/ace profile char", that character's profile will

113

be empty, meaning you'll still be using all addons' default settings. If you then,

114

for example, type "/ace profile char coins", any setting changes you make to Coins

115

after that will be reflected in the character's profile and not the default profile.

Options:

- char : Use a profile specific to the current character.

120

- class : Use a profile specific to the character's class. This profile can

121

be shared by all characters of that class.

122

- default : Use a default profile that will be shared by all characters if no

123

specific profile is selected.

124

125

Additional arguments usable with 'char' and 'class':

126

127

- <addon> : An optional argument that lets you add an addon to the 'char'

128

or 'class' profile. Once added to the profile, any changes you

129

make to the addon will be specific to that character or the

130

character's class.

131

- all : Add every addon to the profile so that each will be customized

132

in that profile.

133

134

-----------------------

135

COMMON ADDON COMMANDS

136

-----------------------

137

138

There are common commands available to most, if not all, Ace addons. Addon authors

139

have some measure of control over these, however, so they may not be available in

140

all Ace addons.

141

142

/<cmd> ? or /<cmd> ? <option>

143

144

This is a help command that will display some extra detail on the addon itself or

145

on the command option you supply.

146

147

/<cmd> enable | disable

148

149

This allows the addon to be enabled or disabled in-game. The enabled/disabled state

150

will also be saved between game sessions. Disabling/enabling will save specific to

151

the profile you have loaded, so addons may be enabled or disabled for specific

152

characters or classes.

/<cmd> report

Not all addons will have this option available. If it is available, this will

157

display all of that addon's settings within the currently loaded profile.

158

159

_____________________________________________________________________________________

160

161

DEVELOPMENT

162

_____________________________________________________________________________________

163

164

To use Ace for addon development, download the developer tool kit, which contains

165

documentation, examples, templates, and AceUtil, a unique, non-distributed library

166

of shareable functions.

167

168

_____________________________________________________________________________________

169

170

CREDITS

171

_____________________________________________________________________________________

172

173

- Rowne for his Fetch and FetchDB, which AceState and AceDB, respectively, were

174

derived from. While I claim some credit for adding my own ideas to AceDB's data-

175

handling approach, it is primarily Rowne's concept. Rowne is a brilliant

176

efficiency expert. His work is what inspired me to create Ace.

177

- Trimble, who got me started on Lua and addon development. His debug usage is what

178

inspired my eventual implementation of debug handling in Ace.

179

- Danboo for his wonderfully efficient and elegent event handling technique. Even

180

though his technique may not be readily recognizable in Ace's variation on it,

181

the basic concept is still derived from his and would not exist if he hadn't

182

first introduced his.

183

- Lazything for his suggestion in Rowne's Fetch forum on Curse to have an addon

184

register itself for state initialization instead of needing its own frame. This

185

little trick greatly reduces redundant code in addons' XML files.

186

- Derkyle, for code in his ItemsMatrix which inspired me to expand AceHook with the

187

capability to hook object methods in addition to just functions.

188

- Neriak for the German translation.

189

190

_____________________________________________________________________________________

191

192

SPECIAL THANKS

193

_____________________________________________________________________________________

194

195

The following people deserve very special thanks.

196

197

- Rowne, not just for the many excellent ideas of his I incorporated into Ace, but

198

also for his support and feedback while helping me to test Ace and all my Ace

199

addons. I can happily and gratefully say that Rowne is the first developer other

200

than myself to adopt Ace. His conversion of all his addons to Ace was a great test

201

run that helped stabalize and polish Ace for release.

202

203

- Kalia for her kind and patient support and testing of all my Ace addons. She

204

helped polish these addons, stamp out bugs, and plug up some memory leaks.

205

206

- Kaelten for his contributions and help in testing Ace by adopting it for his

207

addons. Also for several good suggestions for tweaks and additions to Ace,

208

including the profile system.

209

210

_____________________________________________________________________________________

211

212

VERSION HISTORY

213

_____________________________________________________________________________________

[5/12/2006] v1.3.1

(changed)

- Updated Toc Number for 1.10

218

219

[2006-1-4] v1.3 RC3

220

(changed)

221

- Changed a few errors to debug statements.

222

- A few optimizations.

223

- Fixed a Hook Bug.

224

225

[2006-1-1] v1.3 RC2

226

(changed)

227

- Found a couple of errors in my AceHook implementation

228

- Scripts now use the new hook system.

229

- Removed file AceScript.lua

230

231

[2005-12-30] v1.3 RC1

232

(changed)

233

- The Hooking system has been completely redone. Fixing the memory leak.

234

- Hooking scripts has been unified with the hooking system.

235

- Ace.CopyTable() will not setn on the new table if the original was numerically indexed.

236

- MyAddons support has been completely updated. myAddons v2.4 is now supported.

237

238

[2005-10-11] v1.2.5

239

(changed)

240

- Updated for game patch 1.8

241

- Modified Ace's addon loading to handle Blizzard's new addons.

242

243

[2005-09-17] v1.2.4

244

(changed)

245

- Updated the German localization thanks to Neriak's translations.

246

(fixed)

247

- A bug that broke the use of AceDebug

248

249

[2005-09-15] v1.2.3

250

(fixed)

251

- A bug in the chat command registering that prevented an addon's additional

252

commands from registering if the first one was already in use.

253

254

[2005-09-14] v1.2.2

255

(fixed)

256

- Supplied temporary function mappings for CmdEnable and CmdDisable, which were

257

removed in 1.2, to support existing addons' use of these.

258

259

[2005-09-14] v1.2.1

260

(fixed)

261

- A typo in the myAddOns support

262

- Removed a leftover debugging statement.

[2005-09-13] v1.2

-----------------

Feature Changes

-----------------

(chat commands)

- load : Load any addon (not just Ace addons) that can be loaded dynamically. Type

270

/ace list loadable for a list of addons you can load. Note that addons must be

271

modified to be loadable in this way, so you may not immediately be able to use

272

this feature.

273

- enable/disable : These affect the flag that appears in the AddOn menu on the

274

character login screen. They only toggle this flag. You will have to restart the

275

game or reload the UI to load or unload the addon.

276

- list : This option has been modified.

277

/ace list : Displays a list of all addons. For Ace addons, it will display their

278

primary chat command.

279

/ace list ace : List only Ace addons.

280

/ace list other : List non-Ace addons.

281

/ace list loadable : List addons that can be loaded dynamically, if any.

282

(new)

283

- German translation, much thanks to Neriak!

284

(changed)

285

- The standard enable/disable options available to most Ace addons' chat commands

286

have been replaced with 'standby'. This is to avoid confusion with the new API

287

enable/disable features provided in game patch 1.7. 'standby' functions the same

288

as enable/disable did but instead acts as a toggle between these two states.

-------------

API Changes

-------------

(added)

- Script handling support. This refers to the ability to add OnShow, OnClick, and

294

other handlers to frame elements. This system works just like the hooking system

295

for functions and methods. Addons now have the following methods available to

296

them: HookScript, UnhookScript, UnhookAllScripts, and CallScript.

297

- An enabled event will now fire at game load for each enabled addon.

298

- New chat command methods:

299

error() : Prefixes messages with a standard error text.

300

msg() : Passes all arguments to format() then sends the results to the

301

cmd:result() method.

302

status() : Displays a message in similar format to what cmd:report() uses. This

303

is to allow report labels to be reused for chat command feedback.

304

(changed)

305

- Base classes have been renamed. The "Class" part of each name has been dropped.

306

For example, AceChatCmdClass is now AceChatCmd. The old names are mapped to the

307

new, so existing addons will continue working. Use of these names is considered

308

deprecated, so they may be removed in the future. This change was just to keep

309

naming consistent in light of certain changes to addon declaration standards.

310

- The game state is initialized differently now to take advantage of ADDON_LOADED

311

and to work more efficiently.

312

- AceDB:insert() will now create a table if the key being referenced does not exist.

313

- Localization functions will now be destroyed after they are used in order to clear

314

even more memory.

315

- Simplified the way events are processed. Also separated the processing of custom

316

events from real events in order to avoid variable clashing.

317

- Addons no longer require a description field. If left blank, Ace will supply the

318

text from the notes section of the toc file. Keep in mind that addons which create

319

"sub-addons" or applications (apps for short), such as OneBag, which provides both

320

OneBag and OneBankBag will need to supply a separate description for the extra

321

apps. Otherwise, each will share the same description.

322

- The defined chat commands now set an order of precedence. For example, if you

323

define a list of chat commands such as COMMANDS = {"/mc", "/mycmd", "/mycommand"}

324

then the Ace command object will attempt to use /mc as the primary command. If

325

/mc is already registered by another addon, then /mycmd will be attempted. Each

326

command will still be registered if possible, but now the first one that is able

327

to be registered will be the one shown in Ace's addon lists and usage displays.

328

- The AceChatCmd:report() method now accept 'indent' as one of the configuration

329

options in addition to 'text', 'val', and 'map'. 'indent' is an integer specifying

330

the number of level to indent a report line.

vanilla-wow-addons – Blame information for rev 1