WoW:Creating simple pop-up dialog boxes - Revision history

Move page script: Move page script moved page Creating simple pop-up dialog boxes to WoW:Creating simple pop-up dialog boxes without leaving a redirect

2023-08-15T04:47:57Z

Move page script moved page Creating simple pop-up dialog boxes to Creating simple pop-up dialog boxes without leaving a redirect

← Older revision	Revision as of 04:47, 15 August 2023
(No difference)

Bear at 09:11, 21 May 2020

2020-05-21T09:11:51Z

WoWWiki>Mikk: /* Basic setup */ note on avoiding some taint

2012-03-25T00:44:46Z

Basic setup: note on avoiding some taint

← Older revision		Revision as of 00:44, 25 March 2012
Line 21:		Line 21:
	whileDead = true,		whileDead = true,
	hideOnEscape = true,		hideOnEscape = true,
			preferredIndex = 3, -- avoid some UI taint, see http://www.wowace.com/announcements/how-to-avoid-some-ui-taint/
	}		}

WoWWiki>Farmbuyer: mention maxLetters

2010-09-17T17:14:49Z

mention maxLetters

Show changes

WoWWiki>Gourra at 12:16, 20 September 2009

2009-09-20T12:16:53Z

← Older revision		Revision as of 12:16, 20 September 2009
Line 1:		Line 1:
	{{UIHowTo}}		{{UIHowTo}}
	'''Static popups'' are simple one- or two-button dialog boxes you see when confirming a warlock summon, sending money		'''Static popups''' are simple one- or two-button dialog boxes you see when confirming a warlock summon, sending money
	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.		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.

Line 6:		Line 6:


	== Basic ~~Setup~~ ==		== 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.		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.

Line 41:		Line 40:
	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.		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.

			== Displaying the popup ==
	== Displaying the ~~Popup~~ ==

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

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

			== Hiding the popup ==
	== Hiding the ~~Popup~~ ==

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

Line 65:		Line 60:
	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.		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.

	== Advanced ~~Setup~~ ==		== Advanced setup ==

	* ''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.		* ''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.

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

			=== Dialog text parameters ===
	=== Dialog ~~Text Parameters~~ ===

	The ''text'' field of an entry can contain formatting placeholders. When the popup is actually displayed,		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		the calling function can pass two additional arguments to <tt>StaticPopup_Show</tt>. The ''text'' field and
Line 83:		Line 75:
	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>.		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>.

			=== Editable text fields ===
	=== Editable ~~Text Fields~~ ===

	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:		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:

Line 105:		Line 95:
	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.		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.

	== Optional ~~Features~~ ==		== Optional features ==

	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.		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.

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

	== Passing ~~Arguments~~ to ~~Local Functions~~ ==		== Passing arguments to local functions ==

	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:		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:

Line 173:		Line 161:
	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.		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.

	== Notes and ~~Observations~~ ==		== Notes and observations ==
	* 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>		* 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)		* 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)

WoWWiki>Farmbuyer: /* Passing Arguments to Local Functions */

2009-09-20T10:35:56Z

Passing Arguments to Local Functions

Show changes

WoWWiki>Starlightblunder: {{UIHowTo}}, slight lead-in tweak

2009-05-26T14:30:22Z

{{UIHowTo}}, slight lead-in tweak

← Older revision		Revision as of 14:30, 26 May 2009
Line 1:		Line 1:
	~~This HOWTO covers the creation of what Blizzard calls~~ ''~~static~~ popups''~~. These~~ are ~~the~~ simple		{{UIHowTo}}
	one-~~button and~~ two-button dialog boxes you see when confirming a warlock summon, sending money		'''Static popups'' are simple one- or two-button dialog boxes you see when confirming a warlock summon, sending money
	through the mail, renaming a pet, and so forth.		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.

	As you might expect, all of the basic UI elements (positioning, sound effects, layout) are handled for you.		As you might expect, all of the basic UI elements (positioning, sound effects, layout) are handled for you.

WoWWiki>KirkBot: Typo fixing using AWB

