WoW:Creating simple pop-up dialog boxes: Difference between revisions

{{UIHowTo}}

through the mail, renaming a pet, and so forth. This tutorial describes how you can use the StaticPopup code to display simple dialogs in your own addon.

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.

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.

To display the dialog, call <tt>StaticPopup_Show</tt> with the name of the entry:

Up to 4 static popups may be displayed at once.  The UI will handle finding an open slot for you.

To make the dialog disappear without having a user click it, call <tt>StaticPopup_Hide</tt> with the name of the entry:

Calling the <tt>StaticPopup_Hide</tt> function after the dialog has already been hidden does not appear to have any ill effect.  Return values of this function, if any, are not documented.

* ''OnAccept'' - This function can take up to two arguments, both optional.  They are for passing arbitrary data around the callbacks.  There are very few examples of the use of the arguments.  In general this is used with dialogs that have an editable text field, to pass the entered text back to the function.  Also for chaining dialog boxes together.

** "clicked" - The player clicked button2, or hit the escape key and hideOnEscape is set.

The ''text'' field of an entry can contain formatting placeholders.  When the popup is actually displayed,

the calling function can pass two additional arguments to <tt>StaticPopup_Show</tt>.  The ''text'' field and

For example, the default guild invitation popup sets <tt>text = "%s invites you to join %s"</tt>, and the display call is to <tt>StaticPopup_Show ("GUILD_INVITE", name_of_officer, name_of_guild)</tt>.

To add a editbox in the popup set the ''hasEditBox'' option field to true. The EditBox gets the name "$parentEditBox", relative to the Popup, and is also available in the popup's ''.editBox'' field.  (Recall that the popup dialog is the value returned from the ''StaticPopup_Show()'' function.)  To get and set the value of the EditBox use the following code:

Using ''hasEditBox''/''.editBox'' causes a small one-line text field to appear.  You can use the ''hasWideEditBox'' option field (and the corresponding ''.wideEditBox'' dialog field) to cause the text field to have the full width of the dialog box instead.  To do this, you must set both options, but only the wide edit box will be used.

There are some more settings available for use in static popup entries.  This list is almost certainly incomplete, I'm just describing the ones which catch my eye.  For more information, extract the StaticPopup.xml and .lua files from the default UI and browse.

to be implemented by addon authors, the example is simple enough to remain here.)

It is possible, though not immediately obvious how, to pass arbitrary user data to the local functions (e.g. OnAccept, OnCancel).  Write your local function like this:

If you need to manipulate any of the dialog's visual elements, most of them are directly accessible as table fields of the dialog, so you do not need to use an expensive sequence of ''getglobal(self:GetName().."Something")''.  For example, ''dialog.button1'' points to the first button.  See the StaticPopup.xml file's various OnLoad sections for the full list.

* The 'text' fields and button1/2/3 fields are usually localized.  Blizzard tends to use generic texts like ACCEPT, CANCEL, and OKAY; you can probably do the same.  These global variables contain a localized string and can be used as-is, like <tt>button1 = ACCEPT</tt>

* Creating a static popup with an editbox and only one button will cause the button and the editbox to overlap. Having more than one button will get the desired behavior. (Tested on 2.4.1)