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:

1. Double-click the menu item.

   or

   Select Script from the menu item’s popup 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 dropdown or cascading menu. For example, the
  script for the Clicked event for the Open menu item on the File
  menu will open a file.
• Help You may
  want to provide Help on a menu item when a user presses the f1 key
  or clicks the context Help button [?] on the title
  bar of the window with which the menu is associated and then points
  and clicks on a menu item.
• Selected You will probably
  use few Selected scripts since users don’t expect things
  to happen when they simply highlight a menu item. (One possible
  use of Selected scripts, though, is to change MicroHelp displayed in
  an MDI application as the user scrolls through a menu.)

About
the Clicked event

When it is triggered The Clicked event is triggered whenever:

• The menu item is clicked
  with the mouse
• The menu item is selected (highlighted) using the
  keyboard and then enter is pressed
• The shortcut key for the menu item is pressed
• The menu containing the menu item is displayed and
  the accelerator key is pressed
• A popup menu displays

Whether a menu item responds A menu item responds to a mouse click or the keyboard only
if both its Visible and Enabled properties are TRUE.

When its script is executed If the menu item has a dropdown or cascading menu under it,
the script for its Clicked event (if any) is executed when the mouse
button is pressed, and then the dropdown 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 Clicked event to specify menu item properties When the user clicks an item on the menu bar to display a
dropdown menu, the Clicked event for the menu item on the menu bar
is triggered and then the dropdown menu is displayed.

You can use the menu bar’s Clicked event to specify
the properties of the menu items in the dropdown menu. For example,
if you want to disable items in a dropdown 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
during execution. For example, to hide a menu, you can use the Hide
built-in 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 popup menu.

For more information, see Chapter 5, “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 also 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 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
can do this by displaying the Structure List view and then selecting
Add from the popup menu.

For more information, see Chapter 7, “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:

For example, to move the window w_cust from within
a menu item script, code:

To minimize w_cust, code:

Using ParentWindow

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

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:

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

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:

For example, to enable a CommandButton in window w_cust
from a menu item script, code:

Referring
to menu items

When referring to a menu item, use this syntax:

Reference within the same menu When referring to a menu item within the same menu, you don’t
have to qualify the reference with the menu name.

When referring to a menu item in a dropdown 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 checkmark next to the menu item m_bold,
which is on a dropdown menu under m_text in the menu saved
in the library as m_menu, code:

If the above script were for a menu item in the same menu
(m_menu), you wouldn’t need to qualify the menu
item with the name of the menu. You could simply code:

---