Working With Toolbars and Navigation Bars - Basic Concepts

Applies to TestComplete 15.47, last modified on January 20, 2023

General Notes

TestComplete can recognize toolbar and navigation bar controls of iOS Open Applications. It allows you to simulate actions on a toolbar or navigation bar using its methods and properties. You can work with these controls using similar methods.

Specifics of Working With Toolbars and Navigation Bars

TestComplete supports any controls located on a toolbar or navigation bar. To work with these controls, you should use different methods and properties. For example, the SwitchItem action sets the state of a switch control, but cannot be used to touch a button.

In order to call methods and properties of toolbar or navigation bar items (buttons, switches and so on), you need to find them in the Object Browser. To learn how to do this, see Addressing Objects in iOS Applications (Legacy).

Addressing Items

The section below describes how to specify toolbar or navigation bar items in your tests:

Using Item Indexes and Names

It is possible to specify an item by its name or index. In most cases, you specify an item by its name in the following way:

toolbarObj.TouchItem("Item1")    // Touch an item

The sample script below simulates a touch on the "Item" item and a long touch on the "BarBtn" item of an application’s toolbar.

JavaScript, JScript

function Test()
{
  // Select the mobile device
  Mobile.SetCurrent("iPhone");
  // Obtain the Toolbar object
  var p = Mobile.Device().Process("SampleApp");
  var toolbar = p.Window().Toolbar();
  
  // Touch the "Item" item
  toolbar.TouchItem("Item");
  
  // Long touch the "BarBtn" item
  toolbar.LongTouchItem("BarBtn");
}

Python

def Test():
  # Select the mobile device
  Mobile.SetCurrent("iPhone")
  # Obtain the Toolbar object 
  p = Mobile.Device().Process("SampleApp")
  toolbar = p.Window().Toolbar()
  
  # Touch the "Item" item
  toolbar.TouchItem("Item")
  
  # Long touch the "BarBtn" item
  toolbar.LongTouchItem("BarBtn")

VBScript

Sub Test()
  Dim p, toolbar
  ' Select the mobile device
  Mobile.SetCurrent("iPhone")
  ' Obtain the Toolbar object
  Set p = Mobile.Device.Process("SampleApp")
  Set toolbar = p.Window(0).Toolbar()
  
  ' Touch the "Item" item
  toolbar.TouchItem("Item")
  
  ' Long touch the "BarBtn" item
  toolbar.LongTouchItem("BarBtn")
End Sub 

DelphiScript

procedure Test();
var
  p, toolbar;
begin
  // Select the mobile device
  Mobile.SetCurrent('iPhone');
  // Obtain the Toolbar object
  p := Mobile.Device.Process('SampleApp');
  toolbar := p.Window(0).Toolbar(0);
  
  // Touch the "Item" item
  toolbar.TouchItem('Item');
  
  // Long touch the "BarBtn" item
  toolbar.LongTouchItem('BarBtn');
end;

C++Script, C#Script

function Test()
{
  // Select the mobile device
  Mobile["SetCurrent"]("iPhone");
  // Obtain the Toolbar object
  var p = Mobile["Device"].Process("SampleApp");
  var toolbar = p["Window"]()["Toolbar"]();

  // Touch the "Item" item
  toolbar["TouchItem"]("Item");

  // Long touch the "BarBtn" item
  toolbar["LongTouchItem"]("BatBtn");
}

If the toolbar or navigation bar does not display the text of items, you can find it using the properties of the iOS ToolBar or iOS NavigationBar object. Use the wItemText property to obtain the name of an item.

If an item does not have a name, you can specify it using its index (in other words, its position). Indexes are zero-based: the first item of each group of the toolbar has index 0, the second - 1, and so on. The total number of items is specified by the wItemCount property. The last item has index wItemCount - 1. To obtain the total number of items, you can use the wItemCount property. In this case, the last item will have index wItemCount - 1. For instance, the script below simulates a touch on the fifth item and a long touch the second item:

JavaScript, JScript

function Test()
{
  // Select the mobile device
  Mobile.SetCurrent("iPhone");
  // Obtain the Toolbar object
  var p = Mobile.Device().Process("SampleApp");
  var toolbar = p.Window().Toolbar();
  
  // Touch the fifth item
  toolbar.TouchItem(4);
  
  // Long touch the second item
  toolbar.LongTouchItem(1);
}

Python

def Test():
  # Select the mobile device
  Mobile.SetCurrent("iPhone")
  # Obtain the Toolbar object 
  p = Mobile.Device().Process("SampleApp")
  toolbar = p.Window().Toolbar()
  
  # Touch the fifth item
  toolbar.TouchItem(4)
  
  # Long touch the second item
  toolbar.LongTouchItem(1)

VBScript

