Version

xamRibbon - Recordable Methods

Topic Overview

Purpose

This topic provides information about the xamRibbon™ control’s testable user recordable and replay-able methods.

XamRibbon Recordable Methods

OpenGroupDialog

Description

This action launches the DialogBoxLauncherTool of a RibbonGroup .

xamRibbon Recordable Methods Reference 1.png

Parameters

The following table explains the method’s parameter followed by code example.

Method parameter Description

oGroupId

Unique identifier of the ribbon group among other ribbon groups. This identifier is the group’s header.

If the group does not have a header or if the header is a duplicate, then the identifier will be the visible index of the group among other visible groups of the ribbon.

Example

Clicking the DialogBoxLauncherTool (outlined in the above screenshot) records the following script.

WpfWindow("Window1").XamRibbon("xamRibbon").OpenGroupDialog ARRAY("RibbonGroup", "Format", 0, "DialogBoxLauncherTool")

Possible exceptions

The following exceptions will result from not being able to locate the DialogBoxLauncherTool :

  • The oGroupId is null or missing

  • The index of the ribbon group (if present) is out of range of the total existing ribbon groups

  • The ribbon group (if present) does not match any of the headers of the existing ribbon groups

  • The ribbon group is removed, collapsed or hidden

  • The ribbon group does not have a DialogBoxLauncherTool or the DialogBoxLauncherTool is removed, collapsed or hidden in that group

SelectTab

Description

Clicking on the selected tab of the ribbon identified by its oTabId . Selecting a ContextualTabGroup the first tab in that group is always selected by default and hence recorded as a selection of the first tab (not the ContextualTabGroup ).

The following screenshot illustrates this concept. Selecting the ContextualTabGroup will, by default, record the first RibbonTab in the group instead.

xamRibbon Recordable Methods Reference 2.png

Parameters

The following table explains the method’s parameter followed by code example.

Method parameter Description

oTabId

This is a unique identifier for the Ribbon tabs representing the tab header.

If the tab does not have a header or if the header is duplicate, then the identifier will be the visible index of the tab among other visible tabs of the ribbon.

Example

Clicking the contextual tab called “Selection” (Illustrated in the above screenshot) records the first ribbon tab instead.

WpfWindow("Window1").XamRibbon("xamRibbon").SelectTab "Font Selection"

Possible exceptions

The following exceptions will result from not being able to locate the tab:

  • If the oTabId is null or missing

  • The tab index (if present) is out of range of the total existing tabs

  • The header (if present) does not match any of the headers of the existing tabs

  • The tab is removed, collapsed or hidden

PerformToolAction

Description

This method performs Click, SelectValue, SetValue, Activate, DropDown, CloseUp actions on an IRibbonTool located within an ApplicationMenu, QuickAccessToolbar or a RibbonGroup within the selected tab. DropDown ToolAction is a ReplayOnly action except for the ApplicationMenu and QuickCustomizeMenu drop down. CloseUp is a ReplayOnly action

Parameters

The following table explains the method’s parameter followed by code example.

Method parameter Description

oToolAction

This is an enumeration used to identify the type of action performed on a Ribbon tool.

The enumerated values are:

  • Click = 0

  • SelectValue = 1

  • SetValue–=2

  • Activate =3

  • DropDown = 4

  • CloseUp = 5

oToolPath

This is an array representing the entire tool path; helpful in identifying the tool.

The first parameter of the array is the location of the tool representing one of the following string values:

  • ApplicationMenuLeftArea

  • ApplicationMenuRecentItems

  • ApplicationMenuFooterToolbar

  • QuickAccessToolbar

  • QuickCustomizeMenu

  • RibbonGroup

  • ApplicationMenu (Used only with DropDown)

The intermediate parameters are the headers or visible indices of the root and intermediate tools; helpful in reaching the specific tool (last parameter).

The last parameter is the tool identifier which is the header of the tool, or its visible index (if the tool has no header or the header is a duplicate with another tool at the same level).

oToolValue

This is the new value of the editor based tool. Its value depends on the following conditions:

  1. If the tool is a Text editor base tool, it represents the value in the textbox of that tool.

  2. If the tool is a ComboEditor tool, it represents the selected item from the ComboBox dropDown.

  3. If the tool is a ToggleButton, it represents one of following values:

    • Check

    • Uncheck

    • Indeterminate

