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 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.
• When 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 F1or 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 Chapter 8, “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 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 Chapter 10, “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, this statement moves the window w_cust from
within a menu item script:

This statement minimizes w_cust:

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:

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, this statement enables a CommandButton in window w_cust from a
menu item script:

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 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:

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:

---