Editing WoW:Creating simple pop-up dialog boxes (section)

== Basic setup ==
In the "Hello, World" programming tradition, the example on this page will assume that you have a function, called <tt>GreetTheWorld</tt>, and that you are creating a simple dialog to ask the player whether or not to be socially outgoing.

New dialogs are created by adding an entry to the global <tt>StaticPopupDialogs</tt> table, and populating the entry with required and optional information. Here is a simple two-button entry:

 StaticPopupDialogs["EXAMPLE_HELLOWORLD"] = {
   text = "Do you want to greet the world today?",
   button1 = "Yes",
   button2 = "No",
   OnAccept = function()
       GreetTheWorld()
   end,
   timeout = 0,
   whileDead = true,
   hideOnEscape = true,
   preferredIndex = 3,  -- avoid some UI taint, see http://www.wowace.com/announcements/how-to-avoid-some-ui-taint/
 }

The index in the array is an arbitrary string. It must be unique in the context of the array. (If you are
familiar with the [[HOWTO:_Create_a_Slash_Command|SlashCmdList]] array, this works exactly the same.)

Here you see the basic required information, along with some settings that are strictly optional but should be given by all well-behaved entries:

* ''text'' - This is the text inside the dialog box. For example, "Looting this item will bind it to you."
* ''button1'' - This is the text on the left-hand "yes" button. Clicking this button will call the <tt>OnAccept</tt> function in the entry. In a popup with only one button, it is this one. There are global variables includiung ACCEPT, CANCEL, and OKAY, which contain localized strings and are perfectly suited for assigning to the button* fields. Some dialogs (like the "you are not part of this instance's group and are going to get teleported" warning) do not even have a single button.
* ''button2'' - This is the text on the right-hand "no" button. If the entry has an <tt>OnCancel</tt> function, clicking this button will call it with "clicked" as the reason (see below).
* ''OnAccept'' - This points to a function; it can be as complicated as you like and is typically a local "anonymous"-style function defined on the spot as shown above. You do not need to explicitly hide the popup frame; it will be hidden for you.
* ''timeout'' - After this many seconds, the dialog will go away. If the entry has an <tt>OnCancel</tt> function, it will be called with "timeout" as the reason. Dialogs which do not expire should set this to zero.
* ''whileDead'' - Set to true if this dialog can be shown while the player is a ghost. You probably want to do this.
* ''hideOnEscape'' - Set to true if hitting the Escape key should be treated like clicking button2. You probably want to do this.

If your addon has a general OnLoad event handler, that is an excellent place to perform this array insertion. If the contents of the entry do not require any runtime information, you can perform the insertion during loadup by putting it at file scope.

Note that this guide refers to setting boolean options to 'true' or 'false'; earlier editions used '1' and 'nil' for the same purposes. The fact of the matter is that you can set those options to anything which evaluates to true-valued or false-valued results according to Lua: 'nil' and 'false' are false-valued, anything else (including 0 and "") is true-valued. A lot of original Blizzard code was written for an earlier version of Lua, which did not have formal boolean types. Use whatever makes the most sense for your addon.