Writing scripts for menu items

You write scripts for menu items in the Script view. The scripts specify what happens when users select a menu item.

To write a script for a menu item:

  • Double-click the menu item or select Script from the menu item's pop-up menu.

    The Script view displays for the clicked event, which is the default event for a menu item.

Menu item events

Menu items have the following events:

  • Clicked

    Typically, your application will contain Clicked scripts for each menu item in a drop-down or cascading menu. For example, the script for the Clicked event for the Open menu item on the File menu opens a file.

  • Help

    You can provide Help on a menu item when a user presses the F1 key, or when the user clicks the context Help button [?] on the title bar of the window with which the menu is associated, and then clicks on a menu item.

  • Selected

    You will probably use few Selected scripts since users do not expect things to happen when they simply highlight a menu item. One use of Selected scripts is to change MicroHelp displayed in an MDI application as the user scrolls through a menu.

About the Clicked event

The Clicked event is triggered whenever:

  • The user clicks the menu item

  • The user selects (highlights) the menu item using the keyboard and then presses ENTER

  • The user presses the shortcut key for the menu item

  • The menu containing the menu item is displayed and the user presses the accelerator key Alt+key

  • A script executes the PopMenu function and displays a pop-up menu

  • A menu item responds to a mouse-click or the keyboard only if both its Visible and Enabled properties are set to "true".

  • If the menu item has a drop-down or cascading menu under it, the script for its Clicked event (if any) is executed when the mouse button is pressed, and then the drop-down or cascading menu displays. If the menu item does not have a menu under it, the script for the Clicked event is executed when the mouse button is released.

Using the Clicked event to specify menu item properties

When the user clicks an item on the menu bar to display a drop-down menu, the Clicked event for the menu item on the menu bar is triggered and then the drop-down menu is displayed.

You can use the menu bar's Clicked event to specify the properties of the menu items in the drop-down menu. For example, if you want to disable items in a drop-down menu, you can disable them in the script for the Clicked event for the menu item in the menu bar.

About the Help event

The Help event is triggered when the user presses F1 or clicks the context Help button [?] on a window's title bar and then points and clicks on a menu item.

About the Selected event

The Selected event is triggered when the user selects a menu item.

Using functions and variables

You can use functions and variables in your scripts.

Using functions

PowerBuilder provides built-in functions that act on menu items. You can use these functions in scripts to manipulate menu items at runtime. For example, to hide a menu, you can use the built-in Hide function.

For a complete list of the menu-level built-in functions, look at the Function List view or use the Browser.

Defining menu-level functions

You can define your own menu-level functions to make it easier to manipulate your menus. One way you can do this is in the Function List view, by selecting Add from the pop-up menu.

For more information, see Working with User-Defined Functions.

Using variables

Scripts for menu items have access to all global variables declared for the application. You can also declare local variables, which are accessible only in the script where they are declared.

You can declare instance variables for the menu when you have data that needs to be accessible to scripts in several menu items in a menu. Instance variables are accessible to all menu items in the menu.

For a complete description of variables and how to declare them, see the the section called “Declaring variables” in PowerScript Reference.

Defining menu-level structures

If you need to manipulate a collection of related variables, you can define menu-level structures using the Structure view. You do this by displaying the Structure List view and then selecting Add from the pop-up menu. The Structure and Structure List views are not part of the default layout.

For more information, see Working with Structures.

Referring to objects in your application

You can refer to any object in the application in scripts for menu items. You must fully qualify the reference, using the object name, as follows.

Referring to windows

When referring to a window, you simply name the window. When referring to a property in a window, you must always qualify the property with the window's name:

window.property

For example, this statement moves the window w_cust from within a menu item script:

w_cust.Move(300, 300)

This statement minimizes w_cust:

w_cust.WindowState = Minimized!

You can use the reserved word ParentWindow to refer to the window that the menu is associated with at runtime. For example, the following statement closes the window the menu is associated with:

Close(ParentWindow)

You can also use ParentWindow to refer to properties of the window a menu is associated with, but not to refer to properties of controls or user objects in the window.

For example, the following statement is valid, because it refers to properties of the window itself:

ParentWindow.Height = ParentWindow.Height/2

But the following statement is invalid, because it refers to a control in the window:

ParentWindow.sle_result.Text = "Statement invalid"

Referring to controls and user objects in windows

When referring to a control or user object, you must always qualify the control or user object with the name of the window:

window.control.property
window.userobject.property

For example, this statement enables a CommandButton in window w_cust from a menu item script:

w_cust.cb_print.Enabled = TRUE

Referring to menu items

When referring to a menu item, use this syntax:

menu.menu item
menu.menu item.property

Reference within the same menu

When referring to a menu item within the same menu, you do not have to qualify the reference with the menu name.

When referring to a menu item in a drop-down or cascading menu, you must specify each menu item on the path to the menu item you are referencing, separating the names with periods.

For example, to place a check mark next to the menu item m_bold, which is on a drop-down menu under m_text in the menu saved in the library as m_menu, use this statement:

m_menu.m_text.m_bold.Check( )

If the previous script is for a menu item in the same menu (m_menu), you do not need to qualify the menu item with the name of the menu:

m_text.m_bold.Check( )