ControlsFactory Class

A factory that enables you to register custom controls.

Declaration

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

Remarks

Review the following help topic for information on how to add a custom control: 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.

isExpression boolean

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): Analytics.Elements.IElementMetadata & {
    parentType: string;
    info: any[];
    popularProperties: 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
IElementMetadata & {info: any[], parentType: string, popularProperties: 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.

setDisplayNameForExpression(propertyName, localizationId, displayName) Method

Specifies a property's display name in the End-User Report Designer Expressions tab.

Declaration

setDisplayNameForExpression(propertyName: string, localizationId: string, displayName: string): void

Parameters

Name Type Description
propertyName string

A string that specifies the property name.

localizationId string

A string that specifies the ASPxReportsStringId enumeration member.

displayName string

A string that specifies display text.

Remarks

To display a specific string, specify it in the displayName parameter value and set the localizationId parameter to null.

NOTE

The localizationId parameter has priority over the displayName parameter.

Examples

The following code snippet creates a new category for the Label control and adds the TextFormatString property with the "Text Format String" display name. The panel width is set to 350px to fit the display name:

<head>
    <style>
        .dxrd-right-panel.ui-resizable {
            width: 350px !important;
        }
    </style>
</head>
<script type="text/javascript">
    function CustomizeExpressions(s, e) {
        e.ControlsFactory.setExpressionBinding("XRLabel", "TextFormatString", ["BeforePrint"], "My category");
        e.ControlsFactory.setDisplayNameForExpression("TextFormatString", null, "Text Format String");
    }
</script>

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
    settings.ClientSideEvents.CustomizeToolbox = "CustomizeExpressions";
}).BindToUrl("TestReport").GetHtml()

To serialize the added property, you should also register it at application 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.

setExpressionBinding(controlType, propertyName, events) Method

Adds a new 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 the property to be added.

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.

group string

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

objectProperties string[]

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.

Examples

The following code snippet creates a new category for the Label control and adds the TextFormatString property with the "Text Format String" display name. The panel width is set to 350px to fit the display name:

<head>
    <style>
        .dxrd-right-panel.ui-resizable {
            width: 350px !important;
        }
    </style>
</head>
<script type="text/javascript">
    function CustomizeExpressions(s, e) {
        e.ControlsFactory.setExpressionBinding("XRLabel", "TextFormatString", ["BeforePrint"], "My category");
        e.ControlsFactory.setDisplayNameForExpression("TextFormatString", null, "Text Format String");
    }
</script>

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
    settings.ClientSideEvents.CustomizeToolbox = "CustomizeExpressions";
}).BindToUrl("TestReport").GetHtml()

To serialize the added property, you should also register it at application 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.