Addressing Menu Items in Desktop Windows Applications

While testing menu controls, you can use specific properties and methods of the corresponding program object to perform certain actions and obtain data stored in controls. You can call these methods and properties from your keyword tests, as well as from scripts. This topic describes how to work with the needed properties and methods from your scripts. However, when testing a control from your keyword test, you can use the same methods and properties calling them from keyword test operations. For more information, see Keyword Tests Basic Operations.

To work with menu controls, TestComplete uses the Menu program object. Methods and properties of this object let you simulate various actions over menu items as well as access individual items and check their properties. This topic explains how you can address menu items you are going to work with:

Using Item Names and Indexes

Specifying Items in the Menu Object Methods

When you use the Menu object methods to simulate actions over menu items, you should specify the “full path” to the desired menu or submenu item. Each item in the path can be specified by its name or index; different items should be separated by the pipeline character ( | ). Note that any other delimiter characters except the pipeline character (for example, additional spaces) are not allowed:

When specifying a menu item by name, keep in mind the following:

• The item name should not include the special character that is used to create an access key for that item - in Windows applications it is usually an ampersand (&), in WPF applications - an underscore (_). Typically, only the first ampersand or underscore character in the item name is treated as a special character; all other ampersands and underscores are treated as ordinary characters.

  For example, suppose that the main menu in a Windows application contains the Look & Feel item, whose access key is L and internal name is “&Look & Feel”. In tests, you should address this menu item as “Look & Feel” rather than “&Look & Feel”:

  w.MainMenu.Click("Look & Feel|Flat")   // Correct

  w.MainMenu.Click("&Look & Feel|Flat")  // Incorrect!!!

• The item name should include the ending ellipsis (which is usually added to illustrate that the item calls a special dialog). For example:

  w.MainMenu.Click("File|Open...")  // Correct

  w.MainMenu.Click("File|Open")     // Incorrect!!!

  If you are not sure whether the item name contains ellipsis or not, explore the tested application or use the * wildcard after the item name instead of the ellipsis (for more information on using wildcards, see below).
• Item names should not include the keyboard shortcut that is typically displayed on the right of the item name (unless it is a part of menu item name):

  w.MainMenu.Click("Edit|Copy")         // Correct

  w.MainMenu.Click("Edit|Copy Ctrl+C")  // Incorrect!!!

• If the item caption contains a special character (|, [ or ]), you should address it using its index or question mark wildcards:

  treeObj.ClickItem("?Item1?") // Clicks the root item "[Item1]"

• If the item name contains the asterisk character (*), you should double it:

  w.MainMenu.Click("Window|1 Untitled **")

  Otherwise, it will be treaded as the wildcard (for more information on wildcards, see below).

If you specify an item by index (that is, position in the menu), you should enclose it in square brackets - [ and ]. At that, the brackets should contain only the index number; other symbols (such as spaces) are not allowed:

As you can see, indexes are zero-based, that is, the first item in the menu has the index 0, the second - 1, and so on; the index of the last menu item is Menu.Count-1. Note that separators are also counted as menu items and thus included in the items numeration.

Indexes are useful for addressing owner-drawn and bitmap items, since these items may not have a caption. See Working With Owner-Drawn and Bitmap Menus in Desktop Windows Applications for more information.

In the item path, you can combine both item names and indexes. For example, to click the File | Open... item in the main menu, you can use any of the following statements (assuming that the File menu is the first in the main menu and the Open item is the second in the File menu):

Specifying Items in the Menu.Items Property

You can use the Menu.Items property to obtain the MenuItem object that corresponds to a specific menu item. You can specify the desired item by its name or index:

Unlike the Menu object methods, where you specify the “full path’, the Items property lets you access items one by one. To obtain the item’s submenu, use the MenuItem.SubMenu property. You can then apply the Items property to the resulting Menu object in order to access the desired item in the submenu. You can specify the desired item or subitem by its name or index. For example, to obtain the caption of the File | Open... item in the main menu, you can use any of the following statements (assuming that the File menu is the first item in the main menu and the Open item is the second item in the File menu):

Using Case-Sensitive and Case-Insensitive Item Names

Depending on the Use case-sensitive parameters project option, TestComplete treats item names as case-sensitive or case-insensitive. By default, this option is turned off, so that you can specify the item name in any case (all upper case, all lower case, mixed case, and so on):

If the Use case-sensitive parameters is checked, you can specify menu items only by their actual names in the correct case:

Using Wildcards in Item Names

If menu item names change according to the current context, it may be useful to specify items only by constant parts of their names. To specify arbitrary parts in item names, TestComplete lets you use wildcard characters -- * and ?. The asterisk (*) corresponds to a string of any length (including an empty string), the question mark corresponds to any single character (including none).

To illustrate the wildcards usage, suppose that the Edit menu in the tested application contains the Undo command, whose name depends on the undo buffer: if there is an action to undo, the menu item name contains the Undo word and the action name (for example, Undo Typing or Undo Paste); if there are no actions to undo, the item name is Can't Undo. In order to ensure stable recognition of the Undo menu item whatever name it has, you can replace variable parts of its name with the * wildcard:

In this example, we place the wildcard on both sides of the Undo word, since it can either precede or follow other text.

See Also

Working With Menus in Desktop Windows Applications
Menu Object
MenuItem Object