Jahwo's AddOn Writing Guide

If you never programmed before this might need some explanation. XML works with so called tags, you probably already met something similar here on WoWPro if you ever formatted some text.

A tag looks like this: <tag>.

Tags generally get opened and closed again. Closing tags have a slash (/) in the front: </tag>.

Tags can be closed in their opening tag, looks like this: <tag parameter="stuff" /> (note the slash at the end)

As you can see, it is possible (and often used) to add parameters in the tag.

Everything between the opening and ending of a tag will either influence it or will be influenced by it.

Don't worry if you have problems understanding this, it's not very hard. Just follow the guide and everything will explain itself.

The <Frame> element, how could it be different, represents the frame we are about to create.

We've already given our frame a specific name, with the name parameter. I called it "WoWProFit_MainFrame" because this name is really clear to everyone who reads it. If you somewhen write your own AddOns it'd be nice for you and other people if you give your stuff reasonable names.

A prefix like WoWProFit is not necessary, but again it increases the understandibility and prevents interferences with other AddOns.

We use the <AbsDimension> tag which takes two parameters. The width of our frame as x and the height as y. The values given are in absolute pixel. Thats why it is called AbsDimension.

Another possibility would have been the <RelDimension> tag which, other than our tag takes the values relative to the screen, from 0 to 1. (Means x="0.5" and y="0.5" would be exactly the half of the whole screen)

The width doesn't really matter in our case, because we will have to set it dynamically later on, but for now we set it to 120 so we will see something. The height of 20 pixel is the final height for the frame!

The <Anchors> tags contain all the anchors of the object. In our case it has only one.

Anchors place one point of an object (here the frame) on a point of another object. There are different "versions" of anchors but we just use the simplest of them.

Our <Anchor> element takes just one point parameter, which contains "CENTER". This means that the center of our frame will be anchored to the center of it's parent, which we defined before (the UIParent).

The size of those tiles is defined in the <TileSize> tag which works pretty much the same as the <Size> we used for the whole frame. The difference is that the tiles are squares and therefore we only need one dimension instead of two.
This means we use a tag called <AbsValue> which takes only one parameter called val. We choose a size of 16 * 16 pixel for our tiles.

Informations about how to find the paths to WoW-images can be found in the Appendix

As you can see it contains all possible sides and edges for a nice bordered rectangle. Because of this we need to define how the file has to be split.

We have to specify the size of the "tiles" we want to make out of this file with the <EdgeSize> tag. It works exactly like the <TileSize> element. We need to split the file into 16 * 16 pixel tiles.

The <AbsInsets> tag is similar to the other Abs tags we already used but it takes four arguments: left, right, top, bottom. Those specify how many pixel the approprate side moves to the center of the frame. The values given in the snippet above are perfect for our case.

