|This is an archive of [[Talk:World of Warcraft API]].|
There is also some archived talk from Dec 2004 here. I didn't see the point in making a separate page for it. --Mikk 10:05, 24 May 2006 (EDT)
Cosmos API or official API?Edit
2 points I'd like to discuss
It should be noted that this is the COSMOS-WoW API. Not a Wow API. The majority of commands etc will not work unless COSMOS is installed.
also, when searching from the main page for "API" I get no results. I have to search for "macros" then click the link to this page in order to reach it.
(I'm a Wikinewb so please bare with me. But I love the concept and looking forward to participating)
- I think you are mistaken. The page only lists global functions that are in fact defined by Blizzard. There isn't a single function that requires Cosmos. You might be confused by the fact that most of these functions are defined internally in WoW, and not in the Lua files, hence you don't see a definition for them if you have a look at the files in the Interface folder. It is of course possible that there are errors on the page, and a given function might not work as a result. -- Lego 12:24, 1 Dec 2004 (EST)
- I think you're right *blush* these are all /script [function] or /console [function] commands then? That should perhaps be noted in the initial paragraph to clarify their overall usage. --BillyZ 15:39, 1 Dec 2004 (EST)
- Let me try and explain. Lua is the language you use to issue commands and control a lot of the client. There are two places where Lua can be used:
- the /script [string] command in-game, where "string" can be anything that is a valid expression in the Lua language
- the interface files (.xml and .lua)
- The list of functions that you see on this page are globally accessible functions, that can be called anywhere where Lua can be used. That's why we don't say they are /script commands or interface commands, they are both. They are Lua global functions, usable anywhere where Lua is. You are of course right in that the page implies they are for interface customization, where in fact they can be used in macros as well as part of the /script command. -- Lego 20:15, 1 Dec 2004 (EST)
- Let me try and explain. Lua is the language you use to issue commands and control a lot of the client. There are two places where Lua can be used:
How to find function definitions? Edit
Just wondering where these defintions are coming from (or where the original API document came from)? I've played around with an MPQ reader a bit, but can't find any readable stuff. Are there some binary files that need to be decoded, or are we just using limited information Blizzard released some time ago, or what's the situation here? There seem to be loads of useful functions, but I've no idea how to use them without at least a function prototype. TIA. -- Goldark 10:56, 10 Dec 2004 (EST)
Character Function "AcceptXPLoss" Edit
Now that you don't lose XP, but Dur, is this function's name changed? --Gandork 11:21, 11 Dec 2004 (EST)
How function definitions are found. Edit
I'm afraid there is NO official Blizzard documentation whatsoever on these functions, there never was, and there won't be one, for the forseeable future. What you see on these pages is the result of the collective effort of modders, who have figured it out from the following two sources:
- uses of these functions you can see in the Blizzard Lua files
- trial and error
Eventually, over time, this page should be filled in with more info, and ideally we will have a complete documentation on all the functions. But it takes time, as we have no source for it. As for how we get the list of available functions in the first place, have a look at the Global Function List page. It's a combination of opening WoW.exe in Notepad, and having a clever in-game script test what functions exist and what don't. -- Lego 13:36, 11 Dec 2004 (EST)
Since I just posted a page on the tool I've been using to document API functions, I figured I'd say a word here about how I've been approaching this. Firstly by scanning over the extracted UI code, and using the unix 'strings' tool to grab the usage strings from the WoW.exe file, I get a list of the available functions, then after looking at how a function is used in the UI, I also use the /dump command I wrote in the DevTools AddOn to see what values the Function provides, and then do some experimentation to determine how the function behaves and what it's limitations are. -- Flickering 13:30, 27 Dec 2004 (EST)
Proposed format change to API list Edit
So in looking at the API list I've been wondering if we might want to make a slight format change to include the basics argument list fot each function in the list, personally I'd find it easier to read that way, but i'm wondering what other people feel. What i'm suggesting is the following:
- Frame:RegisterEvent("event") - Register this Frame's interest in a game event. when a game event occurs.
- Frame:RegisterForDrag() - Register a Frame for dragging events
- Frame:SetAllPoints("frame") - ??
- Frame:SetFrameLevel(level) - ??
- Frame:SetID(ID) - Set the ID of a Frame
- Frame:SetMaxResize(maxWidth, maxHeight) - Set the maxmimum size of a resizable Frame
- Frame:SetMinResize(minWidth, minHeight) - Set the minimum size of a resizable Frame
- Frame:SetScale(scale) - Set the size scaling of a Frame relative to its parent.
- Frame:UnregisterEvent("event") - Unregister this Frame's interest in a game event.
I feel this would make the API list more of an at-a-glance reference, in addition to just being an index, but I'd like to know what other people feel before making a sweeping change like this.
-- Flickering 12:39, 23 Dec 2004 (EST)
In the absence of any comments about this, I went through and updated the Mapping functions while I filled in the blanks, hopefully the result is something everyone likes!
-- Flickering 17:28, 26 Dec 2004 (EST)
I absolutely like this idea! Simple yet elegant, kind of d'oh, why didn't I think of this. I'm all for it.
-- Lego 19:27, 26 Dec 2004 (EST)
I like your formatting idea. Great idea. Please go ahead and do it.
-- AlexanderYoshi 00:21, 27 Dec 2004 (EST)
It's struck me as I start to do this and while I'm attempting to maintain consistency across API definitions, that method calls need to have more specific names, otherwise we run into issues where multiple objects have the same named method that does different things. I've moved FrameLayout:GetHeight to demonstrate a format I think would work, but as always I'd be interested in feedback. The suggested format is "API ObjectType FunctionName", giving us API FrameLayout GetHeight, which of course is written as FrameLayout:GetHeight() for reference.
-- Flickering 21:23, 6 Jan 2005 (EST)
Split this page into sections? Edit
Since this page is rather huge, maybe it'd be worth splitting it up into sub-pages..
- Data types
- Core functions (Those which are called globally, not on an object)
- Frame Functions (Those which are called on objects)
Should I do this or not? -- Flickering 15:43, 27 Dec 2004 (EST)
We discussed this one a few times. We don't want to split it up because we want to have a master page with a complete list of the functions for developers to look at.
-- AlexanderYoshi 13:49, 28 Dec 2004 (EST)
That makes sense, though it may be a bit overwhelming. On a related note I've been trying to add Category links to the API documents, I started out with just a single "API Functions" category, but I'm now thinking that perhaps subcategories arranged similarly to those on this page would be a better idea, that way we get the subdivided list for free, should someone want it (albeit with fewer frills, but some scripts may be able to fill in those gaps).
-- Flickering 14:10, 28 Dec 2004 (EST)
Updated for 4150 Edit
Widget methods now current as of 4150. Also finally got around to verifying existence of all methods in-game. Reorganized a bit.
How to add new entries? Edit
I've been experimenting with quite a few of the undocumented API calls, and I'd very much like to do some write-ups about them so that others can benefit, but I'm unsure of how to add whole new pages to the document. =) I saw the template page, but I'm afraid that if I edit it I'll be editing the template and just end up screwing everything up. So how do you use the template to create an entirely new page/entry?
Answer: It's pretty straightforward, here's what I do.. I open 2 browser windows (actually 2 tabs since I use mozilla), one is an edit on the template page, I select all from the text box. Then I click on the function in the wow API list I want to create, and paste the template into the empty edit box that comes up. Once that's done I just fill in the data, remove the comments, fix up the category link, preview, and save! -- Flickering 21:06, 18 Jan 2005 (EST)
Widget API Functions Edit
So in the same spirit as the full symbol scan for normal API functions, I scanned all of the viable symbols on all of the defined Frame objects, and derived a widget API hierarchy based on the actual function definitions. It looks a little different than the one here, mostly because there are several 'top-level' entities which define completely different implementations of the basic functions like Show() and Hide().
I've put together a page with the full list on called Widget API.. Check it out and let me know what you all think.
Well I had a look, but... to be entirely honest, I don't really see how it's different from what I have added to the WoW API page? Ok so you added some Texture and Fontstring derivatives which I didn't have, but apart from that, I don't really understand the difference.. I also obtained the list here by scanning against existing functions in-game, so how is this different? I see you disagree with the interpretation of what's 'top-level', and I personally don't think that Show and Hide are that different, so that's why I lumped them under LayoutFrame. Which is, in fact, the abstract top-level entity defined in UI.xsd. -- Lego 11:58, 6 Feb 2005 (EST)
I wasn't trying to step on any toes, and it wasn't intended as a criticism of the existing WIdget API. I just wanted to make sure tha the derivations matched the code, and then add the object type to the API call name so that we could handle cases where different widget types implement slightly different behaviours for the same method name. As for LayoutFrame, that does indeed seem to be the best approach to those common functions which are implemented differently but which act the same.all of the time, like Show and Hide. -- Flickering 14:02, 6 Feb 2005 (EST)
Place for Important Globals? Purge Old Functions? Edit
Is there a page for important globals like AUCTION_EXPIRED_MAIL_SUBJECT? Also is it OK to purge old functions that don't appear to be in the exe anymore?
--Bug 15:01, 6 Feb 2005 (EST)
There aren't pages for the various global values (yet?) - I do have a pretty comprehensive list as I imagine others do. As for cleanup - which functions do you believe to be expired? I have to admit my focus lately has been more about adding in functions that are not documented here than trying to clean up those that dont exist any more, but it's probably worth asking here about them specifically because sometimes there's a reason to keep them around (the API document includes some that are defined outside of the exe, for example) -- Flickering 16:07, 6 Feb 2005 (EST)
Well there is PickupSendMailCOD(amount), PickupSendMailMoney(amount), AddSendMailCOD(), AddSendMailMoney() and RunMacro(). And should I also unbold the functions I added to the main list in the Global Function List?
--Bug 16:57, 6 Feb 2005 (EST)
With the exception of RunMacro, the others are all referenced in Blizzard's own UI code, but not used. I think in light of that the best idea is to leave them in the page with a note that they do not exist anymore. RunMacro is there but commented out, it may be worth treating it similarly (leave it with a note) but we'll see what the others have to say. As for the Global Function List, that gets updated automatically by a script every so often so you dont need to worry about it. (Oh, and thanks for contributing to the wiki! always nice to see a new name) -- Flickering 17:11, 6 Feb 2005 (EST)
Splitting page (AGAIN) Edit
I know we talked about this in the past and the sentiment was to not split the page at all, but for the sake of maintainability and readability I'd like to reconsider breaking out the Widget API section from the rest. Here are the reasons why I think it's a good idea:
- The page has grown enormously (I've personally added hundreds of API functions) since the last discussion.
- Method calls and base API calls are not interchangable (due to the object requirement for method calls).
- A developer will generally know which type of function they're looking for.
Obviously we'd link to the widget page from this one if we moved it, and both pages would be in the API category. You guys set all this up so you've obviously got the final say, but at least give it a thought again. -- Flickering 16:26, 6 Feb 2005 (EST)
Actually, I have had a closer look at what Flickering has done. I must admit that his page is nicer organized than what I had done here. It's more visually appealing, perhaps clearer, and with the LayoutFrame changes actually has the same structure and information content. I also like how all the API links have been converted to object:method form. In summary:
- I am all for splitting the pages and having a separate Widget API
- I like what Flickering has done and I say let's go with the way he has set it up
A word of caution! Before you delete the Widget part from this page, let's make sure that all method pages that have already been written get correctly migrated. E.g. API_SetVertexColor -> API_Texture_SetVertexColor -- Lego 19:20, 6 Feb 2005 (EST)
Finished moving all API_Function pages (that have already been written) to API_Widget_Function. There is nothing stopping us now from deleting the Widget API section from this page. Lego 19:59, 6 Feb 2005 (EST)
Separation of internal/Lua defined functions Edit
Currently, there are some functions mingled into the list that are actually defined in Blizzard Lua code, e.g. ActionButtonDown, ActionButtonUp. Although these are very useful global functions, some kind of indication is necessary that these are not internal functions. However, I am unsure as to the best way to proceed. We could
- leave the list as it is, and indicate it if a function is Lua defined as opposed to internal, e.g. with a comment
- separate out the two things.
The advantage of letting them mingle is that in that case your average coder can find all references to, for example, Action functions in one place, wether they are internal or Lua defined. The disadvantage is the possible confusion that this can cause, especially if an AddOn replaces some Lua files.
My 2 copper.. Right now there's just a select few of these, and they seem to fit very nicely in the sections that contain them. I'm in favor of leaving them in this document as long as they're clearly annotated as non-core functions (i.e. option 1). If it gets out of hand we may just need to add some guidelines concerning whether a function of this type is eligible for the main API list -- Flickering 23:37, 6 Feb 2005 (EST)
Perhaps something as simple as adding a character before or after the link itself to show it's a 'script defined function'? Something obvious like § meaning 'Scripted' (using §)? In addition to the in-page comment, of course. So you'd get somthing like:
- § ActionButtonDown(id) - Press the specified blahblahblah...
-- Myrathi 20:19, 22 Mar 2005 (EST)
Issue regarding re-organization/renaming of API functions based on widget... Edit
Is the same as calling:
Func( frame, x, y, z );
Where Func is defined as:
Func = function( self, arg1, arg2, arg3 ) -- Do Something return; end;
If you look carefully and consider, you will realize that this means you can call:
GetWidth(MyFrame); AddMessage(MyFrame, "Hiya baby-cakes!");
And it will work. They are not truely defined as object functions... a:b() is merely convention for b(a);
I'm not sure renaming the API functions as such really reflects properly on their true nature. -- AlexanderYoshi 01:13, 7 Feb 2005 (EST)
I'm afraid Alex you are wrong.
is actually the same as
so there are such things as object functions. Since objects in Lua are represented as tables, method calls are the same as accesses to an element of the table. So they are quite different from global functions. You can have a separate global function and several methods of different objects, all of the same name.
For example even in the Blizzard Lua files there is example for this. There is a global GetText funciton, defined in LocaleProperties.lua, which is quite different from the GetText method of several of the widgets.
Lego 09:09, 7 Feb 2005 (EST)
Verified no changes with 4211 or 4216 Edit
I re-ran all my symbol dumps for the 4211 build and there dont appear to be any changes as a result of this patch. The only significant changes seem to have been a re-working of some of the emote code in FrameXML. -- Flickering 16:48, 15 Feb 2005 (EST)
Re-verified for 4216 -- Flickering 15:38, 22 Feb 2005 (EST)
I'd just like to note that the EU version may still be on 4211. The person helping me with some translations had to change it back to get it to work. --The Nerd Wonder 16:54, 22 Feb 2005 (EST)
Verified for 4216 in EU as well. The emote related changes happened 1.2.2->1.2.3, which you could've gotten if you haven't updated your interface files between them.
Still more red than blue Edit
Quite a distressing prospect really, after all this effort still more red than blue on this page... Lego 19:55, 26 Feb 2005 (EST)
What a great idea to just create all the pages so that there is no more red. This completely destroys the informative value of red links.
Loriel 09:32, 2 Nov 2005 (EST)
- I'm glad I'm not the only one who thought this. GRRRR. It'd be nice for someone to go through and just delete all the articles that don't have any information in them, but admins are in short supply here. Schmidt 01:06, 25 Jan 2006 (EST)
- When using this as a reference guide, I'd rather get a red link than a blue one to a stab article. Plus, it allows me to decide as to where I can add information to while just looking at the API. I'd say if the pages contain nothing but a stub notice, delete them. Starlightblunder 04:44, 7 Mar 2006 (EST)
Well I've gone through about 20 articles over the past little bit, maybe 30 articles. I found a couple of them that did actually have some content, so it probably wouldn't be wise to remove them all, wholesale. I deleted about 99% of the ones I looked at (which was about 1/3 of them), and I suspect there's a few more in there. I'll go through them systematically to remove all of them that have no content at all, and we can vote on those that have such little content. But by then there should be only a few, and someone should be able to go through and add to what is left. Schmidt 01:30, 7 Mar 2006 (EST)
Changes fromo 4216 - 1300 Edit
Lots of them, I'll try and get them incorporated today. -- Flickering 16:29, 22 Mar 2005 (EST)
Yeah, I figured there would be. So lucky, you US players have a head start ;-) I will regenerate the list once it hits EU as well. -- Lego 20:06, 22 Mar 2005 (EST)
I have updated the Global List for 1300. Anyone care to verify? -- Lego 13:23, 25 Mar 2005 (EST)
I'll look over it soonish. -- Flickering 20:02, 28 Mar 2005 (EST)
Normalization of API document Format Edit
I've been toying with a plan to go through all of the API documents and make them actually match the function template (Actually, a slightly cleaner template, but basically the same thing). I have a few reasons for wanting to do this, the largest are:
- I want to be able to build the main page from the individual API pages, by grabbing signatures and summaries.
- I'd like to be able to build a stand-alone HTML cross reference for those days when the wiki is down.
- It makes formatting changes easier when things are consistent beforehand.
- Coming up with a process to do this (and verify it) means I can keep new contributions consistent.
- It allows for better tracking of incomplete documentation.
- I can produce 'skeleton' documentation for a great number of the existing undocumented functions if I had better automation.
I spent a bit of time on this over the weekend, and have a process which works for the better behaved entries.
- There's an XSD for an XML representation of an API document.
- There's a script which parses an API wiki page and creates a best guess at the XML representation.
- There's an XSL stylesheet which converts the XML representation back to a standard Wiki format.
If the wiki page makes it through the parsing script without isssues, then the result is a nice consistently formatted page. It's kinda cool when it happens right for one of the larger documents. Anyway, i'm still working on it all offline, but once I have a good degree of confidence about the process I'll start (by hand) converting some of the API documents and you can all chime in on the result.
-- Flickering 20:14, 28 Mar 2005 (EST)
I've gone through and cleaned up the categorization. Most of the old categories have only gained functions, and I'm sure there are some which could do with attention. I also cleaned up places where the same function was listed with different text, and I've clearly marked UI and REMOVED functions. These have their own sections as well, for reference. The only links which I removed were those which should have been on the WidgetAPI.. Hopefully that didn't strand any good documentation in limbo, I guess we'll find out.. I do have a copy of the old version (and checked the two before committing to avoid any unexpected problems). -- Flickering 19:32, 17 Jul 2005 (EDT)
Dressing Room API Edit
I went ahead and added the functions from DressUpFrame.lua. I also adding the description for DressUpItemLink since I was able to confirm it's usage (modified LootLink so I could ctrl-click from it :) ) If it doesn't belong there, or I did something wrong please let me know and I'll correct it. I wasn't sure how previous "patch days" went...