system.gui.createPopupMenu

This function is used in Python Scripting.

Description

Creates a new popup menu, which can then be shown over a component on a mouse event. To use this function, first create a Python sequence whose entries are strings, and another sequence whose entries are function objects. The strings will be the items that are displayed in your popup menu, and when an item is clicked, its corresponding function will be run. Passing in a function of None will cause a separator line to appear in the popup menu, and the corresponding string will not be displayed. Your functions must accept an event object as an argument. See also: Functions.

It is best to have the menu object created only once via an application specific library function. Then, call the show(event) function on both the mousePressed and mouseReleasedevents on your component. The reason for this is that different operating systems (Windows, Linux, MacOS) differ in when they like to show the popup menu. The show(event) function detects when the right time is to show itself, either on mouse press or release. See the examples for more.

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.gui.createPopupMenu(itemNames, itemFunctions)

Parameters

Type	Parameter	Description
PySequence	itemNames	A list of names to create popup menu items with.
PySequence	itemFunctions	A list of functions to match up with the names.

Returns

JPopupMenu - The javax.swing.JPopupMenu that was created.

Scope

Client

Code Examples

Event Handlers

A popup menu must be created on either the mouse released or mouse pressed event handlers. This function is not appropriate for invoking on the property change event.

Also, the mouse motions that invoke the popup menu are dependent on the operating system and may behave differently depending on which button you press on the mouse. Because of the different popup-trigger settings on different operating systems, the example code may behave differently on a Linux or a Mac. The way around this is to do the same code in both the mousePressed and mouseReleased events. In order to avoid code duplication, consider placing the code in a custom method.

Example #1

# This first example is a very basic to demonstrate the fundamentals of making a popup menu. Put the following script in the mouseReleased event of a component. 
# This will only work on Windows - continue on for cross-platform instructions.
# Right click on the component to see the resulting pop-up menu that is created with this code.
  
def sayHello(event):
   system.gui.messageBox("Hello World")
menu = system.gui.createPopupMenu(["Click Me"], [sayHello])
menu.show(event)

Example #2

# The following code demonstrates how to edit a component's custom property after you right clicked the component.
# This code makes use of functions in order to edit the components custom properties.
# The following code should be located in the mouse released event handler.
# Also, there must be custom properties present on the component in order to handle these functions.
# For example, there must be a custom property called 'DatabaseProvider' that takes a string.
if event.button != event.BUTTON1:
    def editDatabaseProvider(event):
        result = system.gui.inputBox("Database Provider",event.source.parent.DatabaseProvider)
        event.source.parent.DatabaseProvider = result
 
    def editTable(event):
        result = system.gui.inputBox("Table Name",event.source.parent.Table)
        event.source.parent.Table = result
 
    def editColumn(event):
        result = system.gui.inputBox("Column Name",event.source.parent.Column)
        event.source.parent.Column = result
 
    def editKeyColumn(event):
        result = system.gui.inputBox("Key Column Name",event.source.parent.KeyColumn)
        event.source.parent.KeyColumn = result
 
    names = ["Edit DB Provider", "Edit Table Name", "Edit Column Name", "Edit Key Column"]
    functions = [editDatabaseProvider, editTable, editColumn, editKeyColumn]
    menu = system.gui.createPopupMenu(names, functions)
    menu.show(event)

Example #3

# This example shows a nested popup menu, with menus within menus.  All menu items call sayHello().
def sayHello(event):
   system.gui.messageBox("Hello World")
subMenu = [["Click Me 2", "Click Me 3"], [sayHello, sayHello]]
menu = system.gui.createPopupMenu(["Click Me", "SubMenu"], [sayHello, subMenu])
menu.show(event)