Selecting Items in Microsoft PropertyGrid

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

One of the actions that you will perform the most over a PropertyGrid control is selecting its items. This topic describes several approaches that can be used to select a particular item in the PropertyGrid control:

To perform these actions, TestComplete should have access to internal objects, properties and methods of the PropertyGrid control. For this purpose, the .NET Application Support and Microsoft Control Support plugins must be installed and enabled.

When testing Microsoft PropertyGrid controls, use specific methods and properties of the corresponding MicrosoftPropertyGrid object. You can call these methods and properties from your keyword tests, as well as from scripts. This topic describes how to work with an object’s properties and methods from your scripts. However, when testing a PropertyGrid 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.

Simulating Item Clicks

To simulate clicks on PropertyGrid items, you can use the ClickLabel and ClickValue actions of the MicrosoftPropertyGrid or PropertyGridItemGroup objects, and a variety of these actions for right- and double-clicks. All of these mouse actions have parameters that specifiy the item to be clicked and the key or a combination of keys (Ctrl, Alt, Shift) to be pressed during the click event.

Below is an example that demonstrates how you can simulate clicks on PropertyGrid items:

JavaScript, JScript

function Main()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys.Process ("PropertyGridSample");
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1");

  // Click some items
  Grid.wItems["Appearance"].ClickLabel("Font");
  Grid.wItems["Appearance"].ClickValue("Text");
}

Python

def Main():

  # Obtain the grid object
  p = Sys.Process ("PropertyGridSample")
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1")

  # Click some items
  Grid.wItems["Appearance"].ClickLabel("Font")
  Grid.wItems["Appearance"].ClickValue("Text")

VBScript

Sub Main
  Dim p, Grid

  ' Obtain the grid object
  Set p = Sys.Process ("PropertyGridSample")
  Set Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1")

  ' Click some items
  Grid.wItems("Appearance").ClickLabel("Font")
  Grid.wItems("Appearance").ClickValue("Text")
End Sub

DelphiScript

procedure Main;
var p, Grid : OleVariant;
begin
  // Obtain the grid object
  p := Sys.Process ('PropertyGridSample');
  Grid := p.WinFormsObject('Form1').WinFormsObject('propertyGrid1');

  // Click some items
  Grid.wItems('Appearance').ClickLabel('Font');
  Grid.wItems('Appearance').ClickValue('Text');
end;

C++Script, C#Script

function Main()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys["Process"]("PropertyGridSample");
  Grid = p["WinFormsObject"]("Form1")["WinFormsObject"]("propertyGrid1");

  // Click some items
  Grid["wItems"]("Appearance")["ClickLabel"]("Font");
  Grid["wItems"]("Appearance")["ClickValue"]("Text");
}

You can refer to a nested item in the PropertyGrid control via its parent items. In certain cases, however, you may find it more convenient to address items directly via the grid object by using their full labels, for instance, “Appearance.Font.Name”. The ClickItem routine from the following example demonstrates how you can do this:

Example

View description

JavaScript, JScript

function Main()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys.Process ("PropertyGridSample");
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1");

  // Click some items
  ClickItem (Grid, "Appearance.Font");
  ClickItem (Grid, "Appearance.Text");
}

// Selects an item specified by its full label
function ClickItem (Grid, FullLabel)
{
  var ItemGroup, Labels, i;

  // Split the full label into parts
  Labels = FullLabel.split (".");

  // Walk down the items hierarchy
  ItemGroup = Grid;
  for (i=0; i<Labels.length-1; i++)
    ItemGroup = ItemGroup.wItems(Labels[i]);

  ItemGroup.ClickValue(Labels[i]);
}

Python

def Main():

  # Obtain the grid object
  p = Sys.Process ("PropertyGridSample")
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1")

  # Click some items
  ClickItem (Grid, "Appearance.Font")
  ClickItem (Grid, "Appearance.Text")

# Selects an item specified by its full label
def ClickItem (Grid, FullLabel):

  # Split the full label into parts
  Labels = FullLabel.split (".")

  # Walk down the items hierarchy
  ItemGroup = Grid
  for i in range(0,Labels.length-1):
    ItemGroup = ItemGroup.wItems[Labels[i]]

  ItemGroup.ClickValue(Labels[i])

VBScript

Sub Main
  Dim p, Grid

  ' Obtain the grid object
  Set p = Sys.Process ("PropertyGridSample")
  Set Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1")

  ' Click some items
  Call ClickItem (Grid, "Appearance.Font")
  Call ClickItem (Grid, "Appearance.Text")
End Sub

' Selects an item specified by its full label
Sub ClickItem (Grid, FullLabel)
  Dim ItemGroup, Labels, i

  ' Split the full label into parts
  Labels = Split (FullLabel, ".")

  ' Access and select the item via its parent items
  Set ItemGroup = Grid
  For i = 0 To UBound(Labels)-1
    Set ItemGroup = ItemGroup.wItems(Labels(i))
  Next

  ItemGroup.ClickValue(Labels(i))
