About xamFormulaEditor

This topic introduces you to the xamFormulaEditor™ control.

This document contains the following sections:

You need to first read the following topics:

The xamFormulaEditor control provides users with a full-fledged formula editing experience. It is related to and built upon the xamCalcualtionManager, which manages sources and targets of formulas as well as various pre-defined and custom functions. A formula is a complex expression using the sources, functions and/or build-in operators. A source serves as a variable in a formula expression. Sources and targets for formulas can be any public property of any object for item calculations. The results of calculations are applied to targets.

The xamFormulaEditor control has two main interfaces for editing formulas – the xamFormulaEditor and the FormulaEditorDialog. The following examples demonstrate how to use the control through both the xamFormulaEditor and the FormulaEditorDialog.

The table below briefly explains the main features of the xamFormulaEditor.

The xamFormulaEditor is an editor control that assists users in entering and editing formulas for a pre-defined target. The target of the xamFormulaEditor can be another control in the same page (e.g. a TextBox, TextBlock, ComboBox etc.) that is registered in a xamCalculationManager. The xamFormulaEditor can also be used to edit the formula for a field in a xamDataGrid control.

The xamFormulaEditor contains two main parts. The first is the formula editing area where users enter the formula expression and the second is the dialog button that, when clicked displays the FormulaEditorDialog. As the user types in the xamFormulaEditor, it displays auto-completion suggestions and contextual help about functions and operands. Furthermore if there is an error in the formula expression, the editor is highlighted in red and hovering over the error indicator displays a tooltip with the error description.

The FormulaEditorDialog is the second main interface of the xamFormulaEditor. When a user clicks the button in the xamFormulaEditor a FormulaEditorDialog containing the xamFormulaEditor’s formula is displayed. The FormulaEditorDialog can also be used as a standalone control.

The dialog has a main text editing area where a formula can be edited by the user. There are also buttons available to insert the most commonly used operators and two lists – one containing the available operands and one containing functions. The functions list is made up of pre-defined functions as well as custom functions you can register using the xamCaluculationManager control’s RegisterUserDefinedFunction method.

While the list can grow quite long, users can search the list by typing into the search text boxes. When users type in the text editing area, contextual help and auto-completion suggestions are displayed in the xamFormulaEditor control. In case of a syntax error, the editing area is highlighted in red and an error is displayed under the text box. Error messages contain the exact error and its place in the formula.

If the FormulaEditorDialog was called from the xamFormulaEditor control after pressing the OK button, the Formula is updated in the xamFormulaEditor, the Target’s value is recalculated and the FormulaEditorDialog is dismissed.

Following are some other topics you may find useful.