Module: popuplib

Module Overview

EventScripts version: 2.0 or greater

Table of Contents

Description

Popuplib provides full support for creating and handling popups and menus that are shown to players on the server.

Quick Example

Creating a simple popup:

# Create a new popup
myPopup = popuplib.create('example_popup')
# Now add some content to it
myPopup.addline('Hello world!')
myPopup.addline('You are playing with ES 2.0!')
# Send the popup to everyone on the server
myPopup.send(es.getUseridList())

For more examples, see http://forums.mattie.info/cs/forums/viewtopic.php?t=18250

Module Content

Classes

• popuplib.Popup_popup -- Normal popup for creating any single content popup
  • Create one with the popuplib.create function rather than using the class directly (see methods)
• popuplib.Popup_easymenu -- Easymenu popup for easily constructing a menu that can span multiple pages
  • Create one with the popuplib.easymenu function rather than using the class directly (see methods)
  • The method popuplib.construct also creates this type of classes with special properties.
• popuplib.Popup_list -- Automatically paged popup that displays a numbered list (10 items per page). Ideal for "top xx" lists.
  • Create one with the popuplib.easylist function rather than using the class directly (see methods)

Methods

popuplib.active(userid)

Checks the player's popup status and returns it in a dictionary form

{'name': 'popup name', 'count': queue_size, 'object': Popup_class_object}

Example:

status = popuplib.active(2)
es.msg('User 2 has popup ' + status['name'] + ' active')
es.msg('User 2 has ' + str(status['count']) + ' popups sent to him')
status['object'].addline('Adding another line to the active popup')

popuplib.close(popupname, users)

Remove the named popup from users' queue but do not trigger menuselect 10, always returns None.

Example:

popuplib.close('admin_menu', playerlib.getUseridList('#alive'))

popuplib.construct(popupname, construct, flags, function = None)

Creates a new easymenu popup object with the specified name and returns a reference to the newly created popup class object of type popuplib.Popup_easymenu. The contents for this popup are automatically created on demand based on the construct type and flags.

The popup can be later referred to by the name given here by other functions shown here or with the popup console command.

You need to delete existing popups with the same name before using this method, use popuplib.exists and popuplib.delete to aid you.

Parameters:

• popupname -- the global popup name that identifies this popup
• construct -- specifies which kind of content this menu has (for example "players")
• flags -- specifies flags for the construct (for example "#all" when using "players" type)
• function -- a Python function or script block that acts as menuselectfb

Example:

def menuhandler(userid, choice, popupname):
    es.tell(userid, 'You chose player '+es.getplayername(choice))
 
playerList = popuplib.construct('test_menu', 'players', '#all', menuhandler)

popuplib.create(popupname)

Creates a new normal popup object with the specified name and returns a reference to the newly created popup class object of type popuplib.Popup_popup.

The popup can be later referred to by the name given here by other functions shown here or with the popup console command.

If the named popup already exists, no new popup is created, but the existing popup is made empty and returned.

Example:

myPopup = popuplib.create('example_popup')

popuplib.delete(popupname)

Deletes a popup with the given name if it exists.

Raises ValueError if the popup does not exist

Example:

try:
    popuplib.delete('example_popup')
except ValueError:
    es.dbgmsg(0, 'example_popup did not exist...')

popuplib.easylist(popupname, data=None, options=10)

Creates a new easylist popup object with the specified name and returns a reference to the newly created popup class object of type popuplib.Popup_easylist.

The popup can be later referred to by the name given here by other functions shown here or with the popup console command.

If the named popup already exists, it is replaced with a new one.

Parameters:

• popupname -- the global popup name that identifies this popup
• data -- optional iterable data (ideally a list) that is used to construct the list
• options -- optional integer value telling how many items to show per page

Example:

top10addons = ['GunGame 4', 'GunGame 3', 'GlobalBan', 'es_AddMap', 'MB_Bullettime',
    'PopupAdmin', 'StickyNades', 'ExtendedEvents', 'Zombie Gamemode', 'RateMap']
 
top10popup = popuplib.easylist('top10addons', top10addons)

popuplib.easymenu(popupname, variable, function)

Creates a new easymenu popup object with the specified name and returns a reference to the newly created popup class object of type popuplib.Popup_easymenu.

The popup can be later referred to by the name given here by other functions shown here or with the popup console command.

If the named popup already exists, it is replaced with the new one.

Parameters:

• popupname -- the global popup name that identifies this popup
• variable -- server variable name that will contain the selected menu item
• function -- a Python function or script block that acts as menuselectfb

Example:

def menuhandler(userid, choice, popupname):
    pass
 
myMenu = popuplib.easymenu('test_menu', '_popup_choice', menuhandler)

popuplib.exists(popupname)

Returns True or False depending on if the named popup exists

Example:

if popuplib.exists('example_popup'):
    popuplib.delete('example_popup')

popuplib.find(popupname)

Find the named popup object and returns the class object reference. If the named popup was not found, None is returned.

Example:

myPopup = popuplib.find('example_popup')
if myPopup:
    myPopup.recache()

popuplib.isqueued(popupname, userid)

Checks if the specified user has the named popup in their queue. The queue position of the popup is returned; 0 == no popup in queue, 1 == popup being displayed, 2 == next in queue, 3,4,...

Example:

if popuplib.isqueued('example_popup', userid):
    popup.close('example_popup', userid)

popuplib.langstring(prefix, langobject, suffix="")

Creates and returns a fake multi-language string object that can be used for addline and similar methods by appending prefix and optional suffix to each of the strings in langobject.

Example:

# text is a langlib object here
p = popuplib.create('langtest')
ml = popuplib.langstring('->1. ', text('option1'))
p.addline(ml)

popuplib.quicksend(time, users, text, function="")

Acts like es.menu except for that it uses the popup queue like any other popup and it allows you to specify a block or function that is called when a menu item is selected.

Example:

popuplib.quicksend(0, event_var['userid'], 'Hello World!\nBlaah...')

popuplib.registerConstruct(name, function)

Registers a new constructor function to be used with the popuplib.construct method.

Example:

def ConstructScripts(popupid, flags, menuselectfb):
    #stuff here
    return new_easymenu
 
popuplib.registerConstruct('scipts', ConstructScripts)

popuplib.send(popupname, users)

Sends the specified popup to selected users. As with most other functions, users can be either a single userid or a list of users.

If the named popup is not found, this function raises ValueError

Example:

popuplib.send('welcome_message', es.getUseridList())

popuplib.unregisterConstruct(name)

Removes a registered constructor function.

Example:

def unload():
    popuplib.unregisterConstruct('myconstruct')

popuplib.unsendname(popupname, users)

Removes the sent popup from users' queue if it exists there. If the popup is currently being displayed to the person, menuselect 10 is issued and any action tied to that is handled.

Example:

popuplib.unsendname('welcome_message', es.getUseridList())

See Also

• popup