2009-04-10T00:03:17Z

Typo fixing using AWB

← Older revision		Revision as of 00:03, 10 April 2009
Line 88:		Line 88:
	OnShow = function()		OnShow = function()
	getglobal(this:GetName().."EditBox"):SetText("Some data")		getglobal(this:GetName().."EditBox"):SetText("Some data")
	-- notice: "this" is the StaticPopup, ~~normaly~~ its "StaticPopup1"		-- notice: "this" is the StaticPopup, normally its "StaticPopup1"
	end,		end,
	OnAccept = function()		OnAccept = function()
	getglobal(this:GetParent():GetName().."EditBox"):GetText()		getglobal(this:GetParent():GetName().."EditBox"):GetText()
	-- do whatever you want with it		-- do whatever you want with it
	-- notice: "this" is the left button, ~~normaly~~ its "StaticPopup1Button1",		-- notice: "this" is the left button, normally its "StaticPopup1Button1",
	-- so you need the GetParent() call.		-- so you need the GetParent() call.
	end,		end,
Line 168:		Line 168:
	* Added by [[user:Layrajha\|Layrajha]]: The OnHide function will always be called after OnAccept or OnCancel have finished their execution. Therefore, it is safe to assume that your changes done in OnAccept or OnCancel will be done when OnHide is called. Also note that you can prevent the popup from hiding after clicking the "Accept" button: just make the OnAccept function return "true" (or anything different from "nil" and "false", it will work just as well).		* Added by [[user:Layrajha\|Layrajha]]: The OnHide function will always be called after OnAccept or OnCancel have finished their execution. Therefore, it is safe to assume that your changes done in OnAccept or OnCancel will be done when OnHide is called. Also note that you can prevent the popup from hiding after clicking the "Accept" button: just make the OnAccept function return "true" (or anything different from "nil" and "false", it will work just as well).

	[[Category: HOWTOs\|Popup Simple Dialog Boxes]]		[[Category:HOWTOs\|Popup Simple Dialog Boxes]]

WoWWiki>Caweman: edited the example of passing arguments to local functions for clarification

2009-03-15T10:57:45Z

edited the example of passing arguments to local functions for clarification

← Older revision		Revision as of 10:57, 15 March 2009
Line 146:		Line 146:
	Write your local function like this:		Write your local function like this:

	OnAccept = function(~~argName~~)		OnAccept = function(self)
	DoSomethingWith(~~argName~~)		DoSomethingWith(self.data)
	end		end

Line 167:		Line 167:
	* While creating your popup entries, you will probably be doing a lot of UI reloading. Extract the <tt>[[FrameXML/DebugUI.xml]]</tt> file from the default UI, copy it into your addon folder, and add it to your .toc file. This has two effects: it starts verbose logging into FrameXML.log, and it adds a "Reload UI" button to your screen. Very handy timesaver. :-)		* While creating your popup entries, you will probably be doing a lot of UI reloading. Extract the <tt>[[FrameXML/DebugUI.xml]]</tt> file from the default UI, copy it into your addon folder, and add it to your .toc file. This has two effects: it starts verbose logging into FrameXML.log, and it adds a "Reload UI" button to your screen. Very handy timesaver. :-)
	* Added by [[user:Layrajha\|Layrajha]]: The OnHide function will always be called after OnAccept or OnCancel have finished their execution. Therefore, it is safe to assume that your changes done in OnAccept or OnCancel will be done when OnHide is called. Also note that you can prevent the popup from hiding after clicking the "Accept" button: just make the OnAccept function return "true" (or anything different from "nil" and "false", it will work just as well).		* Added by [[user:Layrajha\|Layrajha]]: The OnHide function will always be called after OnAccept or OnCancel have finished their execution. Therefore, it is safe to assume that your changes done in OnAccept or OnCancel will be done when OnHide is called. Also note that you can prevent the popup from hiding after clicking the "Accept" button: just make the OnAccept function return "true" (or anything different from "nil" and "false", it will work just as well).

	[[Category: HOWTOs\|Popup Simple Dialog Boxes]]		[[Category: HOWTOs\|Popup Simple Dialog Boxes]]