Example

Clicking on a ButtonTool with header “Copy” located in RibbonGroup with header “Group1” in a tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
Click, ARRAY("RibbonGroup", "Tab1", "Group1", "Copy")

Clicking on a RadioButtonTool with header “RadioButton” located in RibbonGroup with header “Group1” located in QuickAccessToolbar .

XamRibbon(RibbonName).PerformToolAction
Click, ARRAY("QuickAccessToolbar", "Group1", "RadioButton")

Clicking on a LabelTool with header “Label” located in RibbonGroup with header “Group1” located in ApplicationMenuRecentItems area.

XamRibbon(RibbonName).PerformToolAction
Click, ARRAY("ApplicationMenuRecentItems", "Group1", "Label")

Setting value as “Hello” on a TextEditorTool with header “Text editor” located in RibbonGroup with header “Group2” in a tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
SetValue, ARRAY("RibbonGroup", "Tab1", "Group2", "Text editor"), "Hello”

Setting value as “Hi” on a MaskedEditorTool with header “Masked editor” located in RibbonGroup with header “Group2” in a tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
SetValue, ARRAY("RibbonGroup", "Tab1", "Group2", "Masked editor"), "Hi”

Selecting value “One” from ComboEditorTool with header “Combo editor” located in RibbonGroup with header “Group2” in a tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
SelectValue, ARRAY("RibbonGroup", "Tab1", "Group2", "Combo editor"), "One"

Clicking to activate a GalleryItem with header “GalleryItem1” located in a MenuTool with header “GalleryTool” within a RibbonGroup with header “Group2” in a tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
Activate, ARRAY("RibbonGroup", "Tab1", "Group2", “GalleryTool”, "GalleryItem1")

Selecting a tool from GalleryItem with header “GalleryItem1” located in a MenuTool with header “GalleryTool” within a RibbonGroup with header “Group2” in a tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
SelectValue, ARRAY("RibbonGroup", "Tab1", "Group2", “GalleryTool”, "GalleryItem1")

Clicking on a GalleryItem with header “GalleryItem1” located in a MenuTool with header “GalleryTool” within a RibbonGroup with header “Group2” in Tab with header “Tab1”.

XamRibbon(RibbonName).PerformToolAction
Click, ARRAY("RibbonGroup", "Tab1", "Group2", “GalleryTool”, "GalleryItem1")

Clicking an ApplicationMenu button to open its DropDown menu.

XamRibbon(RibbonName).PerformToolAction
DropDown, “ApplicationMenu”

Clicking the QuickCustomizeMenu tool to open its DropDown menu.

XamRibbon(RibbonName).PerformToolAction
DropDown, “QuickCustomizeMenu”

Clicking the ButtonTool with header “Button” located in RibbonGroup with header “Group3” in a tab with header “Tab2” to open its DropDown menu.

XamRibbon(RibbonName).PerformToolAction
DropDown, ARRAY("RibbonGroup", "Tab2", "Group3", "Button")

Clicking the ButtonTool with header “ButtonDrop” located in ApplicationMenuLeftArea to open its DropDown menu.

XamRibbon(RibbonName).PerformToolAction
DropDown, ARRAY("ApplicationMenuLeftArea", "ButtonDrop")

Clicking the ButtonTool with header “Button” located in RibbonGroup with header “Group3” in a tab with header “Tab2” to close its DropDown menu.

XamRibbon(RibbonName).PerformToolAction
CloseUp, ARRAY("RibbonGroup", "Tab2", "Group3", "Button")

Clicking the ButtonTool with header “ButtonDrop” located in ApplicationMenuLeftArea to close its DropDown menu.

XamRibbon(RibbonName).PerformToolAction
CloseUp, ARRAY("ApplicationMenuLeftArea", "ButtonDrop")

Possible exceptions

The following exceptions will result from not being able to locate a tool:

  • Missing or null value for either the oToolAction or oToolPath

  • Entering an invalid path format for identifying the tool

  • Specifying an invalid oToolAction

  • Specifying an invalid oToolPath root location, invalid headers or indices that are out of range of the total existing tools at that level.

  • Removing, hiding or collapsing one or more tools in the oToolPath intermediate path

  • Missing or invalidating the oToolValue for that specific editor control, or changing the value is not allowed for the control

  • Performing SetValue or SelectValue on tools other than those allowed (such as TextEditorTool , ComboEditorTool or ToggleButtonTool )

