Table Of ContentWorld of Warcraft
Programming
A Guide and Reference for Creating
WoW Addons
Second Edition
James Whitehead II
Rick Roe
Wiley Publishing, Inc.
®
WorldofWarcraft Programming:AGuideandReferenceforCreatingWoWAddons,SecondEdition
Publishedby
WileyPublishing,Inc.
10475CrosspointBoulevard
Indianapolis,IN46256
www.wiley.com
Copyright©2010byWileyPublishing,Inc.,Indianapolis,Indiana
PublishedsimultaneouslyinCanada
ISBN:978-0-470-48128-8
ManufacturedintheUnitedStatesofAmerica
Contents at a Glance
Introduction xxxvii
PartI Learning toProgram 1
Chapter1 ProgrammingforWorldofWarcraft 3
Chapter2 ExploringLuaBasics 13
Chapter3 BasicFunctionsandControlStructures 39
Chapter4 WorkingwithTables 53
Chapter5 AdvancedFunctionsandControlStructures 77
Chapter6 LuaStandard Libraries 91
Chapter7 LearningXML 111
PartII ProgramminginWorldofWarcraft 123
Chapter8 AnatomyofanAddon 125
Chapter9 WorkingwithFrames,Widgets,andOtherGraphical
Elements 143
Chapter10 SavingTimewithFrameTemplates 171
Chapter11 ExploringtheWorldofWarcraftAPI 187
Chapter12 InteractingwithWidgets 207
Chapter13 RespondingtoGameEvents 243
Chapter14 Tracking DamagewithCombatTracker 267
PartIII AdvancedAddonTechniques 283
Chapter15 Taking ActionwithSecureTemplates 285
Chapter16 Binding KeysandClickstoAddonCode 309
Chapter17 Creating SlashCommands 337
Chapter18 Responding toGraphicUpdateswithOnUpdate 351
Chapter19 Altering ExistingBehavior withFunctionHooking 359
Chapter20 Creating CustomGraphics 373
Chapter21 Responding totheCombatLogandThreatInformation 387
Chapter22 Creating ScrollFrames 413
Chapter23 Creating DropdownMenus 431
Chapter24 Scanning andConstructingTooltips 451
Chapter25 Taking ProtectedActioninCombat 463
Chapter26 Creating UnitFrameswithGroupTemplates 501
PartIV Reference 537
Chapter27 APIReference 539
Chapter28 APICategories 1025
Chapter29 WidgetReference 1121
Chapter30 EventsReference 1277
PartV Appendixes 1303
Appendix A BestPractices 1305
Appendix B Utilizing AddonLibraries 1329
Appendix C Tracking HistoryUsing VersionControlSystems 1339
Appendix D AddonAuthorResources 1349
Index 1357
Contents
Introduction xxxvii
PartI Learning toProgram 1
Chapter1 ProgrammingforWorldofWarcraft 3
CustomizingtheUserInterface 3
WhatIsanAddon? 4
WhatCanAddonsDo? 4
ExploringYourAddOnsDirectory 7
BlizzardAddons 8
CustomAddons 10
CreatingYourFirstAddon:HeyThere 10
CreatingFilesandDirectories 10
LoadingandTestingtheAddon 11
Summary 12
Chapter2 ExploringLuaBasics 13
DownloadingandInstallingLua 14
DownloadingandInstallingWowLua 14
UsingLuaontheWeb 15
DownloadingandInstallingaLuaInterpreter 16
MicrosoftWindows 16
MacOSX 16
UsingtheLuaInterpreter 17
RunningCommands 18
UnderstandingErrorMessages 18
UsingHistorytoMakeChanges 19
QuittingtheInterpreter 19
MicrosoftWindows 19
MacOSX 19
WorkingwithNumbers 20
BasicArithmeticOperations 20
ScientificNotation 21
HexadecimalNotation 21
UnderstandingFloatingPoint 22
UnderstandingValuesandVariables 23
ExploringValuesandTheirTypes 23
PrimitiveTypes 23
Usingthetype()Function 23
UsingVariables 24
ValidVariableNames 25
AssigningVariables 25
AssigningMultipleVariables 26
ComparingValues 26
WorkingwithStrings 27
ComparingStrings 27
ConcatenatingMultipleStrings 28
ConvertingNumberstoStrings 28
ConvertingStringstoNumbers 29
QuotingStrings 29
SingleQuote(’) 29
DoubleQuote(’’) 30
BracketQuote([[]]) 30
EscapingSpecialCharacters 31
GettingaString’sLength 32
BooleanValuesandOperators 33
UsingtheandOperator 33
UsingtheorOperator 34
NegationUsingthenotOperator 34
UnderstandingthenilValue 35
ExploringScope 35
Blocks 36
Chunks 37
Summary 37
Chapter3 BasicFunctionsandControlStructures 39
UsingFunctions 39
CreatingaFunction 39
LocalFunctions 40
FunctionArgumentsandReturns 41
ConvertingCelsiustoFahrenheit 41
EmptyArguments 42
NoReturnValues 42
FunctionsasLuaValues 42
MakingDecisionswiththeifStatement 43
SimpleConditionals 43
ComplexExpressions 44
ExtendedConditionals 44
DisplayingaPersonalizedGreeting 45
RepeatingActionswiththewhileStatement 46
ComputingFactorials 46
DifferencesBetweenwhileandrepeat 47
LoopingwiththeNumericforStatement 48
ComputingFactorials 50
EvaluationofLoopConditions 50
VariableScopeinforLoops 50
Summary 51
Chapter4 WorkingwithTables 53
StoringDataUsingTables 53
CreatingandIndexingTables 54
ClearinganElementfromaTable 54
ShortcutsforStringKeys 55
CreatingPopulatedTables 55
UsingTablesasArrays 56
CreatinganArray 57
GettingtheLengthofanArray 57
AddingElementstoanArray 58
RemovingElementsfromanArray 60
SortingtheElementsofanArray 61
UsingTablesasNamespaces 61
CreatingaNamespaceofUtilityFunctions 62
AddingFunctionstoaNamespace 62
StoringanExistingFunction 62
DefiningaNewFunction 63
Object-OrientedProgrammingwithTables 63
CreatingaNon-Object-OrientedCounter 63
UsingTablesasSimpleObjects 64
Using:toCallObjectMethods 65
DefiningFunctionsUsing: 66
MakingaBetterCounter 67
ExtendingTableswithMetatables 68
AddingaMetatable 68
DefiningMetamethods 69
DefiningBasicArithmeticUsing___add,___sub,___mul,
and___div 70
DefiningNegationUsing___unm 71
CreatingMeaningfulOutputwith___tostring 71
ConcatenatingTablesUsing___concat 72
ExploringFallbackTableswith___index 72
CatchingCreationofKeyswith___newindex 74
BypassingMetatables 75
value=rawget(tbl,key) 75
rawset(tbl,key,value) 76
Summary 76
Chapter5 AdvancedFunctionsandControlStructures 77
MultipleReturnValues 77
ConvertingHextoRGB 77
AssigningMultipleValues 78
MissingReturnValues? 79
MultipleReturnValuesinWorldofWarcraft 79
UsingaDummyVariable 80
Usingtheselect()Function 81
AcceptingaVariableNumberofArguments 81
DeclaringaVarargFunction 82
Usingselect()with... 83
GenericforLoopsandIterators 84
SyntaxofGenericfor 84
TraversingtheArrayPartofaTable 85
TraversinganEntireTable 86
ClearingaTable 86
UsingOtherIterators 87
SortinganArrayofTableData 87
DefineExampleData 88
DefaultSortOrder 88
CreatingaComparisonFunction 88
CreatingaMoreComplexSortFunction 89
Summary 90
Chapter6 LuaStandardLibraries 91
TableLibrary 92
str=table.concat(table[,sep[,i[,j]]]) 92
table.insert(table,[pos,]value) 92
max=table.maxn(table) 93
value=table.remove(table[,pos]) 93
table.sort(table[,comp]) 93
StringUtilityFunctions 94
FormattingNewStrings 95
PatternMatching 98
CharacterClasses 98
PatternItems 100
PatternCaptures 101
PatternAnchors 102
PatternExamples 102
PatternMatchingFunctions 102
string.gmatch(s,pattern) 103
string.gsub(s,pattern,repl[,n]) 103
string.match(s,pattern[,init]) 104
string.find(s,pattern[,init[,plain]]) 104
MathLibrary 105
WorldofWarcraftAdditionstoLua 108
FunctionAliases 109
Summary 110
Chapter7 LearningXML 111
XMLasaMarkupLanguage 111
XML’sRelationshiptoHTML 112
ComponentsofXML 112
XMLTags 113
XMLElements 113
XMLAttributes 113
XMLEntities 114
CreatingWell-FormedXML 114
ValidatinganXMLDocument 115
ExampleSchemaDefinition 115
ExampleXMLDocument 116
ExploringtheSchema 116
XMLinWorldofWarcraft 117
UsingaGradientType 118
ExploringBlizzard’sXMLUserInterfaceCustomizationTool 119
Summary 121
PartII ProgramminginWorldofWarcraft 123
Chapter8 AnatomyofanAddon 125
ExploringanAddon’sFilesandFolders 125
TableofContents(.toc)File 125
##Interface: 126
##Title: 127
##Notes: 128
##Dependencies:,##RequiredDeps: 128
##OptionalDeps: 129
##LoadOnDemand: 129
##LoadsWith: 129
##DefaultState: 130
##LoadManager: 130
##SavedVariables: 130
##SavedVariablesPerCharacter: 131
X-LabelDirectives 131
AddonCategories 131
XMLFiles 132
LuaScriptFiles 133
MediaFiles 133
Music 133
Graphics 133
LocalizingYourAddons 134
ValidLocales 135
ReasonsforProvidingLocalization 135
EncouragingUserstoContribute 136
ImplementingLocalization 136
AddaFileforEachLocale 136
CreateaGlobalTableContainingtheBaseStrings 136
UsingtheLocalizationTable 137
AddingNewLocales 137
HandlingPartialTranslations 138
IntroducingFrames,WidgetScripts,andEvents 138
Frames,FontStrings,andTextures 138
DisplayingTextwithFontStrings 139
ShowingGraphicsandColorswithTextures 139
AnchoringObjectsOn-Screen 139
RespondingtoInteractionwithWidgetScripts 139
RespondingtoGameEvents 139
LoadingofanAddon 141
Summary 142
Chapter9 Working withFrames,Widgets,andOtherGraphical
Elements 143
IntroducingBagBuddy 143
CreatinganAddonSkeleton 144
CreatingaFrame 144
Parenting 145