WoWWiki>Farmbuyer at 19:53, 7 January 2009

2009-01-07T19:53:20Z

← Older revision		Revision as of 19:53, 7 January 2009
Line 8:		Line 8:
	== Basic Setup ==		== Basic Setup ==

	~~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.		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:		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:

← Older revision		Revision as of 09:11, 21 May 2020
Line 1:		Line 1:
	{{~~UIHowTo~~}}		{{wow/uihowto}}
	'''Static popups''' are simple one-, two-, or three-button dialog boxes you see when confirming a warlock summon, sending money		'''Static popups''' are simple one-, two-, or three-button dialog boxes you see when confirming a warlock summon, sending money
	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.		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.
Line 9:		Line 9:
	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.		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:		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"] = {		StaticPopupDialogs["EXAMPLE_HELLOWORLD"] = {
Line 24:		Line 24:
	}		}

	The index ~~into~~ the array is an arbitrary string. It must be unique in the context of the array. (If you are		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.)		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:		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."		* ''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.		* ''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).		* ''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.		* ''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.		* ''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.		* ''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.		* ''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.		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.		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.

	== Displaying the popup ==		== Displaying the popup ==
Line 47:		Line 47:

	The dialog will be put together and displayed, and the function returns as soon as the dialog is shown.		The dialog will be put together and displayed, and the function returns as soon as the dialog is shown.
	If all goes well, the table object for that dialog will be returned from the function. If there		If all goes well, the table object for that dialog will be returned from the function. If there
	are any problems, it returns nil.		are any problems, it returns nil.

	This function has two more optional arguments, see [[#Dialog_Text_Parameters\|Dialog Text Parameters]] below.		This function has two more optional arguments, see [[#Dialog_Text_Parameters\|Dialog Text Parameters]] below.

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

	== Hiding the popup ==		== Hiding the popup ==
Line 70:		Line 70:

	=== Dialog text parameters ===		=== Dialog text parameters ===
	The ''text'' field of an entry can contain formatting placeholders. When the popup is actually displayed,		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		the calling function can pass two additional arguments to <tt>StaticPopup_Show</tt>. The ''text'' field and
	these two arguments will be passed through the [[API_format\|format]] function before being added to the dialog.		these two arguments will be passed through the [[API_format\|format]] function before being added to the dialog.

Line 166:		Line 166:
	* While creating your popup entries, you will probably be doing a lot of UI reloading. Extract the <tt>[[FrameXML/DebugUI.xml]]</tt> file from the default UI, copy it into your addon folder, and add it to your .toc file. This has two effects: it starts verbose logging into FrameXML.log, and it adds a "Reload UI" button to your screen. Very handy timesaver. :-)		* While creating your popup entries, you will probably be doing a lot of UI reloading. Extract the <tt>[[FrameXML/DebugUI.xml]]</tt> file from the default UI, copy it into your addon folder, and add it to your .toc file. This has two effects: it starts verbose logging into FrameXML.log, and it adds a "Reload UI" button to your screen. Very handy timesaver. :-)
	* Added by [[user:Layrajha\|Layrajha]]: The OnHide function will always be called after OnAccept or OnCancel have finished their execution. Therefore, it is safe to assume that your changes done in OnAccept or OnCancel will be done when OnHide is called. Also note that you can prevent the popup from hiding after clicking the "Accept" button: just make the OnAccept function return "true" (or anything different from "nil" and "false", it will work just as well).		* Added by [[user:Layrajha\|Layrajha]]: The OnHide function will always be called after OnAccept or OnCancel have finished their execution. Therefore, it is safe to assume that your changes done in OnAccept or OnCancel will be done when OnHide is called. Also note that you can prevent the popup from hiding after clicking the "Accept" button: just make the OnAccept function return "true" (or anything different from "nil" and "false", it will work just as well).

	[[Category:HOWTOs\|Popup Simple Dialog Boxes]]		[[Category:HOWTOs\|Popup Simple Dialog Boxes]]