End Sub

DelphiScript

// Selects an item specified by its full label
procedure ClickItem (Grid, FullLabel);
var ItemGroup, nLabels, i : OleVariant;
begin
  // Split the full label into parts
  aqString.ListSeparator := '.';
  nLabels := aqString.GetListLength (FullLabel);

  // Access and select the item via its parent items
  ItemGroup := Grid;
  for i := 0 to nLabels-2 do
    ItemGroup := ItemGroup.wItems[ aqString.GetListItem(FullLabel, i) ];

  ItemGroup.ClickValue( aqString.GetListItem(FullLabel, i) );
end;

procedure Main;
var p, Grid : OleVariant;
begin
  // Obtain the grid object
  p := Sys.Process ('PropertyGridSample');
  Grid := p.WinFormsObject('Form1').WinFormsObject('propertyGrid1');

  // Click some items
  ClickItem (Grid, 'Appearance.Font');
  ClickItem (Grid, 'Appearance.Text');
end;

C++Script, C#Script

function Main()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys["Process"]("PropertyGridSample");
  Grid = p["WinFormsObject"]("Form1")["WinFormsObject"]("propertyGrid1");

  // Click some items
  ClickItem (Grid, "Appearance.Font");
  ClickItem (Grid, "Appearance.Text");
}

// Selects an item specified by its full label
function ClickItem (Grid, FullLabel)
{
  var ItemGroup, Labels, i;

  // Split the full label into parts
  Labels = FullLabel["split"](".");

  // Walk down the items hierarchy
  ItemGroup = Grid;
  for (i=0; i<Labels["length"]-1; i++)
    ItemGroup = ItemGroup["wItems"](Labels[i]);

  ItemGroup["ClickValue"](Labels[i]);
}

Simulating Keyboard Shortcuts

You can navigate through the PropertyGrid using special keyboard shortcuts. For example, the Home and End keys move the focus to the first and the last item, respectively; the Down Arrow and Up Arrow keys select the next and the previous items, and so on. To simulate the shortcuts, use the Keys action added to all onscreen objects by TestComplete:

JavaScript, JScript

// Navigate to the upper item
Grid.Keys("[Home]")

Python

# Navigate to the upper item
Grid.Keys("[Home]")

VBScript

' Navigate to the upper item
Grid.Keys("[Home]")

DelphiScript

// Navigate to the upper item
Grid.Keys('[Home]')

C++Script, C#Script

// Navigate to the upper item
Grid["Keys"]("[Home]")

Using the PropertyGrid.SelectedGridItem Property

It is possible to select a particular item in the PropertyGrid control using its native properties and methods. The PropertyGrid control has the SelectedGridItem property that lets you obtain the selected item or directly specify it. This property can be used to select items that are currently visible in the grid as well as those that are currently out of the grid view. In this case, the grid is scrolled so that the selected item becomes visible. However, if you use this property to select a hidden item, that is the item whose parent item is collapsed, the exception will occur.

Below is an example that illustrates how you can select a grid item using the SelectedGridItem property.

Example

View description

JavaScript

function Main ()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys.Process ("PropertyGridSample");
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1");

  // Select the "Appearance.Font" item
  SelectItem (Grid, "Appearance.Font");
}

// Selects the item specified by its full label
function SelectItem (Grid, FullLabel)
{
  Grid.SelectedGridItem = GetItem (Grid, FullLabel);
}

// Returns the grid item specified by its full label
function GetItem (Grid, FullLabel)
{
  var Labels, Coll, Item;

  // Split the full label into parts
  Labels = FullLabel.split (".");

  // Get the top-level grid items
  Coll = Grid.GetPropEntries();

  // Walk down the hierarchy of items
  for (let i=0; i<Labels.length; i++)
  {
    // Obtain the item by its label
    Item = Coll.Item_2 (Labels[i]);
    if (strictEqual(Item, null))
      return null; // The item with the specified label is not found
    // Get child items of the current item
    Coll = Item.GridItems;
  }
  return Item;
}

JScript

function Main ()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys.Process ("PropertyGridSample");
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1");

  // Select the "Appearance.Font" item
  SelectItem (Grid, "Appearance.Font");
}

// Selects the item specified by its full label
function SelectItem (Grid, FullLabel)
{
  Grid.SelectedGridItem = GetItem (Grid, FullLabel);
}

// Returns the grid item specified by its full label
function GetItem (Grid, FullLabel)
{
  var Labels, Coll, Item, i;

  // Split the full label into parts
  Labels = FullLabel.split (".");

  // Get the top-level grid items
  Coll = Grid.GetPropEntries();

  // Walk down the hierarchy of items
  for (i=0; i<Labels.length; i++)
  {
    // Obtain the item by its label
    Item = Coll.Item_2 (Labels[i]);
    if (Item == null)
      return null; // The item with the specified label is not found
    // Get child items of the current item
    Coll = Item.GridItems;
  }
  return Item;
}

