|
Overview
Syntax: popup <command> <popup id> <parameters>
Note: Command parameters are described inside the < and > characters. Optional parameters are contained within [ and ] characters.
Description
This command makes it easier to create, display, edit and handle various kinds of popups displayed to players.
Starting from EventScripts 2.0, popup command invokes functions from popuplib. For addons, it is recommended to use popuplib in favor over the popup command.
Note: It doesn't expand server variables. Prefix the command with es to expand variables (es popup).
Parameters
- command - tells what to do to your popup
- popup id - unique name for the popup to be modified
- parameters - command specific parameters
<userComments></userComments>
Commands
- popup create
<popup id>
- Creates a new popup to memory. You need to create a popup using this command before using any other commands on it. If the popup already exists, it will be deleted automatically and the created again.
- popup delete
<popup id>
- Deletes a popup from memory. This command will not automatically unsend existing popups sent to clients, use unsendname for that before calling delete.
- popup delline
<popup id> <line number>
- Deletes a line of text from the popup.
- popup addline
<popup id> <text>
- Adds a new line of text to the popup.
- popup insline
<popup id> <line number> <text>
- Insert a line of text to the selected position in the popup.
- popup modline
<popup id> <line number> <text>
- Modifies an existing line by replacing it with new text.
- popup addlinef
<popup id> <format> [token1] ... [token9]
- Adds a new line of text to the popup using es_formatv syntax. (since ES 1.5.0)
- popup inslinef
<popup id> <line number> <format> [token1] ... [token9]
- Insert a line of text using es_formatv syntax to the selected position in the popup. (since ES 1.5.0)
- popup modlinef
<popup id> <line number> <format> [token1] ... [token9]
- Modifies an existing line by replacing it with new text using es_formatv syntax. (since ES 1.5.0)
- popup prepuser
<popup id> <block>
- Define a block to be executed just before the popup is displayed to an user. Useful to provide up-to-date information. A server variable _popup_userid is set to match the userid to whom the popup is to be sent.
- popup menuselect
<popup id> <block>
- Define a block to be executed when user responds to the popup.
- Variables that can be used in the block:
- _popup_choice - the menu option the user chose (integer between 1 and 10)
- _popup_userid - the userid of the player selecting the menu option
- _popup_name - the name of the popup that was just used (since ES 1.5.0.170a)
- popup menuselectfb
<popup id> <block>
- Define a block to be executed when user responds to the popup and individual block for the item has not been set using popup select. The server variables available are the same as in menuselect.
- popup select
<popup id> <1-10> <block>
- Define a block to be executed when user chooses a specific menu item. The server variables available are the same as in menuselect.
- popup submenu
<popup id> <1-10> <sub popup id>
- Define another popup to be immediately displayed when user chooses a specific menu item. The server variables available are the same as in menuselect.
- popup menuvalue
<popup id> <variable> <1-10> <value>
- Define a value to be set to variable when the specific menu item is selected. Especially useful for player list menus.
- popup timeout
<popup id> <send, view> <time>
- Set a timeout after which the popup expires. You can set two timeout values for all popups, send timeout controls how long the popup can be in the user's queue after it is dismissed. View timeout controls how long the popup is allowed to be viewed on the user's screen after which the user automatically sends menuselect 10 to the server. The time is in seconds.
- popup send
<popup id> <user>
- Add the popup to selected users' popup queue. If the queue is empty, the popup will be viewed to the user. You can enqueue multiple popups using the same name. If you want to make sure the user only gets one popup to the queue, check if the popup is already in the queue using isqueued command.
- popup unsend
<queue id> <userid>
- Internal command used with popup timeout send.
- popup unsendid
<queue id> <userid>
- Internal command used with popup timeout view.
- popup unsendname
<popup id> <user>
- Removes all popups with given name from the users' popup queue. If one of those popups is being displayed to the user, it will send menuselect 10 to the server. Note: usage of popup close is recommended for sticky popups.
- popup close
<popup id> <user>
- The same as unsendname except that the action of menuselect 10 is ignored by popup.
- popup isqueued
<popup id> <variable> <userid>
- Checks if the popup named popup id exists in user's popup queue and sets the queue position to variable. If there are multiple popups with the same name, the queue position of the first found match is set into variable. If there are no popups with given name in the queue, variable is set to 0 (zero).
- popup active
<name> <count> <userid>
- Stores the name of active popup to variable name and the number of popups in queue to variable count. If there are no popups in queue, both variables are set to 0 (zero).
- popup exists
<name> <variable>
- Checks if the popup is created and sets variable to 1 if yes, or 0 if no. (since ES 1.5.0)
- popup displaymode
<popup id> <mode>
- Sets the display mode of the popup. The possible values are normal (default) and sticky. See Sticky popups for more info. (since ES 1.5.0)
- popup setvar
<popup id> <i_var> <value>
- Sets an internal popup variable. This is for advanced scripters only {{DocumentationTBD.}} (since ES 1.5.0)
- popup getvar
<popup id> <variable> <i_var>
- Gets an internal popup variable. This is for advanced scripters only {{DocumentationTBD.}} (since ES 1.5.0)
- popup cachemode
<popup id> <mode>
- Sets the cachemode of the popup. Valid values are: global (default), static and user. This is for advanced scripters only {{DocumentationTBD.}} (since ES 1.5.0.170a)
- popup recache
<popup id> [user]
- Refreshes the internal popup cache. Usable with cachemodes static and user. The optional user parameter is only to be used with cachemode user popups (and is required for them). (since ES 1.5.0.170a)
- popup update
<popup id> <user>
- Updates the popup on users' display in case it is visible. Useful if you do modifications to a popup while it is being displayed and you want to refresh it to show the changes. (since ES 1.5.0.170a)
- popup construct
<popup id> <list> <flags>
- Specifies a special automatically constructed popup to a popup name (popup id. The list parameter usually is "players" with the flags parameter being same kind of flags that can be supplied to foreach player. (since ES 2.0.0.247a)
- popup easymenu
<popup id> <variable> <script/block>
- Creates an automatically paged menu to which you can add items using the addoption subcommand. The chosen option is saved in variable and script/block is the menuselectfb block. (since ES 2.0.0.247a)
- popup addoption
<popup id> <value> <text> [state]
- Adds a menu item to easymenu popup. The value is the value set to the variable specified when creating the easymenu. text is the text displayed in the menu and optional state is either 1 or 0, representing enabled/disabled state. Disabled options cannot be chosen by players and appear in white color whereas enabled options appear in orange. (since ES 2.0.0.247a)
- popup setoption
<popup id> <value> [text] [state]
- Changes either the text or state of an option in easymenu. The option to be changed is identified with value. (since ES 2.0.0.247a)
- popup description
<popup id> <text>
- Sets a description to an easymenu popup. (since ES 2.0.0.247a)
- popup info
<popup id> [level]
- Displays information about the specified popup. Optional level specifies the detail level of the information, value between 0 and 4. (since ES 2.0.0.247a)
- popup list
[level]
- Lists all existing popups, optionally with detailed information. (since ES 2.0.0.247a)
- popup emulate
<popup id> <choice> <users>
- Emulates users choosing an option from a popup. For debugging purposes only, never use in a script! (since ES 1.5.0.170a)
- popup editlang
<popup id> <language>
- Changes the editing language of the popup. Adding text in multiple languages enables popups to be sent to users with the language they use Steam in. (since ES 2.0.0.247a)
- popup setstyle
[popup id] <style>
- Sets the visual style of popups. style can be "auto", "radio" or "esc". Server admins only (do not use in a script): If no popup name is specified, makes a default choice for the whole server, you can add ! at the end of the style to force the style for all popups, even those for which a style was explicitly set with this command. (since ES 2.0.0.247a)
- popup quicksend
<time> <userid> <text> [block]
- The same as es_menu but respects popup queuing system. Optionally you can select a block that is executed when an option is chosen from this popup. (since ES 2.0.0.247a)
- popup about
- Displays version information about the popup libraries. (since ES 2.0.0.247a)
Sticky popups
Starting from Popup 2.0 (EventScripts 1.5+), there is a special sticky mode for popups. It differs from normal popups so that it will not go away from the player's screen. The player is still able to use the numeric keys normally to change their weapons.
To change a popup to sticky mode, the command
popup displaymode <popup id> sticky
must be issued after creating the popup.
If you add any menu action (select, menuselectfb, menuselect, submenu), then the sticky feature will be removed from the menu items the chosen action applies to. See the Examples for better understanding of this feature.
User parameter
Notice that some popup commands have parameter <userid> and some others have <user>. They are different. For parameter <userid>, only a valid single userid can be given.
The parameter <user> can be any of these:
- a valid single userid
- a player's Steam ID
- partial player's name
- single foreach-style flag such as #all or #ct
- Note: double flags such as #alive#t are not supported
Examples
These are demonstrations of popup test scripts (save to popupt/es_popupt.txt)
block load
{
// The popups should be created in the load block for maximal performance and flexibility.
// In this example, we will create a popup and name it "HelloWorld"
popup create HelloWorld
// Now that the popup has been created, let us add some visible content to it:
popup addline HelloWorld "This is an example popup"
// To create an empty line to a popup, add a space to it:
popup addline HelloWorld " "
popup addline HelloWorld " Hello World!"
// Now we have a popup named "HelloWorld" and it has three lines of text in it
}
event player_say
{
// Players will never see the popup unless you send it to them
// In this example, we will use player_say event
// If the user says "test", then we will send out HelloWorld popup to them:
if (event_var(text) == "test") do
{
// Note that to use variables, we need to prefix the line with "es":
es popup send HelloWorld event_var(userid)
// Now the user has a nice little popup on their screen :)
}
}
block unload
{
// You might want to clear up the server memory in case your script gets unloaded
// So you should delete all the popups you create in block unload:
popup delete HelloWorld
}
// This example shows how to create a simple menu and how to handle the menu options players choose
block load
{
// Create the menu:
popup create TestMenu
popup addline TestMenu "Choose your drink:"
// To add orange menu options, prefix the line with ->
popup addline TestMenu "->1. Water"
popup addline TestMenu "->2. Juice"
popup addline TestMenu "->3. Milk"
popup addline TestMenu "->4. Coffee"
popup addline TestMenu "0. Close"
// Note: since -> was not used, the last line will appear white
// Now we will add the player tracking by specifying a block
// that is executed whenever a player selects an item from the menu
popup menuselect TestMenu popupt/chosen
// The above will cause "es_xdoblock popupt/chosen" to be used
}
event player_say
{
if (event_var(text) == "!drink") do
{
es popup send TestMenu event_var(userid)
}
}
// The menu item handler block:
block chosen
{
if (server_var(_popup_choice) == 1) then es_tell server_var(_popup_userid) You chose Water!
if (server_var(_popup_choice) == 2) then es_tell server_var(_popup_userid) You drink Juice!
if (server_var(_popup_choice) == 3) then es_tell server_var(_popup_userid) Milk is good for you!
if (server_var(_popup_choice) == 4) then es_tell server_var(_popup_userid) Coffee might ruin your sleep!
if (server_var(_popup_choice) > 4) do
{
if (server_var(_popup_choice) < 10) do
{
es_tell server_var(_popup_userid) You should have chosen an option between 1 and 4...
}
}
}
block unload
{
// Remove the popup from all players
popup unsendname TestMenu #all
// Then delete it from taking up memory
popup delete TestMenu
}
block load
{
// This is an example of sticky popup that will not leave you!
popup create test
popup displaymode test sticky
}
event player_team
{
if (event_var(team) > 1) then es_xdelayed 5 popup send test event_var(userid)
}
Notes
- The server admin (or the script) must load popup script (included in EventScripts package) using es_load popup
- Popup does not use radio menus in Half-Life 2 Deathmatch or in mods using that game as their base.
- VGUI dialogs are used instead (since ES 2.0.0.247a)
- The view timeout no longer sends out menuselect 10 command (since ES 1.5.0)
- Using popuplib, setting oldskooltov to True will bring old functionality back (since ES 2.0.0.244)
- Works indentically regardless of cl_restrict_server_commands setting on clients. (since ES 1.5.0)
See also
|
|