Every object in a <Frames> element has the frame it is in as a parent, in our case the WoWProFit_MainFrame (if we don't say otherwise with a parent parameter)

The $parent argument in the name of the button refers to the name of it's parent. As said above the parent is WoWProFit_MainFrame, and so the complete name of our button is "WoWProFit_MainFrame_Button"

Everything else you can see here should be clear. If not search the The Frame chapter for the here used tags.

This time we opened the <Anchor> tag and inserted a new element, the <Offset>. It takes the already known <AbsDimension> tag. The given x and y values move the anchor-point to the right and the top, because the origin of the coordinate system is in the bottomleft corner of the screen.

We move the point 3 pixel to the right and 3 pixel down, so that our 15*15 pixel sized button is approximately vertically centered in our 20 pixel high frame.

The problem with the texture we use is that it in fact is multiple textures in one file:

We only want to use the first blue circle thingy as our texture so we somehow have to cut it out. That's where the <TexCoords> tag comes in.

<TexCoords> with four arguments as we use it cuts out a part of the texture. The argument left defines where the left side of the piece is. The value given to it is a relative value that expresses a distance from the left side of the whole texture.
For example if it's 0.25 it would be one fourth of the width of the whole texture.

The same thing applies to the right parameter, only this one defines where the right side of the piece is.

Similar to this work top and bottom, only that it's relative to the height and from the top.

In our case we want to keep the left side, so left is "0". The right side is "0.125" because we have 8 different textures in the row and 1 / 8 = 0.125
The top stays the same, so "0". The bottom is exactly the half of the height.

If you have problems understanding this, just play around with the values and look at the results ingame, as you should see the button there by now.

The <Layer> tag is similar to the <Frame> element, but it takes an parameter called level. With it you can define on which "height" the elements in it are placed. Elements in higher levels cover elements in lower levels.
The possible levels are, from highest to lowest:

• HIGHLIGHT
• OVERLAY
• ARTWORK
• BORDER
• BACKGROUND

The name given in inherits is the name of a <Font> object, that defines which font is used and which size it has. You can find the by default inheritable fonts here, but I won't explain this file

The text that will be shown is given text parameter. We set it to "0", this will be changed dynamically later on.

JustifyV and JustifyH control how the text is justified. We want it to be horizontally on the "RIGHT" and vertically at the "TOP"

The <Size> and <Anchors> stuff should be clear in this case.

Because the profit at the beginnning of a session is 0 we want the text to appear yellow. We can use the <Color> tag for this again.

Even though the files size is not 10 * 10 it will be adjusted automatically.

The relativeTo parameter takes the object the Anchor will be relative to. We want the texture to be next to the text we made two steps before, so we give the name of the <FontString> object to the relativeTo parameter.

We also want the texture to be on the right side of the text. This can be accomplished easily if we anchor the topleft point of our <Texture> to the topright point of the <FontString>. We do this with the relativePoint parameter.

The small horizontal Offset is only for some distance between the two objects.

Of course the file of the texture has to be changed, too.

enableMouse="true" allows us to retrieve mouse events like clicking, which we need in the next steps.

<OnMouseDown> is such an Event-Handler. Everything between it's tags is actual lua-code and will be executed if the event is fired. For this tag it is fired if the user presses a mouse button down on the frame.

<OnMouseUp> is an event that is fired if a mouse button is released.

The two brackets () after the name is the place where we can add parameters for our function. We don't need any.

The end statement closes the function.

Our frame WoWProFit_MainFrame has member functions that will have an effect on it.
In the second line you can see how they are called. First there is the name of the frame followed by a colon and the name of the function with the brackets for eventual parameters.

The function StartMoving() causes our frame to move with the mouse cursor.

Same thing with MouseUp only that it will result in making the frame stop moving.

The WoWProFit_MadeProfit is a boolean variable. This means it can have the states true or false. We will use it to control if a new entry in the all time history has been made or not.

The curly brackets indicate that WoWProFit_History is a table. Tables are variables that kind of contain a list of other variables. We use it to store the all-time history of profits and deficits. It does not matter if the table contains something, because it will be overwritten with the saved data we create in the next step.

The saved variable can be found in the file World of Warcraft\WTF\Account\ACCOUNTNAME\REALM\CHARACTERNAME\SavedVariables\WoWProFit.lua

The loading of the variable is one of the last things that happen during the initialization process. That's why we can define it as an empty table, because it will be overwritten with the saved data, if there is any.

The function GetMoney() returns the current money of the player in copper. This means that for example 1 gold 12 silver 85 copper would be returned as 11285.

width has a startup value of 65. This is the sum of all fix width in our frame: The button of 20pixel width, the offset of 5pixel, five times the offset of 2 pixel and three times 10pixel wide textures.

Then we add the width of the texts to the total width. You have to know that the right side of an assignment is always calculated first. That's why we can use the same variable left and right.

The function GetStringWidth() of the FontString object returns the width the text has, not the object!

We do this three times, for the gold, silver and copper FontStrings.

Finally we set the width of our WoWProFit_MainFrame with the SetWidth() function. We give it our just calculated total width as a parameter.

We'll write the WoWProFit_OnEvent() function in the next step.

The if clause begins with the if, followed by a condition. The event variable contains the name of the event that has been fired. With the double equality sign we check if it equals "PLAYER_MONEY".

If this condition is true, everything between the then and it's end statement will be executed.

If the conition is true this also means there has been no update before, and therefore we want to create a new entry in the WoWProFit_History variable. We do this with the table.insert() function.

We give it three parameters.
The first one is the table variable we want to insert a new element.
The second one is the position where the element is inserted. We choose the first position.
The last one is the value that is inserted, we set it to 0 because there has not been any profit until now.

Remember that now that we have changed the History variable, it will be saved with the new values if the player logs out!

Now we add the difference to the current state in our history entry. The entry for the current session is the first one, as we added it above. An element of a table can be accessed with the squared brackets with a index number in between. 1 is the first element, which we need.

Finally we set the LastMoney variable to the current money, so we have the right value to compare to the next time.

With the abs() function we calculate the absolute value of the commited parameter and store it in the variable absMoney.

Now we calculate the gold part of the money. We do this by dividing the coppers by 10000 and cutting of the decimals with the floor() function.

The silver is calculated pretty much the same, only that we divide by 100 and have to subtract the gold part in copper! Again we have to floor() it.

The copper part is the absMoney subtracted by the gold and silver parts in copper.

Now we return all three calculated values. This means we can say x, y, z = WoWProFit_ReturnMoney(money) where x would be gold, y silver and z copper.

If you did not understand everything, no problem, it's maths after all Such things become clear if you begin developing your own code.

We set the text of the gold FontString with it's member function SetText() to the gold variable.

It's exactly the same thing for silver and copper.

We changed our text, so it probably is necessary to change the size of the frame. Luckily we wrote a function for that, so we just have to call WoWProFit_ChangeSize().

You can try selling or buying something ingame now and you will see that the profits/deficits are displayed in the AddOn

Same thing with the else statment only that it doesn't take a condition. It will be executed if everything before failed.

Oh and SetTextColor() sets the color of the text of the FontString. The parameters are r,g,b and it works like the <Color> tag

The loop we use is a so called for loop. The way we use it, it goes through every single element of a table.
The statement for initiates the loop. the function pairs() returns the key and the value of the table given in it's paramter element by element.
The key, whch is the index we used before to access the frst element, wll be saved in the k varuable.
The value is what the element contains for this key. It will be saved in v.

Now we can add all the values to our alltime variable.

After the loop is finished we have a variable that contains our all time profit or deficit.

DEFAULT_CHAT_FRAME is an object just like the Buttons or FontStrings we created ourselves. This one is a standard in the game and represents, how could it be different, the default chat frame. It has a member function called AddMessage(), which allows us to add a message to the chat frame.

The function takes a string as a paramter, and in this string we can use so called escape sequences. The one we use is to change the color of a particular part of the text. "|cFFFF0000" makes the folllowing text red. The values following the |c are a color code in hexadecimal notation (more information here).
The first two digits are the alpha value. The following six are for red, green and blue.

The sequence "|r" resets the color to default.

If we have a profit (else) we display a green "profit".