Python

def Main ():

  # Obtain the grid object
  p = Sys.Process ("PropertyGridSample")
  Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1")

  # Select the "Appearance.Font" item
  SelectItem (Grid, "Appearance.Font")

# Selects the item specified by its full label
def SelectItem (Grid, FullLabel):
  Grid.SelectedGridItem = GetItem (Grid, FullLabel)

# Returns the grid item specified by its full label
def GetItem (Grid, FullLabel):

  # Split the full label into parts
  Labels = FullLabel.split (".")

  # Get the top-level grid items
  Coll = Grid.GetPropEntries()

  # Walk down the hierarchy of items
  for i in range(0, Labels.length-1):
    # Obtain the item by its label
    Item = Coll.Item_2 [Labels[i]]
    if (Item == None):
      return None # The item with the specified label is not found
    # Get child items of the current item
    Coll = Item.GridItems
  return Item

VBScript

Sub Main
  Dim p, Grid

  ' Obtain the grid object
  Set p = Sys.Process ("PropertyGridSample")
  Set Grid = p.WinFormsObject("Form1").WinFormsObject("propertyGrid1")

  ' Select the "Appearance.Font" item
  Call SelectItem (Grid, "Appearance.Font")
End Sub

' Selects the item specified by its full label
Sub SelectItem (Grid, FullLabel)
  Set Grid.SelectedGridItem = GetItem (Grid, FullLabel)
End Sub

' Returns the grid item specified by its full label
Function GetItem (Grid, FullLabel)
  Dim Labels, Coll, Item, i

  ' Split the full label into parts
  Labels = Split (FullLabel, ".")

  ' Get the top-level grid items
  Set Coll = Grid.GetPropEntries

  ' Walk down the hierarchy of items
  For i=0 To UBound(Labels)
    ' Obtain the item by its label
    Set Item = Coll.Item_2 (Labels(i))
    If Item Is Nothing Then
      Set GetItem = Nothing ' The item with the specified label is not found
      Exit Function
    End If
    ' Get child items of the current item
    Set Coll = Item.GridItems
  Next
  Set GetItem = Item
End Function

DelphiScript

procedure SelectItem (Grid, FullLabel); forward;
function GetItem (Grid, FullLabel); forward;

procedure Main;
var p, Grid : OleVariant;
begin
  // Obtain the grid object
  p := Sys.Process ('PropertyGridSample');
  Grid := p.WinFormsObject('Form1').WinFormsObject('propertyGrid1');

  // Select the 'Appearance.Font' item
  SelectItem (Grid, 'Appearance.Font');
end;

// Selects the item specified by its full label
procedure SelectItem (Grid, FullLabel);
begin
  Grid.SelectedGridItem := GetItem (Grid, FullLabel);
end;

// Returns the grid item specified by its full label
function GetItem (Grid, FullLabel);
var nLabels, Coll, Item, i : OleVariant;
begin
  // Get the top-level grid items
  Coll := Grid.GetPropEntries;

  // Walk down the hierarchy of items
  aqString.ListSeparator := '.';
  nLabels := aqString.GetListLength (FullLabel);
  for i:=0 to nLabels-1 do
  begin
    // Obtain the item by its label
    Item := Coll.Item_2 (aqString.GetListItem (FullLabel, i));
    if Item = nil then
      Result := nil; // The item with the specified label is not found
    // Get child items of the current item
    Coll := Item.GridItems;
  end;
  Result := Item;
end;

C++Script, C#Script

function Main ()
{
  var p, Grid;

  // Obtain the grid object
  p = Sys["Process"]("PropertyGridSample");
  Grid = p["WinFormsObject"]("Form1")["WinFormsObject"]("propertyGrid1");

  // Select the "Appearance.Font" item
  SelectItem (Grid, "Appearance.Font");
}

// Selects the item specified by its full label
function SelectItem (Grid, FullLabel)
{
  Grid["SelectedGridItem"] = GetItem (Grid, FullLabel);
}

// Returns the grid item specified by its full label
function GetItem (Grid, FullLabel)
{
  var Labels, Coll, Item, i;

  // Split the full label into parts
  Labels = FullLabel["split"](".");

  // Get the top-level grid items
  Coll = Grid["GetPropEntries"]();

  // Walk down the hierarchy of items
  for (i=0; i<Labels["length"]; i++)
  {
    // Obtain the item by its label
    Item = Coll["Item_2"](Labels[i]);
    if (Item == null)
      return null; // The item with the specified label is not found
    // Get child items of the current item
    Coll = Item["GridItems"];
  }
  return Item;
}

See Also

Working With Microsoft PropertyGrid
Getting the Focused Item in Microsoft PropertyGrid
Obtaining and Setting Item Values in Microsoft PropertyGrid
Working With In-place Editors in Microsoft PropertyGrid
ClickLabel Action (Specific to PropertyGrid Controls)
ClickValue Action (Specific to PropertyGrid Controls)

Highlight search results