ToggleAddToQAT

Description

This method records the right-click action on tools to be added or removed from the QAT.

Adding a tool to the QAT

xamRibbon Recordable Methods Reference 3.png

Removing a tool from the QAT

xamRibbon Recordable Methods Reference 4.png

Parameters

The following table explains the method’s parameter followed by code example.

Method parameter Description

oToolPath

This is an array representing the entire path; helpful in identifying the tool.

The first parameter of the array is the location of the tool representing one of the following string values:

  • QuickAccessToolbar

  • QuickCustomizeMenu

The intermediate parameters are the headers or visible indices of the root and intermediate tools, which help in reaching the specific tool (last parameter).

The last parameter is the tool identifier representing the tool’s header, or its visible index (if the tool has no header or the header is a duplicate with another tool at that level).

bAddToQAT

Boolean value, where True indicates that the tool will be added to QAT and false indicates that it will be removed from QAT.

Example

ButtonTool with header “Button” located in RibbonGroup with header “Group1” Located in QuickAccessToolba r:

ARRAY("QuickAccessToolbar", "Group1", "Button")

ToggleButtonTool with header “Toggle1” located in the QuickCustomizeMenu :

ARRAY("QuickCustomizeMenu", "Toggle1”)

Possible exceptions

The following exceptions will result from not being able to locate the tool:

  • The oToolPath is null or missing.

  • The oToolPath contains invalid headers or indices which are out of range of the total existing tools at that level.

  • One or more tools in the intermediate path of the oToolPath were removed, hidden or collapsed.

  • Attempting to remove a tool from QAT, while the tool is not in QAT

  • Attempting to remove a tool from QAT if the Add/Remove from QAT for that tool is not allowed or disabled if the tool is already added to QAT.

ToggleMinimizeRibbon

Description

This action toggles between minimizing and restoring of the ribbon control.

Minimizing the ribbon.

xamRibbon Recordable Methods Reference 5.png

Maximizing the ribbon.

xamRibbon Recordable Methods Reference 6.png

Parameters

The following table explains the method’s parameter followed by code example.

Method parameter Description

bMinimizeRibbon

Boolean value, with True indicating that the Ribbon will be minimized and false indicating that it will be maximized.

Attempting to use a script to maximize or minimize the ribbon, while the ribbon is already maximized or minimized, and results in the action being ignored.

Example

Selecting “Minimize the Ribbon” from QAT drop-down sets the ToggleMinimizeRibbon to True and records the following script:

WpfWindow("Window1").XamRibbon("xamRibbon").PerformToolAction DropDown, "QuickCustomizeMenu"
WpfWindow("Window1").XamRibbon("xamRibbon").ToggleMinimizeRibbon True

Possible exceptions

If minimizing the ribbon is not allowed and you try to minimize it anyway will result in throwing an exception stating the reason.

ToggleQATLocation

Description

This action toggles between placing the QuickAccessToolBar below or above the ribbon groups.

Choosing to show QuickAccessToolbar below the ribbon.

xamRibbon Recordable Methods Reference 7.png

Choosing to show QuickAccessToolbar above the ribbon.

xamRibbon Recordable Methods Reference 8.png

Example

Selecting “Show Below the Ribbon” from QAT drop-down sets the ToggleQATLocation to True and records the following script:

WpfWindow("Window1").XamRibbon("xamRibbon").PerformToolAction DropDown, "QuickCustomizeMenu"
WpfWindow("Window1").XamRibbon("xamRibbon").ToggleQATLocation True

Parameters

The following table explains the method’s parameter followed by code example.

Method parameter Description

bQATBelowRibbon

Boolean value. True indicates that the QAT will be placed below the ribbon groups and false indicates that it will be placed above the ribbon groups.

If you try using a script to place the QAT above or below the ribbon groups, while it is already present above or below, respectively, the method ignores the action.

Possible exceptions

None

Related Content

Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic provides information about the user actions of the xamRibbon control which you can test and the elements you can inspect.

This topic provides reference information about the xamRibbon control’s test object properties.