The requested page is not available for the requested platform. You are viewing the content for Default platform.
All docs
V19.1
19.2 (EAP/Beta)
19.1
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

ControlsFactory Class

A factory that enables you to register custom controls.

Declaration

class ControlsFactory extends Analytics.Utils.ControlsFactory implements Analytics.Utils.IDisposable

Remarks

For a step-by-step tutorial on how to add a custom control, see Register a Custom Control in the Report Designer Toolbox.

Inheritance

ControlsFactory
ControlsFactory

Methods

createPopularBindingInfo(options) Method

Creates a new object that stores information required to display element properties in the list of popular actions.

Declaration

createPopularBindingInfo(options: Metadata.ISerializationInfoWithBindings, isExpression?: boolean): Metadata.ISerializationInfoWithBindings

Parameters

Name Type Description
options ISerializationInfoWithBindings

An object that stores information required to serialize element properties.

Optional Parameters

Name Type Default Description
isExpression boolean null

true (the default value) to create an expression binding; false to create a legacy data binding.

Returns

Type Description
ISerializationInfoWithBindings

An object that specifies the resulting serialization info.

Remarks

In the CustomizeToolbox event handler, use the createPopularBindingInfo method to create serialization information for a custom control's properties.

Then, add the created information to the custom control's info collection and the corresponding binding names to the popularProperties collection as shown below.


function customizeToolbox(s, e) {
  // ...
  var controlsFactory = e.ControlsFactory;
  var expressionInfo = controlsFactory.createPopularBindingInfo({ bindingName: "BindableProperty", displayName: "Bindable Property", localizationId: "BindableProperty" }, true)
  var dataBindingInfo = controlsFactory.createPopularBindingInfo({ bindingName: "BindableProperty", displayName: "Bindable Property", localizationId: "BindableProperty" }, false)

  // Create an object containing info about a custom label toolbox item.
  var customLabelInfo = controlsFactory.inheritControl("XRLabel", {
    defaultVal: {
      "@ControlType": fullTypeName,
      "@SizeF": "100,23"
    },
    toolboxIndex: 1,
    info: [expressionInfo, dataBindingInfo],
    popularProperties: ["popularExpression", "popularDataBinding"],
  });
  // ...
}

hideExpressionBindings(type, propertyNames) Method

Hides the specified properties for the specified control from the Properties panel's Expressions tab.

Declaration

hideExpressionBindings(type: any, ...propertyNames: any[]): void

Parameters

Name Type Description
type any

A string that specifies the control type.

propertyNames any[]

An array of strings that specify property names to hide.

Remarks

Handle the CustomizeToolbox event and use the following code to hide the Label control's specific properties from the Expressions tab.

<script type="text/javascript">
    function customizeToolbox(s, e) {
        e.ControlsFactory.hideExpressionBindings("XRLabel", "Font", "ForeColor", "Text", "TextAlignment");
    }
</script>

<dx:ASPxReportDesigner ID="ASPxReportDesigner1" ClientInstanceName="reportDesigner" runat="server">
    <ClientSideEvents CustomizeToolbox="customizeToolbox" />
</dx:ASPxReportDesigner>

inheritControl(parentType, extendedOptions) Method

Inherits a new control from the specified parent control and extends it with the specified options.

Declaration

inheritControl(parentType: string, extendedOptions: Analytics.Elements.IElementMetadata): any

Parameters

Name Type Description
parentType string

A string that specifies the type of a control from which a new control should be inherited.

extendedOptions IElementMetadata

An object that specifies options for a new control.

Returns

Type Description
any

An object that specifies the resulting control and its options.

Remarks

The inheritControl method allows you to derive a new custom control from an existing one. Pass the parent control's type as the first method parameter and the required control options as the second method parameter. Note that the info and popularProperties options are concatenated with the parent control's corresponding options, while all other options replace the parent options.

The following code snippet demonstrates how to create a new custom control in the CustomizeToolbox event handler.


function customizeToolbox(s, e) {
  ...
  // Create an object containing info about a custom label toolbox item.
  var customLabelInfo = controlsFactory.inheritControl("XRLabel", {
    surfaceType: CustomLabelSurface,
    defaultVal: {
      "@ControlType": fullTypeName,
      "@SizeF": "100,23"
    },
    toolboxIndex: 1,
    info: [somePropertySerializationInfo, bindablePropertySerializationInfo],
    popularProperties: ["someProperty", "bindableProperty"],
  });
  ...
}

Use the registerControl method to register a custom control in the Toolbox.

See Register a Custom Control in the Report Designer Toolbox for a step-by-step tutorial on how to add a custom control.

registerControl(typeName, metadata) Method

Registers the specified control in the Toolbox of the Web Report Designer.

Declaration

registerControl(typeName: string, metadata: IReportControlMetadata): void

Parameters

Name Type Description
typeName string

A string that specifies the name of a custom control.

metadata IReportControlMetadata

An object that provides information about a toolbox item.

Remarks

For a step-by-step tutorial on how to add a custom control, see Register a Custom Control in the Report Designer Toolbox.

setExpressionBinding(controlType, propertyName, events) Method

Adds a new specified property for the specified control to the End-User Report Designer's Expressions tab.

Declaration

setExpressionBinding(controlType: string, propertyName: string, events: string[], group?: string, objectProperties?: string[]): void

Parameters

Name Type Description
controlType string

A string that specifies the control type for which to add the property.

propertyName string

A string that specifies the property name to add.

events string[]

An array of strings that specify events in which the property should be available.

Optional Parameters

Name Type Default Description
group string null

A string that specifies the category in which the property should be displayed.

objectProperties string[] null

An array of strings that specify the property's inner properties.

Remarks

Handle the CustomizeToolbox event and use the setExpressionBinding method to add new properties to the End-User Report Designer's Expressions tab.

The following code snippet demonstrates how to create a new category for the Label control and add the TextFormatString property:

<script type="text/javascript">
    function customizeToolbox(s, e) {
        e.ControlsFactory.setExpressionBinding("XRLabel", "TextFormatString", ["BeforePrint"], "My category"); 
    }
</script>

<dx:ASPxReportDesigner ID="ASPxReportDesigner1" ClientInstanceName="reportDesigner" runat="server">
    <ClientSideEvents CustomizeToolbox="customizeToolbox" />
</dx:ASPxReportDesigner>

To serialize the added property, you should also register it on the server side at the application's startup:

using DevExpress.XtraReports.Expressions;
using DevExpress.XtraReports.UI;

void Application_Start(object sender, EventArgs e) {
  // ...
    ExpressionBindingDescription description = new ExpressionBindingDescription(
        new string[] { "BeforePrint" }, 0, new string[0], "My category");

    ExpressionBindingDescriptor.SetPropertyDescription(typeof(XRLabel), "TextFormatString", description);
    // ...
}

The following image shows the result.