Sub Test()
  Dim p, toolbar
  ' Select the mobile device
  Mobile.SetCurrent("iPhone")
  ' Obtain the Toolbar object
  Set p = Mobile.Device.Process("SampleApp")
  Set toolbar = p.Window(0).Toolbar()
  
  ' Touch the fifth item
  toolbar.TouchItem(4)
  
  ' Long touch the second item
  toolbar.LongTouchItem(1)
End Sub 

DelphiScript

procedure Test();
var
  p, toolbar;
begin
  // Select the mobile device
  Mobile.SetCurrent('iPhone');
  // Obtain the Toolbar object
  p := Mobile.Device.Process('SampleApp');
  toolbar := p.Window(0).Toolbar(0);
  
  // Touch the fifth item
  toolbar.TouchItem(4);
  
  // Long touch the second item
  toolbar.LongTouchItem(1);
end;

C++Script, C#Script

function Test()
{
  // Select the mobile device
  Mobile["SetCurrent"]("iPhone");
  // Obtain the Toolbar object
  var p = Mobile["Device"].Process("SampleApp");
  var toolbar = p["Window"]()["Toolbar"]();

  // Touch the fifth item
  toolbar["TouchItem"](4);

  // Long touch the second item
  toolbar["LongTouchItem"](1);
}

Using Case-Sensitive and Case-Insensitive Item Captions

Depending on the Use case-sensitive parameters project option, TestComplete treats items' titles as case-sensitive or case-insensitive. By default, this option is turned off, so you can specify an item title using in any case:

toolbarObj.TouchItem("Item1")

toolbarObj.TouchItem("ITEM1")

toolbarObj.TouchItem("item1")

toolbarObj.TouchItem("ItEm1")

If the Use case-sensitive parameters option is checked, you can specify item titles using the appropriate case:

toolbarObj.TouchItem("Item1")  // Correct

toolbarObj.TouchItem("item1")  // Incorrect!!!

Using Wildcards and Regular Expressions in Items Captions

If item titles are variable, that is, they may change depending on the current application context, it is useful to specify items only by the constant parts of their names. To specify variable parts in item names, you can use wildcard characters (* and ?) or regular expressions. The asterisk (*) corresponds to a string of any length (including an empty string), the question mark corresponds to any single character (including none). To specify more complicated parts of a caption, use regular expressions.

For example, your tested application’s toolbar contains the Undo item whose title depends on the undo buffer: if there is an action to undo, the item's title contains the Undo word and the action name (for example, Undo Typing or Undo Paste); if there are no actions to undo, the item's title is Can't Undo. In order to ensure stable recognition of the Undo menu item whatever name it has, you can replace the variable part of the name with the * wildcard:

toolbarObj.TouchItem("*Undo*")

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

Getting a Navigation Bar's Title

A navigation bar may have its own title. The title is placed in the middle of the control and has different formatting. For example, "Orders" is a title in the image below.

NavigationBar title

You can get the title of a navigation bar by using the wText property.

JavaScript, JScript

function Test()
{
  // Select the mobile device
  Mobile.SetCurrent("iPhone");
  // Obtain the NavigationBar object
  var p = Mobile.Device().Process("SampleApp");
  var navbar = p.Window().NavigationBar();
  
  // Post the title to the log
  Log.Message("The navigation bar title is: " + navbar.wText);
}

Python

def Test():
  # Select the mobile device
  Mobile.SetCurrent("iPhone")
  # Obtain the NavigationBar object 
  p = Mobile.Device().Process("SampleApp")
  navbar = p.Window().NavigationBar()
  
  # Post the title to the log
  Log.Message("The navigation bar title is: " + navbar.wText)

VBScript

Sub Test()
  Dim p, navbar
  ' Select the mobile device
  Mobile.SetCurrent("iPhone")
  ' Obtain the NavigationBar object
  Set p = Mobile.Device.Process("SampleApp")
  Set navbar = p.Window(0).NavigationBat()
  
  ' Post the title to the log
  Log.Message("The navigation bar title is: " + navbar.wText)
End Sub 

DelphiScript

procedure Test();
var
  p, navbar;
begin
  // Select the mobile device
  Mobile.SetCurrent('iPhone');
  // Obtain the NavigationBar object
  p := Mobile.Device.Process('SampleApp');
  navbar := p.Window(0).NavigationBar(0);
  
  // Post the title to the log
  Log.Message('The navigation bar title is: ' + navbar.wText);
end;

C++Script, C#Script

function Test()
{
  // Select the mobile device
  Mobile["SetCurrent"]("iPhone");
  // Obtain the NavigationBar object
  var p = Mobile["Device"].Process("SampleApp");
  var navbar = p["Window"]()["NavigationBar"]();
  
  // Post the title to the log
  Log["Message"]("The navigation bar title is: " + navbar["wText"]);
}

See Also

Working With iOS Toolbar and Navigation Bar Controls
iOS Toolbar Support
iOS NavigationBar Support

Highlight search results